From 39729a910a0f75bd91ae6ef2985c662da995dcb3 Mon Sep 17 00:00:00 2001 From: Fabian Jahr Date: Fri, 30 Aug 2024 22:48:10 +0200 Subject: [PATCH] doc: Expand documentation on asmap feature and tooling --- contrib/README.md | 3 +++ contrib/asmap/README.md | 28 +++++++++++++++++++++++++++- src/init.cpp | 9 ++++++++- 3 files changed, 38 insertions(+), 2 deletions(-) diff --git a/contrib/README.md b/contrib/README.md index f375993ac4b769..9456d0bd505d9b 100644 --- a/contrib/README.md +++ b/contrib/README.md @@ -18,6 +18,9 @@ A Linux bash script that will set up traffic control (tc) to limit the outgoing ### [Seeds](/contrib/seeds) ### Utility to generate the pnSeed[] array that is compiled into the client. +### [ASMap](/contrib/asmap) ### +Utilities to analyze and process asmap files. + Build Tools and Keys --------------------- diff --git a/contrib/asmap/README.md b/contrib/asmap/README.md index 5fab4b285e2131..e6eaa9337369e2 100644 --- a/contrib/asmap/README.md +++ b/contrib/asmap/README.md @@ -4,9 +4,35 @@ Tool for performing various operations on textual and binary asmap files, particularly encoding/compressing the raw data to the binary format that can be used in Bitcoin Core with the `-asmap` option. -Example usage: +## Example usage + +To decode/encode asmap files use the `decode` and `encode` commands. + ``` python3 asmap-tool.py encode /path/to/input.file /path/to/output.file python3 asmap-tool.py decode /path/to/input.file /path/to/output.file +``` + +The `diff` command computes the differences between two asmap files. They can +be text or binary. + +``` python3 asmap-tool.py diff /path/to/first.file /path/to/second.file ``` + +The `diff_addrs` command computes the differences between two asmap files but +limited to a set of addresses that need to be passed as a third argument. This +should be a list of known addresses from `getnodeaddresses`. + +``` +bitcoin-cli getnodeaddresses 0 > addrs.json +python3 asmap-tool.py diff /path/to/first.file /path/to/second.file addrs.json +``` + +The `gen_header` command generates a header file from a given asmap file and +is used in the build process to generate the header file containing the +asmap data embedded in the binary. + +``` +python3 asmap-tool.py gen_header /path/to/asmap.dat /path/to/asmap.h +``` diff --git a/src/init.cpp b/src/init.cpp index 3e47f8b961ba36..c90cbadd0a26d8 100644 --- a/src/init.cpp +++ b/src/init.cpp @@ -527,7 +527,14 @@ void SetupServerArgs(ArgsManager& argsman) ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS); argsman.AddArg("-addnode=", strprintf("Add a node to connect to and attempt to keep the connection open (see the addnode RPC help for more info). This option can be specified multiple times to add multiple nodes; connections are limited to %u at a time and are counted separately from the -maxconnections limit.", MAX_ADDNODE_CONNECTIONS), ArgsManager::ALLOW_ANY | ArgsManager::NETWORK_ONLY, OptionsCategory::CONNECTION); - argsman.AddArg("-asmap=", strprintf("Specify asn mapping used for bucketing of the peers (default: %s). Relative paths will be prefixed by the net-specific datadir location.", DEFAULT_ASMAP_FILENAME), ArgsManager::ALLOW_ANY, OptionsCategory::CONNECTION); + argsman.AddArg("-asmap=", strprintf("Use IP to ASN mapping for bucketing of the peers. If a file argument is not given (-asmap or -asmap=1), a file in the default location (%s) will be used.%s Relative paths will be prefixed by the net-specific datadir location.", + DEFAULT_ASMAP_FILENAME, + #ifdef ENABLE_EMBEDDED_ASMAP + " If no file is found there, the embedded mapping data in the binary will be used as a fallback." + #else + "" + #endif + ), ArgsManager::ALLOW_ANY, OptionsCategory::CONNECTION); argsman.AddArg("-bantime=", strprintf("Default duration (in seconds) of manually configured bans (default: %u)", DEFAULT_MISBEHAVING_BANTIME), ArgsManager::ALLOW_ANY, OptionsCategory::CONNECTION); argsman.AddArg("-bind=[:][=onion]", strprintf("Bind to given address and always listen on it (default: 0.0.0.0). Use [host]:port notation for IPv6. Append =onion to tag any incoming connections to that address and port as incoming Tor connections (default: 127.0.0.1:%u=onion, testnet3: 127.0.0.1:%u=onion, testnet4: 127.0.0.1:%u=onion, signet: 127.0.0.1:%u=onion, regtest: 127.0.0.1:%u=onion)", defaultBaseParams->OnionServiceTargetPort(), testnetBaseParams->OnionServiceTargetPort(), testnet4BaseParams->OnionServiceTargetPort(), signetBaseParams->OnionServiceTargetPort(), regtestBaseParams->OnionServiceTargetPort()), ArgsManager::ALLOW_ANY | ArgsManager::NETWORK_ONLY, OptionsCategory::CONNECTION); argsman.AddArg("-cjdnsreachable", "If set, then this host is configured for CJDNS (connecting to fc00::/8 addresses would lead us to the CJDNS network, see doc/cjdns.md) (default: 0)", ArgsManager::ALLOW_ANY, OptionsCategory::CONNECTION);