machine-tags.d

systemd

machine-tags.d

Configure machine tags

/etc/machine-tags.d/*.tags, /run/machine-tags.d/*.tags, /usr/local/lib/machine-tags.d/*.tags, /usr/lib/machine-tags.d/*.tags

Description

The files in the above directories declare machine tags to be added or removed from the list of tags in the TAGS= field of machine-info(5). See that page for the details of how tags are defined and used.

Those files are read and applied by systemd-hostnamed.service(8) when requested via hostnamectl tags --apply, see hostnamectl(1), or directly via the io.systemd.Hostname.ApplyTags() call. The resulting tag list is stored in /etc/machine-info, thus applying the same configuration repeatedly has no further effect.

Note: when machine-tags.d/ files are used, direct management of tags through hostnamectl tags … or by editing the /etc/machine-info file directly are not recommended. Please use one approach or the other.

During boot, the configuration is applied automatically by systemd-machine-tags.service(8).

This allows OS vendors, image builders and system extensions (see systemd-sysext(8)) to declare tags in a drop-in directory hierarchy, instead of setting them imperatively.

Configuration Format

Each file contains a list of entries separated by whitespace (spaces, tabs, or newlines). Empty lines and comments (lines starting with # or ;) are ignored.

An entry without prefix (or, equivalently, prefixed with +) adds a tag. An entry prefixed with - removes matching tags. The pattern may be a literal tag value, or a shell-style glob, see glob(7). For example, -vendor.install.* removes all tags starting with vendor.install., -company.role=* removes any value assigned to the company.role key, and -* removes all tags. Removing a tag that is not set has no effect.

Entries are applied in the order they appear, across all files in the order described below. A tag may hence be removed by a glob and added back by a later entry. When a parameterized tag key=value is added and a different value is already assigned to the same key, the previous assignment is replaced.

Each tag must be a valid machine tag, see machine-info(5) for the syntax. Invalid entries are ignored with a warning, and the remaining entries are still applied.

Configuration Directories and Precedence

Configuration files are read from directories in /etc/, /run/, /usr/local/lib/, and /usr/lib/, in order of precedence, as listed in the SYNOPSIS section above. Files must have the .tags extension. Files in /etc/ override files with the same name in /run/, /usr/local/lib/, and /usr/lib/. Files in /run/ override files with the same name under /usr/.

All configuration files are sorted by their filename in lexicographic order, regardless of which of the directories they reside in, following the usual semantics of systemd configuration files. Empty files and symlinks to /dev/null mask files in directories with lower priority.

Note that masking or removing a file only affects future applications of the configuration. Tags that were applied earlier remain configured until they are removed explicitly, for example with a - entry in another file, or with hostnamectl tags.

Examples

/usr/lib/machine-tags.d/20-vendor.tags example:

# Tags declared by the OS vendor
vendor.role=webserver
vendor.env=production
vendor.region=eu

/etc/machine-tags.d/70-local.tags example:

# Drop the vendor's environment and region tags, but keep the role, and add a local tag
-vendor.env=* -vendor.region=*
local.rack=7

After hostnamectl tags --apply, the configured tags include local.rack=7 and vendor.role=webserver, in addition to any tags that were configured before.