mod_http_upload - HTTP File Upload (XEP-0363)

	Author: Holger Weiss <holger@zedat.fu-berlin.de>
	Requirements: ejabberd 13.06 or newer


	DESCRIPTION
	-----------

This module allows for requesting permissions to upload a file via HTTP.
If the request is accepted, the client receives a URL to use for uploading
the file and another URL from which that file can later be downloaded.

PLEASE NOTE: This module implements an experimental protocol which may
change at any time.  There are already suggestions for improvements, e.g.
from ProcessOne:

https://github.com/processone/ejabberd-saas-docs/blob/master/xmpp-specs/http-filetransfer/http-filetransfer.md


	CONFIGURATION
	-------------

In order to use this module, add configuration snippets such as the
following to your ejabberd.yml file:

  listen:
    # [...]
    -
      module: ejabberd_http
      port: 5443
      tls: true
      certfile: "/etc/ejabberd/example.com.pem"
      request_handlers:
        "": mod_http_upload

  modules:
    # [...]
    mod_http_upload:
      docroot: "/home/xmpp/upload"
      put_url: "https://@HOST@:5443"

The configurable mod_http_upload options are:

- host (default: "upload.@HOST@")

  This option defines the JID for the HTTP upload service.  The keyword
  @HOST@ is replaced with the virtual host name.

- name (default: "HTTP File Upload")

  This option defines the Service Discovery name for the HTTP upload
  service.

- access (default: 'local')

  This option defines the access rule to limit who is permitted to use the
  HTTP upload service.  The default value is 'local'.  If no access rule of
  that name exists, no user will be allowed to use the service.

- max_size (default: 104857600)

  This option limits the acceptable file size.  Either a number of bytes
  (larger than zero) or 'infinity' must be specified.

- secret_length (default: 40)

  This option defines the length of the random string included in the GET
  and PUT URLs generated by mod_http_upload.  The minimum length is 8
  characters, but it is recommended to choose a larger value.

- jid_in_url (default: 'sha1')

  When this option is set to 'node', the node identifier of the user's JID
  (i.e., the user name) is included in the GET and PUT URLs generated by
  mod_http_upload.  Otherwise, a SHA-1 hash of the user's bare JID is
  included instead.

- file_mode (default: 'undefined')

  This option defines the permission bits of uploaded files.  The bits are
  specified as an octal number (see the chmod(1) manual page) within double
  quotes.  For example: "0644".

- dir_mode (default: 'undefined')

  This option defines the permission bits of the 'docroot' directory and any
  directories created during file uploads.  The bits are specified as an
  octal number (see the chmod(1) manual page) within double quotes.  For
  example: "0755".

- docroot (default: "@HOME@/upload")

  Uploaded files are stored below the directory specified (as an absolute
  path) with this option.  It is mandatory to specify either this option or
  the 'service_url' option.  The keyword @HOME@ is replaced with the home
  directory of the user running ejabberd.

- put_url (default: "http://@HOST@:5444")

  This option specifies the initial part of the PUT URLs used for file
  uploads.  The keyword @HOST@ is replaced with the virtual host name.

  NOTE: Different virtual hosts cannot use the same PUT URL domain.

- get_url (default: $put_url)

  This option specifies the initial part of the GET URLs used for
  downloading the files.  By default, it is set to the same value as the
  'put_url', but you can set it to a different value in order to have the
  files served by a proper HTTP server such as Nginx or Apache.  The keyword
  @HOST@ is replaced with the virtual host name.

- service_url (default: 'undefined')

  If a 'service_url' is specified, HTTP upload slot requests are forwarded
  to this external service instead of being handled by mod_http_upload
  itself.  Such a service is available as a Django app, for example:

  https://github.com/mathiasertl/django-xmpp-http-upload

  An HTTP GET query such as the following is issued whenever an
  HTTP upload slot request is accepted as per the 'access' rule:

  http://localhost:5444/?jid=juliet%40example.com&size=10240&name=example.jpg

  In order to accept the request, the service must return an HTTP status
  code of 200 or 201 and two lines of text/plain output.  The first line is
  forwarded to the XMPP client as the HTTP upload PUT URL, the second line
  as the GET URL.

  In order to reject the request, the service should return one of the
  following HTTP status codes:

  - 402
    In this case, a 'resource-constraint' error stanza is sent to the
    client.  Use this to indicate a temporary error after the client
    exceeded a quota, for example.

  - 403
    In this case, a 'not-allowed' error stanza is sent to the client.  Use
    this to indicate a permanent error to a client that is not permitted to
    upload files, for example.

  - 413
    In this case, a 'not-acceptable' error stanza is sent to the client.
    Use this if the file size was too large, for example.

  In any other case, a 'service-unavailable' error stanza is sent to the
  client.

- custom_headers (default: [])

  This option specifies additional header fields to be included in all HTTP
  responses.  For example:

    custom_headers:
      "Access-Control-Allow-Origin": "*"
      "Access-Control-Allow-Methods": "OPTIONS, HEAD, GET, PUT"

- rm_on_unregister (default: 'true')

  This option specifies whether files uploaded by a user should be removed
  when that user is unregistered.  It must be set to 'false' if this is not
  desired.


	REMOVING OLD FILES
	------------------

You might want to use cron(8) to remove uploaded files that are older than
some number of days:

0 1 * * * find /home/xmpp/upload -type f -ctime +365 -exec rm -f '{}' ';'
0 2 * * * find /home/xmpp/upload -type d -exec rmdir '{}' ';' 2>/dev/null

Note that /home/xmpp/upload must be replaced with your actual 'docroot'
path, and 365 with the desired number of days.