From 432f54118d2f3e48ab34b8008259193a03369e91 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@amutable.com>
Date: Fri, 29 May 2026 18:27:09 +0200
Subject: [PATCH] units: add systemd-machine-tag@.service template

Add a service template that adds the machine tag given as its instance
name to the host's machine tags. Whenever an instance is pulled in, the
tag is added; the operation is idempotent.

It talks to hostnamed over Varlink (which is socket-activated), so it
works very early at boot, before the system bus is up. It is ordered
after local-fs.target so that /etc/machine-info can be written, requires
hostnamed's socket and the local filesystems to be available, and does
not run in the initrd.
---
 man/rules/meson.build                |  1 +
 man/systemd-machine-tag@.service.xml | 65 ++++++++++++++++++++++++++++
 units/meson.build                    |  4 ++
 units/systemd-machine-tag@.service   | 23 ++++++++++
 4 files changed, 93 insertions(+)
 create mode 100644 man/systemd-machine-tag@.service.xml
 create mode 100644 units/systemd-machine-tag@.service

diff --git a/man/rules/meson.build b/man/rules/meson.build
index d3df447352..f3db05fc78 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -1107,6 +1107,7 @@ manpages = [
  ['systemd-loop@.service', '8', [], ''],
  ['systemd-machine-id-commit.service', '8', [], ''],
  ['systemd-machine-id-setup', '1', [], ''],
+ ['systemd-machine-tag@.service', '8', [], 'ENABLE_HOSTNAMED'],
  ['systemd-machined.service', '8', ['systemd-machined'], 'ENABLE_MACHINED'],
  ['systemd-makefs@.service',
   '8',
diff --git a/man/systemd-machine-tag@.service.xml b/man/systemd-machine-tag@.service.xml
new file mode 100644
index 0000000000..b5bc1d81c7
--- /dev/null
+++ b/man/systemd-machine-tag@.service.xml
@@ -0,0 +1,65 @@
+<?xml version="1.0"?>
+<!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="systemd-machine-tag_.service" conditional='ENABLE_HOSTNAMED'
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>systemd-machine-tag@.service</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>systemd-machine-tag@.service</refentrytitle>
+    <manvolnum>8</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>systemd-machine-tag@.service</refname>
+    <refpurpose>Add a machine tag to the host</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <para><filename>systemd-machine-tag@.service</filename></para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><filename>systemd-machine-tag@<replaceable>TAG</replaceable>.service</filename> is a service
+    template that adds the machine tag <replaceable>TAG</replaceable> (taken from the instance name) to the
+    host's list of machine tags. Whenever an instance of this template is pulled in, the corresponding tag is
+    added; the operation is idempotent, so pulling it in repeatedly has no further effect.</para>
+
+    <para>The primary use of this template is automatic, hardware-driven tagging: the
+    <varname>SYSTEMD_MACHINE_TAG</varname> udev property, when set on a device, causes the matching instance
+    of this template to be pulled in (via <varname>SYSTEMD_WANTS=</varname>), so that plugging in or
+    detecting a specific device automatically tags the host. See
+    <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+    details on the <varname>SYSTEMD_WANTS=</varname> mechanism.</para>
+
+    <para>Machine tags may be inspected and edited with the <command>tags</command> verb of
+    <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, and are
+    stored in the <varname>TAGS=</varname> field of
+    <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Each
+    tag must be 1…255 characters long and consist only of ASCII alphanumeric characters,
+    <literal>-</literal> and <literal>.</literal>.</para>
+
+    <xi:include href="version-info.xml" xpointer="v262"/>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+    </simplelist></para>
+  </refsect1>
+
+</refentry>
diff --git a/units/meson.build b/units/meson.build
index de7a796a1e..db5edb01e6 100644
--- a/units/meson.build
+++ b/units/meson.build
@@ -503,6 +503,10 @@ units = [
           'file' : 'systemd-machine-id-commit.service',
           'symlinks' : ['sysinit.target.wants/'],
         },
+        {
+          'file' : 'systemd-machine-tag@.service',
+          'conditions' : ['ENABLE_HOSTNAMED'],
+        },
         {
           'file' : 'systemd-machined.service.in',
           'conditions' : ['ENABLE_MACHINED'],
diff --git a/units/systemd-machine-tag@.service b/units/systemd-machine-tag@.service
new file mode 100644
index 0000000000..7fc578d7e8
--- /dev/null
+++ b/units/systemd-machine-tag@.service
@@ -0,0 +1,23 @@
+#  SPDX-License-Identifier: LGPL-2.1-or-later
+#
+#  This file is part of systemd.
+#
+#  systemd is free software; you can redistribute it and/or modify it
+#  under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation; either version 2.1 of the License, or
+#  (at your option) any later version.
+
+[Unit]
+Description=Add Machine Tag %i
+Documentation=man:systemd-machine-tag@.service(8)
+DefaultDependencies=no
+ConditionPathExists=!/etc/initrd-release
+After=local-fs.target systemd-hostnamed.socket
+Requisite=local-fs.target systemd-hostnamed.socket
+Before=shutdown.target
+Conflicts=shutdown.target
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+ExecStart=varlinkctl call /run/systemd/io.systemd.Hostname io.systemd.Hostname.SetTags '{"add":["%i"]}'