diff --git a/data/doveadm.js b/data/doveadm.js index 72da48c32..6012f16b6 100644 --- a/data/doveadm.js +++ b/data/doveadm.js @@ -281,6 +281,52 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. text: `Flush authentication cache.`, }, + 'auth cache status': { + args: { + 'socket-path': { + cli: 'a', + cli_only: false, + type: doveadm_arg_types.STRING, + text: `Path to doveadm socket.`, + }, + reset: { + type: doveadm_arg_types.BOOL, + text: `Reset hit/miss/insert counters after reading them.`, + }, + }, + response: { + example: { + hits: 1234, + misses: 56, + hit_ratio_percent: 95, + pos_entries: 100, + neg_entries: 2, + pos_size: 8192, + neg_size: 64, + used_size: 8256, + max_size: 1048576, + }, + text: ` +| Key | Description | +| --- | ----------- | +| \`hits\` | Number of cache hits since last reset. | +| \`misses\` | Number of cache misses since last reset. | +| \`hit_ratio_percent\` | Cache hit ratio in percent. | +| \`pos_entries\` | Number of positive cache entries. | +| \`neg_entries\` | Number of negative cache entries. | +| \`pos_size\` | Bytes used by positive cache entries. | +| \`neg_size\` | Bytes used by negative cache entries. | +| \`used_size\` | Total bytes used by the cache. | +| \`max_size\` | Maximum cache size in bytes. | +` + }, + man: 'doveadm-auth', + text: `Show authentication cache statistics.`, + added: { + 'doveadm_auth_cache_status_added': false + }, + }, + 'auth login': { cli_only_cmd: true, args: { diff --git a/data/updates.js b/data/updates.js index a4b0ca604..9e635bc63 100644 --- a/data/updates.js +++ b/data/updates.js @@ -94,6 +94,7 @@ export const updates = { /* Tags used in doveadm.js */ + doveadm_auth_cache_status_added: '2.4.5', doveadm_proxy_kick_args: '2.4.0', doveadm_proxy_list_args_added: '2.4.0', doveadm_proxy_list_response_changed: '2.4.0', diff --git a/docs/core/config/auth/caching.md b/docs/core/config/auth/caching.md index f69be7616..80ca7c202 100644 --- a/docs/core/config/auth/caching.md +++ b/docs/core/config/auth/caching.md @@ -22,12 +22,13 @@ lookups. The following rules apply to using the authentication cache: This allows Dovecot to log in some users even if the database is temporarily down. -The authentication cache can be flushed by sending a SIGHUP to -dovecot-auth. +The authentication cache can be flushed with the +[[doveadm,auth cache flush]] command. -Sending SIGUSR2 to dovecot-auth makes it log the number of cache hits -and misses. You can use that information for tuning the cache size and -TTL. +The [[doveadm,auth cache status]] command shows the number +of cache hits and misses, hit ratio, and cache size. You can use that +information for tuning the cache size and TTL. Pass `--reset` to clear +the hit/miss counters after reading them. ## Settings diff --git a/docs/core/man/doveadm-auth.1.md b/docs/core/man/doveadm-auth.1.md index 259f3c095..cc4f688d0 100644 --- a/docs/core/man/doveadm-auth.1.md +++ b/docs/core/man/doveadm-auth.1.md @@ -40,8 +40,7 @@ authentication related actions. [*user-mask* ...] Flush the authentication cache. By default the cache is flushed for all -the users (which can also be done by sending SIGHUP to the auth -process). You can also flush the cache for one or more users by +the users. You can also flush the cache for one or more users by providing a user-mask matching their usernames. **-a** *master_socket_path* @@ -54,6 +53,28 @@ providing a user-mask matching their usernames. +### auth cache status + +**doveadm** [*GLOBAL OPTIONS*] auth cache status + [**-a** *master_socket_path*] + [**--reset**] + +Show authentication cache statistics: number of hits, misses, hit +ratio, number of positive/negative cache entries and the +positive/negative/used/max cache sizes. This information can be used +for tuning the cache size and TTL. + +**-a** *master_socket_path* +: This option is used to specify an absolute path to an alternative + UNIX domain socket. + + By default [[man,doveadm]] will use the socket */rundir/auth-master*. + The socket may be located in another directory, when the default + *base_dir* setting was overridden in */etc/dovecot/dovecot.conf*. + +**--reset** +: Reset the hit/miss/insert counters after reading them. + ### auth lookup **doveadm** [*GLOBAL OPTIONS*] auth lookup diff --git a/docs/installation/upgrade/2.4-to-2.4.x.md b/docs/installation/upgrade/2.4-to-2.4.x.md index 8e137061f..c411f4267 100644 --- a/docs/installation/upgrade/2.4-to-2.4.x.md +++ b/docs/installation/upgrade/2.4-to-2.4.x.md @@ -115,3 +115,11 @@ changed to `2.4.4`. | `push_notification_ox/http_client_request_max_attempts` | `1` | `2` | | `push_notification_ox/http_client_request_timeout` | `1min` | `2s` | | `service/lmtp/service_extra_groups` | | [[setting,default_internal_group]] | + +### v2.4.4 to v2.4.5 + +#### Removed Features + +| Feature | Notes | +| ------- | ----- | +| `auth`: `SIGHUP`, `SIGUSR2` | Use [[doveadm,auth cache flush]] to flush the cache and [[doveadm,auth cache status]] to inspect cache statistics instead. |