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 relay.
48 It must be used on an IPv4/v6 dual stack router.
60 Destination for relayed
62 connection will be determined by the last 4 octets of the original
66 .Li 3ffe:0501:4819:ffff::
71 destination address is
72 .Li 3ffe:0501:4819:ffff::0a01:0101 ,
73 the traffic will be relayed to IPv4 destination
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
83 pseudo interface, by using
88 should be used to configure
89 .Dv net.inet6.ip6.keepfaith
93 The router must be configured to capture all the TCP traffic
96 address prefix, by using
104 utility needs a special name-to-address translation logic, so that
105 hostnames gets resolved into special
108 For small-scale installation, use
110 For large-scale installation, it is useful to have
111 a DNS server with special address translation support.
112 An implementation called
116 .Pa http://www.vermicelli.pasta.cs.uit.no/ipv6/software.html .
117 Make sure you do not propagate translated DNS records to normal DNS cloud,
118 it is highly harmful.
122 is invoked as a standalone program,
124 will daemonize itself.
127 utility will listen to
135 is found, it relays the connection.
141 it is not possible to run local TCP daemons for port
145 or other standard mechanisms.
150 you can run local daemons on the router.
153 utility will invoke local daemon at
155 if the destination address is local interface address,
156 and will perform translation to IPv4 TCP in other cases.
159 for the arguments for the local daemon.
161 The following options are available:
162 .Bl -tag -width indent
164 Debugging information will be generated using
166 .It Fl f Ar configfile
167 Specify a configuration file for access control.
170 Use privileged TCP port number as source port,
171 for IPv4 TCP connection toward final destination.
174 this flag is not necessary as special program code is supplied.
179 utility will relay both normal and out-of-band TCP data.
180 It is capable of emulating TCP half close as well.
183 utility includes special support for protocols used by
185 When translating FTP protocol,
187 translates network level addresses in
193 Inactive sessions will be disconnected in 30 minutes,
194 to avoid stale sessions from chewing up resources.
195 This may be inappropriate for some of the services
196 (should this be configurable?).
203 will handle connection passed from standard input.
204 If the connection endpoint is in the reserved IPv6 address prefix,
206 will relay the connection.
209 will invoke service-specific daemon like
211 by using the command argument passed from
216 utility determines operation mode by the local TCP port number,
217 and enables special protocol handling whenever necessary/possible.
222 on FTP port, it will operate as a FTP relay.
224 The operation mode requires special support for
229 To prevent malicious accesses,
231 implements a simple address-based access control.
239 will avoid relaying unwanted traffic.
242 contains directives with the following format:
245 .Ar src Ns / Ns Ar slen Cm deny Ar dst Ns / Ns Ar dlen
247 If the source address of a query matches
248 .Ar src Ns / Ns Ar slen ,
249 and the translated destination address matches
250 .Ar dst Ns / Ns Ar dlen ,
253 .Ar src Ns / Ns Ar slen Cm permit Ar dst Ns / Ns Ar dlen
255 If the source address of a query matches
256 .Ar src Ns / Ns Ar slen ,
257 and the translated destination address matches
258 .Ar dst Ns / Ns Ar dlen ,
259 permit the connection.
262 The directives are evaluated in sequence,
263 and the first matching entry will be effective.
265 (if we reach the end of the ruleset)
266 the traffic will be denied.
269 traffic may be filtered by using access control functionality in
285 interface has to be configured properly.
287 # sysctl net.inet6.ip6.accept_rtadv=0
288 # sysctl net.inet6.ip6.forwarding=1
289 # sysctl net.inet6.ip6.keepfaith=1
291 # route add -inet6 3ffe:501:4819:ffff:: -prefixlen 96 ::1
292 # route change -inet6 3ffe:501:4819:ffff:: -prefixlen 96 -ifp faith0
294 .Ss Daemon mode samples
297 service, and provide no local telnet service, invoke
304 If you would like to provide local telnet service via
307 .Pa /usr/libexec/telnetd ,
308 use the following command line:
310 # faithd telnet /usr/libexec/telnetd telnetd
313 If you would like to pass extra arguments to the local daemon:
315 # faithd ftp /usr/libexec/ftpd ftpd -l
318 Here are some other examples.
321 if the service checks the source port range.
324 # faithd telnet /usr/libexec/telnetd telnetd
326 .Ss inetd mode samples
327 Add the following lines into
329 Syntax may vary depending upon your operating system.
331 telnet stream tcp6/faith nowait root faithd telnetd
332 ftp stream tcp6/faith nowait root faithd ftpd -l
333 ssh stream tcp6/faith nowait root faithd /usr/sbin/sshd -i
337 will open listening sockets with enabling kernel TCP relay support.
338 Whenever connection comes in,
342 If it the connection endpoint is in the reserved IPv6 address prefix.
345 utility will relay the connection.
348 will invoke service-specific daemon like
350 .Ss Access control samples
351 The following illustrates a simple
355 # permit anyone from 3ffe:501:ffff::/48 to use the translator,
356 # to connect to the following IPv4 destinations:
357 # - any location except 10.0.0.0/8 and 127.0.0.0/8.
358 # Permit no other connections.
360 3ffe:501:ffff::/48 deny 10.0.0.0/8
361 3ffe:501:ffff::/48 deny 127.0.0.0/8
362 3ffe:501:ffff::/48 permit 0.0.0.0/0
369 .%A Jun-ichiro itojun Hagino
371 .%T "An IPv6-to-IPv4 transport relay translator"
373 .%O ftp://ftp.isi.edu/in-notes/rfc3142.txt
380 utility first appeared in WIDE Hydrangea IPv6 protocol stack kit.
383 IPv6 and IPsec support based on the KAME Project (http://www.kame.net/) stack
384 was initially integrated into
386 .Sh SECURITY CONSIDERATIONS
387 It is very insecure to use IP-address based authentication, for connections relayed by
389 and any other TCP relaying services.
391 Administrators are advised to limit accesses to
395 or by using IPv6 packet filters.
398 service from malicious parties and avoid theft of service/bandwidth.
399 IPv6 destination address can be limited by
400 carefully configuring routing entries that points to
404 IPv6 source address needs to be filtered by using packet filters.
407 have more discussions on this topic.