mirror of
https://github.com/mailscope/kumomta.git
synced 2026-08-19 19:08:17 +00:00
Wez Furlong
57 lines
2.5 KiB
Markdown
57 lines
2.5 KiB
Markdown
# Node ID
|
|
|
|
Each KumoMTA (`kumod`) instance can have its own `NodeId`, which is a UUID
|
|
intended identify that specific instance within your own local cluster, help
|
|
with disambiguation during reporting, and also for future configuration
|
|
management/provisioning related functionality.
|
|
|
|
The `NodeId` is reported as the `nodeid` field in the [Log
|
|
Record](../../reference/log_record.md).
|
|
|
|
In the default configuration, KumoMTA will use the file
|
|
`/opt/kumomta/etc/.nodeid` to persist the `NodeId`. If that file doesn't
|
|
exist, a new ID will be generated and stored in that location.
|
|
|
|
If persisting the `NodeId` isn't possible, we fall back to generating an
|
|
id as described in the section below.
|
|
|
|
## Environment Variables
|
|
|
|
The following environment variables influence the Node ID:
|
|
|
|
* `KUMO_NODE_ID` - if this is set to a valid UUID, its value will be used as
|
|
the `NodeId` for the instance. You might contrive for your orchestration
|
|
system to set this if you want total control over the relationship between
|
|
the machine and node id.
|
|
|
|
* `KUMO_NODE_ID_PATH` - this can be set to an alternative location into which
|
|
the nodeid should be stored. If this is not set, the path is assumed to be
|
|
`/opt/kumomta/etc/.nodeid`. If the path is not writable for some reason
|
|
(eg: permission denied), then a fallback nodeid will be computed.
|
|
|
|
## Fallback Node ID
|
|
|
|
If `NodeId` cannot be persisted then the following fallback procedure will be
|
|
used to compute an ID that will have a consistent value across restarts of
|
|
the kumod process:
|
|
|
|
* First attempt to determine the MAC address of the primary network interface
|
|
on the system
|
|
|
|
* If we cannot determine the MAC address then use the POSIX `gethostid(3)`
|
|
call to obtain a 32-bit stable identifier for the system, which is extended
|
|
to 6 bytes to make it the same size and shape as a MAC address.
|
|
|
|
The MAC address bytes are then used to compute a V1 (time based) UUID with a
|
|
fixed timestamp, which produces a UUID that looks something like
|
|
`00000000-0000-1000-8000-XXXXXXXXXXXX` where the X's are the hex digits from
|
|
the MAC address.
|
|
|
|
Neither the true MAC address nor especially the `gethostid(3)` fallback are
|
|
ideal if the network interface might change across the lifetime of a logical
|
|
instance, so we recommend fixing any permission errors that might be preventing
|
|
persisting a true random UUID or alternatively, adjusting your node
|
|
provisioning to pre-define a `KUMO_NODE_ID` environment variable if you have
|
|
stronger opinions about how you want to provision and manage these things.
|
|
|