Skip to content

Commit d4475ea

Browse files
committed
Merge bitcoin/bitcoin#22235: script: add script to generate example bitcoin.conf
b42643c doc: update init.cpp -conf help text (josibake) 970b998 doc: update devtools, release-process readmes (josibake) 50635d2 build: include bitcoin.conf in build outputs (josibake) 6aac946 doc: update bitcoin-conf.md (Josiah Baker) 1c7e820 script: add script to generate example bitcoin.conf (josibake) b483084 doc: replace bitcoin.conf with placeholder file (josibake) Pull request description: create a script for parsing the output from `bitcoind --help` to create an example conf file for new users ## problem per #10746 , `bitcoin.conf` not being put into the data directory during installation causes some confusion for users when running bitcoin. in the discussion on the issue, one proposed solution was to have an example config file and instruct users to `cp` it into their data directory after startup. in addition to #10746 , there have been other requests for a "skeleton config file" (bitcoin/bitcoin#19641) to help users get started with configuring bitcoind. the main issue with an example config file is that it creates a second source of truth regarding what options are available for configuring bitcoind. this means any changes to the options (including the addition or removal of options) would have to be updated for the command line and also updated in the example file. this PR addresses this issue by providing a script to generate an example file directly from the `bitcoind --help` on-demand by running `contrib/devtools/gen-bitcoin-conf.sh`. this solution was originally proposed on #10746 and would also solve #19641 . this guarantees any changes made to the command-line options or the command-line options help would also be reflected in the example file after compiling and running the script. the main purpose of this script is to generate a config file to be included with releases, same as `gen-manpages.sh`. this ensures every release also includes an up-to-date, full example config file for users to edit. the script is also available for users who compile from source for generating an example config for their compiled binary. ## special considerations this removes the `bitcoin.conf` example file from the repo as it is now generated by this script. the original example file did contain extra text related to how to use certain options but going forward all option help docs should be moved into `init.cpp` this also edits `init.cpp` to have the option help indicate that `-conf` is not usable from the config file. this is similar to how `-includeconf` 's help indicates it cannot be used from the command line ACKs for top commit: laanwj: Tested and code review ACK b42643c Tree-SHA512: 4546e0cef92aa1398da553294ce4712d02e616dd72dcbe0b921af474e54f24750464ec813661f1283802472d1e8774e634dd1cc26fbf1f13286d3e0406c02c09
2 parents 5e1aaca + b42643c commit d4475ea

File tree

7 files changed

+114
-193
lines changed

7 files changed

+114
-193
lines changed

