warp/Warp
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b50775317230ec8d13b89d36196446be7d777713
Warp/docs/configuration.md
T
tajniak81andClaude Opus 5.5 b507753172 Phase 8: push and notifications 
Implements PLAN.md Phase 8. internal/pushrules is the rule language: the
spec's default ruleset, all six condition kinds, glob and word-boundary
matching, intentional mentions switching off the legacy body rules, and
rule ordering as Synapse has it. internal/pushserver keeps the rules,
pushers and notifications and talks to push gateways.

Push rules are the m.push_rules account data, written only by the push
server; reads keep the user's own rules and the enabled/actions of each
default and take the rest from the current defaults, so new default rules
reach every user without a migration. PUT account_data/m.push_rules is
refused with 405.

The push server listens on the roomserver's emit stage and evaluates each
event on its own worker for every local member and an invite's target.
Notifications and per-room unread counts are stored in migration 0010;
counts are a seventh sync token stream, so /sync reports
unread_notifications and picks up count changes made after the event or by
a receipt from another device. m.read and m.read.private receipts clear
the counts; leaving a room clears it.

Pushers (http kind only) push through a bounded sender pool with retries,
honour event_id_only, drop push keys the gateway rejects, and go away with
their device. GET /notifications pages the history. New config section
push: enabled, include_content, gateway_timeout, notification_retention.

Account data writes now wake the user's blocked syncs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 11:43:36 +02:00

206 lines
13 KiB
Markdown
Raw Blame History

