mirror of
https://github.com/element-hq/synapse.git
synced 2026-04-22 00:25:44 +00:00
bed00bb766
This adds a way to re-sign all locally-created events with a new signing key, which is useful when rotating server signing keys. This doesn't trigger automatically, instead needs to be triggered when needed via the admin API. c.f. https://github.com/matrix-org/internal-config/issues/1670#issuecomment-4206020126 for internal discussion. --------- Co-authored-by: Kegan Dougall <kegan@element.io> Co-authored-by: Erik Johnston <erikj@element.io>
113 lines
2.9 KiB
Markdown
113 lines
2.9 KiB
Markdown
# Background Updates API
|
|
|
|
This API allows a server administrator to manage the background updates being
|
|
run against the database.
|
|
|
|
## Status
|
|
|
|
This API gets the current status of the background updates.
|
|
|
|
|
|
The API is:
|
|
|
|
```
|
|
GET /_synapse/admin/v1/background_updates/status
|
|
```
|
|
|
|
Returning:
|
|
|
|
```json
|
|
{
|
|
"enabled": true,
|
|
"current_updates": {
|
|
"<db_name>": {
|
|
"name": "<background_update_name>",
|
|
"total_item_count": 50,
|
|
"total_duration_ms": 10000.0,
|
|
"average_items_per_ms": 2.2,
|
|
},
|
|
}
|
|
}
|
|
```
|
|
|
|
`enabled` whether the background updates are enabled or disabled.
|
|
|
|
`db_name` the database name (usually Synapse is configured with a single database named 'master').
|
|
|
|
For each update:
|
|
|
|
`name` the name of the update.
|
|
`total_item_count` total number of "items" processed (the meaning of 'items' depends on the update in question).
|
|
`total_duration_ms` how long the background process has been running, not including time spent sleeping.
|
|
`average_items_per_ms` how many items are processed per millisecond based on an exponential average.
|
|
|
|
|
|
## Enabled
|
|
|
|
This API allows pausing background updates.
|
|
|
|
Background updates should *not* be paused for significant periods of time, as
|
|
this can affect the performance of Synapse.
|
|
|
|
*Note*: This won't persist over restarts.
|
|
|
|
*Note*: This won't cancel any update query that is currently running. This is
|
|
usually fine since most queries are short lived, except for `CREATE INDEX`
|
|
background updates which won't be cancelled once started.
|
|
|
|
|
|
The API is:
|
|
|
|
```
|
|
POST /_synapse/admin/v1/background_updates/enabled
|
|
```
|
|
|
|
with the following body:
|
|
|
|
```json
|
|
{
|
|
"enabled": false
|
|
}
|
|
```
|
|
|
|
`enabled` sets whether the background updates are enabled or disabled.
|
|
|
|
The API returns the `enabled` param.
|
|
|
|
```json
|
|
{
|
|
"enabled": false
|
|
}
|
|
```
|
|
|
|
There is also a `GET` version which returns the `enabled` state.
|
|
|
|
|
|
## Run
|
|
|
|
This API schedules a specific background update to run. The job starts immediately after calling the API.
|
|
|
|
|
|
The API is:
|
|
|
|
```
|
|
POST /_synapse/admin/v1/background_updates/start_job
|
|
```
|
|
|
|
with the following body:
|
|
|
|
```json
|
|
{
|
|
"job_name": "populate_stats_process_rooms"
|
|
}
|
|
```
|
|
|
|
The following JSON body parameters are available:
|
|
|
|
- `job_name` - A string which job to run. Valid values are:
|
|
- `populate_stats_process_rooms` - Recalculate the stats for all rooms.
|
|
- `regenerate_directory` - Recalculate the [user directory](../../../user_directory.md) if it is stale or out of sync.
|
|
- `event_resign` - Re-sign all locally-sent events with the current signing key. This is useful after rotating the server's signing key to ensure all historical events are signed with the new key. Optional additional parameters:
|
|
- `old_key` - Only re-sign events whose signature verifies against this key. Format: `"ed25519:key_id base64_public_key"` (e.g. `"ed25519:my_old_key XGX0JRS2Af3be3knz2fBiRbApjm2Dh61gXDJA8kcJNI"`).
|
|
- `before_ts` - Only re-sign events with a `received_ts` less than this value (milliseconds since the epoch).
|