Nginx module to handle file uploads and downloads for XMPP servers
Go to file
Holger Weiss c4d3486b12 Don't stumble over undefined request arguments
Don't yield an "unitialized value" error if Nginx didn't define the
method that returns the request arguments.
2020-07-02 08:25:35 +02:00
LICENSE.txt Move license terms into LICENSE.txt file 2018-07-19 19:28:10 +02:00 Add instruction for Docker 2019-04-29 15:53:05 +01:00 Don't stumble over undefined request arguments 2020-07-02 08:25:35 +02:00

This Nginx module implements the HTTP server's part of the XMPP extension XEP-0363: HTTP File Upload. It can be used with either ejabberd's mod_http_upload or Prosody's mod_http_upload_external.

Nginx setup

  1. Create a directory and move into it, e.g.:

    # mkdir -p /usr/local/lib/perl
    # wget -O /usr/local/lib/perl/
  2. Install the ngx_http_perl_module. On Debian/Ubuntu-based distributions, the package is called libnginx-mod-http-perl, on RedHat/CentOS-based distributions, it's nginx-mod-http-perl. If you're using Docker, make sure you use the image ending in -perl.

  3. Add the following snippets to the appropriate sections of your Nginx configuration:

    # This directive was probably added by the distribution package already:
    load_module modules/;
    http {
        # Add the following two lines to the existing "http" block.
        perl_modules /usr/local/lib/perl; # Path to
    server {
        # Specify directives such as "listen", "server_name", and TLS-related
        # settings for the "server" that handles the uploads.
        # Uploaded files will be stored below the "root" directory. To minimize
        # disk I/O, make sure the specified path is on the same file system as
        # the directory used by Nginx to store temporary files holding request
        # bodies ("client_body_temp_path", often some directory below /var).
        root /var/www/upload;
        # Specify this "location" block (if you don't use "/", see below):
        location / {
            perl upload::handle;
        # Upload file size limit (default: 1m), also specified in your XMPP
        # server's upload module configuration (see below):
        client_max_body_size 100m;
  4. Open in an editor and adjust the configuration at the top of the file:

    • The $external_secret must match the one specified in your XMPP server's upload module configuration (see below).

    • If the root path of the upload URIs (the location specified in the Nginx server block) isn't / but /some/prefix/, $uri_prefix_components must be set to the number of directory levels. So, for /some/prefix/, it would be 2.

ejabberd setup

Let the mod_http_upload option put_url point to Nginx, and specify exactly the same external_secret as in the settings:

    put_url: ""
    external_secret: "it-is-secret"
    max_size: 104857600 # 100 MiB, also specified in the Nginx configuration.

Prosody setup

Let the mod_http_upload_external option http_upload_external_base_url point to Nginx, and specify exactly the same http_upload_external_secret as in the settings:

http_upload_external_base_url = ""
http_upload_external_secret = "it-is-secret"
http_upload_external_file_size_limit = 104857600 -- 100 MiB


If you have any questions, you could ask in the ejabberd room: (the maintainer of this module is usually joined as Holger).