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 Changesimportant
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 PriorityConfiguration is processed in the following ascending order of preference:
- Command Line Arguments
- Environment Variables
- Configuration File
#
Command Line ArgumentsRun bee start --help
in your Terminal to get the list of available command line arguments.
#
Environment variablesBee 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 fileBee can also be configured by providing a YAML configuration file using the --config
flag.
#
Automatically generate a config fileConfiguration 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 ManagerBee 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 OptionsBee provides the following options to customise your node.
#
Global#
--configdefault /home/<user>/.bee.yaml
The location of a YAML configuration file containing configuration options. See configuration.
#
Start#
--admin-passwordWhen 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: falsedefault ""
#
--api-addrdefault :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-timedefault 15
The expected block time of the attached SWAP endpoint.
#
--block-hashdefault ""
The block hash of the block whose parent is the block that contains the transaction hash
#
--bootnodedefault /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-modedefault false
Cause the node to always accept incoming connections
#
--cache-capacitydefault 1000000
The amount of disk space, in chunks, that is used for forwarding and uploading chunks.
#
--cache-retrievaldefault true
Enable the caching of forwarded content.
#
--chain-enabledefault true
Use a blockchain backend, and hence participate in protocols requiring one.
#
--chequebook-enabledefault true
Enable chequebook.
#
--clef-signer-enabledefault 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-endpointdefault 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-addressdefault 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-originsdefault []
HTTP/WS origin domains or wildcards defining these, which the API will allow responses to, e.g.
#
--data-dirdefault /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-capacitydefault 33554432
Corresponds to LevelDB BlockCacheCapacity
(see above)
#
--db-disable-seeks-compactiondefault false
Corresponds to LevelDB DisableSeeksCompaction
(see above)
#
--db-open-files-limitdefault 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-sizedefault 33554432
Corresponds to LevelDB WriteBuffer
(see above)
#
--debug-api-addrdefault :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-enabledefault false
Set this to true
to enable access to the Debug API
#
--full-nodedefault false
Enable this by setting it to true
to fully participate in serving and forwarding chunks to the network.
#
--gateway-modedefault 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-enabledefault false
Enables the Global Pinning functionality when set to true
.
#
--mainnetdefault false
Set to true to connect to Swarm mainnet.
#
--nat-addrdefault ""
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-iddefault 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-addrdefault :1634
The IP and port to listen for p2p protocol messages.
#
--p2p-ws-enabledefault false
Enables web-sockets transport for p2p communications.
#
--passworddefault ""
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-filedefault ""
The path to a file that contains password for decrypting keys. The empty string assumes no file is presented.
#
--payment-early-percentdefault 50
Percentage below the peers payment threshold when we initiate settlement.
#
--payment-thresholddefault 100000000
The threshold in BZZ where you expect to get paid from your peers.
#
--payment-tolerance-percentdefault 25
Excess debt above payment threshold as a percentage where you disconnect from your peer (default 25).
#
--postage-stamp-addressdefault automatically configured depending on network
The address of the postage stamp contract on the Ethereum blockchain, used for buying batches of stamps.
#
--resolver-optionsdefault 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.
#
--restricteddefault 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
#
--resyncdefault false
Forces the node to resync postage contract data.
#
--static-nodesdefault []
Protect nodes from getting kicked out on bootnode
#
--swap-deployment-gas-pricedefault determined automatically
Gas price in wei to use for deployment and funding
#
--swap-enabledefault true
#
--swap-endpointdefault ws://localhost:8546
SWAP Gnosis Chain (mainnet) or Goerli (testnet) blockchain endpoint.
#
--swap-factory-addressdefault anointed contract for the current blockchain id
#
--swap-initial-depositdefault 10000000000000000
#
--token-encryption-keydefault
Admin username to get the security token.
#
--tracing-enabledefault false
Send tracing spans to the tracing service. More information how to configure and visualize tracing data is available here.
#
--tracing-endpointdefault 127.0.0.1:6831
The URL where the tracing service listens for Thrift protocol UDP messages.
#
--tracing-hostdefault ""
Host to send tracing data.
#
--tracing-portdefault ""
Port to send tracing data.
#
--tracing-service-namedefault bee
Bee service identifier in tracing spans.
#
--transactiondefault ""
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.
#
--verbositydefault info
0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=trace
#
--warmup-timedefault 20m0s
Time to warmup the node before pull/push protocols can be kicked off.
#
--welcome-messagedefault ""
Custom welcome message to be displayed to peers on succesful connection.