# Configuration
Warp reads one YAML file. Every setting can also come from the
environment, and the environment wins. With no file at all the defaults
plus `WARP_*` variables are used, which is how the container image runs.
Where the file comes from, in order:
1. `--config <path>`
2. `$WARP_CONFIG`
3. `./warp.yaml`, if it exists
4. nothing — defaults and environment only
An unknown field is a fatal error. A typo in a security-relevant setting
must not be ignored.
List-valued variables are comma-separated. A single `-` clears a list:
`WARP_CORS_ALLOWED_ORIGINS=-`.
## Settings
| YAML | Environment | Default | Notes |
|---|---|---|---|
| `global.server_name` | `WARP_SERVER_NAME` | — | Required. Part of every ID; cannot be changed later. |
| `global.private_key` | `WARP_PRIVATE_KEY` | `./keys/signing.key` | Written by `warp generate-keys`. |
| `global.well_known.client_base_url` | `WARP_WELL_KNOWN_CLIENT_BASE_URL` | `https://<server_name>` | Advertised to clients. |
| `global.well_known.identity_server_base_url` | `WARP_WELL_KNOWN_IDENTITY_SERVER_BASE_URL` | empty | Omitted from the document when empty. |
| `global.well_known.server_address` | `WARP_WELL_KNOWN_SERVER_ADDRESS` | empty | `host:port` for other homeservers. Empty = no delegation, other servers fall back to SRV/A. |
| `listen.address` | `WARP_LISTEN_ADDRESS` | `:8008` | |
| `listen.read_header_timeout` | `WARP_READ_HEADER_TIMEOUT` | `10s` | |
| `listen.read_timeout` | `WARP_READ_TIMEOUT` | `60s` | |
| `listen.write_timeout` | `WARP_WRITE_TIMEOUT` | `120s` | Must stay above `sync.long_poll_timeout`, or a blocked `/sync` is cut off before it can answer. |
| `listen.idle_timeout` | `WARP_IDLE_TIMEOUT` | `120s` | |
| `listen.max_header_bytes` | `WARP_MAX_HEADER_BYTES` | `1048576` | |
| `listen.shutdown_timeout` | `WARP_SHUTDOWN_TIMEOUT` | `30s` | Grace period for in-flight requests. |
| `listen.federation_address` | `WARP_LISTEN_FEDERATION_ADDRESS` | empty | A second listener serving the same API over TLS, usually `:8448`. Empty = none; see *Federation over TLS*. |
| `listen.tls_cert_file` | `WARP_TLS_CERT_FILE` | empty | PEM certificate chain for the federation listener. Required with it. |
| `listen.tls_key_file` | `WARP_TLS_KEY_FILE` | empty | PEM key for the federation listener. Required with it. |
| `database.driver` | `WARP_DB_DRIVER` | `sqlite` | `sqlite`, `postgres`, `pocketbase` (not implemented). |
| `database.connection_string` | `WARP_DB_CONNECTION_STRING` | SQLite file in the working directory | |
| `database.max_open_conns` | `WARP_DB_MAX_OPEN_CONNS` | `10` | Ignored by SQLite: writes are serialised onto one connection. |
| `database.max_idle_conns` | `WARP_DB_MAX_IDLE_CONNS` | `5` | |
| `database.conn_max_lifetime` | `WARP_DB_CONN_MAX_LIFETIME` | `1h` | |
| `database.auto_migrate` | `WARP_DB_AUTO_MIGRATE` | `true` | `false` makes startup fail while migrations are pending. |
| `client_api.cors_allowed_origins` | `WARP_CORS_ALLOWED_ORIGINS` | `["*"]` | The spec expects any origin. |
| `client_api.trust_x_forwarded_for` | `WARP_TRUST_X_FORWARDED_FOR` | `false` | Only behind a proxy that overwrites the header; the rate limiter keys on the result. |
| `client_api.access_token_lifetime` | `WARP_ACCESS_TOKEN_LIFETIME` | `0s` | `0` = never expire. With a lifetime, clients may ask for a refresh token at login. |
| `client_api.refresh_token_lifetime` | `WARP_REFRESH_TOKEN_LIFETIME` | `0s` | `0` = never expire. |
| `client_api.rate_limit.enabled` | `WARP_RATE_LIMIT_ENABLED` | `true` | |
| `client_api.rate_limit.default.burst` / `.interval` | — | `30` / `100ms` | Every rate-limited endpoint without its own bucket. |
| `client_api.rate_limit.login.burst` / `.interval` | — | `10` / `1s` | `/login` and `/refresh`. |
| `client_api.rate_limit.register.burst` / `.interval` | — | `5` / `2s` | `/register` and `/register/available`. |
| `client_api.rate_limit.room_create.burst` / `.interval` | — | `10` / `1s` | `/createRoom`, which writes a dozen events per call. |
| `client_api.rate_limit.join.burst` / `.interval` | — | `10` / `1s` | The two join endpoints. |
| `client_api.rate_limit.sync.burst` / `.interval` | — | `100` / `20ms` | `/sync` and the writes behind it: typing, receipts, to-device, presence. |
| `client_api.rate_limit.media.burst` / `.interval` | — | `100` / `20ms` | Media downloads and thumbnails: a client opening a room asks for every avatar at once. Uploads are in the default bucket. |
| `sync.presence` | `WARP_SYNC_PRESENCE` | `false` | Off by default; see below. |
| `sync.typing_timeout` | `WARP_SYNC_TYPING_TIMEOUT` | `30s` | How long a typing notification lasts, and the cap on what a client may ask for. |
| `sync.long_poll_timeout` | `WARP_SYNC_LONG_POLL_TIMEOUT` | `30s` | The cap on a `/sync` `?timeout=`. |
| `federation.enabled` | `WARP_FEDERATION_ENABLED` | `false` | |
| `federation.allowlist` | `WARP_FEDERATION_ALLOWLIST` | `[]` | Non-empty = federate only with these. |
| `federation.denylist` | `WARP_FEDERATION_DENYLIST` | `[]` | Always wins over the allowlist. |
| `federation.allow_runtime_toggle` | `WARP_FEDERATION_ALLOW_RUNTIME_TOGGLE` | `true` | See below. |
| `federation.trusted_key_servers` | `WARP_FEDERATION_TRUSTED_KEY_SERVERS` | `[]` | Notaries asked for a server's key when it cannot be reached itself, e.g. `matrix.org`. Empty = only ever ask the server. |
| `federation.key_validity_period` | `WARP_FEDERATION_KEY_VALIDITY_PERIOD` | `24h` | How long other servers may cache this server's key. At most `168h`. |
| `federation.tls_ca_file` | `WARP_FEDERATION_TLS_CA_FILE` | empty | Extra CA certificates (PEM) for outbound federation, on top of the system roots. |
| `media.base_path` | `WARP_MEDIA_BASE_PATH` | `./media_store` | Where media content is kept. Created on the first upload. |
| `media.max_upload_bytes` | `WARP_MEDIA_MAX_UPLOAD_BYTES` | `52428800` | The largest upload (50 MiB), and the largest file fetched from another server. Reported to clients as `m.upload.size`. |
| `media.max_thumbnail_pixels` | `WARP_MEDIA_MAX_THUMBNAIL_PIXELS` | `32000000` | The largest image, in pixels, decoded to make a thumbnail. |
| `media.thumbnail_sizes` | — | five sizes, see [media.md](media.md) | The thumbnails this server makes, as `{width, height, method}`. Empty = no thumbnails. |
| `media.pending_upload_expiry` | `WARP_MEDIA_PENDING_UPLOAD_EXPIRY` | `24h` | How long an ID reserved with `POST /media/v1/create` waits for its content. |
| `media.max_pending_uploads` | `WARP_MEDIA_MAX_PENDING_UPLOADS` | `10` | How many of those one user may hold. |
| `media.legacy_unauthenticated_downloads` | `WARP_MEDIA_LEGACY_UNAUTHENTICATED_DOWNLOADS` | `false` | Also serve the deprecated `/_matrix/media/v3/download` and `/thumbnail`, which need no token. Only for clients older than Matrix 1.11. |
| `push.enabled` | `WARP_PUSH_ENABLED` | `true` | Send pushes to the push gateways of users' pushers. Off, notifications are still counted. |
| `push.include_content` | `WARP_PUSH_INCLUDE_CONTENT` | `true` | Put the event's content into a push. Off, a push carries no message text. |
| `push.gateway_timeout` | `WARP_PUSH_GATEWAY_TIMEOUT` | `10s` | One request to a push gateway. |
| `push.notification_retention` | `WARP_PUSH_NOTIFICATION_RETENTION` | `720h` | How long a read notification is kept for `GET /notifications`. Unread ones are kept until read. |
| `registration.enabled` | `WARP_REGISTRATION_ENABLED` | `false` | |
| `registration.allow_runtime_toggle` | `WARP_REGISTRATION_ALLOW_RUNTIME_TOGGLE` | `true` | |
| `registration.tokens` | `WARP_REGISTRATION_TOKENS` | `[]` | Non-empty = sign-up also needs one of these, as the `m.login.registration_token` stage. |
| `logging.level` | `WARP_LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error`. |
| `logging.format` | `WARP_LOG_FORMAT` | `text` | `text` or `json`. |
| `logging.add_source` | `WARP_LOG_ADD_SOURCE` | `false` | File and line in every record. |
| `metrics.enabled` | `WARP_METRICS_ENABLED` | `true` | |
| `metrics.path` | `WARP_METRICS_PATH` | `/metrics` | Served on the same listener. |
The rate limit buckets share one Go type, so per-bucket environment
variables would all collide on the same name; they are YAML only.
`WARP_RATE_LIMIT_ENABLED=false` turns the whole limiter off, which is what a
test harness wants.
## Rate limiting
Each bucket allows `burst` requests back to back and returns one slot every
`interval`, keyed per client address. Over the limit is
`429 M_LIMIT_EXCEEDED` with a `retry_after_ms` the client is expected to
honour.
Buckets are per endpoint class, so a client hammering `/login` cannot spend
the budget of `/profile`. The key is the client address and not the user,
because the limiter runs before the access token is resolved — a limiter
that had to query the database to find its own key would be a denial of
service of its own. Behind a reverse proxy, set
`client_api.trust_x_forwarded_for: true`, or every client shares one bucket.
The admin API under `/_warp/admin/v1` is not rate limited: it needs an admin
token, and bulk operations from the panel are exactly the traffic a limiter
would get in the way of.
## Presence
`sync.presence` is off by default. Presence — who is online, and the status
message they set — is the noisiest thing in Matrix: every user's state
change is published to everybody they share a room with, which over
federation is quadratic in the worst case. Synapse deployments routinely
turn it off for that reason, and a private homeserver with a dozen users
gains little from it.
With it off:
- `GET` and `PUT /presence/{userId}/status` answer `403 M_FORBIDDEN`. They
are deliberately not unregistered: a client that gets a 404 from
`/presence` concludes the server is too old to have it and stops asking,
where a refusal says this one has it switched off.
- The `presence` section of a `/sync` response is empty.
- `?set_presence=` on `/sync` is ignored rather than refused — it rides on
every sync a client sends, and failing them all would make the server
unusable.
It is a boot-time setting, not a runtime one: turning it on starts
publishing a stream that nothing was tracking before, and a server that
could do that mid-flight would owe every connected client a resync.
## Long polling
`/sync` holds a request open until something happens or the timeout
expires, so `listen.write_timeout` has to stay above
`sync.long_poll_timeout` — otherwise the listener cuts off a blocked sync
before it can answer, and the client sees a dropped connection instead of
an empty response.
Raising `sync.long_poll_timeout` does not make a client hear about messages
sooner: a blocked sync is woken the moment anything concerning it is
written. All the timeout decides is how often an idle client
re-establishes its request.
## Settings that change at runtime
`federation.enabled` and `registration.enabled` are also stored in the
`server_settings` database table, which is what the admin API writes to.
- With `allow_runtime_toggle: true` (the default) the stored value wins
over the config file at boot, and the admin API may change it. The
change takes effect on the next request; no restart.
- With `allow_runtime_toggle: false` the config file is authoritative and
the admin API refuses to change the setting. Any previously stored value
is kept but ignored, so re-enabling the toggle restores the
administrator's last choice.
Everything else is read once at startup.
## What federation off actually means
While `federation.enabled` is false:
- `/_matrix/federation/*`, `/_matrix/key/*` and `/.well-known/matrix/server`
answer `404 M_UNRECOGNIZED`, exactly as on a server with no federation
API. The TLS listener on `listen.federation_address`, if there is one,
stays up and answers the same way.
- Nothing outbound runs. The transaction queue is stopped, and the
federation client refuses every request — key fetches, joins, profile
and alias lookups — before it opens a connection, so a component that
somehow missed the switch still cannot reach another server.
- Events persisted while it is off are not queued for other servers. A
remote server that cares about the room fetches what it missed the next
time it hears from this one. What was already queued when the switch
went off stays queued, and goes out when it comes back on.
- Client-Server endpoints that would need a remote server answer
`M_FORBIDDEN` with a message saying federation is disabled. That
includes downloading media from another server that is not already
cached here; media fetched before the switch went off is still served.
- Events are still signed with the server key, and room and event IDs are
unchanged. A room created while federation is off federates normally
once it is switched on.
## Federation over TLS
Other servers reach this one at whatever its server name resolves to: the
address in `/.well-known/matrix/server`, an SRV record, or the name itself
on port 8448. Two deployment shapes:
- **Behind a reverse proxy** that terminates TLS — the usual one. Set
`global.well_known.server_address` to the proxy's `host:443` and leave
`listen.federation_address` empty: the proxy forwards
`/_matrix/federation` and `/_matrix/key` to `listen.address` like
everything else.
- **Warp terminates TLS itself**: set `listen.federation_address` to
`:8448` with `listen.tls_cert_file` and `listen.tls_key_file`. The
certificate must be valid for the server name (or for the delegated
name, if the well-known document delegates).
Outbound federation verifies certificates against the system roots, plus
`federation.tls_ca_file` when it is set — for a private federation whose
servers share an internal CA. There is no switch to turn verification
off.
Reference in new issue View Git Blame Copy Permalink