From 08365bf5f440a4c9f086142c23044f1884c68033 Mon Sep 17 00:00:00 2001 From: strawberry Date: Sun, 10 Nov 2024 20:16:38 -0500 Subject: [PATCH] update config documentation, commit generated example config also removes the no-op/useless "database_backend" config option Signed-off-by: strawberry --- conduwuit-example.toml | 1923 +++++++++++++++++++++------------- src/api/server/make_knock.rs | 107 ++ src/api/server/send_knock.rs | 190 ++++ src/core/config/mod.rs | 573 ++++++---- src/service/migrations.rs | 11 +- 5 files changed, 1846 insertions(+), 958 deletions(-) create mode 100644 src/api/server/make_knock.rs create mode 100644 src/api/server/send_knock.rs diff --git a/conduwuit-example.toml b/conduwuit-example.toml index 11735616..aa0d1e5d 100644 --- a/conduwuit-example.toml +++ b/conduwuit-example.toml @@ -1,605 +1,867 @@ -# ============================================================================= -# This is the official example config for conduwuit. -# If you use it for your server, you will need to adjust it to your own needs. -# At the very least, change the server_name field! -# -# This documentation can also be found at https://conduwuit.puppyirl.gay/configuration.html -# ============================================================================= +### conduwuit Configuration +### +### THIS FILE IS GENERATED. CHANGES/CONTRIBUTIONS IN THE REPO WILL +### BE OVERWRITTEN! +### +### You should rename this file before configuring your server. Changes +### to documentation and defaults can be contributed in source code at +### src/core/config/mod.rs. This file is generated when building. +### +### Any values pre-populated are the default values for said config option. +### +### At the minimum, you MUST edit all the config options to your environment +### that say "YOU NEED TO EDIT THIS". +### See https://conduwuit.puppyirl.gay/configuration.html for ways to +### configure conduwuit [global] -# The server_name is the pretty name of this server. It is used as a suffix for user -# and room ids. Examples: matrix.org, conduit.rs - -# The Conduit server needs all /_matrix/ requests to be reachable at -# https://your.server.name/ on port 443 (client-server) and 8448 (federation). - -# If that's not possible for you, you can create /.well-known files to redirect -# requests (delegation). See -# https://spec.matrix.org/latest/client-server-api/#getwell-knownmatrixclient -# and -# https://spec.matrix.org/v1.9/server-server-api/#getwell-knownmatrixserver -# for more information - -# YOU NEED TO EDIT THIS -#server_name = "your.server.name" - -# Servers listed here will be used to gather public keys of other servers (notary trusted key servers). +# The server_name is the pretty name of this server. It is used as a +# suffix for user and room IDs/aliases. # -# The default behaviour for conduwuit is to attempt to query trusted key servers before querying the individual servers. -# This is done for performance reasons, but if you would like to query individual servers before the notary servers -# configured below, set to +# See the docs for reverse proxying and delegation: https://conduwuit.puppyirl.gay/deploying/generic.html#setting-up-the-reverse-proxy +# Also see the `[global.well_known]` config section at the very bottom. # -# (Currently, conduwuit doesn't support batched key requests, so this list should only contain Synapse servers) -# Defaults to `matrix.org` -# trusted_servers = ["matrix.org"] - -# Sentry.io crash/panic reporting, performance monitoring/metrics, etc. This is NOT enabled by default. -# conduwuit's default Sentry reporting endpoint is o4506996327251968.ingest.us.sentry.io +# Examples of delegation: +# - https://puppygock.gay/.well-known/matrix/server +# - https://puppygock.gay/.well-known/matrix/client # -# Defaults to *false* -#sentry = false - -# Sentry reporting URL if a custom one is desired +# YOU NEED TO EDIT THIS. THIS CANNOT BE CHANGED AFTER WITHOUT A DATABASE +# WIPE. # -# Defaults to conduwuit's default Sentry endpoint: "https://fe2eb4536aa04949e28eff3128d64757@o4506996327251968.ingest.us.sentry.io/4506996334657536" -#sentry_endpoint = "" - -# Report your Conduwuit server_name in Sentry.io crash reports and metrics +# example: "conduwuit.woof" # -# Defaults to false -#sentry_send_server_name = false +#server_name = -# Performance monitoring/tracing sample rate for Sentry.io +# default address (IPv4 or IPv6) conduwuit will listen on. # -# Note that too high values may impact performance, and can be disabled by setting it to 0.0 (0%) -# This value is read as a percentage to Sentry, represented as a decimal +# If you are using Docker or a container NAT networking setup, this must +# be "0.0.0.0". # -# Defaults to 15% of traces (0.15) -#sentry_traces_sample_rate = 0.15 +# To listen on multiple addresses, specify a vector e.g. ["127.0.0.1", +# "::1"] +# +#address = ["127.0.0.1", "::1"] -# Whether to attach a stacktrace to Sentry reports. -#sentry_attach_stacktrace = false - -# Send panics to sentry. This is true by default, but sentry has to be enabled. -#sentry_send_panic = true - -# Send errors to sentry. This is true by default, but sentry has to be enabled. This option is -# only effective in release-mode; forced to false in debug-mode. -#sentry_send_error = true - -# Controls the tracing log level for Sentry to send things like breadcrumbs and transactions -# Defaults to "info" -#sentry_filter = "info" - - -### Database configuration - -# This is the only directory where conduwuit will save its data, including media. -# Note: this was previously "/var/lib/matrix-conduit" -database_path = "/var/lib/conduwuit" - -# Database backend: Only rocksdb is supported. -database_backend = "rocksdb" - - -### Network - -# The port(s) conduwuit will be running on. You need to set up a reverse proxy such as -# Caddy or Nginx so all requests to /_matrix on port 443 and 8448 will be -# forwarded to the conduwuit instance running on this port -# Docker users: Don't change this, you'll need to map an external port to this. +# The port(s) conduwuit will be running on. +# +# See https://conduwuit.puppyirl.gay/deploying/generic.html#setting-up-the-reverse-proxy for reverse proxying. +# +# Docker users: Don't change this, you'll need to map an external port to +# this. +# # To listen on multiple ports, specify a vector e.g. [8080, 8448] # -# default if unspecified is 8008 -port = 6167 +#port = 8008 -# default address (IPv4 or IPv6) conduwuit will listen on. Generally you want this to be -# localhost (127.0.0.1 / ::1). If you are using Docker or a container NAT networking setup, you -# likely need this to be 0.0.0.0. -# To listen multiple addresses, specify a vector e.g. ["127.0.0.1", "::1"] +# Uncomment unix_socket_path to listen on a UNIX socket at the specified +# path. If listening on a UNIX socket, you MUST remove/comment the +# 'address' key if definedm AND add your reverse proxy to the 'conduwuit' +# group, unless world RW permissions are specified with unix_socket_perms +# (666 minimum). # -# default if unspecified is both IPv4 and IPv6 localhost: ["127.0.0.1", "::1"] -address = "127.0.0.1" +# example: "/run/conduwuit/conduwuit.sock" +# +#unix_socket_path = -# Max request size for file uploads -max_request_size = 20_000_000 # in bytes - -# Uncomment unix_socket_path to listen on a UNIX socket at the specified path. -# If listening on a UNIX socket, you must remove/comment the 'address' key if defined and add your -# reverse proxy to the 'conduwuit' group, unless world RW permissions are specified with unix_socket_perms (666 minimum). -#unix_socket_path = "/run/conduwuit/conduwuit.sock" +# The default permissions (in octal) to create the UNIX socket with. +# #unix_socket_perms = 660 -# Set this to true for conduwuit to compress HTTP response bodies using zstd. -# This option does nothing if conduwuit was not built with `zstd_compression` feature. -# Please be aware that enabling HTTP compression may weaken TLS. -# Most users should not need to enable this. -# See https://breachattack.com/ and https://wikipedia.org/wiki/BREACH before deciding to enable this. -zstd_compression = false - -# Set this to true for conduwuit to compress HTTP response bodies using gzip. -# This option does nothing if conduwuit was not built with `gzip_compression` feature. -# Please be aware that enabling HTTP compression may weaken TLS. -# Most users should not need to enable this. -# See https://breachattack.com/ and https://wikipedia.org/wiki/BREACH before deciding to enable this. -gzip_compression = false - -# Set this to true for conduwuit to compress HTTP response bodies using brotli. -# This option does nothing if conduwuit was not built with `brotli_compression` feature. -# Please be aware that enabling HTTP compression may weaken TLS. -# Most users should not need to enable this. -# See https://breachattack.com/ and https://wikipedia.org/wiki/BREACH before deciding to enable this. -brotli_compression = false - -# Vector list of IPv4 and IPv6 CIDR ranges / subnets *in quotes* that you do not want conduwuit to send outbound requests to. -# Defaults to RFC1918, unroutable, loopback, multicast, and testnet addresses for security. +# This is the only directory where conduwuit will save its data, including +# media. +# Note: this was previously "/var/lib/matrix-conduit" # -# To disable, set this to be an empty vector (`[]`). -# Please be aware that this is *not* a guarantee. You should be using a firewall with zones as doing this on the application layer may have bypasses. +# YOU NEED TO EDIT THIS. # -# Currently this does not account for proxies in use like Synapse does. -ip_range_denylist = [ - "127.0.0.0/8", - "10.0.0.0/8", - "172.16.0.0/12", - "192.168.0.0/16", - "100.64.0.0/10", - "192.0.0.0/24", - "169.254.0.0/16", - "192.88.99.0/24", - "198.18.0.0/15", - "192.0.2.0/24", - "198.51.100.0/24", - "203.0.113.0/24", - "224.0.0.0/4", - "::1/128", - "fe80::/10", - "fc00::/7", - "2001:db8::/32", - "ff00::/8", - "fec0::/10", -] - - -### Moderation / Privacy / Security - -# Config option to control whether the legacy unauthenticated Matrix media repository endpoints will be enabled. -# These endpoints consist of: -# - /_matrix/media/*/config -# - /_matrix/media/*/upload -# - /_matrix/media/*/preview_url -# - /_matrix/media/*/download/* -# - /_matrix/media/*/thumbnail/* +# example: "/var/lib/conduwuit" # -# The authenticated equivalent endpoints are always enabled. +#database_path = + +# conduwuit supports online database backups using RocksDB's Backup engine +# API. To use this, set a database backup path that conduwuit can write +# to. # -# Defaults to true for now, but this is highly subject to change, likely in the next release. -#allow_legacy_media = true +# See https://conduwuit.puppyirl.gay/maintenance.html#backups for more information. +# +# example: "/opt/conduwuit-db-backups" +# +#database_backup_path = -# Set to true to allow user type "guest" registrations. Element attempts to register guest users automatically. -# Defaults to false -allow_guest_registration = false +# The amount of online RocksDB database backups to keep/retain, if using +# "database_backup_path", before deleting the oldest one. +# +#database_backups_to_keep = 1 -# Set to true to log guest registrations in the admin room. -# Defaults to false as it may be noisy or unnecessary. -log_guest_registrations = false +# Set this to any float value in megabytes for conduwuit to tell the +# database engine that this much memory is available for database-related +# caches. +# +# May be useful if you have significant memory to spare to increase +# performance. +# +# Similar to the individual LRU caches, this is scaled up with your CPU +# core count. +# +# This defaults to 128.0 + (64.0 * CPU core count) +# +#db_cache_capacity_mb = -# Set to true to allow guest registrations/users to auto join any rooms specified in `auto_join_rooms` -# Defaults to false -allow_guests_auto_join_rooms = false +# Option to control adding arbitrary text to the end of the user's +# displayname upon registration with a space before the text. This was the +# lightning bolt emoji option, just replaced with support for adding your +# own custom text or emojis. To disable, set this to "" (an empty string). +# +# The default is the trans pride flag. +# +# example: "🏳️⚧️" +# +#new_user_displayname_suffix = "🏳️⚧️" -# Vector list of servers that conduwuit will refuse to download remote media from. -# No default. -# prevent_media_downloads_from = ["example.com", "example.local"] +# If enabled, conduwuit will send a simple GET request periodically to +# `https://pupbrain.dev/check-for-updates/stable` for any new +# announcements made. Despite the name, this is not an update check +# endpoint, it is simply an announcement check endpoint. +# +# This is disabled by default as this is rarely used except for security +# updates or major updates. +# +#allow_check_for_updates = false + +# Set this to any float value to multiply conduwuit's in-memory LRU caches +# with such as "auth_chain_cache_capacity". +# +# May be useful if you have significant memory to spare to increase +# performance. This was previously called +# `conduit_cache_capacity_modifier`. +# +# If you have low memory, reducing this may be viable. +# +# By default, the individual caches such as "auth_chain_cache_capacity" +# are scaled by your CPU core count. +# +#cache_capacity_modifier = 1.0 + +# This item is undocumented. Please contribute documentation for it. +# +#pdu_cache_capacity = varies by system + +# This item is undocumented. Please contribute documentation for it. +# +#auth_chain_cache_capacity = varies by system + +# This item is undocumented. Please contribute documentation for it. +# +#shorteventid_cache_capacity = varies by system + +# This item is undocumented. Please contribute documentation for it. +# +#eventidshort_cache_capacity = varies by system + +# This item is undocumented. Please contribute documentation for it. +# +#shortstatekey_cache_capacity = varies by system + +# This item is undocumented. Please contribute documentation for it. +# +#statekeyshort_cache_capacity = varies by system + +# This item is undocumented. Please contribute documentation for it. +# +#server_visibility_cache_capacity = varies by system + +# This item is undocumented. Please contribute documentation for it. +# +#user_visibility_cache_capacity = varies by system + +# This item is undocumented. Please contribute documentation for it. +# +#stateinfo_cache_capacity = varies by system + +# This item is undocumented. Please contribute documentation for it. +# +#roomid_spacehierarchy_cache_capacity = varies by system + +# Maximum entries stored in DNS memory-cache. The size of an entry may +# vary so please take care if raising this value excessively. Only +# decrease this when using an external DNS cache. Please note +# that systemd-resolved does *not* count as an external cache, even when +# configured to do so. +# +#dns_cache_entries = 32768 + +# Minimum time-to-live in seconds for entries in the DNS cache. The +# default may appear high to most administrators; this is by design as the +# majority of NXDOMAINs are correct for a long time (e.g. the server is no +# longer running Matrix). Only decrease this if you are using an external +# DNS cache. +# +# default_dns_min_ttl: 259200 +# +#dns_min_ttl = + +# Minimum time-to-live in seconds for NXDOMAIN entries in the DNS cache. +# This value is critical for the server to federate efficiently. +# NXDOMAIN's are assumed to not be returning to the federation +# and aggressively cached rather than constantly rechecked. +# +# Defaults to 3 days as these are *very rarely* false negatives. +# +#dns_min_ttl_nxdomain = 259200 + +# Number of retries after a timeout. +# +#dns_attempts = 10 + +# The number of seconds to wait for a reply to a DNS query. Please note +# that recursive queries can take up to several seconds for some domains, +# so this value should not be too low, especially on slower hardware or +# resolvers. +# +#dns_timeout = 10 + +# Fallback to TCP on DNS errors. Set this to false if unsupported by +# nameserver. +# +#dns_tcp_fallback = true + +# Enable to query all nameservers until the domain is found. Referred to +# as "trust_negative_responses" in hickory_resolver. This can avoid +# useless DNS queries if the first nameserver responds with NXDOMAIN or +# an empty NOERROR response. +# +#query_all_nameservers = true + +# Enables using *only* TCP for querying your specified nameservers instead +# of UDP. +# +# If you are running conduwuit in a container environment, this config option may need to be enabled. See https://conduwuit.puppyirl.gay/troubleshooting.html#potential-dns-issues-when-using-docker for more details. +# +#query_over_tcp_only = false + +# DNS A/AAAA record lookup strategy +# +# Takes a number of one of the following options: +# 1 - Ipv4Only (Only query for A records, no AAAA/IPv6) +# +# 2 - Ipv6Only (Only query for AAAA records, no A/IPv4) +# +# 3 - Ipv4AndIpv6 (Query for A and AAAA records in parallel, uses whatever +# returns a successful response first) +# +# 4 - Ipv6thenIpv4 (Query for AAAA record, if that fails then query the A +# record) +# +# 5 - Ipv4thenIpv6 (Query for A record, if that fails then query the AAAA +# record) +# +# If you don't have IPv6 networking, then for better DNS performance it +# may be suitable to set this to Ipv4Only (1) as you will never ever use +# the AAAA record contents even if the AAAA record is successful instead +# of the A record. +# +#ip_lookup_strategy = 5 + +# Max request size for file uploads in bytes. Defaults to 20MB. +# +#max_request_size = 20971520 + +# This item is undocumented. Please contribute documentation for it. +# +#max_fetch_prev_events = 192 + +# Default/base connection timeout (seconds). This is used only by URL +# previews and update/news endpoint checks. +# +#request_conn_timeout = 10 + +# Default/base request timeout (seconds). The time waiting to receive more +# data from another server. This is used only by URL previews, +# update/news, and misc endpoint checks. +# +#request_timeout = 35 + +# Default/base request total timeout (seconds). The time limit for a whole +# request. This is set very high to not cancel healthy requests while +# serving as a backstop. This is used only by URL previews and +# update/news endpoint checks. +# +#request_total_timeout = 320 + +# Default/base idle connection pool timeout (seconds). This is used only +# by URL previews and update/news endpoint checks. +# +#request_idle_timeout = 5 + +# Default/base max idle connections per host. This is used only by URL +# previews and update/news endpoint checks. Defaults to 1 as generally the +# same open connection can be re-used. +# +#request_idle_per_host = 1 + +# Federation well-known resolution connection timeout (seconds) +# +#well_known_conn_timeout = 6 + +# Federation HTTP well-known resolution request timeout (seconds) +# +#well_known_timeout = 10 + +# Federation client request timeout (seconds). You most definitely want +# this to be high to account for extremely large room joins, slow +# homeservers, your own resources etc. +# +#federation_timeout = 300 + +# Federation client idle connection pool timeout (seconds) +# +#federation_idle_timeout = 25 + +# Federation client max idle connections per host. Defaults to 1 as +# generally the same open connection can be re-used +# +#federation_idle_per_host = 1 + +# Federation sender request timeout (seconds). The time it takes for the +# remote server to process sent transactions can take a while. +# +#sender_timeout = 180 + +# Federation sender idle connection pool timeout (seconds) +# +#sender_idle_timeout = 180 + +# Federation sender transaction retry backoff limit (seconds) +# +#sender_retry_backoff_limit = 86400 + +# Appservice URL request connection timeout. Defaults to 35 seconds as +# generally appservices are hosted within the same network. +# +#appservice_timeout = 35 + +# Appservice URL idle connection pool timeout (seconds) +# +#appservice_idle_timeout = 300 + +# Notification gateway pusher idle connection pool timeout +# +#pusher_idle_timeout = 15 # Enables registration. If set to false, no users can register on this # server. # -# If set to true without a token configured, users can register with no form of 2nd- -# step only if you set +# If set to true without a token configured, users can register with no +# form of 2nd-step only if you set # `yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse` to # true in your config. # # If you would like registration only via token reg, please configure # `registration_token` or `registration_token_file`. -allow_registration = false -# Please note that an open registration homeserver with no second-step verification -# is highly prone to abuse and potential defederation by homeservers, including -# matrix.org. +# +#allow_registration = false -# A static registration token that new users will have to provide when creating -# an account. If unset and `allow_registration` is true, registration is open -# without any condition. YOU NEED TO EDIT THIS. -registration_token = "change this token/string here or set registration_token_file" +# This item is undocumented. Please contribute documentation for it. +# +#yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse = false -# Path to a file on the system that gets read for the registration token +# A static registration token that new users will have to provide when +# creating an account. If unset and `allow_registration` is true, +# registration is open without any condition. +# +# YOU NEED TO EDIT THIS OR USE registration_token_file. +# +# example: "o&^uCtes4HPf0Vu@F20jQeeWE7" +# +#registration_token = + +# Path to a file on the system that gets read for the registration token. +# this config option takes precedence/priority over "registration_token". # # conduwuit must be able to access the file, and it must not be empty # -# no default -#registration_token_file = "/etc/conduwuit/.reg_token" - -# controls whether federation is allowed or not -# defaults to true -# allow_federation = true - -# controls whether users are allowed to create rooms. -# appservices and admins are always allowed to create rooms -# defaults to true -# allow_room_creation = true - -# controls whether non-admin local users are forbidden from sending room invites (local and remote), -# and if non-admin users can receive remote room invites. admins are always allowed to send and receive all room invites. -# defaults to false -# block_non_admin_invites = false - -# List of forbidden username patterns/strings. Values in this list are matched as *contains*. -# This is checked upon username availability check, registration, and startup as warnings if any local users in your database -# have a forbidden username. -# No default. -# forbidden_usernames = [] - -# List of forbidden room aliases and room IDs as patterns/strings. Values in this list are matched as *contains*. -# This is checked upon room alias creation, custom room ID creation if used, and startup as warnings if any room aliases -# in your database have a forbidden room alias/ID. -# No default. -# forbidden_alias_names = [] - -# List of forbidden server names that we will block incoming AND outgoing federation with, and block client room joins / remote user invites. +# example: "/etc/conduwuit/.reg_token" # -# This check is applied on the room ID, room alias, sender server name, sender user's server name, inbound federation X-Matrix origin, and outbound federation handler. +#registration_token_file = + +# Controls whether encrypted rooms and events are allowed. # -# Basically "global" ACLs. No default. -# forbidden_remote_server_names = [] +#allow_encryption = true -# List of forbidden server names that we will block all outgoing federated room directory requests for. Useful for preventing our users from wandering into bad servers or spaces. -# No default. -# forbidden_remote_room_directory_server_names = [] - -# Set this to true to allow your server's public room directory to be federated. -# Set this to false to protect against /publicRooms spiders, but will forbid external users -# from viewing your server's public room directory. If federation is disabled entirely -# (`allow_federation`), this is inherently false. -allow_public_room_directory_over_federation = false - -# Set this to true to allow your server's public room directory to be queried without client -# authentication (access token) through the Client APIs. Set this to false to protect against /publicRooms spiders. -allow_public_room_directory_without_auth = false - -# Set this to true to lock down your server's public room directory and only allow admins to publish rooms to the room directory. -# Unpublishing is still allowed by all users with this enabled. +# Controls whether federation is allowed or not. It is not recommended to +# disable this after the fact due to potential federation breakage. # -# Defaults to false -lockdown_public_room_directory = false +#allow_federation = true -# Set this to true to allow federating device display names / allow external users to see your device display name. -# If federation is disabled entirely (`allow_federation`), this is inherently false. For privacy, this is best disabled. -allow_device_name_federation = false +# This item is undocumented. Please contribute documentation for it. +# +#federation_loopback = false -# Vector list of domains allowed to send requests to for URL previews. Defaults to none. -# Note: this is a *contains* match, not an explicit match. Putting "google.com" will match "https://google.com" and "http://mymaliciousdomainexamplegoogle.com" -# Setting this to "*" will allow all URL previews. Please note that this opens up significant attack surface to your server, you are expected to be aware of the risks by doing so. -url_preview_domain_contains_allowlist = [] +# Set this to true to require authentication on the normally +# unauthenticated profile retrieval endpoints (GET) +# "/_matrix/client/v3/profile/{userId}". +# +# This can prevent profile scraping. +# +#require_auth_for_profile_requests = false -# Vector list of explicit domains allowed to send requests to for URL previews. Defaults to none. -# Note: This is an *explicit* match, not a contains match. Putting "google.com" will match "https://google.com", "http://google.com", but not "https://mymaliciousdomainexamplegoogle.com" -# Setting this to "*" will allow all URL previews. Please note that this opens up significant attack surface to your server, you are expected to be aware of the risks by doing so. -url_preview_domain_explicit_allowlist = [] +# Set this to true to allow your server's public room directory to be +# federated. Set this to false to protect against /publicRooms spiders, +# but will forbid external users from viewing your server's public room +# directory. If federation is disabled entirely (`allow_federation`), +# this is inherently false. +# +#allow_public_room_directory_over_federation = false -# Vector list of URLs allowed to send requests to for URL previews. Defaults to none. -# Note that this is a *contains* match, not an explicit match. Putting "google.com" will match "https://google.com/", "https://google.com/url?q=https://mymaliciousdomainexample.com", and "https://mymaliciousdomainexample.com/hi/google.com" -# Setting this to "*" will allow all URL previews. Please note that this opens up significant attack surface to your server, you are expected to be aware of the risks by doing so. -url_preview_url_contains_allowlist = [] +# Set this to true to allow your server's public room directory to be +# queried without client authentication (access token) through the Client +# APIs. Set this to false to protect against /publicRooms spiders. +# +#allow_public_room_directory_without_auth = false -# Vector list of explicit domains not allowed to send requests to for URL previews. Defaults to none. -# Note: This is an *explicit* match, not a contains match. Putting "google.com" will match "https://google.com", "http://google.com", but not "https://mymaliciousdomainexamplegoogle.com" -# The denylist is checked first before allowlist. Setting this to "*" will not do anything. -url_preview_domain_explicit_denylist = [] +# allow guests/unauthenticated users to access TURN credentials +# +# this is the equivalent of Synapse's `turn_allow_guests` config option. +# this allows any unauthenticated user to call the endpoint +# `/_matrix/client/v3/voip/turnServer`. +# +# It is unlikely you need to enable this as all major clients support +# authentication for this endpoint and prevents misuse of your TURN server +# from potential bots. +# +#turn_allow_guests = false -# Maximum amount of bytes allowed in a URL preview body size when spidering. Defaults to 384KB (384_000 bytes) -url_preview_max_spider_size = 384_000 +# Set this to true to lock down your server's public room directory and +# only allow admins to publish rooms to the room directory. Unpublishing +# is still allowed by all users with this enabled. +# +#lockdown_public_room_directory = false -# Option to decide whether you would like to run the domain allowlist checks (contains and explicit) on the root domain or not. Does not apply to URL contains allowlist. Defaults to false. -# Example: If this is enabled and you have "wikipedia.org" allowed in the explicit and/or contains domain allowlist, it will allow all subdomains under "wikipedia.org" such as "en.m.wikipedia.org" as the root domain is checked and matched. -# Useful if the domain contains allowlist is still too broad for you but you still want to allow all the subdomains under a root domain. -url_preview_check_root_domain = false +# Set this to true to allow federating device display names / allow +# external users to see your device display name. If federation is +# disabled entirely (`allow_federation`), this is inherently false. For +# privacy reasons, this is best left disabled. +# +#allow_device_name_federation = false -# Config option to allow or disallow incoming federation requests that obtain the profiles -# of our local users from `/_matrix/federation/v1/query/profile` +# Config option to allow or disallow incoming federation requests that +# obtain the profiles of our local users from +# `/_matrix/federation/v1/query/profile` +# +# Increases privacy of your local user's such as display names, but some +# remote users may get a false "this user does not exist" error when they +# try to invite you to a DM or room. Also can protect against profile +# spiders. # # This is inherently false if `allow_federation` is disabled # -# Defaults to true -allow_profile_lookup_federation_requests = true +#allow_inbound_profile_lookup_federation_requests = true -# Config option to automatically deactivate the account of any user who attempts to join a: -# - banned room -# - forbidden room alias -# - room alias or ID with a forbidden server name +# controls whether standard users are allowed to create rooms. appservices +# and admins are always allowed to create rooms # -# This may be useful if all your banned lists consist of toxic rooms or servers that no good faith user would ever attempt to join, and -# to automatically remediate the problem without any admin user intervention. -# -# This will also make the user leave all rooms. Federation (e.g. remote room invites) are ignored here. -# -# Defaults to false as rooms can be banned for non-moderation-related reasons -#auto_deactivate_banned_room_attempts = false +#allow_room_creation = true - -### Admin Room and Console - -# Controls whether the conduwuit admin room console / CLI will immediately activate on startup. -# This option can also be enabled with `--console` conduwuit argument +# Set to false to disable users from joining or creating room versions +# that aren't 100% officially supported by conduwuit. # -# Defaults to false -#admin_console_automatic = false +# conduwuit officially supports room versions 6 - 11. +# +# conduwuit has slightly experimental (though works fine in practice) +# support for versions 3 - 5 +# +#allow_unstable_room_versions = true -# Controls what admin commands will be executed on startup. This is a vector list of strings of admin commands to run. +# default room version conduwuit will create rooms with. # -# An example of this can be: `admin_execute = ["debug ping puppygock.gay", "debug echo hi"]` +# per spec, room version 10 is the default. # -# This option can also be configured with the `--execute` conduwuit argument and can take standard shell commands and environment variables -# -# Such example could be: `./conduwuit --execute "server admin-notice conduwuit has started up at $(date)"` -# -# Defaults to nothing. -#admin_execute = [""] +#default_room_version = 10 -# Controls whether conduwuit should error and fail to start if an admin execute command (`--execute` / `admin_execute`) fails +# This item is undocumented. Please contribute documentation for it. # -# Defaults to false -#admin_execute_errors_ignore = false +#allow_jaeger = false -# Controls the max log level for admin command log captures (logs generated from running admin commands) +# This item is undocumented. Please contribute documentation for it. # -# Defaults to "info" on release builds, else "debug" on debug builds -#admin_log_capture = "info" +#jaeger_filter = "info" -# Allows admins to enter commands in rooms other than #admins by prefixing with \!admin. The reply -# will be publicly visible to the room, originating from the sender. -# defaults to true -#admin_escape_commands = true - -# Controls whether admin room notices like account registrations, password changes, account deactivations, -# room directory publications, etc will be sent to the admin room. +# If the 'perf_measurements' compile-time feature is enabled, enables +# collecting folded stack trace profile of tracing spans using +# tracing_flame. The resulting profile can be visualized with inferno[1], +# speedscope[2], or a number of other tools. # -# Update notices and normal admin command responses will still be sent. +# [1]: https://github.com/jonhoo/inferno +# [2]: www.speedscope.app # -# defaults to true -#admin_room_notices = true +#tracing_flame = false +# This item is undocumented. Please contribute documentation for it. +# +#tracing_flame_filter = "info" -### Misc +# This item is undocumented. Please contribute documentation for it. +# +#tracing_flame_output_path = "./tracing.folded" + +# Examples: +# - No proxy (default): +# proxy ="none" +# +# - For global proxy, create the section at the bottom of this file: +# [global.proxy] +# global = { url = "socks5h://localhost:9050" } +# +# - To proxy some domains: +# [global.proxy] +# [[global.proxy.by_domain]] +# url = "socks5h://localhost:9050" +# include = ["*.onion", "matrix.myspecial.onion"] +# exclude = ["*.myspecial.onion"] +# +# Include vs. Exclude: +# - If include is an empty list, it is assumed to be `["*"]`. +# - If a domain matches both the exclude and include list, the proxy will +# only be used if it was included because of a more specific rule than +# it was excluded. In the above example, the proxy would be used for +# `ordinary.onion`, `matrix.myspecial.onion`, but not +# `hello.myspecial.onion`. +# +#proxy = "none" + +# This item is undocumented. Please contribute documentation for it. +# +#jwt_secret = + +# Servers listed here will be used to gather public keys of other servers +# (notary trusted key servers). +# +# Currently, conduwuit doesn't support inbound batched key requests, so +# this list should only contain other Synapse servers +# +# example: ["matrix.org", "constellatory.net", "tchncs.de"] +# +#trusted_servers = ["matrix.org"] + +# Whether to query the servers listed in trusted_servers first or query +# the origin server first. For best security, querying the origin server +# first is advised to minimize the exposure to a compromised trusted +# server. For maximum federation/join performance this can be set to true, +# however other options exist to query trusted servers first under +# specific high-load circumstances and should be evaluated before setting +# this to true. +# +#query_trusted_key_servers_first = false + +# Whether to query the servers listed in trusted_servers first +# specifically on room joins. This option limits the exposure to a +# compromised trusted server to room joins only. The join operation +# requires gathering keys from many origin servers which can cause +# significant delays. Therefor this defaults to true to mitigate +# unexpected delays out-of-the-box. The security-paranoid or those +# willing to tolerate delays are advised to set this to false. Note that +# setting query_trusted_key_servers_first to true causes this option to +# be ignored. +# +#query_trusted_key_servers_first_on_join = true + +# Only query trusted servers for keys and never the origin server. This is +# intended for clusters or custom deployments using their trusted_servers +# as forwarding-agents to cache and deduplicate requests. Notary servers +# do not act as forwarding-agents by default, therefor do not enable this +# unless you know exactly what you are doing. +# +#only_query_trusted_key_servers = false + +# Maximum number of keys to request in each trusted server batch query. +# +#trusted_server_batch_size = 1024 # max log level for conduwuit. allows debug, info, warn, or error # see also: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives -# **Caveat**: -# For release builds, the tracing crate is configured to only implement levels higher than error to avoid unnecessary overhead in the compiled binary from trace macros. -# For debug builds, this restriction is not applied. # -# Defaults to "info" +# **Caveat**: +# For release builds, the tracing crate is configured to only implement +# levels higher than error to avoid unnecessary overhead in the compiled +# binary from trace macros. For debug builds, this restriction is not +# applied. +# #log = "info" # controls whether logs will be outputted with ANSI colours # -# defaults to true #log_colors = true -# controls whether encrypted rooms and events are allowed (default true) -#allow_encryption = false - -# if enabled, conduwuit will send a simple GET request periodically to `https://pupbrain.dev/check-for-updates/stable` -# for any new announcements made. Despite the name, this is not an update check -# endpoint, it is simply an announcement check endpoint. -# Defaults to false. -#allow_check_for_updates = false - -# Set to false to disable users from joining or creating room versions that aren't 100% officially supported by conduwuit. -# conduwuit officially supports room versions 6 - 10. conduwuit has experimental/unstable support for 3 - 5, and 11. -# Defaults to true. -#allow_unstable_room_versions = true - -# Option to control adding arbitrary text to the end of the user's displayname upon registration with a space before the text. -# This was the lightning bolt emoji option, just replaced with support for adding your own custom text or emojis. -# To disable, set this to "" (an empty string) -# Defaults to "🏳️‍⚧️" (trans pride flag) -#new_user_displayname_suffix = "🏳️‍⚧️" - -# Option to control whether conduwuit will query your list of trusted notary key servers (`trusted_servers`) for -# remote homeserver signing keys it doesn't know *first*, or query the individual servers first before falling back to the trusted -# key servers. -# -# The former/default behaviour makes federated/remote rooms joins generally faster because we're querying a single (or list of) server -# that we know works, is reasonably fast, and is reliable for just about all the homeserver signing keys in the room. Querying individual -# servers may take longer depending on the general infrastructure of everyone in there, how many dead servers there are, etc. -# -# However, this does create an increased reliance on one single or multiple large entities as `trusted_servers` should generally -# contain long-term and large servers who know a very large number of homeservers. -# -# If you don't know what any of this means, leave this and `trusted_servers` alone to their defaults. -# -# Defaults to true as this is the fastest option for federation. -#query_trusted_key_servers_first = true - -# List/vector of room **IDs** that conduwuit will make newly registered users join. -# The room IDs specified must be rooms that you have joined at least once on the server, and must be public. -# -# No default. -#auto_join_rooms = [] - -# Retry failed and incomplete messages to remote servers immediately upon startup. This is called bursting. -# If this is disabled, said messages may not be delivered until more messages are queued for that server. -# Do not change this option unless server resources are extremely limited or the scale of the server's -# deployment is huge. Do not disable this unless you know what you are doing. -#startup_netburst = true - -# Limit the startup netburst to the most recent (default: 50) messages queued for each remote server. All older -# messages are dropped and not reattempted. The `startup_netburst` option must be enabled for this value to have -# any effect. Do not change this value unless you know what you are doing. Set this value to -1 to reattempt -# every message without trimming the queues; this may consume significant disk. Set this value to 0 to drop all -# messages without any attempt at redelivery. -#startup_netburst_keep = 50 - -# If the 'perf_measurements' feature is enabled, enables collecting folded stack trace profile of tracing spans using -# tracing_flame. The resulting profile can be visualized with inferno[1], speedscope[2], or a number of other tools. -# [1]: https://github.com/jonhoo/inferno -# [2]: www.speedscope.app -# tracing_flame = false - -# If 'tracing_flame' is enabled, sets a filter for which events will be included in the profile. -# Supported syntax is documented at https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives -# tracing_flame_filter = "trace,h2=off" - -# If 'tracing_flame' is enabled, set the path to write the generated profile. -# tracing_flame_output_path = "./tracing.folded" - -# Enable the tokio-console. This option is only relevant to developers. -# See: docs/development.md#debugging-with-tokio-console for more information. -#tokio_console = false - -# Enable backward-compatibility with Conduit's media directory by creating symlinks of media. This -# option is only necessary if you plan on using Conduit again. Otherwise setting this to false -# reduces filesystem clutter and overhead for managing these symlinks in the directory. This is now -# disabled by default. You may still return to upstream Conduit but you have to run Conduwuit at -# least once with this set to true and allow the media_startup_check to take place before shutting -# down to return to Conduit. -# -# Disabled by default. -#media_compat_file_link = false - -# Prunes missing media from the database as part of the media startup checks. This means if you -# delete files from the media directory the corresponding entries will be removed from the -# database. This is disabled by default because if the media directory is accidentally moved or -# inaccessible the metadata entries in the database will be lost with sadness. -# -# Disabled by default. -#prune_missing_media = false - -# Checks consistency of the media directory at startup: -# 1. When `media_compat_file_link` is enbled, this check will upgrade media when switching back -# and forth between Conduit and Conduwuit. Both options must be enabled to handle this. -# 2. When media is deleted from the directory, this check will also delete its database entry. -# -# If none of these checks apply to your use cases, and your media directory is significantly large -# setting this to false may reduce startup time. -# -# Enabled by default. -#media_startup_check = true - # OpenID token expiration/TTL in seconds # -# These are the OpenID tokens that are primarily used for Matrix account integrations, *not* OIDC/OpenID Connect/etc +# These are the OpenID tokens that are primarily used for Matrix account +# integrations (e.g. Vector Integrations in Element), *not* OIDC/OpenID +# Connect/etc # -# Defaults to 3600 (1 hour) #openid_token_ttl = 3600 -# Emergency password feature. This password set here will let you login to the server service account (e.g. `@conduit`) -# and let you run admin commands, invite yourself to the admin room, etc. +# static TURN username to provide the client if not using a shared secret +# ("turn_secret"), It is recommended to use a shared secret over static +# credentials. # -# no default. -#emergency_password = "" +#turn_username = false - -### Generic database options - -# Set this to any float value to multiply conduwuit's in-memory LRU caches with. -# By default, the caches scale automatically with cpu-core-count. -# May be useful if you have significant memory to spare to increase performance. +# static TURN password to provide the client if not using a shared secret +# ("turn_secret"). It is recommended to use a shared secret over static +# credentials. # -# This was previously called `conduit_cache_capacity_modifier` +#turn_password = false + +# vector list of TURN URIs/servers to use # -# Defaults to 1.0. -#cache_capacity_modifier = 1.0 - -# Set this to any float value in megabytes for conduwuit to tell the database engine that this much memory is available for database-related caches. -# May be useful if you have significant memory to spare to increase performance. -# Defaults to 128.0 + (64.0 * CPU core count). -#db_cache_capacity_mb = 256.0 - - -### RocksDB options - -# Set this to true to use RocksDB config options that are tailored to HDDs (slower device storage) +# replace "example.turn.uri" with your TURN domain, such as the coturn +# "realm" config option. if using TURN over TLS, replace the URI prefix +# "turn:" with "turns:" # -# It is worth noting that by default, conduwuit will use RocksDB with Direct IO enabled. *Generally* speaking this improves performance as it bypasses buffered I/O (system page cache). -# However there is a potential chance that Direct IO may cause issues with database operations if your setup is uncommon. This has been observed with FUSE filesystems, and possibly ZFS filesystem. -# RocksDB generally deals/corrects these issues but it cannot account for all setups. -# If you experience any weird RocksDB issues, try enabling this option as it turns off Direct IO and feel free to report in the conduwuit Matrix room if this option fixes your DB issues. -# See https://github.com/facebook/rocksdb/wiki/Direct-IO for more information. +# example: ["turn:example.turn.uri?transport=udp", +# "turn:example.turn.uri?transport=tcp"] # -# Defaults to false -#rocksdb_optimize_for_spinning_disks = false +#turn_uris = [] -# Enables direct-io to increase database performance. This is enabled by default. Set this option to false if the -# database resides on a filesystem which does not support direct-io. -#rocksdb_direct_io = true +# TURN secret to use for generating the HMAC-SHA1 hash apart of username +# and password generation +# +# this is more secure, but if needed you can use traditional +# static username/password credentials. +# +#turn_secret = false -# RocksDB log level. This is not the same as conduwuit's log level. This is the log level for the RocksDB engine/library -# which show up in your database folder/path as `LOG` files. Defaults to error. conduwuit will typically log RocksDB errors as normal. +# TURN secret to use that's read from the file path specified +# +# this takes priority over "turn_secret" first, and falls back to +# "turn_secret" if invalid or failed to open. +# +# example: "/etc/conduwuit/.turn_secret" +# +#turn_secret_file = + +# TURN TTL in seconds +# +#turn_ttl = 86400 + +# List/vector of room IDs or room aliases that conduwuit will make newly +# registered users join. The rooms specified must be rooms that you +# have joined at least once on the server, and must be public. +# +# example: ["#conduwuit:puppygock.gay", +# "!eoIzvAvVwY23LPDay8:puppygock.gay"] +# +#auto_join_rooms = [] + +# Config option to automatically deactivate the account of any user who +# attempts to join a: +# - banned room +# - forbidden room alias +# - room alias or ID with a forbidden server name +# +# This may be useful if all your banned lists consist of toxic rooms or +# servers that no good faith user would ever attempt to join, and +# to automatically remediate the problem without any admin user +# intervention. +# +# This will also make the user leave all rooms. Federation (e.g. remote +# room invites) are ignored here. +# +# Defaults to false as rooms can be banned for non-moderation-related +# reasons +# +#auto_deactivate_banned_room_attempts = false + +# RocksDB log level. This is not the same as conduwuit's log level. This +# is the log level for the RocksDB engine/library which show up in your +# database folder/path as `LOG` files. conduwuit will log RocksDB errors +# as normal through tracing. +# #rocksdb_log_level = "error" -# Max RocksDB `LOG` file size before rotating in bytes. Defaults to 4MB. +# This item is undocumented. Please contribute documentation for it. +# +#rocksdb_log_stderr = false + +# Max RocksDB `LOG` file size before rotating in bytes. Defaults to 4MB in +# bytes. +# #rocksdb_max_log_file_size = 4194304 -# Time in seconds before RocksDB will forcibly rotate logs. Defaults to 0. +# Time in seconds before RocksDB will forcibly rotate logs. +# #rocksdb_log_time_to_roll = 0 -# Amount of threads that RocksDB will use for parallelism on database operatons such as cleanup, sync, flush, compaction, etc. Set to 0 to use all your logical threads. +# Set this to true to use RocksDB config options that are tailored to HDDs +# (slower device storage) +# +# It is worth noting that by default, conduwuit will use RocksDB with +# Direct IO enabled. *Generally* speaking this improves performance as it +# bypasses buffered I/O (system page cache). However there is a potential +# chance that Direct IO may cause issues with database operations if your +# setup is uncommon. This has been observed with FUSE filesystems, and +# possibly ZFS filesystem. RocksDB generally deals/corrects these issues +# but it cannot account for all setups. If you experience any weird +# RocksDB issues, try enabling this option as it turns off Direct IO and +# feel free to report in the conduwuit Matrix room if this option fixes +# your DB issues. +# +# See https://github.com/facebook/rocksdb/wiki/Direct-IO for more information. +# +#rocksdb_optimize_for_spinning_disks = false + +# Enables direct-io to increase database performance via unbuffered I/O. +# +# See https://github.com/facebook/rocksdb/wiki/Direct-IO for more details about Direct IO and RocksDB. +# +# Set this option to false if the database resides on a filesystem which +# does not support direct-io like FUSE, or any form of complex filesystem +# setup such as possibly ZFS. +# +#rocksdb_direct_io = true + +# Amount of threads that RocksDB will use for parallelism on database +# operatons such as cleanup, sync, flush, compaction, etc. Set to 0 to use +# all your logical threads. Defaults to your CPU logical thread count. # -# Defaults to your CPU logical thread count. #rocksdb_parallelism_threads = 0 -# Enables idle IO priority for compaction thread. This prevents any unexpected lag in the server's operation and -# is usually a good idea. Enabled by default. -#rocksdb_compaction_ioprio_idle = true - -# Enables idle CPU priority for compaction thread. This is not enabled by default to prevent compaction from -# falling too far behind on busy systems. -#rocksdb_compaction_prio_idle = false - -# Maximum number of LOG files RocksDB will keep. This must *not* be set to 0. It must be at least 1. -# Defaults to 3 as these are not very useful. +# Maximum number of LOG files RocksDB will keep. This must *not* be set to +# 0. It must be at least 1. Defaults to 3 as these are not very useful +# unless troubleshooting/debugging a RocksDB bug. +# #rocksdb_max_log_files = 3 # Type of RocksDB database compression to use. +# # Available options are "zstd", "zlib", "bz2", "lz4", or "none" -# It is best to use ZSTD as an overall good balance between speed/performance, storage, IO amplification, and CPU usage. -# For more performance but less compression (more storage used) and less CPU usage, use LZ4. -# See https://github.com/facebook/rocksdb/wiki/Compression for more details. +# +# It is best to use ZSTD as an overall good balance between +# speed/performance, storage, IO amplification, and CPU usage. +# For more performance but less compression (more storage used) and less +# CPU usage, use LZ4. See https://github.com/facebook/rocksdb/wiki/Compression for more details. # # "none" will disable compression. # -# Defaults to "zstd" #rocksdb_compression_algo = "zstd" -# Level of compression the specified compression algorithm for RocksDB to use. -# Default is 32767, which is internally read by RocksDB as the default magic number and -# translated to the library's default compression level as they all differ. +# Level of compression the specified compression algorithm for RocksDB to +# use. +# +# Default is 32767, which is internally read by RocksDB as the +# default magic number and translated to the library's default +# compression level as they all differ. # See their `kDefaultCompressionLevel`. # #rocksdb_compression_level = 32767 -# Level of compression the specified compression algorithm for the bottommost level/data for RocksDB to use. -# Default is 32767, which is internally read by RocksDB as the default magic number and -# translated to the library's default compression level as they all differ. +# Level of compression the specified compression algorithm for the +# bottommost level/data for RocksDB to use. Default is 32767, which is +# internally read by RocksDB as the default magic number and translated +# to the library's default compression level as they all differ. # See their `kDefaultCompressionLevel`. # -# Since this is the bottommost level (generally old and least used data), it may be desirable to have a very -# high compression level here as it's lesss likely for this data to be used. Research your chosen compression algorithm. +# Since this is the bottommost level (generally old and least used data), +# it may be desirable to have a very high compression level here as it's +# lesss likely for this data to be used. Research your chosen compression +# algorithm. # #rocksdb_bottommost_compression_level = 32767 -# Whether to enable RocksDB "bottommost_compression". -# At the expense of more CPU usage, this will further compress the database to reduce more storage. -# It is recommended to use ZSTD compression with this for best compression results. +# Whether to enable RocksDB's "bottommost_compression". +# +# At the expense of more CPU usage, this will further compress the +# database to reduce more storage. It is recommended to use ZSTD +# compression with this for best compression results. This may be useful +# if you're trying to reduce storage usage from the database. +# # See https://github.com/facebook/rocksdb/wiki/Compression for more details. # -# Defaults to false as this uses more CPU when compressing. #rocksdb_bottommost_compression = false -# Level of statistics collection. Some admin commands to display database statistics may require -# this option to be set. Database performance may be impacted by higher settings. +# Database recovery mode (for RocksDB WAL corruption) +# +# Use this option when the server reports corruption and refuses to start. +# Set mode 2 (PointInTime) to cleanly recover from this corruption. The +# server will continue from the last good state, several seconds or +# minutes prior to the crash. Clients may have to run "clear-cache & +# reload" to account for the rollback. Upon success, you may reset the +# mode back to default and restart again. Please note in some cases the +# corruption error may not be cleared for at least 30 minutes of +# operation in PointInTime mode. +# +# As a very last ditch effort, if PointInTime does not fix or resolve +# anything, you can try mode 3 (SkipAnyCorruptedRecord) but this will +# leave the server in a potentially inconsistent state. +# +# The default mode 1 (TolerateCorruptedTailRecords) will automatically +# drop the last entry in the database if corrupted during shutdown, but +# nothing more. It is extraordinarily unlikely this will desynchronize +# clients. To disable any form of silent rollback set mode 0 +# (AbsoluteConsistency). +# +# The options are: +# 0 = AbsoluteConsistency +# 1 = TolerateCorruptedTailRecords (default) +# 2 = PointInTime (use me if trying to recover) +# 3 = SkipAnyCorruptedRecord (you now voided your Conduwuit warranty) +# +# See https://github.com/facebook/rocksdb/wiki/WAL-Recovery-Modes for more information on these modes. +# +# See https://conduwuit.puppyirl.gay/troubleshooting.html#database-corruption for more details on recovering a corrupt database. +# +#rocksdb_recovery_mode = 1 + +# Database repair mode (for RocksDB SST corruption) +# +# Use this option when the server reports corruption while running or +# panics. If the server refuses to start use the recovery mode options +# first. Corruption errors containing the acronym 'SST' which occur after +# startup will likely require this option. +# +# - Backing up your database directory is recommended prior to running the +# repair. +# - Disabling repair mode and restarting the server is recommended after +# running the repair. +# +# See https://conduwuit.puppyirl.gay/troubleshooting.html#database-corruption for more details on recovering a corrupt database. +# +#rocksdb_repair = false + +# This item is undocumented. Please contribute documentation for it. +# +#rocksdb_read_only = false + +# This item is undocumented. Please contribute documentation for it. +# +#rocksdb_secondary = false + +# Enables idle CPU priority for compaction thread. This is not enabled by +# default to prevent compaction from falling too far behind on busy +# systems. +# +#rocksdb_compaction_prio_idle = false + +# Enables idle IO priority for compaction thread. This prevents any +# unexpected lag in the server's operation and is usually a good idea. +# Enabled by default. +# +#rocksdb_compaction_ioprio_idle = true + +# Config option to disable RocksDB compaction. You should never ever have +# to disable this. If you for some reason find yourself needing to disable +# this as part of troubleshooting or a bug, please reach out to us in the +# conduwuit Matrix room with information and details. +# +# Disabling compaction will lead to a significantly bloated and +# explosively large database, gradually poor performance, unnecessarily +# excessive disk read/writes, and slower shutdowns and startups. +# +#rocksdb_compaction = true + +# Level of statistics collection. Some admin commands to display database +# statistics may require this option to be set. Database performance may +# be impacted by higher settings. # # Option is a number ranging from 0 to 6: # 0 = No statistics. @@ -608,338 +870,509 @@ allow_profile_lookup_federation_requests = true # 3 to 5 = Statistics with possible performance impact. # 6 = All statistics. # -# Defaults to 1 (No statistics, except in debug-mode) #rocksdb_stats_level = 1 -# Database repair mode (for RocksDB SST corruption) +# This is a password that can be configured that will let you login to the +# server bot account (currently `@conduit`) for emergency troubleshooting +# purposes such as recovering/recreating your admin room, or inviting +# yourself back. # -# Use this option when the server reports corruption while running or panics. If the server refuses -# to start use the recovery mode options first. Corruption errors containing the acronym 'SST' which -# occur after startup will likely require this option. +# See https://conduwuit.puppyirl.gay/troubleshooting.html#lost-access-to-admin-room for other ways to get back into your admin room. # -# - Backing up your database directory is recommended prior to running the repair. -# - Disabling repair mode and restarting the server is recommended after running the repair. +# Once this password is unset, all sessions will be logged out for +# security purposes. # -# Defaults to false -#rocksdb_repair = false - -# Database recovery mode (for RocksDB WAL corruption) +# example: "F670$2CP@Hw8mG7RY1$%!#Ic7YA" # -# Use this option when the server reports corruption and refuses to start. Set mode 2 (PointInTime) -# to cleanly recover from this corruption. The server will continue from the last good state, -# several seconds or minutes prior to the crash. Clients may have to run "clear-cache & reload" to -# account for the rollback. Upon success, you may reset the mode back to default and restart again. -# Please note in some cases the corruption error may not be cleared for at least 30 minutes of -# operation in PointInTime mode. +#emergency_password = + +# This item is undocumented. Please contribute documentation for it. # -# As a very last ditch effort, if PointInTime does not fix or resolve anything, you can try mode -# 3 (SkipAnyCorruptedRecord) but this will leave the server in a potentially inconsistent state. -# -# The default mode 1 (TolerateCorruptedTailRecords) will automatically drop the last entry in the -# database if corrupted during shutdown, but nothing more. It is extraordinarily unlikely this will -# desynchronize clients. To disable any form of silent rollback set mode 0 (AbsoluteConsistency). -# -# The options are: -# 0 = AbsoluteConsistency -# 1 = TolerateCorruptedTailRecords (default) -# 2 = PointInTime (use me if trying to recover) -# 3 = SkipAnyCorruptedRecord (you now voided your Conduwuit warranty) -# -# See https://github.com/facebook/rocksdb/wiki/WAL-Recovery-Modes for more information -# -# Defaults to 1 (TolerateCorruptedTailRecords) -#rocksdb_recovery_mode = 1 +#notification_push_path = "/_matrix/push/v1/notify" - -### Domain Name Resolution and Caching - -# Maximum entries stored in DNS memory-cache. The size of an entry may vary so please take care if -# raising this value excessively. Only decrease this when using an external DNS cache. Please note -# that systemd does *not* count as an external cache, even when configured to do so. -#dns_cache_entries = 32768 - -# Minimum time-to-live in seconds for entries in the DNS cache. The default may appear high to most -# administrators; this is by design. Only decrease this if you are using an external DNS cache. -#dns_min_ttl = 10800 - -# Minimum time-to-live in seconds for NXDOMAIN entries in the DNS cache. This value is critical for -# the server to federate efficiently. NXDOMAIN's are assumed to not be returning to the federation -# and aggressively cached rather than constantly rechecked. -# -# Defaults to 3 days as these are *very rarely* false negatives. -#dns_min_ttl_nxdomain = 259200 - -# The number of seconds to wait for a reply to a DNS query. Please note that recursive queries can -# take up to several seconds for some domains, so this value should not be too low. -#dns_timeout = 10 - -# Number of retries after a timeout. -#dns_attempts = 10 - -# Fallback to TCP on DNS errors. Set this to false if unsupported by nameserver. -#dns_tcp_fallback = true - -# Enable to query all nameservers until the domain is found. Referred to as "trust_negative_responses" in hickory_resolver. -# This can avoid useless DNS queries if the first nameserver responds with NXDOMAIN or an empty NOERROR response. -# -# The default is to query one nameserver and stop (false). -#query_all_nameservers = true - -# Enables using *only* TCP for querying your specified nameservers instead of UDP. -# -# You very likely do *not* want this. hickory-resolver already falls back to TCP on UDP errors. -# Defaults to false -#query_over_tcp_only = false - -# DNS A/AAAA record lookup strategy -# -# Takes a number of one of the following options: -# 1 - Ipv4Only (Only query for A records, no AAAA/IPv6) -# 2 - Ipv6Only (Only query for AAAA records, no A/IPv4) -# 3 - Ipv4AndIpv6 (Query for A and AAAA records in parallel, uses whatever returns a successful response first) -# 4 - Ipv6thenIpv4 (Query for AAAA record, if that fails then query the A record) -# 5 - Ipv4thenIpv6 (Query for A record, if that fails then query the AAAA record) -# -# If you don't have IPv6 networking, then for better performance it may be suitable to set this to Ipv4Only (1) as -# you will never ever use the AAAA record contents even if the AAAA record is successful instead of the A record. -# -# Defaults to 5 - Ipv4ThenIpv6 as this is the most compatible and IPv4 networking is currently the most prevalent. -#ip_lookup_strategy = 5 - - -### Request Timeouts, Connection Timeouts, and Connection Pooling - -## Request Timeouts are HTTP response timeouts -## Connection Timeouts are TCP connection timeouts -## -## Connection Pooling Timeouts are timeouts for keeping an open idle connection alive. -## Connection pooling and keepalive is very useful for federation or other places where for performance reasons, -## we want to keep connections open that we will re-use frequently due to TCP and TLS 1.3 overhead/expensiveness. -## -## Generally these defaults are the best, but if you find a reason to need to change these they are here. - -# Default/base connection timeout. -# This is used only by URL previews and update/news endpoint checks -# -# Defaults to 10 seconds -#request_conn_timeout = 10 - -# Default/base request timeout. The time waiting to receive more data from another server. -# This is used only by URL previews, update/news, and misc endpoint checks -# -# Defaults to 35 seconds -#request_timeout = 35 - -# Default/base request total timeout. The time limit for a whole request. This is set very high to not -# cancel healthy requests while serving as a backstop. -# This is used only by URL previews and update/news endpoint checks -# -# Defaults to 320 seconds -#request_total_timeout = 320 - -# Default/base idle connection pool timeout -# This is used only by URL previews and update/news endpoint checks -# -# Defaults to 5 seconds -#request_idle_timeout = 5 - -# Default/base max idle connections per host -# This is used only by URL previews and update/news endpoint checks -# -# Defaults to 1 as generally the same open connection can be re-used -#request_idle_per_host = 1 - -# Federation well-known resolution connection timeout -# -# Defaults to 6 seconds -#well_known_conn_timeout = 6 - -# Federation HTTP well-known resolution request timeout -# -# Defaults to 10 seconds -#well_known_timeout = 10 - -# Federation client request timeout -# You most definitely want this to be high to account for extremely large room joins, slow homeservers, your own resources etc. -# -# Defaults to 300 seconds -#federation_timeout = 300 - -# Federation client idle connection pool timeout -# -# Defaults to 25 seconds -#federation_idle_timeout = 25 - -# Federation client max idle connections per host -# -# Defaults to 1 as generally the same open connection can be re-used -#federation_idle_per_host = 1 - -# Federation sender request timeout -# The time it takes for the remote server to process sent transactions can take a while. -# -# Defaults to 180 seconds -#sender_timeout = 180 - -# Federation sender idle connection pool timeout -# -# Defaults to 180 seconds -#sender_idle_timeout = 180 - -# Federation sender transaction retry backoff limit -# -# Defaults to 86400 seconds -#sender_retry_backoff_limit = 86400 - -# Appservice URL request connection timeout -# -# Defaults to 35 seconds as generally appservices are hosted within the same network -#appservice_timeout = 35 - -# Appservice URL idle connection pool timeout -# -# Defaults to 300 seconds -#appservice_idle_timeout = 300 - -# Notification gateway pusher idle connection pool timeout -# -# Defaults to 15 seconds -#pusher_idle_timeout = 15 - - -### Presence / Typing Indicators / Read Receipts - -# Config option to control local (your server only) presence updates/requests. Defaults to true. -# Note that presence on conduwuit is very fast unlike Synapse's. -# If using outgoing presence, this MUST be enabled. +# Config option to control local (your server only) presence +# updates/requests. Note that presence on conduwuit is +# very fast unlike Synapse's. If using outgoing presence, this MUST be +# enabled. # #allow_local_presence = true -# Config option to control incoming federated presence updates/requests. Defaults to true. -# This option receives presence updates from other servers, but does not send any unless `allow_outgoing_presence` is true. +# Config option to control incoming federated presence updates/requests. +# +# This option receives presence updates from other +# servers, but does not send any unless `allow_outgoing_presence` is true. # Note that presence on conduwuit is very fast unlike Synapse's. # #allow_incoming_presence = true -# Config option to control outgoing presence updates/requests. Defaults to true. -# This option sends presence updates to other servers, but does not receive any unless `allow_incoming_presence` is true. +# Config option to control outgoing presence updates/requests. +# +# This option sends presence updates to other servers, but does not +# receive any unless `allow_incoming_presence` is true. # Note that presence on conduwuit is very fast unlike Synapse's. -# If using outgoing presence, you MUST enable `allow_local_presence` as well. +# If using outgoing presence, you MUST enable `allow_local_presence` as +# well. # #allow_outgoing_presence = true -# Config option to enable the presence idle timer for remote users. Disabling is offered as an optimization for -# servers participating in many large rooms or when resources are limited. Disabling it may cause incorrect -# presence states (i.e. stuck online) to be seen for some remote users. Defaults to true. -#presence_timeout_remote_users = true - -# Config option to control how many seconds before presence updates that you are idle. Defaults to 5 minutes. +# Config option to control how many seconds before presence updates that +# you are idle. Defaults to 5 minutes. +# #presence_idle_timeout_s = 300 -# Config option to control how many seconds before presence updates that you are offline. Defaults to 30 minutes. +# Config option to control how many seconds before presence updates that +# you are offline. Defaults to 30 minutes. +# #presence_offline_timeout_s = 1800 -# Config option to control whether we should receive remote incoming read receipts. -# Defaults to true. +# Config option to enable the presence idle timer for remote users. +# Disabling is offered as an optimization for servers participating in +# many large rooms or when resources are limited. Disabling it may cause +# incorrect presence states (i.e. stuck online) to be seen for some +# remote users. +# +#presence_timeout_remote_users = true + +# Config option to control whether we should receive remote incoming read +# receipts. +# #allow_incoming_read_receipts = true -# Config option to control whether we should send read receipts to remote servers. -# Defaults to true. +# Config option to control whether we should send read receipts to remote +# servers. +# #allow_outgoing_read_receipts = true -# Config option to control outgoing typing updates to federation. Defaults to true. +# Config option to control outgoing typing updates to federation. +# #allow_outgoing_typing = true -# Config option to control incoming typing updates from federation. Defaults to true. +# Config option to control incoming typing updates from federation. +# #allow_incoming_typing = true -# Config option to control maximum time federation user can indicate typing. +# Config option to control maximum time federation user can indicate +# typing. +# #typing_federation_timeout_s = 30 -# Config option to control minimum time local client can indicate typing. This does not override -# a client's request to stop typing. It only enforces a minimum value in case of no stop request. +# Config option to control minimum time local client can indicate typing. +# This does not override a client's request to stop typing. It only +# enforces a minimum value in case of no stop request. +# #typing_client_timeout_min_s = 15 # Config option to control maximum time local client can indicate typing. +# #typing_client_timeout_max_s = 45 +# Set this to true for conduwuit to compress HTTP response bodies using +# zstd. This option does nothing if conduwuit was not built with +# `zstd_compression` feature. Please be aware that enabling HTTP +# compression may weaken TLS. Most users should not need to enable this. +# See https://breachattack.com/ and https://wikipedia.org/wiki/BREACH +# before deciding to enable this. +# +#zstd_compression = false -### TURN / VoIP +# Set this to true for conduwuit to compress HTTP response bodies using +# gzip. This option does nothing if conduwuit was not built with +# `gzip_compression` feature. Please be aware that enabling HTTP +# compression may weaken TLS. Most users should not need to enable this. +# See https://breachattack.com/ and https://wikipedia.org/wiki/BREACH before +# deciding to enable this. +# +# If you are in a large amount of rooms, you may find that enabling this +# is necessary to reduce the significantly large response bodies. +# +#gzip_compression = false -# vector list of TURN URIs/servers to use +# Set this to true for conduwuit to compress HTTP response bodies using +# brotli. This option does nothing if conduwuit was not built with +# `brotli_compression` feature. Please be aware that enabling HTTP +# compression may weaken TLS. Most users should not need to enable this. +# See https://breachattack.com/ and https://wikipedia.org/wiki/BREACH before +# deciding to enable this. # -# replace "example.turn.uri" with your TURN domain, such as the coturn "realm". -# if using TURN over TLS, replace "turn:" with "turns:" -# -# No default -#turn_uris = ["turn:example.turn.uri?transport=udp", "turn:example.turn.uri?transport=tcp"] +#brotli_compression = false -# TURN secret to use that's read from the file path specified +# Set to true to allow user type "guest" registrations. Some clients like +# Element attempt to register guest users automatically. # -# this takes priority over "turn_secret" first, and falls back to "turn_secret" if invalid or -# failed to open. -# -# no default -#turn_secret_file = "/path/to/secret.txt" +#allow_guest_registration = false -# TURN secret to use for generating the HMAC-SHA1 hash apart of username and password generation +# Set to true to log guest registrations in the admin room. Note that +# these may be noisy or unnecessary if you're a public homeserver. # -# this is more secure, but if needed you can use traditional username/password below. -# -# no default -#turn_secret = "" +#log_guest_registrations = false -# TURN username to provide the client +# Set to true to allow guest registrations/users to auto join any rooms +# specified in `auto_join_rooms`. # -# no default -#turn_username = "" +#allow_guests_auto_join_rooms = false -# TURN password to provide the client +# Config option to control whether the legacy unauthenticated Matrix media +# repository endpoints will be enabled. These endpoints consist of: +# - /_matrix/media/*/config +# - /_matrix/media/*/upload +# - /_matrix/media/*/preview_url +# - /_matrix/media/*/download/* +# - /_matrix/media/*/thumbnail/* # -# no default -#turn_password = "" +# The authenticated equivalent endpoints are always enabled. +# +# Defaults to true for now, but this is highly subject to change, likely +# in the next release. +# +#allow_legacy_media = true -# TURN TTL +# This item is undocumented. Please contribute documentation for it. # -# Default is 86400 seconds -#turn_ttl = 86400 +#freeze_legacy_media = true -# allow guests/unauthenticated users to access TURN credentials +# Checks consistency of the media directory at startup: +# 1. When `media_compat_file_link` is enbled, this check will upgrade +# media when switching back and forth between Conduit and conduwuit. +# Both options must be enabled to handle this. +# 2. When media is deleted from the directory, this check will also delete +# its database entry. # -# this is the equivalent of Synapse's `turn_allow_guests` config option. this allows -# any unauthenticated user to call `/_matrix/client/v3/voip/turnServer`. +# If none of these checks apply to your use cases, and your media +# directory is significantly large setting this to false may reduce +# startup time. # -# defaults to false -#turn_allow_guests = false +#media_startup_check = true +# Enable backward-compatibility with Conduit's media directory by creating +# symlinks of media. This option is only necessary if you plan on using +# Conduit again. Otherwise setting this to false reduces filesystem +# clutter and overhead for managing these symlinks in the directory. This +# is now disabled by default. You may still return to upstream Conduit +# but you have to run conduwuit at least once with this set to true and +# allow the media_startup_check to take place before shutting +# down to return to Conduit. +# +#media_compat_file_link = false -# Other options not in [global]: +# Prunes missing media from the database as part of the media startup +# checks. This means if you delete files from the media directory the +# corresponding entries will be removed from the database. This is +# disabled by default because if the media directory is accidentally moved +# or inaccessible, the metadata entries in the database will be lost with +# sadness. +# +#prune_missing_media = false + +# Vector list of servers that conduwuit will refuse to download remote +# media from. +# +#prevent_media_downloads_from = [] + +# List of forbidden server names that we will block incoming AND outgoing +# federation with, and block client room joins / remote user invites. +# +# This check is applied on the room ID, room alias, sender server name, +# sender user's server name, inbound federation X-Matrix origin, and +# outbound federation handler. +# +# Basically "global" ACLs. +# +#forbidden_remote_server_names = [] + +# List of forbidden server names that we will block all outgoing federated +# room directory requests for. Useful for preventing our users from +# wandering into bad servers or spaces. +# +#forbidden_remote_room_directory_server_names = [] + +# Vector list of IPv4 and IPv6 CIDR ranges / subnets *in quotes* that you +# do not want conduwuit to send outbound requests to. Defaults to +# RFC1918, unroutable, loopback, multicast, and testnet addresses for +# security. +# +# Please be aware that this is *not* a guarantee. You should be using a +# firewall with zones as doing this on the application layer may have +# bypasses. +# +# Currently this does not account for proxies in use like Synapse does. +# +# To disable, set this to be an empty vector (`[]`). +# +# "192.168.0.0/16", "100.64.0.0/10", "192.0.0.0/24", "169.254.0.0/16", +# "192.88.99.0/24", "198.18.0.0/15", "192.0.2.0/24", "198.51.100.0/24", +# "203.0.113.0/24", "224.0.0.0/4", "::1/128", "fe80::/10", "fc00::/7", +# "2001:db8::/32", "ff00::/8", "fec0::/10"] +# +#ip_range_denylist = ["127.0.0.0/8", "10.0.0.0/8", "172.16.0.0/12", + +# Vector list of domains allowed to send requests to for URL previews. +# Defaults to none. Note: this is a *contains* match, not an explicit +# match. Putting "google.com" will match "https://google.com" and +# "http://mymaliciousdomainexamplegoogle.com" Setting this to "*" will +# allow all URL previews. Please note that this opens up significant +# attack surface to your server, you are expected to be aware of the +# risks by doing so. +# +#url_preview_domain_contains_allowlist = [] + +# Vector list of explicit domains allowed to send requests to for URL +# previews. Defaults to none. Note: This is an *explicit* match, not a +# contains match. Putting "google.com" will match "https://google.com", +# "http://google.com", but not +# "https://mymaliciousdomainexamplegoogle.com". Setting this to "*" will +# allow all URL previews. Please note that this opens up significant +# attack surface to your server, you are expected to be aware of the +# risks by doing so. +# +#url_preview_domain_explicit_allowlist = [] + +# Vector list of explicit domains not allowed to send requests to for URL +# previews. Defaults to none. Note: This is an *explicit* match, not a +# contains match. Putting "google.com" will match "https://google.com", +# "http://google.com", but not +# "https://mymaliciousdomainexamplegoogle.com". The denylist is checked +# first before allowlist. Setting this to "*" will not do anything. +# +#url_preview_domain_explicit_denylist = [] + +# Vector list of URLs allowed to send requests to for URL previews. +# Defaults to none. Note that this is a *contains* match, not an +# explicit match. Putting "google.com" will match +# "https://google.com/", +# "https://google.com/url?q=https://mymaliciousdomainexample.com", and +# "https://mymaliciousdomainexample.com/hi/google.com" Setting this to +# "*" will allow all URL previews. Please note that this opens up +# significant attack surface to your server, you are expected to be +# aware of the risks by doing so. +# +#url_preview_url_contains_allowlist = [] + +# Maximum amount of bytes allowed in a URL preview body size when +# spidering. Defaults to 384KB in bytes. +# +#url_preview_max_spider_size = 384000 + +# Option to decide whether you would like to run the domain allowlist +# checks (contains and explicit) on the root domain or not. Does not apply +# to URL contains allowlist. Defaults to false. +# +# Example usecase: If this is +# enabled and you have "wikipedia.org" allowed in the explicit and/or +# contains domain allowlist, it will allow all subdomains under +# "wikipedia.org" such as "en.m.wikipedia.org" as the root domain is +# checked and matched. Useful if the domain contains allowlist is still +# too broad for you but you still want to allow all the subdomains under a +# root domain. +# +#url_preview_check_root_domain = false + +# List of forbidden room aliases and room IDs as strings of regex +# patterns. +# +# Regex can be used or explicit contains matches can be done by +# just specifying the words (see example). +# +# This is checked upon room alias creation, custom room ID creation if +# used, and startup as warnings if any room aliases in your database have +# a forbidden room alias/ID. +# +# example: ["19dollarfortnitecards", "b[4a]droom"] +# +#forbidden_alias_names = [] + +# List of forbidden username patterns/strings. +# +# Regex can be used or explicit contains matches can be done by just +# specifying the words (see example). +# +# This is checked upon username availability check, registration, and +# startup as warnings if any local users in your database have a forbidden +# username. +# +# example: ["administrator", "b[a4]dusernam[3e]"] +# +#forbidden_usernames = [] + +# Retry failed and incomplete messages to remote servers immediately upon +# startup. This is called bursting. If this is disabled, said messages +# may not be delivered until more messages are queued for that server. Do +# not change this option unless server resources are extremely limited or +# the scale of the server's deployment is huge. Do not disable this +# unless you know what you are doing. +# +#startup_netburst = true + +# messages are dropped and not reattempted. The `startup_netburst` option +# must be enabled for this value to have any effect. Do not change this +# value unless you know what you are doing. Set this value to -1 to +# reattempt every message without trimming the queues; this may consume +# significant disk. Set this value to 0 to drop all messages without any +# attempt at redelivery. +# +#startup_netburst_keep = 50 + +# controls whether non-admin local users are forbidden from sending room +# invites (local and remote), and if non-admin users can receive remote +# room invites. admins are always allowed to send and receive all room +# invites. +# +#block_non_admin_invites = false + +# Allows admins to enter commands in rooms other than "#admins" (admin +# room) by prefixing your message with "\!admin" or "\\!admin" followed +# up a normal conduwuit admin command. The reply will be publicly visible +# to the room, originating from the sender. +# +# example: \\!admin debug ping puppygock.gay +# +#admin_escape_commands = true + +# Controls whether the conduwuit admin room console / CLI will immediately +# activate on startup. This option can also be enabled with `--console` +# conduwuit argument. +# +#admin_console_automatic = false + +# Controls what admin commands will be executed on startup. This is a +# vector list of strings of admin commands to run. # # -# Enables running conduwuit with direct TLS support -# It is strongly recommended you use a reverse proxy instead. This is primarily relevant for test suites like complement that require a private CA setup. -# [global.tls] -# certs = "/path/to/my/certificate.crt" -# key = "/path/to/my/private_key.key" +# This option can also be configured with the `--execute` conduwuit +# argument and can take standard shell commands and environment variables # +# Such example could be: `./conduwuit --execute "server admin-notice +# conduwuit has started up at $(date)"` +# +# example: admin_execute = ["debug ping puppygock.gay", "debug echo hi"]` +# +#admin_execute = [] + +# Controls whether conduwuit should error and fail to start if an admin +# execute command (`--execute` / `admin_execute`) fails. +# +#admin_execute_errors_ignore = false + +# Controls the max log level for admin command log captures (logs +# generated from running admin commands). Defaults to "info" on release +# builds, else "debug" on debug builds. +# +#admin_log_capture = "info" + +# The default room tag to apply on the admin room. +# +# On some clients like Element, the room tag "m.server_notice" is a +# special pinned room at the very bottom of your room list. The conduwuit +# admin room can be pinned here so you always have an easy-to-access +# shortcut dedicated to your admin room. +# +#admin_room_tag = "m.server_notice" + +# Sentry.io crash/panic reporting, performance monitoring/metrics, etc. +# This is NOT enabled by default. conduwuit's default Sentry reporting +# endpoint is o4506996327251968.ingest.us.sentry.io +# +#sentry = false + +# Sentry reporting URL if a custom one is desired +# +#sentry_endpoint = "https://fe2eb4536aa04949e28eff3128d64757@o4506996327251968.ingest.us.sentry.io/4506996334657536" + +# Report your conduwuit server_name in Sentry.io crash reports and metrics +# +#sentry_send_server_name = false + +# Performance monitoring/tracing sample rate for Sentry.io +# +# Note that too high values may impact performance, and can be disabled by +# setting it to 0.0 (0%) This value is read as a percentage to Sentry, +# represented as a decimal. Defaults to 15% of traces (0.15) +# +#sentry_traces_sample_rate = 0.15 + +# Whether to attach a stacktrace to Sentry reports. +# +#sentry_attach_stacktrace = false + +# Send panics to sentry. This is true by default, but sentry has to be +# enabled. The global "sentry" config option must be enabled to send any +# data. +# +#sentry_send_panic = true + +# Send errors to sentry. This is true by default, but sentry has to be +# enabled. This option is only effective in release-mode; forced to false +# in debug-mode. +# +#sentry_send_error = true + +# Controls the tracing log level for Sentry to send things like +# breadcrumbs and transactions +# +#sentry_filter = "info" + +# Enable the tokio-console. This option is only relevant to developers. +# See https://conduwuit.puppyirl.gay/development.html#debugging-with-tokio-console for more information. +# +#tokio_console = false + +# This item is undocumented. Please contribute documentation for it. +# +#test = false + +# Controls whether admin room notices like account registrations, password +# changes, account deactivations, room directory publications, etc will +# be sent to the admin room. Update notices and normal admin command +# responses will still be sent. +# +#admin_room_notices = true + +[global.tls] + +# Path to a valid TLS certificate file. +# +# example: "/path/to/my/certificate.crt" +# +#certs = + +# Path to a valid TLS certificate private key. +# +# example: "/path/to/my/certificate.key" +# +#key = + # Whether to listen and allow for HTTP and HTTPS connections (insecure!) -# This config option is only available if conduwuit was built with `axum_dual_protocol` feature (not default feature) -# Defaults to false +# #dual_protocol = false +[global.well_known] -# If you are using delegation via well-known files and you cannot serve them from your reverse proxy, you can -# uncomment these to serve them directly from conduwuit. This requires proxying all requests to conduwuit, not just `/_matrix` to work. +# The server base domain of the URL with a specific port that the server +# well-known file will serve. This should contain a port at the end, and +# should not be a URL. # -#[global.well_known] -#server = "matrix.example.com:443" -#client = "https://matrix.example.com" +# example: "matrix.example.com:443" # -# A single contact and/or support page for /.well-known/matrix/support -# All options here are strings. Currently only supports 1 single contact. -# No default. +#server = + +# The server URL that the client well-known file will serve. This should +# not contain a port, and should just be a valid HTTPS URL. # -#support_page = "" -#support_role = "" -#support_email = "" -#support_mxid = "" +# example: "https://matrix.example.com" +# +#client = + +# This item is undocumented. Please contribute documentation for it. +# +#support_page = + +# This item is undocumented. Please contribute documentation for it. +# +#support_role = + +# This item is undocumented. Please contribute documentation for it. +# +#support_email = + +# This item is undocumented. Please contribute documentation for it. +# +#support_mxid = diff --git a/src/api/server/make_knock.rs b/src/api/server/make_knock.rs new file mode 100644 index 00000000..c1875a1f --- /dev/null +++ b/src/api/server/make_knock.rs @@ -0,0 +1,107 @@ +use axum::extract::State; +use conduit::Err; +use ruma::{ + api::{client::error::ErrorKind, federation::knock::create_knock_event_template}, + events::room::member::{MembershipState, RoomMemberEventContent}, + RoomVersionId, +}; +use serde_json::value::to_raw_value; +use tracing::warn; +use RoomVersionId::*; + +use crate::{service::pdu::PduBuilder, Error, Result, Ruma}; + +/// # `GET /_matrix/federation/v1/make_knock/{roomId}/{userId}` +/// +/// Creates a knock template. +pub(crate) async fn create_knock_event_template_route( + State(services): State, body: Ruma, +) -> Result { + if !services.rooms.metadata.exists(&body.room_id).await { + return Err(Error::BadRequest(ErrorKind::NotFound, "Room is unknown to this server.")); + } + + if body.user_id.server_name() != body.origin() { + return Err(Error::BadRequest( + ErrorKind::InvalidParam, + "Not allowed to knock on behalf of another server/user", + )); + } + + // ACL check origin server + services + .rooms + .event_handler + .acl_check(body.origin(), &body.room_id) + .await?; + + if services + .globals + .config + .forbidden_remote_server_names + .contains(body.origin()) + { + warn!( + "Server {} for remote user {} tried knocking room ID {} which has a server name that is globally \ + forbidden. Rejecting.", + body.origin(), + &body.user_id, + &body.room_id, + ); + return Err!(Request(Forbidden("Server is banned on this homeserver."))); + } + + if let Some(server) = body.room_id.server_name() { + if services + .globals + .config + .forbidden_remote_server_names + .contains(&server.to_owned()) + { + return Err!(Request(Forbidden("Server is banned on this homeserver."))); + } + } + + let room_version_id = services.rooms.state.get_room_version(&body.room_id).await?; + + if matches!(room_version_id, V1 | V2 | V3 | V4 | V5 | V6) { + return Err(Error::BadRequest( + ErrorKind::IncompatibleRoomVersion { + room_version: room_version_id, + }, + "Room version does not support knocking.", + )); + } + + if !body.ver.contains(&room_version_id) { + return Err(Error::BadRequest( + ErrorKind::IncompatibleRoomVersion { + room_version: room_version_id, + }, + "Your homeserver does not support the features required to knock on this room.", + )); + } + + let state_lock = services.rooms.state.mutex.lock(&body.room_id).await; + + let (_pdu, mut pdu_json) = services + .rooms + .timeline + .create_hash_and_sign_event( + PduBuilder::state(body.user_id.to_string(), &RoomMemberEventContent::new(MembershipState::Knock)), + &body.user_id, + &body.room_id, + &state_lock, + ) + .await?; + + drop(state_lock); + + // room v3 and above removed the "event_id" field from remote PDU format + super::maybe_strip_event_id(&mut pdu_json, &room_version_id)?; + + Ok(create_knock_event_template::v1::Response { + room_version: room_version_id, + event: to_raw_value(&pdu_json).expect("CanonicalJson can be serialized to JSON"), + }) +} diff --git a/src/api/server/send_knock.rs b/src/api/server/send_knock.rs new file mode 100644 index 00000000..c57998ae --- /dev/null +++ b/src/api/server/send_knock.rs @@ -0,0 +1,190 @@ +use axum::extract::State; +use conduit::{err, pdu::gen_event_id_canonical_json, warn, Err, Error, PduEvent, Result}; +use ruma::{ + api::{client::error::ErrorKind, federation::knock::send_knock}, + events::{ + room::member::{MembershipState, RoomMemberEventContent}, + StateEventType, + }, + serde::JsonObject, + OwnedServerName, OwnedUserId, + RoomVersionId::*, +}; + +use crate::Ruma; + +/// # `PUT /_matrix/federation/v1/send_knock/{roomId}/{eventId}` +/// +/// Submits a signed knock event. +pub(crate) async fn create_knock_event_v1_route( + State(services): State, body: Ruma, +) -> Result { + if services + .globals + .config + .forbidden_remote_server_names + .contains(body.origin()) + { + warn!( + "Server {} tried knocking room ID {} who has a server name that is globally forbidden. Rejecting.", + body.origin(), + &body.room_id, + ); + return Err!(Request(Forbidden("Server is banned on this homeserver."))); + } + + if let Some(server) = body.room_id.server_name() { + if services + .globals + .config + .forbidden_remote_server_names + .contains(&server.to_owned()) + { + warn!( + "Server {} tried knocking room ID {} which has a server name that is globally forbidden. Rejecting.", + body.origin(), + &body.room_id, + ); + return Err!(Request(Forbidden("Server is banned on this homeserver."))); + } + } + + if !services.rooms.metadata.exists(&body.room_id).await { + return Err(Error::BadRequest(ErrorKind::NotFound, "Room is unknown to this server.")); + } + + // ACL check origin server + services + .rooms + .event_handler + .acl_check(body.origin(), &body.room_id) + .await?; + + let room_version_id = services.rooms.state.get_room_version(&body.room_id).await?; + + if matches!(room_version_id, V1 | V2 | V3 | V4 | V5 | V6) { + return Err!(Request(Forbidden("Room version does not support knocking."))); + } + + let Ok((event_id, value)) = gen_event_id_canonical_json(&body.pdu, &room_version_id) else { + // Event could not be converted to canonical json + return Err!(Request(InvalidParam("Could not convert event to canonical json."))); + }; + + let event_type: StateEventType = serde_json::from_value( + value + .get("type") + .ok_or_else(|| Error::BadRequest(ErrorKind::InvalidParam, "Event missing type property."))? + .clone() + .into(), + ) + .map_err(|_| Error::BadRequest(ErrorKind::InvalidParam, "Event has invalid event type."))?; + + if event_type != StateEventType::RoomMember { + return Err(Error::BadRequest( + ErrorKind::InvalidParam, + "Not allowed to send non-membership state event to knock endpoint.", + )); + } + + let content: RoomMemberEventContent = serde_json::from_value( + value + .get("content") + .ok_or_else(|| Error::BadRequest(ErrorKind::InvalidParam, "Event missing content property"))? + .clone() + .into(), + ) + .map_err(|_| Error::BadRequest(ErrorKind::InvalidParam, "Event content is empty or invalid"))?; + + if content.membership != MembershipState::Knock { + return Err(Error::BadRequest( + ErrorKind::InvalidParam, + "Not allowed to send a non-knock membership event to knock endpoint.", + )); + } + + // ACL check sender server name + let sender: OwnedUserId = serde_json::from_value( + value + .get("sender") + .ok_or_else(|| Error::BadRequest(ErrorKind::InvalidParam, "Event missing sender property."))? + .clone() + .into(), + ) + .map_err(|_| Error::BadRequest(ErrorKind::BadJson, "sender is not a valid user ID."))?; + + services + .rooms + .event_handler + .acl_check(sender.server_name(), &body.room_id) + .await?; + + // check if origin server is trying to send for another server + if sender.server_name() != body.origin() { + return Err(Error::BadRequest( + ErrorKind::InvalidParam, + "Not allowed to knock on behalf of another server.", + )); + } + + let state_key: OwnedUserId = serde_json::from_value( + value + .get("state_key") + .ok_or_else(|| Error::BadRequest(ErrorKind::InvalidParam, "Event missing state_key property."))? + .clone() + .into(), + ) + .map_err(|_| Error::BadRequest(ErrorKind::BadJson, "state_key is invalid or not a user ID."))?; + + if state_key != sender { + return Err(Error::BadRequest( + ErrorKind::InvalidParam, + "State key does not match sender user", + )); + }; + + let origin: OwnedServerName = serde_json::from_value( + serde_json::to_value( + value + .get("origin") + .ok_or_else(|| Error::BadRequest(ErrorKind::InvalidParam, "Event missing origin property."))?, + ) + .expect("CanonicalJson is valid json value"), + ) + .map_err(|_| Error::BadRequest(ErrorKind::InvalidParam, "origin is not a server name."))?; + + let mut event: JsonObject = serde_json::from_str(body.pdu.get()) + .map_err(|_| Error::BadRequest(ErrorKind::InvalidParam, "Invalid knock event PDU."))?; + + event.insert("event_id".to_owned(), "$placeholder".into()); + + let pdu: PduEvent = serde_json::from_value(event.into()) + .map_err(|_| Error::BadRequest(ErrorKind::InvalidParam, "Invalid knock event PDU."))?; + + let mutex_lock = services + .rooms + .event_handler + .mutex_federation + .lock(&body.room_id) + .await; + + let pdu_id = services + .rooms + .event_handler + .handle_incoming_pdu(&origin, &body.room_id, &event_id, value.clone(), true) + .await? + .ok_or_else(|| err!(Request(InvalidParam("Could not accept as timeline event."))))?; + + drop(mutex_lock); + + let knock_room_state = services.rooms.state.summary_stripped(&pdu).await; + + services + .sending + .send_pdu_room(&body.room_id, &pdu_id) + .await?; + + Ok(send_knock::v1::Response { + knock_room_state, + }) +} diff --git a/src/core/config/mod.rs b/src/core/config/mod.rs index eddab2fe..4bba1455 100644 --- a/src/core/config/mod.rs +++ b/src/core/config/mod.rs @@ -36,45 +36,51 @@ use crate::{err, error::Error, utils::sys, Result}; filename = "conduwuit-example.toml", section = "global", undocumented = "# This item is undocumented. Please contribute documentation for it.", - header = "### Conduwuit Configuration\n###\n### THIS FILE IS GENERATED. YOUR CHANGES WILL BE OVERWRITTEN!\n### \ - You should rename this file before configuring your server. Changes\n### to documentation and defaults \ - can be contributed in sourcecode at\n### src/core/config/mod.rs. This file is generated when \ - building.\n###\n", + header = "### conduwuit Configuration\n###\n### THIS FILE IS GENERATED. CHANGES/CONTRIBUTIONS IN THE REPO WILL\n### BE \ + OVERWRITTEN!\n###\n### You should rename this file before configuring your server. Changes\n### to \ + documentation and defaults can be contributed in source code at\n### src/core/config/mod.rs. This file \ + is generated when building.\n###\n### Any values pre-populated are the default values for said config \ + option.\n###\n### At the minimum, you MUST edit all the config options to your environment\n### that say \ + \"YOU NEED TO EDIT THIS\".\n### See https://conduwuit.puppyirl.gay/configuration.html for ways to\n### configure conduwuit\n", ignore = "catchall well_known tls" )] pub struct Config { /// The server_name is the pretty name of this server. It is used as a - /// suffix for user and room ids. Examples: matrix.org, conduit.rs + /// suffix for user and room IDs/aliases. /// - /// The Conduit server needs all /_matrix/ requests to be reachable at - /// https://your.server.name/ on port 443 (client-server) and 8448 (federation). + /// See the docs for reverse proxying and delegation: https://conduwuit.puppyirl.gay/deploying/generic.html#setting-up-the-reverse-proxy + /// Also see the `[global.well_known]` config section at the very bottom. /// - /// If that's not possible for you, you can create /.well-known files to - /// redirect requests (delegation). See - /// https://spec.matrix.org/latest/client-server-api/#getwell-knownmatrixclient - /// and - /// https://spec.matrix.org/v1.9/server-server-api/#getwell-knownmatrixserver - /// for more information. + /// Examples of delegation: + /// - https://puppygock.gay/.well-known/matrix/server + /// - https://puppygock.gay/.well-known/matrix/client /// - /// YOU NEED TO EDIT THIS + /// YOU NEED TO EDIT THIS. THIS CANNOT BE CHANGED AFTER WITHOUT A DATABASE + /// WIPE. + /// + /// example: "conduwuit.woof" pub server_name: OwnedServerName, - /// default address (IPv4 or IPv6) conduwuit will listen on. Generally you - /// want this to be localhost (127.0.0.1 / ::1). If you are using Docker or - /// a container NAT networking setup, you likely need this to be 0.0.0.0. - /// To listen multiple addresses, specify a vector e.g. ["127.0.0.1", "::1"] - /// Default if unspecified is both IPv4 and IPv6 localhost. + /// default address (IPv4 or IPv6) conduwuit will listen on. + /// + /// If you are using Docker or a container NAT networking setup, this must + /// be "0.0.0.0". + /// + /// To listen on multiple addresses, specify a vector e.g. ["127.0.0.1", + /// "::1"] /// /// default: ["127.0.0.1", "::1"] #[serde(default = "default_address")] address: ListeningAddr, - /// The port(s) conduwuit will be running on. You need to set up a reverse - /// proxy such as Caddy or Nginx so all requests to /_matrix on port 443 - /// and 8448 will be forwarded to the conduwuit instance running on this - /// port Docker users: Don't change this, you'll need to map an external - /// port to this. To listen on multiple ports, specify a vector e.g. [8080, - /// 8448] + /// The port(s) conduwuit will be running on. + /// + /// See https://conduwuit.puppyirl.gay/deploying/generic.html#setting-up-the-reverse-proxy for reverse proxying. + /// + /// Docker users: Don't change this, you'll need to map an external port to + /// this. + /// + /// To listen on multiple ports, specify a vector e.g. [8080, 8448] /// /// default: 8008 #[serde(default = "default_port")] @@ -84,108 +90,155 @@ pub struct Config { pub tls: Option, /// Uncomment unix_socket_path to listen on a UNIX socket at the specified - /// path. If listening on a UNIX socket, you must remove/comment the - /// 'address' key if defined and add your reverse proxy to the 'conduwuit' + /// path. If listening on a UNIX socket, you MUST remove/comment the + /// 'address' key if definedm AND add your reverse proxy to the 'conduwuit' /// group, unless world RW permissions are specified with unix_socket_perms /// (666 minimum). + /// + /// example: "/run/conduwuit/conduwuit.sock" pub unix_socket_path: Option, + /// The default permissions (in octal) to create the UNIX socket with. + /// /// default: 660 #[serde(default = "default_unix_socket_perms")] pub unix_socket_perms: u32, - /// Database backend: Only rocksdb is supported. - /// - /// default: rocksdb - #[serde(default = "default_database_backend")] - pub database_backend: String, - /// This is the only directory where conduwuit will save its data, including - /// media. Note: this was previously "/var/lib/matrix-conduit" + /// media. + /// Note: this was previously "/var/lib/matrix-conduit" + /// + /// YOU NEED TO EDIT THIS. + /// + /// example: "/var/lib/conduwuit" pub database_path: PathBuf, + /// conduwuit supports online database backups using RocksDB's Backup engine + /// API. To use this, set a database backup path that conduwuit can write + /// to. + /// + /// See https://conduwuit.puppyirl.gay/maintenance.html#backups for more information. + /// + /// example: "/opt/conduwuit-db-backups" pub database_backup_path: Option, + /// The amount of online RocksDB database backups to keep/retain, if using + /// "database_backup_path", before deleting the oldest one. + /// + /// default: 1 #[serde(default = "default_database_backups_to_keep")] pub database_backups_to_keep: i16, /// Set this to any float value in megabytes for conduwuit to tell the /// database engine that this much memory is available for database-related - /// caches. May be useful if you have significant memory to spare to - /// increase performance. + /// caches. /// - /// default: 256.0 + /// May be useful if you have significant memory to spare to increase + /// performance. + /// + /// Similar to the individual LRU caches, this is scaled up with your CPU + /// core count. + /// + /// This defaults to 128.0 + (64.0 * CPU core count) #[serde(default = "default_db_cache_capacity_mb")] pub db_cache_capacity_mb: f64, /// Option to control adding arbitrary text to the end of the user's /// displayname upon registration with a space before the text. This was the /// lightning bolt emoji option, just replaced with support for adding your - /// own custom text or emojis. To disable, set this to "" (an empty string) - /// Defaults to "🏳️⚧️" (trans pride flag) + /// own custom text or emojis. To disable, set this to "" (an empty string). /// - /// default: 🏳️⚧️ + /// The default is the trans pride flag. + /// + /// example: "🏳️⚧️" + /// + /// default: "🏳️⚧️" #[serde(default = "default_new_user_displayname_suffix")] pub new_user_displayname_suffix: String, /// If enabled, conduwuit will send a simple GET request periodically to /// `https://pupbrain.dev/check-for-updates/stable` for any new /// announcements made. Despite the name, this is not an update check - /// endpoint, it is simply an announcement check endpoint. Defaults to - /// false. + /// endpoint, it is simply an announcement check endpoint. + /// + /// This is disabled by default as this is rarely used except for security + /// updates or major updates. #[serde(default)] pub allow_check_for_updates: bool, - #[serde(default = "default_pdu_cache_capacity")] - pub pdu_cache_capacity: u32, - /// Set this to any float value to multiply conduwuit's in-memory LRU caches - /// with. May be useful if you have significant memory to spare to increase + /// with such as "auth_chain_cache_capacity". + /// + /// May be useful if you have significant memory to spare to increase /// performance. This was previously called /// `conduit_cache_capacity_modifier`. /// - /// default: 1.0. + /// If you have low memory, reducing this may be viable. + /// + /// By default, the individual caches such as "auth_chain_cache_capacity" + /// are scaled by your CPU core count. + /// + /// default: 1.0 #[serde(default = "default_cache_capacity_modifier", alias = "conduit_cache_capacity_modifier")] pub cache_capacity_modifier: f64, + /// default: varies by system + #[serde(default = "default_pdu_cache_capacity")] + pub pdu_cache_capacity: u32, + + /// default: varies by system #[serde(default = "default_auth_chain_cache_capacity")] pub auth_chain_cache_capacity: u32, + /// default: varies by system #[serde(default = "default_shorteventid_cache_capacity")] pub shorteventid_cache_capacity: u32, + /// default: varies by system #[serde(default = "default_eventidshort_cache_capacity")] pub eventidshort_cache_capacity: u32, + /// default: varies by system #[serde(default = "default_shortstatekey_cache_capacity")] pub shortstatekey_cache_capacity: u32, + /// default: varies by system #[serde(default = "default_statekeyshort_cache_capacity")] pub statekeyshort_cache_capacity: u32, + /// default: varies by system #[serde(default = "default_server_visibility_cache_capacity")] pub server_visibility_cache_capacity: u32, + /// default: varies by system #[serde(default = "default_user_visibility_cache_capacity")] pub user_visibility_cache_capacity: u32, + /// default: varies by system #[serde(default = "default_stateinfo_cache_capacity")] pub stateinfo_cache_capacity: u32, + /// default: varies by system #[serde(default = "default_roomid_spacehierarchy_cache_capacity")] pub roomid_spacehierarchy_cache_capacity: u32, /// Maximum entries stored in DNS memory-cache. The size of an entry may /// vary so please take care if raising this value excessively. Only /// decrease this when using an external DNS cache. Please note - /// that systemd does *not* count as an external cache, even when configured - /// to do so. + /// that systemd-resolved does *not* count as an external cache, even when + /// configured to do so. + /// + /// default: 32768 #[serde(default = "default_dns_cache_entries")] pub dns_cache_entries: u32, /// Minimum time-to-live in seconds for entries in the DNS cache. The - /// default may appear high to most administrators; this is by design. Only - /// decrease this if you are using an external DNS cache. + /// default may appear high to most administrators; this is by design as the + /// majority of NXDOMAINs are correct for a long time (e.g. the server is no + /// longer running Matrix). Only decrease this if you are using an external + /// DNS cache. + /// + /// default_dns_min_ttl: 259200 #[serde(default = "default_dns_min_ttl")] pub dns_min_ttl: u64, @@ -195,16 +248,23 @@ pub struct Config { /// and aggressively cached rather than constantly rechecked. /// /// Defaults to 3 days as these are *very rarely* false negatives. + /// + /// default: 259200 #[serde(default = "default_dns_min_ttl_nxdomain")] pub dns_min_ttl_nxdomain: u64, /// Number of retries after a timeout. + /// + /// default: 10 #[serde(default = "default_dns_attempts")] pub dns_attempts: u16, /// The number of seconds to wait for a reply to a DNS query. Please note /// that recursive queries can take up to several seconds for some domains, - /// so this value should not be too low. + /// so this value should not be too low, especially on slower hardware or + /// resolvers. + /// + /// default: 10 #[serde(default = "default_dns_timeout")] pub dns_timeout: u64, @@ -223,8 +283,7 @@ pub struct Config { /// Enables using *only* TCP for querying your specified nameservers instead /// of UDP. /// - /// You very likely do *not* want this. hickory-resolver already falls back - /// to TCP on UDP errors. Defaults to false + /// If you are running conduwuit in a container environment, this config option may need to be enabled. See https://conduwuit.puppyirl.gay/troubleshooting.html#potential-dns-issues-when-using-docker for more details. #[serde(default)] pub query_over_tcp_only: bool, @@ -232,30 +291,34 @@ pub struct Config { /// /// Takes a number of one of the following options: /// 1 - Ipv4Only (Only query for A records, no AAAA/IPv6) + /// /// 2 - Ipv6Only (Only query for AAAA records, no A/IPv4) + /// /// 3 - Ipv4AndIpv6 (Query for A and AAAA records in parallel, uses whatever - /// returns a successful response first) 4 - Ipv6thenIpv4 (Query for AAAA - /// record, if that fails then query the A record) 5 - Ipv4thenIpv6 (Query - /// for A record, if that fails then query the AAAA record) + /// returns a successful response first) /// - /// If you don't have IPv6 networking, then for better performance it may be - /// suitable to set this to Ipv4Only (1) as you will never ever use the - /// AAAA record contents even if the AAAA record is successful instead of - /// the A record. + /// 4 - Ipv6thenIpv4 (Query for AAAA record, if that fails then query the A + /// record) /// - /// Defaults to 5 - Ipv4ThenIpv6 as this is the most compatible and IPv4 - /// networking is currently the most prevalent. + /// 5 - Ipv4thenIpv6 (Query for A record, if that fails then query the AAAA + /// record) + /// + /// If you don't have IPv6 networking, then for better DNS performance it + /// may be suitable to set this to Ipv4Only (1) as you will never ever use + /// the AAAA record contents even if the AAAA record is successful instead + /// of the A record. /// /// default: 5 #[serde(default = "default_ip_lookup_strategy")] pub ip_lookup_strategy: u8, - /// Max request size for file uploads + /// Max request size for file uploads in bytes. Defaults to 20MB. /// /// default: 20971520 #[serde(default = "default_max_request_size")] pub max_request_size: usize, + /// default: 192 #[serde(default = "default_max_fetch_prev_events")] pub max_fetch_prev_events: u16, @@ -365,7 +428,7 @@ pub struct Config { /// Notification gateway pusher idle connection pool timeout /// - /// Defaults to 15 seconds + /// default: 15 #[serde(default = "default_pusher_idle_timeout")] pub pusher_idle_timeout: u64, @@ -373,7 +436,7 @@ pub struct Config { /// server. /// /// If set to true without a token configured, users can register with no - /// form of 2nd- step only if you set + /// form of 2nd-step only if you set /// `yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse` to /// true in your config. /// @@ -387,21 +450,27 @@ pub struct Config { /// A static registration token that new users will have to provide when /// creating an account. If unset and `allow_registration` is true, - /// registration is open without any condition. YOU NEED TO EDIT THIS. + /// registration is open without any condition. + /// + /// YOU NEED TO EDIT THIS OR USE registration_token_file. + /// + /// example: "o&^uCtes4HPf0Vu@F20jQeeWE7" pub registration_token: Option, - /// Path to a file on the system that gets read for the registration token + /// Path to a file on the system that gets read for the registration token. + /// this config option takes precedence/priority over "registration_token". /// /// conduwuit must be able to access the file, and it must not be empty /// - /// no default + /// example: "/etc/conduwuit/.reg_token" pub registration_token_file: Option, /// Controls whether encrypted rooms and events are allowed. #[serde(default = "true_fn")] pub allow_encryption: bool, - /// Controls whether federation is allowed or not. + /// Controls whether federation is allowed or not. It is not recommended to + /// disable this after the fact due to potential federation breakage. #[serde(default = "true_fn")] pub allow_federation: bool, @@ -433,25 +502,25 @@ pub struct Config { /// allow guests/unauthenticated users to access TURN credentials /// /// this is the equivalent of Synapse's `turn_allow_guests` config option. - /// this allows any unauthenticated user to call + /// this allows any unauthenticated user to call the endpoint /// `/_matrix/client/v3/voip/turnServer`. /// - /// defaults to false + /// It is unlikely you need to enable this as all major clients support + /// authentication for this endpoint and prevents misuse of your TURN server + /// from potential bots. #[serde(default)] pub turn_allow_guests: bool, /// Set this to true to lock down your server's public room directory and /// only allow admins to publish rooms to the room directory. Unpublishing /// is still allowed by all users with this enabled. - /// - /// Defaults to false #[serde(default)] pub lockdown_public_room_directory: bool, /// Set this to true to allow federating device display names / allow /// external users to see your device display name. If federation is /// disabled entirely (`allow_federation`), this is inherently false. For - /// privacy, this is best disabled. + /// privacy reasons, this is best left disabled. #[serde(default)] pub allow_device_name_federation: bool, @@ -464,25 +533,29 @@ pub struct Config { /// try to invite you to a DM or room. Also can protect against profile /// spiders. /// - /// Defaults to true. - /// /// This is inherently false if `allow_federation` is disabled #[serde(default = "true_fn", alias = "allow_profile_lookup_federation_requests")] pub allow_inbound_profile_lookup_federation_requests: bool, - /// controls whether users are allowed to create rooms. - /// appservices and admins are always allowed to create rooms - /// defaults to true + /// controls whether standard users are allowed to create rooms. appservices + /// and admins are always allowed to create rooms #[serde(default = "true_fn")] pub allow_room_creation: bool, /// Set to false to disable users from joining or creating room versions /// that aren't 100% officially supported by conduwuit. - /// conduwuit officially supports room versions 6 - 10. conduwuit has - /// experimental/unstable support for 3 - 5, and 11. Defaults to true. + /// + /// conduwuit officially supports room versions 6 - 11. + /// + /// conduwuit has slightly experimental (though works fine in practice) + /// support for versions 3 - 5 #[serde(default = "true_fn")] pub allow_unstable_room_versions: bool, + /// default room version conduwuit will create rooms with. + /// + /// per spec, room version 10 is the default. + /// /// default: 10 #[serde(default = "default_default_room_version")] pub default_room_version: RoomVersionId, @@ -498,10 +571,12 @@ pub struct Config { #[serde(default = "default_jaeger_filter")] pub jaeger_filter: String, - /// If the 'perf_measurements' feature is enabled, enables collecting folded - /// stack trace profile of tracing spans using tracing_flame. The resulting - /// profile can be visualized with inferno[1], speedscope[2], or a number of - /// other tools. [1]: https://github.com/jonhoo/inferno + /// If the 'perf_measurements' compile-time feature is enabled, enables + /// collecting folded stack trace profile of tracing spans using + /// tracing_flame. The resulting profile can be visualized with inferno[1], + /// speedscope[2], or a number of other tools. + /// + /// [1]: https://github.com/jonhoo/inferno /// [2]: www.speedscope.app #[serde(default)] pub tracing_flame: bool, @@ -546,8 +621,10 @@ pub struct Config { /// Servers listed here will be used to gather public keys of other servers /// (notary trusted key servers). /// - /// (Currently, conduwuit doesn't support batched key requests, so this list - /// should only contain other Synapse servers) Defaults to `matrix.org` + /// Currently, conduwuit doesn't support inbound batched key requests, so + /// this list should only contain other Synapse servers + /// + /// example: ["matrix.org", "constellatory.net", "tchncs.de"] /// /// default: ["matrix.org"] #[serde(default = "default_trusted_servers")] @@ -556,9 +633,10 @@ pub struct Config { /// Whether to query the servers listed in trusted_servers first or query /// the origin server first. For best security, querying the origin server /// first is advised to minimize the exposure to a compromised trusted - /// server. For maximum performance this can be set to true, however other - /// options exist to query trusted servers first under specific high-load - /// circumstances and should be evaluated before setting this to true. + /// server. For maximum federation/join performance this can be set to true, + /// however other options exist to query trusted servers first under + /// specific high-load circumstances and should be evaluated before setting + /// this to true. #[serde(default)] pub query_trusted_key_servers_first: bool, @@ -582,7 +660,7 @@ pub struct Config { #[serde(default)] pub only_query_trusted_key_servers: bool, - /// Maximum number of keys to request in each trusted server query. + /// Maximum number of keys to request in each trusted server batch query. /// /// default: 1024 #[serde(default = "default_trusted_server_batch_size")] @@ -590,6 +668,7 @@ pub struct Config { /// max log level for conduwuit. allows debug, info, warn, or error /// see also: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives + /// /// **Caveat**: /// For release builds, the tracing crate is configured to only implement /// levels higher than error to avoid unnecessary overhead in the compiled @@ -601,8 +680,6 @@ pub struct Config { pub log: String, /// controls whether logs will be outputted with ANSI colours - /// - /// default: true #[serde(default = "true_fn", alias = "log_colours")] pub log_colors: bool, @@ -615,40 +692,43 @@ pub struct Config { /// OpenID token expiration/TTL in seconds /// /// These are the OpenID tokens that are primarily used for Matrix account - /// integrations, *not* OIDC/OpenID Connect/etc + /// integrations (e.g. Vector Integrations in Element), *not* OIDC/OpenID + /// Connect/etc /// /// default: 3600 #[serde(default = "default_openid_token_ttl")] pub openid_token_ttl: u64, - /// TURN username to provide the client - /// - /// no default + /// static TURN username to provide the client if not using a shared secret + /// ("turn_secret"), It is recommended to use a shared secret over static + /// credentials. #[serde(default)] pub turn_username: String, - /// TURN password to provide the client - /// - /// no default + /// static TURN password to provide the client if not using a shared secret + /// ("turn_secret"). It is recommended to use a shared secret over static + /// credentials. #[serde(default)] pub turn_password: String, /// vector list of TURN URIs/servers to use /// /// replace "example.turn.uri" with your TURN domain, such as the coturn - /// "realm". if using TURN over TLS, replace "turn:" with "turns:" + /// "realm" config option. if using TURN over TLS, replace the URI prefix + /// "turn:" with "turns:" /// - /// No default - #[serde(default = "Vec::new")] + /// example: ["turn:example.turn.uri?transport=udp", + /// "turn:example.turn.uri?transport=tcp"] + /// + /// default: [] + #[serde(default)] pub turn_uris: Vec, /// TURN secret to use for generating the HMAC-SHA1 hash apart of username /// and password generation /// /// this is more secure, but if needed you can use traditional - /// username/password below. - /// - /// no default + /// static username/password credentials. #[serde(default)] pub turn_secret: String, @@ -657,7 +737,7 @@ pub struct Config { /// this takes priority over "turn_secret" first, and falls back to /// "turn_secret" if invalid or failed to open. /// - /// no default + /// example: "/etc/conduwuit/.turn_secret" pub turn_secret_file: Option, /// TURN TTL in seconds @@ -670,7 +750,10 @@ pub struct Config { /// registered users join. The rooms specified must be rooms that you /// have joined at least once on the server, and must be public. /// - /// No default. + /// example: ["#conduwuit:puppygock.gay", + /// "!eoIzvAvVwY23LPDay8:puppygock.gay"] + /// + /// default: [] #[serde(default = "Vec::new")] pub auto_join_rooms: Vec, @@ -695,15 +778,18 @@ pub struct Config { /// RocksDB log level. This is not the same as conduwuit's log level. This /// is the log level for the RocksDB engine/library which show up in your - /// database folder/path as `LOG` files. Defaults to error. conduwuit will - /// typically log RocksDB errors as normal. + /// database folder/path as `LOG` files. conduwuit will log RocksDB errors + /// as normal through tracing. + /// + /// default: "error" #[serde(default = "default_rocksdb_log_level")] pub rocksdb_log_level: String, #[serde(default)] pub rocksdb_log_stderr: bool, - /// Max RocksDB `LOG` file size before rotating in bytes. Defaults to 4MB. + /// Max RocksDB `LOG` file size before rotating in bytes. Defaults to 4MB in + /// bytes. /// /// default: 4194304 #[serde(default = "default_rocksdb_max_log_file_size")] @@ -727,13 +813,19 @@ pub struct Config { /// but it cannot account for all setups. If you experience any weird /// RocksDB issues, try enabling this option as it turns off Direct IO and /// feel free to report in the conduwuit Matrix room if this option fixes - /// your DB issues. See https://github.com/facebook/rocksdb/wiki/Direct-IO for more information. + /// your DB issues. + /// + /// See https://github.com/facebook/rocksdb/wiki/Direct-IO for more information. #[serde(default)] pub rocksdb_optimize_for_spinning_disks: bool, - /// Enables direct-io to increase database performance. This is enabled by - /// default. Set this option to false if the database resides on a - /// filesystem which does not support direct-io. + /// Enables direct-io to increase database performance via unbuffered I/O. + /// + /// See https://github.com/facebook/rocksdb/wiki/Direct-IO for more details about Direct IO and RocksDB. + /// + /// Set this option to false if the database resides on a filesystem which + /// does not support direct-io like FUSE, or any form of complex filesystem + /// setup such as possibly ZFS. #[serde(default = "true_fn")] pub rocksdb_direct_io: bool, @@ -746,14 +838,17 @@ pub struct Config { pub rocksdb_parallelism_threads: usize, /// Maximum number of LOG files RocksDB will keep. This must *not* be set to - /// 0. It must be at least 1. Defaults to 3 as these are not very useful. + /// 0. It must be at least 1. Defaults to 3 as these are not very useful + /// unless troubleshooting/debugging a RocksDB bug. /// /// default: 3 #[serde(default = "default_rocksdb_max_log_files")] pub rocksdb_max_log_files: usize, /// Type of RocksDB database compression to use. + /// /// Available options are "zstd", "zlib", "bz2", "lz4", or "none" + /// /// It is best to use ZSTD as an overall good balance between /// speed/performance, storage, IO amplification, and CPU usage. /// For more performance but less compression (more storage used) and less @@ -766,10 +861,14 @@ pub struct Config { pub rocksdb_compression_algo: String, /// Level of compression the specified compression algorithm for RocksDB to - /// use. Default is 32767, which is internally read by RocksDB as the + /// use. + /// + /// Default is 32767, which is internally read by RocksDB as the /// default magic number and translated to the library's default /// compression level as they all differ. /// See their `kDefaultCompressionLevel`. + /// + /// default: 32767 #[serde(default = "default_rocksdb_compression_level")] pub rocksdb_compression_level: i32, @@ -783,15 +882,19 @@ pub struct Config { /// it may be desirable to have a very high compression level here as it's /// lesss likely for this data to be used. Research your chosen compression /// algorithm. + /// + /// default: 32767 #[serde(default = "default_rocksdb_bottommost_compression_level")] pub rocksdb_bottommost_compression_level: i32, - /// Whether to enable RocksDB "bottommost_compression". + /// Whether to enable RocksDB's "bottommost_compression". + /// /// At the expense of more CPU usage, this will further compress the /// database to reduce more storage. It is recommended to use ZSTD - /// compression with this for best compression results. See https://github.com/facebook/rocksdb/wiki/Compression for more details. + /// compression with this for best compression results. This may be useful + /// if you're trying to reduce storage usage from the database. /// - /// Defaults to false as this uses more CPU when compressing. + /// See https://github.com/facebook/rocksdb/wiki/Compression for more details. #[serde(default)] pub rocksdb_bottommost_compression: bool, @@ -822,9 +925,9 @@ pub struct Config { /// 2 = PointInTime (use me if trying to recover) /// 3 = SkipAnyCorruptedRecord (you now voided your Conduwuit warranty) /// - /// See https://github.com/facebook/rocksdb/wiki/WAL-Recovery-Modes for more information + /// See https://github.com/facebook/rocksdb/wiki/WAL-Recovery-Modes for more information on these modes. /// - /// Defaults to 1 (TolerateCorruptedTailRecords) + /// See https://conduwuit.puppyirl.gay/troubleshooting.html#database-corruption for more details on recovering a corrupt database. /// /// default: 1 #[serde(default = "default_rocksdb_recovery_mode")] @@ -841,6 +944,8 @@ pub struct Config { /// repair. /// - Disabling repair mode and restarting the server is recommended after /// running the repair. + /// + /// See https://conduwuit.puppyirl.gay/troubleshooting.html#database-corruption for more details on recovering a corrupt database. #[serde(default)] pub rocksdb_repair: bool, @@ -862,6 +967,14 @@ pub struct Config { #[serde(default = "true_fn")] pub rocksdb_compaction_ioprio_idle: bool, + /// Config option to disable RocksDB compaction. You should never ever have + /// to disable this. If you for some reason find yourself needing to disable + /// this as part of troubleshooting or a bug, please reach out to us in the + /// conduwuit Matrix room with information and details. + /// + /// Disabling compaction will lead to a significantly bloated and + /// explosively large database, gradually poor performance, unnecessarily + /// excessive disk read/writes, and slower shutdowns and startups. #[serde(default = "true_fn")] pub rocksdb_compaction: bool, @@ -876,33 +989,45 @@ pub struct Config { /// 3 to 5 = Statistics with possible performance impact. /// 6 = All statistics. /// - /// Defaults to 1 (No statistics, except in debug-mode) - /// /// default: 1 #[serde(default = "default_rocksdb_stats_level")] pub rocksdb_stats_level: u8, + /// This is a password that can be configured that will let you login to the + /// server bot account (currently `@conduit`) for emergency troubleshooting + /// purposes such as recovering/recreating your admin room, or inviting + /// yourself back. + /// + /// See https://conduwuit.puppyirl.gay/troubleshooting.html#lost-access-to-admin-room for other ways to get back into your admin room. + /// + /// Once this password is unset, all sessions will be logged out for + /// security purposes. + /// + /// example: "F670$2CP@Hw8mG7RY1$%!#Ic7YA" pub emergency_password: Option, + /// default: "/_matrix/push/v1/notify" #[serde(default = "default_notification_push_path")] pub notification_push_path: String, /// Config option to control local (your server only) presence - /// updates/requests. Defaults to true. Note that presence on conduwuit is + /// updates/requests. Note that presence on conduwuit is /// very fast unlike Synapse's. If using outgoing presence, this MUST be /// enabled. #[serde(default = "true_fn")] pub allow_local_presence: bool, /// Config option to control incoming federated presence updates/requests. - /// Defaults to true. This option receives presence updates from other + /// + /// This option receives presence updates from other /// servers, but does not send any unless `allow_outgoing_presence` is true. /// Note that presence on conduwuit is very fast unlike Synapse's. #[serde(default = "true_fn")] pub allow_incoming_presence: bool, - /// Config option to control outgoing presence updates/requests. Defaults to - /// true. This option sends presence updates to other servers, but does not + /// Config option to control outgoing presence updates/requests. + /// + /// This option sends presence updates to other servers, but does not /// receive any unless `allow_incoming_presence` is true. /// Note that presence on conduwuit is very fast unlike Synapse's. /// If using outgoing presence, you MUST enable `allow_local_presence` as @@ -986,6 +1111,9 @@ pub struct Config { /// compression may weaken TLS. Most users should not need to enable this. /// See https://breachattack.com/ and https://wikipedia.org/wiki/BREACH before /// deciding to enable this. + /// + /// If you are in a large amount of rooms, you may find that enabling this + /// is necessary to reduce the significantly large response bodies. #[serde(default)] pub gzip_compression: bool, @@ -998,18 +1126,18 @@ pub struct Config { #[serde(default)] pub brotli_compression: bool, - /// Set to true to allow user type "guest" registrations. Element attempts - /// to register guest users automatically. Defaults to false. + /// Set to true to allow user type "guest" registrations. Some clients like + /// Element attempt to register guest users automatically. #[serde(default)] pub allow_guest_registration: bool, - /// Set to true to log guest registrations in the admin room. - /// Defaults to false as it may be noisy or unnecessary. + /// Set to true to log guest registrations in the admin room. Note that + /// these may be noisy or unnecessary if you're a public homeserver. #[serde(default)] pub log_guest_registrations: bool, /// Set to true to allow guest registrations/users to auto join any rooms - /// specified in `auto_join_rooms` Defaults to false. + /// specified in `auto_join_rooms`. #[serde(default)] pub allow_guests_auto_join_rooms: bool, @@ -1033,7 +1161,7 @@ pub struct Config { /// Checks consistency of the media directory at startup: /// 1. When `media_compat_file_link` is enbled, this check will upgrade - /// media when switching back and forth between Conduit and Conduwuit. + /// media when switching back and forth between Conduit and conduwuit. /// Both options must be enabled to handle this. /// 2. When media is deleted from the directory, this check will also delete /// its database entry. @@ -1041,8 +1169,6 @@ pub struct Config { /// If none of these checks apply to your use cases, and your media /// directory is significantly large setting this to false may reduce /// startup time. - /// - /// Enabled by default. #[serde(default = "true_fn")] pub media_startup_check: bool, @@ -1051,9 +1177,9 @@ pub struct Config { /// Conduit again. Otherwise setting this to false reduces filesystem /// clutter and overhead for managing these symlinks in the directory. This /// is now disabled by default. You may still return to upstream Conduit - /// but you have to run Conduwuit at least once with this set to true and + /// but you have to run conduwuit at least once with this set to true and /// allow the media_startup_check to take place before shutting - /// down to return to Conduit. Disabled by default. + /// down to return to Conduit. #[serde(default)] pub media_compat_file_link: bool, @@ -1061,14 +1187,16 @@ pub struct Config { /// checks. This means if you delete files from the media directory the /// corresponding entries will be removed from the database. This is /// disabled by default because if the media directory is accidentally moved - /// or inaccessible the metadata entries in the database will be lost with - /// sadness. Disabled by default. + /// or inaccessible, the metadata entries in the database will be lost with + /// sadness. #[serde(default)] pub prune_missing_media: bool, /// Vector list of servers that conduwuit will refuse to download remote - /// media from. No default. - #[serde(default = "HashSet::new")] + /// media from. + /// + /// default: [] + #[serde(default)] pub prevent_media_downloads_from: HashSet, /// List of forbidden server names that we will block incoming AND outgoing @@ -1078,13 +1206,17 @@ pub struct Config { /// sender user's server name, inbound federation X-Matrix origin, and /// outbound federation handler. /// - /// Basically "global" ACLs. No default. - #[serde(default = "HashSet::new")] + /// Basically "global" ACLs. + /// + /// default: [] + #[serde(default)] pub forbidden_remote_server_names: HashSet, /// List of forbidden server names that we will block all outgoing federated /// room directory requests for. Useful for preventing our users from - /// wandering into bad servers or spaces. No default. + /// wandering into bad servers or spaces. + /// + /// default: [] #[serde(default = "HashSet::new")] pub forbidden_remote_room_directory_server_names: HashSet, @@ -1100,28 +1232,12 @@ pub struct Config { /// Currently this does not account for proxies in use like Synapse does. /// /// To disable, set this to be an empty vector (`[]`). - /// The default is: - /// [ - /// "127.0.0.0/8", - /// "10.0.0.0/8", - /// "172.16.0.0/12", - /// "192.168.0.0/16", - /// "100.64.0.0/10", - /// "192.0.0.0/24", - /// "169.254.0.0/16", - /// "192.88.99.0/24", - /// "198.18.0.0/15", - /// "192.0.2.0/24", - /// "198.51.100.0/24", - /// "203.0.113.0/24", - /// "224.0.0.0/4", - /// "::1/128", - /// "fe80::/10", - /// "fc00::/7", - /// "2001:db8::/32", - /// "ff00::/8", - /// "fec0::/10", - /// ] + /// + /// default: ["127.0.0.0/8", "10.0.0.0/8", "172.16.0.0/12", + /// "192.168.0.0/16", "100.64.0.0/10", "192.0.0.0/24", "169.254.0.0/16", + /// "192.88.99.0/24", "198.18.0.0/15", "192.0.2.0/24", "198.51.100.0/24", + /// "203.0.113.0/24", "224.0.0.0/4", "::1/128", "fe80::/10", "fc00::/7", + /// "2001:db8::/32", "ff00::/8", "fec0::/10"] #[serde(default = "default_ip_range_denylist")] pub ip_range_denylist: Vec, @@ -1132,7 +1248,9 @@ pub struct Config { /// allow all URL previews. Please note that this opens up significant /// attack surface to your server, you are expected to be aware of the /// risks by doing so. - #[serde(default = "Vec::new")] + /// + /// default: [] + #[serde(default)] pub url_preview_domain_contains_allowlist: Vec, /// Vector list of explicit domains allowed to send requests to for URL @@ -1143,7 +1261,9 @@ pub struct Config { /// allow all URL previews. Please note that this opens up significant /// attack surface to your server, you are expected to be aware of the /// risks by doing so. - #[serde(default = "Vec::new")] + /// + /// default: [] + #[serde(default)] pub url_preview_domain_explicit_allowlist: Vec, /// Vector list of explicit domains not allowed to send requests to for URL @@ -1152,7 +1272,9 @@ pub struct Config { /// "http://google.com", but not /// "https://mymaliciousdomainexamplegoogle.com". The denylist is checked /// first before allowlist. Setting this to "*" will not do anything. - #[serde(default = "Vec::new")] + /// + /// default: [] + #[serde(default)] pub url_preview_domain_explicit_denylist: Vec, /// Vector list of URLs allowed to send requests to for URL previews. @@ -1164,19 +1286,23 @@ pub struct Config { /// "*" will allow all URL previews. Please note that this opens up /// significant attack surface to your server, you are expected to be /// aware of the risks by doing so. - #[serde(default = "Vec::new")] + /// + /// default: [] + #[serde(default)] pub url_preview_url_contains_allowlist: Vec, /// Maximum amount of bytes allowed in a URL preview body size when - /// spidering. Defaults to 384KB. + /// spidering. Defaults to 384KB in bytes. /// - /// defaukt: 384000 + /// default: 384000 #[serde(default = "default_url_preview_max_spider_size")] pub url_preview_max_spider_size: usize, /// Option to decide whether you would like to run the domain allowlist /// checks (contains and explicit) on the root domain or not. Does not apply - /// to URL contains allowlist. Defaults to false. Example: If this is + /// to URL contains allowlist. Defaults to false. + /// + /// Example usecase: If this is /// enabled and you have "wikipedia.org" allowed in the explicit and/or /// contains domain allowlist, it will allow all subdomains under /// "wikipedia.org" such as "en.m.wikipedia.org" as the root domain is @@ -1186,21 +1312,36 @@ pub struct Config { #[serde(default)] pub url_preview_check_root_domain: bool, - /// List of forbidden room aliases and room IDs as patterns/strings. Values - /// in this list are matched as *contains*. This is checked upon room alias - /// creation, custom room ID creation if used, and startup as warnings if - /// any room aliases in your database have a forbidden room alias/ID. - /// No default. - #[serde(default = "RegexSet::empty")] + /// List of forbidden room aliases and room IDs as strings of regex + /// patterns. + /// + /// Regex can be used or explicit contains matches can be done by + /// just specifying the words (see example). + /// + /// This is checked upon room alias creation, custom room ID creation if + /// used, and startup as warnings if any room aliases in your database have + /// a forbidden room alias/ID. + /// + /// example: ["19dollarfortnitecards", "b[4a]droom"] + /// + /// default: [] + #[serde(default)] #[serde(with = "serde_regex")] pub forbidden_alias_names: RegexSet, - /// List of forbidden username patterns/strings. Values in this list are - /// matched as *contains*. This is checked upon username availability - /// check, registration, and startup as warnings if any local users in your - /// database have a forbidden username. - /// No default. - #[serde(default = "RegexSet::empty")] + /// List of forbidden username patterns/strings. + /// + /// Regex can be used or explicit contains matches can be done by just + /// specifying the words (see example). + /// + /// This is checked upon username availability check, registration, and + /// startup as warnings if any local users in your database have a forbidden + /// username. + /// + /// example: ["administrator", "b[a4]dusernam[3e]"] + /// + /// default: [] + #[serde(default)] #[serde(with = "serde_regex")] pub forbidden_usernames: RegexSet, @@ -1231,9 +1372,12 @@ pub struct Config { #[serde(default)] pub block_non_admin_invites: bool, - /// Allows admins to enter commands in rooms other than #admins by prefixing - /// with \!admin. The reply will be publicly visible to the room, - /// originating from the sender. + /// Allows admins to enter commands in rooms other than "#admins" (admin + /// room) by prefixing your message with "\!admin" or "\\!admin" followed + /// up a normal conduwuit admin command. The reply will be publicly visible + /// to the room, originating from the sender. + /// + /// example: \\!admin debug ping puppygock.gay #[serde(default = "true_fn")] pub admin_escape_commands: bool, @@ -1246,8 +1390,6 @@ pub struct Config { /// Controls what admin commands will be executed on startup. This is a /// vector list of strings of admin commands to run. /// - /// An example of this can be: `admin_execute = ["debug ping puppygock.gay", - /// "debug echo hi"]` /// /// This option can also be configured with the `--execute` conduwuit /// argument and can take standard shell commands and environment variables @@ -1255,6 +1397,8 @@ pub struct Config { /// Such example could be: `./conduwuit --execute "server admin-notice /// conduwuit has started up at $(date)"` /// + /// example: admin_execute = ["debug ping puppygock.gay", "debug echo hi"]` + /// /// default: [] #[serde(default)] pub admin_execute: Vec, @@ -1272,6 +1416,14 @@ pub struct Config { #[serde(default = "default_admin_log_capture")] pub admin_log_capture: String, + /// The default room tag to apply on the admin room. + /// + /// On some clients like Element, the room tag "m.server_notice" is a + /// special pinned room at the very bottom of your room list. The conduwuit + /// admin room can be pinned here so you always have an easy-to-access + /// shortcut dedicated to your admin room. + /// + /// default: "m.server_notice" #[serde(default = "default_admin_room_tag")] pub admin_room_tag: String, @@ -1283,12 +1435,11 @@ pub struct Config { /// Sentry reporting URL if a custom one is desired /// - /// Defaults to conduwuit's default Sentry endpoint: - /// "https://fe2eb4536aa04949e28eff3128d64757@o4506996327251968.ingest.us.sentry.io/4506996334657536" + /// default: "https://fe2eb4536aa04949e28eff3128d64757@o4506996327251968.ingest.us.sentry.io/4506996334657536" #[serde(default = "default_sentry_endpoint")] pub sentry_endpoint: Option, - /// Report your Conduwuit server_name in Sentry.io crash reports and metrics + /// Report your conduwuit server_name in Sentry.io crash reports and metrics #[serde(default)] pub sentry_send_server_name: bool, @@ -1307,7 +1458,8 @@ pub struct Config { pub sentry_attach_stacktrace: bool, /// Send panics to sentry. This is true by default, but sentry has to be - /// enabled. + /// enabled. The global "sentry" config option must be enabled to send any + /// data. #[serde(default = "true_fn")] pub sentry_send_panic: bool, @@ -1318,13 +1470,14 @@ pub struct Config { pub sentry_send_error: bool, /// Controls the tracing log level for Sentry to send things like - /// breadcrumbs and transactions Defaults to "info" + /// breadcrumbs and transactions + /// + /// default: "info" #[serde(default = "default_sentry_filter")] pub sentry_filter: String, /// Enable the tokio-console. This option is only relevant to developers. - /// See: docs/development.md#debugging-with-tokio-console for more - /// information. + /// See https://conduwuit.puppyirl.gay/development.html#debugging-with-tokio-console for more information. #[serde(default)] pub tokio_console: bool, @@ -1346,18 +1499,33 @@ pub struct Config { #[derive(Clone, Debug, Deserialize)] #[config_example_generator(filename = "conduwuit-example.toml", section = "global.tls")] pub struct TlsConfig { + /// Path to a valid TLS certificate file. + /// + /// example: "/path/to/my/certificate.crt" pub certs: String, + /// Path to a valid TLS certificate private key. + /// + /// example: "/path/to/my/certificate.key" pub key: String, - #[serde(default)] /// Whether to listen and allow for HTTP and HTTPS connections (insecure!) + #[serde(default)] pub dual_protocol: bool, } #[derive(Clone, Debug, Deserialize, Default)] #[config_example_generator(filename = "conduwuit-example.toml", section = "global.well_known")] pub struct WellKnownConfig { - pub client: Option, + /// The server base domain of the URL with a specific port that the server + /// well-known file will serve. This should contain a port at the end, and + /// should not be a URL. + /// + /// example: "matrix.example.com:443" pub server: Option, + /// The server URL that the client well-known file will serve. This should + /// not contain a port, and should just be a valid HTTPS URL. + /// + /// example: "https://matrix.example.com" + pub client: Option, pub support_page: Option, pub support_role: Option, pub support_email: Option, @@ -1460,7 +1628,6 @@ impl fmt::Display for Config { }; line("Server name", self.server_name.host()); - line("Database backend", &self.database_backend); line("Database path", &self.database_path.to_string_lossy()); line( "Database backup path", @@ -1861,8 +2028,6 @@ fn default_unix_socket_perms() -> u32 { 660 } fn default_database_backups_to_keep() -> i16 { 1 } -fn default_database_backend() -> String { "rocksdb".to_owned() } - fn default_db_cache_capacity_mb() -> f64 { 128.0 + parallelism_scaled_f64(64.0) } fn default_pdu_cache_capacity() -> u32 { parallelism_scaled_u32(10_000).saturating_add(100_000) } diff --git a/src/service/migrations.rs b/src/service/migrations.rs index d6c342f8..4c821fa3 100644 --- a/src/service/migrations.rs +++ b/src/service/migrations.rs @@ -59,7 +59,6 @@ pub(crate) async fn migrations(services: &Services) -> Result<()> { async fn fresh(services: &Services) -> Result<()> { let db = &services.db; - let config = &services.server.config; services .globals @@ -73,10 +72,7 @@ async fn fresh(services: &Services) -> Result<()> { // Create the admin room and server user on first run crate::admin::create_admin_room(services).boxed().await?; - warn!( - "Created new {} database with version {DATABASE_VERSION}", - config.database_backend, - ); + warn!("Created new RocksDB database with version {DATABASE_VERSION}"); Ok(()) } @@ -201,10 +197,7 @@ async fn migrate(services: &Services) -> Result<()> { } } - info!( - "Loaded {} database with schema version {DATABASE_VERSION}", - config.database_backend, - ); + info!("Loaded RocksDB database with schema version {DATABASE_VERSION}"); Ok(()) }