ip-l2tp

ip l2tp { tunnel | session } { command } [ arguments ]

tunnel
    Manages L2TPv3 tunnels in the kernel. Used with add, show, or del commands.

session
    Manages L2TPv3 sessions within an existing tunnel. Used with add, show, or del commands.

add
    Creates a new L2TPv3 tunnel or session. Requires specific options to define its properties.

show
    Displays details of configured L2TPv3 tunnels or sessions. Can be filtered by ID.

del
    Deletes an existing L2TPv3 tunnel or session. Requires its unique identifier(s).

tunnel_id ID
    A unique, locally assigned identifier for the L2TPv3 tunnel.

peer_tunnel_id ID
    The identifier used by the remote peer for this tunnel.

encap { ip | udp }
    Specifies the encapsulation type for the tunnel: direct IP or UDP. Default is usually UDP.

src_addr ADDR
    The local source IP address for the tunnel endpoint.

dst_addr ADDR
    The destination IP address of the remote tunnel endpoint.

cookie HEX_STR
    An optional local cookie value (hexadecimal string) for tunnel or session authentication/identification.

peer_cookie HEX_STR
    An optional cookie value expected from the remote peer for tunnel or session.

udp_dport PORT
    The UDP destination port number for UDP encapsulated tunnels (default is 1701).

udp_sport PORT
    The UDP source port number for UDP encapsulated tunnels.

vlan_id ID
    When used with Ethernet pseudowires, specifies the VLAN ID to associate with the tunnel.

dev NAME
    The network device (interface) to which the tunnel's source IP address is bound.

l2tp_session_id ID
    A unique, locally assigned identifier for the L2TPv3 session within a tunnel.

peer_l2tp_session_id ID
    The identifier used by the remote peer for this session.

pw_type { eth | vlan | ppp }
    The pseudowire type, specifying the Layer 2 protocol being tunneled (e.g., Ethernet, VLAN-aware Ethernet, PPP).

offset OFFSET
    Specifies an offset for cookie matching, useful for partial cookie checks.

data_size SIZE
    Specifies the size of data for cookie matching, used with offset.

mtu MTU
    Sets the Maximum Transmission Unit for the virtual network interface created for the session.

interface NAME
    Specifies a name for the virtual network interface created for the session (e.g., for Ethernet pseudowire).

The ip-l2tp command is a utility within the iproute2 suite, used for configuring and managing Layer 2 Tunneling Protocol version 3 (L2TPv3) tunnels and sessions in the Linux kernel.

L2TPv3 provides a mechanism for tunneling arbitrary Layer 2 protocols (like Ethernet, PPP, etc.) over IP networks. Unlike L2TPv2, L2TPv3 focuses on generic Layer 2 tunneling and is not tied to PPP. It can be used for various purposes, including extending Layer 2 networks over IP, creating virtual private LAN services (VPLS), or backhauling traffic.

This command allows administrators to add, display, and delete L2TPv3 tunnels and individual L2TPv3 sessions associated with these tunnels, providing control over the tunnel endpoints, encapsulation type (e.g., UDP, IP), and session identifiers.

Requires the l2tp_v3 kernel module and specific pseudowire modules (e.g., l2tp_eth, l2tp_ppp) to be loaded. Proper network configuration (e.g., routing, firewall rules) is essential for tunnel functionality. This command primarily configures the L2TPv3 data plane in the kernel; the control plane (session establishment, keepalives) typically needs an external L2TP daemon or user-space application.

L2TPv3 is a significant evolution from L2TPv2. While L2TPv2 primarily focused on tunneling PPP over IP, L2TPv3 is a more generic Layer 2 tunneling mechanism, capable of encapsulating various Layer 2 protocols (e.g., Ethernet, PPP, ATM, Frame Relay) using the concept of 'pseudowires.' It also introduces 64-bit tunnel and session IDs and optional session cookies for improved multiplexing and security.

The pw_type option, used during session creation, is crucial as it defines the specific Layer 2 frame type being encapsulated and tunneled. Common types include eth for raw Ethernet frames (creating a l2tpethX interface), vlan for VLAN-tagged Ethernet frames, and ppp for PPP frames, each leading to different network interface behaviors and requirements.

The ip-l2tp command was integrated into the iproute2 suite to provide native kernel control over L2TPv3 tunnels and sessions. Its development aligns with the evolving L2TPv3 kernel support, enabling direct configuration of Layer 2 tunneling without sole reliance on user-space daemons for data forwarding. This has significantly enhanced the flexibility for network extension and virtualization use cases in Linux.

ip(8), ip-link(8), ip-address(8), ip-route(8)