rbridge.conf Reference

rbridge.conf is the RBridge configuration file. Its default path is /etc/rbridge.conf, but it may sit everywhere else using the -c command line option.

When RBridge starts, rbridge.conf is generally parsed at the very beginning and all the internal parameter settings are set up accordingly.

Whitespace (blanks, tabs and newlines) are generally ignored.

Comments may be included with a “#”, any text starting with “#” until the end of the line is ignored.

A parameter setting has the syntax “ = ” contained in one single line.

A value may include blanks when it is specified in double quotes.

serial

The parameter serial holds the serial number of a license that has been purchased. This parameter works closely together with the parameter lickey and the nodeid of the RBridge running in bridging mode.

Example

serial= ACME190226

lickey

The parameter lickey is a license key that authorises the license to be valid for the nodeid of the RBridge node. Technically, it’s just a MD5 hash using several parameters as its input.

Licensing applies only if an RBridge is running in bridging mode (connecting an Ethernet segment / LAN to a peer RBridge).

An RBridge in bridging mode and with no or invalid licensing parameters runs in trial mode for 30 days after installation and requires a restart after 3600 seconds runtime (one hour).

The configuration parameter interface controls if an RBridge runs in bridging mode or as a registry (see below).

Example

serial= ACME190226
lickey= c90219951a3551c28bae99d866621c9f

RBridge CLI example on an RBridge in bridging mode with active licensing:

$ sudo rbridge control
RBridge: connected to PID 78792
RBridge> license
 valid license (serial=ACME190226)
RBridge>

RBridge CLI example on an RBridge in bridging mode with testing license:

$ sudo rbridge control
RBridge: connected to PID 78801
RBridge> license
 30 day testing period running, 27 days and 3 hours remaining
 this RBridge endpoint will terminate in 3597 seconds
RBridge>

RBridge CLI example on an RBridge in registry mode:

$ sudo rbridge control
RBridge: connected to PID 78810
RBridge> license
 this RBridge is running as a registry, no license required
RBridge>

Recommendations and summary

• an RBridge running in registry mode doesn’t require any license
• an RBridge running in bridging mode runs as a 30 day trial without licensing
• the RBridge CLI command “license” shows the licensing status

interface

If this parameter is set, this interface that is connected to the remote side on Ethernet / Layer 2 level. The RBridge node then runs in bridging mode.

If this parameter is empty or not present, RBridge runs in registry mode becoming a third party instance to help other RBridges to find each other. In that case, no further licensing is required.

Example

interface= eth0

Recommendations and summary

• Just keep in mind that this parameter serves actually two purposes (controlling in what mode RBridge runs and defining the bridged LAN for bridging mode).
• Just use the interface naming as it appears to be on your operating system (as shown by your networking tools).
• Bridging WLAN interfaces may work, however there might be unwanted packet loss as the wireless connection quality is not guaranteed.

local_address

This parameter restricts the local binding of the RBridge UDP server to a specific address. Possible values are numerical IPv4 addresses, numerical IPv6-mapped IPv4 addresses, numerical IPv6 addresses or DNS hostnames resolving either to an A or AAAA record.

Examples

local_address= 10.1.1.12
local_address= ::ffff:10.1.1.12
local_address= 2001:db8::2:4
local_address= resolving.to.something.inlab.net

local_port

This parameter changes the local UDP default port to the specified numerical value.

Examples

local_port= 20000

Recommendations and summary

• Both parameters, local_address and local_port should only be set if there’s an urgent need to do so.
• In general, we recommend to leave them unspecified (thus binding to all local addresses and using the default port).
• “Binding to everything” enables RBridge to freely use UDP over both IP protocols and also to switch between them when necessary.

remote_address

This parameter allows to specify the IP address of a known RBridge peer.

Possible values are numerical IPv4 addresses, numerical IPv6-mapped IPv4 addresses, numerical IPv6 addresses or DNS hostnames resolving either to an A or AAAA record.

Examples

