From 01a39884c8adca68da7f1e991c67757257bf7d9a Mon Sep 17 00:00:00 2001 From: Holger Weiss Date: Wed, 18 Jul 2018 23:12:33 +0200 Subject: [PATCH] Move documentation into README.md --- README.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ upload.pm | 42 ++++------------------ 2 files changed, 108 insertions(+), 36 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..effce89 --- /dev/null +++ b/README.md @@ -0,0 +1,102 @@ +upload.pm +========= + +This [Nginx][1] module implements the HTTP server's part of the XMPP extension +[XEP-0363: HTTP File Upload][2]. It can be used with either ejabberd's +[`mod_http_upload`][3] or Prosody's [`mod_http_upload_external`][4]. + +Nginx setup +----------- + +1. Create a directory and move `upload.pm` into it, e.g.: + + ```sh + # mkdir -p /usr/local/lib/perl + # wget -P /usr/local/lib/perl https://git.io/fNZgL + ``` + +2. Install the [`ngx_http_perl_module`][5]. 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: + + ```nginx configuration file + # This directive was probably added by the distribution package already: + load_module modules/ngx_http_perl_module.so; + + http { + # Add the following two lines to the existing "http" block. + perl_modules /usr/local/lib/perl; # Path to upload.pm. + perl_require upload.pm; + } + + 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 this directory: + 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 `upload.pm` 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`][3] option `put_url` point to Nginx, and specify +exactly the same `external_secret` as in the `upload.pm` settings: + +```yaml +modules: + mod_http_upload: + put_url: "https://upload.example.com" + external_secret: "it-is-secret" + max_size: 104857600 # 100 MiB, also specified in the Nginx configuration. +``` + +Prosody setup +------------- + +Let the [`mod_http_upload_external`][4] option `http_upload_external_base_url` +point to Nginx, and specify exactly the same `http_upload_external_secret` as in +the `upload.pm` settings: + +```lua +http_upload_external_base_url = "https://upload.example.com" +http_upload_external_secret = "it-is-secret" +http_upload_external_file_size_limit = 104857600 -- 100 MiB +``` + +Contact +------- + +If you have any questions, you could ask in the ejabberd room: +`ejabberd@conference.process-one.net` (the maintainer of this module is usually +joined as _Holger_). + +[1]: https://nginx.org/en/ +[2]: https://xmpp.org/extensions/xep-0363.html +[3]: https://docs.ejabberd.im/admin/configuration/#mod-http-upload +[4]: https://modules.prosody.im/mod_http_upload_external.html#implementation +[5]: https://nginx.org/en/docs/http/ngx_http_perl_module.html diff --git a/upload.pm b/upload.pm index 88c1118..76f56b9 100644 --- a/upload.pm +++ b/upload.pm @@ -1,5 +1,6 @@ -# See: https://modules.prosody.im/mod_http_upload_external.html -# +# Nginx module to handle file uploads and downloads for ejabberd's +# mod_http_upload or Prosody's mod_http_upload_external. + # Copyright 2018 Holger Weiss # # Permission to use, copy, modify, and/or distribute this software for any @@ -16,43 +17,12 @@ package upload; -#### INSTALLATION - -# 1) Create a directory and move this module into it, e.g., /usr/local/lib/perl. -# -# 2) Install ngx_http_perl_module (on Debian/Ubuntu: libnginx-mod-http-perl). -# -# 3) Add the following snippets to the appropriate sections of your Nginx -# configuration (the "load_module" directive might've been added by a -# distribution package already): -# -# load_module modules/ngx_http_perl_module.so; -# http { -# # [...] -# perl_modules /usr/local/lib/perl; -# perl_require upload.pm; -# } -# server { -# # [...] -# location / { -# perl upload::handle; -# } -# } -# -# 4) Adjust the configuration below. Notes: -# -# - The $external_secret must match the one specified in your XMPP server's -# upload module configuration. -# - If the root path of the upload URIs (i.e., the "location" specified in -# Nginx) isn't "/" but "/some/prefix/", $uri_prefix_components must be set -# to the number of directory levels; for "/some/prefix/", it would be 2. - -#### CONFIGURATION +## CONFIGURATION ----------------------------------------------------- my $external_secret = 'it-is-secret'; +my $uri_prefix_components = 0; my $file_mode = 0640; my $dir_mode = 0750; -my $uri_prefix_components = 0; my %custom_headers = ( 'Access-Control-Allow-Origin' => '*', 'Access-Control-Allow-Methods' => 'OPTIONS, HEAD, GET, PUT', @@ -60,7 +30,7 @@ my %custom_headers = ( 'Access-Control-Allow-Credentials' => 'true', ); -#### END OF CONFIGURATION +## END OF CONFIGURATION ---------------------------------------------- use warnings; use strict;