ql2tpd.toml(5)

✨ ql2tpd.toml(5) ✨

okay bestie, gather round 💖 you're looking at the manual page for ql2tpd.toml, living in section 5 of the go-l2tp man pages. this is the glow-up guide for the config file. let's go 🫶

---

🌸 NAME 🌸

ql2tpd.toml — the configuration file for ql2tpd, no cap 💅

---

🦋 DESCRIPTION 🦋

so like. the ql2tpd.toml file is literally the whole personality of ql2tpd. it's what tells the daemon which L2TP tunnels and sessions to establish. that's the job. that's the assignment. periodt ✨

ql2tpd.toml is written in the TOML markup langange (https://toml.io/en/). (yes the original says "langange", we don't gatekeep typos here, it's iconic 😭)

Tunnel and session instances get called out in the configuration file using named TOML tables. think of each one like its own little group chat 📱

Each tunnel or session instance table holds the configuration parameters for that instance as key:value pairs. simple. clean. slay.

Every tunnel and session has a minimal set of configuration that you must specify. no skipping, bestie, it's required 💀

on top of that, each tunnel or session entry may also call out various optional key:value pairs, and those control ql2tpd's runtime behaviour. these options are generally not required, and ql2tpd will use sensible defaults for them if you don't include them in the config. it's giving "we got you, babe" 🎀

---

👑 TUNNEL CONFIGURATION 👑

Tunnels are described using named entries in the tunnel table.

Each tunnel entry describes a single tunnel instance, and must call out at least:

• the tunnel L2TP version (only L2TPv3 is supported),
• the tunnels encapsulation protocol,
• the local IP address,
• the local tunnel ID,
• the peer's IP address,
• the peer's tunnel ID.

Here's the full list of tunnel configuration options, and bestie I am not skipping a single one 🌈:

# This is a tunnel instance named "t1"
[tunnel.t1]

# version specifies the version of the L2TP specification the
# tunnel should use.
# Only "l2tpv3" is supported.
version = "l2tpv3"

# encap specifies the encapsulation to be used for the tunnel.
# L2TPv3 tunnels may be UDP or IP.
encap = "udp"

# local specifies the local address that the tunnel should
# bind its socket to
local = "127.0.0.1:5000"

# tid specifies the local tunnel ID of the tunnel.
# Tunnel IDs must be unique for the host.
# L2TPv2 tunnel IDs are 16 bit, and may be in the range 1 - 65535.
# L2TPv3 tunnel IDs are 32 bit, and may be in the range 1 - 4294967295.
tid = 62719

# peer specifies the address of the peer that the tunnel should
# connect its socket to
peer = "127.0.0.1:5001"

# ptid specifies the peer's tunnel ID for the tunnel.
# The peer's tunnel ID must be unique for the peer, and are unrelated
# to the local tunnel ID.
# The rules for tunnel ID range apply to the peer tunnel ID too.
ptid = 72819

# hello_timeout if set enables L2TP keep-alive (HELLO) messages.
# A hello message is sent N milliseconds after the last control
# message was sent or received.  It allows for early detection of
# tunnel failure on quiet connections.
# By default no keep-alive messages are sent.
hello_timeout = 7500 # milliseconds

quick translation for the girlies who skim 🍓: version only ever wants "l2tpv3", encap can be UDP or IP, local binds the socket, tid is your local tunnel ID (unique to the host), peer is where you're connecting, ptid is their tunnel ID (unique to them, unrelated to yours), and hello_timeout is the keep-alive HELLO vibe — it fires N milliseconds after the last control message went out or came in, so quiet connections get caught early when something's wrong. by default, no keep-alive messages are sent. 🙈

---

💜 SESSION CONFIGURATION 💜

Sessions are described using named entries in the session table inside the parent tunnel table. nesties stay together, always 🫶

Each session entry describes a single session instance within the parent tunnel, and must call out at least:

• the pseudowire type to be used (this must be Ethernet),
• the local session ID,
• the peer's session ID

Here's the full list of session configuration options, every single one, we don't do half-finished here ✨:

# This is a session instance called "s1" within parent tunnel "t1".
# Session instances are always created inside a parent tunnel.
[tunnel.t1.session.s1]

# pseudowire specifies the type of layer 2 frames carried by the session.
# Static sessions support Ethernet pseudowires only.
pseudowire = "eth"

# sid specifies the local session ID of the session.
# Session IDs must be unique to the tunnel for L2TPv2, or unique to
# the peer for L2TPv3.
# L2TPv2 session IDs are 16 bit, and may be in the range 1 - 65535.
# L2TPv3 session IDs are 32 bit, and may be in the range 1 - 4294967295.
sid = 12389

# psid specifies the peer's session ID for the session.
# The peer's session ID is unrelated to the local session ID.
# The rules for the session ID range apply to the peer session ID too.
psid = 1234

# seqnum, if set, enables the transmission of sequence numbers with
# L2TP data messages.  Use of sequence numbers enables the data plane
# to reorder data packets to ensure they are delivered in sequence.
# By default sequence numbers are not used.
seqnum = false

# cookie, if set, specifies the local L2TPv3 cookie for the session.
# Cookies are a data verification mechanism intended to allow misdirected
# data packets to be detected and rejected.
# Transmitted data packets will include the local cookie in their header.
# Cookies may be either 4 or 8 bytes long, and contain aribrary data.
# By default no local cookie is set.
cookie = [ 0x12, 0xe9, 0x54, 0x0f, 0xe2, 0x68, 0x72, 0xbc ]

# peer_cookie, if set, specifies the L2TPv3 cookie the peer will send in
# the header of its data messages.
# Messages received without the peer's cookie (or with the wrong cookie)
# will be rejected.
# By default no peer cookie is set.
peer_cookie = [ 0x74, 0x2e, 0x28, 0xa8 ]

# interface_name, if set, specifies the network interface name to be
# used for the session instance.
# By default the Linux kernel autogenerates an interface name specific to
# the pseudowire type, e.g. "l2tpeth0", "ppp0".
# Setting the interface name can be useful when you need to be certain
# of the interface name a given session will use.
# By default the kernel autogenerates an interface name.
interface_name = "l2tpeth42"

# l2spec_type specifies the L2TPv3 Layer 2 specific sublayer field to
# be used in data packet headers as per RFC3931 section 3.2.2.
# Currently supported values are "none" and "default".
# By default no Layer 2 specific sublayer is used.
l2spec_type = "default"

okay the tea ☕: pseudowire is Ethernet-only for static sessions, sid is your local session ID, psid is theirs and it's totally unrelated to yours. seqnum turns on sequence numbers so the data plane can reorder packets into the right order — off by default. cookie is your local L2TPv3 cookie: a data verification mechanism so misdirected packets get detected and rejected, and your transmitted packets carry the local cookie in their header. cookies can be 4 or 8 bytes and hold arbitrary data — no local cookie by default. peer_cookie is the cookie your peer will send in its data message headers, and anything arriving without it (or with the wrong one) gets rejected, so get it right fr fr 💀. interface_name lets you name the interface yourself instead of letting the Linux kernel autogenerate one specific to the pseudowire type (like "l2tpeth0", "ppp0") — useful when you need to be certain which interface a session uses. and l2spec_type picks the L2TPv3 Layer 2 specific sublayer field in data packet headers per RFC3931 section 3.2.2; supported values are "none" and "default", and by default no Layer 2 specific sublayer is used. 👑

---

🌈 SEE ALSO 🌈

• ql2tpd(1)

---

🎀 AUTHORS 🎀

Katalix Systems, Ltd. 💖

---

and that's the whole page, bestie, you ate it 🍓✨ this was go-l2tp v0.1.8, dated May 2024 — go forth and configure your tunnels, main character energy only 👑💅