Skip to main content

Configuration

Configuration Methods and Priority​

There are three configuration methods, each with a different priority level. Configuration is processed in the following ascending order of preference:

  1. Command Line Flags
  2. Environment Variables
  3. YAML Configuration File
info

All three methods may be used when running Bee using bee start.

However when Bee is started as a service with tools like systemctl or brew services, only the YAML configuration file is supported by default.

Command Line Arguments​

Run bee start --help in your terminal to list the available command-line arguments:

Start a Swarm node

Usage:
  bee start [flags]

Flags:
      --allow-private-cidrs                      allow to advertise private CIDRs to the public network
      --api-addr string                          HTTP API listen address (default "127.0.0.1:1633")
      --block-time uint                          chain block time (default 15)
      --blockchain-rpc-endpoint string           rpc blockchain endpoint
      --bootnode strings                         initial nodes to connect to
      --bootnode-mode                            cause the node to always accept incoming connections
      --cache-capacity uint                      cache capacity in chunks, multiply by 4096 to get approximate capacity in bytes (default 1000000)
      --cache-retrieval                          enable forwarded content caching (default true)
      --chequebook-enable                        enable chequebook (default true)
      --cors-allowed-origins strings             origins with CORS headers enabled
      --data-dir string                          data directory (default "/home/noah/.bee")
      --db-block-cache-capacity uint             size of block cache of the database in bytes (default 33554432)
      --db-disable-seeks-compaction              disables db compactions triggered by seeks (default true)
      --db-open-files-limit uint                 number of open files allowed by database (default 200)
      --db-write-buffer-size uint                size of the database write buffer in bytes (default 33554432)
      --full-node                                cause the node to start in full mode
  -h, --help                                     help for start
      --mainnet                                  triggers connect to main net bootnodes. (default true)
      --nat-addr string                          NAT exposed address
      --neighborhood-suggester string            suggester for target neighborhood (default "https://api.swarmscan.io/v1/network/neighborhoods/suggestion")
      --network-id uint                          ID of the Swarm network (default 1)
      --p2p-addr string                          P2P listen address (default ":1634")
      --p2p-ws-enable                            enable P2P WebSocket transport
      --password string                          password for decrypting keys
      --password-file string                     path to a file that contains password for decrypting keys
      --payment-early-percent int                percentage below the peers payment threshold when we initiate settlement (default 50)
      --payment-threshold string                 threshold in BZZ where you expect to get paid from your peers (default "13500000")
      --payment-tolerance-percent int            excess debt above payment threshold in percentages where you disconnect from your peer (default 25)
      --postage-stamp-address string             postage stamp contract address
      --postage-stamp-start-block uint           postage stamp contract start block number
      --pprof-mutex                              enable pprof mutex profile
      --pprof-profile                            enable pprof block profile
      --price-oracle-address string              price oracle contract address
      --redistribution-address string            redistribution contract address
      --resolver-options strings                 ENS compatible API endpoint for a TLD and with contract address, can be repeated, format [tld:][contract-addr@]url
      --resync                                   forces the node to resync postage contract data
      --staking-address string                   staking contract address
      --statestore-cache-capacity uint           lru memory caching capacity in number of statestore entries (default 100000)
      --static-nodes strings                     protect nodes from getting kicked out on bootnode
      --storage-incentives-enable                enable storage incentives feature (default true)
      --swap-deployment-gas-price string         gas price in wei to use for deployment and funding
      --swap-enable                              enable swap
      --swap-endpoint string                     swap blockchain endpoint
      --swap-factory-address string              swap factory addresses
      --swap-initial-deposit string              initial deposit if deploying a new chequebook (default "0")
      --target-neighborhood string               neighborhood to target in binary format (ex: 111111001) for mining the initial overlay
      --token-encryption-key string              admin username to get the security token
      --tracing-enable                           enable tracing
      --tracing-endpoint string                  endpoint to send tracing data (default "127.0.0.1:6831")
      --tracing-host string                      host to send tracing data
      --tracing-port string                      port to send tracing data
      --tracing-service-name string              service name identifier for tracing (default "bee")
      --use-postage-snapshot                     bootstrap node using postage snapshot from the network
      --verbosity string                         log verbosity level 0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=trace (default "info")
      --warmup-time duration                     time to warmup the node before some major protocols can be kicked off (default 5m0s)
      --welcome-message string                   send a welcome message string during handshakes
      --withdrawal-addresses-whitelist strings   withdrawal target addresses