contrib/devtools/README.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,21 @@ example:
9090
BUILDDIR=$PWD/build contrib/devtools/gen-manpages.py
9191
```
9292

93+
gen-bitcoin-conf.sh
94+
===================
95+
96+
Generates a bitcoin.conf file in `share/examples/` by parsing the output from `bitcoind --help`. This script is run during the
97+
release process to include a bitcoin.conf with the release binaries and can also be run by users to generate a file locally.
98+
When generating a file as part of the release process, make sure to commit the changes after running the script.
99+
100+
With in-tree builds this tool can be run from any directory within the
101+
repository. To use this tool with out-of-tree builds set `BUILDDIR`. For
102+
example:
103+
104+
```bash
105+
BUILDDIR=$PWD/build contrib/devtools/gen-bitcoin-conf.sh
106+
```
107+
93108
security-check.py and test-security-check.py
94109
============================================
95110

contrib/devtools/gen-bitcoin-conf.sh

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
#!/usr/bin/env bash
2+
# Copyright (c) 2021 The Bitcoin Core developers
3+
# Distributed under the MIT software license, see the accompanying
4+
# file COPYING or http://www.opensource.org/licenses/mit-license.php.
5+
6+
export LC_ALL=C
7+
TOPDIR=${TOPDIR:-$(git rev-parse --show-toplevel)}
8+
BUILDDIR=${BUILDDIR:-$TOPDIR}
9+
BINDIR=${BINDIR:-$BUILDDIR/src}
10+
BITCOIND=${BITCOIND:-$BINDIR/bitcoind}
11+
SHARE_EXAMPLES_DIR=${SHARE_EXAMPLES_DIR:-$TOPDIR/share/examples}
12+
EXAMPLE_CONF_FILE=${EXAMPLE_CONF_FILE:-$SHARE_EXAMPLES_DIR/bitcoin.conf}
13+
14+
[ ! -x "$BITCOIND" ] && echo "$BITCOIND not found or not executable." && exit 1
15+
16+
DIRTY=""
17+
VERSION_OUTPUT=$($BITCOIND --version)
18+
if [[ $VERSION_OUTPUT == *"dirty"* ]]; then
19+
DIRTY="${DIRTY}${BITCOIND}\n"
20+
fi
21+
22+
if [ -n "$DIRTY" ]
23+
then
24+
echo -e "WARNING: $BITCOIND was built from a dirty tree.\n"
25+
echo -e "To safely generate a bitcoin.conf file, please commit your changes to $BITCOIND, rebuild, then run this script again.\n"
26+
fi
27+
28+
echo 'Generating example bitcoin.conf file in share/examples/'
29+
30+
# create the directory, if it doesn't exist
31+
mkdir -p "${SHARE_EXAMPLES_DIR}"
32+
33+
# create the header text
34+
cat > "${EXAMPLE_CONF_FILE}" << 'EOF'
35+
##
36+
## bitcoin.conf configuration file.
37+
## Generated by contrib/devtools/gen-bitcoin-conf.sh.
38+
##
39+
## Lines beginning with # are comments.
40+
## All possible configuration options are provided. To use, copy this file
41+
## to your data directory (default or specified by -datadir), uncomment
42+
## options you would like to change, and save the file.
43+
##
44+
45+
46+
### Options
47+
EOF
48+
49+
# parse the output from bitcoind --help
50+
# adding newlines is a bit funky to ensure portability for BSD
51+
# see here for more details: https://stackoverflow.com/a/24575385
52+
${BITCOIND} --help \
53+
| sed '1,/Print this help message and exit/d' \
54+
| sed -E 's/^[[:space:]]{2}\-/#/' \
55+
| sed -E 's/^[[:space:]]{7}/# /' \
56+
| sed -E '/[=[:space:]]/!s/#.*$/&=1/' \
57+
| awk '/^#[a-z]/{x=$0;next}{if (NF==0) print x"\n",x="";else print}' \
58+
| sed 's,\(^[[:upper:]].*\)\:$,\
59+
### \1,' \
60+
| sed 's/[[:space:]]*$//' >> "${EXAMPLE_CONF_FILE}"
61+
62+
# create the footer text
63+
cat >> "${EXAMPLE_CONF_FILE}" << 'EOF'
64+
65+
# [Sections]
66+
# Most options will apply to all networks. To confine an option to a specific
67+
# network, add it under the relevant section below.
68+
#
69+
# Note: If not specified under a network section, the options addnode, connect,
70+
# port, bind, rpcport, rpcbind, and wallet will only apply to mainnet.
71+
72+
# Options for mainnet
73+
[main]
74+
75+
# Options for testnet
76+
[test]
77+
78+
# Options for signet
79+
[signet]
80+
81+
# Options for regtest
82+
[regtest]
83+
EOF

contrib/guix/libexec/build.sh

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -368,6 +368,10 @@ mkdir -p "$DISTSRC"
368368
;;
369369
esac
370370

371+
# copy over the example bitcoin.conf file. if contrib/devtools/gen-bitcoin-conf.sh
372+
# has not been run before buildling, this file will be a stub
373+
cp "${DISTSRC}/share/examples/bitcoin.conf" "${DISTNAME}/"
374+
371375
# Finally, deterministically produce {non-,}debug binary tarballs ready
372376
# for release
373377
case "$HOST" in

doc/bitcoin-conf.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,4 +61,12 @@ Windows | `%APPDATA%\Bitcoin\` | `C:\Users\username\AppData\Roaming\Bitcoin\bitc
6161
Linux | `$HOME/.bitcoin/` | `/home/username/.bitcoin/bitcoin.conf`
6262
macOS | `$HOME/Library/Application Support/Bitcoin/` | `/Users/username/Library/Application Support/Bitcoin/bitcoin.conf`
6363

