1.\" $NetBSD: faithd.8,v 1.18 2002/05/09 14:24:03 itojun 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 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.Ss Daemon mode 119When 120.Nm 121is invoked as a standalone program, 122.Nm 123will daemonize itself. 124.Nm 125will listen to 126.Tn TCPv6 127port 128.Ar service . 129If 130.Tn TCPv6 131traffic to port 132.Ar service 133is found, it relays the connection. 134.Pp 135Since 136.Nm 137listens to TCP port 138.Ar service , 139it is not possible to run local TCP daemons for port 140.Ar service 141on the router, using 142.Xr inetd 8 143or other standard mechanisms. 144By specifying 145.Ar serverpath 146to 147.Nm Ns , 148you can run local daemons on the router. 149.Nm 150will invoke local daemon at 151.Ar serverpath 152if the destination address is local interface address, 153and will perform translation to IPv4 TCP in other cases. 154You can also specify 155.Ar serverargs 156for the arguments for the local daemon. 157.Pp 158The following options are available: 159.Bl -tag -width indent 160.It Fl d 161Debugging information will be generated using 162.Xr syslog 3 . 163.It Fl f Ar configfile 164Specify a configuration file for access control. 165See below. 166.It Fl p 167Use privileged TCP port number as source port, 168for IPv4 TCP connection toward final destination. 169For relaying 170.Xr ftp 1 171this flag is not necessary as special program code is supplied. 172.El 173.Pp 174.Nm 175will relay both normal and out-of-band TCP data. 176It is capable of emulating TCP half close as well. 177.Nm 178includes special support for protocols used by 179.Xr ftp 1 . 180When translating FTP protocol, 181.Nm 182translates network level addresses in 183.Li PORT/LPRT/EPRT 184and 185.Li PASV/LPSV/EPSV 186commands. 187.Pp 188Inactive sessions will be disconnected in 30 minutes, 189to avoid stale sessions from chewing up resources. 190This may be inappropriate for some of the services 191.Pq should this be configurable? . 192.Ss inetd mode 193When 194.Nm 195is invoked via 196.Xr inetd 8 , 197.Nm 198will handle connection passed from standard input. 199If the connection endpoint is in the reserved IPv6 address prefix, 200.Nm 201will relay the connection. 202Otherwise, 203.Nm 204will invoke service-specific daemon like 205.Xr telnetd 8 , 206by using the command argument passed from 207.Xr inetd 8 . 208.Pp 209.Nm 210determines operation mode by the local TCP port number, 211and enables special protocol handling whenever necessary/possible. 212For example, if 213.Nm 214is invoked via 215.Xr inetd 8 216on 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 223To prevent malicious accesses, 224.Nm 225implements a simple address-based access control. 226With 227.Pa /etc/faithd.conf 228.Po 229or 230.Ar configfile 231specified by 232.Fl f 233.Pc , 234.Nm 235will avoid relaying unwanted traffic. 236The 237.Pa faithd.conf 238contains directives with the following format: 239.Bl -bullet 240.It 241.Xo 242.Ic Ar src/slen Li deny Ar dst/dlen 243.Xc 244.Pp 245If the source address of a query matches 246.Ar src/slen , 247and the translated destination address matches 248.Ar dst/dlen , 249deny the connection. 250.It 251.Xo 252.Ic Ar src/slen Li permit Ar dst/dlen 253.Xc 254.Pp 255If the source address of a query matches 256.Ar src/slen , 257and the translated destination address matches 258.Ar dst/dlen , 259permit the connection. 260.El 261.Pp 262The directives are evaluated in sequence, 263and the first matching entry will be effective. 264If there is no match 265.Pq if we reach the end of the ruleset 266the traffic will be denied. 267.Pp 268With inetd mode, 269traffic may be filtered by using access control functionality in 270.Xr inetd 8 . 271.Sh EXIT STATUS 272.Nm 273exits with 274.Dv EXIT_SUCCESS 275.Pq 0 276on success, and 277.Dv EXIT_FAILURE 278.Pq 1 279on error. 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 320if the service checks the source port range. 321.Bd -literal -offset 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 -offset 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 enabling kernel TCP relay support. 337Whenever connection comes in, 338.Nm 339will be invoked by 340.Xr inetd 8 . 341If it 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 -offset 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. 357# 3583ffe:501:ffff::/48 deny 10.0.0.0/8 3593ffe:501:ffff::/48 deny 127.0.0.0/8 3603ffe:501: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.Rs 367.%A Jun-ichiro itojun Hagino 368.%A Kazu Yamamoto 369.%T "An IPv6-to-IPv4 transport relay translator" 370.%B RFC3142 371.%O ftp://ftp.isi.edu/in-notes/rfc3142.txt 372.%D June 2001 373.Re 374.\" 375.Sh HISTORY 376The 377.Nm 378command first appeared in WIDE Hydrangea IPv6 protocol stack kit. 379.\" 380.Sh SECURITY CONSIDERATIONS 381It is very insecure to use IP-address based authentication, for connections relayed by 382.Nm Ns , 383and any other TCP relaying services. 384.Pp 385Administrators are advised to limit accesses to 386.Nm 387using 388.Pa faithd.conf , 389or by using IPv6 packet filters. 390It is to protect 391.Nm 392service from malicious parties and avoid theft of service/bandwidth. 393IPv6 destination address can be limited by 394carefully configuring routing entries that points to 395.Xr faith 4 , 396using 397.Xr route 8 . 398IPv6 source address needs to be filtered by using packet filters. 399Documents listed in 400.Sx SEE ALSO 401have more discussions on this topic. 402