{ "content": [ { "type": "text", "text": "# ip-l2tp (man)\n\n## NAME\n\nip-l2tp - L2TPv3 static unmanaged tunnel configuration\n\n## SYNOPSIS\n\nip [ OPTIONS ] l2tp { COMMAND | help }\n\n## DESCRIPTION\n\nThe ip l2tp commands are used to establish static, or so-called unmanaged L2TPv3 ethernet\ntunnels. For unmanaged tunnels, there is no L2TP control protocol so no userspace daemon is\nrequired - tunnels are manually created by issuing commands at a local system and at a remote\npeer.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS** (1 subsections)\n- **DESCRIPTION** (6 subsections)\n- **EXAMPLES** (3 subsections)\n- **INTEROPERABILITY**\n- **SEE ALSO**\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "ip-l2tp", "section": "", "mode": "man", "summary": "ip-l2tp - L2TPv3 static unmanaged tunnel configuration", "synopsis": "ip [ OPTIONS ] l2tp { COMMAND | help }", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [ "site-A:# ip l2tp add tunnel tunnelid 3000 peertunnelid 4000 \\", "encap udp local 1.2.3.4 remote 5.6.7.8 \\", "udpsport 5000 udpdport 6000", "site-A:# ip l2tp add session tunnelid 3000 sessionid 1000 \\", "peersessionid 2000", "site-B:# ip l2tp add tunnel tunnelid 4000 peertunnelid 3000 \\", "encap udp local 5.6.7.8 remote 1.2.3.4 \\", "udpsport 6000 udpdport 5000", "site-B:# ip l2tp add session tunnelid 4000 sessionid 2000 \\", "peersessionid 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.", "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.", "To carry non-IP data, the L2TP network interface is added to a bridge instead of being as‐", "signed 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 physi‐", "cal interface used by the tunnel. When the ethernet frames carry protocols which are reassem‐", "bled 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 ex‐", "actly as transmitted. In such cases, it is important that frames leaving the tunnel are re‐", "assembled back into a single frame before being forwarded on. To do so, enable netfilter con‐", "nection tracking (conntrack) or manually load the Linux netfilter defrag modules at each tun‐", "nel endpoint.", "site-A:# modprobe nfdefragipv4", "site-B:# modprobe nfdefragipv4", "If L2TP is being used over IPv6, use the IPv6 defrag module." ], "see_also": [ { "name": "ip", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/ip/8/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 2, "subsections": [ { "name": "ip l2tp add tunnel", "lines": 22 } ] }, { "name": "DESCRIPTION", "lines": 43, "subsections": [ { "name": "ip l2tp add tunnel - add a new tunnel", "lines": 44 }, { "name": "ip l2tp del tunnel - destroy a tunnel", "lines": 4 }, { "name": "ip l2tp show tunnel - show information about tunnels", "lines": 4 }, { "name": "ip l2tp add session - add a new session to a tunnel", "lines": 38 }, { "name": "ip l2tp del session - destroy a session", "lines": 6 }, { "name": "ip l2tp show session - show information about sessions", "lines": 8 } ] }, { "name": "EXAMPLES", "lines": 1, "subsections": [ { "name": "Setup L2TP tunnels and sessions", "lines": 19 }, { "name": "Configure as IP interfaces", "lines": 12 }, { "name": "Configure as bridged interfaces", "lines": 43 } ] }, { "name": "INTEROPERABILITY", "lines": 12, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "AUTHOR", "lines": 5, "subsections": [] } ], "sections": { "NAME": { "content": "ip-l2tp - L2TPv3 static unmanaged tunnel configuration\n", "subsections": [] }, "SYNOPSIS": { "content": "ip [ OPTIONS ] l2tp { COMMAND | help }\n", "subsections": [ { "name": "ip l2tp add tunnel", "content": "remote ADDR local ADDR\ntunnelid ID peertunnelid ID\n[ encap { ip | udp } ]\n[ udpsport PORT ] [ udpdport PORT ]\n[ udpcsum { on | off } ]\n[ udp6csumtx { on | off } ]\n[ udp6csumrx { on | off } ]\nip l2tp add session [ name NAME ]\ntunnelid ID sessionid ID peersessionid ID\n[ cookie HEXSTR ] [ peercookie HEXSTR ]\n[ l2spectype { none | default } ]\n[ seq { none | send | recv | both } ]\nip l2tp del tunnel tunnelid ID\nip l2tp del session tunnelid ID sessionid ID\nip l2tp show tunnel [ tunnelid ID ]\nip l2tp show session [ tunnelid ID.B ] [ sessionid ID ]\nNAME := STRING\nADDR := { IPADDRESS | any }\nPORT := { NUMBER }\nID := { NUMBER }\nHEXSTR := { 8 or 16 hex digits (4 / 8 bytes) }\n" } ] }, "DESCRIPTION": { "content": "The ip l2tp commands are used to establish static, or so-called unmanaged L2TPv3 ethernet\ntunnels. For unmanaged tunnels, there is no L2TP control protocol so no userspace daemon is\nrequired - tunnels are manually created by issuing commands at a local system and at a remote\npeer.\n\nL2TPv3 is suitable for Layer-2 tunneling. Static tunnels are useful to establish network\nlinks across IP networks when the tunnels are fixed. L2TPv3 tunnels can carry data of more\nthan one session. Each session is identified by a sessionid and its parent tunnel's tun‐\nnelid. A tunnel must be created before a session can be created in the tunnel.\n\nWhen creating an L2TP tunnel, the IP address of the remote peer is specified, which can be\neither an IPv4 or IPv6 address. The local IP address to be used to reach the peer must also\nbe specified. This is the address on which the local system will listen for and accept re‐\nceived L2TP data packets from the peer.\n\nL2TPv3 defines two packet encapsulation formats: UDP or IP. UDP encapsulation is most common.\nIP encapsulation uses a dedicated IP protocol value to carry L2TP data without the overhead\nof UDP. Use IP encapsulation only when there are no NAT devices or firewalls in the network\npath.\n\nWhen an L2TPv3 ethernet session is created, a virtual network interface is created for the\nsession, which must then be configured and brought up, just like any other network interface.\nWhen data is passed through the interface, it is carried over the L2TP tunnel to the peer. By\nconfiguring the system's routing tables or adding the interface to a bridge, the L2TP inter‐\nface is like a virtual wire (pseudowire) connected to the peer.\n\nEstablishing an unmanaged L2TPv3 ethernet pseudowire involves manually creating L2TP contexts\non the local system and at the peer. Parameters used at each site must correspond or no data\nwill be passed. No consistency checks are possible since there is no control protocol used to\nestablish unmanaged L2TP tunnels. Once the virtual network interface of a given L2TP session\nis configured and enabled, data can be transmitted, even if the peer isn't yet configured. If\nthe peer isn't configured, the L2TP data packets will be discarded by the peer.\n\nTo establish an unmanaged L2TP tunnel, use l2tp add tunnel and l2tp add session commands de‐\nscribed in this document. Then configure and enable the tunnel's virtual network interface,\nas required.\n\nNote that unmanaged tunnels carry only ethernet frames. If you need to carry PPP traffic\n(L2TPv2) or your peer doesn't support unmanaged L2TPv3 tunnels, you will need an L2TP server\nwhich implements the L2TP control protocol. The L2TP control protocol allows dynamic L2TP\ntunnels and sessions to be established and provides for detecting and acting upon network\nfailures.\n", "subsections": [ { "name": "ip l2tp add tunnel - add a new tunnel", "content": "tunnelid ID\nset the tunnel id, which is a 32-bit integer value. Uniquely identifies the tunnel.\nThe value used must match the peertunnelid value being used at the peer.\n\npeertunnelid ID\nset the peer tunnel id, which is a 32-bit integer value assigned to the tunnel by the\npeer. The value used must match the tunnelid value being used at the peer.\n\nremote ADDR\nset the IP address of the remote peer. May be specified as an IPv4 address or an IPv6\naddress.\n\nlocal ADDR\nset the IP address of the local interface to be used for the tunnel. This address must\nbe the address of a local interface. May be specified as an IPv4 address or an IPv6\naddress.\n\nencap ENCAP\nset the encapsulation type of the tunnel.\nValid values for encapsulation are: udp, ip.\n\nudpsport PORT\nset the UDP source port to be used for the tunnel. Must be present when udp encapsula‐\ntion is selected. Ignored when ip encapsulation is selected.\n\nudpdport PORT\nset the UDP destination port to be used for the tunnel. Must be present when udp en‐\ncapsulation is selected. Ignored when ip encapsulation is selected.\n\nudpcsum STATE\n(IPv4 only) control if IPv4 UDP checksums should be calculated and checked for the en‐\ncapsulating UDP packets, when UDP encapsulating is selected. Default is off.\nValid values are: on, off.\n\nudp6csumtx STATE\n(IPv6 only) control if IPv6 UDP checksums should be calculated for encapsulating UDP\npackets, when UDP encapsulating is selected. Default is on.\nValid values are: on, off.\n\nudp6csumrx STATE\n(IPv6 only) control if IPv6 UDP checksums should be checked for the encapsulating UDP\npackets, when UDP encapsulating is selected. Default is on.\nValid values are: on, off.\n" }, { "name": "ip l2tp del tunnel - destroy a tunnel", "content": "tunnelid ID\nset the tunnel id of the tunnel to be deleted. All sessions within the tunnel must be\ndeleted first.\n" }, { "name": "ip l2tp show tunnel - show information about tunnels", "content": "tunnelid ID\nset the tunnel id of the tunnel to be shown. If not specified, information about all\ntunnels is printed.\n" }, { "name": "ip l2tp add session - add a new session to a tunnel", "content": "name NAME\nsets the session network interface name. Default is l2tpethN.\n\ntunnelid ID\nset the tunnel id, which is a 32-bit integer value. Uniquely identifies the tunnel\ninto which the session will be created. The tunnel must already exist.\n\nsessionid ID\nset the session id, which is a 32-bit integer value. Uniquely identifies the session\nbeing created. The value used must match the peersessionid value being used at the\npeer.\n\npeersessionid ID\nset the peer session id, which is a 32-bit integer value assigned to the session by\nthe peer. The value used must match the sessionid value being used at the peer.\n\ncookie HEXSTR\nsets an optional cookie value to be assigned to the session. This is a 4 or 8 byte\nvalue, specified as 8 or 16 hex digits, e.g. 014d3636deadbeef. The value must match\nthe peercookie value set at the peer. The cookie value is carried in L2TP data pack‐\nets and is checked for expected value at the peer. Default is to use no cookie.\n\npeercookie HEXSTR\nsets an optional peer cookie value to be assigned to the session. This is a 4 or 8\nbyte value, specified as 8 or 16 hex digits, e.g. 014d3636deadbeef. The value must\nmatch the cookie value set at the peer. It tells the local system what cookie value to\nexpect to find in received L2TP packets. Default is to use no cookie.\n\nl2spectype L2SPECTYPE\nset the layer2specific header type of the session.\nValid values are: none, default.\n\nseq SEQ\ncontrols sequence numbering to prevent or detect out of order packets. send puts a\nsequence number in the default layer2specific header of each outgoing packet. recv\nreorder packets if they are received out of order. Default is none.\nValid values are: none, send, recv, both.\n" }, { "name": "ip l2tp del session - destroy a session", "content": "tunnelid ID\nset the tunnel id in which the session to be deleted is located.\n\nsessionid ID\nset the session id of the session to be deleted.\n" }, { "name": "ip l2tp show session - show information about sessions", "content": "tunnelid ID\nset the tunnel id of the session(s) to be shown. If not specified, information about\nsessions in all tunnels is printed.\n\nsessionid ID\nset the session id of the session to be shown. If not specified, information about all\nsessions is printed.\n" } ] }, "EXAMPLES": { "content": "", "subsections": [ { "name": "Setup L2TP tunnels and sessions", "content": "site-A:# ip l2tp add tunnel tunnelid 3000 peertunnelid 4000 \\\nencap udp local 1.2.3.4 remote 5.6.7.8 \\\nudpsport 5000 udpdport 6000\nsite-A:# ip l2tp add session tunnelid 3000 sessionid 1000 \\\npeersessionid 2000\n\nsite-B:# ip l2tp add tunnel tunnelid 4000 peertunnelid 3000 \\\nencap udp local 5.6.7.8 remote 1.2.3.4 \\\nudpsport 6000 udpdport 5000\nsite-B:# ip l2tp add session tunnelid 4000 sessionid 2000 \\\npeersessionid 1000\n\nsite-A:# ip link set l2tpeth0 up mtu 1488\n\nsite-B:# ip link set l2tpeth0 up mtu 1488\n\nNotice that the IP addresses, UDP ports and tunnel / session ids are matched and reversed at\neach site.\n" }, { "name": "Configure as IP interfaces", "content": "The two interfaces can be configured with IP addresses if only IP data is to be carried. This\nis perhaps the simplest configuration.\n\nsite-A:# ip addr add 10.42.1.1 peer 10.42.1.2 dev l2tpeth0\n\nsite-B:# ip addr add 10.42.1.2 peer 10.42.1.1 dev l2tpeth0\n\nsite-A:# ping 10.42.1.2\n\nNow the link should be usable. Add static routes as needed to have data sent over the new\nlink.\n" }, { "name": "Configure as bridged interfaces", "content": "To carry non-IP data, the L2TP network interface is added to a bridge instead of being as‐\nsigned its own IP address, using standard Linux utilities. Since raw ethernet frames are then\ncarried inside the tunnel, the MTU of the L2TP interfaces must be set to allow space for\nthose headers.\n\nsite-A:# ip link set l2tpeth0 up mtu 1446\nsite-A:# ip link add br0 type bridge\nsite-A:# ip link set l2tpeth0 master br0\nsite-A:# ip link set eth0 master br0\nsite-A:# ip link set br0 up\n\nIf you are using VLANs, setup a bridge per VLAN and bridge each VLAN over a separate L2TP\nsession. For example, to bridge VLAN ID 5 on eth1 over an L2TP pseudowire:\n\nsite-A:# ip link set l2tpeth0 up mtu 1446\nsite-A:# ip link add brvlan5 type bridge\nsite-A:# ip link set l2tpeth0.5 master brvlan5\nsite-A:# ip link set eth1.5 master brvlan5\nsite-A:# ip link set brvlan5 up\n\nAdding the L2TP interface to a bridge causes the bridge to forward traffic over the L2TP\npseudowire just like it forwards over any other interface. The bridge learns MAC addresses of\nhosts attached to each interface and intelligently forwards frames from one bridge port to\nanother. IP addresses are not assigned to the l2tpethN interfaces. If the bridge is correctly\nconfigured at both sides of the L2TP pseudowire, it should be possible to reach hosts in the\npeer's bridged network.\n\nWhen raw ethernet frames are bridged across an L2TP tunnel, large frames may be fragmented\nand forwarded as individual IP fragments to the recipient, depending on the MTU of the physi‐\ncal interface used by the tunnel. When the ethernet frames carry protocols which are reassem‐\nbled by the recipient, like IP, this isn't a problem. However, such fragmentation can cause\nproblems for protocols like PPPoE where the recipient expects to receive ethernet frames ex‐\nactly as transmitted. In such cases, it is important that frames leaving the tunnel are re‐\nassembled back into a single frame before being forwarded on. To do so, enable netfilter con‐\nnection tracking (conntrack) or manually load the Linux netfilter defrag modules at each tun‐\nnel endpoint.\n\nsite-A:# modprobe nfdefragipv4\n\nsite-B:# modprobe nfdefragipv4\n\nIf L2TP is being used over IPv6, use the IPv6 defrag module.\n" } ] }, "INTEROPERABILITY": { "content": "Unmanaged (static) L2TPv3 tunnels are supported by some network equipment equipment vendors\nsuch as Cisco.\n\nIn Linux, L2TP Hello messages are not supported in unmanaged tunnels. Hello messages are used\nby L2TP clients and servers to detect link failures in order to automate tearing down and\nreestablishing dynamic tunnels. If a non-Linux peer supports Hello messages in unmanaged tun‐\nnels, it must be turned off to interoperate with Linux.\n\nLinux defaults to use the Default Layer2SpecificHeader type as defined in the L2TPv3 protocol\nspecification, RFC3931. This setting must be consistent with that configured at the peer.\nSome vendor implementations (e.g. Cisco) default to use a Layer2SpecificHeader type of None.\n", "subsections": [] }, "SEE ALSO": { "content": "ip(8)\n", "subsections": [] }, "AUTHOR": { "content": "James Chapman \n\n\n\niproute2 19 Apr 2012 IP-L2TP(8)", "subsections": [] } } } }