8.7 KiB
Configuring Conduit
Conduit can be configured via a config file (conventionally called Conduit.toml) or environment variables. If a config option is set in both the config file and as an environment variable, the environment variable takes precedence.
You absolutely need to set the environment variable CONDUIT_CONFIG_FILE to either point to a config file (
e.g. CONDUIT_CONFIG_FILE=/etc/conduit/Conduit.toml) or to an empty string (CONDUIT_CONFIG_FILE='') if you want to
configure Conduit with just environment variables.
Mandatory config options
Mandatory variables must be configured in order for Conduit to run properly.
Server Name
- Config file key:
server_name - Envirnoment variable:
CONDUIT_SERVER_NAME - Default value: None, you will need to choose your own.
The server_name is the name of this server. It is used as a suffix for user and room ids. Example: If you set it
to conduit.rs, your usernames will look like @somebody:conduit.rs.
The Conduit server needs to be reachable at https://your.server.name/ on port 443 (client-server) and 8448 ( server-server) OR you can create /.well-known files to redirect requests. See the Client-Server specs and the Server-Server specs for more information.
Database Path
- Config file key:
database_path - Envirnoment variable:
CONDUIT_DATABASE_PATH - Default value: None, but many people like to use
/var/lib/conduit/.
A directory where Conduit stores its database and media files. This directory must exist, have enough free space and be readable and writable by the user Conduit is running as.
What does enough free space mean? It heavily on the amount of messages your Conduit server will see and the amount and size of media files users on your Conduit server send. As a rule of thumb, you should have at least 10 GB of free space left. You should be comfortable for quite some time with 50 GB.
Port
- Config file key:
port - Environment variable:
CONDUIT_PORT - Default value: None, but many people like to use
6167.
The TCP port Conduit will listen on for connections. The port needs to be free (no other program is listeing on it).
Conduit does currently (2021-12) not offer HTTPS by itself. Only unencrypted HTTP requests will be accepted on this port. Unless you know what you are doing, this port should not be exposed to the internet. Instead, use a reverse proxy capable of doing TLS to offer your Conduit server to the internet via HTTPS.
Optional configuration options
These config options come with defaults and don't need to be configured for Conduit to run. That said, you should still check them to make sure that your Conduit server behaves like you want it to do.
Maximum request size
- Config file key:
max_request_size - Environment variable:
CONDUIT_MAX_REQUEST_SIZE - Default value:
20_000_000(~= 20 MB)
The maximum size in bytes for incoming requests to Conduit. You can use underscores to improve readability.
This will effectively limit the size for images, videos and other files users on your Conduit server can send.
Allow Registration?
- Config file key:
allow_registration - Environment variable:
CONDUIT_ALLOW_REGISTRATION - Default value:
true - Possible values:
true,false
It this is set to false, no new users can register accounts on your Conduit server. Already registered users will not
be affected from this setting and can continue to user your server.
The first user to ever register on your Conduit server will be considered the admin account and is automatically invited into the admin room.
Allow Encryption?
- Config file key:
allow_encryption - Environment variable:
CONDUIT_ALLOW_ENCRYPTION - Default value:
true - Possible values:
true,false
If this is set to false, Conduit disables the ability for users to create encrypted chats. Existing encrypted chats
may continue to work.
Allow federation?
- Config file key:
allow_federation - Environment variable:
CONDUIT_ALLOW_FEDERATION - Default value:
false - Possible values:
true,false
Federation means that users from different Matrix servers can chat with each other. E.g. @mathew:matrix.org can chat
with @timo:conduit.rs.
If this option is set to false, users on your Conduit server can only talk with other users on your Conduit server.
Federation with other servers needs to happen over HTTPS, so make sure you have set up a reverse proxy.
You can use the Federation Tester to test your federation ability.
Jaeger Tracing
- Config file key:
allow_jaeger - Environment variable:
CONDUIT_ALLOW_JAEGER - Default value:
false - Possible values:
true,false
Enable Jaeger to support monitoring and troubleshooting through Jaeger.
If you don't know what Jaeger is, you can safely leave this set to false.
Trusted servers
- Config file key:
trusted_servers - Environment variable:
CONDUIT_TRUSTED_SERVERS - Default value:
[] - Possible values: JSON-Array of server domains, e.g.
["matrix.org"]or["matrix.org", "conduit.rs"].
Matrix servers have so-called "server keys", which authenticate messages from their users. Because your Conduit server might not know the server keys from every server it encounters, it can ask a trusted server for them. This speeds things up for rooms with people from a lot of different servers.
You should only set this to include trustworthy servers. Most people consider ["matrix.org"] to bea good default.
Only relevant if you have federation enabled.
Limit amount of concurrent requests
- Config file key:
max_concurrent_requests - Environment variable:
CONDUIT_MAX_CONCURRENT_REQUESTS - Default value:
100 - Suggested values:
1-1000(u16)
How many requests Conduit can make at the same time. This affects federation with other Matrix servers, push notifications and app_services.
// TODO Timo: When does it make sense to change this?
Configure logging
- Config file key:
log - Environment variable:
CONDUIT_LOG - Default value:
info,state_res=warn,rocket=off,_=off,sled=off
Configures which kind of messages Conduit logs.
// TODO: Better and more thorough explanation
Worker threads
- Config file key:
workers - Environment variable:
CONDUIT_WORKERS - Default value: cpu core count * 2
- Possible values: // TODO
// TODO: Which thing exactly threads? What not?
Listening address
- Config file key:
address - Environment variable:
CONDUIT_ADDRESS - Default value:
127.0.0.1 - Possible values: Valid IP addresses.
Which IP address conduit is listening on. 127.0.0.1 means that Conduit can only be accessed from the same server or
through a reverse proxy on that server. If you want it to be accessible from any network interface (which you should
not, because other matrix servers should talk to your Conduit via a reverse proxy and not directly), you can set it
to 0.0.0.0.
Database cache capacity
- Config file key:
db_cache_capacity_mb - Environment variable:
CONDUIT_DB_CACHE_CAPACITY_MB - Default value:
200 - Possible values:
true,false
The total amount of memory (RAM) that the database cache will be able to use.
// TODO: this needs clearification: In RAM or on disk and for what exactly?
PDU cache capacity
- Config file key:
pdu_cache_capacity - Environment variable:
CONDUIT_PDU_CACHE_CAPACITY - Default value:
100_000 - Suggested values:
1_000-1_000_000(u32)
The total capacity (read: number of items) the pdu cache can hold in memory. Setting this to a lower number may slow Conduit down, as it must fetch more data from the database. Increasing it will mean that Conduit will start to use more memory as the cache slowly fills up.
SQLite WAL clean interval
- Config file key:
sqlite_wal_clean_second_interval - Environment variable:
CONDUIT_SQLITE_WAL_CLEAN_SECOND_INTERVAL - Default value:
60(every 60 seconds) - Suggested values:
1-3600(u32)
How often the WAL file should be cleaned up. The WAL file will be written to until cleaned up, after which it restarts writing from the beginning.
The file's size will correspond to how long it could write to it in one go. (e.g. if conduit writes 100MB of data to the database inbetween that period, the file will grow to 100MB). You can read more about that in the SQLite Docs.
Reducing this down too much can offset the benefits of using a WAL at all. However, having this too high can result in a large WAL file.
Only relevant when using SQLite as the database.
Still undocumented config options
tracing_flameproxyjwt_secret