It’s important to keep the BitBox Base in a consistently configured state. Here we describe how to set the initial configuration on build, control it internally during operations, store and backup the configuration and manage it remotely from the BitBox App.
The initial system configuration is set on build and can be altered by setting build options in the file
Available options are described directly in the file and are set to default values. A few examples of build options you can set:
BASE_BITCOIN_NETWORK: set to
BASE_HOSTNAME: set it to
aliceand your BitBox Base will be visible as
alice.localwithin your network
BASE_AUTOSETUP_SSD: set to “true” to automatically initialize the SSD on first boot
BASE_OVERLAYROOT: set to ‘true’ to make the root filesystem read-only
- …and many more.
To preserve a local configuration, you can copy the file to
build-local.conf in the same directory. This file is excluded from Git source control and overwrites options from
System configuration is managed internally using the script
bbb-config.sh. Its goal is to centrally define how changes are applied to the system and reuse a single set of commands. This is why it is called by the build script as well as by the BitBox Base Middleware during operations. Changes are applied by simple operating system commands like copying and deleting files, or replacing text values withing configuration files.
You can call the script
bbb-config.sh --help to see all possible commands and arguments:
BitBox Base: system configuration utility usage: bbb-config.sh [--version] [--help] <command> [<args>] assumes Redis database running to be used with 'redis-cli' possible commands: enable <bitcoin_ibd_clearnet|dashboard_hdmi|dashboard_web|wifi|autosetup_ssd| tor|tor_bbbmiddleware|tor_ssh|tor_electrum|overlayroot|root_pwlogin> disable any 'enable' argument set <bitcoin_network|hostname|root_pw|wifi_ssid|wifi_pw> bitcoin_network <mainnet|testnet> bitcoin_ibd <true|false> bitcoin_dbcache int (MB) other arguments string get <tor_ssh_onion|tor_electrum_onion>
Similar to the configuration script, the
bbb-cmd.sh script acts as the central repository for standard commands, to be called from the Middleware.
BitBox Base: system commands repository usage: bbb-cmd.sh [--version] [--help] <command> possible commands: setup <datadir> base <restart|shutdown> bitcoind <reindex|resync|refresh_rpcauth> flashdrive <check|mount|umount> backup <sysconfig|hsm_secret> restore <sysconfig|hsm_secret> mender-update <install|commit>
The Redis key/value datastore is used to manage configuration data. It can be queried from all software components, be it from the command line, Bash, Python or Go with minimal overhead.
- from the terminal, Redis can be used with its command-line utility
- for usage within bash scripts, the necessary helper function are sourced from the include redis.sh.inc
- Go applications use the Redigo client
- Python uses redis-py
The Redis data is dumped frequently and on demand to
/data/redis/bitboxbase.rdb, from where it can be backed up or restored.
Configuration values are stored in keys, like the following examples. For a full reference of used keys, refer to
base:hostname bitbox-base tor:base:enabled 1 bitcoind:network mainnet lightningd:bind-addr 127.0.0.1:9735 electrs:db_dir /mnt/ssd/electrs/db
This application parses a template, populates it with the corresponding Redis values, and stores it to the system (even into the read-only filesystem, if applicable).
- during build, the bash function
generateConfig()is used within the Armbian customizing script.
- in regular operation, changes to Redis values and the regeneration of config files are typically executed through the
To keep the configuration scripts consistent, the bash function
generateConfig() is sourced from the include file
Ultimately, the configuration is managed by the user through the BitBox App, that talks to the Middleware which in turn calls either the
bbb-cmd.sh script with the necessary arguments.
The App provides a convenient backup feature to save the whole system configuration directly to a USB stick plugged into the Base.