mirror of
https://github.com/mailscope/kumomta.git
synced 2026-08-19 10:58:17 +00:00
Wez Furlong
75 lines
3.0 KiB
Markdown
75 lines
3.0 KiB
Markdown
---
|
|
tags:
|
|
- meta
|
|
---
|
|
|
|
# Connection Metadata Object
|
|
|
|
{{since('2023.08.22-4d895015')}}
|
|
|
|
This object represents a collection of metadata keys and values that
|
|
are associated with an established incoming SMTP connection.
|
|
|
|
KumoMTA populates a small number of predefined fields (see below), and allows
|
|
your policy scripts the ability to read those values as well as write (and
|
|
read!) additional values as needed by the local policy. For instance, you may
|
|
decide to compute a value after EHLO has been processed by
|
|
[smtp_server_ehlo](events/smtp_server_ehlo.md) and access that value in a
|
|
later SMTP event handler.
|
|
|
|
Prior to calling [smtp_server_message_received](events/smtp_server_message_received.md),
|
|
KumoMTA will copy the values from the connection metadata and use those to populate
|
|
the [message](message/index.md) metadata.
|
|
|
|
The `get_meta` and `set_meta` methods shown below are used to read and write
|
|
metadata values.
|
|
|
|
## Predefined Connection Metadata Values
|
|
|
|
The following values are predefined by KumoMTA:
|
|
|
|
<style>
|
|
table tbody tr td:nth-of-type(2) {
|
|
white-space: nowrap;
|
|
}
|
|
</style>
|
|
|
|
|Scope|Name|Purpose|Since|
|
|
|----|----|-------|-----|
|
|
|Connection|`reception_protocol`|indicates the reception protocol, such as `ESMTP`|{{since('2023.08.22-4d895015', inline=True)}}|
|
|
|Connection|`received_via`|indicates the IP:port of the KumoMTA listener that is handling this session|{{since('2023.08.22-4d895015', inline=True)}}|
|
|
|Connection|`received_from`|indicates the IP:port of the sending or peer machine in this session|{{since('2023.08.22-4d895015', inline=True)}}|
|
|
|Connection|`hostname`|A copy of the effective value of the hostname set by [kumo.start_esmtp_listener](kumo/start_esmtp_listener/hostname.md)|{{since('2023.11.28-b5252a41', inline=True)}}|
|
|
|Connection|`authn_id`|the authentication id if the message was received via authenticated SMTP||
|
|
|Connection|`authz_id`|the authorization id if the message was received via authenticated SMTP||
|
|
|
|
!!! Note
|
|
Additional metadata is available at the Message scope, for a full list of all available metadata, see the [Predefined Metadata](./metadata.md) page.
|
|
|
|
## Available Methods
|
|
|
|
### `conn_meta:get_meta(name)`
|
|
|
|
Returns the value associated with *name*, or `nil` if no such value has been defined.
|
|
Values may be predefined by KumoMTA or may be set by policy scripts using `conn_meta:set_meta()`.
|
|
|
|
### `conn_meta:set_meta(name, value)`
|
|
|
|
Sets the value associated with *name* to *value*. Value must be serializable as JSON; it can be simple
|
|
strings or numbers, but may also be an array or object value.
|
|
|
|
To avoid collisions with current and future predefined keys, prefix your own
|
|
meta keys with `x_`. See the
|
|
[set_meta naming convention](message/set_meta.md#naming-convention-for-user-defined-keys)
|
|
for the rationale.
|
|
|
|
### `conn_meta:auth_info()`
|
|
|
|
{{since('2026.03.04-bb93ecb1')}}
|
|
|
|
Returns a *read-only copy* of the [AuthInfo](kumo.aaa/auth_info.md) object
|
|
for the current session, which can be used in a call to
|
|
[kumo.aaa.query_resource_access](kumo.aaa/query_resource_access.md) for
|
|
advanced access control use-cases.
|
|
|