.TH IP\-L2TP 8 "19 Apr 2012" "iproute2" "Linux"

.SH "NAME"

ip-l2tp - L2TPv3 static unmanaged tunnel configuration

.SH "SYNOPSIS"

.sp

.ad l

.in +8

.ti -8

.B ip

.RI "[ " OPTIONS " ]"

.B l2tp

.RI " { " COMMAND " | "

.BR help " }"

.sp

.ti -8

.BR "ip l2tp add tunnel"

.br

.BI remote " ADDR " local " ADDR "

.br

.B tunnel_id

.IR ID

.B peer_tunnel_id

.IR ID

.br

.RB "[ " encap " { " ip " | " udp " } ]"

.br

.RB "[ " udp_sport

.IR PORT

.RB " ] [ " udp_dport

.IR PORT

.RB " ]"

.br

.RB "[ " udp_csum " { " on " | " off " } ]"

.br

.RB "[ " udp6_csum_tx " { " on " | " off " } ]"

.br

.RB "[ " udp6_csum_rx " { " on " | " off " } ]"

.br

.ti -8

.BR "ip l2tp add session"

.RB "[ " name

.IR NAME

.RB " ]"

.br

.B tunnel_id

.IR ID

.B session_id

.IR ID

.B peer_session_id

.IR ID

.br

.RB "[ " cookie

.IR HEXSTR

.RB " ] [ " peer_cookie

.IR HEXSTR

.RB " ]"

.br

.RB "[ " l2spec_type " { " none " | " default " } ]"

.br

.RB "[ " seq " { " none " | " send " | " recv " | " both " } ]"

.br

.ti -8

.BR "ip l2tp del tunnel"

.B tunnel_id

.IR ID

.br

.ti -8

.BR "ip l2tp del session"

.B tunnel_id

.IR ID

.B session_id

.IR ID

.br

.ti -8

.BR "ip l2tp show tunnel" " [ " tunnel_id

.IR ID " ]"

.br

.ti -8

.BR "ip l2tp show session" " [ " tunnel_id

.IR ID .B " ] ["

.B session_id

.IR ID " ]"

.br

.ti -8

.IR NAME " := "

.IR STRING

.ti -8

.IR ADDR " := { " IP_ADDRESS " |"

.BR any " }"

.ti -8

.IR PORT " := { " NUMBER " }"

.ti -8

.IR ID " := { " NUMBER " }"

.ti -8

.ti -8

.IR HEXSTR " := { 8 or 16 hex digits (4 / 8 bytes) }"

.SH DESCRIPTION

The

.B ip l2tp

commands are used to establish static, or so-called

.I 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.

.PP

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.

.PP

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.

.PP

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.

.PP

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.

.PP

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.

.PP

To establish an unmanaged L2TP tunnel, use

.B l2tp add tunnel

and

.B l2tp add session

commands described in this document. Then configure and enable the

tunnel's virtual network interface, as required.

.PP

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.

.SS ip l2tp add tunnel - add a new tunnel

.TP

.BI tunnel_id " ID"

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.

.TP

.BI peer_tunnel_id " ID"

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.

.TP

.BI remote " ADDR"

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

address or an IPv6 address.

.TP

.BI local " ADDR"

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.

.TP

.BI encap " ENCAP"

set the encapsulation type of the tunnel.

.br

Valid values for encapsulation are:

.BR udp ", " ip "."

.TP

.BI udp_sport " PORT"

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.

.TP

.BI udp_dport " PORT"

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.

.TP

.BI udp_csum " STATE"

(IPv4 only) control if IPv4 UDP checksums should be calculated and checked for the

encapsulating UDP packets, when UDP encapsulating is selected.

Default is

.BR off "."

.br

Valid values are:

.BR on ", " off "."

.TP

.BI udp6_csum_tx " STATE"

(IPv6 only) control if IPv6 UDP checksums should be calculated for encapsulating

UDP packets, when UDP encapsulating is selected.

Default is

.BR on "."

.br

Valid values are:

.BR on ", " off "."

.TP

.BI udp6_csum_rx " STATE"

(IPv6 only) control if IPv6 UDP checksums should be checked for the encapsulating

UDP packets, when UDP encapsulating is selected.

Default is

.BR on "."

.br

Valid values are:

.BR on ", " off "."

.SS ip l2tp del tunnel - destroy a tunnel

.TP

.BI tunnel_id " ID"

set the tunnel id of the tunnel to be deleted. All sessions within the

tunnel must be deleted first.

.SS ip l2tp show tunnel - show information about tunnels

.TP

.BI tunnel_id " ID"

set the tunnel id of the tunnel to be shown. If not specified,

information about all tunnels is printed.

.SS ip l2tp add session - add a new session to a tunnel

.TP

.BI name " NAME "

sets the session network interface name. Default is l2tpethN.

.TP

.BI tunnel_id " ID"

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.

.TP

.BI session_id " ID"

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.

.TP

.BI peer_session_id " ID"

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.

.TP

.BI cookie " HEXSTR"

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.

.TP

.BI peer_cookie " HEXSTR"

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.

.TP

.BI l2spec_type " L2SPECTYPE"

set the layer2specific header type of the session.

.br

Valid values are:

.BR none ", " default "."

.TP

.BI seq " SEQ"

controls sequence numbering to prevent or detect out of order packets.

.B send

puts a sequence number in the default layer2specific header of each

outgoing packet.

.B recv

reorder packets if they are received out of order.

Default is

.BR none "."

.br

Valid values are:

.BR none ", " send ", " recv ", " both "."

.SS ip l2tp del session - destroy a session

.TP

.BI tunnel_id " ID"

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

.TP

.BI session_id " ID"

set the session id of the session to be deleted.

.SS ip l2tp show session - show information about sessions

.TP

.BI tunnel_id " ID"

set the tunnel id of the session(s) to be shown. If not specified,

information about sessions in all tunnels is printed.

.TP

.BI session_id " ID"

set the session id of the session to be shown. If not specified,

information about all sessions is printed.

.SH EXAMPLES

.PP

.SS Setup L2TP tunnels and sessions

.nf

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

.fi

.PP

Notice that the IP addresses, UDP ports and tunnel / session ids are

matched and reversed at each site.

.SS Configure as IP interfaces

The two interfaces can be configured with IP addresses if only IP data

is to be carried. This is perhaps the simplest configuration.

.PP

.nf

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

.fi

.PP

Now the link should be usable. Add static routes as needed to have

data sent over the new link.

.PP

.SS Configure as bridged interfaces

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.

.PP

.nf

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

.fi

.PP

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:

.PP

.nf

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

.fi

.PP

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.

.PP

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.

.PP

.nf

site-A:# modprobe nf_defrag_ipv4

site-B:# modprobe nf_defrag_ipv4

.fi

.PP

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

.SH INTEROPERABILITY

.PP

Unmanaged (static) L2TPv3 tunnels are supported by some network

equipment equipment vendors such as Cisco.

.PP

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.

.PP

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.

.SH SEE ALSO

.br

.BR ip (8)

.SH AUTHOR

James Chapman <jchapman@katalix.com>