From 207bcb3191aeed861ffde9e30cf56dae978fae92 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Tue, 13 Oct 2020 11:59:18 +0100 Subject: [PATCH 1/4] Update documentation on retention policies limits Document the changes from https://github.com/matrix-org/synapse/pull/8104 --- docs/message_retention_policies.md | 34 +++++++++++++++++++----------- 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/docs/message_retention_policies.md b/docs/message_retention_policies.md index 1dd60bdad952..91855497d569 100644 --- a/docs/message_retention_policies.md +++ b/docs/message_retention_policies.md @@ -136,24 +136,34 @@ the server's database. ### Lifetime limits -**Note: this feature is mainly useful within a closed federation or on -servers that don't federate, because there currently is no way to -enforce these limits in an open federation.** - -Server admins can restrict the values their local users are allowed to -use for both `min_lifetime` and `max_lifetime`. These limits can be -defined as such in the `retention` section of the configuration file: +Server admins can set limits on the values of `max_lifetime` to use when +purging old events in a room. These limits can be defined as such in the +`retention` section of the configuration file: ```yaml allowed_lifetime_min: 1d allowed_lifetime_max: 1y ``` -Here, `allowed_lifetime_min` is the lowest value a local user can set -for both `min_lifetime` and `max_lifetime`, and `allowed_lifetime_max` -is the highest value. Both parameters are optional (e.g. setting -`allowed_lifetime_min` but not `allowed_lifetime_max` only enforces a -minimum and no maximum). +These values are evaluated when running purge jobs, to adjust the +effective value of `max_lifetime`, and make sure it's within the +`[allowed_lifetime_min, allowed_lifetime_max]` range. If the value of +`max_lifetime` defined in the room's state is lower than +`allowed_lifetime_min`, the value of `allowed_lifetime_min` will be used +instead. Likewise, if the value of `max_lifetime` is higher than +`allowed_lifetime_max`, the value of `allowed_lifetime_max` will be used +instead. + +In the example above, we ensure Synapse never deletes events that are less +than one day old, and that it always deletes events that are over a year +old. + +If a default policy is set, and its `max_lifetime` value is lower than +`allowed_lifetime_min` or higher than `allowed_lifetime_max`, the same +process applies. + +Both parameters are optional; if one is omitted Synapse won't use it to +adjust the effective value of `max_lifetime`. Like other settings in this section, these parameters can be expressed either as a duration or as a number of milliseconds. From 5220991d248a31e5a621875427af3c41eb1462a3 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Tue, 13 Oct 2020 12:00:54 +0100 Subject: [PATCH 2/4] Changelog --- changelog.d/8529.doc | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/8529.doc diff --git a/changelog.d/8529.doc b/changelog.d/8529.doc new file mode 100644 index 000000000000..6e710e6527bb --- /dev/null +++ b/changelog.d/8529.doc @@ -0,0 +1 @@ +Document the new behaviour of the `allowed_lifetime_min` and `allowed_lifetime_max` settings in the room retention configuration. From caad04fd064cb25ce120b50cced9cebcfc353e79 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Wed, 14 Oct 2020 12:04:18 +0100 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- docs/message_retention_policies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/message_retention_policies.md b/docs/message_retention_policies.md index 91855497d569..2b7178cf4cb5 100644 --- a/docs/message_retention_policies.md +++ b/docs/message_retention_policies.md @@ -145,7 +145,7 @@ purging old events in a room. These limits can be defined as such in the allowed_lifetime_max: 1y ``` -These values are evaluated when running purge jobs, to adjust the +The limits are considered when running purge jobs, to adjust the effective value of `max_lifetime`, and make sure it's within the `[allowed_lifetime_min, allowed_lifetime_max]` range. If the value of `max_lifetime` defined in the room's state is lower than From ddd1f2bc9af1130e5ce209eb44f4c3c168115f19 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Wed, 14 Oct 2020 14:27:35 +0100 Subject: [PATCH 4/4] Incorporate review --- docs/message_retention_policies.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/message_retention_policies.md b/docs/message_retention_policies.md index 2b7178cf4cb5..75d2028e1740 100644 --- a/docs/message_retention_policies.md +++ b/docs/message_retention_policies.md @@ -145,14 +145,14 @@ purging old events in a room. These limits can be defined as such in the allowed_lifetime_max: 1y ``` -The limits are considered when running purge jobs, to adjust the -effective value of `max_lifetime`, and make sure it's within the -`[allowed_lifetime_min, allowed_lifetime_max]` range. If the value of -`max_lifetime` defined in the room's state is lower than -`allowed_lifetime_min`, the value of `allowed_lifetime_min` will be used -instead. Likewise, if the value of `max_lifetime` is higher than -`allowed_lifetime_max`, the value of `allowed_lifetime_max` will be used -instead. +The limits are considered when running purge jobs. If necessary, the +effective value of `max_lifetime` will be brought between +`allowed_lifetime_min` and `allowed_lifetime_max` (inclusive). +This means that, if the value of `max_lifetime` defined in the room's state +is lower than `allowed_lifetime_min`, the value of `allowed_lifetime_min` +will be used instead. Likewise, if the value of `max_lifetime` is higher +than `allowed_lifetime_max`, the value of `allowed_lifetime_max` will be +used instead. In the example above, we ensure Synapse never deletes events that are less than one day old, and that it always deletes events that are over a year