diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt
index 6126b1bb5..29dde44a4 100644
--- a/.github/actions/spelling/expect.txt
+++ b/.github/actions/spelling/expect.txt
@@ -784,7 +784,6 @@ sysexits
 syslogd
 syslogging
 sysreport
-systemt
 tabindex
 TABLEGEN
 Taddressverification
diff --git a/docs/core/design/var_expand.md b/docs/core/design/var_expand.md
index a3092c0ec..6d11e2fe0 100644
--- a/docs/core/design/var_expand.md
+++ b/docs/core/design/var_expand.md
@@ -8,7 +8,7 @@ dovecotlinks:
 # Variable expansion design
 
 Dovecot comes with powerful variable expansion system, which allows constructing reusable text templates.
-This has been upgraded since v2.3 to a more flexible systemt .
+This has been upgraded since v2.3 to a more flexible system.
 
 ## Syntax
 
diff --git a/docs/core/plugins/mail_crypt.md b/docs/core/plugins/mail_crypt.md
index e12b2a4ec..b6da62c7d 100644
--- a/docs/core/plugins/mail_crypt.md
+++ b/docs/core/plugins/mail_crypt.md
@@ -194,7 +194,7 @@ provided via password query:
 
 ```[dovecot.conf]
 passdb sql {
-  query = SELECT email as user, password, '%Mw' AS userdb_crypt_user_key_password \
+  query = SELECT email as user, password, '%{password | sha256}' AS userdb_crypt_user_key_password \
     FROM virtual_users \
     WHERE email='%{user}'
 }
diff --git a/docs/installation/upgrade/2.3-to-2.4.md b/docs/installation/upgrade/2.3-to-2.4.md
index e3cdf913c..9ae5b4840 100644
--- a/docs/installation/upgrade/2.3-to-2.4.md
+++ b/docs/installation/upgrade/2.3-to-2.4.md
@@ -25,6 +25,8 @@ setup.
 
 <!-- @include: include/2.4-redesign.inc -->
 
+<!-- @include: include/2.4-var-expand.inc -->
+
 <!-- @include: include/2.4-directory-hashing.inc -->
 
 <!-- @include: include/2.4-unknown-invalid-variables.inc -->
diff --git a/docs/installation/upgrade/include/2.4-var-expand.inc b/docs/installation/upgrade/include/2.4-var-expand.inc
new file mode 100644
index 000000000..2abed75c5
--- /dev/null
+++ b/docs/installation/upgrade/include/2.4-var-expand.inc
@@ -0,0 +1,57 @@
+#### Variable expansion
+
+A new [[link,var_expand]] syntax has been introduced.
+All old one-letter %variables have been removed,
+and some old variable aliases have been dropped too.
+
+##### List of common short variables and their replacements.
+
+| Old variable | New syntax |
+| -------- | ---------- |
+| `%a` | `%{local_port}` |
+| `%b` | `%{remote_port}` |
+| `%c` | `%{certificate}` |
+| `%c` | `%{secured}` |
+| `%d` | `%{user \| domain }` |
+| `%h` | `%{home}` |
+| `%l` | `%{local_ip }` |
+| `%m` | `%{mechanism}` |
+| `%n` | `%{user \| username }` |
+| `%p` | `%{client_pid }` |
+| `%r` | `%{remote_ip }` |
+| `%s` | `%{protocol}` |
+| `%u` | `%{user}` |
+| `%w` | `%{password}` |
+
+##### Common modifier syntaxes and their replacements.
+
+| Old syntax | New syntax |
+| ---------- | ---------- |
+| `%1Mu` | `%{user \| md5 \| hexlify(1)}` |
+| `%2.1Mu` | `%{user \| md5 \| hexlify \| substr(2,1)}` |
+| `%2.256N` | `%{ user \| md5 \| substr(0, 8) % 256 \| hex(2)}` |
+| `%256Nu` | `%{ user \| md5 \| substr(0, 8) % 256 \| hex}` |
+| `%Hu` | No conversion available, use one of the syntaxes. |
+| `%Ln` | `%{user \| username \| lower }` |
+| `%Lu` | `%{user \| lower }` |
+| `%Mu` | `%{user \| md5}` |
+
+##### Common long variables and their replacements.
+
+| Old variable | New syntax |
+| ------------ | ------------ |
+| `%{auth_domain}` | `%{auth_user \| domain}` |
+| `%{auth_username}` | `%{auth_user \| username}` |
+| `%{lip}` | `%{local_ip}` |
+| `%{lport}` | `%{local_port}` |
+| `%{mech}` | `%{mechanism}` |
+| `%{orig_domain }` | `%{original_user \| domain }` |
+| `%{orig_username}` | `%{original_user \| username }` |
+| `%{orig_user}` | `%{original_user}` |
+| `%{real_lip}` | `%{real_local_ip}` |
+| `%{real_lport}` | `%{real_local_port }` |
+| `%{real_rip}` | `%{real_remote_ip }` |
+| `%{real_rport}` | `%{real_remote_port}` |
+| `%{rip}` | `%{remote_ip}` |
+| `%{rport}` | `%{remote_port }` |
+| `%{service}` | `%{protocol}` |