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