Global Flags:
      --config string   config file (default is $HOME/.bee.yaml)

Environment variables​

Bee configuration can also be set 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.

export VARIABLE_NAME=variableValue

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

YAML configuration file​

You can view the default contents of the bee.yaml configuration file using the bee printconfig command:

bee printconfig
# allow to advertise private CIDRs to the public network
allow-private-cidrs: false
# HTTP API listen address
api-addr: 127.0.0.1:1633
# chain block time
block-time: "15"
# rpc blockchain endpoint
blockchain-rpc-endpoint: ""
# initial nodes to connect to
bootnode: []
# cause the node to always accept incoming connections
bootnode-mode: false
# cache capacity in chunks, multiply by 4096 to get approximate capacity in bytes
cache-capacity: "1000000"
# enable forwarded content caching
cache-retrieval: true
# enable chequebook
chequebook-enable: true
# config file (default is $HOME/.bee.yaml)
config: /root/.bee.yaml
# origins with CORS headers enabled
cors-allowed-origins: []
# data directory
data-dir: /root/.bee
# size of block cache of the database in bytes
db-block-cache-capacity: "33554432"
# disables db compactions triggered by seeks
db-disable-seeks-compaction: true
# number of open files allowed by database
db-open-files-limit: "200"
# size of the database write buffer in bytes
db-write-buffer-size: "33554432"
# cause the node to start in full mode
full-node: false
# help for printconfig
help: false
# triggers connect to main net bootnodes.
mainnet: true
# NAT exposed address
nat-addr: ""
# suggester for target neighborhood
neighborhood-suggester: https://api.swarmscan.io/v1/network/neighborhoods/suggestion
# ID of the Swarm network
network-id: "1"
# P2P listen address
p2p-addr: :1634
# enable P2P WebSocket transport
p2p-ws-enable: false
# password for decrypting keys
password: ""
# path to a file that contains password for decrypting keys
password-file: ""
# percentage below the peers payment threshold when we initiate settlement
payment-early-percent: 50
# threshold in BZZ where you expect to get paid from your peers
payment-threshold: "13500000"
# excess debt above payment threshold in percentages where you disconnect from your peer
payment-tolerance-percent: 25
# postage stamp contract address
postage-stamp-address: ""
# postage stamp contract start block number
postage-stamp-start-block: "0"
# enable pprof mutex profile
pprof-mutex: false
# enable pprof block profile
pprof-profile: false
# price oracle contract address
price-oracle-address: ""
# redistribution contract address
redistribution-address: ""
# ENS compatible API endpoint for a TLD and with contract address, can be repeated, format [tld:][contract-addr@]url
resolver-options: []
# forces the node to resync postage contract data
resync: false
# staking contract address
staking-address: ""
# lru memory caching capacity in number of statestore entries
statestore-cache-capacity: "100000"
# protect nodes from getting kicked out on bootnode
static-nodes: []
# enable storage incentives feature
storage-incentives-enable: true
# gas price in wei to use for deployment and funding
swap-deployment-gas-price: ""
# enable swap
swap-enable: false
# swap blockchain endpoint
swap-endpoint: ""
# swap factory addresses
swap-factory-address: ""
# initial deposit if deploying a new chequebook
swap-initial-deposit: "0"
# neighborhood to target in binary format (ex: 111111001) for mining the initial overlay
target-neighborhood: ""
# enable tracing
tracing-enable: false
# endpoint to send tracing data
tracing-endpoint: 127.0.0.1:6831
# host to send tracing data
tracing-host: ""
# port to send tracing data
tracing-port: ""
# service name identifier for tracing
tracing-service-name: bee
# bootstrap node using postage snapshot from the network
use-postage-snapshot: false
# log verbosity level 0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=trace
verbosity: info
# time to warmup the node before some major protocols can be kicked off
warmup-time: 5m0s
# send a welcome message string during handshakes
welcome-message: ""
# withdrawal target addresses
withdrawal-addresses-whitelist: []
info

