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  /var/run/pure-ftpd.up‐
18       load.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  up‐
36              loaded file.  Environment variables aren't cleared. So don't put
37              sensitive data in them before calling pure-uploadscript  if  you
38              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.   UP‐
48       LOAD_PERMS The permissions, as an octal integer.  UPLOAD_UID The numer‐
49       ical UID of the owner.  UPLOAD_GID The numerical GID of the owner.  UP‐
50       LOAD_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