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