Attachments

Note

Attachments from XMPP to Matrix require no special configuration.

For matridge to bridge attachments from Matrix to XMPP, you have two options:

• HTTP Upload: matridge will use your XMPP server’s upload component (XEP-0363).

• No upload: matridge will copy attachments to a path it can write to. You then need to serve these files from via an HTTP server (eg nginx, prosody’s http_files, etc.).

HTTP Upload

matridge can use the HTTP Upload component (XEP-0363) of your XMPP server, if you configure it with upload-service=upload.example.org (see Generic slidge config). In this setting, matridge will upload files just like any normal user of your server.

Example 1: prosody’s mod_http_file_share

In matridge’s configuration file, use upload-service=upload.example.org

modules_enabled = {
  -- make sure http_file_share is listed here
  "http_file_share";
}

Component "upload.example.org" "http_file_share"
  -- allow matridge to use the upload component
  http_file_share_access = { "matrix.example.org" }

More info: mod_http_file_share.

Example 2: ejabberd mod_http_upload

In matridge’s configuration file, use upload-service=example.org

The subdomain’s FQDN (example.org) should be listed under the top level ‘hosts’.

hosts:
  - "example.org"

acl:
  slidge_acl:
    server:
      - "matrix.example.org"

listen:
  -
    port: 5443
    module: ejabberd_http
    tls: true
    request_handlers:
      /upload: mod_http_upload

modules:
  mod_http_upload:
    # Any path that ejabberd has read and write access to
    docroot: /ejabberd/upload
    put_url: "https://@HOST@:5443/upload"
    access:
      - allow: local
      - allow: slidge_acl

To get more information about component configuration, see ejabberd’s docs.

No upload

You need to set up no-upload-path to point to a directory, and no-upload-url-prefix to an URL prefix pointing to files in that directory (see Generic slidge config for more detail). Example: no-upload-path=/var/www/matridge-attachments/ and no-upload-url-prefix=https://example.org/matridge/ means that /var/www/matridge-attachments/some-image.jpg is accessible at https://example.org/matridge/some-image.jpg

Make sure that no-upload-path is writeable by matridge and readable by your HTTP server. You may use no-upload-file-read-others=true to do that easily, but you might want to restrict which users can read this directory.

Warning

matridge will not take care of removing old files, so you should set up a cronjob, a systemd timer, or something similar, to regularly delete files, eg. find . -mtime +7 -delete && find . -depth -type d -empty -delete to clean up files older than a week.

For the following examples, in matridge’s config, you would have no-upload-path=/var/lib/matridge/attachments.

Example 1: prosody’s http_files

Here, no-upload-url-prefix would be https://example.org:5281/files/, as per the mod_http_files documentation.

modules_enabled = {
  -- make sure http_files is listed here
  "http_files";
}

-- Must be the same value as matridge's no-upload-path
http_files_dir = "/var/lib/matridge/attachments"

Example 2: nginx

Here, no-upload-url-prefix would be https://example.org/matridge/.

server {
  listen 80;
  server_name example.org;
  root /var/www/html;  # if you already have nginx serving files…

  # the section below is for matridge
  location /matridge {
    #  Must be the same value as matridge's no-upload-path
    alias /var/lib/matridge/attachments/;
  }
}

See the nginx docs for more info.

Next steps

To make your matridge install top notch, set up its privileges.