[src/trunk]: src/share/man/man4 add manpage for faith pseudo interface (which...

[itojun <itojun%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/3c638aadfc53
branches:  trunk
changeset: 474725:3c638aadfc53
user:      itojun <itojun%NetBSD.org@localhost>
date:      Sat Jul 17 07:09:40 1999 +0000

description:
add manpage for faith pseudo interface (which is for
IPv6-to-IPv4 tcp relay translation).

diffstat:

 share/man/man4/Makefile |    4 +-
 share/man/man4/faith.4  |  122 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 124 insertions(+), 2 deletions(-)

diffs (144 lines):

diff -r 62fd7d673e75 -r 3c638aadfc53 share/man/man4/Makefile
--- a/share/man/man4/Makefile   Sat Jul 17 07:07:08 1999 +0000
+++ b/share/man/man4/Makefile   Sat Jul 17 07:09:40 1999 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile,v 1.93 1999/07/12 15:13:30 kleink Exp $
+#      $NetBSD: Makefile,v 1.94 1999/07/17 07:09:40 itojun Exp $
 #      @(#)Makefile    8.1 (Berkeley) 6/18/93
 
 MAN=   ahb.4 ahc.4 aria.4 atalk.4 audio.4 bha.4 bpf.4 ccd.4 cd.4 ch.4 \
@@ -31,7 +31,7 @@
 MAN+=  si.4
 
 # IPv6/IPsec
-MAN+=  gif.4 ipsec.4 inet6.4
+MAN+=  faith.4 gif.4 ipsec.4 inet6.4
 
 MLINKS+=bha.4 bt.4
 MLINKS+=fd.4 stderr.4 fd.4 stdin.4 fd.4 stdout.4
diff -r 62fd7d673e75 -r 3c638aadfc53 share/man/man4/faith.4
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man4/faith.4    Sat Jul 17 07:09:40 1999 +0000
@@ -0,0 +1,122 @@
+.\" 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.
+.\"
+.\"    $NetBSD: faith.4,v 1.1 1999/07/17 07:09:40 itojun Exp $
+.\"     KAME Id: faith.4,v 1.1.2.1 1999/07/17 07:03:49 itojun Exp
+.\"
+.Dd April 10, 1999
+.Dt FAITH 4
+.Os
+.Sh NAME
+.Nm faith
+.Nd
+.Tn IPv6-to-IPv4 TCP relay capturing interface
+.Sh SYNOPSIS
+.Cd "pseudo-device faith 1"
+.Sh DESCRIPTION
+The
+.Nm
+interface captures IPv6 TCP traffic,
+for implementing userland IPv6-to-IPv4 TCP relay
+like
+.Xr faithd 8 .
+.Pp
+Special action will be taken when IPv6 TCP traffic is seen on a router,
+and routing table suggests to route it to
+.Nm
+interface.
+In this case, the packet will be accepted by the router,
+regardless of list of IPv6 interface addresses assigned to the router.
+The packet will be captured by an IPv6 TCP socket, if it has
+.Dv IN6P_FAITH
+flag turned on and it has matching address/port pairs.
+In result,
+.Nm
+will let you capture IPv6 TCP traffic to some specific destination addresses.
+Userland programs, such as
+.Xr faithd 8
+can use this behavior to relay IPv6 TCP traffic to IPv4 TCP traffic.
+The program can accept some specific IPv6 TCP traffic, perform
+.Xr getsockname 3
+to get the IPv6 destination address specified by the client,
+and perform application-specific address mapping to relay IPv6 TCP to IPv4 TCP.
+.Pp
+.Dv IN6P_FAITH
+flag on IPv6 TCP socket can be set by using
+.Xr setsockopt 2 ,
+with level equals to
+.Dv IPPROTO_IPV6
+and optname equals to
+.Dv IPv6_FAITH .
+.Pp
+To handle error reports by ICMPv6, some of ICMPv6 packets routed to
+.Nm
+interface will be delivered to IPv6 TCP, as well.
+.Pp
+To understand how
+.Nm
+can be used, take a look at source code of
+.Xr faithd 8 .
+.Pp
+As
+.Nm
+interface implements potentially dangerous operation,
+great care must be taken when configuring
+.Nm
+interface.
+To avoid possible misuse,
+.Xr sysctl 8
+variable
+.Li net.inet6.ip6.keepfaith
+must be set to
+.Li 1
+prior to the use of the interface.
+When
+.Li net.inet6.ip6.keepfaith
+is
+.Li 0 ,
+no packet will be captured by
+.Nm
+interface.
+.Pp
+.Nm
+interface is intended to be used on routers, not on hosts.
+.\"
+.Sh SEE ALSO
+.Xr inet 4 ,
+.Xr inet6 4 ,
+.Xr faithd 8 .
+.\" .Rs
+.\" .%A        Jun-ichiro itojun Hagino
+.\" .%A        Kazu Yamamoto
+.\" .%T        ``FAITH'' IPv6-to-IPv4 TCP relay translator
+.\" .%D        July 1999
+.\" .Re
+.\"
+.Sh HISTORY
+The FAITH IPv6-to-IPv4 TCP relay translator was first appeared in
+WIDE hydrangea IPv6 stack.