402 lines
9.7 KiB
Groff
402 lines
9.7 KiB
Groff
.\" $NetBSD: faithd.8,v 1.29 2012/03/15 22:35:03 njoly Exp $
|
|
.\" $KAME: faithd.8,v 1.37 2002/05/09 14:21:23 itojun Exp $
|
|
.\"
|
|
.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of the project nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.Dd January 9, 2010
|
|
.Dt FAITHD 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm faithd
|
|
.Nd FAITH IPv6/v4 translator daemon
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl dp
|
|
.Op Fl f Ar configfile
|
|
.Ar service
|
|
.Op Ar serverpath Op Ar serverargs
|
|
.Nm
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility provides IPv6-to-IPv4 TCP relaying.
|
|
It can only be used on an IPv4/v6 dual stack router.
|
|
.Pp
|
|
When
|
|
.Nm
|
|
receives
|
|
.Tn TCPv6
|
|
traffic, it will relay the
|
|
.Tn TCPv6
|
|
traffic to
|
|
.Tn TCPv4 .
|
|
The destination for the relayed
|
|
.Tn TCPv4
|
|
connection will be determined by the last 4 octets of the original
|
|
.Tn IPv6
|
|
destination.
|
|
For example, if
|
|
.Li 2001:0db8:4819:ffff::
|
|
is reserved for
|
|
.Nm ,
|
|
and the
|
|
.Tn TCPv6
|
|
destination address is
|
|
.Li 2001:0db8:4819:ffff::0a01:0101 ,
|
|
the traffic will be relayed to IPv4 destination
|
|
.Li 10.1.1.1 .
|
|
.Pp
|
|
To use the
|
|
.Nm
|
|
translation service,
|
|
an IPv6 address prefix must be reserved for mapping IPv4 addresses into.
|
|
The kernel must be properly configured to route all the TCP connections
|
|
toward the reserved IPv6 address prefix into the
|
|
.Xr faith 4
|
|
pseudo interface, using the
|
|
.Xr route 8
|
|
command.
|
|
Also,
|
|
.Xr sysctl 8
|
|
should be used to configure
|
|
.Dv net.inet6.ip6.keepfaith
|
|
to
|
|
.Dv 1 .
|
|
.Pp
|
|
The router must be configured to capture all the TCP traffic
|
|
for the reserved
|
|
.Tn IPv6
|
|
address prefix, by using
|
|
.Xr route 8
|
|
and
|
|
.Xr sysctl 8
|
|
commands.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility needs special name-to-address translation logic, so that
|
|
hostnames gets resolved into the special
|
|
.Tn IPv6
|
|
address prefix.
|
|
For small-scale installations, use
|
|
.Xr hosts 5 ;
|
|
For large-scale installations, it is useful to have
|
|
a DNS server with special address translation support.
|
|
An implementation called
|
|
.Nm totd
|
|
is available at
|
|
.Lk http://www.dillema.net/software/totd.html .
|
|
Make sure you do not propagate translated DNS records over to normal
|
|
DNS, as it can cause severe problems.
|
|
.Ss Daemon mode
|
|
When
|
|
.Nm
|
|
is invoked as a standalone program,
|
|
.Nm
|
|
will daemonize itself.
|
|
.Nm
|
|
will listen to
|
|
.Tn TCPv6
|
|
port
|
|
.Ar service .
|
|
If
|
|
.Tn TCPv6
|
|
traffic to port
|
|
.Ar service
|
|
is found, it relays the connection.
|
|
.Pp
|
|
Since
|
|
.Nm
|
|
listens to TCP port
|
|
.Ar service ,
|
|
it is not possible to run local TCP daemons for port
|
|
.Ar service
|
|
on the router, using
|
|
.Xr inetd 8
|
|
or other standard mechanisms.
|
|
By specifying
|
|
.Ar serverpath
|
|
to
|
|
.Nm ,
|
|
you can run local daemons on the router.
|
|
The
|
|
.Nm
|
|
utility will invoke ia local daemon at
|
|
.Ar serverpath
|
|
if the destination address is a local interface address,
|
|
and will perform translation to IPv4 TCP in other cases.
|
|
You can also specify
|
|
.Ar serverargs
|
|
for the arguments for the local daemon.
|
|
.Pp
|
|
The following options are available:
|
|
.Bl -tag -width indent
|
|
.It Fl d
|
|
Debugging information will be generated using
|
|
.Xr syslog 3 .
|
|
.It Fl f Ar configfile
|
|
Specify a configuration file for access control.
|
|
See below.
|
|
.It Fl p
|
|
Use privileged TCP port number as source port,
|
|
for IPv4 TCP connection toward final destination.
|
|
For relaying
|
|
.Xr ftp 1
|
|
this flag is not necessary as special program code is supplied.
|
|
.El
|
|
.Pp
|
|
.Nm
|
|
will relay both normal and out-of-band TCP data.
|
|
It is capable of emulating TCP half close as well.
|
|
.Nm
|
|
includes special support for protocols used by
|
|
.Xr ftp 1 .
|
|
When translating the FTP protocol,
|
|
.Nm
|
|
translates network level addresses in
|
|
.Li PORT/LPRT/EPRT
|
|
and
|
|
.Li PASV/LPSV/EPSV
|
|
commands.
|
|
.Pp
|
|
Inactive sessions will be disconnected in 30 minutes,
|
|
to prevent stale sessions from chewing up resources.
|
|
This may be inappropriate for some services
|
|
.Pq should this be configurable? .
|
|
.Ss inetd mode
|
|
When
|
|
.Nm
|
|
is invoked via
|
|
.Xr inetd 8 ,
|
|
.Nm
|
|
will handle connections passed from standard input.
|
|
If the connection endpoint is in the reserved IPv6 address prefix,
|
|
.Nm
|
|
will relay the connection.
|
|
Otherwise,
|
|
.Nm
|
|
will invoke a service-specific daemon like
|
|
.Xr telnetd 8 ,
|
|
by using the command argument passed from
|
|
.Xr inetd 8 .
|
|
.Pp
|
|
.Nm
|
|
determines operation mode by the local TCP port number,
|
|
and enables special protocol handling whenever necessary/possible.
|
|
For example, if
|
|
.Nm
|
|
is invoked via
|
|
.Xr inetd 8
|
|
on the FTP port, it will operate as an FTP relay.
|
|
.\".Pp
|
|
.\"The operation mode requires special support for
|
|
.\".Nm
|
|
.\"in
|
|
.\".Xr inetd 8 .
|
|
.Ss Access control
|
|
To prevent malicious access,
|
|
.Nm
|
|
implements a simple address-based access control.
|
|
With
|
|
.Pa /etc/faithd.conf
|
|
.Po
|
|
or
|
|
.Ar configfile
|
|
specified by
|
|
.Fl f
|
|
.Pc ,
|
|
.Nm
|
|
will avoid relaying unwanted traffic.
|
|
The
|
|
.Pa faithd.conf
|
|
configuration file contains directives of the following format:
|
|
.Bl -bullet
|
|
.It
|
|
.Xo
|
|
.Ar src/slen Li deny Ar dst/dlen
|
|
.Xc
|
|
.Pp
|
|
If the source address of a query matches
|
|
.Ar src/slen ,
|
|
and the translated destination address matches
|
|
.Ar dst/dlen ,
|
|
deny the connection.
|
|
.It
|
|
.Xo
|
|
.Ar src/slen Li permit Ar dst/dlen
|
|
.Xc
|
|
.Pp
|
|
If the source address of a query matches
|
|
.Ar src/slen ,
|
|
and the translated destination address matches
|
|
.Ar dst/dlen ,
|
|
permit the connection.
|
|
.El
|
|
.Pp
|
|
The directives are evaluated in sequence,
|
|
and the first matching entry will be effective.
|
|
If there is no match
|
|
.Pq if we reach the end of the ruleset
|
|
the traffic will be denied.
|
|
.Pp
|
|
With inetd mode,
|
|
traffic may be filtered by using access control functionality in
|
|
.Xr inetd 8 .
|
|
.Sh EXIT STATUS
|
|
.Nm
|
|
exits with
|
|
.Dv EXIT_SUCCESS
|
|
.Pq 0
|
|
on success, and
|
|
.Dv EXIT_FAILURE
|
|
.Pq 1
|
|
on error.
|
|
.Sh EXAMPLES
|
|
Before invoking
|
|
.Nm ,
|
|
the
|
|
.Xr faith 4
|
|
interface has to be configured properly.
|
|
.Bd -literal
|
|
# sysctl -w net.inet6.ip6.accept_rtadv=0
|
|
# sysctl -w net.inet6.ip6.forwarding=1
|
|
# sysctl -w net.inet6.ip6.keepfaith=1
|
|
# ifconfig faith0 create up
|
|
# route add -inet6 2001:0db8:4819:ffff:: -prefixlen 96 ::1
|
|
# route change -inet6 2001:0db8:4819:ffff:: -prefixlen 96 -ifp faith0
|
|
.Ed
|
|
.Ss Daemon mode samples
|
|
To translate
|
|
.Li telnet
|
|
service, and provide no local telnet service, invoke
|
|
.Nm
|
|
as follows:
|
|
.Bd -literal
|
|
# faithd telnet
|
|
.Ed
|
|
.Pp
|
|
If you would like to provide local telnet service via
|
|
.Xr telnetd 8
|
|
on
|
|
.Pa /usr/libexec/telnetd ,
|
|
use the following command line:
|
|
.Bd -literal
|
|
# faithd telnet /usr/libexec/telnetd telnetd
|
|
.Ed
|
|
.Pp
|
|
If you would like to pass extra arguments to the local daemon:
|
|
.Bd -literal
|
|
# faithd ftp /usr/libexec/ftpd ftpd -l
|
|
.Ed
|
|
.Pp
|
|
Here are some other examples.
|
|
You may need
|
|
.Fl p
|
|
if the service checks the source port range.
|
|
.Bd -literal
|
|
# faithd ssh
|
|
# faithd telnet /usr/libexec/telnetd telnetd
|
|
.Ed
|
|
.Ss inetd mode samples
|
|
Add the following lines into
|
|
.Xr inetd.conf 5 .
|
|
.\"Syntax may vary depending upon your operating system.
|
|
.Bd -literal
|
|
telnet stream faith/tcp6 nowait root faithd telnetd
|
|
ftp stream faith/tcp6 nowait root faithd ftpd -l
|
|
ssh stream faith/tcp6 nowait root faithd /usr/sbin/sshd -i
|
|
.Ed
|
|
.Pp
|
|
.Xr inetd 8
|
|
will open listening sockets with kernel TCP relay support enabled.
|
|
Whenever a connection comes in,
|
|
.Nm
|
|
will be invoked by
|
|
.Xr inetd 8 .
|
|
If the connection endpoint is in the reserved IPv6 address prefix.
|
|
.Nm
|
|
will relay the connection.
|
|
Otherwise,
|
|
.Nm
|
|
will invoke service-specific daemon like
|
|
.Xr telnetd 8 .
|
|
.Ss Access control samples
|
|
The following illustrates a simple
|
|
.Pa faithd.conf
|
|
setting.
|
|
.Bd -literal
|
|
# permit anyone from 2001:0db8:ffff::/48 to use the translator,
|
|
# to connect to the following IPv4 destinations:
|
|
# - any location except 10.0.0.0/8 and 127.0.0.0/8.
|
|
# Permit no other connections.
|
|
#
|
|
2001:0db8:ffff::/48 deny 10.0.0.0/8
|
|
2001:0db8:ffff::/48 deny 127.0.0.0/8
|
|
2001:0db8:ffff::/48 permit 0.0.0.0/0
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr faith 4 ,
|
|
.Xr route 8 ,
|
|
.Xr sysctl 8 ,
|
|
.Pa pkgsrc/net/totd
|
|
.Rs
|
|
.%A Jun-ichiro itojun Hagino
|
|
.%A Kazu Yamamoto
|
|
.%T "An IPv6-to-IPv4 transport relay translator"
|
|
.%B RFC 3142
|
|
.%U http://www.ietf.org/rfc/rfc3142.txt
|
|
.%D June 2001
|
|
.Re
|
|
.\"
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
utility first appeared in the WIDE Hydrangea IPv6 protocol stack kit.
|
|
.\"
|
|
.Sh SECURITY CONSIDERATIONS
|
|
It is very insecure to use IP-address based authentication, for connections relayed by
|
|
.Nm ,
|
|
and any other TCP relaying services.
|
|
.Pp
|
|
Administrators are advised to limit accesses to
|
|
.Nm
|
|
using
|
|
.Pa faithd.conf ,
|
|
or by using IPv6 packet filters, to protect the
|
|
.Nm
|
|
service from malicious parties, and to avoid theft of service/bandwidth.
|
|
IPv6 destination addresses can be limited by
|
|
carefully configuring routing entries that point to
|
|
.Xr faith 4 ,
|
|
using
|
|
.Xr route 8 .
|
|
The IPv6 source address needs to be filtered using packet filters.
|
|
The documents listed in
|
|
.Sx SEE ALSO
|
|
have more information on this topic.
|