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