ip-l2tp - L2TPv3 static unmanaged tunnel configuration

Author

       James Chapman <jchapman@katalix.com>

iproute2                                           19 Apr 2012                                        IP-L2TP(8)

Description

The ipl2tp commands are used to establish static, or so-called unmanaged L2TPv3 ethernet tunnels. For
unmanaged tunnels, there is no L2TP control protocol so no userspace daemon is required - tunnels are
manually created by issuing commands at a local system and at a remote peer.

L2TPv3 is suitable for Layer-2 tunneling. Static tunnels are useful to establish network links across IP
networks when the tunnels are fixed. L2TPv3 tunnels can carry data of more than one session. Each session
is identified by a session_id and its parent tunnel's tunnel_id. A tunnel must be created before a
session can be created in the tunnel.

When creating an L2TP tunnel, the IP address of the remote peer is specified, which can be either an IPv4
or IPv6 address. The local IP address to be used to reach the peer must also be specified. This is the
address on which the local system will listen for and accept received L2TP data packets from the peer.

L2TPv3 defines two packet encapsulation formats: UDP or IP. UDP encapsulation is most common. IP
encapsulation uses a dedicated IP protocol value to carry L2TP data without the overhead of UDP. Use IP
encapsulation only when there are no NAT devices or firewalls in the network path.

When an L2TPv3 ethernet session is created, a virtual network interface is created for the session, which
must then be configured and brought up, just like any other network interface. When data is passed
through the interface, it is carried over the L2TP tunnel to the peer. By configuring the system's
routing tables or adding the interface to a bridge, the L2TP interface is like a virtual wire
(pseudowire) connected to the peer.

Establishing an unmanaged L2TPv3 ethernet pseudowire involves manually creating L2TP contexts on the
local system and at the peer. Parameters used at each site must correspond or no data will be passed. No
consistency checks are possible since there is no control protocol used to establish unmanaged L2TP
tunnels. Once the virtual network interface of a given L2TP session is configured and enabled, data can
be transmitted, even if the peer isn't yet configured. If the peer isn't configured, the L2TP data
packets will be discarded by the peer.

To establish an unmanaged L2TP tunnel, use l2tpaddtunnel and l2tpaddsession commands described in
this document. Then configure and enable the tunnel's virtual network interface, as required.

Note that unmanaged tunnels carry only ethernet frames. If you need to carry PPP traffic (L2TPv2) or your
peer doesn't support unmanaged L2TPv3 tunnels, you will need an L2TP server which implements the L2TP
control protocol. The L2TP control protocol allows dynamic L2TP tunnels and sessions to be established
and provides for detecting and acting upon network failures.

ipl2tpaddtunnel-addanewtunneltunnel_idID
set the tunnel id, which is a 32-bit integer value. Uniquely identifies the tunnel. The value used
must match the peer_tunnel_id value being used at the peer.

peer_tunnel_idID
set the peer tunnel id, which is a 32-bit integer value assigned to the tunnel by the peer. The
value used must match the tunnel_id value being used at the peer.

remoteADDR
set the IP address of the remote peer. May be specified as an IPv4 address or an IPv6 address.

localADDR
set the IP address of the local interface to be used for the tunnel. This address must be the
address of a local interface. May be specified as an IPv4 address or an IPv6 address.

encapENCAP
set the encapsulation type of the tunnel.
Valid values for encapsulation are: udp, ip.

udp_sportPORT
set the UDP source port to be used for the tunnel. Must be present when udp encapsulation is
selected. Ignored when ip encapsulation is selected.

udp_dportPORT
set the UDP destination port to be used for the tunnel. Must be present when udp encapsulation is
selected. Ignored when ip encapsulation is selected.

udp_csumSTATE
(IPv4 only) control if IPv4 UDP checksums should be calculated and checked for the encapsulating
UDP packets, when UDP encapsulating is selected. Default is off.
Valid values are: on, off.

udp6_csum_txSTATE
(IPv6 only) control if IPv6 UDP checksums should be calculated for encapsulating UDP packets, when
UDP encapsulating is selected. Default is on.
Valid values are: on, off.

