Configuration

Your Bee node can be configured by adding arguments terminal command on startup.

Run bee start --help in your Terminal to get the list of available command line arguments.

Example

In this example, we change the port that the Bee API runs on, enable the Debug API, and set it to listen on port 6666.

bee start \
--api-addr=:8888 \
--debug-api-enable=true \
--debug-api-addr=:6666

Configuration file

Bee can also be configured by providing a yaml configuration file using the --config flag.

bee start --config /home/<user>/bee-config.yaml
tip

Run bee printconfig &> bee-default.yaml to print a default version of the configuration file.

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 node using systemctl.

Linux

sudo vi /etc/bee/bee.yaml
sudo systemctl restart bee

MacOS

vi /usr/local/etc/swarm-bee/bee.yaml
brew services restart swarm-bee

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.

Example

Here we substitute start for printconfig when specifying arguments at the command line.

bee printconfig \
--verbosity=5 \
&> bee-config.yaml

This produces the following file contents, showing the default configuration of Bee, with some added log verbosity:

api-addr: :1633
bootnode:
- /dnsaddr/bootnode.ethswarm.org
clef-signer-enable: false
clef-signer-endpoint: ""
cors-allowed-origins: []
data-dir: /Users/sig/.bee
db-capacity: "5000000"
debug-api-addr: :1635
debug-api-enable: false
gateway-mode: false
global-pinning-enable: false
nat-addr: ""
network-id: "1"
p2p-addr: :1634
p2p-quic-enable: false
p2p-ws-enable: false
password: ""
password-file: ""
payment-early: "10000"
payment-threshold: "100000"
payment-tolerance: "10000"
resolver-options: []
standalone: false
swap-enable: true
swap-endpoint: http://localhost:8545
swap-factory-address: ""
swap-initial-deposit: "100000000"
tracing-enable: false
tracing-endpoint: 127.0.0.1:6831
tracing-service-name: bee
verbosity: info
welcome-message: ""

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 instructions. See configuration.

Start

--api-addr

default :1633

The ip and port the API will serve http requests from. Ommiting 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'.

--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.

--clef-signer-enable

default false

Set this to true to enable signing using Ethereum's 'Clef' external signer. Clef is an 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.

--cors-allowed-origins

default []

Http/WS origin domains or wildcards defining these, which the API will allow responses to, e.g.

bee start --cors-allowed-origins="*"
bee start --cors-allowed-origins="https://website.ethswarm.org"

--data-dir

default /home/<user>/.bee

The location on your disk where Bee stores it's data. This consists of the following three types of data.

Data in this directory will be required to restore a node state using the same key.

1. Chunk Data

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

This is information about the local state of your Bee node and should be backed up.

3. Keystore Data

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.

--db-capacity

default 5000000

Chunk database capacity in chunks. A chunk is 4096 bytes in size, so the total database capacity in kb can be estimated as db-capacity * 4096. The default 5,000,000 chunks is therefore approximately 20.5gb. We recommend a minimum of 2.5gb capacity for a node to be able to effectively function in the network. Light nodes that do not participate in storing may be able to specify less.

--debug-api-addr

default :1635

The IP and port the Debug API will serve http requests from.

Ommiting 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

--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.

--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.

--network-id

default 1

The network ID for which to accept new connections. Set to 1 for mainnet, 2 for testnet.

--p2p-addr

default :1634

The ip and port to listen for p2p protocol messages.

--p2p-quic-enable

default false

--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

Amount in BZZ below the peers payment threshold which causes Bee to initiate settlement (default 10000)

--payment-threshold

default 100000

The threshold in BZZ where you expect to get paid from your peers.

--payment-tolerance

default 10000

The excess debt above payment threshold in BZZ where you disconnect from your peer.

--resolver-options

default eth:0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e

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.

--standalone

default false

Set this flag if we would like the node not to try to connect to the network. Useful for development.

--swap-enable

default true

--swap-endpoint

default http://localhost:8545

SWAP ethereum blockchain endpoint.

--swap-factory-address

default anointed contract for the current blockchain id

--swap-initial-deposit

default 100000000

--tracing-enable

default false

Send tracing spans to the tracing service. More information how to configure and visualize tracing data is available on /docs/bee-developers/useful-dev-info#tracing.

--tracing-endpoint

default 127.0.0.1:6831

The URL where the tracing service listens for Thrift protocol UDP messages.

--tracing-service-name

default bee

Bee service identifier in tracing spans.

--verbosity

default info

0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=trace

--welcome-message

default ""

Custom welcome message to be displayed to peers on succesful connection.

Environment variables

Bee config may also be passed using environment variables.

Environment variables are set as variables in your operating systems session or systemd configuration file. To set an environment variable, type the following in your terminal session.

export VARIABLE_NAME=variableValue

Verify if it is correctly set by running echo $VARIABLE_NAME.

All available configuration options are also available as prefixed, captilised and underscored environment variables.

e.g. --api-addr becomes BEE_API_ADDR.

Precedence Order of Configuration

Configuration is processed in the following ascending priority order of preference:

  1. Command Line Variables
  2. Environment Variables
  3. Configuration File