| blob | e1979edda710e01dd90987ffbeea50703b939f9b |
1 .\" $NetBSD: faithd.8,v 1.25 2009/10/25 01:09:09 jakllsch Exp $
2 .\" $KAME: faithd.8,v 1.37 2002/05/09 14:21:23 itojun Exp $
3 .\"
4 .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
5 .\" All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. Neither the name of the project nor the names of its contributors
16 .\" may be used to endorse or promote products derived from this software
17 .\" without specific prior written permission.
18 .\"
19 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29 .\" SUCH DAMAGE.
30 .\"
31 .Dd October 25, 2009
32 .Dt FAITHD 8
33 .Os
34 .Sh NAME
35 .Nm faithd
36 .Nd FAITH IPv6/v4 translator daemon
37 .Sh SYNOPSIS
38 .Nm
39 .Op Fl dp
40 .Op Fl f Ar configfile
41 .Ar service
42 .Op Ar serverpath Op Ar serverargs
43 .Nm
44 .Sh DESCRIPTION
45 .Nm
46 provides IPv6-to-IPv4 TCP relay.
47 .Nm
48 must be used on an IPv4/v6 dual stack router.
49 .Pp
50 When
51 .Nm
52 receives
53 .Tn TCPv6
54 traffic,
55 .Nm
56 will relay the
57 .Tn TCPv6
58 traffic to
59 .Tn TCPv4 .
60 Destination for relayed
61 .Tn TCPv4
62 connection will be determined by the last 4 octets of the original
63 .Tn IPv6
64 destination.
65 For example, if
66 .Li 2001:0db8:4819:ffff::
67 is reserved for
68 .Nm ,
69 and the
70 .Tn TCPv6
71 destination address is
72 .Li 2001:0db8:4819:ffff::0a01:0101 ,
73 the traffic will be relayed to IPv4 destination
74 .Li 10.1.1.1 .
75 .Pp
76 To use
77 .Nm
78 translation service,
79 an IPv6 address prefix must be reserved for mapping IPv4 addresses into.
80 Kernel must be properly configured to route all the TCP connection
81 toward the reserved IPv6 address prefix into the
82 .Xr faith 4
83 pseudo interface, by using
84 .Xr route 8
85 command.
86 Also,
87 .Xr sysctl 8
88 should be used to configure
89 .Dv net.inet6.ip6.keepfaith
90 to
91 .Dv 1 .
92 .Pp
93 The router must be configured to capture all the TCP traffic
94 toward reserved
95 .Tn IPv6
96 address prefix, by using
97 .Xr route 8
98 and
99 .Xr sysctl 8
100 commands.
101 .Pp
102 .Nm
103 needs a special name-to-address translation logic, so that
104 hostnames gets resolved into special
105 .Tn IPv6
106 address prefix.
107 For small-scale installation, use
108 .Xr hosts 5 .
109 For large-scale installation, it is useful to have
110 a DNS server with special address translation support.
111 An implementation called
112 .Nm totd
113 is available
114 at
115 .Pa http://www.vermicelli.pasta.cs.uit.no/software/totd.html .
116 Make sure you do not propagate translated DNS records to normal DNS cloud,
117 it is highly harmful.
118 .Ss Daemon mode
119 When
120 .Nm
121 is invoked as a standalone program,
122 .Nm
123 will daemonize itself.
124 .Nm
125 will listen to
126 .Tn TCPv6
127 port
128 .Ar service .
129 If
130 .Tn TCPv6
131 traffic to port
132 .Ar service
133 is found, it relays the connection.
134 .Pp
135 Since
136 .Nm
137 listens to TCP port
138 .Ar service ,
139 it is not possible to run local TCP daemons for port
140 .Ar service
141 on the router, using
142 .Xr inetd 8
143 or other standard mechanisms.
144 By specifying
145 .Ar serverpath
146 to
147 .Nm ,
148 you can run local daemons on the router.
149 .Nm
150 will invoke local daemon at
151 .Ar serverpath
152 if the destination address is local interface address,
153 and will perform translation to IPv4 TCP in other cases.
154 You can also specify
155 .Ar serverargs
156 for the arguments for the local daemon.
157 .Pp
158 The following options are available:
159 .Bl -tag -width indent
160 .It Fl d
161 Debugging information will be generated using
162 .Xr syslog 3 .
163 .It Fl f Ar configfile
164 Specify a configuration file for access control.
165 See below.
166 .It Fl p
167 Use privileged TCP port number as source port,
168 for IPv4 TCP connection toward final destination.
169 For relaying
170 .Xr ftp 1
171 this flag is not necessary as special program code is supplied.
172 .El
173 .Pp
174 .Nm
175 will relay both normal and out-of-band TCP data.
176 It is capable of emulating TCP half close as well.
177 .Nm
178 includes special support for protocols used by
179 .Xr ftp 1 .
180 When translating FTP protocol,
181 .Nm
182 translates network level addresses in
183 .Li PORT/LPRT/EPRT
184 and
185 .Li PASV/LPSV/EPSV
186 commands.
187 .Pp
188 Inactive sessions will be disconnected in 30 minutes,
189 to avoid stale sessions from chewing up resources.
190 This may be inappropriate for some of the services
191 .Pq should this be configurable? .
192 .Ss inetd mode
193 When
194 .Nm
195 is invoked via
196 .Xr inetd 8 ,
197 .Nm
198 will handle connection passed from standard input.
199 If the connection endpoint is in the reserved IPv6 address prefix,
200 .Nm
201 will relay the connection.
202 Otherwise,
203 .Nm
204 will invoke service-specific daemon like
205 .Xr telnetd 8 ,
206 by using the command argument passed from
207 .Xr inetd 8 .
208 .Pp
209 .Nm
210 determines operation mode by the local TCP port number,
211 and enables special protocol handling whenever necessary/possible.
212 For example, if
213 .Nm
214 is invoked via
215 .Xr inetd 8
216 on FTP port, it will operate as a FTP relay.
217 .\".Pp
218 .\"The operation mode requires special support for
219 .\".Nm
220 .\"in
221 .\".Xr inetd 8 .
222 .Ss Access control
223 To prevent malicious accesses,
224 .Nm
225 implements a simple address-based access control.
226 With
227 .Pa /etc/faithd.conf
228 .Po
229 or
230 .Ar configfile
231 specified by
232 .Fl f
233 .Pc ,
234 .Nm
235 will avoid relaying unwanted traffic.
236 The
237 .Pa faithd.conf
238 contains directives with the following format:
239 .Bl -bullet
240 .It
241 .Xo
242 .Ar src/slen Li deny Ar dst/dlen
243 .Xc
244 .Pp
245 If the source address of a query matches
246 .Ar src/slen ,
247 and the translated destination address matches
248 .Ar dst/dlen ,
249 deny the connection.
250 .It
251 .Xo
252 .Ar src/slen Li permit Ar dst/dlen
253 .Xc
254 .Pp
255 If the source address of a query matches
256 .Ar src/slen ,
257 and the translated destination address matches
258 .Ar dst/dlen ,
259 permit the connection.
260 .El
261 .Pp
262 The directives are evaluated in sequence,
263 and the first matching entry will be effective.
264 If there is no match
265 .Pq if we reach the end of the ruleset
266 the traffic will be denied.
267 .Pp
268 With inetd mode,
269 traffic may be filtered by using access control functionality in
270 .Xr inetd 8 .
271 .Sh EXIT STATUS
272 .Nm
273 exits with
274 .Dv EXIT_SUCCESS
275 .Pq 0
276 on success, and
277 .Dv EXIT_FAILURE
278 .Pq 1
279 on error.
280 .Sh EXAMPLES
281 Before invoking
282 .Nm ,
283 .Xr faith 4
284 interface has to be configured properly.
285 .Bd -literal
286 # sysctl -w net.inet6.ip6.accept_rtadv=0
287 # sysctl -w net.inet6.ip6.forwarding=1
288 # sysctl -w net.inet6.ip6.keepfaith=1
289 # ifconfig faith0 create up
290 # route add -inet6 2001:0db8:4819:ffff:: -prefixlen 96 ::1
291 # route change -inet6 2001:0db8:4819:ffff:: -prefixlen 96 -ifp faith0
292 .Ed
293 .Ss Daemon mode samples
294 To translate
295 .Li telnet
296 service, and provide no local telnet service, invoke
297 .Nm
298 as follows:
299 .Bd -literal
300 # faithd telnet
301 .Ed
302 .Pp
303 If you would like to provide local telnet service via
304 .Xr telnetd 8
305 on
306 .Pa /usr/libexec/telnetd ,
307 use the following command line:
308 .Bd -literal
309 # faithd telnet /usr/libexec/telnetd telnetd
310 .Ed
311 .Pp
312 If you would like to pass extra arguments to the local daemon:
313 .Bd -literal
314 # faithd ftp /usr/libexec/ftpd ftpd -l
315 .Ed
316 .Pp
317 Here are some other examples.
318 You may need
319 .Fl p
320 if the service checks the source port range.
321 .Bd -literal
322 # faithd ssh
323 # faithd telnet /usr/libexec/telnetd telnetd
324 .Ed
325 .Ss inetd mode samples
326 Add the following lines into
327 .Xr inetd.conf 5 .
328 .\"Syntax may vary depending upon your operating system.
329 .Bd -literal
330 telnet stream faith/tcp6 nowait root faithd telnetd
331 ftp stream faith/tcp6 nowait root faithd ftpd -l
332 ssh stream faith/tcp6 nowait root faithd /usr/sbin/sshd -i
333 .Ed
334 .Pp
335 .Xr inetd 8
336 will open listening sockets with enabling kernel TCP relay support.
337 Whenever connection comes in,
338 .Nm
339 will be invoked by
340 .Xr inetd 8 .
341 If it the connection endpoint is in the reserved IPv6 address prefix.
342 .Nm
343 will relay the connection.
344 Otherwise,
345 .Nm
346 will invoke service-specific daemon like
347 .Xr telnetd 8 .
348 .Ss Access control samples
349 The following illustrates a simple
350 .Pa faithd.conf
351 setting.
352 .Bd -literal
353 # permit anyone from 2001:0db8:ffff::/48 to use the translator,
354 # to connect to the following IPv4 destinations:
355 # - any location except 10.0.0.0/8 and 127.0.0.0/8.
356 # Permit no other connections.
357 #
358 2001:0db8:ffff::/48 deny 10.0.0.0/8
359 2001:0db8:ffff::/48 deny 127.0.0.0/8
360 2001:0db8:ffff::/48 permit 0.0.0.0/0
361 .Ed
362 .Sh SEE ALSO
363 .Xr faith 4 ,
364 .Xr route 8 ,
365 .Xr sysctl 8 ,
366 .Pa pkgsrc/net/totd
367 .Rs
368 .%A Jun-ichiro itojun Hagino
369 .%A Kazu Yamamoto
370 .%T "An IPv6-to-IPv4 transport relay translator"
371 .%B RFC 3142
372 .%O ftp://ftp.isi.edu/in-notes/rfc3142.txt
373 .%D June 2001
374 .Re
375 .\"
376 .Sh HISTORY
377 The
378 .Nm
379 command first appeared in WIDE Hydrangea IPv6 protocol stack kit.
380 .\"
381 .Sh SECURITY CONSIDERATIONS
382 It is very insecure to use IP-address based authentication, for connections relayed by
383 .Nm ,
384 and any other TCP relaying services.
385 .Pp
386 Administrators are advised to limit accesses to
387 .Nm
388 using
389 .Pa faithd.conf ,
390 or by using IPv6 packet filters.
391 It is to protect
392 .Nm
393 service from malicious parties and avoid theft of service/bandwidth.
394 IPv6 destination address can be limited by
395 carefully configuring routing entries that points to
396 .Xr faith 4 ,
397 using
398 .Xr route 8 .
399 IPv6 source address needs to be filtered by using packet filters.
400 Documents listed in
401 .Sx SEE ALSO
402 have more discussions on this topic.