udp6_csum_rxSTATE
(IPv6 only) control if IPv6 UDP checksums should be checked for the encapsulating UDP packets,
when UDP encapsulating is selected. Default is on.
Valid values are: on, off.

ipl2tpdeltunnel-destroyatunneltunnel_idID
set the tunnel id of the tunnel to be deleted. All sessions within the tunnel must be deleted
first.

ipl2tpshowtunnel-showinformationabouttunnelstunnel_idID
set the tunnel id of the tunnel to be shown. If not specified, information about all tunnels is
printed.

ipl2tpaddsession-addanewsessiontoatunnelnameNAME
sets the session network interface name. Default is l2tpethN.

tunnel_idID
set the tunnel id, which is a 32-bit integer value. Uniquely identifies the tunnel into which the
session will be created. The tunnel must already exist.

session_idID
set the session id, which is a 32-bit integer value. Uniquely identifies the session being
created. The value used must match the peer_session_id value being used at the peer.

peer_session_idID
set the peer session id, which is a 32-bit integer value assigned to the session by the peer. The
value used must match the session_id value being used at the peer.

cookieHEXSTR
sets an optional cookie value to be assigned to the session. This is a 4 or 8 byte value,
specified as 8 or 16 hex digits, e.g. 014d3636deadbeef. The value must match the peer_cookie value
set at the peer. The cookie value is carried in L2TP data packets and is checked for expected
value at the peer. Default is to use no cookie.

peer_cookieHEXSTR
sets an optional peer cookie value to be assigned to the session. This is a 4 or 8 byte value,
specified as 8 or 16 hex digits, e.g. 014d3636deadbeef. The value must match the cookie value set
at the peer. It tells the local system what cookie value to expect to find in received L2TP
packets. Default is to use no cookie.

l2spec_typeL2SPECTYPE
set the layer2specific header type of the session.
Valid values are: none, default.

seqSEQ
controls sequence numbering to prevent or detect out of order packets. send puts a sequence
number in the default layer2specific header of each outgoing packet. recv reorder packets if they
are received out of order. Default is none.
Valid values are: none, send, recv, both.

ipl2tpdelsession-destroyasessiontunnel_idID
set the tunnel id in which the session to be deleted is located.

session_idID
set the session id of the session to be deleted.

ipl2tpshowsession-showinformationaboutsessionstunnel_idID
set the tunnel id of the session(s) to be shown. If not specified, information about sessions in
all tunnels is printed.

session_idID
set the session id of the session to be shown. If not specified, information about all sessions is
printed.

Examples

