| blob | 17661c67cf7c4b3dc23abb9403fcf3d7dab90de6 |
1 .\" $KAME: faithd.8,v 1.33 2001/09/05 03:04:20 itojun Exp $
2 .\"
3 .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
4 .\" All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the project nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" $FreeBSD: src/usr.sbin/faithd/faithd.8,v 1.2.2.12 2003/03/12 22:08:14 trhodes Exp $
31 .\" $DragonFly: src/usr.sbin/faithd/faithd.8,v 1.10 2008/08/10 21:29:16 hasso Exp $
32 .\"
33 .Dd May 17, 1998
34 .Dt FAITHD 8
35 .Os
36 .Sh NAME
37 .Nm faithd
38 .Nd FAITH IPv6/v4 translator daemon
39 .Sh SYNOPSIS
40 .Nm
41 .Op Fl dp
42 .Op Fl f Ar configfile
43 .Ar service
44 .Op Ar serverpath Op Ar serverargs
45 .Sh DESCRIPTION
46 The
47 .Nm
48 utility provides IPv6-to-IPv4 TCP relay. It
49 must be used on an IPv4/v6 dual stack router.
50 .Pp
51 When
52 .Nm
53 receives
54 .Tn TCPv6
55 traffic,
56 .Nm
57 will relay the
58 .Tn TCPv6
59 traffic to
60 .Tn TCPv4 .
61 Destination for relayed
62 .Tn TCPv4
63 connection will be determined by the last 4 octets of the original
64 .Tn IPv6
65 destination.
66 For example, if
67 .Li 2001:db8:4819:ffff::
68 is reserved for
69 .Nm ,
70 and the
71 .Tn TCPv6
72 destination address is
73 .Li 2001:db8:4819:ffff::a01:101 ,
74 the traffic will be relayed to IPv4 destination
75 .Li 10.1.1.1 .
76 .Pp
77 To use
78 .Nm
79 translation service,
80 an IPv6 address prefix must be reserved for mapping IPv4 addresses into.
81 Kernel must be properly configured to route all the TCP connection
82 toward the reserved IPv6 address prefix into the
83 .Xr faith 4
84 pseudo interface, by using
85 .Xr route 8
86 command.
87 Also,
88 .Xr sysctl 8
89 should be used to configure
90 .Va net.inet6.ip6.keepfaith
91 to
92 .Dv 1 .
93 .Pp
94 The router must be configured to capture all the TCP traffic
95 toward reserved
96 .Tn IPv6
97 address prefix, by using
98 .Xr route 8
99 and
100 .Xr sysctl 8
101 commands.
102 .Pp
103 The
104 .Nm
105 utility needs a special name-to-address translation logic, so that
106 hostnames gets resolved into special
107 .Tn IPv6
108 address prefix.
109 For small-scale installation, use
110 .Xr hosts 5 .
111 For large-scale installation, it is useful to have
112 a DNS server with special address translation support.
113 An implementation called
114 .Nm totd
115 is available
116 at
117 .Pa http://www.vermicelli.pasta.cs.uit.no/software/totd.html
118 Make sure you do not propagate translated DNS records to normal DNS cloud,
119 it is highly harmful.
120 .Ss Daemon mode
121 When
122 .Nm
123 is invoked as a standalone program,
124 .Nm
125 will daemonize itself.
126 The
127 .Nm
128 utility will listen to
129 .Tn TCPv6
130 port
131 .Ar service .
132 If
133 .Tn TCPv6
134 traffic to port
135 .Ar service
136 is found, it relays the connection.
137 .Pp
138 Since
139 .Nm
140 listens to TCP port
141 .Ar service ,
142 it is not possible to run local TCP daemons for port
143 .Ar service
144 on the router, using
145 .Xr inetd 8
146 or other standard mechanisms.
147 By specifying
148 .Ar serverpath
149 to
150 .Nm ,
151 you can run local daemons on the router.
152 The
153 .Nm
154 utility will invoke local daemon at
155 .Ar serverpath
156 if the destination address is local interface address,
157 and will perform translation to IPv4 TCP in other cases.
158 You can also specify
159 .Ar serverargs
160 for the arguments for the local daemon.
161 .Pp
162 The following options are available:
163 .Bl -tag -width indent
164 .It Fl d
165 Debugging information will be generated using
166 .Xr syslog 3 .
167 .It Fl f Ar configfile
168 Specify a configuration file for access control.
169 See below.
170 .It Fl p
171 Use privileged TCP port number as source port,
172 for IPv4 TCP connection toward final destination.
173 For relaying
174 .Xr ftp 1
175 and
176 .Xr rlogin 1 ,
177 this flag is not necessary as special program code is supplied.
178 .El
179 .Pp
180 The
181 .Nm
182 utility will relay both normal and out-of-band TCP data.
183 It is capable of emulating TCP half close as well.
184 The
185 .Nm
186 utility includes special support for protocols used by
187 .Xr ftp 1
188 and
189 .Xr rlogin 1 .
190 When translating FTP protocol,
191 .Nm
192 translates network level addresses in
193 .Li PORT/LPRT/EPRT
194 and
195 .Li PASV/LPSV/EPSV
196 commands.
197 For RLOGIN protocol,
198 .Nm
199 will relay back connection from
200 .Xr rlogind 8
201 on the server to
202 .Xr rlogin 1
203 on client.
204 .Pp
205 Inactive sessions will be disconnected in 30 minutes,
206 to avoid stale sessions from chewing up resources.
207 This may be inappropriate for some of the services
208 (should this be configurable?).
209 .Ss inetd mode
210 When
211 .Nm
212 is invoked via
213 .Xr inetd 8 ,
214 .Nm
215 will handle connection passed from standard input.
216 If the connection endpoint is in the reserved IPv6 address prefix,
217 .Nm
218 will relay the connection.
219 Otherwise,
220 .Nm
221 will invoke service-specific daemon like
222 .Xr telnetd 8 ,
223 by using the command argument passed from
224 .Xr inetd 8 .
225 .Pp
226 The
227 .Nm
228 utility determines operation mode by the local TCP port number,
229 and enables special protocol handling whenever necessary/possible.
230 For example, if
231 .Nm
232 is invoked via
233 .Xr inetd 8
234 on FTP port, it will operate as a FTP relay.
235 .Pp
236 The operation mode requires special support for
237 .Nm
238 in
239 .Xr inetd 8 .
240 .Ss Access control
241 To prevent malicious accesses,
242 .Nm
243 implements a simple address-based access control.
244 With
245 .Pa /etc/faithd.conf
246 (or
247 .Ar configfile
248 specified by
249 .Fl f ) ,
250 .Nm
251 will avoid relaying unwanted traffic.
252 The
253 .Pa faithd.conf
254 contains directives with the following format:
255 .Bl -bullet
256 .It
257 .Ar src Ns / Ns Ar slen Cm deny Ar dst Ns / Ns Ar dlen
258 .Pp
259 If the source address of a query matches
260 .Ar src Ns / Ns Ar slen ,
261 and the translated destination address matches
262 .Ar dst Ns / Ns Ar dlen ,
263 deny the connection.
264 .It
265 .Ar src Ns / Ns Ar slen Cm permit Ar dst Ns / Ns Ar dlen
266 .Pp
267 If the source address of a query matches
268 .Ar src Ns / Ns Ar slen ,
269 and the translated destination address matches
270 .Ar dst Ns / Ns Ar dlen ,
271 permit the connection.
272 .El
273 .Pp
274 The directives are evaluated in sequence,
275 and the first matching entry will be effective.
276 If there is no match
277 (if we reach the end of the ruleset)
278 the traffic will be denied.
279 .Pp
280 With inetd mode,
281 traffic may be filtered by using access control functionality in
282 .Xr inetd 8 .
283 .Sh EXAMPLES
284 Before invoking
285 .Nm ,
286 .Xr faith 4
287 interface has to be configured properly.
288 .Bd -literal -offset
289 # sysctl net.inet6.ip6.accept_rtadv=0
290 # sysctl net.inet6.ip6.forwarding=1
291 # sysctl net.inet6.ip6.keepfaith=1
292 # ifconfig faith0 up
293 # route add -inet6 2001:db8:4819:ffff:: -prefixlen 96 ::1
294 # route change -inet6 2001:db8:4819:ffff:: -prefixlen 96 -ifp faith0
295 .Ed
296 .Ss Daemon mode samples
297 To translate
298 .Li telnet
299 service, and provide no local telnet service, invoke
300 .Nm
301 as follows:
302 .Bd -literal -offset
303 # faithd telnet
304 .Ed
305 .Pp
306 If you would like to provide local telnet service via
307 .Xr telnetd 8
308 on
309 .Pa /usr/libexec/telnetd ,
310 use the following command line:
311 .Bd -literal -offset
312 # faithd telnet /usr/libexec/telnetd telnetd
313 .Ed
314 .Pp
315 If you would like to pass extra arguments to the local daemon:
316 .Bd -literal -offset
317 # faithd ftp /usr/libexec/ftpd ftpd -l
318 .Ed
319 .Pp
320 Here are some other examples.
321 You may need
322 .Fl p
323 to translate rsh/rlogin services.
324 .Bd -literal -offset
325 # faithd ssh
326 # faithd login /usr/libexec/rlogin rlogind
327 # faithd shell /usr/libexec/rshd rshd
328 .Ed
329 .Pp
330 However, you should be careful when translating rlogin or rsh
331 connections.
332 See
333 .Sx SECURITY CONSIDERATIONS
334 for more details.
335 .Ss inetd mode samples
336 Add the following lines into
337 .Xr inetd.conf 5 .
338 Syntax may vary depending upon your operating system.
339 .Bd -literal -offset
340 telnet stream tcp6/faith nowait root /usr/sbin/faithd telnetd
341 ftp stream tcp6/faith nowait root /usr/sbin/faithd ftpd -l
342 ssh stream tcp6/faith nowait root /usr/sbin/faithd /usr/sbin/sshd -i
343 .Ed
344 .Pp
345 .Xr inetd 8
346 will open listening sockets with enabling kernel TCP relay support.
347 Whenever connection comes in,
348 .Nm
349 will be invoked by
350 .Xr inetd 8 .
351 If it the connection endpoint is in the reserved IPv6 address prefix.
352 The
353 .Nm
354 utility will relay the connection.
355 Otherwise,
356 .Nm
357 will invoke service-specific daemon like
358 .Xr telnetd 8 .
359 .Ss Access control samples
360 The following illustrates a simple
361 .Pa faithd.conf
362 setting.
363 .Bd -literal -offset
364 # permit anyone from 2001:db8:ffff::/48 to use the translator,
365 # to connect to the following IPv4 destinations:
366 # - any location except 10.0.0.0/8 and 127.0.0.0/8.
367 # Permit no other connections.
368 #
369 2001:db8:ffff::/48 deny 10.0.0.0/8
370 2001:db8:ffff::/48 deny 127.0.0.0/8
371 2001:db8:ffff::/48 permit 0.0.0.0/0
372 .Ed
373 .Sh DIAGNOSTICS
374 The
375 .Nm
376 utility exits with
377 .Dv EXIT_SUCCESS
378 .Pq 0
379 on success, and
380 .Dv EXIT_FAILURE
381 .Pq 1
382 on error.
383 .Sh SEE ALSO
384 .Xr faith 4 ,
385 .Xr route 8 ,
386 .Xr sysctl 8
387 .Rs
388 .%A Jun-ichiro itojun Hagino
389 .%A Kazu Yamamoto
390 .%T "An IPv6-to-IPv4 transport relay translator"
391 .%B RFC 3142
392 .%O ftp://ftp.isi.edu/in-notes/rfc3142.txt
393 .%D June 2001
394 .Re
395 .\"
396 .Sh HISTORY
397 The
398 .Nm
399 utility first appeared in WIDE Hydrangea IPv6 protocol stack kit.
400 .\"
401 .Pp
402 IPv6 and IPsec support based on the KAME Project
403 .Pa ( http://www.kame.net/ )
404 stack was initially integrated into
405 .Fx 4.0
406 .Sh SECURITY CONSIDERATIONS
407 It is very insecure to use
408 .Xr rhosts 5
409 and other IP-address based authentication, for connections relayed by
410 .Nm
411 (and any other TCP relaying services).
412 .Pp
413 Administrators are advised to limit accesses to
414 .Nm
415 using
416 .Pa faithd.conf ,
417 or by using IPv6 packet filters.
418 It is to protect
419 .Nm
420 service from malicious parties and avoid theft of service/bandwidth.
421 IPv6 destination address can be limited by
422 carefully configuring routing entries that points to
423 .Xr faith 4 ,
424 using
425 .Xr route 8 .
426 IPv6 source address needs to be filtered by using packet filters.
427 Documents listed in
428 .Sx SEE ALSO
429 have more discussions on this topic.