pure-uploadscript(8)

1pure-uploadscript(8)               Pure-FTPd              pure-uploadscript(8)
2
3
4

NAME

6       pure-uploadscript  - Automatically run an external program after a suc‐
7       cessful upload
8

SYNTAX

10       pure-uploadscript [-p </path/to/pidfile>] [-B] [-g <gid>] [-h] -r <pro‐
11       gram to run> [-u <uid>]
12

DESCRIPTION

14       If  Pure-FTPd  is  compiled with --with-uploadscript (default in binary
15       distributions), and if the -o (or  --uploadscript)  is  passed  to  the
16       server,  a named pipe called /var/run/pure-ftpd.upload.pipe is created.
17       You    will    also     notice     an     important     file     called
18       /var/run/pure-ftpd.upload.lock, used for locking.
19       After a successful upload, the file name is written to the pipe.
20       pure-uploadscript  reads  this pipe to automatically run any program or
21       script to process the newly uploaded file.
22

OPTIONS

24       -B     Daemonize the process and fork it in background.
25
26       -g <gid>
27              Switch the group ID to <gid>.
28
29       -h or --help
30              Display available options.
31
32       -r <program to run>
33              Tell what program/script to run. It has to be an absolute  file‐
34              name, the PATH environment variable is ignored.  The first argu‐
35              ment of that program will be the  unquoted  name  of  the  newly
36              uploaded  file.   Environment variables aren't cleared. So don't
37              put sensitive data in them before calling  pure-uploadscript  if
38              you switch uid.
39
40       -u <uid>
41              Switch the user ID to <uid>.
42

ENVIRONMENT

44       When  the  upload script is run, the name of the newly uploaded file is
45       the first argument passed to the  script  (referenced  as  $1  by  most
46       shells)  .  Some  environment  variables are also filled by useful info
47       about  the  file.   UPLOAD_SIZE  The  size  of  the  file,  in   bytes.
48       UPLOAD_PERMS  The  permissions,  as  an  octal integer.  UPLOAD_UID The
49       numerical UID of the owner.  UPLOAD_GID The numerical GID of the owner.
50       UPLOAD_USER  The  login  of the owner.  UPLOAD_GROUP The group name the
51       files belongs to.  UPLOAD_VUSER The full user name, or the virtual user
52       name (127 chars max) .
53

FILES

55       /var/run/pure-ftpd.upload.pipe           /var/run/pure-ftpd.upload.lock
56       /var/run/pure-uploadscript.pid
57

SECURITY

59       pure-ftpd and pure-uploadscript are trying to limit  security  implica‐
60       tions of such a feature.
61
62       -  The  pipe can only be created and opened by root. It must have perms
63       600, with uid 0, or it will be ignored.
64
65       - The argument passed to an external program/script is always an  exact
66       absolute  path  name. It doesn't get fooled by chroot()ed environments,
67       and by absolute or relative paths added to the STOR command.
68
69       - UID and GID are set just  after  parsing  command-line  options,  and
70       pure-uploadscript never gets back supervisor privileges.
71
72       -   Descriptors   to  the  pipe  are  never  passed  to  external  pro‐
73       grams/scripts. So when UID switched, the target  user  can't  mess  the
74       pipe.
75
76       -  Only  regular  files are processed, control characters are rejected,
77       and a header+footer avoid partial file names.
78
79       - Two external programs/scripts can't run at the same time. Uploads are
80       always processed sequentially, in chronological order. This is to avoid
81       denial-of-services by issuing a lot of simultaneous  STOR  commands  in
82       order  to  launch a fork bomb on the server. For this reason, your pro‐
83       grams shouldn't take a long time to complete (but they  can  run  them‐
84       selves in background) .
85

EXAMPLES

87       A sample script could be:
88
89       #! /bin/sh
90       echo  "$1  uploaded"  |  /usr/bin/mutt  -s  "New  upload:  $1" \ ftpad‐
91       min@dom.ai.n
92
93       Never forget to quote ("variable") all  variables  in  all  your  shell
94       scripts to avoid security flaws.
95
96

AUTHORS

98       Frank DENIS <j at pureftpd dot org>
99
100