6bed4peer.man

.TH 6BED4CLIENT 8 "Februari 1, 2011"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
6bed4client \- client-side daemon for instant-on IPv6 service
.SH SYNOPSYS
.B 6bed4client
[\fB\-t\fR \fI/dev/tunX\fR] [\fB\-d\fR] [\fB\-f\fR] [\fB\-l\fR \fIv4addr\fR] [\fB\-p\fR \fIport\fR] [\fB\-r\fR \fIhops\fR] [\fB-s \fIv4addr\fR]
.PP
.B 6bed4client
[\fB\-h\fR]
.SH DESCRIPTION
.PP
The \fB6bed4client\fR creates an instant-on, zero-config IPv6
communication facility.  It is designed to work behind NAT and
firewalls, and to find the shortest possible route to a communications
peer.
.PP
The command usually works through a 6bed4 interface, often a tunnel,
through which commands are passed to this daemon, which encapsulates
the traffic into UDP and IPv4 before sending it.  Return UDP/IPv4
traffic is decapsulated and offered through the 6bed4 interface.
.SH OPTIMAL ROUTING
The \fB6bed4client\fR goes through lengths to achieve optimal routing
for all packets.  The existence of a public server ensures that
IPv6 connections are always possible, but anything more direct is
of course better.
.PP
Note that the structure of a 6bed4 IPv6 address is such that it
reveals a host's public IPv4 address and an external UDP port used
for the 6bed4 tunneling protocol.  This information can be used to
derive both local addressing information, as well as remote.  This
will only work for addresses that start with the standard prefix
under which 6bed4 addresses are created.
.PP
If traffic is intended for the same public IPv4 address as the local
node, then it is likely to be a host on the same local network.  In
such cases, a Neighbor Solicitation is sent to the IPv4 all-hosts multicast
address in an attempt to find a direct route on the LAN.  This may not
always work, for instance in the presence of subnets without multicast
forwarding between their segments.
.PP
More generally though, a remote peer has an IPv4 address and a UDP
port over which it once commenced 6bed4 towards the public server,
to obtain its IPv6 address.  In an attempt to find a direct route,
the \fB6bed4client\fR will try to find a direct route to that
endpoint.  If it succeeds to send a Neighbor Solicitation and
receives back a Neighbor Advertisement, it has established a direct
channel for IPv6 communications, and it can continue to use that
instead of going through the public server.
.PP
Direct connections to an IPv4/UDP address will only fail if the
remote system is behind symmetric NAT or a similar firewall.  In
this case, an initiative from that remote system to contact the
local system may still succeed, and give rise to a seconde attempt
towards the remote peer, which should then succeed.  Only if both
local and remote peers use symmetric NAT, will it be necessary
to continue to communicate through the public 6bed4 server.
.PP
In general, local network traffic is preferred over anything
else.  Second-best is direct traffic to a public IPv4/UDP address,
and the public 6bed4 server would be the last resort.
.SH SPECIAL CASES
A system with access to native IPv6 can still use 6bed4, although
it would not want to setup a default route over it.  The use of
doing this is twofold: At first it unloads the public server from
having to make the connection, and secondly it makes the connection
between the local and remote host as direct as is possible over
IPv4.  The mixed setup of native IPv6 and 6bed4 will not lead to
any trouble, as 6bed4 traffic is easily recognised by the target
address prefix, and the interface is setup to handle this.
.PP
It is possible to allocate a fixed 6bed4 address for a server, and
publish it in DNS.  This would be as constant as the IPv4 address
and UDP port assigned to the \fB6bed4client\fR, but most NAT and
firewalls support port forwarding; the \fB\-p\fR option on the client
can be used to support reception of incoming 6bed4 traffic on the
forwarded port.
.SH OPTIONS
.TP
\fB\-t\fR \fI/dev/tunX\fR
.TP
\fB\-\-tundev\fR \fI/dev/tunX\fR
Instead of creating a tunnel for the duration that \fB6bed4server\fR runs,
use one that already exists and that has already been setup with
the proper IPv6 prefix.  This option makes it possible for
non-root users to run \fB6bed4server\fR.  All that is required is acccess to
the tunnel device by the user that runs \fB6bed4server\fR.  Optional on Linux.
.TP
\fB\-d\fR
.TP
\fB\-\-default\-route\fR
Create a default route through the 6bed4 interface.  This means that the
entire IPv6 Internet can be accessed through the 6bed4 interface.  This is
not setup by default, as 6bed4 might also be used as an add-on interface
that connects more directly to other 6bed4 hosts.
.TP
\fB\-l\fR \fIv4addr\fR
.TP
\fB\-\-listen\fR \fIv4addr\fR
Listen for 6bed4 messages on the specified IPv4 address.  This will also
be the address from which the traffic is sent.  This setting may be
used together with \fB\-p\fR to control the daemon's behaviour such that
it can be the target of a port forwarding setup in NAT or firewall.
.TP
\fB\-p\fR \fIport\fR
.TP
\fB\-\-port\fR \fIport\fR
Let the 6bed4 daemon listen to the given UDP port.  This will also be
the port from which the traffic is sent.  This setting may be used
together with \fB\-l\fR to control the daemon's behaviour such that it
can be the target of a port forwarding setup in NAT or firewall.
.TP
\fB\-s\fR
.TP
\fB\-\-v4server\fR \fIv4addr\fR
Use the given IPv4 address as the fallback 6bed4 server instead of the
default public server.  This is an experimental facility; it may lead to
network inefficiencies or instabilities if the public server address cannot
be found by comparison.  Use with caution, and please report any problems
that you run into when using this option.  Do not assume this feature will
always be present.
.TP
\fB\-f\fR
.TP
\fB\-\-foreground\fR
.TP
\fB\-\-fork\-not\fR
Do not fork to the background.  Instead, stay on the foreground and listen
to break signals.  This is primarily useful for testing, including while
rolling out 6bed4 on a site.
.TP
\fB\-e\fR
.TP
\fB\-\-error\-console\fR
Normally, debugging messages are sent tot syslog.  With this setting, the
messages are instead printed to the console.
On systems supporting the non-POSIX syslog extension LOG_PERROR, the output will be sent to stderr.
On systems without that extension, the system console is used.
.TP
\fB\-k\fR \fItime\fR[,\fIreach\fR]
.TP
\fB\-\-keepalive \fItime\fR[,\fIreach\fR]
This setting defines the keepalives sent to the Public 6bed4 Service.
The \fItime\fR indicates the number of seconds between keepalives, the
\fIreach\fR indicates the TTL to use on the traffic where supported;
it is only needed to get outside NAT and firewalls, but not to reach
the central infrastructure.  The default is \fB\-\-keepalive 30,3\fR
and may be automatically determined in future versions.
.TP
\fB\-r\fR \fIhops\fR
.TP
\fB\-\-radius\fR \fIhops\fR
Set the multicast radius to the given number of hops, the default being 1.
This number is used as the TTL on multicast messages, thereby determining
whether routers are permitted to forward these packets.  The value 0
indicates that no multicast should be used.  Values above 1 run the risk
of deregulating the performance of 6bed4 on an unsuitable network, please
read \fBLOCAL NETWORKING\fR below for details.
.TP
\fB\-u\fI
.TP
\fB\-\-udp-variability\fR
TODO - argue, and maybe implement.
Accept variations in remote UDP ports when comparing 6bed4 address with
each other, or with an IPv6 address.  This reduces the security of the
tunnel mechanism by permitting different processes, and possibly different
users, on the remote end to take over from each other.  It also means that
remote symmetric routers stand a chance of contacting this node over direct
peering traffic.  This option is not helpful if the local node is a
symmetric router; and if both peers run a symmetric router then there is
never going to be direct traffic between the peers.
.PP
This option sets up support for remote peers that run a NAT router that is
inherently unsuitable for peer-to-peer traffic.  The default setup is not
kind to those routers, but it sends a much clearer signal about the origin
of the problems, namely at the symmetric NAT router.  Being able to
pinpoint the cause of a problem is probably more helpful than trying to
deal with a few situations but fail on certain connections, where each
end concludes that the other end must be at fault because direct connections
only fail with that other party.
.SH LOCAL NETWORKING
Whenever possible, 6bed4 connections are connected directly over the locally
attached network.  This optimises the traffic by not passing it through an
external router.  But it also implies trust in the peers on a local network;
for this reason, it is possible to set \fB\-\-radius 0\fR and thereby
disable the attempts to find peers locally.
.PP
The mechanism used to find peers locally is through multicast.  It is
assumed that all hosts that can be reached over multicast can also be
reached over unicast, given that their direct address were known.  The
response to a multicast query through Neighbor Solicitation is a unicast
response through Neighbor Advertisement, in both cases encapsulated in
UDP and IPv4.
.PP
The default setting \fB\-\-radius 1\fR works only on locally attached
subnets.  This is generally safe, as this network is normally unfiltered.
In places where filtering is applied within a subnet, the administrative
staff should be prepared to stop confusion of network nodes; in case of
6bed4, this means setting \fB\-\-radius 0\fR to avoid relying on an open
locally attached subnet.  This setting implies that the daemon does not
listen for incoming queries over multicast.  The standards specify that
multicast support is optional, so this does not break any standards.
.PP
Settings of \fB\-\-radius 2\fR and beyond are more dangerous; it could
lead to asymmetric routes if not properly configured on a network.  The
problem of asymmetric routes being that one half might go through a
hole in NAT, which closes when traffic does not flow through bidirectionally.
The daemon goes through lengths to avoid this situation, and to that end it
may generate Neighbor Solicitations and Redirects in response to every
packet exchanged.  If you see this pattern, you almost certainly have an
asymmetric routing situation.
.PP
To avoid asymmetric routes, all nodes should be able to find each other
through multicast in both directions; if A can find B, then B should be
able to find A.  Plain 6bed4 traffic should be able to pass in both
directions as well as multicast traffic.  Note that multicast traffic is
always sent to default UDP port 25788, but unicast traffic may be sent
to any UDP port.  These additional requirements are the reason why the
default settings are limited to the locally attached subnets.
.SH BUGS
This daemon does not pass on QoS headers as it should according to the
specification.
.PP
The daemon needs to access the neighbor cache to be able to compare routes
in both directions and ensure their symmetry.  It does this by accessing
the AF_NETLINK(7) interface, more specifically NETLINK_ROUTE(7).  This
introduces a number of potential problems.
.PP
First, the AF_NETLINK/NETLINK_ROUTE facility may limit portability to non-Linux platforms.
The AF_NETLINK is the closest bet to a standard approach, and similar
constructions exist on other platforms, so there may be no problem in
reality.
.PP
Second, the AF_NETLINK/NETLINK_ROUTE documentation is incomplete, and unclear at some
points.  This means that the current code may not work on all platforms;
notably, the proper use of macros is insufficiently documented to support
reliable porting to other platforms and newer kernel versions.  Another
point of concern is whether message breakdown into partial messages has
been covered accurately, as that process also has not been specified fully.
.PP
Thirdly, AF_NETLINK/NETLINK_ROUTE queries are not cached.  Every Neighbor Discovery
that is accepted from a remote origin will trigger the process of
comparing routes.  This may lead to scaling problems on very active
nodes with lots of peers to communicate with simultaneously.
.SH AUTHOR
\fB6bed4client\fR was written by Rick van Rein from OpenFortress.
It was created to support the 0cpm project.