1 .\" $KAME: faithd.8,v 1.37 2002/05/09 14:21:23 itojun Exp $
3 .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the project nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
18 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
37 .Nd FAITH IPv6/v4 translator daemon
41 .Op Fl f Ar configfile
43 .Op Ar serverpath Op Ar serverargs
47 utility provides IPv6-to-IPv4 TCP relaying.
48 It can only be used on an IPv4/v6 dual stack router.
54 traffic, it will relay the
58 The destination for the relayed
60 connection will be determined by the last 4 octets of the original
64 .Li 3ffe:0501:4819:ffff::
69 destination address is
70 .Li 3ffe:0501:4819:ffff::0a01:0101 ,
71 the traffic will be relayed to IPv4 destination
77 an IPv6 address prefix must be reserved for mapping IPv4 addresses into.
78 The kernel must be properly configured to route all the TCP connections
79 toward the reserved IPv6 address prefix into the
81 pseudo interface, using the
86 should be used to configure
87 .Dv net.inet6.ip6.keepfaith
91 The router must be configured to capture all the TCP traffic
94 address prefix, by using
102 utility needs special name-to-address translation logic, so that
103 hostnames get resolved into the special
106 For small-scale installations, use
108 For large-scale installations, it is useful to have
109 a DNS server with special address translation support.
110 An implementation called
113 .Pa http://www.vermicelli.pasta.cs.uit.no/software/totd.html .
114 Make sure you do not propagate translated DNS records over to normal
115 DNS, as it can cause severe problems.
119 is invoked as a standalone program,
121 will daemonize itself.
124 utility will listen to
132 is found, it relays the connection.
138 it is not possible to run local TCP daemons for port
142 or other standard mechanisms.
147 you can run local daemons on the router.
150 utility will invoke a local daemon at
152 if the destination address is a local interface address,
153 and will perform translation to IPv4 TCP in other cases.
156 for the arguments for the local daemon.
158 The following options are available:
159 .Bl -tag -width indent
161 Debugging information will be generated using
163 .It Fl f Ar configfile
164 Specify a configuration file for access control.
167 Use privileged TCP port number as source port,
168 for IPv4 TCP connection toward final destination.
171 this flag is not necessary as special program code is supplied.
176 utility will relay both normal and out-of-band TCP data.
177 It is capable of emulating TCP half close as well.
180 utility includes special support for protocols used by
182 When translating the FTP protocol,
184 translates network level addresses in
190 Inactive sessions will be disconnected in 30 minutes,
191 to prevent stale sessions from chewing up resources.
192 This may be inappropriate for some services
193 (should this be configurable?).
200 will handle connections passed from standard input.
201 If the connection endpoint is in the reserved IPv6 address prefix,
203 will relay the connection.
206 will invoke a service-specific daemon like
208 by using the command argument passed from
213 utility determines operation mode by the local TCP port number,
214 and enables special protocol handling whenever necessary/possible.
219 on the FTP port, it will operate as an FTP relay.
221 The operation mode requires special support for
226 To prevent malicious access,
228 implements simple address-based access control.
236 will avoid relaying unwanted traffic.
239 configuration file contains directives of the following format:
242 .Ar src Ns / Ns Ar slen Cm deny Ar dst Ns / Ns Ar dlen
244 If the source address of a query matches
245 .Ar src Ns / Ns Ar slen ,
246 and the translated destination address matches
247 .Ar dst Ns / Ns Ar dlen ,
250 .Ar src Ns / Ns Ar slen Cm permit Ar dst Ns / Ns Ar dlen
252 If the source address of a query matches
253 .Ar src Ns / Ns Ar slen ,
254 and the translated destination address matches
255 .Ar dst Ns / Ns Ar dlen ,
256 permit the connection.
259 The directives are evaluated in sequence,
260 and the first matching entry will be effective.
262 (if we reach the end of the ruleset)
263 the traffic will be denied.
266 traffic may be filtered by using access control functionality in
283 interface has to be configured properly.
285 # sysctl net.inet6.ip6.accept_rtadv=0
286 # sysctl net.inet6.ip6.forwarding=1
287 # sysctl net.inet6.ip6.keepfaith=1
289 # route add -inet6 3ffe:501:4819:ffff:: -prefixlen 96 ::1
290 # route change -inet6 3ffe:501:4819:ffff:: -prefixlen 96 -ifp faith0
292 .Ss Daemon mode samples
295 service, and provide no local telnet service, invoke
302 If you would like to provide local telnet service via
305 .Pa /usr/libexec/telnetd ,
306 use the following command line:
308 # faithd telnet /usr/libexec/telnetd telnetd
311 If you would like to pass extra arguments to the local daemon:
313 # faithd ftp /usr/libexec/ftpd ftpd -l
316 Here are some other examples.
319 if the service checks the source port range.
322 # faithd telnet /usr/libexec/telnetd telnetd
324 .Ss inetd mode samples
325 Add the following lines into
327 Syntax may vary depending upon your operating system.
329 telnet stream tcp6/faith nowait root faithd telnetd
330 ftp stream tcp6/faith nowait root faithd ftpd -l
331 ssh stream tcp6/faith nowait root faithd /usr/sbin/sshd -i
335 will open listening sockets with kernel TCP relay support enabled.
336 Whenever a connection comes in,
340 If the connection endpoint is in the reserved IPv6 address prefix.
343 utility will relay the connection.
346 will invoke service-specific daemon like
348 .Ss Access control samples
349 The following illustrates a simple
353 # permit anyone from 3ffe:501: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.
358 3ffe:501:ffff::/48 deny 10.0.0.0/8
359 3ffe:501:ffff::/48 deny 127.0.0.0/8
360 3ffe:501:ffff::/48 permit 0.0.0.0/0
367 .%A Jun-ichiro itojun Hagino
369 .%T "An IPv6-to-IPv4 transport relay translator"
371 .%U http://tools.ietf.org/html/rfc3142
378 utility first appeared in the WIDE Hydrangea IPv6 protocol stack kit.
381 IPv6 and IPsec support based on the KAME Project (http://www.kame.net/) stack
382 was initially integrated into
384 .Sh SECURITY CONSIDERATIONS
385 It is very insecure to use IP-address based authentication, for connections relayed by
387 and any other TCP relaying services.
389 Administrators are advised to limit accesses to
393 or by using IPv6 packet filters, to protect the
395 service from malicious parties, and to avoid theft of service/bandwidth.
396 IPv6 destination addresses can be limited by
397 carefully configuring routing entries that point to
401 The IPv6 source address needs to be filtered using packet filters.
402 The documents listed in
404 have more information on this topic.