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


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


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

usage: slidge [-h] [-c CONFIG] [-q] [-d] [--version] --jid JID --legacy-module
              LEGACY_MODULE --secret SECRET [--admins [ADMINS ...]]
              [--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-seen-fallback] [--log-file LOG_FILE]
              [--mam-max-days MAM_MAX_DAYS] [--no-roster-push]
              [--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]
              [--secret-key SECRET_KEY] [--server SERVER] [--sync-avatar]
              [--upload-requester UPLOAD_REQUESTER]
              [--upload-service UPLOAD_SERVICE]
              [--user-jid-validator USER_JID_VALIDATOR]

Named Arguments#

-c, --config

Path to a INI config file.

-q, --quiet


Default: 20

-d, --debug



show program’s version number and exit

--jid, -j

The gateway component’s JID


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


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


JIDs of the gateway admins

Default: ()


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


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

Default: 200


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

Default: 2


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

Default: 200


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

Default: True


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

Default: False


Chunk size when slidge needs to download files using HTTP.

Default: 1024


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


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


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

Default: 0:05:00


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


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 to a file instead of stdout/err


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

Default: 7


Do not fill users’ rosters with legacy contacts automatically

Default: False


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

Default: False


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

Default: “copy”


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.


Base URL that servers files in the dir set in the no-upload-path option, eg


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”


Timeout for QR code flashing confirmation.

Default: 60


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


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 the user XMPP avatar to legacy network (if supported).

Default: True


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


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


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


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