aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/README.md1
-rw-r--r--doc/bitcoin-conf.md37
2 files changed, 38 insertions, 0 deletions
diff --git a/doc/README.md b/doc/README.md
index c2187ca3b3..de33c1b5b9 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -69,6 +69,7 @@ The Bitcoin repo's [root README](/README.md) contains relevant information on th
### Miscellaneous
- [Assets Attribution](assets-attribution.md)
+- [bitcoin.conf Configuration File](bitcoin-conf.md)
- [Files](files.md)
- [Fuzz-testing](fuzzing.md)
- [Reduce Traffic](reduce-traffic.md)
diff --git a/doc/bitcoin-conf.md b/doc/bitcoin-conf.md
new file mode 100644
index 0000000000..88ecb8fe65
--- /dev/null
+++ b/doc/bitcoin-conf.md
@@ -0,0 +1,37 @@
+# `bitcoin.conf` Configuration File
+
+The configuration file is used by `bitcoind`, `bitcoin-qt` and `bitcoin-cli`.
+
+All command-line options (except for `-?`, `-help`, `-version` and `-conf`) may be specified in a configuration file, and all configuration file options (except for `includeconf`) may also be specified on the command line. Command-line options override values set in the configuration file and configuration file options override values set in the GUI.
+
+## Configuration File Format
+
+The configuration file is a plain text file and consists of `option=value` entries, one per line. Leading and trailing whitespaces are removed.
+
+In contrast to the command-line usage:
+- an option must be specified without leading `-`;
+- a value of the given option is mandatory; e.g., `testnet=1` (for chain selection options), `noconnect=1` (for negated options).
+
+### Blank lines
+
+Blank lines are allowed and ignored by the parser.
+
+### Comments
+
+A comment starts with a number sign (`#`) and extends to the end of the line. All comments are ignored by the parser.
+
+Comments may appear in two ways:
+- on their own on an otherwise empty line (_preferable_);
+- after an `option=value` entry.
+
+### Network specific options
+
+Network specific options can be:
+- placed into sections with headers `[main]` (not `[mainnet]`), `[test]` (not `[testnet]`) or `[regtest]`;
+- prefixed with a chain name; e.g., `regtest.maxmempool=100`.
+
+## Configuration File Path
+
+The configuration file is not automatically created; you can create it using your favorite text editor. By default, the configuration file name is `bitcoin.conf` and it is located in the Bitcoin data directory, but both the Bitcoin data directory and the configuration file path may be changed using the `-datadir` and `-conf` command-line options.
+
+The `includeconf=<file>` option in the `bitcoin.conf` file can be used to include additional configuration files.