Skip to content

Commit c736ebf

Browse files
kwvgkwvg
committed
merge bitcoin#24555: create initial doc/cjdns.md for CJDNS how-to documentation
1 parent 554bd24 commit c736ebf

File tree

3 files changed

+107
-9
lines changed

3 files changed

+107
-9
lines changed

‎doc/cjdns.md

+95
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# CJDNS support in Dash Core
2+
3+
It is possible to run Dash Core over CJDNS, an encrypted IPv6 network that
4+
uses public-key cryptography for address allocation and a distributed hash table
5+
for routing.
6+
7+
## What is CJDNS?
8+
9+
CJDNS is like a distributed, shared VPN with multiple entry points where every
10+
participant can reach any other participant. All participants use addresses from
11+
the `fc00::/8` network (reserved IPv6 range). Installation and configuration is
12+
done outside of Dash Core, similarly to a VPN (either in the host/OS or on
13+
the network router).
14+
15+
Compared to IPv4/IPv6, CJDNS provides end-to-end encryption and protects nodes
16+
from traffic analysis and filtering.
17+
18+
Used with Tor and I2P, CJDNS is a complementary option that can enhance network
19+
redundancy and robustness for both the Dash network and individual nodes.
20+
21+
Each network has different characteristics. For instance, Tor is widely used but
22+
somewhat centralized. I2P connections have a source address and I2P is slow.
23+
CJDNS is fast but does not hide the sender and the recipient from intermediate
24+
routers.
25+
26+
## Installing CJDNS and connecting to the network
27+
28+
To install and set up CJDNS, follow the instructions at
29+
https://github.com/cjdelisle/cjdns#cjdns.
30+
31+
Don't skip steps
32+
["2. Find a friend"](https://github.com/cjdelisle/cjdns#2-find-a-friend) and
33+
["3. Connect your node to your friend's
34+
node"](https://github.com/cjdelisle/cjdns#3-connect-your-node-to-your-friends-node).
35+
You need to be connected to the CJDNS network before it will work with your
36+
Dash Core node.
37+
38+
Typically, CJDNS might be launched from its directory with
39+
`sudo ./cjdroute < cjdroute.conf` and it sheds permissions after setting up the
40+
[TUN](https://en.wikipedia.org/wiki/TUN/TAP) interface. You may also [launch it as an
41+
unprivileged user](https://github.com/cjdelisle/cjdns/blob/master/doc/non-root-user.md)
42+
with some additional setup.
43+
44+
The network connection can be checked by running `./tools/peerStats` from the
45+
CJDNS directory.
46+
47+
## Run Dash Core with CJDNS
48+
49+
Once you are connected to the CJDNS network, the following Dash Core
50+
configuration option makes CJDNS peers automatically reachable:
51+
52+
```
53+
-cjdnsreachable
54+
```
55+
56+
When enabled, this option tells Dash Core that it is running in an
57+
environment where a connection to an `fc00::/8` address will be to the CJDNS
58+
network instead of to an [RFC4193](https://datatracker.ietf.org/doc/html/rfc4193)
59+
IPv6 local network. This helps Dash Core perform better address management:
60+
- Your node can consider incoming `fc00::/8` connections to be from the CJDNS
61+
network rather than from an IPv6 private one.
62+
- If one of your node's local addresses is `fc00::/8`, then it can choose to
63+
gossip that address to peers.
64+
65+
## Additional configuration options related to CJDNS
66+
67+
```
68+
-onlynet=cjdns
69+
```
70+
71+
Make automatic outbound connections only to CJDNS addresses. Inbound and manual
72+
connections are not affected by this option. It can be specified multiple times
73+
to allow multiple networks, e.g. onlynet=cjdns, onlynet=i2p, onlynet=onion.
74+
75+
CJDNS support was added to Dash Core in version 21.0 and there may be fewer
76+
CJDNS peers than Tor or IP ones. You can use `dash-cli -addrinfo` to see the
77+
number of CJDNS addresses known to your node.
78+
79+
In general, a node can be run with both an onion service and CJDNS (or any/all
80+
of IPv4/IPv6/onion/I2P/CJDNS), which can provide a potential fallback if one of
81+
the networks has issues. There are a number of ways to configure this; see
82+
[doc/tor.md](https://github.com/dashpay/dash/blob/master/doc/tor.md) for
83+
details.
84+
85+
## CJDNS-related information in Dash Core
86+
87+
There are several ways to see your CJDNS address in Dash Core:
88+
- in the "Local addresses" output of CLI `-netinfo`
89+
- in the "localaddresses" output of RPC `getnetworkinfo`
90+
91+
To see which CJDNS peers your node is connected to, use `dash-cli -netinfo 4`
92+
or the `getpeerinfo` RPC (i.e. `dash-cli getpeerinfo`).
93+
94+
To see which CJDNS addresses your node knows, use the `getnodeaddresses 0 cjdns`
95+
RPC.

‎doc/i2p.md

+5-5
Original file line numberDiff line numberDiff line change
@@ -73,8 +73,8 @@ phase when syncing up a new node can be very slow. This phase can be sped up by
7373
using other networks, for instance `onlynet=onion`, at the same time.
7474

7575
In general, a node can be run with both onion and I2P hidden services (or
76-
any/all of IPv4/IPv6/onion/I2P), which can provide a potential fallback if one
77-
of the networks has issues.
76+
any/all of IPv4/IPv6/onion/I2P/CJDNS), which can provide a potential fallback if
77+
one of the networks has issues.
7878

7979
## Persistent vs transient I2P addresses
8080

@@ -102,9 +102,9 @@ listening should only be turned off if really needed.
102102

103103
There are several ways to see your I2P address in Dash Core if accepting
104104
incoming I2P connections (`-i2pacceptincoming`):
105-
- in the debug log (grep for `AddLocal`, the I2P address ends in `.b32.i2p`)
106-
- in the output of the `getnetworkinfo` RPC in the "localaddresses" section
107-
- in the output of `dash-cli -netinfo` peer connections dashboard
105+
- in the "Local addresses" output of CLI `-netinfo`
106+
- in the "localaddresses" output of RPC `getnetworkinfo`
107+
- in the debug log (grep for `AddLocal`; the I2P address ends in `.b32.i2p`)
108108

109109
To see which I2P peers your node is connected to, use `dash-cli -netinfo 4`
110110
or the `getpeerinfo` RPC (e.g. `dash-cli getpeerinfo`).

‎doc/tor.md

+7-4
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,9 @@ for how to properly configure Tor.
1111
## How to see information about your Tor configuration via Dash Core
1212

1313
There are several ways to see your local onion address in Dash Core:
14-
- in the debug log (grep for "tor:" or "AddLocal")
15-
- in the output of RPC `getnetworkinfo` in the "localaddresses" section
16-
- in the output of the CLI `-netinfo` peer connections dashboard
14+
- in the "Local addresses" output of CLI `-netinfo`
15+
- in the "localaddresses" output of RPC `getnetworkinfo`
16+
- in the debug log (grep for "AddLocal"; the Tor address ends in `.onion`)
1717

1818
You may set the `-debug=tor` config logging option to have additional
1919
information in the debug log about your Tor configuration.
@@ -22,6 +22,9 @@ CLI `-addrinfo` returns the number of addresses known to your node per
2222
network. This can be useful to see how many onion peers your node knows,
2323
e.g. for `-onlynet=onion`.
2424

25+
To fetch a number of onion addresses that your node knows, for example seven
26+
addresses, use the `getnodeaddresses 7 onion` RPC.
27+
2528
## 1. Run Dash Core behind a Tor proxy
2629

2730
The first step is running Dash Core behind a Tor proxy. This will already anonymize all
@@ -51,7 +54,7 @@ outgoing connections, but more is possible.
5154
-onlynet=onion Make automatic outbound connections only to .onion addresses.
5255
Inbound and manual connections are not affected by this option.
5356
It can be specified multiple times to allow multiple networks,
54-
e.g. onlynet=onion, onlynet=i2p.
57+
e.g. onlynet=onion, onlynet=i2p, onlynet=cjdns.
5558

5659
An example how to start the client if the Tor proxy is running on local host on
5760
port 9050 and only allows .onion nodes to connect:

0 commit comments

Comments
 (0)