7017af2aaf1111d5299ddd2011ef6f7079bca718
[dragonfly.git] / usr.sbin / faithd / faithd.8
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.2 2003/06/17 04:29:53 dillon 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 3ffe:0501:4819:ffff::
68 is reserved for
69 .Nm ,
70 and the
71 .Tn TCPv6
72 destination address is
73 .Li 3ffe:0501:4819:ffff::0a01:0101 ,
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 .Dv 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/ipv6/software.html .
118 Make sure you do not propagate translated DNS records to normal DNS cloud,
119 it is highly harmful.
120 .Pp
121 .Ss Daemon mode
122 When
123 .Nm
124 is invoked as a standalone program,
125 .Nm
126 will daemonize itself.
127 The
128 .Nm
129 utility will listen to
130 .Tn TCPv6
131 port
132 .Ar service .
133 If
134 .Tn TCPv6
135 traffic to port
136 .Ar service
137 is found, it relays the connection.
138 .Pp
139 Since
140 .Nm
141 listens to TCP port
142 .Ar service ,
143 it is not possible to run local TCP daemons for port
144 .Ar service
145 on the router, using
146 .Xr inetd 8
147 or other standard mechanisms.
148 By specifying
149 .Ar serverpath
150 to
151 .Nm ,
152 you can run local daemons on the router.
153 The
154 .Nm
155 utility will invoke local daemon at
156 .Ar serverpath
157 if the destination address is local interface address,
158 and will perform translation to IPv4 TCP in other cases.
159 You can also specify
160 .Ar serverargs
161 for the arguments for the local daemon.
162 .Pp
163 The following options are available:
164 .Bl -tag -width indent
165 .It Fl d
166 Debugging information will be generated using
167 .Xr syslog 3 .
168 .It Fl f Ar configfile
169 Specify a configuration file for access control.
170 See below.
171 .It Fl p
172 Use privileged TCP port number as source port,
173 for IPv4 TCP connection toward final destination.
174 For relaying
175 .Xr ftp 1
176 and
177 .Xr rlogin 1 ,
178 this flag is not necessary as special program code is supplied.
179 .El
180 .Pp
181 The
182 .Nm
183 utility will relay both normal and out-of-band TCP data.
184 It is capable of emulating TCP half close as well.
185 The
186 .Nm
187 utility includes special support for protocols used by
188 .Xr ftp 1
189 and
190 .Xr rlogin 1 .
191 When translating FTP protocol,
192 .Nm
193 translates network level addresses in
194 .Li PORT/LPRT/EPRT
195 and
196 .Li PASV/LPSV/EPSV
197 commands.
198 For RLOGIN protocol,
199 .Nm
200 will relay back connection from
201 .Xr rlogind 8
202 on the server to
203 .Xr rlogin 1
204 on client.
205 .Pp
206 Inactive sessions will be disconnected in 30 minutes,
207 to avoid stale sessions from chewing up resources.
208 This may be inappropriate for some of the services
209 (should this be configurable?).
210 .Ss inetd mode
211 When
212 .Nm
213 is invoked via
214 .Xr inetd 8 ,
215 .Nm
216 will handle connection passed from standard input.
217 If the connection endpoint is in the reserved IPv6 address prefix,
218 .Nm
219 will relay the connection.
220 Otherwise,
221 .Nm
222 will invoke service-specific daemon like
223 .Xr telnetd 8 ,
224 by using the command argument passed from
225 .Xr inetd 8 .
226 .Pp
227 The
228 .Nm
229 utility determines operation mode by the local TCP port number,
230 and enables special protocol handling whenever necessary/possible.
231 For example, if
232 .Nm
233 is invoked via
234 .Xr inetd 8
235 on FTP port, it will operate as a FTP relay.
236 .Pp
237 The operation mode requires special support for
238 .Nm
239 in
240 .Xr inetd 8 .
241 .Ss Access control
242 To prevent malicious accesses,
243 .Nm
244 implements a simple address-based access control.
245 With
246 .Pa /etc/faithd.conf
247 (or
248 .Ar configfile
249 specified by
250 .Fl f ) ,
251 .Nm
252 will avoid relaying unwanted traffic.
253 The
254 .Pa faithd.conf
255 contains directives with the following format:
256 .Bl -bullet
257 .It
258 .Ar src Ns / Ns Ar slen Cm deny Ar dst Ns / Ns Ar dlen
259 .Pp
260 If the source address of a query matches
261 .Ar src Ns / Ns Ar slen ,
262 and the translated destination address matches
263 .Ar dst Ns / Ns Ar dlen ,
264 deny the connection.
265 .It
266 .Ar src Ns / Ns Ar slen Cm permit Ar dst Ns / Ns Ar dlen
267 .Pp
268 If the source address of a query matches
269 .Ar src Ns / Ns Ar slen ,
270 and the translated destination address matches
271 .Ar dst Ns / Ns Ar dlen ,
272 permit the connection.
273 .El
274 .Pp
275 The directives are evaluated in sequence,
276 and the first matching entry will be effective.
277 If there is no match
278 (if we reach the end of the ruleset)
279 the traffic will be denied.
280 .Pp
281 With inetd mode,
282 traffic may be filtered by using access control functionality in
283 .Xr inetd 8 .
284 .Sh EXAMPLES
285 Before invoking
286 .Nm ,
287 .Xr faith 4
288 interface has to be configured properly.
289 .Bd -literal -offset
290 # sysctl net.inet6.ip6.accept_rtadv=0
291 # sysctl net.inet6.ip6.forwarding=1
292 # sysctl net.inet6.ip6.keepfaith=1
293 # ifconfig faith0 up
294 # route add -inet6 3ffe:501:4819:ffff:: -prefixlen 96 ::1
295 # route change -inet6 3ffe:501:4819:ffff:: -prefixlen 96 -ifp faith0
296 .Ed
297 .Ss Daemon mode samples
298 To translate
299 .Li telnet
300 service, and provide no local telnet service, invoke
301 .Nm
302 as follows:
303 .Bd -literal -offset
304 # faithd telnet
305 .Ed
306 .Pp
307 If you would like to provide local telnet service via
308 .Xr telnetd 8
309 on
310 .Pa /usr/libexec/telnetd ,
311 use the following command line:
312 .Bd -literal -offset
313 # faithd telnet /usr/libexec/telnetd telnetd
314 .Ed
315 .Pp
316 If you would like to pass extra arguments to the local daemon:
317 .Bd -literal -offset
318 # faithd ftp /usr/libexec/ftpd ftpd -l
319 .Ed
320 .Pp
321 Here are some other examples.
322 You may need
323 .Fl p
324 to translate rsh/rlogin services.
325 .Bd -literal -offset
326 # faithd ssh
327 # faithd login /usr/libexec/rlogin rlogind
328 # faithd shell /usr/libexec/rshd rshd
329 .Ed
330 .Pp
331 However, you should be careful when translating rlogin or rsh
332 connections.
333 See
334 .Sx SECURITY CONSIDERATIONS
335 for more details.
336 .Ss inetd mode samples
337 Add the following lines into
338 .Xr inetd.conf 5 .
339 Syntax may vary depending upon your operating system.
340 .Bd -literal -offset
341 telnet  stream  tcp6/faith  nowait  root  /usr/sbin/faithd  telnetd
342 ftp     stream  tcp6/faith  nowait  root  /usr/sbin/faithd  ftpd -l
343 ssh     stream  tcp6/faith  nowait  root  /usr/sbin/faithd  /usr/sbin/sshd -i
344 .Ed
345 .Pp
346 .Xr inetd 8
347 will open listening sockets with enabling kernel TCP relay support.
348 Whenever connection comes in,
349 .Nm
350 will be invoked by
351 .Xr inetd 8 .
352 If it the connection endpoint is in the reserved IPv6 address prefix.
353 The
354 .Nm
355 utility will relay the connection.
356 Otherwise,
357 .Nm
358 will invoke service-specific daemon like
359 .Xr telnetd 8 .
360 .Ss Access control samples
361 The following illustrates a simple
362 .Pa faithd.conf
363 setting.
364 .Bd -literal -offset
365 # permit anyone from 3ffe:501:ffff::/48 to use the translator,
366 # to connect to the following IPv4 destinations:
367 # - any location except 10.0.0.0/8 and 127.0.0.0/8.
368 # Permit no other connections.
369 #
370 3ffe:501:ffff::/48 deny 10.0.0.0/8
371 3ffe:501:ffff::/48 deny 127.0.0.0/8
372 3ffe:501:ffff::/48 permit 0.0.0.0/0
373 .Ed
374 .Sh RETURN VALUES
375 The
376 .Nm
377 utility exits with
378 .Dv EXIT_SUCCESS
379 .Pq 0
380 on success, and
381 .Dv EXIT_FAILURE
382 .Pq 1
383 on error.
384 .Sh SEE ALSO
385 .Xr faith 4 ,
386 .Xr route 8 ,
387 .Xr sysctl 8
388 .Rs
389 .%A Jun-ichiro itojun Hagino
390 .%A Kazu Yamamoto
391 .%T "An IPv6-to-IPv4 transport relay translator"
392 .%B RFC3142
393 .%O ftp://ftp.isi.edu/in-notes/rfc3142.txt
394 .%D June 2001
395 .Re
396 .\"
397 .Sh HISTORY
398 The
399 .Nm
400 utility first appeared in WIDE Hydrangea IPv6 protocol stack kit.
401 .\"
402 .Pp
403 IPv6 and IPsec support based on the KAME Project (http://www.kame.net/) stack
404 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.