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