pure-authd(8)

💅 pure-authd(8) — the external auth bestie for Pure-FTPd

Okay so real talk, this is the pure-authd(8) page from the Pure-FTPd fam, and it's basically the introvert of the suite: it sits on a Unix socket, forks your auth program, and whispers the answers back to whoever asked. Let's get into it ✨

---

🌸 NAME 🌸

pure-authd — the External authentication agent for Pure-FTPd. That's the whole vibe. It's the middleman, the group-chat admin, the one who relays your login tea ☕

---

🎀 SYNTAX 🎀

pure-authd [-p </path/to/pidfile>] [-u uid] [-g gid] [-B] <-s
/path/to/socket> -r /program/to/run

That's it, that's the whole summoning ritual 🕯️ (and yeah, -s and -r are the non-negotiable ones, everything else is garnish)

---

🦋 DESCRIPTION 🦋

So pure-authd is a daemon that forks an authentication program, waits for an authentication reply, and feeds it to an application server. Middleman behavior, honestly iconic 🔥

It listens to a local Unix socket. When something new connects to that socket, it should feed pure-authd this exact structure:

account:xxx
password:xxx
localhost:xxx
localport:xxx
peer:xxx
end

(replace xxx with appropriate values, bestie — don't leave the literal x's in there 💀)

Quick decoder ring: localhost, localport and peer are numeric IP addresses and ports. And peer is the IP address of the remote client. That's the one you actually care about for logs, iykyk 👀

These arguments then get passed to the authentication program as environment variables:

AUTHD_ACCOUNT
AUTHD_PASSWORD
AUTHD_LOCAL_IP
AUTHD_LOCAL_PORT
AUTHD_REMOTE_IP
AUTHD_ENCRYPTED

Your authentication program should take appropriate actions to fetch account info based on all that, and then reply to standard output with a structure like this one:

auth_ok:1
uid:42
gid:21
dir:/home/j
end

Now let's break down every single field, because they all matter and I refuse to skip a single one 💖

• auth_ok:xxx — the moment of truth:
  • If xxx is 0, the user was not found (the next authentication method passed to pure-ftpd will be tried).
  • If xxx is -1, the user was found, but there was a fatal authentication error: user is root, password is wrong, account has expired, etc. (next authentication methods will not be tried).
  • If xxx is 1, the user was found and successfully authenticated. Pop the confetti 🎉
• uid:xxx — The system uid to be assigned to that user. Must be > 0.
• gid:xxx — The primary system gid. Must be > 0.
• dir:xxx — The absolute path to the home directory. Can contain /./ for a chroot jail. Cute and also load-bearing 🔒
• slow_tilde_expansion:xxx (optional, default is 1) — When the command 'cd ~user' is issued, it's handy to go to that user's home directory, as expected in a shell environment. But fetching account info can be an expensive operation for non-system accounts. If xxx is 0, 'cd ~user' will expand to the system user home directory. If xxx is 1, 'cd ~user' won't expand. You should use 1 in most cases with external authentication, when your FTP users don't match system users. You can also set xxx to 1 if you're using slow nss_* system authentication modules. Yes this is a lot of words for a tilde, but it's important words 🫶
• throttling_bandwidth_ul:xxx (optional) — The allocated bandwidth for uploads, in bytes per second.
• throttling_bandwidth_dl:xxx (optional) — The allocated bandwidth for downloads, in bytes per second.
• user_quota_size:xxx (optional) — The maximal total size for this account, in bytes.
• user_quota_files:xxx (optional) — The maximal number of files for this account.
• ratio_upload:xxx (optional)
• radio_download:xxx (optional) — The user must match a ratio_upload:ratio_download ratio. (Yes, the page literally says radio_download up there and then ratio_download down here. I'm not touching it. That's canon. Copy it exactly at your own peril 😭)

⚠️ Big one: only one authentication program is forked at a time. It must return quickly. No lazy auth program allowed, she has places to be 💅

---

🌈 OPTIONS 🌈

• -u <uid> — Have the daemon run with that uid.
• -g <gid> — Have the daemon run with that gid.
• -B — Fork in background (daemonization). Bye-bye foreground, hello little ghost process 👻
• -s </path/to/socket> — Set the full path to the local Unix socket.
• -r </path/to/program> — Set the full path to the authentication program.
• -h — Output help information and exit. The classic "wait what were the flags again" button 🙈

---

⭐ EXAMPLES ⭐

To run this program the standard way, type:

pure-authd -s /var/run/ftpd.sock -r /usr/bin/my-auth-program &

pure-ftpd -lextauth:/var/run/ftpd.sock &

And /usr/bin/my-auth-program can be as simple as:

#! /bin/sh
echo 'auth_ok:1'
echo 'uid:42'
echo 'gid:21'
echo 'dir:/home/j'
echo 'end'

Like, genuinely that's the whole program. Shell script girlies stay winning 🐚✨

---

👑 AUTHORS 👑

Frank DENIS <j at pureftpd dot org> — the original author, the blueprint, the main character of this page.

---

💜 SEE ALSO 💜

ftp(1), pure-ftpd(8) pure-ftpwho(8) pure-mrtginfo(8) pure-uploadscript(8) pure-statsdecode(8) pure-pw(8) pure-quotacheck(8) pure-authd(8) pure-certd(8)

Also RFC 959, RFC 2389, RFC 2228 and RFC 2428. Reading RPCs is self-care, allegedly 📚

---

Anyway bestie, that's the page! Big kiss from Frank Denis, version 1.0.54, and this little pure-authd(8) manual page, signing off — go forth and authenticate responsibly 💖✨🎀🦋