Nginx module to handle file uploads and downloads for XMPP servers
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

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.

  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).