Skip to content

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.

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.