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) pure-certd(8)

       RFC 959, RFC 2228, RFC 2389 and RFC 2428.