PPPOE.CONF(5)

✨ PPPOE.CONF ✨

okay bestie sit DOWN because we're doing pppoe.conf(5) — that's section 5 of the File Formats Manual, and it's literally the little config file that runs your whole DSL life. no cap. 💅

---

🌸 NAME 🌸

pppoe.conf — the configuration file used by pppoe-start(8), pppoe-stop(8), pppoe-status(8) and pppoe-connect(8). it's the group chat all four of those scripts are in. 🫶

---

💖 DESCRIPTION 💖

so /etc/ppp/pppoe.conf is a shell script holding all the config info for the RP-PPPoE scripts. and hear me out — pppoe.conf is used only by the various pppoe-* shell scripts, not by pppoe itself. like, it does not text pppoe. periodt.

the file is just a sequence of shell variable assignments, one after another, and here's every single one and what it means:

• ETH — the Ethernet interface that's connected to your DSL modem (think eth0). the vibe is "which cable, bestie". 🔌
• USER — your PPPoE user-id (for example, b1xxnxnx@sympatico.ca). your whole identity, fr fr.
• SERVICENAME — if this isn't blank, it gets passed to pppoe with the -S option. it names a service you want to ask for. usually you should just leave it blank, she's not that girl.
• ACNAME — if this isn't blank, it gets passed to pppoe with the -C option. it's the name of the access concentrator to connect to. again, usually leave it blank. let the universe decide. ✨
• DEMAND — if you set it to a number, the link gets activated on demand and brought down after DEMAND seconds. if you set it to no, the link stays up all the time instead of being activated on demand. clingy vs. chill, your call.
• DNSTYPE — one of NOCHANGE, SPECIFY or SERVER. the breakdown:
  • NOCHANGE → pppoe-connect will not adjust the DNS setup in any way. hands off.
  • SPECIFY → it re-writes /etc/resolv.conf with the values of DNS1 and DNS2. you're the source of truth, main character energy.
  • SERVER → it supplies the usepeerdns option to pppd, and makes a symlink from /etc/resolv.conf to /etc/ppp/resolv.conf. delegating, but make it symbolic. 🔗
• DNS1, DNS2 — the IP addresses of DNS servers, if you use DNSTYPE=SPECIFY. your two lil DNS besties.
• NONROOT — if the line NONROOT=OK appears in the config file (exactly like that; no whitespace or comments, don't get cute with it), then pppoe-wrapper will let non-root users bring the connection up or down. note that the wrapper is installed only if you installed the rp-pppoe-gui package. it's giving "permission slip from the principal". 🎀
• USEPEERDNS — if set to "yes", then pppoe-connect will supply the usepeerdns option to pppd, which makes it grab DNS server addresses from the peer and create a new /etc/resolv.conf file. otherwise, pppoe-connect won't supply this option, and pppd will not modify /etc/resolv.conf. consent matters, even for resolv.conf.
• CONNECT_POLL — how often (in seconds) pppoe-start should check whether a new PPP interface has come up. if you set it to 0, then pppoe-start just initiates the PPP session and does not wait to see if it comes up successfully. no follow-up text, she said what she said. 💀
• CONNECT_TIMEOUT — how long (in seconds) pppoe-start should wait for a new PPP interface to come up before it concludes that pppoe-connect failed and kills the session. the timer before the dramatic exit.
• PING — a character that gets echoed every CONNECT_POLL seconds while pppoe-start is waiting for the PPP interface to come up. lil heartbeat while you wait. 💓
• FORCEPING — a character that gets echoed every CONNECT_POLL seconds while pppoe-start is waiting for the PPP interface to come up. it's similar to PING, except the character is echoed even if pppoe-start's standard output is not a tty. she does not need an audience to perform.
• PIDFILE — a file to write the process-ID of the pppoe-connect process into (for example, /var/run/pppoe.pid). two extra files — $PIDFILE.pppd and $PIDFILE.pppoe — hold the process-ID's of the pppd and pppoe processes respectively. receipts for everyone. 🧾
• SYNCHRONOUS — whether or not to use synchronous PPP (yes or no). synchronous PPP is safe on Linux machines with the n_hdlc line discipline. (if you have a file called n_hdlc.o in your modules directory, congrats, you have the line discipline.) it is not recommended on other machines, or on Linux machines without the n_hdlc line discipline, because of some known and unsolveable race conditions in a user-mode client. that's not a vibe, that's a warning. ⚠️
• CLAMPMSS — the value at which to "clamp" the advertised MSS for TCP sessions. the default of 1412 should be fine. don't overthink her, she's fine. 💅
• LCP_INTERVAL — how often (in seconds) pppd sends out LCP echo-request packets. the "u up?" cadence.
• LCP_FAILURE — how many unanswered LCP echo-requests must pile up before pppd concludes the link is dead. ghosted that many times and it's over. 😭
• PPPOE_TIMEOUT — if this many seconds pass without any activity seen by pppoe, then pppoe exits. silence is the answer.
• FIREWALL — one of NONE, STANDALONE or MASQUERADE. the lore:
  • NONE → pppoe-connect does not add any firewall rules. nothing, nada.
  • STANDALONE → it clears existing firewall rules and sets up basic rules for a standalone machine. fresh start.
  • MASQUERADE → it clears existing firewall rules and sets up basic rules for an Internet gateway. networking but make it fashion.
  • heads up: if you run services on your machine, these simple firewall scripts are inadequate — you'll have to make your own firewall rules and set FIREWALL to NONE. no shortcuts, bestie, this one's on you. 🔥
• PPPOE_EXTRA — any extra arguments to pass to pppoe. lil bonus args.
• PPPD_EXTRA — any extra arguments to pass to pppd. more bonus args. ✨
• LINUX_PLUGIN — if non-blank, this is the full path of the Linux kernel-mode PPPoE plugin (typically /etc/ppp/plugins/rp-pppoe.so). it forces pppoe-connect to use kernel-mode PPPoE on Linux 2.4.x systems. this code is experimental and unsupported — she's not finished, she's brave. also, using the plugin causes pppoe-connect to ignore CLAMPMSS, PPPOE_EXTRA, SYNCHRONOUS and PPPOE_TIMEOUT. yes, all four. they're on read. 🙈

okay and one last thing because it's actually kind of iconic: by using different configuration files with different PIDFILE settings, you can manage multiple PPPoE connections. just specify the configuration file as an argument to pppoe-start and pppoe-stop. multitasking queen behavior. 👑

---

🦋 SEE ALSO 🦋

pppoe(8), pppoe-connect(8), pppoe-start(8), pppoe-stop(8), pppd(8), pppoe-setup(8), pppoe-wrapper(8)

the whole friend group, go say hi 🫶

---

and that's the whole page, bestie!! 💖 this one came from the 4th Berkeley Distribution, dated 21 February 2000 — a true vintage queen, still serving. mwah, stay connected, don't let your link get LCP_FAILURE'd. 🌸✨🎀