README

   1 Download Server
   2 ===============
   3
   4 (c) 2012 Alex Bligh - Provided under the MIT Licence. See LICENCE file.
   5
   6 This download server provides reliable logged downloads over http. It is
   7 intended to be used where:
   8
   9 A. A website (such as a Wordpress website) wants to offer a downlaod facility
  10    and record the downloads made. Let's call this the 'source website'.
  11
  12 B. The download should come from a different website (possibly because the
  13    source website is https and large downloads over http are resource
  14    consumptive). Let's call this the 'download web site'.
  15
  16 C. It is imperative that the download must be tracked by authenticated
  17    username, and by time and success.
  18
  19 The strategy used is as follows:
  20
  21 1. The source website contains a link to a download page, which appears
  22    to be on the source website, but in fact is redirect page.
  23
  24 2. The redirect page redirects to a dynamically constructed URL on
  25    on the download site. That URL is a URL for a CGI script with the
  26    following parameters:
  27
  28      a) the file to be downloaded (or the name of a symlink to
  29         such a file).
  30
  31      b) the id of the user against whom the download is to be logged.
  32
  33      c) the UNIX time (since epoch)
  34
  35      d) a hash of the above plus a shared secret
  36
  37 3. The download script checks the parameters, checks the time is
  38    within a few seconds, and checks the hash value. If these match, it
  39    serves the file, logging start, success and errors. The purpose of the
  40    time check is so that the URL can't realistically be distributed to
  41    others. The hash prevents tampering with the parameters.
  42
  43
  44 INSTALLATION
  45 ============
  46
  47 httpd.conf.example contains an example httpd.conf for the downloads server
  48
  49 download.pl contains the script to go in the download directory on the
  50 download server, and should be marked executable. In this example that
  51 would be
  52   /var/www/server.example.com/download/download.pl
  53
  54 ambdownload.php is a Wordpress plugin which will can be installed in the
  55 plugins directory in Wordpress, e.g. in
  56   wp-content/plugins/ambdownload/ambdownload.php
  57 This allows setting of a custom meta on a page to turn it into a download
  58 page. For instance, if you wished to make a page redirect to download
  59 'myfile', set a custom meta key for that page named 'download_file'
  60 to the value 'myfile'. You will need to enable this module once you have
  61 installed it.
  62
  63 You should set the following meta keys:
  64     download_file - the tag of the file (see above)
  65     download_url - the base URL of the perl script, e.g
  66                  http://server.example.com/download/download.pl
  67     download_error - if set, redirects to this page if a user is not set
  68
  69 Note, to avoid having to muck around with Wordpress, myfile could be a symlink,
  70 and the script will correctly name the downloaded file as per the target of the
  71 symlink.
  72
  73 Running download.pl with two parameters, e.g.
  74    /var/www/server.example.com/download/download.pl 'myname@example.com' 'myfile'
  75 will print out the URL to use to download 'myfile', logged as
  76 'myname@example.com'
  77
  78 Your files to be downloaded should be put in
  79   /var/www/server.example.com/download/
  80 These may be symlinks. The apache configuration will prevent them from being
  81 downloaded directly.
  82
  83 Ensure both servers have a file
  84   /etc/apache2/download.secret
  85 with some random textual data in. 32 random ASCII characters should be fine.
  86 You can change this whenever you want, provided it's changed on both servers
  87 simultaneously.
  88
  89 Logging will take place to
  90   /var/log/download.log
  91 Ensure this file is created by you, and owned by the user running cgi scripts.
  92 Usually this will do
  93   # >/var/log/download.log
  94   # chown www-data:www-data /var/log/download.log
  95
  96 You will need to do your own log rotation.
  97
  98