From d9eedcf56ba1209582ae480a743e25672ed1154a Mon Sep 17 00:00:00 2001 From: Gusted Date: Mon, 30 Dec 2024 17:41:48 +0100 Subject: [PATCH] Document user cooldown feature Ref: forgejo/forgejo#6422 --- docs/admin/config-cheat-sheet.md | 2 ++ docs/admin/recommendations.md | 8 ++++++++ 2 files changed, 10 insertions(+) diff --git a/docs/admin/config-cheat-sheet.md b/docs/admin/config-cheat-sheet.md index c4850dd8..b46b29e2 100644 --- a/docs/admin/config-cheat-sheet.md +++ b/docs/admin/config-cheat-sheet.md @@ -690,6 +690,8 @@ And the following unique queues: The user's email will be replaced with a concatenation of the user name in lower case, "@" and NO_REPLY_ADDRESS. - `USER_DELETE_WITH_COMMENTS_MAX_TIME`: **0** Minimum amount of time a user must exist before comments are kept when the user is deleted. - `VALID_SITE_URL_SCHEMES`: **http, https**: Valid site url schemes for user profiles +- `USERNAME_COOLDOWN_PERIOD`: **0**: The cooldown period in days before a username previously used by another user can be claimed by someone other than the original user. If you enter a non-positive number here, the cooldown period is deactivated and previously used usernames can be claimed immediately. +- `MAX_USER_REDIRECTS`: **0**: The number of user redirects that a user can keep. The oldest entry is removed when a new user redirection is created. The default value is **5** if `USERNAME_COOLDOWN_PERIOD` is set to a positive value. ### Service - Explore (`service.explore`) diff --git a/docs/admin/recommendations.md b/docs/admin/recommendations.md index 46dc18a7..9e2ea3a1 100644 --- a/docs/admin/recommendations.md +++ b/docs/admin/recommendations.md @@ -73,6 +73,14 @@ The explore page is a good way to quickly check what is happening with an instan If you have an instance with a lot of activity, it is recommended to change this value to **true**. In that situation, the explore page will filter out repositories that are likely to be less relevant in order to see what interesting projects are available on that instance. +### `[service].USERNAME_COOLDOWN_PERIOD` + +If a user or an organization is renamed, each old username, until it is claimed, will redirect to the latest username. In the context of public forges, to prevent namesquatting and allow users to reverse their username change within a certain period of time, a cooldown period can be configured to ensure that no user can claim the username within the cooldown period (with the exception of the original user and administrators). + +If your instance has an open registration, it is recommended to change this value to **7**. This means that there is a seven-day cooldown period for old usernames before they can be claimed by anyone, and that users can revert to their old username within seven days. + +There is a closely related configuration option `[service].MAX_USER_REDIRECTS` for which the default value is **5** when a cooldown period is specified. This controls the number of user redirects a user can have (and therefore how many usernames are subject to a cooldown period). The intention of this option is to prevent abuse of the cooldown feature by limiting the amount of usernames that one user can keep on cooldown. + ## Tips ### Git over SSH