pure-uploadscript(8)

💅 pure-uploadscript(8) — Pure-FTPd's upload after-party 💅

okay so bestie, this is the manual page for pure-uploadscript(8) from Pure-FTPd. It's the little helper that runs an external program after a successful upload. The vibe? Upload lands, script goes brrr. Periodt. ✨

🎀 NAME 🎀

pure-uploadscript — Automatically run an external program after a successful upload.

🌸 SYNTAX 🌸

pure-uploadscript [-p </path/to/pidfile>] [-B] [-g <gid>] [-h] -r <program to run> [-u <uid>]

quick side quest: the syntax also shows -p </path/to/pidfile>, but the OPTIONS section below never explains it, so I'm not inventing lore. iykyk 🫶

🦋 DESCRIPTION 🦋

If Pure-FTPd is compiled with --with-uploadscript (default in binary distributions), and if the -o (or --uploadscript) is passed to the server, a named pipe called /var/run/pure-ftpd.upload.pipe is created.

You will also notice an important file called /var/run/pure-ftpd.upload.lock, used for locking. Very main character of it.

After a successful upload, the file name is written to the pipe. pure-uploadscript reads this pipe to automatically run any program or script to process the newly uploaded file. Slay, honestly.

✨ OPTIONS ✨

• -B — Daemonize the process and fork it in background. It ghosts into daemon mode ✨
• -g <gid> — Switch the group ID to <gid>.
• -h, --help — Display available options.
• -r <program to run> — Tell what program/script to run. It has to be an absolute filename, the PATH environment variable is ignored. The first argument of that program will be the unquoted name of the newly uploaded file. Environment variables aren't cleared. So don't put sensitive data in them before calling pure-uploadscript if you switch uid.
• -u <uid> — Switch the user ID to <uid>.

bestie warning: that -r note about env vars is real. If you're switching uid, don't leave sensitive stuff chilling in environment variables before calling pure-uploadscript. ngl, that's giving "please don't leak" energy 💀

🌈 ENVIRONMENT 🌈

When the upload script is run, the name of the newly uploaded file is the first argument passed to the script (referenced as $1 by most shells). Some environment variables are also filled by useful info about the file.

• UPLOAD_SIZE — The size of the file, in bytes.
• UPLOAD_PERMS — The permissions, as an octal integer.
• UPLOAD_UID — The numerical UID of the owner.
• UPLOAD_GID — The numerical GID of the owner.
• UPLOAD_USER — The login of the owner.
• UPLOAD_GROUP — The group name the file belongs to.
• UPLOAD_VUSER — The full user name, or the virtual user name (127 chars max).

🎀 FILES 🎀

• /var/run/pure-ftpd.upload.pipe
• /var/run/pure-ftpd.upload.lock
• /var/run/pure-uploadscript.pid

🔐 SECURITY 🔐

pure-ftpd and pure-uploadscript are trying to limit security implications of such a feature. Respect the hustle.

• The pipe can only be created and opened by root. It must have perms 600, with uid 0, or it will be ignored.
• The argument passed to an external program/script is always an exact absolute path name. It doesn't get fooled by chroot()ed environments, and by absolute or relative paths added to the STOR command.
• UID and GID are set just after parsing command-line options, and pure-uploadscript never gets back supervisor privileges.
• Descriptors to the pipe are never passed to external programs/scripts. So when UID switched, the target user can't mess the pipe.
• Only regular files are processed, control characters are rejected, and a header+footer avoid partial file names.
• Two external programs/scripts can't run at the same time. Uploads are always processed sequentially, in chronological order. This is to avoid denial-of-services by issuing a lot of simultaneous STOR commands in order to launch a fork bomb on the server. For this reason, your programs shouldn't take a long time to complete (but they can run themselves in background).

💖 EXAMPLES 💖

A sample script could be:

#! /bin/sh
echo "$1 uploaded" | /usr/bin/mutt -s "New upload: $1" \
ftpadmin@dom.ai.n

Never forget to quote ("variable") all variables in all your shell scripts to avoid security flaws. fr fr, this is the unskippable tutorial level.

👑 AUTHORS 👑

Frank DENIS <j at pureftpd dot org>

🦋 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)
• RFC 959, RFC 2228, RFC 2389 and RFC 2428.

---

okay bye bestie 🫶 footer check: Frank Denis, version 1.0.54, manual pure-uploadscript(8) — no date printed on this footer, so I'm not making one up 💀. stay slaying 💖