.\"	$NetBSD: l2tp.4,v 1.4 2018/08/14 06:26:52 wiz Exp $
.\"
.\" Copyright (C) 2017 Internet Initiative Japan Inc.
.\" 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 August 14, 2018
.Dt L2TP 4
.Os
.Sh NAME
.Nm l2tp
.Nd layer two tunneling protocol version 3
.Sh SYNOPSIS
.Cd "pseudo-device l2tp"
.Sh DESCRIPTION
The
.Nm
interface implements version 3 of the Layer Two Tunneling Protocol (L2TPv3).
It can tunnel layer 2 protocol traffic over IPv4 or IPv6, as specified in
.Li RFC3931 .
.Pp
The L2TPv3 protocol is comprised of two types of messages: control messages
and data messages.
Control messages are used in the establishment,
maintenace, and clearing of control connections and sessions.
The
.Nm
interface can send control messages and data messages; furthermore
the management of control messages is entrusted to userland daemon.
Without a management daemon, the
.Nm
interface can send data messages using the
.Xr ifconfig 8
.Cm tunnel
and
.Cm session
subcommands, or the
.Dv SIOCSIFPHYADDR
and
.Dv SIOCSL2TPSESSION
ioctls.
Additionally, it can use cookies specified in
.Li RFC3931
by using the
.Xr ifconfig 8
.Cm cookie
subcommand, or the
.Dv SIOCSL2TPCOOKIE
ioctl.
.Ss Packet format
Layer 2 frames are prepended with a L2TPv3 header as described by
RFC 3931.
The resulting L2TPv3 packets will be encapsulated in an outer packet,
which may be either an IPv4 or IPv6 packet, with IP protocol number 115.
.Sh EXAMPLES
Configuration example:
.Bd -literal
wm0 = 192.168.0.1/24                        wm0 = 192.168.0.2/24

+------------+                                    +------------+
|  NetBSD_A  |                                    |  NetBSD_B  |
|------------|                                    |------------|
|   [l2tp0] - - - - - - - - (tunnel) - - - - - - - - [l2tp0]   |
|          [wm0]------------- ... --------------[wm0]          |
|            |                                    |            |
+---[wm1]----+                                    +----[wm1]---+
      |                                                  |
      |                                                  |
+------------+                                    +------------+
|   Host_X   |                                    |   Host_Y   |
+------------+                                    +------------+
.Ed
.Ss Configuration example without cookies
On NetBSD_A:
.Bd -literal
# ifconfig wm0 inet 192.168.0.1/24
# ifconfig l2tp0 create
# ifconfig l2tp0 tunnel 192.168.0.1 192.168.0.2
# ifconfig l2tp0 session 1234 4321
# ifconfig bridge0 create
# brconfig bridge0 add wm1
# brconfig bridge0 add l2tp0
# ifconfig l2tp0 up
# ifconfig wm1 up
# ifconfig bridge0 up
.Ed
.Pp
On NetBSD_B:
.Bd -literal
# ifconfig wm0 inet 192.168.0.2/24
# ifconfig l2tp0 create
# ifconfig l2tp0 tunnel 192.168.0.2 192.168.0.1
# ifconfig l2tp0 session 4321 1234
# ifconfig bridge0 create
# brconfig bridge0 add wm1
# brconfig bridge0 add l2tp0
# ifconfig l2tp0 up
# ifconfig wm1 up
# ifconfig bridge0 up
.Ed
.Ss Configuration example with cookies
On NetBSD_A:
.Bd -literal
# ifconfig wm0 inet 192.168.0.1/24
# ifconfig l2tp0 create
# ifconfig l2tp0 tunnel 192.168.0.1 192.168.0.2
# ifconfig l2tp0 session 1234 4321
# ifconfig l2tp0 cookie 4 12345 4 54321
# ifconfig bridge0 create
# brconfig bridge0 add wm1
# brconfig bridge0 add l2tp0
# ifconfig l2tp0 up
# ifconfig wm1 up
# ifconfig bridge0 up
.Ed
.Pp
On NetBSD_B:
.Bd -literal
# ifconfig wm0 inet 192.168.0.2/24
# ifconfig l2tp0 create
# ifconfig l2tp0 tunnel 192.168.0.2 192.168.0.1
# ifconfig l2tp0 session 4321 1234
# ifconfig l2tp0 cookie 4 54321 4 12345
# ifconfig bridge0 create
# brconfig bridge0 add wm1
# brconfig bridge0 add l2tp0
# ifconfig l2tp0 up
# ifconfig wm1 up
# ifconfig bridge0 up
.Ed
.Sh SEE ALSO
.Xr inet 4 ,
.Xr inet6 4 ,
.Xr ifconfig 8
.Rs
.%A J. Lau, Ed.
.%A M. Townsley, Ed.
.%A I. Goyret, Ed.
.%B RFC 3931
.%T Layer Two Tunneling Protocol - Version 3 (L2TPv3)
.%D March 2005
.%U ftp://ftp.ietf.org/rfc/rfc3931.txt
.Re
.Sh HISTORY
The
.Nm
device first appeared in
.Nx 8.0 .
.Sh BUGS
Currently, the
.Nm
interface supports Ethernet frames over IPv4 or IPv6 only.