ABCDEFGHIJKLMNOPQRSTUVWXYZ

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)