doc: create initial doc/cjdns.md for CJDNS how-to documentation by jonatack · Pull Request #24555 · bitcoin/bitcoin

jonatack · 2022-03-14T10:19:52Z

and update and improve doc/tor.md and doc/i2p.md.

Adapted in part from the CJDNS description in #23077 and feedback by Vasil Dimov and from the CJDNS documentation and feedback by Caleb James DeLisle.

Targets backport to v23.x.

Co-authored-by: Vasil Dimov [email protected]

jonatack · 2022-03-16T20:21:37Z

Pinging people who have installed CJDNS and run bitcoind with it per #23077 reviews and or/have a CJDNS node up: @dunxen @vasild @jamesob @cjdelisle

doc/cjdns.md

cjdelisle · 2022-03-16T22:14:17Z

ACK on the content of cjdns.md, other files I am not qualified.

jonatack · 2022-03-17T01:12:31Z

Updated with feedback from @cjdelisle (thanks!)

git diff 3fde801 a69ef4b

diff --git a/doc/cjdns.md b/doc/cjdns.md
index 5b4e112b90..482d861af6 100644
--- a/doc/cjdns.md
+++ b/doc/cjdns.md
@@ -16,7 +16,7 @@ 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 the individual node.
+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.
@@ -35,8 +35,13 @@ node"](https://github.com/cjdelisle/cjdns#3-connect-your-node-to-your-friends-no
 You need to be connected to the CJDNS network before it will work with your
 Bitcoin Core node.
 
