diff --git a/data/updates.js b/data/updates.js
index 7e6fc3b38..46dd19fb9 100644
--- a/data/updates.js
+++ b/data/updates.js
@@ -58,6 +58,7 @@ export const updates = {
 	migration_imapc_features: '2.4.0',
 	namespace_prefix_shared_variables_changed: '2.4.0',
 	pbkdf2_hashing: '2.4.0',
+	passwd_file_iteration: '2.4.0',
 	process_title_imap_process: '2.4.0',
 	process_title_initializing: '2.4.0',
 	process_title_mail_processes: '2.4.0',
diff --git a/docs/core/config/auth/databases/passwd_file.md b/docs/core/config/auth/databases/passwd_file.md
index 1431f8019..3e85a3739 100644
--- a/docs/core/config/auth/databases/passwd_file.md
+++ b/docs/core/config/auth/databases/passwd_file.md
@@ -64,6 +64,12 @@ passdb passwd-file {
 }
 ```
 
+[[added,passwd_file_iteration]]
+To iterate databases that use [[variable]] expansion in the path, you need to provide enough information when using
+e.g. [[doveadm,user]] to iterate. For example [[doveadm,user,*@domain.com]] would match with ``%{user | domain}`` expansion in
+the above example, and [[doveadm,user,*]] would iterate `/etc/auth/passwd` if available.
+This iteration works with all doveadm mail commands similarly.
+
 ### Variables
 
 [[setting,passdb_fields]] and [[setting,userdb_fields]] can use