1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
.. GENERATED FILE, DO NOT EDIT DIRECTLY
This file is automatically generated using https://codeberg.org/slidge/legacy-module-template/
Its source is at:
https://codeberg.org/slidge/legacy-module-template/src/branch/main/docs/source/admin/attachments.rst.jinja
Open a pull request for this repository instead, to benefit the documentation of all slidge-based gateways.
.. _attachments:
===========
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 <https://prosody.im/doc/modules/mod_http_files>`_, etc.).
.. _upload:
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 :ref:`generic-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 :ref:`configuration file <config-file>`, use ``upload-service=upload.example.org``
.. code-block:: lua
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 <https://prosody.im/doc/modules/mod_http_file_share>`_.
Example 2: ejabberd mod_http_upload
-----------------------------------
In matridge's :ref:`configuration file <config-file>`, use ``upload-service=example.org``
The subdomain's FQDN (example.org) should be listed under the top level 'hosts'.
.. code-block:: yaml
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
<https://docs.ejabberd.im/admin/configuration/modules/#mod-http-upload>`_.
.. _no-upload:
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 :ref:`generic-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 <https://prosody.im/doc/modules/mod_http_files>`_.
.. code-block:: lua
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"
.. _nginx-no-upload:
Example 2: nginx
----------------
Here, ``no-upload-url-prefix`` would be ``https://example.org/matridge/``.
.. code-block:: nginx
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 <https://docs.nginx.com/nginx/admin-guide/web-server/serving-static-content/>`_ for more info.
Next steps
==========
To make your matridge install top notch, set up its :ref:`privileges <privileges>`.
|
