1.\" $NetBSD: faithd.8,v 1.28 2010/01/15 19:19:32 joerg 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 January 9, 2010 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 45The 46.Nm 47utility provides IPv6-to-IPv4 TCP relaying. 48It can only be used on an IPv4/v6 dual stack router. 49.Pp 50When 51.Nm 52receives 53.Tn TCPv6 54traffic, it will relay the 55.Tn TCPv6 56traffic to 57.Tn TCPv4 . 58The destination for the relayed 59.Tn TCPv4 60connection will be determined by the last 4 octets of the original 61.Tn IPv6 62destination. 63For example, if 64.Li 2001:0db8:4819:ffff:: 65is reserved for 66.Nm , 67and the 68.Tn TCPv6 69destination address is 70.Li 2001:0db8:4819:ffff::0a01:0101 , 71the traffic will be relayed to IPv4 destination 72.Li 10.1.1.1 . 73.Pp 74To use the 75.Nm 76translation service, 77an IPv6 address prefix must be reserved for mapping IPv4 addresses into. 78The kernel must be properly configured to route all the TCP connections 79toward the reserved IPv6 address prefix into the 80.Xr faith 4 81pseudo interface, using the 82.Xr route 8 83command. 84Also, 85.Xr sysctl 8 86should be used to configure 87.Dv net.inet6.ip6.keepfaith 88to 89.Dv 1 . 90.Pp 91The router must be configured to capture all the TCP traffic 92for the reserved 93.Tn IPv6 94address prefix, by using 95.Xr route 8 96and 97.Xr sysctl 8 98commands. 99.Pp 100The 101.Nm 102utility needs special name-to-address translation logic, so that 103hostnames gets resolved into the special 104.Tn IPv6 105address prefix. 106For small-scale installations, use 107.Xr hosts 5 ; 108For large-scale installations, it is useful to have 109a DNS server with special address translation support. 110An implementation called 111.Nm totd 112is available at 113.Pa http://www.vermicelli.pasta.cs.uit.no/software/totd.html . 114Make sure you do not propagate translated DNS records over to normal 115DNS, as it can cause severe problems. 116.Ss Daemon mode 117When 118.Nm 119is invoked as a standalone program, 120.Nm 121will daemonize itself. 122.Nm 123will listen to 124.Tn TCPv6 125port 126.Ar service . 127If 128.Tn TCPv6 129traffic to port 130.Ar service 131is found, it relays the connection. 132.Pp 133Since 134.Nm 135listens to TCP port 136.Ar service , 137it is not possible to run local TCP daemons for port 138.Ar service 139on the router, using 140.Xr inetd 8 141or other standard mechanisms. 142By specifying 143.Ar serverpath 144to 145.Nm , 146you can run local daemons on the router. 147The 148.Nm 149utility will invoke ia local daemon at 150.Ar serverpath 151if the destination address is a local interface address, 152and will perform translation to IPv4 TCP in other cases. 153You can also specify 154.Ar serverargs 155for the arguments for the local daemon. 156.Pp 157The following options are available: 158.Bl -tag -width indent 159.It Fl d 160Debugging information will be generated using 161.Xr syslog 3 . 162.It Fl f Ar configfile 163Specify a configuration file for access control. 164See below. 165.It Fl p 166Use privileged TCP port number as source port, 167for IPv4 TCP connection toward final destination. 168For relaying 169.Xr ftp 1 170this flag is not necessary as special program code is supplied. 171.El 172.Pp 173.Nm 174will relay both normal and out-of-band TCP data. 175It is capable of emulating TCP half close as well. 176.Nm 177includes special support for protocols used by 178.Xr ftp 1 . 179When translating the FTP protocol, 180.Nm 181translates network level addresses in 182.Li PORT/LPRT/EPRT 183and 184.Li PASV/LPSV/EPSV 185commands. 186.Pp 187Inactive sessions will be disconnected in 30 minutes, 188to prevent stale sessions from chewing up resources. 189This may be inappropriate for some services 190.Pq should this be configurable? . 191.Ss inetd mode 192When 193.Nm 194is invoked via 195.Xr inetd 8 , 196.Nm 197will handle connections passed from standard input. 198If the connection endpoint is in the reserved IPv6 address prefix, 199.Nm 200will relay the connection. 201Otherwise, 202.Nm 203will invoke a service-specific daemon like 204.Xr telnetd 8 , 205by using the command argument passed from 206.Xr inetd 8 . 207.Pp 208.Nm 209determines operation mode by the local TCP port number, 210and enables special protocol handling whenever necessary/possible. 211For example, if 212.Nm 213is invoked via 214.Xr inetd 8 215on the FTP port, it will operate as an FTP relay. 216.\".Pp 217.\"The operation mode requires special support for 218.\".Nm 219.\"in 220.\".Xr inetd 8 . 221.Ss Access control 222To prevent malicious access, 223.Nm 224implements a simple address-based access control. 225With 226.Pa /etc/faithd.conf 227.Po 228or 229.Ar configfile 230specified by 231.Fl f 232.Pc , 233.Nm 234will avoid relaying unwanted traffic. 235The 236.Pa faithd.conf 237configuration file contains directives of the following format: 238.Bl -bullet 239.It 240.Xo 241.Ar src/slen Li deny Ar dst/dlen 242.Xc 243.Pp 244If the source address of a query matches 245.Ar src/slen , 246and the translated destination address matches 247.Ar dst/dlen , 248deny the connection. 249.It 250.Xo 251.Ar src/slen Li permit Ar dst/dlen 252.Xc 253.Pp 254If the source address of a query matches 255.Ar src/slen , 256and the translated destination address matches 257.Ar dst/dlen , 258permit the connection. 259.El 260.Pp 261The directives are evaluated in sequence, 262and the first matching entry will be effective. 263If there is no match 264.Pq if we reach the end of the ruleset 265the traffic will be denied. 266.Pp 267With inetd mode, 268traffic may be filtered by using access control functionality in 269.Xr inetd 8 . 270.Sh EXIT STATUS 271.Nm 272exits with 273.Dv EXIT_SUCCESS 274.Pq 0 275on success, and 276.Dv EXIT_FAILURE 277.Pq 1 278on error. 279.Sh EXAMPLES 280Before invoking 281.Nm , 282the 283.Xr faith 4 284interface 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 294To translate 295.Li telnet 296service, and provide no local telnet service, invoke 297.Nm 298as follows: 299.Bd -literal 300# faithd telnet 301.Ed 302.Pp 303If you would like to provide local telnet service via 304.Xr telnetd 8 305on 306.Pa /usr/libexec/telnetd , 307use the following command line: 308.Bd -literal 309# faithd telnet /usr/libexec/telnetd telnetd 310.Ed 311.Pp 312If 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 317Here are some other examples. 318You may need 319.Fl p 320if 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 326Add the following lines into 327.Xr inetd.conf 5 . 328.\"Syntax may vary depending upon your operating system. 329.Bd -literal 330telnet stream faith/tcp6 nowait root faithd telnetd 331ftp stream faith/tcp6 nowait root faithd ftpd -l 332ssh stream faith/tcp6 nowait root faithd /usr/sbin/sshd -i 333.Ed 334.Pp 335.Xr inetd 8 336will open listening sockets with kernel TCP relay support enabled. 337Whenever a connection comes in, 338.Nm 339will be invoked by 340.Xr inetd 8 . 341If the connection endpoint is in the reserved IPv6 address prefix. 342.Nm 343will relay the connection. 344Otherwise, 345.Nm 346will invoke service-specific daemon like 347.Xr telnetd 8 . 348.Ss Access control samples 349The following illustrates a simple 350.Pa faithd.conf 351setting. 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# 3582001:0db8:ffff::/48 deny 10.0.0.0/8 3592001:0db8:ffff::/48 deny 127.0.0.0/8 3602001: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.%U ftp://ftp.isi.edu/in-notes/rfc3142.txt 373.%D June 2001 374.Re 375.\" 376.Sh HISTORY 377The 378.Nm 379utility first appeared in the WIDE Hydrangea IPv6 protocol stack kit. 380.\" 381.Sh SECURITY CONSIDERATIONS 382It is very insecure to use IP-address based authentication, for connections relayed by 383.Nm , 384and any other TCP relaying services. 385.Pp 386Administrators are advised to limit accesses to 387.Nm 388using 389.Pa faithd.conf , 390or by using IPv6 packet filters, to protect the 391.Nm 392service from malicious parties, and to avoid theft of service/bandwidth. 393IPv6 destination addresses can be limited by 394carefully configuring routing entries that point to 395.Xr faith 4 , 396using 397.Xr route 8 . 398The IPv6 source address needs to be filtered using packet filters. 399The documents listed in 400.Sx SEE ALSO 401have more information on this topic. 402