[src/trunk]: src/share/man/man4 manpage for "pseudo-device gif", for IPv4/v6 ...

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

details:   https://anonhg.NetBSD.org/src/rev/3142a2f6e1e8
branches:  trunk
changeset: 474199:3142a2f6e1e8
user:      itojun <itojun%NetBSD.org@localhost>
date:      Thu Jul 01 10:52:17 1999 +0000

description:
manpage for "pseudo-device gif", for IPv4/v6 tunnelling.

diffstat:

 share/man/man4/gif.4 |  221 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 221 insertions(+), 0 deletions(-)

diffs (225 lines):

diff -r 08cc8758922d -r 3142a2f6e1e8 share/man/man4/gif.4
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man4/gif.4      Thu Jul 01 10:52:17 1999 +0000
@@ -0,0 +1,221 @@
+.\" 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.
+.\"
+.\"     $Id: gif.4,v 1.1 1999/07/01 10:52:17 itojun Exp $
+.\"
+.Dd April 10, 1999
+.Dt GIF 4
+.Os KAME
+.Sh NAME
+.Nm gif
+.Nd
+.Tn Generic tunnel interface
+.Sh SYNOPSIS
+.Cd "pseudo-device gif 4"
+.Sh DESCRIPTION
+The
+.Nm
+interface is a generic tunnelling pseudo device for IPv4 and IPv6.
+It can tunnel IPv[46] traffic over IPv[46].
+Therefore, there can be four possible configurations.
+The behavior of
+.Nm
+is mainly based on RFC1933 IPv6-over-IPv4 configured tunnel.
+.Pp
+To use
+.Nm gif ,
+administrator needs to configure protocol and addresses used for the outer 
+header.
+This can be done by using
+.Xr gifconfig 8 ,
+or
+.Dv SIOCSIFPHYADDR
+ioctl.
+Use routing table to route the packets toward
+.Nm
+interface.
+.Pp
+.Nm
+interface can be configued to perform bidirectional tunnel, or
+multi-destination tunnel.
+This is controlled by
+.Dv IFF_LINK0
+interface flag.
+Also,
+.Nm
+can be configured to be ECN friendly.
+This can be configured by
+.Dv IFF_LINK1 .
+.\"
+.Ss Bidirectional and multi-destination mode
+Usually,
+.Nm
+implements bidirectional tunnel.
+.Xr gifconfig 8
+should configure a tunnel ingress point
+.Pq this node
+and an egress point
+.Pq tunnel endpoint ,
+and
+one
+.Nm
+interface will tunnel to only a single tunnel endpoint,
+and accept from only a single tunnel endpoint.
+Source and destination address for outer IP header is always the
+ingress and the egress point configued by
+.Xr gifconfig 8 .
+.Pp
+With
+.Dv IFF_LINK0
+interface flag,
+.Nm
+can be configured to implement multi-destination tunnel.
+With
+.Dv IFF_LINK0 ,
+it is able to configure egress point to IPv4 wildcard address
+.Pq Nm 0.0.0.0
+or IPv6 unspecified address
+.Pq Nm 0::0 .
+In this case, destination address for the outer IP header is
+determined based on the routing table setup.
+Therefore, one
+.Nm
+interface can tunnel to multiple destinations.
+Also,
+.Nm
+will accept tunneled traffic from any outer source address.
+.Pp
+When finding a
+.Nm gif
+interface from the inbound tunneled traffic,
+bidirectional mode interface is preferred than multi-destination mode interface.
+For example, if you have the following three
+.Nm
+interfaces on node A, tunneled traffic from C to A will match the second
+.Nm
+interface, not the third one.
+.Bl -bullet -compact -offset indent
+.It
+bidirectional, A to B
+.It
+bidirectional, A to C
+.It
+multi-destination, A to any
+.El
+.Pp
+Please note that multi-destination mode is far less secure
+than bidirectional mode.
+Multi-destination mode
+.Nm
+can accept tunneled packet from anybody,
+and can be attacked from a malicious node.
+.Pp
+.Ss ECN friendly behavior
+.Nm
+can be configured to be ECN friendly, as described in
+.Dv draft-ipsec-ecn-00.txt .
+This is turned off by default, and can be turned on by
+.Dv IFF_LINK1
+interface flag.
+.Pp
+Without
+.Dv IFF_LINK1 ,
+.Nm
+will show a normal behavior, like described in RFC1933.
+This can be summarized as follows:
+.Bl -tag -width "Ingress" -offset indent
+.It Ingress
+Set outer TOS bit to
+.Dv 0 .
+.It Egress
+Drop outer TOS bit.
+.El
+.Pp
+With
+.Dv IFF_LINK1 ,
+.Nm
+will copy ECN bits
+.Po
+.Dv 0x02
+and
+.Dv 0x01
+on IPv4 TOS byte or IPv6 traffic class byte
+.Pc
+on egress and ingress, as follows:
+.Bl -tag -width "Ingress" -offset indent
+.It Ingress
+Copy TOS bits except for ECN CE
+.Po
+masked with
+.Dv 0xfe
+.Pc
+from
+inner to outer.
+set ECN CE bit to
+.Dv 0 .
+.It Egress
+Use inner TOS bits with some change.
+If outer ECN CE bit is
+.Dv 1 ,
+enable ECN CE bit on the inner.
+.El
+.Pp
+Note that the ECN friendly behavior violates RFC1933.
+This should be used in mutual agreement with the tunnel endpoint.
+.Pp
+.Ss Backward compatibility
+.Nm
+interface will capture packets toward IPv4-in-IPv4 tunnel,
+which has been used by
+.Xr vif 4 
+multicast tunnel device
+.Pq used in MBone community .
+For compatibility, IPv4-in-IPv4 traffic will be matched to
+.Nm
+interfaces first, and then sent to
+.Xr vif 4
+if no match is found.
+.\"
+.Sh SEE ALSO
+.Xr inet 4 ,
+.Xr inet6 4 ,
+.Xr vif 4 ,
+.Xr gifconfig 8 ,
+RFC1933
+.Rs
+.%A    Sally Floyd
+.%A    David L. Black
+.%A    K. K. Ramakrishnan
+.%T    "IPsec Interactions with ECN"
+.%D    February 1999
+.%O    http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt
+.Re
+.\"
+.Sh HISTORY
+The
+.Nm
+device first appeared in WIDE hydrangea IPv6 kit.