Note that depending on whether Bee is started directly with the bee start command or started as a service with systemctl / brew services, the default directory for the YAML configuration file (shown in the config option above) will be different.

To change your node's configuration, simply edit the YAML file and restart Bee:

Open the config file for editing:

sudo vi /etc/bee/bee.yaml

After saving your changes, restart your node:

sudo systemctl restart bee

Manually generating YAML config file for bee start​

No YAML file is generated during installation when using the shell script install method, so you must generate one if you wish to use a YAML file to specify your configuration options. To do this you can use the bee printconfig command to print out a set of default options and save it to a new file in the default location:

bee printconfig &> $HOME/.bee.yaml
info

Note that bee printconfig prints the default configuration for your node, not the current configuration including any changes.

When using bee.yaml with the bee start command, make sure to use the --config flag to specify the location of your configuration file.

Node Types​

There are three node types which each offer varying levels of functionality - full, light, and ultra-light. You can configure your node to run as any of these three types by setting the related options within your configuration.

For a deeper dive into each node type and its features and limitations, refer to the Node Types page.

How to Set Node Type​

There are three relevant options which are used to set your node type: full-node, swap-enable, and blockchain-rpc-endpoint. The required option values for each node type are outlined below:

Node Typefull-nodeswap-enableblockchain-rpc-endpointFunctionality
Full NodetruetrueRequiredFull functionality, including uploads, downloads, and Swarm network participation.
Light NodefalsetrueRequiredSupports uploading and downloading only.
Ultra-Light NodefalsefalseNot requiredFree-tier downloads only.

Configuration Examples​

Bee nodes can be configured using command-line flags, environment variables, or a YAML configuration file:

Full Node Configuration​

Using Command-Line Arguments​

bee start \
  --password mypassword \
  --full-node \
  --swap-enable \
  --blockchain-rpc-endpoint https://xdai.fairdatasociety.org

Using Environment Variables​

export BEE_PASSWORD="mypassword"
export BEE_FULL_NODE="true"
export BEE_SWAP_ENABLE="true"
export BEE_BLOCKCHAIN_RPC_ENDPOINT="https://xdai.fairdatasociety.org"
bee start

Using YAML Configuration​

password: mypassword
full-node: true
swap-enable: true
blockchain-rpc-endpoint: "https://xdai.fairdatasociety.org"

Default Data and Config Directories​

Depending on the operating system and startup method used, the default directories for your node will differ:

Bee Service Default Directories (Package Manager Install)​

When installed using a package manager, Bee is set up to run as a service with default data and configuration directories set up automatically during the installation. The examples below include default directories for Linux and macOS. You can find the complete details of default directories for different operating systems in the bee.yaml files included in the packaging folder of the Bee repo.

The default data folder and config file locations:

data-dir: /var/lib/bee
config: /etc/bee/bee.yaml

Shell Script Install Default Directories​

For all operating systems, the default data and config directories for the bee start startup method can be found using the bee printconfig command:

This will print out a complete default Bee node configuration file to the terminal, the config and data-dir values show the default directories for your system:

config: /root/.bee.yaml
data-dir: /root/.bee
info

The default directories for your system may differ from the example above, so make sure to run the bee printconfig command to view the default directories for your system.

Create Password​

A password is required for all modes, and can either be set directly in text through the password configuration option or alternatively a file can be used by setting the password-file option to the path where your password file is located.

