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