PPPOED(8)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💅 PPPOED(8) — the pppoed girlies' guide

okay so real talk, <rainbow>pppoed</rainbow> is from the System Manager's Manual section 8, and she is that girl for handling incoming PPP over Ethernet connections. buckle up bestie, we're going in 🎀

✨ SYNOPSIS ✨

pppoed [-Fd] [-P pidfile] [-a name] [-e exec | -l label] [-n ngdebug]
       [-p provider] interface

like, that's the whole vibe. one interface, a bunch of flags, iconic behavior 💅

🌸 DESCRIPTION 🌸

so <pink>pppoed</pink> sits and listens on the interface you hand her, waiting for PPP over Ethernet (PPPoE) service request packets to show up. when one does? she actions it — negotiates a session, then invokes a ppp(8) program. and the negotiation itself is done by the “pppoe” netgraph node, so go read ng_pppoe(4) for the juicy details 👑

here's the thing: <pink>pppoed</pink> will only offer services to clients who are requesting services from the provider you specified — and if you didn't specify one, that's taken as an empty name. but if you pass a provider name of “*”? then any PPPoE request gets offered service. she's generous like that 💖

the name you supply gets used as the access concentrator name when the connection is established. no name given? she just uses the current base hostname. periodt.

🦋 what actually happens when a request comes in

after receiving a request (PADI) from the PPPoE netgraph node, <pink>pppoed</pink> calls fork(2) and makes a whole child process, then goes right back to servicing more requests. like a true multitasking queen ✨

that child process offers service (using name) and then waits for a SUCCESS indication from the PPPoE node. and the moment she gets that SUCCESS? <pink>pppoed</pink> executes

exec /usr/sbin/ppp -direct label

as a shell sub-process 🫶

  • no label specified? it defaults to provider, easy.
  • you can specify a different command with the exec argument.
  • and that exec argument is mandatory if neither provider nor label are given — no cap, it's required.

when the child is started, its standard input and standard output are attached to the same netgraph(4) data socket (check ng_socket(4) for that one).

🌈 environment variables, aka the little extras

the child process gets these two env vars handed to it:

  • HISMACADDR — set to the MAC address of the peer 🍓
  • ACNAME — set to the name of the AC 💜

⭐ startup behavior (the part where she vanishes into the background)

upon invocation, <pink>pppoed</pink> attaches a “pppoe” netgraph node to the relevant “ether” node using “interface:” as the node name, and then connects that “pppoe” node to a local “socket” node.

then:

  • if the -F option has not been given, <pink>pppoed</pink> goes into the background and disassociates herself from the controlling terminal 🫥
  • if -F is given, she stays in the foreground, main character energy, watching everything 👀

💅 OPTIONS 💅

  • -F — stay in the foreground instead of backgrounding and detaching from the controlling terminal. she's not leaving, she's invested.
  • -d — turn on additional diagnostics (peep the “DIAGNOSTICS” section below for the deets 🔍).
  • -P pidfile — if pidfile is given, <pink>pppoed</pink> writes her process ID to that file on startup 📝
  • -a name — the name handed over as the access concentrator name when establishing the connection. if no name is given, the current base hostname is used 🌸
  • -e exec — specify another command to run instead of the default exec /usr/sbin/ppp -direct label. this is mandatory if provider and label are both not given. (mutually exclusive with -l, iykyk)
  • -l label — the label passed to /usr/sbin/ppp -direct label. if label has not been specified, it defaults to provider. (mutually exclusive with -e)
  • -n ngdebug — if given, NgSetDebug() is called with an argument of ngdebug 🐛
  • -p provider — only offer services to clients requesting services from this provider. taken as an empty name if not provided. a provider name of “*” means any PPPoE requests will be offered service 🔥

and don't forget the trailing interface argument — that's the whole point bestie 💀

🔍 DIAGNOSTICS 🔍

after creating all those necessary netgraph(4) nodes we talked about up there, <pink>pppoed</pink> uses syslogd(8) to report all incoming connections 📢

  • with -d, she reports on the child processes' creation of a new netgraph socket, its service offer, and the invocation of the ppp(8) program.
  • with -n, netgraph diagnostic messages are also redirected to syslogd(8).

ngl it's sometimes useful to add the following to /etc/syslog.conf:

!pppoed
*.*                             /var/log/pppoed.log

and the following to /etc/newsyslog.conf:

/var/log/pppoed.log           640  3       100    *     Z

like, do it. your future self will thank you 🫶

🧚 SEE ALSO 🧚

NgSetDebug(3), netgraph(4), ng_ether(4), ng_pppoe(4), ng_socket(4), syslog.conf(5), ppp(8), syslogd(8)

the whole friend group, honestly 👑

👑 HISTORY 👑

<pink>pppoed</pink> was written by Brian Somers <brian@Awfulhak.org> and first appeared in FreeBSD 3.4. a legend, fr fr 🌟

💀 BUGS 💀

okay so this is the messy part 🙈 if another netgraph node is already using the given interface, <pink>pppoed</pink> will fail to start. why? because netgraph(4) does not currently allow node chaining. that's just how it is rn. this may change in the future though, so manifesting ✨

and that's the page bestie, every single detail intact, no cap 💖

Debian · dated <hotpink>November 8, 1999</hotpink> · that's the source and version and date, mwah 💋 slay, go configure your PPPoE 🎀

📦 where this page comes from