usr.sbin/faithd/README

   1 Configuring FAITH IPv6-to-IPv4 TCP relay
   2
   3 Kazu Yamamoto and Jun-ichiro itojun Hagino
   4 $KAME: README,v 1.8 2001/09/05 03:04:20 itojun Exp $
   5 $FreeBSD: src/usr.sbin/faithd/README,v 1.2.2.3 2002/04/28 05:40:28 suz Exp $
   6 $DragonFly: src/usr.sbin/faithd/README,v 1.2 2003/06/17 04:29:53 dillon Exp $
   7
   8 Introduction
   9 ============
  10
  11 FAITH is a IPv6-to-IPv4 TCP relay.  It performs tcp relay just as some of
  12 firewall-oriented gateway does, but between IPv6 and IPv4 with address
  13 translation.
  14 TCP connections has to be made from IPv6 node to IPv4 node.  FAITH will
  15 not relay connections for the opposite direction.
  16 To perform relays, FAITH daemon needs to be executed on a router between
  17 your local IPv6 site and outside IPv4 network.  The daemon needs to be
  18 invoked per each TCP services (TCP port number).
  19
  20         IPv4 node "dest" = 123.4.5.6
  21                 |
  22         [[[[ outside IPv4 ocean ]]]]
  23                 |
  24         node that runs FAITH-daemon (usually a router)
  25                 |
  26         ==+=====+===+==== IPv6, or IPv4/v6 network in your site ^
  27           |         |                                           | connection
  28         clients   IPv6 node "src"                               |
  29
  30 You will have to allocate an IPv6 address prefix to map IPv4 addresses into.
  31 The following description uses 3ffe:0501:ffff:0000:: as example.
  32 Please use a prefix which belongs to your site.
  33 FAITH will make it possible to make a IPv6 TCP connection From IPv6 node
  34 "src", toward IPv4 node "dest", by specifying FAITH-mapped address
  35 3ffe:0501:ffff:0000::123.4.5.6
  36 (which is, 3ffe:0501:ffff:0000:0000:0000:7b04:0506).
  37 The address mapping can be performed by hand:-), by special nameserver on
  38 the network, or by special resolver on the source node.
  39
  40
  41 Setup
  42 =====
  43
  44 The following example assumes:
  45 - You have assigned 3ffe:0501:ffff:0000:: as FAITH adderss prefix.
  46 - You are willing to provide IPv6-to IPv4 TCP relay for telnet.
  47
  48 <<On the translating router on which faithd runs>>
  49
  50 (1) If you have IPv6 TCP server for the "telnet" service, i.e. telnetd via
  51     inet6d, disable that daemon.  Comment out the line from "inet6d.conf"
  52     and send the HUP signal to "inet6d".
  53
  54 (2) Execute sysctl as root to enable FAITH support in the kernel.
  55
  56         # sysctl -w net.inet6.ip6.keepfaith=1
  57
  58 (3) Route packets toward FAITH prefix into "faith0" interface.
  59
  60         # ifconfig faith0 up
  61         # route add -inet6 3ffe:0501:ffff:0000:: -prefixlen 64 ::1
  62         # route change -inet6 3ffe:0501:ffff:0000:: -prefixlen 64 -ifp faith0
  63
  64 (4) Execute "faithd" by root as follows:
  65
  66         # faithd telnet /usr/libexec/telnetd telnetd
  67
  68     1st argument is a service name you are willing to provide TCP relay.
  69         (it can be specified either by number "23" or by string "telnet")
  70     2nd argument is a path name for local IPv6 TCP server.  If there is a
  71     connection toward the router itself, this program will be invoked.
  72     3rd and the following arguments are arguments for the local IPv6 TCP
  73     server.  (3rd argument is typically the program name without its path.)
  74
  75     More examples:
  76
  77         # faithd login /usr/libexec/rlogin rlogind
  78         # faithd shell /usr/libexec/rshd rshd
  79         # faithd ftpd /usr/libexec/ftpd ftpd -l
  80         # faithd sshd
  81
  82 If inetd(8) on your platform have special support for faithd, it is possible
  83 to setup faithd services via inetd(8).  Consult manpage for details.
  84
  85
  86 <<Routing>>
  87
  88 (4) Make sure that packets whose destinations match the prefix can
  89 reach from the IPv6 host to the translating router.
  90
  91 <<On the IPv6 host>>
  92
  93 There are two ways to translate IPv4 address to IPv6 address:
  94         (a) Faked by DNS
  95         (b) Faked by /etc/hosts.
  96
  97 (5.a) Install "newbie" and set up FAITH mode. See kit/ports/newbie.
  98
  99 (5.b) Add an entry into /etc/hosts so that you can resolve hostname into
 100 faked IPv6 addrss.  For example, add the following line for www.netbsd.org:
 101
 102         3ffe:0501:ffff:0000::140.160.140.252    www.netbsd.org
 103
 104 <<On the translating router on which faithd runs.>>
 105
 106 (6) To see if "faithd" works, watch "/var/log/daemon". Note: please
 107 setup "/etc/syslog.conf" so that LOG_DAEMON messages are to be stored
 108 in "/var/log/daemon".
 109
 110         <e.g.>
 111         daemon.*   /var/log/daemon
 112
 113
 114 Access control
 115 ==============
 116
 117 Since faithd implements TCP relaying service, it is critical to implement
 118 proper access control to cope with malicious use.  Bad guy may try to
 119 use your relay router to circumvent access controls, or may try to
 120 abuse your network (like sending SPAMs from IPv4 address that belong to you).
 121 Install IPv6 packet filter directives that would reject traffic from
 122 unwanted source.  If you are using inetd-based setup, you may be able to
 123 use access control mechanisms in inetd.
 124
 125
 126 Advanced configuration
 127 ======================
 128
 129 If you would like to restrict IPv4 destination for translation, you may
 130 want to do the following:
 131
 132         # route add -inet6 3ffe:0501:ffff:0000::123.0.0.0 -prefixlen 104 ::1
 133         # route change -inet6 3ffe:0501:ffff:0000::123.0.0.0 -prefixlen 104 \
 134                 -ifp faith0
 135
 136 By this way, you can restrict IPv4 destination to 123.0.0.0/8.
 137 You may also want to reject packets toward 3ffe:0501:ffff:0000::/64 which
 138 is not in 3ffe:0501:ffff:0000::123.0.0.0/104.  This will be left as excerside
 139 for the reader.
 140
 141 By doing this, you will be able to provide your IPv4 web server to outside
 142 IPv6 customers, without risks of unwanted open relays.
 143
 144         [[[[ IPv6 network outside ]]]]                  |
 145                 |                                       | connection
 146         node that runs FAITH-daemon (usually a router)  v
 147                 |
 148         ========+======== IPv4/v6 network in your site
 149                 |                       (123.0.0.0/8)
 150         IPv4 web server