usr.sbin/faithd/faithd.8

   1 .\"     $KAME: faithd.8,v 1.37 2002/05/09 14:21:23 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$
  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.
  48 It 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 3ffe:0501:4819:ffff::
  67 is reserved for
  68 .Nm ,
  69 and the
  70 .Tn TCPv6
  71 destination address is
  72 .Li 3ffe:0501:4819:ffff::0a01:0101 ,
  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 .Dv 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/ipv6/software.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 this flag is not necessary as special program code is supplied.
 175 .El
 176 .Pp
 177 The
 178 .Nm
 179 utility will relay both normal and out-of-band TCP data.
 180 It is capable of emulating TCP half close as well.
 181 The
 182 .Nm
 183 utility includes special support for protocols used by
 184 .Xr ftp 1 .
 185 When translating FTP protocol,
 186 .Nm
 187 translates network level addresses in
 188 .Li PORT/LPRT/EPRT
 189 and
 190 .Li PASV/LPSV/EPSV
 191 commands.
 192 .Pp
 193 Inactive sessions will be disconnected in 30 minutes,
 194 to avoid stale sessions from chewing up resources.
 195 This may be inappropriate for some of the services
 196 (should this be configurable?).
 197 .Ss inetd mode
 198 When
 199 .Nm
 200 is invoked via
 201 .Xr inetd 8 ,
 202 .Nm
 203 will handle connection passed from standard input.
 204 If the connection endpoint is in the reserved IPv6 address prefix,
 205 .Nm
 206 will relay the connection.
 207 Otherwise,
 208 .Nm
 209 will invoke service-specific daemon like
 210 .Xr telnetd 8 ,
 211 by using the command argument passed from
 212 .Xr inetd 8 .
 213 .Pp
 214 The
 215 .Nm
 216 utility determines operation mode by the local TCP port number,
 217 and enables special protocol handling whenever necessary/possible.
 218 For example, if
 219 .Nm
 220 is invoked via
 221 .Xr inetd 8
 222 on FTP port, it will operate as a FTP relay.
 223 .Pp
 224 The operation mode requires special support for
 225 .Nm
 226 in
 227 .Xr inetd 8 .
 228 .Ss Access control
 229 To prevent malicious accesses,
 230 .Nm
 231 implements a simple address-based access control.
 232 With
 233 .Pa /etc/faithd.conf
 234 (or
 235 .Ar configfile
 236 specified by
 237 .Fl f ) ,
 238 .Nm
 239 will avoid relaying unwanted traffic.
 240 The
 241 .Pa faithd.conf
 242 contains directives with the following format:
 243 .Bl -bullet
 244 .It
 245 .Ar src Ns / Ns Ar slen Cm deny Ar dst Ns / Ns Ar dlen
 246 .Pp
 247 If the source address of a query matches
 248 .Ar src Ns / Ns Ar slen ,
 249 and the translated destination address matches
 250 .Ar dst Ns / Ns Ar dlen ,
 251 deny the connection.
 252 .It
 253 .Ar src Ns / Ns Ar slen Cm permit Ar dst Ns / Ns Ar dlen
 254 .Pp
 255 If the source address of a query matches
 256 .Ar src Ns / Ns Ar slen ,
 257 and the translated destination address matches
 258 .Ar dst Ns / Ns Ar dlen ,
 259 permit the connection.
 260 .El
 261 .Pp
 262 The directives are evaluated in sequence,
 263 and the first matching entry will be effective.
 264 If there is no match
 265 (if we reach the end of the ruleset)
 266 the traffic will be denied.
 267 .Pp
 268 With inetd mode,
 269 traffic may be filtered by using access control functionality in
 270 .Xr inetd 8 .
 271 .Sh EXIT STATUS
 272 The
 273 .Nm
 274 utility exits with
 275 .Dv EXIT_SUCCESS
 276 .Pq 0
 277 on success, and
 278 .Dv EXIT_FAILURE
 279 .Pq 1
 280 on error.
 281 .Sh EXAMPLES
 282 Before invoking
 283 .Nm ,
 284 .Xr faith 4
 285 interface has to be configured properly.
 286 .Bd -literal -offset
 287 # sysctl net.inet6.ip6.accept_rtadv=0
 288 # sysctl net.inet6.ip6.forwarding=1
 289 # sysctl net.inet6.ip6.keepfaith=1
 290 # ifconfig faith0 up
 291 # route add -inet6 3ffe:501:4819:ffff:: -prefixlen 96 ::1
 292 # route change -inet6 3ffe:501:4819:ffff:: -prefixlen 96 -ifp faith0
 293 .Ed
 294 .Ss Daemon mode samples
 295 To translate
 296 .Li telnet
 297 service, and provide no local telnet service, invoke
 298 .Nm
 299 as follows:
 300 .Bd -literal -offset
 301 # faithd telnet
 302 .Ed
 303 .Pp
 304 If you would like to provide local telnet service via
 305 .Xr telnetd 8
 306 on
 307 .Pa /usr/libexec/telnetd ,
 308 use the following command line:
 309 .Bd -literal -offset
 310 # faithd telnet /usr/libexec/telnetd telnetd
 311 .Ed
 312 .Pp
 313 If you would like to pass extra arguments to the local daemon:
 314 .Bd -literal -offset
 315 # faithd ftp /usr/libexec/ftpd ftpd -l
 316 .Ed
 317 .Pp
 318 Here are some other examples.
 319 You may need
 320 .Fl p
 321 if the service checks the source port range.
 322 .Bd -literal -offset
 323 # faithd ssh
 324 # faithd telnet /usr/libexec/telnetd telnetd
 325 .Ed
 326 .Ss inetd mode samples
 327 Add the following lines into
 328 .Xr inetd.conf 5 .
 329 Syntax may vary depending upon your operating system.
 330 .Bd -literal -offset
 331 telnet  stream  tcp6/faith  nowait  root  faithd  telnetd
 332 ftp     stream  tcp6/faith  nowait  root  faithd  ftpd -l
 333 ssh     stream  tcp6/faith  nowait  root  faithd  /usr/sbin/sshd -i
 334 .Ed
 335 .Pp
 336 .Xr inetd 8
 337 will open listening sockets with enabling kernel TCP relay support.
 338 Whenever connection comes in,
 339 .Nm
 340 will be invoked by
 341 .Xr inetd 8 .
 342 If it the connection endpoint is in the reserved IPv6 address prefix.
 343 The
 344 .Nm
 345 utility will relay the connection.
 346 Otherwise,
 347 .Nm
 348 will invoke service-specific daemon like
 349 .Xr telnetd 8 .
 350 .Ss Access control samples
 351 The following illustrates a simple
 352 .Pa faithd.conf
 353 setting.
 354 .Bd -literal -offset
 355 # permit anyone from 3ffe:501:ffff::/48 to use the translator,
 356 # to connect to the following IPv4 destinations:
 357 # - any location except 10.0.0.0/8 and 127.0.0.0/8.
 358 # Permit no other connections.
 359 #
 360 3ffe:501:ffff::/48 deny 10.0.0.0/8
 361 3ffe:501:ffff::/48 deny 127.0.0.0/8
 362 3ffe:501:ffff::/48 permit 0.0.0.0/0
 363 .Ed
 364 .Sh SEE ALSO
 365 .Xr faith 4 ,
 366 .Xr route 8 ,
 367 .Xr sysctl 8
 368 .Rs
 369 .%A Jun-ichiro itojun Hagino
 370 .%A Kazu Yamamoto
 371 .%T "An IPv6-to-IPv4 transport relay translator"
 372 .%B RFC3142
 373 .%O ftp://ftp.isi.edu/in-notes/rfc3142.txt
 374 .%D June 2001
 375 .Re
 376 .\"
 377 .Sh HISTORY
 378 The
 379 .Nm
 380 utility first appeared in WIDE Hydrangea IPv6 protocol stack kit.
 381 .\"
 382 .Pp
 383 IPv6 and IPsec support based on the KAME Project (http://www.kame.net/) stack
 384 was initially integrated into
 385 .Fx 4.0
 386 .Sh SECURITY CONSIDERATIONS
 387 It is very insecure to use IP-address based authentication, for connections relayed by
 388 .Nm ,
 389 and any other TCP relaying services.
 390 .Pp
 391 Administrators are advised to limit accesses to
 392 .Nm
 393 using
 394 .Pa faithd.conf ,
 395 or by using IPv6 packet filters.
 396 It is to protect
 397 .Nm
 398 service from malicious parties and avoid theft of service/bandwidth.
 399 IPv6 destination address can be limited by
 400 carefully configuring routing entries that points to
 401 .Xr faith 4 ,
 402 using
 403 .Xr route 8 .
 404 IPv6 source address needs to be filtered by using packet filters.
 405 Documents listed in
 406 .Sx SEE ALSO
 407 have more discussions on this topic.