You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
429 lines
14 KiB
429 lines
14 KiB
.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
|
|
.RB "[ " offset
|
|
.IR OFFSET
|
|
.RB " ] [ " peer_offset
|
|
.IR OFFSET
|
|
.RB " ]"
|
|
.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 "."
|
|
.TP
|
|
.BI offset " OFFSET"
|
|
sets the byte offset from the L2TP header where user data starts in
|
|
transmitted L2TP data packets. This is hardly ever used. If set, the
|
|
value must match the peer_offset value used at the peer. Default is 0.
|
|
.TP
|
|
.BI peer_offset " OFFSET"
|
|
sets the byte offset from the L2TP header where user data starts in
|
|
received L2TP data packets. This is hardly ever used. If set, the
|
|
value must match the offset value used at the peer. Default is 0.
|
|
.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>
|