1 .TH 6BED4CLIENT 8 "Februari 1, 2011"
2 .\" Please adjust this date whenever revising the manpage.
4 .\" Some roff macros, for reference:
5 .\" .nh disable hyphenation
6 .\" .hy enable hyphenation
8 .\" .ad b justify to both left and right margins
9 .\" .nf disable filling
10 .\" .fi enable filling
11 .\" .br insert line break
12 .\" .sp <n> insert n+1 empty lines
13 .\" for manpage-specific macros, see man(7)
15 6bed4client \- client-side daemon for instant-on IPv6 service
18 [\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]
24 The \fB6bed4client\fR creates an instant-on, zero-config IPv6
25 communication facility. It is designed to work behind NAT and
26 firewalls, and to find the shortest possible route to a communications
29 The command usually works through a 6bed4 interface, often a tunnel,
30 through which commands are passed to this daemon, which encapsulates
31 the traffic into UDP and IPv4 before sending it. Return UDP/IPv4
32 traffic is decapsulated and offered through the 6bed4 interface.
34 The \fB6bed4client\fR goes through lengths to achieve optimal routing
35 for all packets. The existence of a public server ensures that
36 IPv6 connections are always possible, but anything more direct is
39 Note that the structure of a 6bed4 IPv6 address is such that it
40 reveals a host's public IPv4 address and an external UDP port used
41 for the 6bed4 tunneling protocol. This information can be used to
42 derive both local addressing information, as well as remote. This
43 will only work for addresses that start with the standard prefix
44 under which 6bed4 addresses are created.
46 If traffic is intended for the same public IPv4 address as the local
47 node, then it is likely to be a host on the same local network. In
48 such cases, a Neighbor Solicitation is sent to the IPv4 all-hosts multicast
49 address in an attempt to find a direct route on the LAN. This may not
50 always work, for instance in the presence of subnets without multicast
51 forwarding between their segments.
53 More generally though, a remote peer has an IPv4 address and a UDP
54 port over which it once commenced 6bed4 towards the public server,
55 to obtain its IPv6 address. In an attempt to find a direct route,
56 the \fB6bed4client\fR will try to find a direct route to that
57 endpoint. If it succeeds to send a Neighbor Solicitation and
58 receives back a Neighbor Advertisement, it has established a direct
59 channel for IPv6 communications, and it can continue to use that
60 instead of going through the public server.
62 Direct connections to an IPv4/UDP address will only fail if the
63 remote system is behind symmetric NAT or a similar firewall. In
64 this case, an initiative from that remote system to contact the
65 local system may still succeed, and give rise to a seconde attempt
66 towards the remote peer, which should then succeed. Only if both
67 local and remote peers use symmetric NAT, will it be necessary
68 to continue to communicate through the public 6bed4 server.
70 In general, local network traffic is preferred over anything
71 else. Second-best is direct traffic to a public IPv4/UDP address,
72 and the public 6bed4 server would be the last resort.
74 A system with access to native IPv6 can still use 6bed4, although
75 it would not want to setup a default route over it. The use of
76 doing this is twofold: At first it unloads the public server from
77 having to make the connection, and secondly it makes the connection
78 between the local and remote host as direct as is possible over
79 IPv4. The mixed setup of native IPv6 and 6bed4 will not lead to
80 any trouble, as 6bed4 traffic is easily recognised by the target
81 address prefix, and the interface is setup to handle this.
83 It is possible to allocate a fixed 6bed4 address for a server, and
84 publish it in DNS. This would be as constant as the IPv4 address
85 and UDP port assigned to the \fB6bed4client\fR, but most NAT and
86 firewalls support port forwarding; the \fB\-p\fR option on the client
87 can be used to support reception of incoming 6bed4 traffic on the
91 \fB\-t\fR \fI/dev/tunX\fR
93 \fB\-\-tundev\fR \fI/dev/tunX\fR
94 Instead of creating a tunnel for the duration that \fB6bed4server\fR runs,
95 use one that already exists and that has already been setup with
96 the proper IPv6 prefix. This option makes it possible for
97 non-root users to run \fB6bed4server\fR. All that is required is acccess to
98 the tunnel device by the user that runs \fB6bed4server\fR. Optional on Linux.
102 \fB\-\-default\-route\fR
103 Create a default route through the 6bed4 interface. This means that the
104 entire IPv6 Internet can be accessed through the 6bed4 interface. This is
105 not setup by default, as 6bed4 might also be used as an add-on interface
106 that connects more directly to other 6bed4 hosts.
108 \fB\-l\fR \fIv4addr\fR
110 \fB\-\-listen\fR \fIv4addr\fR
111 Listen for 6bed4 messages on the specified IPv4 address. This will also
112 be the address from which the traffic is sent. This setting may be
113 used together with \fB\-p\fR to control the daemon's behaviour such that
114 it can be the target of a port forwarding setup in NAT or firewall.
118 \fB\-\-port\fR \fIport\fR
119 Let the 6bed4 daemon listen to the given UDP port. This will also be
120 the port from which the traffic is sent. This setting may be used
121 together with \fB\-l\fR to control the daemon's behaviour such that it
122 can be the target of a port forwarding setup in NAT or firewall.
126 \fB\-\-v4server\fR \fIv4addr\fR
127 Use the given IPv4 address as the fallback 6bed4 server instead of the
128 default public server. This is an experimental facility; it may lead to
129 network inefficiencies or instabilities if the public server address cannot
130 be found by comparison. Use with caution, and please report any problems
131 that you run into when using this option. Do not assume this feature will
139 Do not fork to the background. Instead, stay on the foreground and listen
140 to break signals. This is primarily useful for testing, including while
141 rolling out 6bed4 on a site.
145 \fB\-\-error\-console\fR
146 Normally, debugging messages are sent tot syslog. With this setting, the
147 messages are instead printed to the console.
148 On systems supporting the non-POSIX syslog extension LOG_PERROR, the output will be sent to stderr.
149 On systems without that extension, the system console is used.
151 \fB\-k\fR \fItime\fR[,\fIreach\fR]
153 \fB\-\-keepalive \fItime\fR[,\fIreach\fR]
154 This setting defines the keepalives sent to the Public 6bed4 Service.
155 The \fItime\fR indicates the number of seconds between keepalives, the
156 \fIreach\fR indicates the TTL to use on the traffic where supported;
157 it is only needed to get outside NAT and firewalls, but not to reach
158 the central infrastructure. The default is \fB\-\-keepalive 30,3\fR
159 and may be automatically determined in future versions.
163 \fB\-\-radius\fR \fIhops\fR
164 Set the multicast radius to the given number of hops, the default being 1.
165 This number is used as the TTL on multicast messages, thereby determining
166 whether routers are permitted to forward these packets. The value 0
167 indicates that no multicast should be used. Values above 1 run the risk
168 of deregulating the performance of 6bed4 on an unsuitable network, please
169 read \fBLOCAL NETWORKING\fR below for details.
173 \fB\-\-udp-variability\fR
174 TODO - argue, and maybe implement.
175 Accept variations in remote UDP ports when comparing 6bed4 address with
176 each other, or with an IPv6 address. This reduces the security of the
177 tunnel mechanism by permitting different processes, and possibly different
178 users, on the remote end to take over from each other. It also means that
179 remote symmetric routers stand a chance of contacting this node over direct
180 peering traffic. This option is not helpful if the local node is a
181 symmetric router; and if both peers run a symmetric router then there is
182 never going to be direct traffic between the peers.
184 This option sets up support for remote peers that run a NAT router that is
185 inherently unsuitable for peer-to-peer traffic. The default setup is not
186 kind to those routers, but it sends a much clearer signal about the origin
187 of the problems, namely at the symmetric NAT router. Being able to
188 pinpoint the cause of a problem is probably more helpful than trying to
189 deal with a few situations but fail on certain connections, where each
190 end concludes that the other end must be at fault because direct connections
191 only fail with that other party.
193 Whenever possible, 6bed4 connections are connected directly over the locally
194 attached network. This optimises the traffic by not passing it through an
195 external router. But it also implies trust in the peers on a local network;
196 for this reason, it is possible to set \fB\-\-radius 0\fR and thereby
197 disable the attempts to find peers locally.
199 The mechanism used to find peers locally is through multicast. It is
200 assumed that all hosts that can be reached over multicast can also be
201 reached over unicast, given that their direct address were known. The
202 response to a multicast query through Neighbor Solicitation is a unicast
203 response through Neighbor Advertisement, in both cases encapsulated in
206 The default setting \fB\-\-radius 1\fR works only on locally attached
207 subnets. This is generally safe, as this network is normally unfiltered.
208 In places where filtering is applied within a subnet, the administrative
209 staff should be prepared to stop confusion of network nodes; in case of
210 6bed4, this means setting \fB\-\-radius 0\fR to avoid relying on an open
211 locally attached subnet. This setting implies that the daemon does not
212 listen for incoming queries over multicast. The standards specify that
213 multicast support is optional, so this does not break any standards.
215 Settings of \fB\-\-radius 2\fR and beyond are more dangerous; it could
216 lead to asymmetric routes if not properly configured on a network. The
217 problem of asymmetric routes being that one half might go through a
218 hole in NAT, which closes when traffic does not flow through bidirectionally.
219 The daemon goes through lengths to avoid this situation, and to that end it
220 may generate Neighbor Solicitations and Redirects in response to every
221 packet exchanged. If you see this pattern, you almost certainly have an
222 asymmetric routing situation.
224 To avoid asymmetric routes, all nodes should be able to find each other
225 through multicast in both directions; if A can find B, then B should be
226 able to find A. Plain 6bed4 traffic should be able to pass in both
227 directions as well as multicast traffic. Note that multicast traffic is
228 always sent to default UDP port 25788, but unicast traffic may be sent
229 to any UDP port. These additional requirements are the reason why the
230 default settings are limited to the locally attached subnets.
232 This daemon does not pass on QoS headers as it should according to the
235 The daemon needs to access the neighbor cache to be able to compare routes
236 in both directions and ensure their symmetry. It does this by accessing
237 the AF_NETLINK(7) interface, more specifically NETLINK_ROUTE(7). This
238 introduces a number of potential problems.
240 First, the AF_NETLINK/NETLINK_ROUTE facility may limit portability to non-Linux platforms.
241 The AF_NETLINK is the closest bet to a standard approach, and similar
242 constructions exist on other platforms, so there may be no problem in
245 Second, the AF_NETLINK/NETLINK_ROUTE documentation is incomplete, and unclear at some
246 points. This means that the current code may not work on all platforms;
247 notably, the proper use of macros is insufficiently documented to support
248 reliable porting to other platforms and newer kernel versions. Another
249 point of concern is whether message breakdown into partial messages has
250 been covered accurately, as that process also has not been specified fully.
252 Thirdly, AF_NETLINK/NETLINK_ROUTE queries are not cached. Every Neighbor Discovery
253 that is accepted from a remote origin will trigger the process of
254 comparing routes. This may lead to scaling problems on very active
255 nodes with lots of peers to communicate with simultaneously.
257 \fB6bed4client\fR was written by Rick van Rein from OpenFortress.
258 It was created to support the 0cpm project.
projects / 6bed4 / blob