Formatted manual page
[public-tsp] / pubtsp.man
1 .TH PUBTSP 8 "December 12, 2010"
2 .\" Please adjust this date whenever revising the manpage.
3 .\"
4 .\" Some roff macros, for reference:
5 .\" .nh        disable hyphenation
6 .\" .hy        enable hyphenation
7 .\" .ad l      left justify
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)
14 .SH NAME
15 pubtsp \- server-side daemon for public TSP service
16 .SH SYNOPSYS
17 .B pubtsp
18 [\fB\-t\fR \fI/dev/tunX\fR] \fB\-l\fR \fIv4addr\fR \fB\-L\fR \fIv6prefix/64\fR
19 .B pubtsp
20 \fB\-h\fR
21 .SH DESCRIPTION
22 .PP
23 TSP, or the Tunnel Setup Protocol, is standardised in RFC 5722.  It defines
24 several methods for encapsulating IPv6 traffic in IPv4 packets.  It also
25 defines SASL as its generic authentication layer.
26 .PP
27 This daemon implements a specific profile for the server side of TSP.
28 The profile of RFC 5722 implemented by this daemon supports NAT traversal
29 for public use.  The idea of this profile is to support IPv6-only devices
30 from an IPv4-only network without a need to configure a tunnel.
31 .PP
32 This NAT traversing aspect of this profile is achieved
33 by packing IPv6 into UDP and then into IPv4.  This is a
34 guaranteed manner of traversing NAT, provided that this daemon listens
35 to a public IPv4 address.  The daemon currently does not support any
36 other modes of operation.
37 .PP
38 The public-use aspect of this profile means that there is no requirement for
39 clients to register.  In terms of SASL, this uses the ANONYMOUS method of
40 authentication.  However, this does not mean that the use of \fBpubTSP\fR
41 makes it possible to browse IPv6 networks anonymously; in order to
42 ensure traceability of abusive behaviour, the IPv4 address and UDP port
43 of the tunnel client are mentioned in the IPv6 address.  See ADDRESS FORMAT
44 below for details, and SECURITY CHECKS for further precautions against abuse.
45 .PP
46 The foreseen application of servers under this profile of TSP are
47 IPv6-only services that are accessed from an IPv4-only network.  The pivotal
48 point of defining IPv6-only service can be simplicity, or making IPv6
49 more efficient and/or more useful.  To avoid making IPv6 a strict
50 requirement, clients for such an IPv6-only service could implement this
51 profile of TSP to provide a simple backward-compatible mode for IPv4-only
52 network nodes, without impairing all advantages of being IPv6-only.
53 .PP
54 This daemon is in fact a stateless translation between an IPv4 client
55 and the general IPv6 world; the interactions defined by TSP are all
56 handled as required by RFC 5722, but some are strictly speaking not
57 required for \fBpubTSP\fR.  We emphesise that their specification should still
58 be met in all clients, so as to avoid dependency on this one
59 implementation of TSP, and/or its current version.
60 .PP
61 The implementation listens to a UDP socket on TSP standard port 3653
62 on the IPv4 side, and to a
63 tunnel endpoint to capture all traffic matching an IPv6 prefix.
64 It basically tosses traffic back and forth between these interfaces,
65 but not without performing the SECURITY CHECKS desribed below
66 on what is tossed at it.
67 .SH OPTIONS
68 .TP
69 \fB\-h\fR
70 .TP
71 \fB\-\-help\fR
72 Print usage information and exit.
73 .TP
74 \fB\-t\fR \fI/dev/tunX\fR
75 .TP
76 \fB\-\-tundev\fR \fI/dev/tunX\fR
77 Instead of creating a tunnel for the duration that \fBpubTSP\fR runs,
78 use one that already exists and that has already been setup with
79 the proper IPv6 prefix.  This option makes it possible for
80 non-root users to run \fBpubTSP\fR.  All that is required is acccess to
81 the tunnel device by the user that runs \fBpubTSP\fR.  Optional on Linux.
82 .TP
83 \fB\-l\fR \fIv4addr\fR
84 .TP
85 \fB\-\-v4listen\fR \fIv4addr\fR
86 Bind to the given local IPv4 address and listen for incoming TSP
87 tunnel commands and packaged-IPv6 traffic.  Required.
88 .TP
89 \fB\-L\fR \fIv6prefix/64\fR
90 .TP
91 \fB\-\-v6prefix\fR \fIv6prefix/64\fR
92 Bind to the given IPv6 address range through a tunnel device, and
93 forward incoming IPv6 messages to IPv4-based UDP tunnel endpoints.
94 See ADDRESS FORMAT below for an explanation of the lower half of
95 the IPv6 addresses.  Required.
96 .PP
97 If no \fB\-t\fR option is given, a tunnel will be created for the time that
98 \fBpubTSP\fR is running, and the \fIv6prefix/64\fR is used as a router address
99 on that interface.  Routing table entries will not be setup, nor will
100 the general ablity to forward IPv6 traffic.
101 .SH ADDRESS FORMAT
102 .PP
103 An IPv6 address used from \fBpubTSP\fR reveals the IPv4 address and UDP port
104 used by the tunnel endpoint.  This format is checked on sending from
105 the IPv4 tunnel to IPv6, and used to reconstruct the IPv4 tunnel access
106 information for traffic from IPv6 to the IPv4 tunnel.
107 .PP
108 The format of the IPv6 addresses managed by \fBpubTSP\fR are:
109 .PP
110 \fIv6prefix\fR ... \fIv4addr\fR ... \fIudp-port\fR ... \fIlocalnet\fR
111 .PP
112 In this format, the \fIv6prefix\fR is configured with the \fB\-L\fR option,
113 and the \fIv4addr\fR with the \fB\-l\fR option.  The \fIudp-port\fR is noted on
114 arrival of a packet on the IPv4 tunnel side of \fBpubTSP\fR.
115 .PP
116 The \fIlocalnet\fR defaults to 0, but may be used to differentiate up to
117 65,536 different hosts accessible through the same TSP client.  As
118 the main application foreseen for \fBpubTSP\fR is to get IPv6-only tools and
119 devices working on an IPv4-only network, this is not a probable setup,
120 but it is nevertheless possible.  The current version of \fBpubTSP\fR does
121 not actually hand this over as a subnet.
122 .PP
123 The router address that \fBpubTSP\fR chooses for itself consists of the
124 \fIv6prefix\fR with zeroes appended; this falls outside the setup above,
125 because neither IPv4 addresses nor UDP port numbers are not permitted
126 te be zero-valued.
127 .PP
128 Incoming IPv6 traffic destined for a serviced address is first checked
129 as specified under SECURITY CHECKS, and then forwarded to \fIudp-port\fR at
130 \fIv4addr\fR.  In doing so, the IPv6 packet is embedded in whole inside
131 the UDP packet.  The IPv6 addresses are not altered, but only used
132 to derive IPv4 contact information.
133 .PP
134 Outgoing IPv6 traffic arriving on the IPv4 tunnel side of \fBpubTSP\fR will
135 be checked to have been sent from the right \fIv6prefix\fR and mention
136 the \fIv4addr\fR and \fIudp-port\fR matching the client's public side.  That
137 is, NAT may translate the IPv4 address and UDP port used, but these
138 parts of the IPv6 address should show how it is forwarded to \fBpubTSP\fR.
139 Note that the TSP protocol provides this necessary information at the
140 time the TSP tunnel is created.
141 .PP
142 It is recommended to keep NAT state in tact by regularly sending over
143 the UDP port to the tunnel endpoint.  At the very least, a regular
144 ping could do that.  Alternatively, a client-mode only daemon could
145 ensure that it is sending regularly during the times that an outside
146 party might wish to send to it.  This is under the assumption that no
147 explicit mapping in NAT overtakes this responsibility of an active
148 mapping between the internal and external address space.
149 .SH SECURITY CHECKS
150 .PP
151 Not everything will be passed through \fBpubTSP\fR, even if this would be
152 technically possible.  A few security checks are applied to silently
153 drop traffic that looks evil.
154 .PP
155 Packets should be long enough to at least contain the IPv6 traffic
156 and a minimal payload size.  Also, it should not exceed a predefined
157 MTU of 1280 bytes for IPv6.
158 .PP
159 IPv6 traffic uploaded through the IPv4 side should reveal the proper
160 IPv4 settings in the IPv6 source address, as specified under
161 ADDRESS FORMAT above.  This is basically the tunnel aspect of egress
162 filtering.
163 .PP
164 Tunnel commands should adhere to the format of RFC 5722 and may not
165 contain any NUL characters.
166 .SH LICENSE
167 Released under GNU Public License version 3.
168 .SH SEE ALSO
169 The 0cpm project is an example of an IPv6-only SIP application
170 that can use \fBpubTSP\fR and comparable TSP tunnel services to
171 demonstrate the advantages of IPv6 to end users.  It is also
172 a typical example of a transitionary need for something like
173 \fBpubTSP\fR.
174 .PP
175 http://0cpm.org/ \- the homepage of the 0cpm project.
176 .PP
177 http://devel.0cpm.org/pubtsp \- the homepage of \fBpubTSP\fR.
178 .PP
179 RFC 5722 \- the general specification of TSP, of which \fBpubTSP\fR is
180 implements a specific profile for public service under NAT traversal.
181 .SH AUTHOR
182 \fBpubTSP\fR was written by Rick van Rein from OpenFortress.
183 It was created to support the 0cpm project.