Add "doveadm auth cache status" command, remove SIGHUP/SIGUSR auth si…

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: {

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',

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
 

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.
 
 <!-- @include: include/option-x.inc -->
 
+### 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

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. |