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