OPTIONS
-------
-Note that any options must be given in the fixed order:
+Note that any options must be given or omitted in the fixed order:
- [-v] [-4] [-B n] [-T n] [-m mcast] [-t tap]
+ [-v] [-tpg] [-4] [-B n] [-T n] [-m mcast] [-t tap] [-S source]
*-v*::
also see logs about connections and messaging, or *-vvv* for *rrqnet*
to be insanely verbose on +stderr+ about virtually everything.
+*-tpg*::
+
+This enables a special UDP transport quirk where *rrqnet* expands any
+packet in the range [1461,1477] bytes to be of 1478 bytes instead. It
+is a work-around for an observed problem in a NAT traversal case for
+certain packet sizes in that range.
+
*-4*::
This directs *rrqnet* to use an ipv4-only socket for its UDP. By
* When a tap is used, stdin and stdout are closed, but stderr remains
open.
-* Without a *-t* argument, *rrqnet* will merely operate as a virtual
-switch among its channels.
-
* With "*-*" as tap name, *rrqnet* will use stdin/stdout as local
networking channel in a format compatible with VDE plugs.
+* Without a *-t* argument, *rrqnet* will operate merely as a virtual
+cable switch among its channels.
+
+*-S* _source_::
+
+This tells which source address to use for outgoing UDP messages.
+
+port::
+
+This non-optional argument tells which UDP port to use.
+
_address-block[:port][=cryptfile]_ [ *-i* _mac_[,_mac_]* ]::
Remotes are declared as +ipv4+ or +ipv6+ network address blocks
collection of fully connected hosts, although the more common is a
"star' formation. See the EXAMPLES section for inspiration.
-*rrqnet* includes logic aiming to protect against broadcast cycles.
-Howewer it does not have the more advanced spanning tree logic that is
-offered by bridge interfaces. In general it's best to avoid cycles and
-rather run several *rrqnet* on a host with their local taps connected
-in a bridge interface.
+*rrqnet* includes logic to protect against broadcast cycles. Whilst
+acting as a switch for all its remotes it does not have spanning tree
+logic as is offered by bridge interfaces. Generally it's probably best
+to avoid cabling cycles, but *rrqnet* also handles full mesh linking
+between multiple hosts without additional configuration. Such a setup
+is also dynamically adapting to prefer the fastest link between hosts.
By default *rrqnet* opens an +ipv6+ socket on the given port. This
mode handles both +ipv6+ and +ipv4+ remotes with +ipv4+ remotes
-handled by means of ipv6-mapped address translations. If *-4* is
-given, *rrqnet* opens an +ipv4+ socket instead, and it cannot then
-have +ipv6+ remotes.
+handled by means of standard ipv6-mapped address translations. If *-4*
+is given, *rrqnet* opens a plain +ipv4+ socket instead, and it cannot
+then have +ipv6+ remotes.
-A *rrqnet* daemon delivers the packets received from the local end,
+An *rrqnet* daemon delivers the packets received from the local end,
i.e., the _tap_ or _stdio_, to known remote ends according the
-targeted MAC addresses and established remote channels. Likewise,
-packets from remotes are delivered to the local end or to other
-remotes according to the targeted MAC addresses. If a packet is an
-Ethernet broadcast, it is delivered to all (known) channels except the
-one it came from.
+targeted MAC addresses through its established remote channels.
+Likewise, packets from remotes are delivered to the local end or to
+other remotes according to the targeted MAC addresses. If a packet is
+an Ethernet broadcast, it is delivered to all (known) channels except
+the one it came from.
If *rrqnet* is started without *-t* option it will operate like an
Ethernet switch that provides connectivity among its +UDP+ channels
This format declares remotes by +ipv4+ address, with optional network
prefix length (0-32), optional port (1-65535) and/or optional key file
-pathname. *rrqnet* will accept packets from sources that match. If the
-network prefix length, +n+, is omitted or given as 32, and a port is
-given, then the remote is taken as an _uplink_.
+pathname. *rrqnet* will accept packets from sources that match by
+prefix. If the network prefix length, +n+, is omitted or given as 32,
+and a port is given, then it declares an _uplink_.
.matching ipv4 uplink and downlink
====
This format declares remotes by ipv6 address, with optional network
prefix length (0-128) and/or optional key file pathname. *rrqnet* will
-accept packets from sources that match. This format (without square
-brackets) is without port number part, and it thus only declares a
-prefix mask for allowed sender hosts.
+accept packets from sources that match by prefix. This format (without
+square brackets) is without port number part, and it thus only
+declares a prefix mask for allowed remote hosts.
.ipv6 address block within square brackets
This format declares remotes by ipv6 address, with optional network
prefix length (0-128) within square brackets, then optionally a port
number and/or an optional key file pathname. *rrqnet* will accept
-packets from sources that match. If the network prefix length, +n+, is
-omitted, or given as 128, and a port number is given, then it declares
-an _uplink_.
+packets from sources that match by prefix. If the network prefix
+length, +n+, is omitted, or given as 128, and a port number is given,
+then it declares an _uplink_.
.matching ipv6 uplink and downlink
====
----
====
-Remotes are declarations to match the source IP addresses for UDP
-traffic. It is either a full host and port address, or an address
-block with or without port number. A full network address and port
+The remote declarations define by prefix match the allowed source IP
+addresses for incoming UDP traffic. A full network address and port
(e.g +[fe::1:4]:2300+ of example 2) declares an _uplink_ that the
-declaring *rrqnet* daemon will establish and maintain by means of
-regular heartbeat messaging. An address block declaration defines the
-mask for allowed incoming connections, aka _downlinks_, that teh
-declaring dameon expects are maintained as uplinks by the remote
-*rrqnet* daemons.
+*rrqnet* daemon will establish and maintain by means of regular
+"heartbeat" messaging. Other declarations define the mask for allowed
+incoming connections, aka _downlinks_, that the dameon expects the
+remote end to maintain as uplinks by the remote *rrqnet* daemons.
+
+Two (or more) +rrqnet+ plugs may be set up with uplink connections to
+each other in which case both (all) of them maintain the link.
+
+.example of multiple pair-wise uplinks
+====
+----
+[1.0.0.1]# rrqnet -t vpn0 2300 2.0.0.1:2300 3.0.0.1:2300 4.0.0.1:2300
+[2.0.0.1]# rrqnet -t vpn0 2300 1.0.0.1:2300 3.0.0.1:2300 4.0.0.1:2300
+[3.0.0.1]# rrqnet -t vpn0 2300 2.0.0.1:2300 1.0.0.1:2300 4.0.0.1:2300
+[4.0.0.1]# rrqnet -t vpn0 2300 2.0.0.1:2300 3.0.0.1:2300 1.0.0.1:2300
+----
+====
The *-i* option, if used for a remote declaration, is followed by a
comma separated list of the MAC addresses to ignore on the associated
TRANSPORT ENCRYPTION
--------------------
-Transport encryption is added to a channel by menas of using a shared
+Transport encryption is added to a channel by means of using a shared
key. This is a sizable file, say 1 Mb, of binary data that is used for
scrambling the network packets. For example, 1 Mb random data is fine.
That declaration says that all channels with hosts of ipv4 address
+10.2.0.0/16+, port 1400, use the file +/sec/keyfile+ for transport
-encryption.
-
+encryption. This may also be used as way of restricting remote
+connections to those that use the right key.
FURTHER EXAMPLES
----------------
Simple rrqnet set up (ipv6)
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This is an example set up for connecting two hosts with *rrqnet*,
-without transport encryption. We pretend these hosts are mutually
-reachable with ipv6 addresses +fe::2+ and +fe::1:3+ respectively, and
-we want to use the ipv6 network +fd::1000:0/120+ over *rrqnet*. A
-nominal set up might then be as follows:
+This is an example of connecting two hosts with *rrqnet* without
+transport encryption. We pretend these hosts are mutually reachable
+with ipv6 addresses +fe::2+ and +fe::1:3+ respectively, and we want to
+use the ipv6 network +fd::1000:0/120+ over *rrqnet*. A nominal set up
+might then be as follows:
.simple rrqnet set up (ipv6)
====
----
====
-Thus, the host +fe::2+ is set up with a tap, +tap0+, having +ipv6+
-address and net +fd::1000:10/120+, and a *rrqnet* daemon for the tap
-and UDP port +1400+ that uplinks to a remote *rrqnet* at +fe::1:3+
-port +1400+. Similarly, the host +fe::1:3+ is set up with a tap
-+tap0+, having +ipv6+ address and net +fd::1000:20/120+, and a *rrqnet*
-daemon for the tap and UDP port +1400+ that uplinks to a remote
-*rrqnet* at +fe::2+ port +1400+.
+Thus, the host +fe::2+ is set up with a tap +tap0+ having ipv6 address
++fd::1000:10/120+, and an *rrqnet* daemon for the tap using UDP port
++1400+ and an uplink +fe::1:3+ port +1400+. Similarly, the host
++fe::1:3+ is set up with a tap +tap0+ having ipv6 address
++fd::1000:20/120+, and an *rrqnet* daemon for the tap using UDP port
++1400+ and an uplink (back) to +fe::2+ port +1400+.
This example also needs ipv6 address resolution set up, which uses the
MAC addresses of the two taps. Let's say it's +02:00:00:00:00:02+ for
Simple rrqnet set up (ipv4)
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This is an example set up for connecting two hosts with *rrqnet*,
-without transport encryption. We pretend these hosts are mutually
-reachable with ipv4 addresses +10.0.0.1+ and +192.168.0.1+
-respectively, and we want to use the ipv4 network +10.100.100.0/24+
-over *rrqnet*. A nominal set up might be as follows:
+This is an example of connecting two hosts with *rrqnet* without
+transport encryption. We pretend these hosts are mutually reachable
+with ipv4 addresses +10.0.0.1+ and +192.168.0.1+ respectively, and we
+want to use the ipv4 network +10.100.100.0/24+ over *rrqnet*. A
+nominal set up might be as follows:
.Simple rrqnet set up (ipv4)
====
----
====
-Thus, the host +10.0.0.1+ is set up with a tap, +tap0+, having ipv4
-address and net +10.100.100.1/24+, and a *rrqnet* daemon for the tap
-and UDP port +1400+ that uplinks to a remote *rrqnet* at +192.168.0.1+
-port +1400+. Similarly, the host +192.168.0.1+ is set up with a tap
-+tap0+, having +ipv4+ address and net +10.100.100.2/24+, and a
-*rrqnet* daemon for the tap and UDP port +1400+ that uplinks to a
-remote *rrqnet* at +10.0.0.1+ port 1400.
+Thus, the host +10.0.0.1+ is set up with a tap +tap0+ having ipv4
+address +10.100.100.1/24+, and an *rrqnet* daemon for the tap and UDP
+port +1400+ uplink +192.168.0.1+ port +1400+. Similarly, the host
++192.168.0.1+ is set up with a tap +tap0+ having ipv4 address
++10.100.100.2/24+, and an *rrqnet* daemon for the tap and UDP port
++1400+ and uplink (back) to +10.0.0.1+ port 1400.
The kernel automagically performs ipv4 address resolution to learn the
MAC addresses associated with the remote ipv4 addresses through the
rrqnet set up through NAT
~~~~~~~~~~~~~~~~~~~~~~~~~
-If one of the hosts, say +192.168.0.1+ is behind a NAT router with
-different IP, say, a dynamic IP on the net +10.2.0.0/16+, we need a
+If one of the hosts, say +192.168.0.1+, is behind a NAT router with
+different IP, say a dynamic IP on the net +10.2.0.0/16+, we need a
different set up. In this scenario, the first host would be set up as
a "server" and the second a client that would utilize the router's NAT
function for return traffic. The set up would be as follows:
====
Thus, the "server" is set up to allow connections from any host on the
-network +10.2.0.0/16+, port 1400, while the "client" is set up the
-same way as in the simple example above. The client will establish and
+network +10.2.0.0/16+ port 1400 while the "client" is set up the same
+way as in the simple example above. The client will establish and
uphold the connection by virtue of its 30 second "heart beat", and
return traffic will be channeled via the router's NAT function.
Note that the server sees the _external_ IP of the client and not its
-_internal_ IP. The server's *rrqnet* therefor has a remote declaration
-to allow messages from that external IP, and in the example case, even
-an address block of a 16 bit common prefix (the choice of a 16 bit
-prefix is merely for the sake of this example).
+_internal_ IP. The server's *rrqnet* therefore has a remote
+declaration to allow messages from that external IP. In the example
+case it allows the address block of the 16 bit common prefix (the
+choice of a 16 bit prefix is merely for the sake of this example).
Multiple client hosts
~~~~~~~~~~~~~~~~~~~~~
-In a "client-server" set up, there can be any number of "client"
-hosts. However, the "clients" behind a common NAT router must then use
+In a "client-server" set up there can be any number of "client" hosts.
+However, the "clients" behind a common NAT router must then use
distinct ports as otherwise the router will be confused about the
return traffic.
-With multiple remote channels, a *rrqnet* daemon serves as a network
+With multiple remote channels, an *rrqnet* daemon serves as a network
switch that forwards traffic in between the channels as well as to and
from the "server" tap. The daemon also forwards Ethernet broadcasts
out on all established channels in support of ARP messaging.
-Further, a *rrqnet* daemon may be both a "server" with down-link
+Further, an *rrqnet* daemon may be both a "server" with down-link
channels, and a "client" with one or more up-link channels, all at the
same time. Such a daemon forwards traffic between all established
channels by means of the Ethernet addresses, as well as broadcasts
-onto all channels
+onto all channels.
Stdio network
~~~~~~~~~~~~~
-The *rrqnet* daemon may be set up to use standard input/output rather
-than a tap for local network traffic. This operation mode has some
-rare use cases, such as linking two *rrqnet* daemons, or connecting to
-a VDE network. For example:
+The *rrqnet* daemon may be configured to use standard input/output
+rather than a tap for local network traffic. This operation mode has
+more rare use cases, such as linking two *rrqnet* daemons or
+connecting to a VDE network. For example:
.stdio network between two rrqnet plugs
====
----
====
-That example set up would make a connection between the two "server"
-daemons operating at different UDP ports, accepting messages from any
-ipv4 host, where port +1400+ has +keyfile0+ for transport encryption,
-and +1401+ has +keyfile1+ for transport encryption.
+The example above connects the two "server" +rrqnet+ daemons operating
+at different UDP ports, each accepting messages from any ipv4 host.
+Port +1400+ has +keyfile0+ for transport encryption, and +1401+ has
++keyfile1+ for transport encryption.
-Another example would be for connecting the *rrqnet* traffic to a VDE
-network via a +vde_plug+ as in the following example:
+The follwoing, different, example connects the *rrqnet* traffic to a
+VDE network via a +vde_plug+:
.stdio network to a vde_plug
====
ends only, but it doesn't perform any payload verification. Messages
smaller than 12 bytes are taken as "heartbeats", and larger messages
are first decrypted as applicable, then treated as Ethernet messages
-and delivered according to their destination MAC addresses. *rrqnet*
-versions after 0.2.3 adds some data to the Ethernet packet in the UDP
-communication.
+and delivered according to their destination MAC addresses.
*rrqnet* bridges its connections, and forwards Ethernet broadcasts to
all known end-points except the incoming one. The input logic takes
timing logic based on binding MAC addresses to remotes. That binding
is sticky for a short time: 6s for broadcast and 20s for unicast. Any
packet received during that time from the same MAC address via another
-remote is dropped. Also, a downlink without incoming traffic for 3
-minutes is considered stale.
+remote is dropped. Also, downlinks without incoming traffic for 3
+minutes are considered stale.
*rrqnet* sends a "heartbeat" of an empty UDP message on its uplinks
every 30 seconds. This is done in order to maintain the channel with
SEE ALSO
--------
-*rrqnet-cron.sh(8)* - Management script to uphold a *rrqnet* plug.
+*rrqnet-cron(8)* - Management script to uphold a *rrqnet* plug.
+*rrqnet-ifupdown(8)* - Management script to uphold a *rrqnet* plug.
*vde_plug(1)* - Virtual Distributed Ethernet plug.
projects / rrq / rrqnet.git / blobdiff