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 “
A value may include blanks when it is specified in double quotes.
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.
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).
Running RBridge in registry mode requires no licensing.
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).
serial= ACME190226 lickey= c90219951a3551c28bae99d866621c9f
$ sudo rbridge control RBridge: connected to PID 78792 RBridge> license valid license (serial=ACME190226) RBridge>
$ 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>
$ sudo rbridge control RBridge: connected to PID 78810 RBridge> license this RBridge is running as a registry, no license required RBridge>
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.
There are reports that WLAN packet injection is nor working on the Raspberry Pi 3+. We are currently testing WLAN injection with the Raspberry Pi 4, in general we recommend to avoid bridging of WLAN interfaces.
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.
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
This parameter changes the local UDP default port to the specified numerical value.
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.
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
This parameter changes the local UDP default port to the specified numerical value.
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.
macsecret = OJHJ$%&aha(HHHOA macsecret = "A MAC Secret with blanks" macsecret = 17272888010111
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.
Configuring the same macsecret, but different key values on both sides will cause that complete garbage is injected into the networks (obviously, this should be avoided).
key = KKASJIUASUZUETGUFWKLIIWDLL key =
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.
encryption_mode = 1
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.
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 $
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).
registry_linkname = "Joe's remote office connection" registry_linkname = "remote administration datacenter Munich-East" registry_linkname =
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).
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=
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.
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).
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=
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.
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.
registry_macsecret= "Hash of my own registry" registry_macsecret= 123456789ABC registry_macsecret=
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.
registry_key = "a more complicated string &(/%)FF/%)" registry_key = 89228110022 registry_key =
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).
registry_log= 1 registry_log= 0
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:
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.
transparent= 1 transparent= 0
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.
force_encryption= 1 force_encryption= 0
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.
own_fragmentation= 1 own_fragmentation= 0
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).
noinject= 1 noinject= 0
This parameter requires a special RBridge build which is only available for law enforcement agencies and other legal purposes. Setting it to 1 has otherwise no effect (the RBridge node will still be detectable by “rbridge -s” scanning).
If set to 1, the RBridge node operates in stealth mode and will not be detected by RBridge scanning (“rbridge -s”).
stealth_mode= 1 stealth_mode= 0
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.
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 $
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.
local_mac_deny = /home/test/local_deny.txt $ cat /home/test/local_allow.txt 80:fa:5b:15:6d:14 $
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).
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).
This parameter specifies at what interval the registries are being contacted if necessary. This parameter defaults to 10 (seconds).
This parameter controls the timestamp-window in which a packet is accepted. This parameter defaults to 300 seconds (5 minutes).
This parameter specifies at which interval a keepalive packet is being sent to a known peer. This parameter defaults to 10 seconds.
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.