diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/JSON-RPC-interface.md | 11 | ||||
| -rw-r--r-- | doc/REST-interface.md | 12 | ||||
| -rw-r--r-- | doc/developer-notes.md | 27 | ||||
| -rw-r--r-- | doc/release-notes.md | 5 | ||||
| -rw-r--r-- | doc/release-process.md | 4 | ||||
| -rw-r--r-- | doc/tor.md | 27 |
6 files changed, 65 insertions, 21 deletions
diff --git a/doc/JSON-RPC-interface.md b/doc/JSON-RPC-interface.md index 40d8e330e2..c66e79af71 100644 --- a/doc/JSON-RPC-interface.md +++ b/doc/JSON-RPC-interface.md @@ -127,3 +127,14 @@ However, the wallet may not be up-to-date with the current state of the mempool or the state of the mempool by an RPC that returned before this RPC. For example, a wallet transaction that was BIP-125-replaced in the mempool prior to this RPC may not yet be reflected as such in this RPC response. + +## Limitations + +There is a known issue in the JSON-RPC interface that can cause a node to crash if +too many http connections are being opened at the same time because the system runs +out of available file descriptors. To prevent this from happening you might +want to increase the number of maximum allowed file descriptors in your system +and try to prevent opening too many connections to your JSON-RPC interface at the +same time if this is under your control. It is hard to give general advice +since this depends on your system but if you make several hundred requests at +once you are definitely at risk of encountering this issue. diff --git a/doc/REST-interface.md b/doc/REST-interface.md index 842a3964df..3b127703b7 100644 --- a/doc/REST-interface.md +++ b/doc/REST-interface.md @@ -12,6 +12,18 @@ REST Interface consistency guarantees The [same guarantees as for the RPC Interface](/doc/JSON-RPC-interface.md#rpc-consistency-guarantees) apply. +Limitations +----------- + +There is a known issue in the REST interface that can cause a node to crash if +too many http connections are being opened at the same time because the system runs +out of available file descriptors. To prevent this from happening you might +want to increase the number of maximum allowed file descriptors in your system +and try to prevent opening too many connections to your rest interface at the +same time if this is under your control. It is hard to give general advice +since this depends on your system but if you make several hundred requests at +once you are definitely at risk of encountering this issue. + Supported API ------------- diff --git a/doc/developer-notes.md b/doc/developer-notes.md index 9cb416bb30..596f65cf10 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -14,7 +14,7 @@ Developer Notes - [Compiling for debugging](#compiling-for-debugging) - [Compiling for gprof profiling](#compiling-for-gprof-profiling) - [`debug.log`](#debuglog) - - [Testnet and Regtest modes](#testnet-and-regtest-modes) + - [Signet, testnet, and regtest modes](#signet-testnet-and-regtest-modes) - [DEBUG_LOCKORDER](#debug_lockorder) - [Valgrind suppressions file](#valgrind-suppressions-file) - [Compiling for test coverage](#compiling-for-test-coverage) @@ -135,7 +135,7 @@ Refer to [/test/functional/README.md#style-guidelines](/test/functional/README.m Coding Style (Doxygen-compatible comments) ------------------------------------------ -Bitcoin Core uses [Doxygen](http://www.doxygen.nl/) to generate its official documentation. +Bitcoin Core uses [Doxygen](https://www.doxygen.nl/) to generate its official documentation. Use Doxygen-compatible comment blocks for functions, methods, and fields. @@ -156,7 +156,7 @@ For example, to describe a function use: bool function(int arg1, const char *arg2, std::string& arg3) ``` -A complete list of `@xxx` commands can be found at http://www.doxygen.nl/manual/commands.html. +A complete list of `@xxx` commands can be found at https://www.doxygen.nl/manual/commands.html. As Doxygen recognizes the comments by the delimiters (`/**` and `*/` in this case), you don't *need* to provide any commands for a comment to be valid; just a description text is fine. @@ -203,7 +203,7 @@ Also not picked up by Doxygen: */ ``` -A full list of comment syntaxes picked up by Doxygen can be found at http://www.doxygen.nl/manual/docblocks.html, +A full list of comment syntaxes picked up by Doxygen can be found at https://www.doxygen.nl/manual/docblocks.html, but the above styles are favored. Recommendations: @@ -216,7 +216,7 @@ Recommendations: - Backticks aren't required when referring to functions Doxygen already knows about; it will build hyperlinks for these automatically. See - http://www.doxygen.nl/manual/autolink.html for complete info. + https://www.doxygen.nl/manual/autolink.html for complete info. - Avoid linking to external documentation; links can break. @@ -259,14 +259,15 @@ on all categories (and give you a very large `debug.log` file). The Qt code routes `qDebug()` output to `debug.log` under category "qt": run with `-debug=qt` to see it. -### Testnet and Regtest modes +### Signet, testnet, and regtest modes -Run with the `-testnet` option to run with "play bitcoins" on the test network, if you -are testing multi-machine code that needs to operate across the internet. +If you are testing multi-machine code that needs to operate across the internet, +you can run with either the `-signet` or the `-testnet` config option to test +with "play bitcoins" on a test network. -If you are testing something that can run on one machine, run with the `-regtest` option. -In regression test mode, blocks can be created on-demand; see [test/functional/](/test/functional) for tests -that run in `-regtest` mode. +If you are testing something that can run on one machine, run with the +`-regtest` option. In regression test mode, blocks can be created on demand; +see [test/functional/](/test/functional) for tests that run in `-regtest` mode. ### DEBUG_LOCKORDER @@ -543,7 +544,7 @@ General Bitcoin Core - *Rationale*: RPC allows for better automatic testing. The test suite for the GUI is very limited. -- Make sure pull requests pass Travis CI before merging. +- Make sure pull requests pass CI before merging. - *Rationale*: Makes sure that they pass thorough testing, and that the tester will keep passing on the master branch. Otherwise, all new pull requests will start failing the tests, resulting in @@ -1036,7 +1037,7 @@ Scripted diffs -------------- For reformatting and refactoring commits where the changes can be easily automated using a bash script, we use -scripted-diff commits. The bash script is included in the commit message and our Travis CI job checks that +scripted-diff commits. The bash script is included in the commit message and our CI job checks that the result of the script is identical to the commit. This aids reviewers since they can verify that the script does exactly what it is supposed to do. It is also helpful for rebasing (since the same script can just be re-run on the new master commit). diff --git a/doc/release-notes.md b/doc/release-notes.md index f286a4493b..8f1e03e16b 100644 --- a/doc/release-notes.md +++ b/doc/release-notes.md @@ -63,6 +63,11 @@ P2P and network changes Updated RPCs ------------ +- `getpeerinfo` no longer returns the following fields: `addnode`, `banscore`, + and `whitelisted`, which were previously deprecated in 0.21. Instead of + `addnode`, the `connection_type` field returns manual. Instead of + `whitelisted`, the `permissions` field indicates if the peer has special + privileges. The `banscore` field has simply been removed. (#20755) Changes to Wallet or GUI related RPCs can be found in the GUI or Wallet section below. diff --git a/doc/release-process.md b/doc/release-process.md index cedb36d51d..92845bcc82 100644 --- a/doc/release-process.md +++ b/doc/release-process.md @@ -307,9 +307,9 @@ bitcoin.org (see below for bitcoin.org update instructions). - First, check to see if the Bitcoin.org maintainers have prepared a release: https://github.com/bitcoin-dot-org/bitcoin.org/labels/Core - - If they have, it will have previously failed their Travis CI + - If they have, it will have previously failed their CI checks because the final release files weren't uploaded. - Trigger a Travis CI rebuild---if it passes, merge. + Trigger a CI rebuild---if it passes, merge. - If they have not prepared a release, follow the Bitcoin.org release instructions: https://github.com/bitcoin-dot-org/bitcoin.org/blob/master/docs/adding-events-release-notes-and-alerts.md#release-notes diff --git a/doc/tor.md b/doc/tor.md index 692041ccea..86e5d9ddf3 100644 --- a/doc/tor.md +++ b/doc/tor.md @@ -5,6 +5,16 @@ It is possible to run Bitcoin Core as a Tor onion service, and connect to such s The following directions assume you have a Tor proxy running on port 9050. Many distributions default to having a SOCKS proxy listening on port 9050, but others may not. In particular, the Tor Browser Bundle defaults to listening on port 9150. See [Tor Project FAQ:TBBSocksPort](https://www.torproject.org/docs/faq.html.en#TBBSocksPort) for how to properly 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 + +You may set the `-debug=tor` config logging option to have additional +information in the debug log about your Tor configuration. + ## 1. Run Bitcoin Core behind a Tor proxy @@ -51,14 +61,19 @@ The directory can be different of course, but virtual port numbers should be equ your bitcoind's P2P listen port (8333 by default), and target addresses and ports should be equal to binding address and port for inbound Tor connections (127.0.0.1:8334 by default). - -externalip=X You can tell bitcoin about its publicly reachable address using - this option, and this can be a .onion address. Given the above - configuration, you can find your .onion address in + -externalip=X You can tell bitcoin about its publicly reachable addresses using + this option, and this can be an onion address. Given the above + configuration, you can find your onion address in /var/lib/tor/bitcoin-service/hostname. For connections coming from unroutable addresses (such as 127.0.0.1, where the - Tor proxy typically runs), .onion addresses are given + Tor proxy typically runs), onion addresses are given preference for your node to advertise itself with. + You can set multiple local addresses with -externalip. The + one that will be rumoured to a particular peer is the most + compatible one and also using heuristics, e.g. the address + with the most incoming connections, etc. + -listen You'll need to enable listening for incoming connections, as this is off by default behind a proxy. @@ -71,7 +86,7 @@ should be equal to binding address and port for inbound Tor connections (127.0.0 In a typical situation, where you're only reachable via Tor, this should suffice: - ./bitcoind -proxy=127.0.0.1:9050 -externalip=57qr3yd1nyntf5k.onion -listen + ./bitcoind -proxy=127.0.0.1:9050 -externalip=7zvj7a2imdgkdbg4f2dryd5rgtrn7upivr5eeij4cicjh65pooxeshid.onion -listen (obviously, replace the .onion address with your own). It should be noted that you still listen on all devices and another node could establish a clearnet connection, when knowing @@ -89,7 +104,7 @@ and open port 8333 on your firewall (or use -upnp). If you only want to use Tor to reach .onion addresses, but not use it as a proxy for normal IPv4/IPv6 communication, use: - ./bitcoind -onion=127.0.0.1:9050 -externalip=57qr3yd1nyntf5k.onion -discover + ./bitcoind -onion=127.0.0.1:9050 -externalip=7zvj7a2imdgkdbg4f2dryd5rgtrn7upivr5eeij4cicjh65pooxeshid.onion -discover ## 3. Automatically create a Bitcoin Core onion service |