X-Git-Url: http://git.arpa2.org/?p=6bed4;a=blobdiff_plain;f=doc%2Fman%2F6bed4router.man;fp=doc%2Fman%2F6bed4router.man;h=db939a7fa78b8969d964aa0df4173e21217f80d7;hp=0000000000000000000000000000000000000000;hb=b28c6e33e7317c561a757c03fc9e510738c13a72;hpb=a0987d9d5dae066149106d60bf422765aa5635ab diff --git a/doc/man/6bed4router.man b/doc/man/6bed4router.man new file mode 100644 index 0000000..db939a7 --- /dev/null +++ b/doc/man/6bed4router.man @@ -0,0 +1,259 @@ +.TH 6BED4 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 insert n+1 empty lines +.\" for manpage-specific macros, see man(7) +.SH NAME +6bed4router \- server-side daemon for 6bed4 service +.SH SYNOPSYS +.B 6bed4router +[\fB\-d\fR \fI/dev/tunX\fR] \fB\-l\fR \fIv4addr\fR \fB\-L\fR \fIv6prefix/64\fR [\fB\-m\fR/\fB\-i\fR/\fBs\fR/\fBt\fR/\fBu\fR \fI...\fR] +.PP +.B 6bed4router +[\fB\-h\fR] +.SH DESCRIPTION +.PP +Through a \fB6bed4router\fR daemon, it is possible to make a small range of IPv6 +addresses available to a potentially large number of IPv4-only users. This means that even an IPv4-only +network can host IPv6-only applications, as long as they can fall back on +a tunnel based on this profile. +.PP +Use the \fB6bed4router\fR on nodes that support \fB6bed4peer\fR clients +anywhere; instead, use the \fB6bed4node\fR on nodes that want to provide +native IPv6 on a local network. +.PP +These tunnels are intended for mobile and embedded devices, to assist them +in instant changeover from being IPv4-only to eventually being IPv6-only. +Given the +restricted resources in embedded applications, this is likely to improve +the speed of transitioning to IPv6. To avoid cluttered access, these +tunnels should be reserved for resource-hampered devices. For routers, +transitioning mechanisms like 6to4 and 6in4 are more suitable. For +desktops, tunnelling routers or a direct link to a subscription tunnel +service is a better solution. +.PP +The NAT traversing aspect of this profile is needed to support the normal +openness of IPv6 connections. This is achieved by packing IPv6 into UDP +and then into IPv4. This is a guaranteed manner of traversing NAT, +provided that this daemon listens to a public IPv4 address. The daemon +currently does not support any other modes of operation. +.PP +The public-use aspect of this profile means that there is no requirement for +clients to register. However, this does not mean that the use of \fB6bed4router\fR +makes it possible to browse IPv6 networks anonymously; in order to +ensure traceability of abusive behaviour, the IPv4 address and UDP port +of the tunnel client are mentioned in the IPv6 address. See ADDRESS FORMAT +below for details, and SECURITY CHECKS for further precautions against abuse. +.PP +The intended application of clients under this transitionary mechanism are +IPv6-only devices that need a transport over an IPv4-only network. The +reason for defining IPv6-only device can be simplicity, or making IPv6 +more efficient and/or more useful. To avoid making IPv6 a breaking +requirement in roll-outs, devices for such an IPv6-only service could +implement this mechanism to provide a simple backward-compatible mode for +IPv4-only network nodes, without impairing all advantages of being IPv6-only. +.PP +This daemon is in fact a stateless translation between an IPv4 client +and the general IPv6 world; to configure an IPv6 address on the tunnel +client side it will perform autoconfiguration over the tunnel. The +assigned prefix will be a /112, with 16 bits of interface identifiers +to fill in. The interface identifier 0 is reserved for the router, +or in other words, the tunnel server. +.PP +The tunnel server implementation listens to a UDP socket on port 3653 +on the IPv4 side, and to a +tunnel endpoint to capture all traffic matching an IPv6 /64 prefix. +It basically tosses traffic back and forth between these interfaces, +but not without performing the SECURITY CHECKS desribed below +on what is tossed at it. +.SH OPTIONS +.TP +\fB\-d\fR \fI/dev/tunX\fR +.TP +\fB\-\-tundev\fR \fI/dev/tunX\fR +Instead of creating a tunnel for the duration that \fB6bed4router\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 \fB6bed4router\fR. All that is required is acccess to +the tunnel device by the user that runs \fB6bed4router\fR. Optional on Linux. +.TP +\fB\-l\fR \fIv4addr\fR +.TP +\fB\-\-v4listen\fR \fIv4addr\fR +Bind to the given local IPv4 address and listen for incoming IPv6 +neighbour discovery packages as well as general IPv6 traffic. Required. +.TP +\fB\-L\fR \fIv6prefix/64\fR +.TP +\fB\-\-v6prefix\fR \fIv6prefix/64\fR +Bind to the given IPv6 address range through a tunnel device, and +forward incoming IPv6 messages to IPv4-based UDP tunnel endpoints. +See ADDRESS FORMAT below for an explanation of the lower half of +the IPv6 addresses. Required. +.IP +If no \fB\-d\fR option is given, a tunnel will be created for the time that +\fB6bed4router\fR is running, and the \fIv6prefix/64\fR is used as a router address +on that interface. Routing table entries will not be setup by \fB6bed4router\fR, +nor will the general ablity to forward IPv6 traffic. +.TP +\fB\-m\fR \fIv6addr\fR +.TP +\fB\-\-masqhost\fR \fIv6addr\fR +Use the given IPv6 address as the target for masqueraded operation. This +means that any ports setup with \fB\-\-sctp\fR, \fB\-\-tcp\fR or \fB\-\-udp\fR +are forwarded +to this address when addressed on the client's idea of the 6bed4 router +address. Note that the router only uses a few ICMPv6 messages, so the use +of these additional ports can benefit various applications, ranging from +authentication services to honeypots. +.TP +\fB\-s\fR \fIport\fR[\fB:\fIport\fR] +.TP +\fB\-t\fR \fIport\fR[\fB:\fIport\fR] +.TP +\fB\-u\fR \fIport\fR[\fB:\fIport\fR] +.TP +\fB\-sctp\fR \fIport\fR[\fB:\fIport\fR] +.TP +\fB\-tcp\fR \fIport\fR[\fB:\fIport\fR] +.TP +\fB\-udp\fR \fIport\fR[\fB:\fIport\fR] +Apply the masquerading port or port range for SCTP, TCP or UDP to the +masquerading host set by the last preceding \fB\-\-masqhost\fR option, +or use the tunnel's IPv6-side address +if none was set yet. Ports that have been previously bound will not make it, +so it is possible to first relay a port with \fB\-t 22\fR to a service and +then pass the rest to a honeypot with \fB\-t 1:65535\fR. +.TP +\fB\-i\fR +Apply masquerading for ICMPv6 to the masquerading host set by the last +preceding \fB\-\-masqhost\fR option, or use the tunnel's IPv6-side address +if none was set yet. The ICMPv6 messages with a special meaning to 6bed4 +are exempted (Router and Neighbor Solicitation and Advertisement, as well +as Redirect) but other messages will be masqueraded. +.TP +\fB\-h\fR +.TP +\fB\-\-help\fR +Print usage information and exit. +.SH ADDRESS FORMAT +.PP +An IPv6 address used from \fB6bed4router\fR reveals the IPv4 address and UDP port +used by the tunnel endpoint. This format is checked on sending from +the IPv4 tunnel to IPv6, and used to reconstruct the IPv4 tunnel access +information for traffic from IPv6 to the IPv4 tunnel. +.PP +The format of the IPv6 addresses managed by \fB6bed4router\fR are: +.PP +\fIv6prefix\fR + \fIv4addr\fR + \fIudp-port\fR + \fIinterfaceidentifier\fR +.PP +In this format, the \fIv6prefix\fR is configured with the \fB\-L\fR option, +and the \fIv4addr\fR with the \fB\-l\fR option. The \fIudp-port\fR is noted on +arrival of a packet on the IPv4 tunnel side of \fB6bed4router\fR. +.PP +The \fIinterfaceidentifier\fR is always 0 on the router side, and may be set +to other values to distinguish 65,535 different client addresses. As +the main application foreseen for \fB6bed4router\fR is to get IPv6-only tools and +devices working on an IPv4-only network, it is very likely that the clients +will pick a fixed \fIinterfaceidentifier\fR such as 1 and hard-code it. +.PP +Due to the IPv6 practice of assigning link-local names composed of \fBfe80::\fR +and the \fIinterfaceidentifier\fR, the router-side of a tunnel can always +be addressed as \fBfe80::0\fR and clients can be found at addresses ranging +from \fBfe80::1\fR to \fBfe80::ffff\fR. +.PP +Incoming IPv6 traffic destined for a serviced address is first checked +as specified under SECURITY CHECKS, and then forwarded to \fIudp-port\fR at +\fIv4addr\fR. In doing so, the IPv6 packet is embedded in whole inside +the UDP packet. The IPv6 addresses are not altered, but only used +to derive IPv4 contact information. +.PP +Outgoing IPv6 traffic arriving on the IPv4 tunnel side of \fB6bed4router\fR will +be checked to have been sent from the right \fIv6prefix\fR and mention +the \fIv4addr\fR and \fIudp-port\fR matching the client's public side. That +is, NAT may translate the IPv4 address and UDP port used, but these +parts of the IPv6 address should show how it is forwarded to \fB6bed4router\fR. +Note that autonegotiation protocol provides this necessary information at the +time the \fB6bed4router\fR daemon starts. If the NAT mapping changes during the uptime +of the tunnel, a new Router Advertisement is sent from tunnel server to +client, to notify it of the new prefix to use. The original message is +then discarded. +.PP +If it is desired to keep the same IPv6 address for longer periods, it +is recommended that the client keeps NAT state intact by regularly +sending over the UDP port to the tunnel endpoint. For example, a regular +ping could do that. Alternatively, a client-mode only daemon could +ensure that it is sending regularly during the times that an outside +party might wish to send to it. This is under the assumption that no +explicit mapping in NAT overtakes this responsibility of an active +mapping between the internal and external address space. +.SH SECURITY CHECKS +.PP +Not everything will be passed through \fB6bed4router\fR, even if this would be +technically possible. A few security checks are applied to silently +drop traffic that looks evil. +.PP +Packets should be long enough to at least contain the IPv6 traffic +and a minimal payload size. Also, it should not exceed a predefined +MTU of 1280 bytes for IPv6. +.PP +IPv6 traffic uploaded through the IPv4 side should reveal the proper +IPv4 settings in the IPv6 source address, as specified under +ADDRESS FORMAT above. This is basically the tunnel aspect of egress +filtering. +.PP +Tunnel commands should adhere to the format of RFC 5722 and may not +contain any NUL characters. +.SH BUGS +Currently, \fB6bed4router\fR does not use ICMP notifications at the IPv4 +level to provide smart feedback to an IPv6 client. It is undecided +at this point if this would add value. +.PP +To be able to fallback to this TSP profile, an IPv6-only application +needs to find a \fB6bed4router\fR or similar service. A general naming +or numbering scheme is needed to make that straightforward. The +\fB6bed4router\fR service could be setup privately and configured in +individual IPv6-only nodes, but it could accelerate the introduction +of IPv6-only nodes if this were organised by network providers. +.PP +Ideally, \fB6bed4router\fR would be near all heavily connected nodes +of the Internet. There, they would improve connectivity without +being a detour for the traffic. Alternatively, it would be located +in various uplinks. To optimise routing, it is possible to assign +a fixed IPv4 address and IPv6 prefix for \fB6bed4router\fR running +anywhere; its stateless operation means that traffic going back and +forth can go through different instances of \fB6bed4router\fR without +posing problems. +.PP +The \fB6bed4router\fR daemon is a piece of highly efficient code, +and it should be able to handle very high bandwidths. A stress +test has not been conducted yet. +.PP +This daemon does not pass on QoS headers as it should according to the +specification. +.SH LICENSE +Released under a BSD-style license without advertisement clause. +.SH SEE ALSO +The 0cpm project is an example of an IPv6-only SIP application +that can use \fB6bed4router\fR and comparable TSP tunnel services to +demonstrate the advantages of IPv6 to end users. It is also +a typical example of a transitionary need for something like +\fB6bed4router\fR. +.PP +http://0cpm.org/ \- the homepage of the 0cpm project. +.PP +http://devel.0cpm.org/6bed4/ \- the homepage of \fB6bed4\fR. +.PP +RFC 5722 \- the authoritative description of TSP, of which \fB6bed4\fR +implements a specific profile for public service under NAT traversal. +.SH AUTHOR +\fB6bed4router\fR was written by Rick van Rein from OpenFortress. +It was created to support the 0cpm project.