Configuration¶
Both matteridge-specific options and slidge generic options can be set using config text file(s), command-line arguments, or environment variables.
Config files¶
Location¶
By default, matteridge uses all config files found in /etc/slidge/conf.d/*.conf.
You can change this using the SLIDGE_CONF_DIR env var, eg
SLIDGE_CONF_DIR=/path/dir1:/path/dir2:/path/dir3.
We recommend using /etc/slidge/conf.d/common.conf file to set
the options common to several slidge-based gateways
(eg, attachment handling, logging options, etc.),
then use a matteridge-specific dedicated config file, eg
/etc/slidge/matteridge.conf.
Point to this specific file using the -c command line argument when
launching matteridge.
matteridge -c /etc/slidge/matteridge.conf
Syntax¶
Config files are simple text files with key=value entries.
some-option=some-value
some-other-option=some-other-value
Command-line arguments¶
To pass options as command-line arguments, prepend their name with --.
matteridge --some-option=some-value --some-other-option=some-other-value
Environment variables¶
To pass options as environment variables:
uppercase their name;
substitue dashed for underscores;
prepend with
SLIDGE_for generic slidge options, orMATTERIDGE_for matteridge-specific options.
SLIDGE_SOME_GENERIC_OPTION=some-value
MATTERIDGE_SOME_SPECIFIC_OPTION=some-other-value
matteridge-specific config¶
matteridge provides the instance-wide options displayed in the table below.
| name | default | help |
|---|---|---|
| backfill-posts | 30 | Number of posts to fetch for channels (before slidge was launched) |
| max-participants | 100 | Maximum number of participants to fetch in groups. |
| user-agent | Mattermost/XMPP (Matteridge) | User-Agent string (set as header on requests sent to Mattermost servers) |
Generic slidge config¶
Note
The following options are for slidge version 0.3.11.
Depending on how you installed matteridge, you might have a different version of slidge.
Use matteridge --help for the exact list of options you can use.
Slidge provides the generic instance-wide options displayed in the table below. They may not all have an effect on matteridge’s behaviour.
Mandatory settings¶
| name | default | help |
|---|---|---|
| secret | unset | The gateway component’s secret (required to connect to the XMPP server) |
| jid | unset | The gateway component’s JID |
Basic configuration¶
| name | default | help |
|---|---|---|
| admins | () | JIDs of the gateway admins |
| mam-max-days | 7 | Maximum number of days for group archive retention. |
| port | 5347 | The XMPP server’s port for incoming component connections |
| server | localhost | The XMPP server’s host name. Defaults to localhost, which is the standard way of running slidge, on the same host as the XMPP server. The ‘Jabber Component Protocol’ (XEP-0114) does not mention encryption, so you *should* provide encryption another way, eg via port forwarding, if you change this. |
| legacy-module | unset | Importable python module containing (at least) a BaseGateway and a LegacySession subclass. NB: this is not needed if you use a gateway-specific entrypoint, e.g., `slidgram` or `python -m slidgram`. |
| home-dir | inferred | Directory where slidge will writes it persistent data and cache. Defaults to /var/lib/slidge/${SLIDGE_JID}. |
| user-jid-validator | inferred | Regular expression to restrict users that can register to the gateway, by JID. Defaults to .*@${INFERRED_SERVER}. INFERRED_SERVER is derived for the gateway JID, by removing whatever is before the first encountered dot in it. Example: if slidge’s JID=slidge.example.org, INFERRED_SERVER=example.org. |
Attachments¶
| name | default | help |
|---|---|---|
| attachment-maximum-file-name-length | 200 | Some legacy network provide ridiculously long filenames, strip above this limit, preserving suffix. |
| convert-stickers | False | Convert lottie vector stickers (from the legacy side) to webp animations. |
| fix-filename-suffix-mime-type | False | Fix the Filename suffix based on the Mime Type of the file. Some clients (eg Conversations) may not inline files that have a wrong suffix for the MIME Type. Therefore the MIME Type of the file is checked, if the suffix is not valid for that MIME Type, a valid one will be picked. |
| no-upload-file-read-others | False | After writing a file in NO_UPLOAD_PATH, change its permission so that ‘others’ can read it. |
| no-upload-method | copy | Whether to ‘copy’, ‘move’, ‘hardlink’ or ‘symlink’ the files in no-upload-path. |
| no-upload-path | None | Instead of using the XMPP server’s HTTP upload component, copy files to this dir. You need to set NO_UPLOAD_URL_PREFIX too if you use this option, and configure an web server to serve files in this dir. |
| no-upload-url-prefix | None | Base URL that servers files in the dir set in the no-upload-path option, eg https://example.com:666/slidge-attachments/ |
| upload-requester | None | Set which JID should request the upload slots. Defaults to the user’s JID if IQ/get privileges granted for the ‘urn:xmpp:http:upload:0’ namespace; the component JID otherwise. |
| upload-service | None | JID of an HTTP upload service the gateway can use. This is optional, as it should be automatically determined via servicediscovery. |
| upload-url-prefix | None | This is an optional setting to make sure the URL of your upload service is never leaked to the legacy network in bodies of messages. This can happen under rare circumstances and/or bugs,when replying to an attachment. Set this to the common prefix of the public URL your attachments get, eg https://upload.example.org:5281/ |
| use-attachment-original-urls | False | For legacy plugins in which attachments are publicly downloadable URLs, let XMPP clients directly download them from this URL. Note that this will probably leak your client IP to the legacy network. |
Logging¶
| name | default | help |
|---|---|---|
| log-file | None | Log to a file instead of stdout/err |
| log-format | %(levelname)s:%(name)s:%(message)s | Optionally, a format string for logging messages. Refer to https://docs.python.org/3/library/logging.html#logrecord-attributes for available options. |
Advanced settings¶
| name | default | help |
|---|---|---|
| avatar-resampling-threads | 2 | Number of additional threads to use for avatar resampling. Even in a single-core context, this makes avatar resampling non-blocking. |
| avatar-size | 200 | Maximum image size (width and height), image ratio will be preserved |
| component-name | None | Overrides the default component name with a custom one. This is seen in service discovery and as the nickname of the component in chat windows. |
| dev-mode | False | Enables an interactive python shell via chat commands, for admins.Not safe to use in prod, but great during dev. |
| ignore-delay-threshold | 300 | Threshold, in seconds, below which the <delay> information is stripped out of emitted stanzas. |
| partial-registration-timeout | 3600 | Timeout before registration and login. Only useful for legacy networks where a single step registration process is not enough. |
| qr-timeout | 60 | Timeout for QR code flashing confirmation. |
| strip-leading-emoji-adhoc | False | Strip the leading emoji in ad-hoc command names, if present, in case you are a emoji-hater. |
| welcome-message | None | Overrides the default welcome message received by newly registered users. |
| db-url | inferred | Database URL, see <https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls>. Defaults to sqlite:///${HOME_DIR}/slidge.sqlite |
Advanced logging configuration¶
To customize the output of the slidge, you can use the command line argument --log-config
to specify a logging configuration file.