GIF(4)                    OpenBSD Programmer's Manual                   GIF(4)

NAME
     gif - generic tunnel interface

SYNOPSIS
     pseudo-device gif

DESCRIPTION
     The gif interface is a generic tunnelling pseudo-device for IPv4 and
     IPv6.  It can tunnel IPv[46] over IPv[46] with behavior mainly based on
     RFC 1933 IPv6-over-IPv4, for a total of four possible combinations.  When
     instead used as a member in a bridge(4), it will tunnel Ethernet packets
     over IPv[46] using RFC 3378 EtherIP encapsulation (version 3), providing
     two more combinations.

     A gif interface can be created at runtime using the ifconfig gifN create
     command or by setting up a hostname.if(5) configuration file for
     netstart(8).

     For all six modes the gif interface must be configured with the addresses
     used for the outer header.  This can be done by using ifconfig(8)'s
     tunnel command (which uses the SIOCSIFPHYADDR ioctl).

     For the IPv[46] over IPv[46] modes the addresses of the inner header must
     be configured by using ifconfig(8) in the normal way.  Note that IPv6
     link-local address (those start with fe80::) will be automatically con-
     figured whenever possible.  One may need to remove any IPv6 link-local
     address manually using ifconfig(8), to disable the use of IPv6 as inner
     header, for example when a pure IPv4-over-IPv6 tunnel is required.  The
     routing table can be used to direct packets toward the gif interface.

     For the Ethernet-over-IP modes the gif interface must be made a member of
     a bridge(4).  The sysctl(3) variable net.inet.etherip.allow must be set
     to 1, unless ipsec(4) is being used to protect the traffic.  Ethernet
     frames are then encapsulated and sent across the network to another
     bridge(4), which decapsulates the datagram and processes the resulting
     Ethernet frame as if it had originated on a normal Ethernet interface.
     This effectively allows a layer 2 network to be extended from one point
     to another, possibly through the Internet.  This mechanism may be used in
     conjunction with IPsec by specifying the appropriate IPsec flows between
     the two bridges.  To only protect the bridge traffic between the two
     bridges, the transport protocol 97 (etherip) selector may be used in
     ipsec.conf(5).  Otherwise, the Ethernet frames will be sent in the clear
     between the two bridges.

EXAMPLES
     Given two physically separate Ethernet networks, a bridge can be used as
     follows to make them appear as the same local area network.  If bridge1
     on network1 has the external IP address 1.2.3.4 on fxp0, bridge2 on net-
     work2 has the external IP address 4.3.2.1 on fxp0, and both bridges have
     fxp1 on their internal network (network1 and network2, respectively), the
     following configuration can be used to bridge network1 and network2.

     First create the bridge interface, adding the encapsulation interface and
     internal Ethernet interface to the bridge interface:

           # ifconfig bridge0 add gif0 add fxp1

     Create and configure the gif0 interface:

           (on bridge 1) # ifconfig gif0 tunnel 1.2.3.4 4.3.2.1
           (on bridge 2) # ifconfig gif0 tunnel 4.3.2.1 1.2.3.4

     Create Security Associations (SAs) between the external IP address of
     each bridge and matching ingress flows by using the following
     ipsec.conf(5) file on bridge1:

           esp from 1.2.3.4 to 4.3.2.1 spi 0x4242:0x4243 \
                   authkey file "auth1:auth2" enckey file "enc1:enc2"
           flow esp proto etherip from 1.2.3.4 to 4.3.2.1

     Now load these rules into the kernel by issuing the ipsecctl(8) command:

           # ipsecctl -f ipsec.conf

     Appropriate ipsec.conf(5) for bridge2:

           esp from 4.3.2.1 to 1.2.3.4 spi 0x4243:0x4242 \
                   authkey file "auth2:auth1" enckey file "enc2:enc1"
           flow esp proto etherip from 4.3.2.1 to 1.2.3.4

     And load them:

           # ipsecctl -f ipsec.conf

     To use dynamic (as opposed to static) keying, use this ipsec.conf(5) on
     bridge1:

           ike esp proto etherip from 1.2.3.4 to 4.3.2.1

     And on bridge2:

           ike esp proto etherip from 4.3.2.1 to 1.2.3.4

     Bring up the internal interface (if not already up) and encapsulation in-
     terface:

           # ifconfig fxp1 up
           # ifconfig gif0 up

     Finally, bring the bridge interface up and allow it to start processing
     frames:

           # ifconfig bridge0 up link2

     The internal interface on each bridge need not have an IP address: the
     bridge can function without it.

     Note:  It is possible to put the above commands in the hostname.if(5)
     files, using the `!' operator.

SEE ALSO
     sysctl(3), bridge(4), inet(4), inet6(4), ipsec(4), hostname.if(5),
     ifconfig(8), netstart(8)

     R. Gilligan and E. Nordmark, "Transition Mechanisms for IPv6 Hosts and
     Routers", RFC 1933, April 1996.

     R. Housley and S. Hollenbeck, "EtherIP: Tunneling Ethernet Frames in IP
     Datagrams", RFC 3378, September 2002.

HISTORY
     The gif device first appeared in WIDE hydrangea IPv6 kit.

BUGS
     There are many tunnelling protocol specifications, defined differently
     from each other.  gif may not interoperate with peers which are based on
     different specifications, and are picky about outer header fields.  For
     example, you cannot usually use gif to talk with IPsec devices that use
     IPsec tunnel mode.

     The current code does not check if the ingress address (outer source
     address) configured to gif makes sense.  Make sure to configure an ad-
     dress which belongs to your node.  Otherwise, your node will not be able
     to receive packets from the peer, and your node will generate packets
     with a spoofed source address.

     If the outer protocol is IPv6, path MTU discovery for encapsulated packet
     may affect communication over the interface.

     When used in conjunction with a bridge(4) interface, only one bridge tun-
     nel may be operational for every pair of source/destination addresses.
     If more than one gif interface is configured with the same pair of outer
     addresses, the one with the lowest index number will receive all traffic.

OpenBSD 4.7                    November 24, 2009                             3
