PPPCTL(8)

💅 PPPCTL(8) — the PPP control program, bestie edition

okay so real talk: this is pppctl, and it lives in section 8 of the System Manager's Manual (yes, the system manager one, she's official 👑). She's your little remote control for the ppp(8) daemon. Let's get into it.

---

✨ SYNOPSIS ✨

pppctl [-v] [-t n] [-p passwd] [host:]Port | LocalSocket
       [command[;command]...]

that's the whole vibe. one socket arg, optional flags, optional commands. slay.

---

🎀 DESCRIPTION 🎀

So this utility gives you command line control of the ppp(8) daemon — like, you type stuff and the daemon actually does it. Her primary use is making it easy to write lil scripts that control a running daemon. main character energy fr fr. 💖

You pass pppctl at least one argument, and that argument tells her which socket ppp is listening on. (Go look at the set server command of ppp for the deets, iykyk.) Here's how she reads that socket string:

• if it starts with a /, she treats it as an AF_LOCAL socket 🔌
• if it contains a colon, she treats it as a host:port pair
• otherwise she treats it as a TCP port specification on the local machine (127.0.0.1)

Both the host and the port can be given numerically — do that if you wanna dodge a DNS lookup, or if you don't have an entry for that port in /etc/services. no cap, that's the move. ⭐

All the remaining arguments get concatenated into the command(s) that get sent to the ppp daemon. And if there's a semi-colon anywhere in there? She treats those as command delimiters, so you can stack more than one command in a single "session". Like, for example:

pppctl 3000 set timeout 300\; show timeout

⚠️ do NOT forget to escape or quote that ; — it's a special character for most shells and she WILL be messy about it if you don't. 😭

If you give her no command arguments at all, pppctl slides into interactive mode, where commands get read from standard input. And when she's reading commands she uses the editline(3) library, so you get command-line editing (with editrc(5) defining the editing behaviour). History size defaults to 20 lines. cute. 🎀

The following command line options are available:

🌸 OPTIONS 🌸

• -v — Display all data sent to and received from the ppp daemon. Normally pppctl only shows you the non-prompt lines it receives. This option is ignored in interactive mode. 🙈
• -t n — Use a timeout of n instead of the default 2 seconds when connecting. You might need this if you're controlling a daemon over a slow link — or honestly even a dialup one, no judgement. 🐌
• -p passwd — Specify the password required by the ppp daemon. If you don't use this switch, pppctl will prompt you for a password once it's successfully connected to ppp. very demure, very mindful. 💅

---

🦋 ENVIRONMENT 🦋

The following environment variables are understood by pppctl when in interactive mode:

• EL_SIZE — The number of history lines. The default is 20.
• EL_EDITOR — The edit mode. Only values of "emacs" and "vi" are accepted. Other values are silently ignored. This environment variable will override the bind -v and bind -e commands in ~/.editrc. 💜

---

🔥 EXAMPLES 🔥

If you run ppp in -auto mode, pppctl can be used to automate so many frequent tasks (and actually you can control ppp in any mode except interactive mode — noted 📝).

Use of the -p option is discouraged — even in scripts that aren't readable by others — because a ps(1) listing may reveal your secret. like, literally everyone can see it. 💀

The best way to allow easy, secure pppctl access is to create a local server socket in /etc/ppp/ppp.conf (in the correct section) like this:

set server /var/run/internet "" 0177

This will instruct ppp to create a local domain socket, with srw------- permissions and no password, allowing access only to the user that invoked ppp. Refer to the ppp(8) man page for further details. 🫶

You can now create some easy-access scripts. To connect to the internet:

#! /bin/sh
test $# -eq 0 && time=300 || time=$1
exec pppctl /var/run/internet set timeout $time\; dial

To disconnect:

#! /bin/sh
exec pppctl /var/run/internet set timeout 300\; close

To check if the line is up:

#! /bin/sh
pppctl -p '' -v /var/run/internet quit | grep ^PPP >/dev/null
if [ $? -eq 0 ]; then
  echo Link is up
else
  echo Link is down
fi

You can even make a generic script:

#! /bin/sh
exec pppctl /var/run/internet "$@"

✨ iconic. you could also use pppctl to control when dial-on-demand works. Suppose you want ppp to run all the time, but you wanna prevent dial-out between 8pm and 8am each day. However — and this is the important part — any connections active at 8pm should continue to remain active until they're closed or naturally time out.

A cron(8) entry for 8pm which runs:

pppctl /var/run/internet set filter dial 0 deny 0 0

will block all further dial requests, and the corresponding 8am entry:

pppctl /var/run/internet set filter dial -1

will allow them again. 🧚 periodt.

---

🌈 SEE ALSO 🌈

ps(1), editline(3), editrc(5), services(5), ppp(8)

---

💖 HISTORY 💖

The pppctl utility first appeared in FreeBSD 2.2.5.

---

and that's the whole page bb 🦋 — this one came out of the Debian fam, dated June 26, 1997, and honestly? she's aged like fine wine. mwah 💋🎀