Configuration

Note

For legacy module-specific options, refer to their own docs: matridge, matteridge, messlidger, skidge, sleamdge, slidcord, slidge-whatsapp, slidgnal, slidgram.

By default, slidge uses all config files found in /etc/slidge/conf.d/*. You can change this using the SLIDGE_CONF_DIR env var, eg SLIDGE_CONF_DIR=/path/dir1:/path/dir2:/path/dir3.

It is recommended to use /etc/slidge/conf.d/ to store configuration options common to all slidge components (eg, attachment handling, logging options, etc.), and to specify a plugin-specific file on startup, eg:

slidge -c /etc/slidge/superduper.conf

Note

For the debian unofficial package, just edit the /etc/slidge/conf.d/common.conf and /etc/slidge/*.conf files, and use Debian packages (systemd) to launch slidge.

Command-line arguments

-h, --help            show this help message and exit
-c, --config CONFIG   Path to a INI config file. [env var: SLIDGE_CONFIG]
--log-config LOG_CONFIG
                      Path to a INI config file to personalise logging output.
-q, --quiet           loglevel=WARNING (unused if --log-config is specified) [env var: SLIDGE_QUIET]
-d, --debug           loglevel=DEBUG (unused if --log-config is specified) [env var: SLIDGE_DEBUG]
--version             show program's version number and exit

Regarding the --log-config argument, refer to the official python documentation for the syntax.

Other options

Warning

Because of an ugly mess that will soon™ be fixed, it is impossible to use the config file to turn off boolean arguments that are true by default. As a workaround, use CLI args instead, e.g., --some-opt=false.

The following options can be used:

  • in a config file (see top of this page);

  • as command line arguments, prepended with --, e.g., --some-option=value;

  • as environment variables, upper case, prepended with SLIDGE_, and with dashes substituted with underscores, e.g., SLIDGE_SOME_OPTION=value.

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 .*@${SLIDGE_SERVER}, but since SLIDGE_SERVER is usually localhost, you probably want to change that to .*@example.com

Attachments

name default

help

attachment-maximum-file-name-length 200

Some legacy network provide ridiculously long filenames, strip above this limit, preserving suffix.

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 component JID.

upload-service None

JID of an HTTP upload service the gateway can use. This is optional, as it should be automatically determined via servicediscovery.

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