Configuration
Bee is a very flexible piece of software, and can be configured in a variety of ways depending on your use case. This expanded section will cover configuration in detail.
Important Configuration Changes#
important
Before starting Bee for the first time, there is some configuration to do! Make sure you consider updating the recommended settings in the installation guide!
Specifying Configuration#
Configuration Priority#
Configuration is processed in the following ascending order of preference:
- Command Line Arguments
- Environment Variables
- Configuration File
Command Line Arguments#
Run bee start --help in your Terminal to get the list of available command line arguments.
Environment variables#
Bee config may also be passed using environment variables.
Environment variables are set as variables in your operating system's session or systemd configuration file. To set an environment variable, type the following in your terminal session.
Verify if it is correctly set by running echo $VARIABLE_NAME.
All available configuration options are available as BEE prefixed,
capitalised, and underscored environment variables.
e.g. --api-addr becomes BEE_API_ADDR.
Configuration file#
Bee can also be configured by providing a YAML configuration file using the --config flag.
Automatically generate a config file#
Configuration files can be easily generated by simply substituting the start command with printconfig when starting Bee using the command line.
This produces the following file contents, showing the default configuration of Bee:
Configuring Bee Installed Using a Package Manager#
Bee node's installed using package managers apt-get or yum are
configured using a configuration file which is automatically generated
during the installation process.
To alter Bee's configuration, simply edit the configuration file as desired, and restart your Bee service.
Linux#
MacOS#
Configuration Options#
Bee provides the following options to customise your node.
Global#
--config#
default /home/<user>/.bee.yaml
The location of a YAML configuration file containing configuration options. See configuration.
Start#
--admin-password#
When the permission checks for the API is enabled then this option configure admin password that is used to generate Bearer tokens.
Be aware that you need to pass a bcrypt hash of the password here not the actual plaintext password!
default ""
--allow-private-cidrs: false#
default ""
--api-addr#
default :1633
The IP and port the API will serve HTTP requests from. Omitting the IP part of the address will cause the server to listen to all interfaces. Argument values are of the form '132.132.132.132:1633'.
--block-time#
default 15
The expected block time of the attached SWAP endpoint.
--block-hash#
default ""
The block hash of the block whose parent is the block that contains the transaction hash
--bootnode#
default /dnsaddr/bootnode.ethswarm.org
This is a multiaddr specifying the Bee bootnodes used for bootstrapping the network. It can be multiple values.
By default a node connects to the Swarm mainnet. When using a private or test network, network specific bootnodes must be set.
Any Bee node in a network can act as a bootnode.
--bootnode-mode#
default false
Cause the node to always accept incoming connections
--cache-capacity#
default 1000000
The amount of disk space, in chunks, that is used for forwarding and uploading chunks.
--cache-retrieval#
default true
Enable the caching of forwarded content.
--chain-enable#
default true
Use a blockchain backend, and hence participate in protocols requiring one.
--chequebook-enable#
default true
Enable chequebook.
--clef-signer-enable#
default false
Set this to true to enable signing using Ethereum's Clef external signer. Clef is a new feature which requires a corresponding rules files or running in advanced mode to allow for auto-signing of handshakes and cheques.
--clef-signer-endpoint#
default default path for clef for each host operating system
You may also specify a custom IPC file path for your Clef signer.
--clef-signer-ethereum-address#
default selects the clef address at index 0
Use this command to specify which Bee Clef address is used if you have imported multiple keys into Bee Clef.
warning
If you have multiple addresses imported into your instance of Bee Clef, you must specify your address for each node, including the first one, as addresses may been re-ordered during import.
--cors-allowed-origins#
default []
HTTP/WS origin domains or wildcards defining these, which the API will allow responses to, e.g.
--data-dir#
default /home/<user>/.bee
The location on your disk where Bee stores its data. Data in this directory will be required to restore a node state using the same key.
This consists of the following three types of data.
1. Chunk Data (localstore)#
This consists of chunks and files that you have pinned locally, cached chunks you have requested, or chunks within your radius of responsibility which you are responsible for serving to your peers.
2. State Data (statestore)#
This is information about the local state of your Bee node and should be backed up.
3. Keystore Data (keys)#
These files contain encrypted versions of your private key and should be backed up and kept private.
danger
Keep the key files in your keystore data directory safe!
They are the cryptographic proof of your network identity and cannot be recovered.
The next four options expose low-level configurations for LevelDB's  Openfile method. Please let us know how you get on with tweaking these settings on your hardware in the #node-operators channel on our Discord server
--db-block-cache-capacity#
default 33554432
Corresponds to LevelDB BlockCacheCapacity (see above)
--db-disable-seeks-compaction#
default false
Corresponds to LevelDB DisableSeeksCompaction (see above)
--db-open-files-limit#
default 200
info
To accomodate less powerful hardware and operating systems, the db-open-files-limit is set deliberately low. We recommend that you try to increase it to nearer to 10000 or more if this is possible when using your hardware. Please let us know how you get on with tweaking these settings on your hardware in the #node-operators channel on our Discord server
Corresponds to LevelDB OpenFilesCacheCapacity (see above)
--db-write-buffer-size#
default 33554432
Corresponds to LevelDB WriteBuffer (see above)
--debug-api-addr#
default :1635
The IP and port the Debug API will serve HTTP requests from.
Omitting the IP part of the address will cause the server to listen to all requests.
--debug-api-enable must be set to true.
--debug-api-enable#
default false
Set this to true to enable access to the Debug API
--full-node#
default false
Enable this by setting it to true to fully participate in serving and forwarding chunks to the network.
--gateway-mode#
default false
Set this to true to disable a set of sensitive features in the API
to ensure that it is safe to expose your api-addr to the public
Internet.
--global-pinning-enable#
default false
Enables the Global Pinning functionality when set to true.
--mainnet#
default false
Set to true to connect to Swarm mainnet.
--nat-addr#
default ""
Sets the expected public IP. Normally this is generated automatically, but in certain circumstances it may be desirable to set it manually.
Format is 123.123.123.123:1634 where the port number is your Bee p2p port.
--network-id#
default 1 if --mainnet=true
default 10 if --mainnet=false
The network ID for which to accept new connections. Set to 1 for mainnet, 10 for testnet.
--p2p-addr#
default :1634
The IP and port to listen for p2p protocol messages.
--p2p-ws-enable#
default false
Enables web-sockets transport for p2p communications.
--password#
default ""
Password used to decrypt Swarm identity keys.
danger
Passing passwords as command line arguments is insecure. Use a password file or environment variable in production environments.
--password-file#
default ""
The path to a file that contains password for decrypting keys. The empty string assumes no file is presented.
--payment-early-percent#
default 50
Percentage below the peers payment threshold when we initiate settlement.
--payment-threshold#
default 100000000
The threshold in BZZ where you expect to get paid from your peers.
--payment-tolerance-percent#
default 25
Excess debt above payment threshold as a percentage where you disconnect from your peer (default 25).
--postage-stamp-address#
default automatically configured depending on network
The address of the postage stamp contract on the Ethereum blockchain, used for buying batches of stamps.
--resolver-options#
default eth:0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e@localhost:8545
ENS API endpoint for a TLD, with contract address. Multiple values can be provided.
Settings should be provided in the format [tld:][contract-addr@]url
A default top level domain and resolver contract address are provided, but an ENS/Geth endpoint must be provided to enable this functionality.
--restricted#
default false
Enable permission check on the http APIs.
You should also specify admin password using the --admin-password option.
To generate a valid admin password use the provided bcrypt utility
--resync#
default false
Forces the node to resync postage contract data.
--static-nodes#
default []
Protect nodes from getting kicked out on bootnode
--swap-deployment-gas-price#
default determined automatically
Gas price in wei to use for deployment and funding
--swap-enable#
default true
--swap-endpoint#
default ws://localhost:8546
SWAP Gnosis Chain (mainnet) or Goerli (testnet) blockchain endpoint.
--swap-factory-address#
default anointed contract for the current blockchain id
--swap-initial-deposit#
default 10000000000000000
--token-encryption-key#
default
Admin username to get the security token.
--tracing-enable#
default false
Send tracing spans to the tracing service. More information how to configure and visualize tracing data is available here.
--tracing-endpoint#
default 127.0.0.1:6831
The URL where the tracing service listens for Thrift protocol UDP messages.
--tracing-host#
default ""
Host to send tracing data.
--tracing-port#
default ""
Port to send tracing data.
--tracing-service-name#
default bee
Bee service identifier in tracing spans.
--transaction#
default ""
As a spam prevention measure, for nodes which deployed their
chequebook with v0.5.0 or before, specify transaction - the
transaction hash of any Ethereum transaction on the XDAI
network
sent from the Bee node's Ethereum address.
--verbosity#
default info
0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=trace
--warmup-time#
default 20m0s
Time to warmup the node before pull/push protocols can be kicked off.
--welcome-message#
default ""
Custom welcome message to be displayed to peers on succesful connection.