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.3 2006/02/17 19:40:14 swildner 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 RETURN VALUES
 285 The
 286 .Nm
 287 utility exits with
 288 .Dv EXIT_SUCCESS
 289 .Pq 0
 290 on success, and
 291 .Dv EXIT_FAILURE
 292 .Pq 1
 293 on error.
 294 .Sh EXAMPLES
 295 Before invoking
 296 .Nm ,
 297 .Xr faith 4
 298 interface has to be configured properly.
 299 .Bd -literal -offset
 300 # sysctl net.inet6.ip6.accept_rtadv=0
 301 # sysctl net.inet6.ip6.forwarding=1
 302 # sysctl net.inet6.ip6.keepfaith=1
 303 # ifconfig faith0 up
 304 # route add -inet6 3ffe:501:4819:ffff:: -prefixlen 96 ::1
 305 # route change -inet6 3ffe:501:4819:ffff:: -prefixlen 96 -ifp faith0
 306 .Ed
 307 .Ss Daemon mode samples
 308 To translate
 309 .Li telnet
 310 service, and provide no local telnet service, invoke
 311 .Nm
 312 as follows:
 313 .Bd -literal -offset
 314 # faithd telnet
 315 .Ed
 316 .Pp
 317 If you would like to provide local telnet service via
 318 .Xr telnetd 8
 319 on
 320 .Pa /usr/libexec/telnetd ,
 321 use the following command line:
 322 .Bd -literal -offset
 323 # faithd telnet /usr/libexec/telnetd telnetd
 324 .Ed
 325 .Pp
 326 If you would like to pass extra arguments to the local daemon:
 327 .Bd -literal -offset
 328 # faithd ftp /usr/libexec/ftpd ftpd -l
 329 .Ed
 330 .Pp
 331 Here are some other examples.
 332 You may need
 333 .Fl p
 334 to translate rsh/rlogin services.
 335 .Bd -literal -offset
 336 # faithd ssh
 337 # faithd login /usr/libexec/rlogin rlogind
 338 # faithd shell /usr/libexec/rshd rshd
 339 .Ed
 340 .Pp
 341 However, you should be careful when translating rlogin or rsh
 342 connections.
 343 See
 344 .Sx SECURITY CONSIDERATIONS
 345 for more details.
 346 .Ss inetd mode samples
 347 Add the following lines into
 348 .Xr inetd.conf 5 .
 349 Syntax may vary depending upon your operating system.
 350 .Bd -literal -offset
 351 telnet  stream  tcp6/faith  nowait  root  /usr/sbin/faithd  telnetd
 352 ftp     stream  tcp6/faith  nowait  root  /usr/sbin/faithd  ftpd -l
 353 ssh     stream  tcp6/faith  nowait  root  /usr/sbin/faithd  /usr/sbin/sshd -i
 354 .Ed
 355 .Pp
 356 .Xr inetd 8
 357 will open listening sockets with enabling kernel TCP relay support.
 358 Whenever connection comes in,
 359 .Nm
 360 will be invoked by
 361 .Xr inetd 8 .
 362 If it the connection endpoint is in the reserved IPv6 address prefix.
 363 The
 364 .Nm
 365 utility will relay the connection.
 366 Otherwise,
 367 .Nm
 368 will invoke service-specific daemon like
 369 .Xr telnetd 8 .
 370 .Ss Access control samples
 371 The following illustrates a simple
 372 .Pa faithd.conf
 373 setting.
 374 .Bd -literal -offset
 375 # permit anyone from 3ffe:501:ffff::/48 to use the translator,
 376 # to connect to the following IPv4 destinations:
 377 # - any location except 10.0.0.0/8 and 127.0.0.0/8.
 378 # Permit no other connections.
 379 #
 380 3ffe:501:ffff::/48 deny 10.0.0.0/8
 381 3ffe:501:ffff::/48 deny 127.0.0.0/8
 382 3ffe:501:ffff::/48 permit 0.0.0.0/0
 383 .Ed
 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.