Skip to content
Back to top
View this page
Edit this page

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