-Typically, CJDNS might be launched with `./cjdroute < cjdroute.conf >
-cjdroute.log` and the network connection checked with `./tools/peerStats`.
+Typically, CJDNS might be launched with `sudo ./cjdroute < cjdroute.conf` and it
+sheds permissions after setting up the [TUN](https://en.wikipedia.org/wiki/TUN/TAP)
+device. 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 with `./tools/peerStats`.

cjdelisle · 2022-03-17T01:12:55Z

ACK without reservation on cjdns.md

dunxen · 2022-03-17T05:31:06Z

ACK a69ef4b

Looks good to me! And thanks for mentioning the "don't skip these steps" part. I think one of those was mostly the trouble people had because we skipped it 😅

jonatack · 2022-03-17T08:56:42Z

Looks good to me! And thanks for mentioning the "don't skip these steps" part. I think one of those was mostly the trouble people had because we skipped it 😅

Yes! I skipped those and so did a couple others 🙂

doc/cjdns.md

vasild

Thank you!

doc/cjdns.md

jonatack · 2022-03-21T17:00:44Z

Thanks for the excellent feedback @vasild; updated.

git diff a69ef4b 1e95550

diff --git a/doc/cjdns.md b/doc/cjdns.md
index 482d861af6..220a95e742 100644
--- a/doc/cjdns.md
+++ b/doc/cjdns.md
@@ -35,13 +35,14 @@ node"](https://github.com/cjdelisle/cjdns#3-connect-your-node-to-your-friends-no
 You need to be connected to the CJDNS network before it will work with your
 Bitcoin Core node.
 
-Typically, CJDNS might be launched with `sudo ./cjdroute < cjdroute.conf` and it
-sheds permissions after setting up the [TUN](https://en.wikipedia.org/wiki/TUN/TAP)
-device. 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.
+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 with `./tools/peerStats`.
+The network connection can be checked by running `./tools/peerStats` from the
+CJDNS directory.
 
 ## Run Bitcoin Core with CJDNS
 
@@ -52,10 +53,14 @@ configuration option makes CJDNS peers automatically reachable:
 
-With this option enabled, if your node connects to `fc00::/8` addresses, they
-will lead to the CJDNS network. Without the option and by default, they will
-lead to an IPv6 local network as defined in
-[RFC 4193](https://datatracker.ietf.org/doc/html/rfc4193).
+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
 
@@ -71,11 +76,7 @@ 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.
 
-Another consideration with `onlynet=cjdns` is that the initial blocks download
-phase when syncing up a new node can be 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 CJDNS hidden services (or
+In general, a node can be run with both an onion hidden 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.
 
@@ -88,5 +89,5 @@ There are several ways to see your CJDNS address in Bitcoin Core:
 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"`
+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 6b440f43a6..39f65c4e5f 100644
--- a/doc/i2p.md
+++ b/doc/i2p.md
@@ -93,7 +93,7 @@ There are several ways to see your I2P address in Bitcoin Core:
 To see which I2P peers your node is connected to, use `bitcoin-cli -netinfo 4`
 or the `getpeerinfo` RPC (e.g. `bitcoin-cli getpeerinfo`).
 
-To see which I2P addresses your node knows, use the `getnodeaddresses 0 "i2p"`
+To see which I2P addresses your node knows, use the `getnodeaddresses 0 i2p`
 RPC.
 
 ## Compatibility
diff --git a/doc/tor.md b/doc/tor.md
index b8876b9825..08d031d084 100644
--- a/doc/tor.md
+++ b/doc/tor.md
@@ -28,7 +28,7 @@ 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.
+addresses, use the `getnodeaddresses 7 onion` RPC.
 </p></details>

lsilva01

ACK 1e95550

nit: According to this comment, if the node is proxying IPv6 over Tor, CJDNS will not work.

As doc/tor.md suggests using ./bitcoind -proxy=127.0.0.1:9050 to run Tor and it will prevent CJDNS from working, maybe it would be interesting to add a setting that allows Tor + CJDNS to work together.

Adapted in part from the CJDNS description in bitcoin#23077 by Vasil Dimov and from CJDNS documentation and feedback by Caleb James DeLisle. Co-authored-by: Vasil Dimov <[email protected]>

and improve local addresses section

jonatack · 2022-03-22T11:57:50Z

Thanks for the review and feedback @lsilva01. Without going into specific configuration suggestions, I've re-pushed with the following update. What do you think? Do we need to provide specific Tor + CJDNS configurations?

diff

--- a/doc/cjdns.md
+++ b/doc/cjdns.md
@@ -76,9 +76,11 @@ 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 hidden 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.
+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

vasild

ACK f44efc3

lsilva01

I think it's good. The user has a reference to the Tor documentation for configuring both networks.

ACK f44efc3

stickies-v · 2022-03-24T18:14:18Z

Post-merge ACK f44efc3 . This is my first time hearing about CJDNS and having this documentation is very helpful.
I wanted to suggest if it would be helpful to add some hints as per e.g. this IRC discussion on using the public nodes, but maybe that is too specific for this documentation.

jonatack · 2022-03-24T18:27:12Z

I wanted to suggest if it would be helpful to add some hints as per e.g. this IRC discussion on using the public nodes

Thanks! For now, I didn't want to replicate or enhance the CJDNS installation docs (i.e. https://github.com/cjdelisle/cjdns#2-find-a-friend), but this can evolve based on feedback.

maflcko · 2022-03-24T19:00:37Z

Shouldn't docs be linked from the root doc.md?

jonatack · 2022-03-24T19:16:36Z

Shouldn't docs be linked from the root doc.md?

I overlooked that. Done in #24663 along with a link in -cjdnsreachable.

daae288 doc, init: add links to doc/cjdns.md (Jon Atack) Pull request description: Follow-up to bitcoin#24555. ACKs for top commit: jessebarton: ACK [daae288](bitcoin@daae288) Tree-SHA512: eb8f4324f182f7917ddafa9b88ad753fe8f890c1c883c1342768ed9eac998c422ecd9e998fc977e72e26bc87f6aed295940b522187190481889255c8b2e05311

Adapted in part from the CJDNS description in bitcoin#23077 by Vasil Dimov and from CJDNS documentation and feedback by Caleb James DeLisle. Co-authored-by: Vasil Dimov <[email protected]> Github-Pull: bitcoin#24555 Rebased-From: ed15848

and improve local addresses section Github-Pull: bitcoin#24555 Rebased-From: 3bf6f0c

Github-Pull: bitcoin#24555 Rebased-From: f44efc3

174af33 util: Add inotify_rm_watch to syscall sandbox (AllowFileSystem) (Hennadii Stepanov) ded10fe build: Fix Boost.Process test for Boost 1.78 (Hennadii Stepanov) 26c2f23 build: Fix Boost.Process detection on macOS arm64 (Hennadii Stepanov) 85f85c7 util: add linkat to syscall sandbox (AllowFileSystem) (fanquake) eaa0419 contrib: fix signet miner (sighash mismatch) (Sebastian Falbesoner) 235b042 rpc: Exclude descriptor when address is excluded (MarcoFalke) b05a59b ci: Temporarily use clang-13 to work around clang-14 TSan bug (MarcoFalke) 65b9667 doc, init: add links to doc/cjdns.md (Jon Atack) 7a553d4 doc: update i2p.md with cjdns, improve local addresses section (Jon Atack) 4148396 doc: update tor.md with cjdns and getnodeaddresses, fix tor grep, (Jon Atack) 4690e8a doc: create initial doc/cjdns.md for cjdns how-to documentation (Jon Atack) 5d24f61 Clarify in -maxtimeadjustment that only outbound peers influence time data (Jon Atack) b1646f1 test: set segwit height back to 0 on regtest (Martin Zumsande) ef6a37b rpc: rename getdeploymentinfo status-next to status_next (Jon Atack) 2a6fcf9 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 174af33, I think we should merge this and move forward with rc3.. hebasto: ACK 174af33 Tree-SHA512: 5a493e1652b780b527767d6ca9e67012abd2fa5573496e85e0d8aa4bed3eb332bfcd72610b8dfb954ff274d42450623233c96c479de2085b9c8344ba5abf1935

…o docum…

fanquake added the Docs label Mar 14, 2022

jonatack force-pushed the cjdns-doc branch from 9a6b799 to 3fde801 Compare March 14, 2022 10:25

jonatack mentioned this pull request Mar 14, 2022

23.x backports #24512

Merged

cjdelisle reviewed Mar 16, 2022

View reviewed changes

doc/cjdns.md Outdated Show resolved Hide resolved

cjdelisle reviewed Mar 16, 2022

View reviewed changes

doc/cjdns.md Outdated Show resolved Hide resolved

jonatack force-pushed the cjdns-doc branch from 3fde801 to a69ef4b Compare March 17, 2022 01:08

jonatack commented Mar 18, 2022

View reviewed changes

doc/cjdns.md Outdated Show resolved Hide resolved

vasild reviewed Mar 18, 2022

View reviewed changes

jonatack force-pushed the cjdns-doc branch from a69ef4b to 1e95550 Compare March 21, 2022 16:55

lsilva01 approved these changes Mar 21, 2022

View reviewed changes

jonatack and others added 3 commits March 22, 2022 12:54

doc: create initial doc/cjdns.md for cjdns how-to documentation

ed15848

Adapted in part from the CJDNS description in bitcoin#23077 by Vasil Dimov and from CJDNS documentation and feedback by Caleb James DeLisle. Co-authored-by: Vasil Dimov <[email protected]>

doc: update tor.md with cjdns and getnodeaddresses, fix tor grep,

3bf6f0c

and improve local addresses section

doc: update i2p.md with cjdns, improve local addresses section

f44efc3

jonatack force-pushed the cjdns-doc branch from 1e95550 to f44efc3 Compare March 22, 2022 11:55

vasild approved these changes Mar 22, 2022

View reviewed changes

lsilva01 approved these changes Mar 23, 2022

View reviewed changes

laanwj merged commit 65e9ca2 into bitcoin:master Mar 24, 2022

jonatack deleted the cjdns-doc branch March 24, 2022 17:45

jonatack mentioned this pull request Mar 24, 2022

doc, init: add links to doc/cjdns.md #24663

Merged

jonatack added a commit to jonatack/bitcoin that referenced this pull request Mar 31, 2022

doc: update tor.md with cjdns and getnodeaddresses, fix tor grep,

4148396

and improve local addresses section Github-Pull: bitcoin#24555 Rebased-From: 3bf6f0c

jonatack added a commit to jonatack/bitcoin that referenced this pull request Mar 31, 2022

doc: update i2p.md with cjdns, improve local addresses section

7a553d4

Github-Pull: bitcoin#24555 Rebased-From: f44efc3

sidhujag pushed a commit to syscoin/syscoin that referenced this pull request Apr 2, 2022

Merge bitcoin#24555: doc: create initial doc/cjdns.md for CJDNS how-t…

58ad38d

…o docum…

bitcoin locked and limited conversation to collaborators Mar 24, 2023

Conversation

jonatack commented Mar 14, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jonatack commented Mar 16, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cjdelisle commented Mar 16, 2022

Uh oh!

jonatack commented Mar 17, 2022

Uh oh!

cjdelisle commented Mar 17, 2022

Uh oh!

dunxen commented Mar 17, 2022

Uh oh!

jonatack commented Mar 17, 2022

Uh oh!

Uh oh!

vasild left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jonatack commented Mar 21, 2022

Uh oh!

lsilva01 left a comment

Choose a reason for hiding this comment

Uh oh!

jonatack commented Mar 22, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vasild left a comment

Choose a reason for hiding this comment

Uh oh!

lsilva01 left a comment

Choose a reason for hiding this comment

Uh oh!

stickies-v commented Mar 24, 2022

Uh oh!

jonatack commented Mar 24, 2022

Uh oh!

maflcko commented Mar 24, 2022

Uh oh!

jonatack commented Mar 24, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

jonatack commented Mar 14, 2022 •

edited

Loading

jonatack commented Mar 16, 2022 •

edited

Loading

jonatack commented Mar 22, 2022 •

edited

Loading