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>
2.9 KiB
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:
{
"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:
{
"enabled": false
}
enabled sets whether the background updates are enabled or disabled.
The API returns the enabled param.
{
"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:
{
"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 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 areceived_tsless than this value (milliseconds since the epoch).