PPPOE-SERVER(8)

💖 PPPOE-SERVER(8) 💖

okay bestie, gather round, because today we're talking about pppoe-server from the System Manager's Manual, and she is that girl. ✨

---

🌸 NAME 🌸

pppoe-server — the user-space PPPoE server. yes, the one. she serves PPPoE (Point-to-Point Protocol over Ethernet) and she's serving 💅

---

🎀 SYNOPSIS 🎀

pppoe-server [options]

that's it. that's the whole vibe. options go in, magic comes out. 🦋

---

✨ DESCRIPTION ✨

so pppoe-server is a user-space server for PPPoE (that's Point-to-Point Protocol over Ethernet, iykyk) built for Linux and other UNIX systems. she works in concert with the pppoe client — like a duo, a duo — to respond to PPPoE discovery packets and set up PPPoE sessions. no cap. 🔥

---

👑 OPTIONS 👑

okay this is the main character section, let's go one by one, don't skip, every single one matters:

• -F — makes pppoe-server not fork and become a daemon. the default is to fork and become a daemon, so this is the "please stay right here in my terminal" option. 🙈
• -I interface — says which Ethernet interface to use. under Linux it's typically eth0 or eth1. the interface should be "up" before you start pppoe-server, but it does not need an IP address. you can hand her multiple -I options if you want her responding on more than one interface. she's flexible like that. 💜
• -X pidfile — causes pppoe-server to write its process ID into pidfile. bonus: she keeps that file locked, so only a single process can start for a given pidfile. exclusive. 💅
• -q /path/to/pppd — specifies the full path to the pppd program. the default is determined at compile time. one use case: handing her a wrapper program that modifies the arguments passed to pppd — that lets you do things the server doesn't directly support (like specifying IPv6 addresses). ✨
• -Q /path/to/pppoe — specifies the full path to the pppoe program. default is determined at compile time. this one only matters if you're not using kernel-mode PPPoE. 🫶
• -T timeout — passed directly to pppoe; go read pppoe(8) for the details. if you're using kernel-mode PPPoE, this option has no effect. 💀
• -C ac_name — specifies which name to report as the access concentrator name. if you don't supply it, the host name gets used. 🎀
• -S name — offer a service named name. you can specify multiple -S options; each one makes that named service get advertised in a Service-Name tag in the PADO frame. the first -S option specifies the default service, used when the PPPoE client requests a Service-Name of length zero. 🌈
• -m MSS — passed directly to pppoe; see pppoe(8) for details. if you're using kernel-mode PPPoE, this option has no effect. 🦋
• -x n — limits the number of sessions per peer MAC address to n. if a given MAC address tries to create more than n sessions, its PADI and PADR packets are just... ignored. if you set n to 0 (which is the default), then no limit is imposed on sessions per peer MAC address. 😌
• -s — passed directly to pppoe; see pppoe(8) for details. on top of that, it causes pppd to be invoked with the sync option. ⭐
• -L ip — sets the local IP address, passed to spawned pppd processes. if not specified, the default is 10.0.0.1. if you specify 0.0.0.0, then the selection of the local IP address is delegated to pppd. 🙌
• -R ip — sets the starting remote IP address. as sessions get established, IP addresses are assigned starting from ip. pppoe-server automatically keeps track of the pool of addresses and passes a valid remote IP address to pppd. if not specified, a starting address of 10.67.15.1 is used. if specified as 0.0.0.0, remote IP allocation is delegated to pppd. 🔥
• -N num — allows at most num concurrent PPPoE sessions. if not specified, the default is 64. 👑
• -M string — sends string in a MOTM tag in a PADM packet right after sending the PADS to a client. surprise message, bestie! 💌
• -H url — sends url in a HURL tag in a PADM packet right after sending the PADS to a client. note that url must start with either http:// or https://. no exceptions. 🚨
• -O fname — tells pppd to use the option file fname instead of the default /etc/ppp/pppoe-server-options. 📁
• -p fname — reads the specified file fname, which is a text file made of one IP address per line. those IP addresses get assigned to clients. the number of sessions allowed equals the number of addresses found in the file. the -p option overrides both -R and -N. 💥

besides plain IP addresses, the pool file can also contain lines of this form:

a.b.c.d-e

which includes all IP addresses from a.b.c.d to a.b.c.e. for example, the line:

1.2.3.4-7

is equivalent to:

1.2.3.4
1.2.3.5
1.2.3.6
1.2.3.7

look at her being efficient. 💅

• -r — tells the PPPoE server to randomly permute session numbers. instead of handing out sessions in order, the session numbers are assigned in an unpredictable order. chaotic. unpredictable. iconic. 🎲
• -u — tells the server to invoke pppd with the unit option. note: this only works for pppd version 2.4.0 or newer. ⭐
• -o offset — instead of numbering PPPoE sessions starting at 1, they get numbered starting at offset+1. this lets you run multiple servers on a given machine — just make sure their session numbers do not overlap. don't be messy. 🙈
• -f disc:sess — sets the Ethernet frame types for PPPoE discovery and session frames. the types are specified as hexadecimal numbers separated by a colon. standard PPPoE uses frame types 8863:8864.

⚠️ do not use this option unless you are absolutely sure the peer you're dealing with uses non-standard frame types. seriously. 💀

• -k — tells the server to use kernel-mode PPPoE on Linux. this option is available only on Linux kernels 2.4.0 and later, and only if the server was built with kernel-mode support. ✨
• -g path — tells the server the full path to the pppoe.so or rp-pppoe.so plugin to use with kernel-mode PPPoE. if omitted, a compiled-in default is used; that default can be displayed using the -h option. 🫶
• -i — tells the server to completely ignore PADI frames if there are no free session slots. not today, thank you. 🚫
• -h — prints a brief usage message and exits. the little helper. 🌸
• -U path — creates a UNIX socket you can connect to in order to manage pppoe-server at run-time. please refer to the CONTROL-SOCKET section below for more detailed instructions. 👑

---

💫 OPERATION 💫

pppoe-server listens for incoming PPPoE discovery packets. when a session gets established, she spawns a pppd process. these options get passed to pppd:

nodetach noaccomp nobsdcom nodeflate nopcomp novj novjccomp default-asyncmap

on top of that, the local and remote IP addresses are set based on the -L and -R options. the pty option is supplied along with a pppoe command to initiate the PPPoE session. and finally, extra pppd options can be placed in the file /etc/ppp/pppoe-server-options — which must exist, even if it is just empty! not me forgetting to create an empty file and wondering why nothing works 😭

⚠️ real talk: pppoe-server is meant mainly for testing PPPoE clients. she is not a high-performance server meant for production use. she's a test girlie, not a workhorse. 🫶

---

🎀 CONTROL-SOCKET 🎀

the control-socket was implemented as a secondary mechanism to improve run-time control of the pppoe-server. to use it you need to start pppoe-server with the -U option described above. then (in the absence of a control-client currently) you can use netcat to connect to the control socket, for example:

nc -U /run/pppoe-server.control

assuming -U /run/pppoe-server.control was passed to pppoe-server. 🦋

the following commands are implemented:

• set drain {off|on|quit} — sets whether or not pppoe-server responds to PADI packets. when set to off, pppoe-server will respond; otherwise PADI packets get ignored. this allows the pppoe-server to be drained from clients. in addition, when set to quit, it will terminate pppoe-server when all pppoe-clients have terminated. 💅

this allows for (mostly) seamless upgrades, in that the currently running instance can be issued with "set drain quit" prior to starting a new interface on the same interfaces — thus allowing new connections to be made whilst maintaining proper state on existing clients. glow-up with zero downtime, periodt. ✨

• show status — shows basic status information for the connected-to pppoe-server. 📊

---

💜 AUTHORS 💜

pppoe-server was written by Dianne Skoll <dianne@skoll.ca>. queen behavior. 👑

the pppoe home page is https://dianne.skoll.ca/projects/rp-pppoe/. go say hi. 🫶

---

🌈 SEE ALSO 🌈

pppd(8), pppoe(8), pppoe-sniff(8), pppoe-relay(8)

---

and that's the whole page, bestie! this one came to you courtesy of the 4th Berkeley Distribution, dated 21 June 2008 — vintage but still slaying 💖✨ go set up some sessions, you got this 🎀🦋