Configuration

Config file location

By default, slidge-whatsapp 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

Optional dependencies

WhatsApp requires that image, audio, and video attachments are sent in specific formats; these formats are generaly incompatible with prevailing standards across XMPP clients.

Thus, sending attachments with full client compatibility requires that we convert these on-the-fly; this requires that FFmpeg is installed. If a valid FFmpeg installation is not found, attachments will still be sent in their original formats, which may cause these to appear as “document” attachments in official WhatsApp clients.

FFmpeg is widely used and packaged – please refer to your distribution’s documentation on how to install the FFmpeg package.

slidge-whatsapp-specific config

slidge-whatsapp provides the component-wide options displayed in the table below. They can be used:

• as key=value in a config file;

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

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

name	default	help
add-group-participants-to-roster	True	Whether or not group participants will be added to the XMPP roster
always-sync-roster	False	Whether or not to perform a full sync of the WhatsApp roster on startup
db-params	?_foreign_keys=true	Additional parameters to pass to database connection string
db-path	None	The path to the database used for the WhatsApp plugin. Default to ${SLIDGE_HOME_DIR}/whatsapp/whatsapp.db
enable-link-previews	True	Whether or not previews for links (URLs) should be generated on outgoing messages

Generic slidge config

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:

• as key=value in a config file;

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

Note

The following options are for slidge version 0.3.3. Depending on how you installed slidge-whatsapp, you might have a different version of slidge. Use slidge-whatsapp --help for the exact list of options you can use.

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

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.