From 9d0659f865e33941c37392900743975be230d3ce Mon Sep 17 00:00:00 2001 From: itojun Date: Thu, 1 Jul 1999 10:52:17 +0000 Subject: [PATCH] manpage for "pseudo-device gif", for IPv4/v6 tunnelling. --- share/man/man4/gif.4 | 221 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 221 insertions(+) create mode 100644 share/man/man4/gif.4 diff --git a/share/man/man4/gif.4 b/share/man/man4/gif.4 new file mode 100644 index 000000000000..3ca5028996ef --- /dev/null +++ b/share/man/man4/gif.4 @@ -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.