Skip to content

Configuration Basics

Learn about the Bondy runtime configuration, the Bondy configuration file, its syntax, variable replacement and the required OS-specific configuration.

The complete behaviour of Bondy is defined by the combination of 3 types of "configuration" data:

  1. Bondy node runtime configuration, which controls things like network listeners, availability of optional services, security defaults, clustering and load regulation. This is mostly static configuration done by modifying the bondy.conf file and a set of environment variables.
  2. Multi-tenancy security configuration, which controls the definition of realms and its security including user identities, authentication and authorizacion policies, Same Sign-on and Single Sign-on. This is done dynamically by via the Admin API. However, it can also be configured via the bondy.conf file.
  3. RPC and Pub/Sub configuration, a.k.a Control Plane, which defines the available RPC procedures–their invocation policies e.g. load balancing–and PubSub subscriptions and their respective routing information. This is dynamic configured by clients and maintained in the Registry via WAMP.

The following diagram shows the scopes and mechanism for managing each configuration type:

Documentation Scope

This reference documentation covers only the Bondy node runtime configuration using environment variables and the bondy.conf file.

To learn more about Multi-tenancy security configuration check the WAMP and HTTP references.

As opposed to other application networking options i.e. Service Mesh, in which services are configured using a proprietary API e.g. Istio APIs and YAML for Kubernetes resources, Bondy RPC and Pub/Sub configuration is entirely managed by WAMP.

Bondy environment variables

Bondy will use the following environment variables to configure the node identity and the paths it uses to store data.

Variable NameDescriptionDefault
BONDY_ERL_NODENAMEName of the Bondy node.bondy
BONDY_ERL_DISTRIBUTED_COOKIEErlang distribute cookie to be used to connect a remote shell to a Bondy nodebondy
BONDY_ETC_DIRThe directory where the bondy.conf will be located. The host should Bondy executable to READ and WRITE files on this directorySee File Location section below
BONDY_DATA_DIRThe directory where Bondy will store its embedded database. Check the relevant requirements in the Operating System Configuration section below./data
BONDY_LOG_DIRThe directory where Bondy will write any defined logs./log
BONDY_TMP_DIRThe directly where Bondy will store any temporary data./tmp


In previous version of Bondy these options where configured using the bondy.conf file but that introduced certain issues with the configuration system.

The Bondy configuration file

Bondy configuration file, named bondy.conf, is used to set a wide variety of node runtime configuration options.

During node startup, Bondy will check the existence of the file, parse it and validate its contents. In case of a syntax or validation error, Bondy will stop printing the reason to standard output.

If a configuration file is not found at the expected location, Bondy will create one using default values.

Cluster deplopyment

When deploying a Bondy cluster it is vital that the same bondy.conf file is used with all nodes.

File Location

The default file location depends on the installation method you've used as shown in the following table.

Installation methodDefault Location
Source tarball/etc/bondy.conf
Official Docker image/bondy/etc/bondy.conf

The location can be overridden using the BONDY_ETC_DIR environment variable.

File Syntax

The file uses a sysctl-like syntax that looks like this:

# comment
key = value

Note that blank lines are ignored, and whitespace before and after a key or value is ignored, although a value can contain whitespace within. Lines which begin with a # are considered comments and ignored.

The documentation for each key defines the acceptable datatype and format for each value and the default value (if any).

Value Datatypes

The following are the set of acceptable datatypes used in the documentation.

string()Any string. Although each token might add specific formatting rules via the documentation100
integer()An integer100
bytesize()Work pretty much like duration but with three differences.
The units are MB, KB and GB
If not unit is specified, the value defaults to bytes
You can only use one unit.
Lowercase units (i.e. gb, mb, and kb) are ok, but mixed case are not. That's to avoid confusion with Megabits
flag()Equivalent to a boolean valueon | off
time_duration_units()Durations are fixed intervals of time, the largest unit of which will be a one week. Anything larger will have to be expressed in terms of weeks, since larger units (month, year) are of variable duration. The following units are supported:
- f: fortnight
- w: week
- d: day
- h: hour
- m: minute
- s: second
- ms: millisecond
You can use any combination of these.
ip()The IP datatype exists currently as an IP/Port combo127.0.0.1:8098
path()file and directory are effectively strings. In the future they could allow for included validators like valid path and exists. Some files may need to exist, some may not. some may need to be writable.$(platform_etc_dir)/


nodename = bondy@
distributed_cookie = bondy
security.allow_anonymous_user = off

Default values

For every option not provided by your configuration, Bondy might define a default value (check the default value for each key in each Configuration Reference section).

How options and their defaults are documented

Take the following snippet of the Node section as an example.

nodename  :: string
Default = 'bondy@'Since v0.1.0

It defines the token nodename which takes a string value and defaults to bondy@ Notice the documentation will further specify which strings are acceptable.


Start a Bondy node without providing a configuration file and inspect the one generated by Bondy once the node has started. Bondy would have created the file using the default values. You can copy this file and use it as template to make your modifications.

When you are done copy your modified file to the expected location and start Bondy again.

Variable Substitution

Within the bondy.conf file you can use the following variables which Bondy will substitute before running.

  • platform_etc_dir

The following is an example of how to use variable substitution.

broker_bridge.config_file = $(platform_etc_dir)/bb_conf.json

User environment variable substitution

If you want to use environment variables in the bondy.conf you have to rename the file to bondy.conf.template.

During startup, Bondy considers all files with suffix .template for OS variable substitution and if successful results in a new file of the same name stripped of the .template suffix and where all environment variables have been replaced.

The syntax for environment variables is ${VAR_NAME}.

Notice the BONDY_* variables mentioned above will always be used by Bondy.


nodename = ${BONDY_NODENAME}
distributed_cookie = bondy
security.allow_anonymous_user = off
security.config_file = ${BONDY_SECURITY_CONF_FILE}

Operating System Configuration

Configuring Open File Limits

Bondy can accumulate a large number of open file handles during operation. The creation of numerous data files is normal, and the storage backend performs periodic merges of data file collections to avoid accumulating file handles.

To accommodate this you should increase the open files limit on your system.


We recommend setting a soft limit of 65536 and a hard limit of 200000.

Temporary changing Open File Limits

Most operating systems can check and change the open-files limit for the current shell session using the ulimit command.

Start by checking the current open file limit values with:

ulimit -Hn # Hard limit
ulimit -Sn # Soft limit

Set the limit by using:

ulimit -n 200000


The above configuration persists only for the duration of your shell session. To make the change permanent read the following section.

Permanently changing Open File Limits

To change the limit on a system-wide, permanent basis read the following sections.

Except where otherwise noted, content on this site is licensed under a Creative Commons Attribution-ShareAlike (CC-BY-SA) 4.0 International license.
Bondy and Leapsight are registered trademarks of Leapsight Technologies Ltd.