ip-l2tp.8 (13294B)
- .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 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>