SetupL2TPtunnelsandsessions
       site-A:# ip l2tp add tunnel tunnel_id 3000 peer_tunnel_id 4000 \
                  encap udp local 1.2.3.4 remote 5.6.7.8 \
                  udp_sport 5000 udp_dport 6000
       site-A:# ip l2tp add session tunnel_id 3000 session_id 1000 \
                  peer_session_id 2000

       site-B:# ip l2tp add tunnel tunnel_id 4000 peer_tunnel_id 3000 \
                  encap udp local 5.6.7.8 remote 1.2.3.4 \
                  udp_sport 6000 udp_dport 5000
       site-B:# ip l2tp add session tunnel_id 4000 session_id 2000 \
                  peer_session_id 1000

       site-A:# ip link set l2tpeth0 up mtu 1488

       site-B:# ip link set l2tpeth0 up mtu 1488

       Notice that the IP addresses, UDP ports and tunnel / session ids are matched and reversed at each site.

   ConfigureasIPinterfaces
       The  two interfaces can be configured with IP addresses if only IP data is to be carried. This is perhaps
       the simplest configuration.

       site-A:# ip addr add 10.42.1.1 peer 10.42.1.2 dev l2tpeth0

       site-B:# ip addr add 10.42.1.2 peer 10.42.1.1 dev l2tpeth0

       site-A:# ping 10.42.1.2

       Now the link should be usable. Add static routes as needed to have data sent over the new link.

   Configureasbridgedinterfaces
       To carry non-IP data, the L2TP network interface is added to a bridge instead of being assigned  its  own
       IP address, using standard Linux utilities. Since raw ethernet frames are then carried inside the tunnel,
       the MTU of the L2TP interfaces must be set to allow space for those headers.

       site-A:# ip link set l2tpeth0 up mtu 1446
       site-A:# ip link add br0 type bridge
       site-A:# ip link set l2tpeth0 master br0
       site-A:# ip link set eth0 master br0
       site-A:# ip link set br0 up

       If  you  are  using VLANs, setup a bridge per VLAN and bridge each VLAN over a separate L2TP session. For
       example, to bridge VLAN ID 5 on eth1 over an L2TP pseudowire:

       site-A:# ip link set l2tpeth0 up mtu 1446
       site-A:# ip link add brvlan5 type bridge
       site-A:# ip link set l2tpeth0.5 master brvlan5
       site-A:# ip link set eth1.5 master brvlan5
       site-A:# ip link set brvlan5 up

       Adding the L2TP interface to a bridge causes the bridge to forward traffic over the L2TP pseudowire  just
       like  it  forwards  over  any  other interface. The bridge learns MAC addresses of hosts attached to each
       interface and intelligently forwards frames from one  bridge  port  to  another.  IP  addresses  are  not
       assigned  to  the  l2tpethN  interfaces.  If the bridge is correctly configured at both sides of the L2TP
       pseudowire, it should be possible to reach hosts in the peer's bridged network.

       When raw ethernet frames are bridged across an L2TP tunnel, large frames may be fragmented and  forwarded
       as  individual  IP fragments to the recipient, depending on the MTU of the physical interface used by the
       tunnel. When the ethernet frames carry protocols which are reassembled by the recipient,  like  IP,  this
       isn't  a  problem.  However,  such  fragmentation  can  cause problems for protocols like PPPoE where the
       recipient expects to receive ethernet frames exactly as transmitted. In such cases, it is important  that
       frames  leaving  the tunnel are reassembled back into a single frame before being forwarded on. To do so,
       enable netfilter connection tracking (conntrack) or manually load the Linux netfilter defrag  modules  at
       each tunnel endpoint.

       site-A:# modprobe nf_defrag_ipv4

       site-B:# modprobe nf_defrag_ipv4

       If L2TP is being used over IPv6, use the IPv6 defrag module.

Interoperability

       Unmanaged (static) L2TPv3 tunnels are supported by some network equipment vendors such as Cisco.

       In  Linux,  L2TP  Hello  messages are not supported in unmanaged tunnels. Hello messages are used by L2TP
       clients and servers to detect link failures in order to automate tearing down and reestablishing  dynamic
       tunnels.  If  a  non-Linux  peer  supports  Hello messages in unmanaged tunnels, it must be turned off to
       interoperate with Linux.

       Linux defaults  to  use  the  Default  Layer2SpecificHeader  type  as  defined  in  the  L2TPv3  protocol
       specification,  RFC3931.  This  setting  must be consistent with that configured at the peer. Some vendor
       implementations (e.g. Cisco) default to use a Layer2SpecificHeader type of None.

Name

       ip-l2tp - L2TPv3 static unmanaged tunnel configuration

Synopsis

ip [ OPTIONS ] l2tp  { COMMAND | help }

       ipl2tpaddtunnelremoteADDRlocalADDRtunnel_idIDpeer_tunnel_idID
               [ encap { ip | udp } ]
               [ udp_sportPORT  ] [ udp_dportPORT  ]
               [ udp_csum { on | off } ]
               [ udp6_csum_tx { on | off } ]
               [ udp6_csum_rx { on | off } ]
       ipl2tpaddsession [ nameNAME  ]
               tunnel_idIDsession_idIDpeer_session_idID
               [ cookieHEXSTR  ] [ peer_cookieHEXSTR  ]
               [ l2spec_type { none | default } ]
               [ seq { none | send | recv | both } ]
       ipl2tpdeltunneltunnel_idIDipl2tpdelsessiontunnel_idIDsession_idIDipl2tpshowtunnel [ tunnel_idID ]
       ipl2tpshowsession [ tunnel_idID.B ][session_idID ]
       NAME := STRINGADDR := { IP_ADDRESS | any }
       PORT := { NUMBER }
       ID := { NUMBER }
       HEXSTR := { 8 or 16 hex digits (4 / 8 bytes) }