diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/developer-notes.md | 46 | ||||
| -rw-r--r-- | doc/init.md | 18 | ||||
| -rw-r--r-- | doc/man/bitcoin-cli.1 | 4 | ||||
| -rw-r--r-- | doc/man/bitcoin-qt.1 | 8 | ||||
| -rw-r--r-- | doc/man/bitcoin-tx.1 | 6 | ||||
| -rw-r--r-- | doc/man/bitcoin-wallet.1 | 67 | ||||
| -rw-r--r-- | doc/man/bitcoind.1 | 8 | ||||
| -rw-r--r-- | doc/release-notes-14491.md | 5 | ||||
| -rw-r--r-- | doc/release-notes-14667.md | 4 | ||||
| -rw-r--r-- | doc/release-notes-14941.md | 5 | ||||
| -rw-r--r-- | doc/release-notes-14982.md | 5 | ||||
| -rw-r--r-- | doc/release-notes.md | 71 | ||||
| -rw-r--r-- | doc/release-notes/release-notes-pr12255.md | 17 | ||||
| -rw-r--r-- | doc/translation_process.md | 20 |
14 files changed, 247 insertions, 37 deletions
diff --git a/doc/developer-notes.md b/doc/developer-notes.md index ec29310ffe..1deb5d791a 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -17,6 +17,7 @@ Developer Notes - [DEBUG_LOCKORDER](#debug_lockorder) - [Valgrind suppressions file](#valgrind-suppressions-file) - [Compiling for test coverage](#compiling-for-test-coverage) + - [Performance profiling with perf](#performance-profiling-with-perf) - [Locking/mutex usage notes](#lockingmutex-usage-notes) - [Threads](#threads) - [Ignoring IDE/editor files](#ignoring-ideeditor-files) @@ -265,6 +266,51 @@ make cov # A coverage report will now be accessible at `./test_bitcoin.coverage/index.html`. ``` +### Performance profiling with perf + +Profiling is a good way to get a precise idea of where time is being spent in +code. One tool for doing profiling on Linux platforms is called +[`perf`](http://www.brendangregg.com/perf.html), and has been integrated into +the functional test framework. Perf can observe a running process and sample +(at some frequency) where its execution is. + +Perf installation is contingent on which kernel version you're running; see +[this StackExchange +thread](https://askubuntu.com/questions/50145/how-to-install-perf-monitoring-tool) +for specific instructions. + +Certain kernel parameters may need to be set for perf to be able to inspect the +running process' stack. + +```sh +$ sudo sysctl -w kernel.perf_event_paranoid=-1 +$ sudo sysctl -w kernel.kptr_restrict=0 +``` + +Make sure you [understand the security +trade-offs](https://lwn.net/Articles/420403/) of setting these kernel +parameters. + +To profile a running bitcoind process for 60 seconds, you could use an +invocation of `perf record` like this: + +```sh +$ perf record \ + -g --call-graph dwarf --per-thread -F 140 \ + -p `pgrep bitcoind` -- sleep 60 +``` + +You could then analyze the results by running + +```sh +perf report --stdio | c++filt | less +``` + +or using a graphical tool like [Hotspot](https://github.com/KDAB/hotspot). + +See the functional test documentation for how to invoke perf within tests. + + **Sanitizers** Bitcoin Core can be compiled with various "sanitizers" enabled, which add diff --git a/doc/init.md b/doc/init.md index 5778b09d05..a6c9bb94d8 100644 --- a/doc/init.md +++ b/doc/init.md @@ -56,7 +56,7 @@ All three configurations assume several paths that might need to be adjusted. Binary: `/usr/bin/bitcoind` Configuration file: `/etc/bitcoin/bitcoin.conf` Data directory: `/var/lib/bitcoind` -PID file: `/var/run/bitcoind/bitcoind.pid` (OpenRC and Upstart) or `/var/lib/bitcoind/bitcoind.pid` (systemd) +PID file: `/var/run/bitcoind/bitcoind.pid` (OpenRC and Upstart) or `/run/bitcoind/bitcoind.pid` (systemd) Lock file: `/var/lock/subsys/bitcoind` (CentOS) The configuration file, PID directory (if applicable) and data directory @@ -65,6 +65,22 @@ reasons to make the configuration file and data directory only readable by the bitcoin user and group. Access to bitcoin-cli and other bitcoind rpc clients can then be controlled by group membership. +NOTE: When using the systemd .service file, the creation of the aforementioned +directories and the setting of their permissions is automatically handled by +systemd. Directories are given a permission of 710, giving the bitcoin group +access to files under it _if_ the files themselves give permission to the +bitcoin group to do so (e.g. when `-sysperms` is specified). This does not allow +for the listing of files under the directory. + +NOTE: It is not currently possible to override `datadir` in +`/etc/bitcoin/bitcoin.conf` with the current systemd, OpenRC, and Upstart init +files out-of-the-box. This is because the command line options specified in the +init files take precedence over the configurations in +`/etc/bitcoin/bitcoin.conf`. However, some init systems have their own +configuration mechanisms that would allow for overriding the command line +options specified in the init files (e.g. setting `BITCOIND_DATADIR` for +OpenRC). + ### macOS Binary: `/usr/local/bin/bitcoind` diff --git a/doc/man/bitcoin-cli.1 b/doc/man/bitcoin-cli.1 index 553addfa84..355b4d3cc2 100644 --- a/doc/man/bitcoin-cli.1 +++ b/doc/man/bitcoin-cli.1 @@ -1,5 +1,5 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.6. -.TH BITCOIN-CLI "1" "December 2018" "bitcoin-cli v0.17.99.0" "User Commands" +.TH BITCOIN-CLI "1" "February 2019" "bitcoin-cli v0.17.99.0" "User Commands" .SH NAME bitcoin-cli \- manual page for bitcoin-cli v0.17.99.0 .SH SYNOPSIS @@ -104,7 +104,7 @@ Chain selection options: .IP Use the test chain .SH COPYRIGHT -Copyright (C) 2009-2018 The Bitcoin Core developers +Copyright (C) 2009-2019 The Bitcoin Core developers Please contribute if you find Bitcoin Core useful. Visit <https://bitcoincore.org> for further information about the software. diff --git a/doc/man/bitcoin-qt.1 b/doc/man/bitcoin-qt.1 index 1d87acd3de..052d420608 100644 --- a/doc/man/bitcoin-qt.1 +++ b/doc/man/bitcoin-qt.1 @@ -1,5 +1,5 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.6. -.TH BITCOIN-QT "1" "December 2018" "bitcoin-qt v0.17.99.0" "User Commands" +.TH BITCOIN-QT "1" "February 2019" "bitcoin-qt v0.17.99.0" "User Commands" .SH NAME bitcoin-qt \- manual page for bitcoin-qt v0.17.99.0 .SH SYNOPSIS @@ -56,7 +56,7 @@ Specify data directory .HP \fB\-dbcache=\fR<n> .IP -Set database cache size in megabytes (4 to 16384, default: 450) +Set database cache size in MiB (4 to 16384, default: 450) .HP \fB\-debuglogfile=\fR<file> .IP @@ -500,7 +500,7 @@ mining and transaction creation (default: 0.00001) \fB\-whitelistforcerelay\fR .IP Force relay of transactions from whitelisted peers even if they violate -local relay policy (default: 1) +local relay policy (default: 0) .HP \fB\-whitelistrelay\fR .IP @@ -606,7 +606,7 @@ Set SSL root certificates for payment request (default: \fB\-system\-\fR) .IP Show splash screen on startup (default: 1) .SH COPYRIGHT -Copyright (C) 2009-2018 The Bitcoin Core developers +Copyright (C) 2009-2019 The Bitcoin Core developers Please contribute if you find Bitcoin Core useful. Visit <https://bitcoincore.org> for further information about the software. diff --git a/doc/man/bitcoin-tx.1 b/doc/man/bitcoin-tx.1 index f16c68ca14..c5d3985763 100644 --- a/doc/man/bitcoin-tx.1 +++ b/doc/man/bitcoin-tx.1 @@ -1,5 +1,5 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.6. -.TH BITCOIN-TX "1" "December 2018" "bitcoin-tx v0.17.99.0" "User Commands" +.TH BITCOIN-TX "1" "February 2019" "bitcoin-tx v0.17.99.0" "User Commands" .SH NAME bitcoin-tx \- manual page for bitcoin-tx v0.17.99.0 .SH SYNOPSIS @@ -92,7 +92,7 @@ sign=SIGHASH\-FLAGS .IP Add zero or more signatures to transaction. This command requires JSON registers:prevtxs=JSON object, privatekeys=JSON object. See -signrawtransaction docs for format of sighash flags, JSON +signrawtransactionwithkey docs for format of sighash flags, JSON objects. .PP Register Commands: @@ -105,7 +105,7 @@ set=NAME:JSON\-STRING .IP Set register NAME to given JSON\-STRING .SH COPYRIGHT -Copyright (C) 2009-2018 The Bitcoin Core developers +Copyright (C) 2009-2019 The Bitcoin Core developers Please contribute if you find Bitcoin Core useful. Visit <https://bitcoincore.org> for further information about the software. diff --git a/doc/man/bitcoin-wallet.1 b/doc/man/bitcoin-wallet.1 new file mode 100644 index 0000000000..3c4849cca7 --- /dev/null +++ b/doc/man/bitcoin-wallet.1 @@ -0,0 +1,67 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.6. +.TH BITCOIN-WALLET "1" "February 2019" "bitcoin-wallet v0.17.99.0" "User Commands" +.SH NAME +bitcoin-wallet \- manual page for bitcoin-wallet v0.17.99.0 +.SH DESCRIPTION +Bitcoin Core bitcoin\-wallet version v0.17.99.0 +.PP +wallet\-tool is an offline tool for creating and interacting with Bitcoin Core wallet files. +By default wallet\-tool will act on wallets in the default mainnet wallet directory in the datadir. +To change the target wallet, use the \fB\-datadir\fR, \fB\-wallet\fR and \fB\-testnet\fR/\-regtest arguments. +.SS "Usage:" +.IP +bitcoin\-wallet [options] <command> +.SH OPTIONS +.HP +\-? +.IP +This help message +.HP +\fB\-datadir=\fR<dir> +.IP +Specify data directory +.HP +\fB\-wallet=\fR<wallet\-name> +.IP +Specify wallet name +.PP +Debugging/Testing options: +.HP +\fB\-debug=\fR<category> +.IP +Output debugging information (default: 0). +.HP +\fB\-printtoconsole\fR +.IP +Send trace/debug info to console (default: 1 when no \fB\-debug\fR is true, 0 +otherwise. +.PP +Chain selection options: +.HP +\fB\-testnet\fR +.IP +Use the test chain +.PP +Commands: +.IP +create +.IP +Create new wallet file +.IP +info +.IP +Get wallet info +.SH COPYRIGHT +Copyright (C) 2009-2019 The Bitcoin Core developers + +Please contribute if you find Bitcoin Core useful. Visit +<https://bitcoincore.org> for further information about the software. +The source code is available from <https://github.com/bitcoin/bitcoin>. + +This is experimental software. +Distributed under the MIT software license, see the accompanying file COPYING +or <https://opensource.org/licenses/MIT> + +This product includes software developed by the OpenSSL Project for use in the +OpenSSL Toolkit <https://www.openssl.org> and cryptographic software written by +Eric Young and UPnP software written by Thomas Bernard. diff --git a/doc/man/bitcoind.1 b/doc/man/bitcoind.1 index 5c4b1cd03b..5e057d923f 100644 --- a/doc/man/bitcoind.1 +++ b/doc/man/bitcoind.1 @@ -1,5 +1,5 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.6. -.TH BITCOIND "1" "December 2018" "bitcoind v0.17.99.0" "User Commands" +.TH BITCOIND "1" "February 2019" "bitcoind v0.17.99.0" "User Commands" .SH NAME bitcoind \- manual page for bitcoind v0.17.99.0 .SH SYNOPSIS @@ -56,7 +56,7 @@ Specify data directory .HP \fB\-dbcache=\fR<n> .IP -Set database cache size in megabytes (4 to 16384, default: 450) +Set database cache size in MiB (4 to 16384, default: 450) .HP \fB\-debuglogfile=\fR<file> .IP @@ -500,7 +500,7 @@ mining and transaction creation (default: 0.00001) \fB\-whitelistforcerelay\fR .IP Force relay of transactions from whitelisted peers even if they violate -local relay policy (default: 1) +local relay policy (default: 0) .HP \fB\-whitelistrelay\fR .IP @@ -580,7 +580,7 @@ Username for JSON\-RPC connections .IP Accept command line and JSON\-RPC commands .SH COPYRIGHT -Copyright (C) 2009-2018 The Bitcoin Core developers +Copyright (C) 2009-2019 The Bitcoin Core developers Please contribute if you find Bitcoin Core useful. Visit <https://bitcoincore.org> for further information about the software. diff --git a/doc/release-notes-14491.md b/doc/release-notes-14491.md new file mode 100644 index 0000000000..1cf36e85cf --- /dev/null +++ b/doc/release-notes-14491.md @@ -0,0 +1,5 @@ +Descriptor import support +--------------------- + +The `importmulti` RPC now supports importing of addresses from descriptors. A "desc" parameter can be provided instead of the "scriptPubKey" in a request, as well as an optional range for ranged descriptors to specify the start and end of the range to import. More information about +descriptors can be found [here](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md). diff --git a/doc/release-notes-14667.md b/doc/release-notes-14667.md new file mode 100644 index 0000000000..5cb1d0aee7 --- /dev/null +++ b/doc/release-notes-14667.md @@ -0,0 +1,4 @@ +New RPC methods +------------ + +- `deriveaddresses` returns one or more addresses corresponding to an [output descriptor](/doc/descriptors.md). diff --git a/doc/release-notes-14941.md b/doc/release-notes-14941.md deleted file mode 100644 index c3820d0368..0000000000 --- a/doc/release-notes-14941.md +++ /dev/null @@ -1,5 +0,0 @@ -Miscellaneous RPC changes ------------- - -- The `unloadwallet` RPC is now synchronous, meaning that it blocks until the - wallet is fully unloaded. diff --git a/doc/release-notes-14982.md b/doc/release-notes-14982.md deleted file mode 100644 index 3f0bf8aacd..0000000000 --- a/doc/release-notes-14982.md +++ /dev/null @@ -1,5 +0,0 @@ -New RPCs --------- - -- The RPC `getrpcinfo` returns runtime details of the RPC server. At the moment - it returns the active commands and the corresponding execution time. diff --git a/doc/release-notes.md b/doc/release-notes.md index a54b08848f..113b8c07d0 100644 --- a/doc/release-notes.md +++ b/doc/release-notes.md @@ -116,7 +116,8 @@ Configuration option changes defaults to being off, so that changes in policy and disconnect/ban behavior will not cause a node that is whitelisting another to be dropped by peers. Users can still explicitly enable this behavior with the command line option - (and may want to consider letting the Bitcoin Core project know about their + (and may want to consider [contacting](https://bitcoincore.org/en/contact/) + the Bitcoin Core project to let us know about their use-case, as this feature could be deprecated in the future). Documentation @@ -130,6 +131,10 @@ Documentation to the [REST interface documentation](https://github.com/bitcoin/bitcoin/blob/master/doc/REST-interface.md) indicating that the same rules apply. +- Further information is added to the [JSON-RPC + documentation](https://github.com/bitcoin/bitcoin/blob/master/doc/JSON-RPC-interface.md) + about how to secure this interface. + - A new [document](https://github.com/bitcoin/bitcoin/blob/master/doc/bitcoin-conf.md) about the `bitcoin.conf` file describes how to use it to configure Bitcoin Core. @@ -190,14 +195,18 @@ Deprecated or removed RPCs New RPCs -------- -- A new `getnodeaddresses` RPC returns peer addresses known to this +- The `getnodeaddresses` RPC returns peer addresses known to this node. It may be used to find nodes to connect to without using a DNS seeder. -- A new `listwalletdir` RPC returns a list of wallets in the wallet +- The `listwalletdir` RPC returns a list of wallets in the wallet directory (either the default wallet directory or the directory configured by the `-walletdir` parameter). +- The `getrpcinfo` returns runtime details of the RPC server. At the + moment, it returns an array of the currently active commands and how + long they've been running. + Updated RPCs ------------ @@ -254,11 +263,21 @@ in the Low-level Changes section below. - See the [Mining](#mining) section for changes to `getblocktemplate`. -- The `getrawtransaction` RPC no longer checks the unspent UTXO set for - a transaction. The remaining behaviors are as follows: 1. If a - blockhash is provided, check the corresponding block. 2. If no - blockhash is provided, check the mempool. 3. If no blockhash is - provided but txindex is enabled, also check txindex. +- The `getrawtransaction` RPC & REST endpoints no longer check the + unspent UTXO set for a transaction. The remaining behaviors are as + follows: 1. If a blockhash is provided, check the corresponding block. + 2. If no blockhash is provided, check the mempool. 3. If no blockhash + is provided but txindex is enabled, also check txindex. + +- The `unloadwallet` RPC is now synchronous, meaning it will not return + until the wallet is fully unloaded. + +REST changes +------------ + +- A new `/rest/blockhashbyheight/` endpoint is added for fetching the + hash of the block in the current best blockchain based on its height + (how many blocks it is after the Genesis Block). Graphical User Interface (GUI) ------------------------------ @@ -282,6 +301,16 @@ Graphical User Interface (GUI) CFLAGS="-mmacosx-version-min=10.11" for setting the deployment sdk version) +Tools +---- + +- A new `bitcoin-wallet` tool is now distributed alongside Bitcoin + Core's other executables. Without needing to use any RPCs, this tool + can currently create a new wallet file or display some basic + information about an existing wallet, such as whether the wallet is + encrypted, whether it uses an HD seed, how many transactions it + contains, and how many address book entries it has. + Low-level changes ================= @@ -306,6 +335,32 @@ Configuration deterministic wallets. This release makes specifying `-usehd` an invalid configuration option. +Network +------- + +- This release allows peers that your node automatically disconnected + for misbehavior (e.g. sending invalid data) to reconnect to your node + if you have unused incoming connection slots. If your slots fill up, + a misbehaving node will be disconnected to make room for nodes without + a history of problems (unless the misbehaving node helps your node in + some other way, such as by connecting to a part of the Internet from + which you don't have many other peers). Previously, Bitcoin Core + banned the IP addresses of misbehaving peers for a period of time + (default of 1 day); this was easily circumvented by attackers with + multiple IP addresses. If you manually ban a peer, such as by using + the `setban` RPC, all connections from that peer will still be + rejected. + +Security +-------- + +- This release changes the Random Number Generator (RNG) used from + OpenSSL to Bitcoin Core's own implementation, although entropy + gathered by Bitcoin Core is fed out to OpenSSL and then read back in + when the program needs strong randomness. This moves Bitcoin Core a + little closer to no longer needing to depend on OpenSSL, a dependency + that has caused security issues in the past. + Changes for particular platforms -------------------------------- diff --git a/doc/release-notes/release-notes-pr12255.md b/doc/release-notes/release-notes-pr12255.md new file mode 100644 index 0000000000..5ac8b44283 --- /dev/null +++ b/doc/release-notes/release-notes-pr12255.md @@ -0,0 +1,17 @@ +systemd init file +========= + +The systemd init file (`contrib/init/bitcoind.service`) has been changed to use +`/var/lib/bitcoind` as the data directory instead of `~bitcoin/.bitcoin`. This +change makes Bitcoin Core more consistent with other services, and makes the +systemd init config more consistent with existing Upstart and OpenRC configs. + +The configuration, PID, and data directories are now completely managed by +systemd, which will take care of their creation, permissions, etc. See +[`systemd.exec (5)`](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#RuntimeDirectory=) +for more details. + +When using the provided init files under `contrib/init`, overriding the +`datadir` option in `/etc/bitcoin/bitcoin.conf` will have no effect. This is +because the command line arguments specified in the init files take precedence +over the options specified in `/etc/bitcoin/bitcoin.conf`. diff --git a/doc/translation_process.md b/doc/translation_process.md index 19f145e9bf..9692832842 100644 --- a/doc/translation_process.md +++ b/doc/translation_process.md @@ -68,11 +68,21 @@ The Transifex Bitcoin project config file is included as part of the repo. It ca To assist in updating translations, we have created a script to help. 1. `python contrib/devtools/update-translations.py` -2. Update `src/qt/bitcoin_locale.qrc` manually or via - `ls src/qt/locale/*ts|xargs -n1 basename|sed 's/\(bitcoin_\(.*\)\).ts/<file alias="\2">locale\/\1.qm<\/file>/'` -3. Update `src/Makefile.qt.include` manually or via - `ls src/qt/locale/*ts|xargs -n1 basename|sed 's/\(bitcoin_\(.*\)\).ts/ qt\/locale\/\1.ts \\/'` -4. `git add` new translations from `src/qt/locale/` +2. `git add` new translations from `src/qt/locale/` +3. Update `src/qt/bitcoin_locale.qrc` manually or via +```bash +git ls-files src/qt/locale/*ts|xargs -n1 basename|sed 's/\(bitcoin_\(.*\)\).ts/<file alias="\2">locale\/\1.qm<\/file>/' +``` +4. Update `src/Makefile.qt.include` manually or via +```bash +git ls-files src/qt/locale/*ts|xargs -n1 basename|sed 's/\(bitcoin_\(.*\)\).ts/ qt\/locale\/\1.ts \\/' +``` +5. Update `build_msvc/libbitcoin_qt/libbitcoin_qt.vcxproj` or via +```bash +git ls-files src/qt/locale/*ts|xargs -n1 basename | + sed 's/@/%40/' | + sed 's/\(bitcoin_\(.*\)\).ts/ <None Include="..\\..\\src\\qt\\locale\\\1.ts">\n <DeploymentContent>true<\/DeploymentContent>\n <\/None>/' +``` **Do not directly download translations** one by one from the Transifex website, as we do a few post-processing steps before committing the translations. |