pure-uploadscript
pure-uploadscript(8) Pure-FTPd pure-uploadscript(8)
NAME
pure-uploadscript - Automatically run an external program after a suc-
cessful upload
SYNTAX
pure-uploadscript [-p </path/to/pidfile>] [-B] [-g <gid>] [-h] -r <pro-
gram to run> [-u <uid>]
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.
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.
OPTIONS
-B Daemonize the process and fork it in background.
-g <gid>
Switch the group ID to <gid>.
-h or --help
Display available options.
-r <program to run>
Tell what program/script to run. It has to be an absolute file-
name, the PATH environment variable is ignored. The first argu-
ment 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>.
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
files 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 implica-
tions of such a feature.
- 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 pro-
grams/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 pro-
grams shouldn't take a long time to complete (but they can run them-
selves in background) .
EXAMPLES
A sample script could be :
#! /bin/sh
echo "$1 uploaded" | /usr/bin/mutt -s "New upload : $1" \ ftpad-
min@dom.ai.n
Never forget to quote ("variable") all variables in all your shell
scripts to avoid security flaws.
AUTHORS
Frank DENIS <j@pureftpd.org>
SEE ALSO
ftp(1), pure-ftpd(8) pure-ftpwho(8) pure-mrtginfo(8) pure-upload-
script(8) pure-statsdecode(8) pure-pw(8) pure-quotacheck(8) pure-
authd(8)
RFC 959, RFC 2228, RFC 2389 and RFC 2428.
Pure-FTPd team 1.0.2 pure-uploadscript(8)