local_address= 10.1.1.13
local_address= ::ffff:10.1.1.13
local_address= 2001:db8::2:5
local_address= resolving.to.something.inlab.net

remote_port

This parameter changes the local UDP default port to the specified numerical value.

Examples

remote_port= 20000

Recommendations and summary

• If you want two RBridges communicate directly, it’s sufficient to specify only the address sitting directly on the Internet (without any NAT device in between).
• If an RBridge does not have this set, it generally accepts any peer that sends authenticated keepalive packets as the new connection path.
• If an RBridge doesn’t know its peer address, but has a registry_linkname set and knows about at least one registry, it tries to find its peer additionally that way.

macsecret

Setting this parameter enables basic authentication for an RBridge running in bridging mode. In case that true random key material is used, this parameter is ignored. Basically, it controls the authentication mechanism between to RBridges establishing a RBridge tunnel. The macsecret therefore needs to be the same on both sides. For security reasons a somewhat complex value should be preferably chosen.

Examples

macsecret = OJHJ$%&aha(HHHOA
macsecret = "A MAC Secret with blanks"
macsecret = 17272888010111

key

This parameter specifies the encryption key and also needs to be the same on both sides. The actual key which is internally used is the SHA-2 hash value of the specified string.

If this parameter is empty or not included in rbridge.conf, the sender will authenticate, but not encrypt.

If this parameter is present together with true_random_keymaterial, the selected true random key is xored with the SHA-2 hash of key before encryption or decryption.

Examples

key = KKASJIUASUZUETGUFWKLIIWDLL
key =

encryption_mode

This parameter controls which encryption algorithm is used. If it’s set to 0 (the default), RBridge uses ChaCha20 (a newer, very fast algorithm). If it is set to 1, AES-256 CTR (counter mode) is used instead.

The parameter setting is valid for all encrypted communication and needs to be the same on both sides.

Example (activating AES-256 CTR)

encryption_mode = 1

true_random_keymaterial

This parameter specifies a binary file containing true random bytes generated with a suitable hardware based true random number generator. The total size of the file needs to be exactly 64 MB (67108864 bytes) thus providing a total of 2097152 true random 32 byte keys.

The key material contained in this file is read into memory for fastest access, so that even the Raspberry Pi platform can easily handle this since there is no disk IO slowdown.

The overall security obtained by this method is quite extreme: A potential attacker trying to decrypt a previously recorded packet stream actually needs the contents of this key material file (or, more precisely all the different true random keys that have been used).

If the parameter key is present together with true_random_keymaterial, the selected true random key is xored with the SHA-2 hash of key before encryption or decryption.

If the parameter macsecret is present together with true_random_keymaterial, authentication is based on the SHA-2 hash over all 2097152 true random keys xored with the SHA-2 hash over the macsecret string and the actual packet contents.

Example

true_random_keymaterial = "/home/rbridge/keymaterial.bin"

$ ls -l /home/rbridge/keymaterial.bin
-r-------- 1 root wheel 67108864 Mar 8 14:48 /home/rbridge/keymaterial.bin
$

registry_linkname

This parameter associates a name to the intended link that two RBridges want to establish (and needs to be the same on both sides as well). If there’s no peer address known, but one or two registries available an RBridge peer announces itself with its communication parameters towards the registries. If it is empty or unspecified (not present), the RBridge node will never contact any registry.

Towards the registries a connection or negotiation request is identified by the SHA-2 hash over the concatenation of macsecret and registry_linkname (and the IP protocol available).

Examples

registry_linkname = "Joe's remote office connection"
registry_linkname = "remote administration datacenter Munich-East"
registry_linkname =

Recommendations and summary:

• A RBridge in bridging mode needs to have a method of authentication available. This may be either a shared macsecret or a shared identical true random key material (64 megabytes of true random data).
• If there’s no authentication method available, RBridge will refuse to be started in bridging mode.
• Not authenticated packets will be dropped.
• Available true random key material (parameter true_random_keymaterial) overrides any settings of macsecret and key and switches encryption on.
• The parameter registry_linkname enables negotiations with external registries and gives the potential link a “name”.

registry_address_1

This parameter specifies the IPv4 or IPv6 address of the first registry that a RBridge in routing mode may connect if necessary. Possible values are numerical IPv4 addresses, numerical IPv6-mapped IPv4 addresses, numerical IPv6 addresses or DNS hostnames resolving either to an A or AAAA record.

If this parameter is not present in the RBridge configuration file (rbridge.conf), it defaults to r.inlab.net. This DNS entry resolves to an A record (IPv4) pointing to our public registry.

If it’s present, but contains no value (rbridge_registry_1=) registry 1 will never be contacted (obviously).

Examples

registry_address_1= 10.1.1.12
registry_address_1= ::ffff:10.1.1.12
registry_address_1= 2001:db8::2:4
registry_address_1= resolving.to.an.RBridge.registry
registry_address_1=

registry_port_1

This parameter changes the UDP default port of registry 1 to the specified numerical value. Usually, this doesn’t need to be changed since a registry. If you are running your own RBridge registry on a different port for some reason, this should be changed accordingly. Our public registry (reachable over IPv4 at r.inlab.net) listens on the DASP (Distributed Authenticated Service Protocol) default port 439.

Examples

registry_port_1= 20000

registry_address_2

This parameter specifies the IPv4 or IPv6 address of the second registry that a RBridge in routing mode may alternatively connect if necessary. As before, possible values are numerical IPv4 addresses, numerical IPv6-mapped IPv4 addresses, numerical IPv6 addresses or DNS hostnames resolving either to an A or AAAA record.

If this parameter is not present in the RBridge configuration file (rbridge.conf), it defaults to r6.inlab.net. This DNS entry resolves to an AAAA record (IPv6) pointing to our same public registry when IPv6 is used.

If it’s present, but contains no value (rbridge_registry_2=) registry 2 will never be contacted (obviously).

Examples

registry_address_2= 10.1.1.13
registry_address_2= ::ffff:10.1.1.13
registry_address_2= 2001:db8::2:5
registry_address_2= resolving.to.an.RBridge.registry
registry_address_2=

registry_port_2

This parameter changes the UDP default port of registry 2 to the specified numerical value. Usually, this doesn’t need to be changed since a registry. If you are running your own RBridge registry on a different port for some reason, this should be changed accordingly. Our public registry (reachable over IPv6 at r6.inlab.net) listens on the DASP (Distributed Authenticated Service Protocol) default port 439.

Examples

registry_port_1= 20001

Recommendations and summary

• Leaving these parameters empty will result that an RBridge contacts our public registry either over IPv4 or IPv6 (whichever is available).
• If you have set up your own RBridge registry, these parameters should point to the directly reachable address(es).
• You may split the registry entries by using registry 1 slot for IPv4 and the registry 2 slot for IPv6, however this is not mandatory at all (if you know where your own registry sits, just configure it accordingly).

registry_macsecret

This parameter specifies the authentication hash for packets between an RBridge node in bridging mode and an RBridge acting as a registry. The default value in both cases is “PUBLIC”. If set to empty, a bridging RBridge will never contact a registry.

Examples

registry_macsecret= "Hash of my own registry"
registry_macsecret= 123456789ABC
registry_macsecret=

registry_key

This parameter specifies the encryption key for the communication between bridging RBridges and registry RBridges. The actual key which is internally used is the SHA-2 hash value of the specified string.

If this parameter is empty or not present, encryption towards registries will be switched off.

Examples

registry_key = "a more complicated string &(/%)FF/%)"
registry_key = 89228110022
registry_key =

Recommendations and summary

• Good to know here: Starting RBridge with no configuration file at all will start it as a public registry with the default settings.

registry_log

This parameter controls whether an RBridge running as a registry (or in registry mode) logs the registry requests to the internal RBridge log and the syslog at the same time. This parameter defaults to 0 (disabled).

Examples

registry_log= 1
registry_log= 0

transparent

This parameter controls whether really all packet types are being forwarded or not. If set to 0 (default) the following packet types will not be forwarded:

• IPv4 DHCP packets
• IPv6 DHCP packets
• IPv6 Router Solicitations (ICMPv6 type 133)
• IPv6 Router Advertisements. (ICMPv6 type 134).

This suppression is applied in both directions (after having received a packet from the local LAN and also after receiving an encapsulated packet from the remote side). Therefore, the connection is only fully transparent if transparent is set to 1 on both sides.

Examples

transparent= 1
transparent= 0

force_encryption

This parameter controls whether a not encrypted packet is accepted by an RBridge receiving it in the case that an encryption key is known at the same time. This parameter defaults to 1 (enabled), causing not encrypted (but authenticated) packets without further notice.

Setting it to 0 (disabled) practically allows further processing of not encrypted packets.

Examples

force_encryption= 1
force_encryption= 0

own_fragmentation

This parameter controls whether RBridge uses the UDP standard fragmentation/reassembly or its own fragmentation/reassembly mechanism. If set to 0, the normal UDP fragmentation of the underlying IP stack is used, if set to 1, RBridge uses its own fragmentation mechanism. This parameter defaults to 1.

“Own fragmentation” at a higher level avoids serious problems with routing devices having difficulties with UDP fragmentation and reassembly (resulting in a serious degradation in performance).

This controls the fragmentation behaviour of the sender. When one side uses “own fragmentation”, the other side automatically switches to that mode as well.

Examples

own_fragmentation= 1
own_fragmentation= 0

noinject

This parameter allows to configure a testing mode: If set to 1 (enabled) the RBridge will never inject any packets into the local LAN. Everything else is processed normally (forwarding and receiving of packets through the DASP tunnel and update of the forwarding table). This parameter defaults to 0 (disabled).

Examples

noinject= 1
noinject= 0

stealth_mode

If set to 1, the RBridge node operates in stealth mode and will not be detected by RBridge scanning (“rbridge -s”).

Examples

stealth_mode= 1
stealth_mode= 0

Recommendations and summary

• The parameters of this parameter group may be changed and set as needed.
• Please contact us when there is demand to operate RBridge in stealth mode.

local_mac_allow

This parameter references a file which contains a set of allowed MAC addresses (one per line). Only packets with an allowed source address (and received locally) will be further processed, everything else will be dropped.

Example

local_mac_allow = /home/test/local_allow.txt

$ cat /home/test/local_allow.txt
80:fa:5b:15:6d:14
00:03:ba:27:87:33
00:00:5e:00:02:31
$

local_mac_deny

This parameter references a file which contains a set of denied MAC addresses (one per line). All packets received locally will be further processed, but if the source address in contained in this list the packet will be dropped.

Example

local_mac_deny = /home/test/local_deny.txt

$ cat /home/test/local_allow.txt
80:fa:5b:15:6d:14
$

remote_mac_allow

This is the positive MAC address filter with the same semantics as local_mac_allow, but valid for packets received remotely (through the RBridge DASP UDP tunnel).

remote_mac_deny

This is the negative MAC address filter with the same semantics as local_mac_deny, but working on packets received remotely (through the RBridge DASP UDP tunnel).

Recommendations and summary

• We recommend to use either positive (allow) filtering or negative (deny), but not both at the same time.
• The RBridge CLI command “hash” shows you the currently active settings.

registry_interval

This parameter specifies at what interval the registries are being contacted if necessary. This parameter defaults to 10 (seconds).

timestamptolerance

This parameter controls the timestamp-window in which a packet is accepted. This parameter defaults to 300 seconds (5 minutes).

keepaliveinterval

This parameter specifies at which interval a keepalive packet is being sent to a known peer. This parameter defaults to 10 seconds.

keepalivetimeout

This parameter specifies the timeout for receiving keepalive packets. If this timeout is exceeded, the link to the peer switches to state “down”. This parameter defaults to 30 seconds.

Recommendations and summary

• Usually these parameters work well with their defaults.
• Decrease the timestamp tolerance if you want a stricter handling (and make sure that time synchronisation is set up correctly).