aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorfanquake <fanquake@gmail.com>2022-03-31 11:54:51 +0100
committerfanquake <fanquake@gmail.com>2022-03-31 12:19:22 +0100
commitc243e0835166e7821bc5552db4bedcc3c99e3ccd (patch)
tree7efcc2f5addc2d6a82470c633b2417a9093ac097 /doc
parent7d03cf632d16659166ef7f0d2e3b37ac1f05c0b5 (diff)
parent174af33d5d78cfe341b688f5393d9acc8c4aaf6b (diff)
downloadbitcoin-c243e0835166e7821bc5552db4bedcc3c99e3ccd.tar.xz
Merge bitcoin/bitcoin#24512: 23.x backports
174af33d5d78cfe341b688f5393d9acc8c4aaf6b util: Add inotify_rm_watch to syscall sandbox (AllowFileSystem) (Hennadii Stepanov) ded10fe3eae2ad8058d0cc8f1cee1ad1d34bb507 build: Fix Boost.Process test for Boost 1.78 (Hennadii Stepanov) 26c2f23f36228e334d17c43a0cb61f76cc545c3d build: Fix Boost.Process detection on macOS arm64 (Hennadii Stepanov) 85f85c7e5fce1ac1682bf62808d37f3da23614f7 util: add linkat to syscall sandbox (AllowFileSystem) (fanquake) eaa04194b979635a3d8590a8409084159d1e6576 contrib: fix signet miner (sighash mismatch) (Sebastian Falbesoner) 235b04259414fd708c31bbe0cab28ba09bcd25f1 rpc: Exclude descriptor when address is excluded (MarcoFalke) b05a59b69fd51dd6a7ebc79dc0d11dc2af47a006 ci: Temporarily use clang-13 to work around clang-14 TSan bug (MarcoFalke) 65b966743c62914df7fd9b7f028f1f5bb3683eda doc, init: add links to doc/cjdns.md (Jon Atack) 7a553d4e657d52e2d15b53a4b54b4ca5ecde2f04 doc: update i2p.md with cjdns, improve local addresses section (Jon Atack) 4148396229db008419f895161b6c7310a44d563b doc: update tor.md with cjdns and getnodeaddresses, fix tor grep, (Jon Atack) 4690e8af1300daba276c7b426030d4c69d27d73b doc: create initial doc/cjdns.md for cjdns how-to documentation (Jon Atack) 5d24f612d1f7f5f1258216e3b7c569399c657abb Clarify in -maxtimeadjustment that only outbound peers influence time data (Jon Atack) b1646f1bb573031ca587081276d9fe7c4873b8c9 test: set segwit height back to 0 on regtest (Martin Zumsande) ef6a37b7c4b942f2db95809a299700e410b94460 rpc: rename getdeploymentinfo status-next to status_next (Jon Atack) 2a6fcf9c136f7a0c6ba12010ff1769acd07804cf init, doc: improve -onlynet help and tor/i2p documentation (Jon Atack) Pull request description: Backport the following to 23.x: - #24468 - #24528 - #24527 - #24609 - #24555 - #24663 - #24572 - #24636 - #24553 - #24659 - #24521 - #24523 - #24690 - #24710 Possibly also: - #24579 - #24691 ACKs for top commit: laanwj: List-of-commits ACK 174af33d5d78cfe341b688f5393d9acc8c4aaf6b, I think we should merge this and move forward with rc3.. hebasto: ACK 174af33d5d78cfe341b688f5393d9acc8c4aaf6b Tree-SHA512: 5a493e1652b780b527767d6ca9e67012abd2fa5573496e85e0d8aa4bed3eb332bfcd72610b8dfb954ff274d42450623233c96c479de2085b9c8344ba5abf1935
Diffstat (limited to 'doc')
-rw-r--r--doc/README.md1
-rw-r--r--doc/cjdns.md95
-rw-r--r--doc/i2p.md16
-rw-r--r--doc/p2p-bad-ports.md6
-rw-r--r--doc/tor.md17
5 files changed, 117 insertions, 18 deletions
diff --git a/doc/README.md b/doc/README.md
index c200ac3753..33f71f4807 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -73,6 +73,7 @@ The Bitcoin repo's [root README](/README.md) contains relevant information on th
- [Assets Attribution](assets-attribution.md)
- [Assumeutxo design](assumeutxo.md)
- [bitcoin.conf Configuration File](bitcoin-conf.md)
+- [CJDNS Support](cjdns.md)
- [Files](files.md)
- [Fuzz-testing](fuzzing.md)
- [I2P Support](i2p.md)
diff --git a/doc/cjdns.md b/doc/cjdns.md
new file mode 100644
index 0000000000..5b2bcaf874
--- /dev/null
+++ b/doc/cjdns.md
@@ -0,0 +1,95 @@
+# CJDNS support in Bitcoin Core
+
+It is possible to run Bitcoin Core over CJDNS, an encrypted IPv6 network that
+uses public-key cryptography for address allocation and a distributed hash table
+for routing.
+
+## What is CJDNS?
+
+CJDNS is like a distributed, shared VPN with multiple entry points where every
+participant can reach any other participant. All participants use addresses from
+the `fc00::/8` network (reserved IPv6 range). Installation and configuration is
+done outside of Bitcoin Core, similarly to a VPN (either in the host/OS or on
+the network router).
+
+Compared to IPv4/IPv6, CJDNS provides end-to-end encryption and protects nodes
+from traffic analysis and filtering.
+
+Used with Tor and I2P, CJDNS is a complementary option that can enhance network
+redundancy and robustness for both the Bitcoin network and individual nodes.
+
+Each network has different characteristics. For instance, Tor is widely used but
+somewhat centralized. I2P connections have a source address and I2P is slow.
+CJDNS is fast but does not hide the sender and the recipient from intermediate
+routers.
+
+## Installing CJDNS and connecting to the network
+
+To install and set up CJDNS, follow the instructions at
+https://github.com/cjdelisle/cjdns#cjdns.
+
+Don't skip steps
+["2. Find a friend"](https://github.com/cjdelisle/cjdns#2-find-a-friend) and
+["3. Connect your node to your friend's
+node"](https://github.com/cjdelisle/cjdns#3-connect-your-node-to-your-friends-node).
+You need to be connected to the CJDNS network before it will work with your
+Bitcoin Core node.
+
+Typically, CJDNS might be launched from its directory with
+`sudo ./cjdroute < cjdroute.conf` and it sheds permissions after setting up the
+[TUN](https://en.wikipedia.org/wiki/TUN/TAP) interface. You may also [launch it as an
+unprivileged user](https://github.com/cjdelisle/cjdns/blob/master/doc/non-root-user.md)
+with some additional setup.
+
+The network connection can be checked by running `./tools/peerStats` from the
+CJDNS directory.
+
+## Run Bitcoin Core with CJDNS
+
+Once you are connected to the CJDNS network, the following Bitcoin Core
+configuration option makes CJDNS peers automatically reachable:
+
+```
+-cjdnsreachable
+```
+
+When enabled, this option tells Bitcoin Core that it is running in an
+environment where a connection to an `fc00::/8` address will be to the CJDNS
+network instead of to an [RFC4193](https://datatracker.ietf.org/doc/html/rfc4193)
+IPv6 local network. This helps Bitcoin Core perform better address management:
+ - Your node can consider incoming `fc00::/8` connections to be from the CJDNS
+ network rather than from an IPv6 private one.
+ - If one of your node's local addresses is `fc00::/8`, then it can choose to
+ gossip that address to peers.
+
+## Additional configuration options related to CJDNS
+
+```
+-onlynet=cjdns
+```
+
+Make automatic outbound connections only to CJDNS addresses. Inbound and manual
+connections are not affected by this option. It can be specified multiple times
+to allow multiple networks, e.g. onlynet=cjdns, onlynet=i2p, onlynet=onion.
+
+CJDNS support was added to Bitcoin Core in version 23.0 and there may be fewer
+CJDNS peers than Tor or IP ones. You can use `bitcoin-cli -addrinfo` to see the
+number of CJDNS addresses known to your node.
+
+In general, a node can be run with both an onion service and CJDNS (or any/all
+of IPv4/IPv6/onion/I2P/CJDNS), which can provide a potential fallback if one of
+the networks has issues. There are a number of ways to configure this; see
+[doc/tor.md](https://github.com/bitcoin/bitcoin/blob/master/doc/tor.md) for
+details.
+
+## CJDNS-related information in Bitcoin Core
+
+There are several ways to see your CJDNS address in Bitcoin Core:
+- in the "Local addresses" output of CLI `-netinfo`
+- in the "localaddresses" output of RPC `getnetworkinfo`
+
+To see which CJDNS peers your node is connected to, use `bitcoin-cli -netinfo 4`
+or the `getpeerinfo` RPC (i.e. `bitcoin-cli getpeerinfo`).
+
+To see which CJDNS addresses your node knows, use the `getnodeaddresses 0 cjdns`
+RPC.
diff --git a/doc/i2p.md b/doc/i2p.md
index ee650f3999..39f65c4e5f 100644
--- a/doc/i2p.md
+++ b/doc/i2p.md
@@ -65,9 +65,9 @@ logging` for more information.
-onlynet=i2p
```
-Make outgoing connections only to I2P addresses. Incoming connections are not
-affected by this option. It can be specified multiple times to allow multiple
-network types, e.g. onlynet=onion, onlynet=i2p.
+Make automatic outbound connections only to I2P addresses. Inbound and manual
+connections are not affected by this option. It can be specified multiple times
+to allow multiple networks, e.g. onlynet=onion, onlynet=i2p.
I2P support was added to Bitcoin Core in version 22.0 and there may be fewer I2P
peers than Tor or IP ones. Therefore, using I2P alone without other networks may
@@ -80,15 +80,15 @@ phase when syncing up a new node can be very slow. This phase can be sped up by
using other networks, for instance `onlynet=onion`, at the same time.
In general, a node can be run with both onion and I2P hidden services (or
-any/all of IPv4/IPv6/onion/I2P), which can provide a potential fallback if one
-of the networks has issues.
+any/all of IPv4/IPv6/onion/I2P/CJDNS), which can provide a potential fallback if
+one of the networks has issues.
## I2P-related information in Bitcoin Core
There are several ways to see your I2P address in Bitcoin Core:
-- in the debug log (grep for `AddLocal`, the I2P address ends in `.b32.i2p`)
-- in the output of the `getnetworkinfo` RPC in the "localaddresses" section
-- in the output of `bitcoin-cli -netinfo` peer connections dashboard
+- in the "Local addresses" output of CLI `-netinfo`
+- in the "localaddresses" output of RPC `getnetworkinfo`
+- in the debug log (grep for `AddLocal`; the I2P address ends in `.b32.i2p`)
To see which I2P peers your node is connected to, use `bitcoin-cli -netinfo 4`
or the `getpeerinfo` RPC (e.g. `bitcoin-cli getpeerinfo`).
diff --git a/doc/p2p-bad-ports.md b/doc/p2p-bad-ports.md
index 0dd7d36cf4..4f717f97a2 100644
--- a/doc/p2p-bad-ports.md
+++ b/doc/p2p-bad-ports.md
@@ -1,6 +1,6 @@
-When Bitcoin Core automatically opens outgoing P2P connections it chooses
+When Bitcoin Core automatically opens outgoing P2P connections, it chooses
a peer (address and port) from its list of potential peers. This list is
-populated with unchecked data, gossiped over the P2P network by other peers.
+populated with unchecked data gossiped over the P2P network by other peers.
A malicious actor may gossip an address:port where no Bitcoin node is listening,
or one where a service is listening that is not related to the Bitcoin network.
@@ -17,7 +17,7 @@ authentication are unlikely to be considered a malicious action,
e.g. port 80 (http).
Below is a list of "bad" ports which Bitcoin Core avoids when choosing a peer to
-connect to. If a node is listening on such a port, it will likely receive less
+connect to. If a node is listening on such a port, it will likely receive fewer
incoming connections.
1: tcpmux
diff --git a/doc/tor.md b/doc/tor.md
index 086e6747bf..08d031d084 100644
--- a/doc/tor.md
+++ b/doc/tor.md
@@ -16,9 +16,9 @@ configure Tor.
## How to see information about your Tor configuration via Bitcoin Core
There are several ways to see your local onion address in Bitcoin Core:
-- in the debug log (grep for "tor:" or "AddLocal")
-- in the output of RPC `getnetworkinfo` in the "localaddresses" section
-- in the output of the CLI `-netinfo` peer connections dashboard
+- in the "Local addresses" output of CLI `-netinfo`
+- in the "localaddresses" output of RPC `getnetworkinfo`
+- in the debug log (grep for "AddLocal"; the Tor address ends in `.onion`)
You may set the `-debug=tor` config logging option to have additional
information in the debug log about your Tor configuration.
@@ -27,6 +27,9 @@ CLI `-addrinfo` returns the number of addresses known to your node per
network. This can be useful to see how many onion peers your node knows,
e.g. for `-onlynet=onion`.
+To fetch a number of onion addresses that your node knows, for example seven
+addresses, use the `getnodeaddresses 7 onion` RPC.
+
## 1. Run Bitcoin Core behind a Tor proxy
The first step is running Bitcoin Core behind a Tor proxy. This will already anonymize all
@@ -55,10 +58,10 @@ outgoing connections, but more is possible.
-seednode=X SOCKS5. In Tor mode, such addresses can also be exchanged with
other P2P nodes.
- -onlynet=onion Make outgoing connections only to .onion addresses. Incoming
- connections are not affected by this option. This option can be
- specified multiple times to allow multiple network types, e.g.
- onlynet=onion, onlynet=i2p.
+ -onlynet=onion Make automatic outbound connections only to .onion addresses.
+ Inbound and manual connections are not affected by this option.
+ It can be specified multiple times to allow multiple networks,
+ e.g. onlynet=onion, onlynet=i2p, onlynet=cjdns.
In a typical situation, this suffices to run behind a Tor proxy: