Skip to content

Var expand safe #1550

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
cmouse wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Var expand safe #1550

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bb79ae5
upgrade: Note that safe filter must be last in pipeline
cmouse Jun 7, 2026
8403386
variables: Indicate safe must be last in pipeline
cmouse Jun 7, 2026
f5b2fcc
variables: document escape filter
cmouse Jun 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions data/updates.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,7 @@ export const updates = {
variables_owner_user_added: '2.4.0',
var_expand: '2.4.0',
variables_oauth2: '2.4.3',
variables_escape_added: '2.4.5',
variables_safe_added: '2.4.3',
variables_switch_added: '2.4.3',
xclient_dest_added: '2.4.3',
Expand Down
5 changes: 4 additions & 1 deletion docs/core/settings/variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,8 @@ a provider. There are global providers, and context-specific providers.

A variable can be then filtered with various filters, such as `%{variable | upper}` to get
uppercase representation of variable. You can chain as many filters as you need.
If a pipeline contains the `safe` filter, it applies to the whole pipeline output.
The `safe` filter must always be the last filter in the pipeline.

Filters can accept parameters, both positional and named. E.g. `%{literal('\r\n\')}` will expand
to CR LF. `%{user | substr(0, 1)}` will take first character of username. Example of named parameters
Expand Down Expand Up @@ -108,6 +110,7 @@ Bytes output type indicates that the output will be tagged as binary output. Sub
| `domain` | String | String | Provides domain part of user@domain value. |
| `encrypt(key=bytes, iv=bytes, raw=boolean, algorithm=string)` | Any | Any | Encrypts given input, see [cryptography support](#cryptography-support). |
| `encrypt(key=string, salt=string, rounds=number, raw=boolean, hash=string, algorithm=string)` | Any | Any | Encrypts given input, see [cryptography support](#cryptography-support). |
| `escape` | String | String | Apply the configured escape function to the input. Returns an error if no escape function is configured. This filter is intended to be used with `safe` filter, when used without, the output is escaped again at output time (double-escaped). [[added,variables_escape_added]] |
| `hash(method, rounds=number, salt=string)` | Bytes | Bytes | Returns raw hash from input using given hash method. Rounds and salt are optional. |
| `hexlify(width)` | Bytes | String | Convert bytes into hex with optional width, truncates or pads up to width. |
| `hex(width)` | Number | Number | Convert base-10 number to base-16 number. If width is specified the result is truncated or padded with 0 to width. Negative width is applied after number. |
Expand Down Expand Up @@ -139,7 +142,7 @@ Bytes output type indicates that the output will be tagged as binary output. Sub
| `unhexlify` | String | Bytes | Convert hex encoded input into bytes. |
| `upper` | String | String | Uppercases input. |
| `username` | String | String | Provides user part of user@domain value. |
| `safe` | String | String | Don't escape the variable output. This is mainly intended for [[setting,ldap_base]] when the DN comes from a variable. [[added,variables_safe_added]] |
| `safe` | String | String | Don't escape the output of the whole pipeline. This must always be the last filter in the pipeline. This is mainly intended for [[setting,ldap_base]] when the DN comes from a variable. [[added,variables_safe_added]] |

## Global providers

Expand Down
8 changes: 7 additions & 1 deletion docs/installation/upgrade/2.4-to-2.4.x.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ dovecotlinks:

### v2.4.2 to v2.4.3

* Using [[link,settings_variables]] with LDAP settings now requires using `| safe` filter to allow passing through LDAP characters that are otherwise escaped. Note that this should be used only for variables coming from trusted sources, not for e.g. username variable.
* Using [[link,settings_variables]] with LDAP settings now requires using `| safe` filter to allow passing through LDAP characters that are otherwise escaped. The `safe` filter must always be the last filter in the pipeline. Note that this should be used only for variables coming from trusted sources, not for e.g. username variable.

#### Changed Setting Defaults

Expand Down Expand Up @@ -118,6 +118,12 @@ changed to `2.4.4`.

### v2.4.4 to v2.4.5

#### New Features

| Feature | Notes |
| ------- | ----- |
| [[link,settings_variables,`escape` filter]] | Explicitly apply the configured escape function within a variable expansion pipeline. Useful for partial escaping when combined with `concat` and `safe`. |

#### Removed Features

| Feature | Notes |
Expand Down