RBridge V3
A secure remote Ethernet Bridge for Linux
Installation and Administration Manual
Status: CURRENT
Version: V3
Date:
Feb 14, 2011
Inlab Software GmbH
Josef-Würth-Str. 3
82031 Grünwald
Germany
Tel.:
Fax:
Email:
Home:
+49 89 6412795
+49 89 6411160
office@inlab.de
http://www.inlab.de
Legal Notices
© Copyright 2005-2010, 2011 by Inlab Software GmbH, Josef-Wuerth-Str. 3, Gruenwald,
Germany. All Rights Reserved / Alle Rechte vorbehalten.
This product or document is protected by copyright and distributed under licenses restricting
its use, copying, distribution, and decompilation. No part of this product or document may be
reproduced in any form by any means without prior written authorization of Inlab Software
GmbH.
BalanceNG is a trademark of Inlab Software GmbH. Gentoo is a trademark by Gentoo
Technologies, Inc. Debian is a registered trademark of Software In The Public Interest, Inc.
FreeBSD is a registered trademark of Walnut Creek CDROM, Inc. Linux is a registered
trademark of Linus Torvalds. All other trademarks and registered trademarks mentioned in
this document are properties by their respective holders.
DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS,
REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF
MERCHANTABILITY, FITNESS FOR FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH
DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.
Date: Feb 14, 2011
Page 2 / 13
RBridge V3 Installation and Administration Manual
© Copyright 2011 by Inlab Software GmbH
All Rights Reserved
Table of Contents
1. Introduction.................................................................................................... 4
2. Installation .....................................................................................................5
3. Licensing........................................................................................................5
4. Operation ...................................................................................................... 5
5. /etc/rbridge.conf............................................................................................. 5
6. Public RBridge Registry Service....................................................................7
7. Command Line Interface............................................................................... 7
7.1. copyright................................................................................................. 7
7.2. hash........................................................................................................ 7
7.3. help......................................................................................................... 8
7.4. license.....................................................................................................8
7.5. log........................................................................................................... 9
7.6. nodeid..................................................................................................... 9
7.7. quit.......................................................................................................... 9
7.8. registry.................................................................................................... 9
7.9. uptime..................................................................................................... 9
7.10. startuplog............................................................................................10
7.11. status.................................................................................................. 10
7.12. stop..................................................................................................... 10
7.13. version................................................................................................ 10
8. MAC Address Filtering.................................................................................10
9. The RBridge Protocol.................................................................................. 11
9.1. PACKET_TYPE_DATA........................................................................ 11
9.2. PACKET_TYPE_ZDATA......................................................................11
9.3. PACKET_TYPE_KEEPALIVE..............................................................12
9.4. PACKET_TYPE_REGISTRY_REQUEST........................................... 12
9.5. PACKET_TYPE_REGISTRY_REPLY................................................. 12
RBridge V3 Installation and Administration Manual
© Copyright 2011 by Inlab Software GmbH
All Rights Reserved
Date: Feb 14, 2011
Page 3 / 13
1. Introduction
RBridge is a secure remote Ethernet bridge solution for Linux. It connects two trusted Ethernet
segments remotely over UDP using either IPv4 or IPv6 transport.
RBridge uses SHA-2 (precisely SHA-256) for authentication, AES for encryption and
timestamps for protection against replay attacks.
Using a registry mechanism and UDP protocol, RBridge is capable to connect directly to the
peer from within NAT or firewall protected areas by using a special “hole punching” technique
(thus requiring no configuration at the connecting routers). For this functionality, RBridge itself
is capable to act as a registry service for any associated pair of RBridges.
Per default, RBridge uses zlib compression of data (which can be disabled on the sender
side).
Additionally, RBridge offers a controlling command line interface (CLI) accessible using telnet.
WARNING: RBridge is a very powerful tool. RBridge should be setup and installed by
experienced network administrators only.
The following figure shows two networks separated by routers and the big Internet in between
as usual:
RBridge allows in that situation to connect the two Ethernet segments as if they were one
single Layer 2 network:
Both RBridges are learning automatically the Ethernet addresses on the other side and start
forwarding packets if necessary.
Date: Feb 14, 2011
Page 4 / 13
RBridge V3 Installation and Administration Manual
© Copyright 2011 by Inlab Software GmbH
All Rights Reserved
2. Installation
RBridge is currently available as an .deb Debian package and as a “tarball” distribution.
3. Licensing
Licensing is based on the MAC address of the eth0 interface (“nodeid”). A serial number and
a node-specific key needs to be present in the file /etc/rbridge.conf for full licensing.
An example licensing entry in /etc/rbridge.conf looks like this:
serial=TRIAL
lickey=4e2307aa78f9f0b6f43f80cf2a536a20
NOTE: RBridge in trial mode (without any licensing) will terminate after exactly one hour of
operation with a syslog message.
4. Operation
startup:
rbrigde [options] start
display nodeid:
rbrigde -N
show release:
rbrigde -r
show this usage information:
rbrigde -h
options:
[-c <conf>]
[-d]
[-h]
[-N]
[-r]
load specific configuration file instead of /etc/rbridge.conf
debug mode: stay in foreground and print debug messages
show this help and usage information
show nodeid and exit immediately
show release and exit immediately
5. /etc/rbridge.conf
Here's an example rbridge.conf file which needs to be copied to /etc/rbridge.conf and changed
at the indicated places. The rbridge.conf.example file may be found in the TAR archive
distribution or in /opt/RBridge (when the .deb package has been installed).
# $Id: rbridge.conf.example,v 1.4 2011/01/14 16:54:22 t Exp $
# Substitute the following with your serial number and key,
# RBridge will terminate after 1 hour of operation in trial mode.
serial=TRIAL
lickey=00000000000000000000000000000000
# The traffic on this interface will be bridged to the peer:
interface=eth0
# You can telnet to this to get a control connection:
control_address=127.0.0.1
control_port=10439
#
RBridge V3 Installation and Administration Manual
© Copyright 2011 by Inlab Software GmbH
All Rights Reserved
Date: Feb 14, 2011
Page 5 / 13
local_address=
local_port=439
#
remote_address=
remote_port=
#
#
#
#
The following two secrets are used to authenticate and encrypt the
traffic between both RBridge peers (PLEASE CHANGE AND UNCOMMENT):
sha2secret=CHANGEME
aessecret=CHANGEME
# This is a unique name for the RBridge link used for registering
# (PLEASE CHANGE AND UNCOMMENT):
# registry_linkname=CHANGEME
# Contact information of first registry:
registry_address_1=rbridge-registry.inlab.net
registry_port_1=439
# Optional contact information of second registry:
# registry_address_2=rbridge-registry.secudos.com
# registry_port_2=439
# Secrets for communication with the registries and for this RBridge
# as a registry:
registry_sha2secret=Public-RBridge-Registry
registry_aessecret=Public-RBridge-Registry
# uncomment if you wish this RBridge acting as a registry:
#registry_enable=1
# comment the following line if you wish zlib compression to be disabled:
zlib_enable=1
# uncomment if you wish registry entries to be logged:
#registry_log=1
# Parameters (usually don't need to be changed):
registry_interval=10
timestamptolerance=300
keepaliveinterval=30
keepalivetimeout=90
# uncomment, if you wish to disable the CLI stop command
# stop_disable=1
# uncomment, if you wish DHCP packets to be passed along
# transparent=1
# Location of activity LED (ARM architecture only)
# - Slow blinking: RBridge active
# - Long ON, short OFF blinking: Connection to peer established
activityLED=/sys/class/leds/LED2/brightness
# uncomment for MAC address allow filters (and populate files accordingly):
# local_mac_allow=/etc/rbridge_local.allow
# remote_mac_allow=/etc/rbridge_local.allow
# uncomment for MAC address deny filters (and populate files accordingly):
# local_mac_deny=/etc/rbridge_local.deny
# remote_mac_deny=/etc/rbridge_remote.deny
Date: Feb 14, 2011
Page 6 / 13
RBridge V3 Installation and Administration Manual
© Copyright 2011 by Inlab Software GmbH
All Rights Reserved
6. Public RBridge Registry Service
The IPv4 Host rbridge-registry.inlab.net is available as a public RBridge registry service
(with the credentials in the rbridge.conf example). There's no warranty of availability, you may
use your own RBridge installation as a registry service.
7. Command Line Interface
The command line interface (CLI) may be accessed using telnet, if “control_address” and
“control_port” have been specified in rbridge.conf.
A typical dialog may look as follows:
$ telnet localhost 10439
Trying ::1...
Connected to localhost.
Escape character is '^]'.
This is RBridge 3.XYZ (created 20XX/YY/ZZ)
RBridge>
The following commands are available:
RBridge> help
the following commands are available:
copyright
show Copyright information
hash
show forwarding table and MAC filters
help (or ?) show this help information
license
show licensing information
log
show current log
nodeid
show nodeid
quit (or q) quit CLI
registry
show current registry entries
uptime
show uptime
startuplog
show startup log
status
show general status
stop
stop immediately
version
show version
The stop command may be disabled with “stop_disable=1”. The dialog is closed automatically
after 60 seconds of inactivity.
7.1. copyright
This command show the Copyright information.
Example:
RBridge> copyright
----------------------------------------------------------Copyright (C) 2011 by Inlab Software GmbH, Germany.
All rights reserved / Alle Rechte vorbehalten.
Visit http://www.inlab.de/rbridge/ for further information.
----------------------------------------------------------RBridge>
7.2. hash
This command displays the current hash information. There's the forwarding table and four
deny and allow hashes.
RBridge V3 Installation and Administration Manual
© Copyright 2011 by Inlab Software GmbH
All Rights Reserved
Date: Feb 14, 2011
Page 7 / 13
Example:
RBridge> hash
forwarding table:
00:14:38:e6:d1:88 eth0
06:00:0a:05:10:01 eth0
00:e0:81:58:ef:2f eth0
00:0d:4b:08:29:73 eth0
00:00:48:b1:b5:10 eth0
00:04:13:25:06:90 eth0
00:04:13:25:06:97 eth0
00:19:5b:ef:12:93 REMOTE_PEER
00:24:b2:c7:f5:8f REMOTE_PEER
00:0e:0c:6c:ba:4a eth0
00:40:63:c9:f5:b5 eth0
00:18:4d:0a:c4:5c eth0
00:03:ba:27:87:33 eth0
00:00:5e:00:01:09 REMOTE_PEER
06:00:ac:11:02:37 eth0
00:50:7f:9e:da:f8 eth0
00:04:13:22:1b:03 eth0
local_rbridge.deny:
local_rbridge.allow:
remote_rbridge.deny:
remote_rbridge.allow:
RBridge>
7.3. help
This command displays the available help information (may be abbreviated with “?”).
Example:
RBridge> help
the following commands are available:
copyright
show Copyright information
hash
show forwarding table and MAC filters
help (or ?) show this help information
license
show licensing information
log
show current log
nodeid
show nodeid
quit (or q) quit CLI
registry
show current registry entries
uptime
show uptime
startuplog
show startup log
status
show general status
stop
stop immediately
version
show version
RBridge>
7.4. license
This command displays the current licensing status.
Example (with no licensing):
RBridge> license
no or invalid license, will terminate after 2787 seconds runtime
Example (with valid licensing):
RBridge> license
valid full license (serial=rbridge-registry.inlab.net)
Date: Feb 14, 2011
Page 8 / 13
RBridge V3 Installation and Administration Manual
© Copyright 2011 by Inlab Software GmbH
All Rights Reserved
Example (with valid OEM licensing):
RBridge> license
valid full OEM license
7.5. log
This command shows the last 40 log messages (as reported to the syslog).
Example:
RBridge> log
2011/01/19 11:58:19 5 started
7.6. nodeid
This command displays the nodeid (which is needed for registry communication and for
licensing). The nodeid is always identical with the eth0 MAC address.
Example:
RBridge> nodeid
Node-ID (eth0 MAC) is 00:0e:0c:6c:ba:4a
7.7. quit
This command quits the CLI (may be abbreviated with “q”).
Example:
RBridge> q
Connection closed by foreign host.
$
7.8. registry
This command displays the current state of the registry. Entries may be “active” (waiting for a
peer) or “SOLVED” (peer found). Entries will be removed after 300 seconds (5 Minutes) if they
are SOLVED or if they are not refreshed anymore with a REGISTRY_REQUEST packet.
Example:
RBridge> registry
00:0e:0c:6c:ba:4a
00:e0:4b:2d:68:ab
00:19:66:b3:c8:e4
8 active ::ffff:10.79.150.186,34135
3 active ::ffff:10.79.150.186,38423
0 active ::ffff:10.13.196.120,439
7.9. uptime
This command shows the current uptime in seconds.
Example:
RBridge> uptime
uptime is 83589 seconds
RBridge V3 Installation and Administration Manual
© Copyright 2011 by Inlab Software GmbH
All Rights Reserved
Date: Feb 14, 2011
Page 9 / 13
7.10. startuplog
This command shows the first 40 log messages that were logged after startup.
Example:
RBridge> startuplog
2011/01/18 13:07:47 5 started
2011/01/18 13:07:48 5 REGISTRY entry accepted for nodeid 00:19:66:b3:c8:e4 from
::ffff:10.13.196.120,439
2011/01/18 13:07:49 5 REGISTRY entry accepted for nodeid 00:e0:4b:2d:68:ab from
::ffff:10.79.150.186,38423
2011/01/19 11:38:13 5 REGISTRY entry accepted for nodeid 00:0e:0c:6c:ba:4a from
::ffff:10.79.150.186,34135
7.11. status
This command show current status information.
Example:
RBridge> status
this RBridge is acting as a registry
registry logs are enabled
zlib data compression is enabled
link ESTABLISHED to nodeid 00:0e:0c:6c:ba:4a
current peer address: ::ffff:92.79.150.186,34135
current registry_1 address: 217.13.196.120,439
current kernel statistics: 6535 packets received, 0 dropped
1135335 bytes locally received from eth0 in 9137 packets
130681 bytes locally received from eth0 in 2089 packets (and forwarded)
34002 bytes saved by compression in 1884 packets (forwarded)
59256 bytes received remotely in 327 packets
58384 bytes received remotely in 316 packets (and forwarded)
7.12. stop
This command stops the current running RBridge process and all associated threads. This
command may be disabled by including “disable_stop=1” in rbridge.conf.
Example:
RBridge> stop
Connection closed by foreign host.
7.13. version
This command displays the current version number.
Example:
RBridge> version
this is RBridge 3.XYZ (created 20XX/YY/ZZ)
8. MAC Address Filtering
RBridge offers “deny” and “allow” filtering mechanisms which are always checking the
Ethernet source address.
# uncomment for MAC address allow filters (and populate files accordingly):
Date: Feb 14, 2011
Page 10 / 13
RBridge V3 Installation and Administration Manual
© Copyright 2011 by Inlab Software GmbH
All Rights Reserved
# local_mac_allow=/etc/rbridge_local.allow
# remote_mac_allow=/etc/rbridge_local.allow
# uncomment for MAC address deny filters (and populate files accordingly):
# local_mac_deny=/etc/rbridge_local.deny
# remote_mac_deny=/etc/rbridge_remote.deny
The referenced files always contain a set of MAC addresses (one address per line) in a colon
separated ASCII format.
If a “deny” file exists, RBridge will drop any packet received on the local (or remote) side with
a matching source MAC address. All other packets are passed along.
If an “allow” file exists, RBridge will forward only packets which MAC source address is
contained in the specified set. All other packets are dropped.
9. The RBridge Protocol
The RBridge protocol uses UDP transport (either IPv4 or IPv6) and is defined by the following
packet types:
9.1. PACKET_TYPE_DATA
This packet type has the following format:
<32 bytes SHA2-256 authentication hash>
<4 bytes timestamp in network byte order>
<packet type=1>
<encryption: 1=encrypted, 0=not encrypted>
<2 bytes data length in network byte order>
<variable length data padded to 16 byte boundary>
The initial authentication hash is the result of SHA2-256 with the ASCII value of “sha2secret”
and the packet contents beginning with the timestamp (at offset 32) up to the end as input.
The timestamp transports the time notion of the sender in network byte order and protects
against replay attacks (see the “timestamptolerance” configuration value).
If the packet is encrypted (encryption=1), the data is encrypted with AES using the SHA2-256
hash of the value of “aessecret” as the actual AES key.
The length of the original data (the Ethernet packet) is 2 bytes in network byte order.
The data area is padded with zeros (0x00) to a boundary of 16 bytes (and encrypted
afterwards if encryption=1).
9.2. PACKET_TYPE_ZDATA
This packet type has the following format:
<32 bytes SHA2-256 authentication hash>
<4 bytes timestamp in network byte order>
<packet type=2>
<encryption: 1=encrypted, 0=not encrypted>
<2 bytes data length in network byte order>
<variable length data padded to 16 byte boundary>
RBridge V3 Installation and Administration Manual
© Copyright 2011 by Inlab Software GmbH
All Rights Reserved
Date: Feb 14, 2011
Page 11 / 13
The packet semantics are the same as with PACKET_TYPE_DATA, but the data part is zlib
compressed (if enabled). The receiver needs to perform an additional decompression step
after authentication, timestamp validation and decryption.
9.3. PACKET_TYPE_KEEPALIVE
This packet type has the following format:
<32 bytes SHA2-256 authentication hash>
<4 bytes timestamp in network byte order>
<packet type=3>
<encryption: 1=encrypted, 0=not encrypted>
<2 bytes data length in network byte order (always 12)>
<6 bytes own nodeid>
<6 bytes peer nodeid>
<4 bytes padding>
This packets is sent out every “keepaliveinterval” seconds, if a peer address is known. The
data contains always the own nodeid and the peer nodeid (00:00:00:00:00:00 if not known
during the initial phase). The data part may be encrypted or not, the authentication works the
same way as with PACKET_TYPE_DATA.
9.4. PACKET_TYPE_REGISTRY_REQUEST
This packet type has the following format:
<32 bytes SHA2-256 authentication hash>
<4 bytes timestamp in network byte order>
<packet type=4>
<encryption: 1=encrypted, 0=not encrypted>
<2 bytes data length in network byte order (always 48)>
<32 bytes registry signature>
<6 bytes nodeid>
<10 bytes padding>
This packet is sent out every “registry_interval” seconds, if there's no current peer known, but
one or two registries specified. Authentication and encryption works similar as with
PACKET_TYPE DATA and PACKET_TYPE_KEEPALIVE, with the difference that
“registry_sha2secret” is used instead of “sha2secret” and “registry_aessecret” is used instead
of “aessecret”.
The registry signature is the SHA2-256 hash result with the values of “sha2secret” and
“registry_linkname” as input. This way two peers with the same “sha2secret” and
“registrylinkname” are able to find each other, if they are addressing the same registry.
Additionally, the RBridge nodeid is sent.
9.5. PACKET_TYPE_REGISTRY_REPLY
This packet type has the following format:
<32 bytes SHA2-256 authentication hash>
<4 bytes timestamp in network byte order>
<packet type=5>
<encryption: 1=encrypted, 0=not encrypted>
<2 bytes data length in network byte order (always 48)>
<32 bytes registry signature>
Date: Feb 14, 2011
Page 12 / 13
RBridge V3 Installation and Administration Manual
© Copyright 2011 by Inlab Software GmbH
All Rights Reserved
<6 bytes peer nodeid>
<variable length peer connection parameters>
<one byte binary 0>
<padding to 16 byte boundary>
This packet is send in response to a PACKET_TYPE_REGISTRY_REQUEST if the registry
has found a matching peer. Authentication and encryption are handled the same way as with
PACKET_TYPE_REGISTRY_REQUEST.
The peer nodeid is reported back together with the connection parameters of the peer in text
format (<IP-Address>,<port>). The connection parameters are reported as seen by the
registry.
RBridge V3 Installation and Administration Manual
© Copyright 2011 by Inlab Software GmbH
All Rights Reserved
Date: Feb 14, 2011
Page 13 / 13