Configuration

Note

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

Note

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

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

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.

Common config

Slidge can be configured via CLI args, environment variables and/or INI files.

To use env vars, use this convention: --home-dir becomes HOME_DIR.

Everything in /etc/slidge/conf.d/* is automatically used. To use a plugin-specific INI file, put it in another dir, and launch slidge with -c /path/to/plugin-specific.conf. Use the long version of the CLI arg without the double dash prefix inside this INI file, eg debug=true.

An example configuration file is available at https://git.sr.ht/~nicoco/slidge/tree/master/item/dev/confs/slidge-example.ini

usage: slidge [-h] [-c CONFIG] [-q] [-d] [--version] --jid JID --legacy-module
              LEGACY_MODULE --secret SECRET [--admins [ADMINS ...]]
              [--always-invite-when-adding-bookmarks]
              [--attachment-maximum-file-name-length ATTACHMENT_MAXIMUM_FILE_NAME_LENGTH]
              [--avatar-resampling-threads AVATAR_RESAMPLING_THREADS]
              [--avatar-size AVATAR_SIZE]
              [--correction-empty-body-as-retraction] [--dev-mode]
              [--download-chunk-size DOWNLOAD_CHUNK_SIZE]
              [--fix-filename-suffix-mime-type] [--home-dir HOME_DIR]
              [--ignore-delay-threshold IGNORE_DELAY_THRESHOLD]
              [--last-message-correction-retraction-workaround]
              [--last-seen-fallback] [--log-file LOG_FILE]
              [--log-format LOG_FORMAT] [--mam-max-days MAM_MAX_DAYS]
              [--no-roster-push] [--no-upload-file-read-others]
              [--no-upload-method NO_UPLOAD_METHOD]
              [--no-upload-path NO_UPLOAD_PATH]
              [--no-upload-url-prefix NO_UPLOAD_URL_PREFIX]
              [--partial-registration-timeout PARTIAL_REGISTRATION_TIMEOUT]
              [--port PORT] [--qr-timeout QR_TIMEOUT]
              [--roster-push-presence-subscription-request-fallback]
              [--secret-key SECRET_KEY] [--server SERVER] [--sync-avatar]
              [--upload-requester UPLOAD_REQUESTER]
              [--upload-service UPLOAD_SERVICE]
              [--user-jid-validator USER_JID_VALIDATOR]
              [--use-attachment-original-urls]

Named Arguments

-c, --config

Path to a INI config file.

-q, --quiet

loglevel=WARNING

Default: 20

-d, --debug

loglevel=DEBUG

--version

show program’s version number and exit

--jid, -j

The gateway component’s JID

--legacy-module

Importable python module containing (at least) a BaseGateway and a LegacySession subclass

--secret

The gateway component’s secret (required to connect to the XMPP server)

--admins

JIDs of the gateway admins

Default: ()

--always-invite-when-adding-bookmarks

Send an invitation to join MUCs when adding them to the bookmarks. While this should not be necessary, it helps with clients that do not support XEP-0402 or that do not respect the auto-join flag.

Default: True

--attachment-maximum-file-name-length

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

Default: 200

--avatar-resampling-threads

Number of additional threads to use for avatar resampling. Even in a single-core context, this makes avatar resampling non-blocking.

Default: 2

--avatar-size

Maximum image size (width and height), image ratio will be preserved

Default: 200

--correction-empty-body-as-retraction

Treat last message correction to empty message as a retraction. (this is what cheogram do for retraction)

Default: True

--dev-mode

Enables an interactive python shell via chat commands, for admins.Not safe to use in prod, but great during dev.

Default: False

--download-chunk-size

Chunk size when slidge needs to download files using HTTP.

Default: 1024

--fix-filename-suffix-mime-type

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.

Default: False

--home-dir

Shelve file used to store persistent user data. Defaults to /var/lib/slidge/${SLIDGE_JID}.

--ignore-delay-threshold

Threshold, in seconds, below which the <delay> information is stripped out of emitted stanzas.

Default: 0:05:00

--last-message-correction-retraction-workaround

If the legacy service does not support last message correction but supports message retractions, slidge can ‘retract’ the edited message when you edit from an XMPP client, as a workaround. This may only work for editing messages once. If the legacy service does not support retractions and this is set to true, when XMPP clients attempt to correct, this will send a new message.

Default: False

--last-seen-fallback

When using XEP-0319 (Last User Interaction in Presence), use the presence status to display the last seen information in the presence status. Useful for clients that do not implement XEP-0319.

Default: True

--log-file

Log to a file instead of stdout/err

--log-format

Optionally, a format string for logging messages. Refer to https://docs.python.org/3/library/logging.html#logrecord-attributes for available options.

Default: “%(levelname)s:%(name)s:%(message)s”

--mam-max-days

Maximum number of days for group archive retention. Since all text content stored in RAM right now,

Default: 7

--no-roster-push

Do not fill users’ rosters with legacy contacts automatically

Default: False

--no-upload-file-read-others

After writing a file in NO_UPLOAD_PATH, change its permission so that ‘others’ can read it.

Default: False

--no-upload-method

Whether to ‘copy’, ‘move’, ‘hardlink’ or ‘symlink’ the files in no-upload-path.

Default: “copy”

--no-upload-path

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

Base URL that servers files in the dir set in the no-upload-path option, eg https://example.com:666/slidge-attachments/

--partial-registration-timeout

Timeout before registration and login. Only useful for legacy networks where a single step registration process is not enough.

Default: 3600

--port, -p

The XMPP server’s port for incoming component connections

Default: “5347”

--qr-timeout

Timeout for QR code flashing confirmation.

Default: 60

--roster-push-presence-subscription-request-fallback

If True, legacy contacts will send a presence request subscription when privileged roster push does not work, eg, if XEP-0356 (privileged entity) is not available for the component.

Default: True

--secret-key

Encryption for disk storage

--server, -s

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.

Default: “localhost”

--sync-avatar

Sync the user XMPP avatar to legacy network (if supported).

Default: True

--upload-requester

Set which JID should request the upload slots. Defaults to the component JID.

--upload-service

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

--user-jid-validator

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

--use-attachment-original-urls

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.

Default: False