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.5 2006/03/26 22:56:58 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 .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 3ffe:501:4819:ffff:: -prefixlen 96 ::1
 294 # route change -inet6 3ffe:501: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 3ffe:501: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 3ffe:501:ffff::/48 deny 10.0.0.0/8
 370 3ffe:501:ffff::/48 deny 127.0.0.0/8
 371 3ffe:501: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 RFC3142
 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 (http://www.kame.net/) stack
 403 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.