64-
You can find an example bitcoin.conf file in [share/examples/bitcoin.conf](../share/examples/bitcoin.conf).
64+
An example configuration file can be generated by [contrib/devtools/gen-bitcoin-conf.sh](../contrib/devtools/gen-bitcoin-conf.sh).
65+
Run this script after compiling to generate an up-to-date configuration file.
66+
The output is placed under `share/examples/bitcoin.conf`.
67+
To use the generated configuration file, copy the example file into your data directory and edit it there, like so:
68+
69+
```
70+
# example copy command for linux user
71+
cp share/examples/bitcoin.conf ~/.bitcoin
72+
```

doc/release-process.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ Release Process
88
* Update translations see [translation_process.md](https://github.com/bitcoin/bitcoin/blob/master/doc/translation_process.md#synchronising-translations).
99
* Update release candidate version in `configure.ac` (`CLIENT_VERSION_RC`).
1010
* Update manpages (after rebuilding the binaries), see [gen-manpages.py](https://github.com/bitcoin/bitcoin/blob/master/contrib/devtools/README.md#gen-manpagespy).
11+
* Update bitcoin.conf and commit, see [gen-bitcoin-conf.sh](https://github.com/bitcoin/bitcoin/blob/master/contrib/devtools/README.md#gen-bitcoin-confsh).
1112

1213
### Before every major and minor release
1314

share/examples/bitcoin.conf

Lines changed: 1 addition & 191 deletions
Original file line numberDiff line numberDiff line change
@@ -1,191 +1 @@
1-
##
2-
## bitcoin.conf configuration file. Lines beginning with # are comments.
3-
##
4-
5-
# Network-related settings:
6-
7-
# Note that if you use testnet, signet or regtest, particularly with the options
8-
# addnode, connect, port, bind, rpcport, rpcbind or wallet, you will also
9-
# want to read "[Sections]" further down.
10-
11-
# Run on the testnet network
12-
#testnet=0
13-
14-
# Run on a signet network
15-
#signet=0
16-
17-
# Run a regression test network
18-
#regtest=0
19-
20-
# Connect via a SOCKS5 proxy
21-
#proxy=127.0.0.1:9050
22-
23-
# Bind to given address and always listen on it. Use [host]:port notation for IPv6
24-
#bind=<addr>
25-
26-
# Bind to given address and add permission flags to peers connecting to it. Use [host]:port notation for IPv6
27-
#whitebind=perm@<addr>
28-
29-
##############################################################
30-
## Quick Primer on addnode vs connect ##
31-
## Let's say for instance you use addnode=4.2.2.4 ##
32-
## addnode will connect you to and tell you about the ##
33-
## nodes connected to 4.2.2.4. In addition it will tell ##
34-
## the other nodes connected to it that you exist so ##
35-
## they can connect to you. ##
36-
## connect will not do the above when you 'connect' to it. ##
37-
## It will *only* connect you to 4.2.2.4 and no one else.##
38-
## ##
39-
## So if you're behind a firewall, or have other problems ##
40-
## finding nodes, add some using 'addnode'. ##
41-
## ##
42-
## If you want to stay private, use 'connect' to only ##
43-
## connect to "trusted" nodes. ##
44-
## ##
45-
## If you run multiple nodes on a LAN, there's no need for ##
46-
## all of them to open lots of connections. Instead ##
47-
## 'connect' them all to one node that is port forwarded ##
48-
## and has lots of connections. ##
49-
## Thanks goes to [Noodle] on Freenode. ##
50-
##############################################################
51-
52-
# Use as many addnode= settings as you like to connect to specific peers
53-
#addnode=69.164.218.197
54-
#addnode=10.0.0.2:8333
55-
56-
# Alternatively use as many connect= settings as you like to connect ONLY to specific peers
57-
#connect=69.164.218.197
58-
#connect=10.0.0.1:8333
59-
60-
# Listening mode, enabled by default except when 'connect' is being used
61-
#listen=1
62-
63-
# Port on which to listen for connections (default: 8333, testnet: 18333, signet: 38333, regtest: 18444)
64-
#port=
65-
66-
# Maximum number of inbound + outbound connections (default: 125). This option
67-
# applies only if inbound connections are enabled; otherwise, the number of connections
68-
# will not be more than 11: 8 full-relay connections, 2 block-relay-only ones, and
69-
# occasionally 1 short-lived feeler or extra outbound block-relay-only connection.
70-
# These limits do not apply to connections added manually with the -addnode
71-
# configuration option or the addnode RPC, which have a separate limit of 8 connections.
72-
#maxconnections=
73-
74-
# Maximum upload bandwidth target in MiB per day (e.g. 'maxuploadtarget=1024' is 1 GiB per day).
75-
# This limits the upload bandwidth for those with bandwidth limits. 0 = no limit (default: 0).
76-
# -maxuploadtarget does not apply to peers with 'download' permission.
77-
# For more information on reducing bandwidth utilization, see: doc/reduce-traffic.md.
78-
#maxuploadtarget=
79-
80-
#
81-
# JSON-RPC options (for controlling a running Bitcoin/bitcoind process)
82-
#
83-
84-
# server=1 tells Bitcoin-Qt and bitcoind to accept JSON-RPC commands
85-
#server=0
86-
87-
# Bind to given address to listen for JSON-RPC connections.
88-
# Refer to the manpage or bitcoind -help for further details.
89-
#rpcbind=<addr>
90-
91-
# If no rpcpassword is set, rpc cookie auth is sought. The default `-rpccookiefile` name
92-
# is .cookie and found in the `-datadir` being used for bitcoind. This option is typically used
93-
# when the server and client are run as the same user.
94-
#
95-
# If not, you must set rpcuser and rpcpassword to secure the JSON-RPC API.
96-
#
97-
# The config option `rpcauth` can be added to server startup argument. It is set at initialization time
98-
# using the output from the script in share/rpcauth/rpcauth.py after providing a username:
99-
#
100-
# ./share/rpcauth/rpcauth.py alice
101-
# String to be appended to bitcoin.conf:
102-
# rpcauth=alice:f7efda5c189b999524f151318c0c86$d5b51b3beffbc02b724e5d095828e0bc8b2456e9ac8757ae3211a5d9b16a22ae
103-
# Your password:
104-
# DONT_USE_THIS_YOU_WILL_GET_ROBBED_8ak1gI25KFTvjovL3gAM967mies3E=
105-
#
106-
# On client-side, you add the normal user/password pair to send commands:
107-
#rpcuser=alice
108-
#rpcpassword=DONT_USE_THIS_YOU_WILL_GET_ROBBED_8ak1gI25KFTvjovL3gAM967mies3E=
109-
#
110-
# You can even add multiple entries of these to the server conf file, and client can use any of them:
111-
# rpcauth=bob:b2dd077cb54591a2f3139e69a897ac$4e71f08d48b4347cf8eff3815c0e25ae2e9a4340474079f55705f40574f4ec99
112-
113-
# How many seconds bitcoin will wait for a complete RPC HTTP request.
114-
# after the HTTP connection is established.
115-
#rpcclienttimeout=30
116-
117-
# By default, only RPC connections from localhost are allowed.
118-
# Specify as many rpcallowip= settings as you like to allow connections from other hosts,
119-
# either as a single IPv4/IPv6 or with a subnet specification.
120-
121-
# NOTE: opening up the RPC port to hosts outside your local trusted network is NOT RECOMMENDED,
122-
# because the rpcpassword is transmitted over the network unencrypted.
123-
124-
# server=1 tells Bitcoin-Qt to accept JSON-RPC commands.
125-
# it is also read by bitcoind to determine if RPC should be enabled
126-
#rpcallowip=10.1.1.34/255.255.255.0
127-
#rpcallowip=1.2.3.4/24
128-
#rpcallowip=2001:db8:85a3:0:0:8a2e:370:7334/96
129-
130-
# Listen for RPC connections on this TCP port:
131-
#rpcport=8332
132-
133-
# You can use Bitcoin or bitcoind to send commands to Bitcoin/bitcoind
134-
# running on another host using this option:
135-
#rpcconnect=127.0.0.1
136-
137-
# Wallet options
138-
139-
# Specify where to find wallet, lockfile and logs. If not present, those files will be
140-
# created as new.
141-
#wallet=</path/to/dir>
142-
143-
# Create transactions that have enough fees so they are likely to begin confirmation within n blocks (default: 6).
144-
# This setting is over-ridden by the -paytxfee option.
145-
#txconfirmtarget=n
146-
147-
# Pay a transaction fee every time you send bitcoins.
148-
#paytxfee=0.000x
149-
150-
# Miscellaneous options
151-
152-
# Pre-generate this many public/private key pairs, so wallet backups will be valid for
153-
# both prior transactions and several dozen future transactions.
154-
#keypool=100
155-
156-
# Maintain coinstats index used by the gettxoutsetinfo RPC (default: 0).
157-
#coinstatsindex=1
158-
159-
# Enable pruning to reduce storage requirements by deleting old blocks.
160-
# This mode is incompatible with -txindex and -coinstatsindex.
161-
# 0 = default (no pruning).
162-
# 1 = allows manual pruning via RPC.
163-
# >=550 = target to stay under in MiB.
164-
#prune=550
165-
166-
# User interface options
167-
168-
# Start Bitcoin minimized
169-
#min=1
170-
171-
# Minimize to the system tray
172-
#minimizetotray=1
173-
174-
# [Sections]
175-
# Most options apply to mainnet, testnet, signet and regtest.
176-
# If you want to confine an option to just one network, you should add it in the
177-
# relevant section below.
178-
# EXCEPTIONS: The options addnode, connect, port, bind, rpcport, rpcbind and wallet
179-
# only apply to mainnet unless they appear in the appropriate section below.
180-
181-
# Options only for mainnet
182-
[main]
183-
184-
# Options only for testnet
185-
[test]
186-
187-
# Options only for signet
188-
[signet]
189-
190-
# Options only for regtest
191-
[regtest]
1+
# This is a placeholder file. Please follow the instructions in `contrib/devtools/README.md` to generate a bitcoin.conf file.

src/init.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -409,7 +409,7 @@ void SetupServerArgs(ArgsManager& argsman)
409409
argsman.AddArg("-blockreconstructionextratxn=<n>", strprintf("Extra transactions to keep in memory for compact block reconstructions (default: %u)", DEFAULT_BLOCK_RECONSTRUCTION_EXTRA_TXN), ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
410410
argsman.AddArg("-blocksonly", strprintf("Whether to reject transactions from network peers. Automatic broadcast and rebroadcast of any transactions from inbound peers is disabled, unless the peer has the 'forcerelay' permission. RPC transactions are not affected. (default: %u)", DEFAULT_BLOCKSONLY), ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
411411
argsman.AddArg("-coinstatsindex", strprintf("Maintain coinstats index used by the gettxoutsetinfo RPC (default: %u)", DEFAULT_COINSTATSINDEX), ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
412-
argsman.AddArg("-conf=<file>", strprintf("Specify path to read-only configuration file. Relative paths will be prefixed by datadir location. (default: %s)", BITCOIN_CONF_FILENAME), ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
412+
argsman.AddArg("-conf=<file>", strprintf("Specify path to read-only configuration file. Relative paths will be prefixed by datadir location (only useable from command line, not configuration file) (default: %s)", BITCOIN_CONF_FILENAME), ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
413413
argsman.AddArg("-datadir=<dir>", "Specify data directory", ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
414414
argsman.AddArg("-dbbatchsize", strprintf("Maximum database write batch size in bytes (default: %u)", nDefaultDbBatchSize), ArgsManager::ALLOW_ANY | ArgsManager::DEBUG_ONLY, OptionsCategory::OPTIONS);
415415
argsman.AddArg("-dbcache=<n>", strprintf("Maximum database cache size <n> MiB (%d to %d, default: %d). In addition, unused mempool memory is shared for this cache (see -maxmempool).", nMinDbCache, nMaxDbCache, nDefaultDbCache), ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);

0 commit comments

Comments
 (0)