.\"	$OpenBSD: gif.4,v 1.27 2012/09/26 17:34:38 jmc Exp $
.\"	$KAME: gif.4,v 1.15 2000/04/19 09:39:42 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 $Mdocdate: September 26 2012 $
.Dt GIF 4
.Os
.Sh NAME
.Nm gif
.Nd generic tunnel interface
.Sh SYNOPSIS
.Cd "pseudo-device gif"
.Sh DESCRIPTION
The
.Nm
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 4213 IPv6-over-IPv4, for a total of four possible combinations.
When instead used as a member in a
.Xr bridge 4 ,
it will tunnel Ethernet packets over IPv[46] using RFC 3378 EtherIP
encapsulation (version 3), providing two more combinations.
.Pp
A
.Nm
interface can be created at runtime using the
.Ic ifconfig gif Ns Ar N Ic create
command or by setting up a
.Xr hostname.if 5
configuration file for
.Xr netstart 8 .
.Pp
For all six modes the
.Nm
interface must be configured with the
addresses used for the outer header.
This can be done by using
.Xr ifconfig 8 Ns 's
.Ic tunnel
command (which uses the
.Dv SIOCSIFPHYADDR
ioctl).
.Pp
For the IPv[46] over IPv[46] modes the addresses of the inner
header must be configured by using
.Xr ifconfig 8
in the normal way.
Note that IPv6 link-local address
.Pq those start with Li fe80::
will be automatically configured whenever possible.
One may need to remove any IPv6 link-local address manually using
.Xr 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
.Nm
interface.
.Pp
For the Ethernet-over-IP modes the
.Nm
interface must be made a member of a
.Xr bridge 4 .
The
.Xr sysctl 3
variable
.Dv net.inet.etherip.allow
must be set to 1, unless
.Xr ipsec 4
is being used to protect the traffic.
Ethernet frames are then encapsulated and sent across the network
to another
.Xr 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
.Xr ipsec.conf 5 .
Otherwise, the Ethernet frames will be sent in the clear between the
two bridges.
.Sh 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 network2 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.
.Pp
First create the bridge interface,
adding the encapsulation interface and internal Ethernet interface
to the bridge interface:
.Bd -literal -offset indent
# ifconfig bridge0 add gif0 add fxp1
.Ed
.Pp
Create and configure the gif0 interface:
.Bd -literal -offset indent
(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
.Ed
.Pp
Create Security Associations (SAs) between the external IP address of each
bridge and matching ingress flows by using the following
.Xr ipsec.conf 5
file on bridge1:
.Bd -literal -offset indent
esp from 1.2.3.4 to 4.3.2.1 spi 0x4242:0x4243 \e
        authkey file "auth1:auth2" enckey file "enc1:enc2"
flow esp proto etherip from 1.2.3.4 to 4.3.2.1
.Ed
.Pp
Now load these rules into the kernel by issuing the
.Xr ipsecctl 8
command:
.Bd -literal -offset indent
# ipsecctl -f ipsec.conf
.Ed
.Pp
Appropriate
.Xr ipsec.conf 5
for bridge2:
.Bd -literal -offset indent
esp from 4.3.2.1 to 1.2.3.4 spi 0x4243:0x4242 \e
        authkey file "auth2:auth1" enckey file "enc2:enc1"
flow esp proto etherip from 4.3.2.1 to 1.2.3.4
.Ed
.Pp
And load them:
.Bd -literal -offset indent
# ipsecctl -f ipsec.conf
.Ed
.Pp
To use dynamic (as opposed to static) keying,
use this
.Xr ipsec.conf 5
on bridge1:
.Bd -literal -offset indent
ike esp proto etherip from 1.2.3.4 to 4.3.2.1
.Ed
.Pp
And on bridge2:
.Bd -literal -offset indent
ike esp proto etherip from 4.3.2.1 to 1.2.3.4
.Ed
.Pp
Bring up the internal interface (if not already up) and encapsulation
interface:
.Bd -literal -offset indent
# ifconfig fxp1 up
# ifconfig gif0 up
.Ed
.Pp
Finally, bring the bridge interface up and allow it to start processing
frames:
.Pp
.Dl # ifconfig bridge0 up link2
.Pp
The internal interface on each bridge need not have an IP
address: the bridge can function without it.
.Pp
Note:  It is possible to put the above commands in the
.Xr hostname.if 5
files, using the
.Sq !\&
operator.
.Sh SEE ALSO
.Xr sysctl 3 ,
.Xr bridge 4 ,
.Xr inet 4 ,
.Xr inet6 4 ,
.Xr ipsec 4 ,
.Xr hostname.if 5 ,
.Xr ifconfig 8 ,
.Xr netstart 8
.Sh STANDARDS
.Rs
.%A R. Housley
.%A S. Hollenbeck
.%D September 2002
.%R RFC 3378
.%T EtherIP: Tunneling Ethernet Frames in IP Datagrams
.Re
.Pp
.Rs
.%A E. Nordmark
.%A R. Gilligan
.%D October 2005
.%R RFC 4213
.%T Basic Transition Mechanisms for IPv6 Hosts and Routers
.Re
.Sh HISTORY
The
.Nm
device first appeared in WIDE hydrangea IPv6 kit.
.Sh BUGS
There are many tunnelling protocol specifications,
defined differently from each other.
.Nm
may not interoperate with peers which are based on different specifications,
and are picky about outer header fields.
For example, you cannot usually use
.Nm
to talk with IPsec devices that use IPsec tunnel mode.
.Pp
The current code does not check if the ingress address
.Pq outer source address
configured to
.Nm
makes sense.
Make sure to configure an address 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.
.Pp
If the outer protocol is IPv6, path MTU discovery for encapsulated packet
may affect communication over the interface.
.Pp
When used in conjunction with a
.Xr bridge 4
interface,
only one bridge tunnel may be operational for every pair of
source/destination addresses.
If more than one
.Nm
interface is configured with the same pair of outer addresses, the
one with the lowest index number will receive all traffic.