Setting Blockchain RPC endpoint​

Full and light Bee nodes require a Gnosis Chain RPC endpoint so they can interact with and deploy their chequebook contract, see the latest view of the current postage stamp batches, and interact with and top-up postage stamp batches. A blockchain RPC endpoint is not required for nodes running in ultra-light mode. We recommend you run your own Gnosis Chain node if you are planning to run a full node, and especially if you plan to run a hive of nodes. If you do not wish to run your own Gnosis Chain node and are willing to trust a third party, you may also consider using an RPC endpoint provider such as GetBlock. For running a light node or for testing out a single full node you may also consider using one of the free public RPC endpoints listed in the Gnosis Chain documentation. However, these endpoint providers offer no SLA or availability guarantees and are therefore not recommended for full node operators. To set your RPC endpoint provider, specify it with the blockchain-rpc-endpoint value, which is set to an empty string by default.

## bee.yaml
blockchain-rpc-endpoint: https://rpc.gnosis.gateway.fm
info

The gateway.fm RPC endpoint in the example is great for learning how to set up Bee, but for the sake of security and reliability it's recommended that you run your run your own Gnosis Chain node rather than relying on a third party provider.

Configuring Swap Initial Deposit (Optional)​

When running your Bee node with SWAP enabled for the first time, your node will deploy a 'chequebook' contract using the canonical factory contract which is deployed by Swarm. Once the chequebook is deployed, Bee will (optionally) deposit a certain amount of xBZZ in the chequebook contract so that it can pay other nodes in return for their services. The amount of xBZZ transferred to the chequebook is set by the swap-initial-deposit configuration setting (it may be left at the default value of zero or commented out).

NAT address​

Swarm is all about sharing and storing chunks of data. To enable other Bees (also known as peers) to connect to your Bee, you must broadcast your public IP address in order to ensure that Bee is reachable on the correct p2p port (default 1634). We recommend that you manually configure your external IP and check connectivity to ensure your Bee is able to receive connections from other peers.

First, determine your public IP address:

curl icanhazip.com
123.123.123.123

Then configure your node, including your p2p port (default 1634).

## bee.yaml
nat-addr: "123.123.123.123:1634"

ENS Resolution (Optional)​

The ENS domain resolution system is used to host websites on Bee, and in order to use this your Bee must be connected to a mainnet Ethereum blockchain node. We recommend you run your own ethereum node. An option for resource restricted devices is geth+nimbus and a guide can be found here. Other options include dappnode, nicenode, stereum and avado.

If you do not wish to run your own Ethereum node, you may use a blockchain RPC service provider such as Infura. After signing up for Infura, simply set your --resolver-options to https://mainnet.infura.io/v3/your-api-key.

## bee.yaml
resolver-options: ["https://mainnet.infura.io/v3/<<your-api-key>>"]

Sepolia Testnet Configuration​

In order to operate a Bee node on the Sepolia testnet, you need to change mainnet to false, and provide a valid Sepolia testnet RPC endpoint through the blockchain-rpc-endpoint option.

Here is an example of a full configuration for a testnet full node:

data-dir: /home/username/bee/sepolia # Specified an alternate "data-dir" for our testnet node data
full-node: true
mainnet: false # Changed to "false"
password: password
blockchain-rpc-endpoint: wss://sepolia.infura.io/ws/v3/<API-KEY> # Replaced the Gnosis Chain RPC with a Sepolia testnet RPC endpoint
swap-enable: true
verbosity: 5
welcome-message: "welcome-from-the-hive"
warmup-time: 30s

Funding Testnet Node​

Make sure to fund your node with Sepolia ETH rather than xDAI to pay for gas on the Sepolia testnet. There are many public faucets you can use to obtain Sepolia ETH, such as this one from Infura.

To get Sepolia BZZ (sBZZ) you can use this Uniswap market, just make sure that you've switched to the Sepolia network in your browser wallet.