meson,docs: add machine-tags.d(5) and install empty config dirs

man/machine-info.xml

@@ -179,7 +179,10 @@
           <varname>ConditionMachineTag=</varname> and <varname>AssertMachineTag=</varname> unit settings, see
           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
           for details. They may be queried and changed with the <command>tags</command> command of
-          <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
+          <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+          Tags may also be declared in <filename>machine-tags.d/</filename> drop-in directories, see
+          <citerefentry><refentrytitle>machine-tags.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+          and applied with <command>hostnamectl tags --apply</command>.</para>
 
           <xi:include href="version-info.xml" xpointer="v261"/></listitem>
         </varlistentry>
@@ -252,6 +255,7 @@ TAGS=room=kitchen:company.location=berlin:company.role=personal</programlisting>
         <member><citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
         <member><citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
         <member><citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+        <member><citerefentry><refentrytitle>machine-tags.d</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
         <member><citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
       </simplelist></para>
   </refsect1>

man/machine-tags.d.xml

@@ -0,0 +1,139 @@
+<?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="machine-tags.d" conditional='ENABLE_HOSTNAMED'
+    xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>machine-tags.d</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>machine-tags.d</refentrytitle>
+    <manvolnum>5</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>machine-tags.d</refname>
+    <refpurpose>Configure machine tags</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <para><simplelist>
+      <member><filename>/etc/machine-tags.d/*.tags</filename></member>
+      <member><filename>/run/machine-tags.d/*.tags</filename></member>
+      <member><filename>/usr/local/lib/machine-tags.d/*.tags</filename></member>
+      <member><filename>/usr/lib/machine-tags.d/*.tags</filename></member>
+    </simplelist></para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>The files in the above directories declare machine tags to be added or removed from the list of
+    tags in the <varname>TAGS=</varname> field of
+    <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+    See that page for the details of how tags are defined and used.</para>
+
+    <para>Those files are read and applied by
+    <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    when requested via <command>hostnamectl tags --apply</command>, see
+    <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, or
+    directly via the <function>io.systemd.Hostname.ApplyTags()</function> call. The resulting tag list is
+    stored in <filename>/etc/machine-info</filename>, thus applying the same configuration repeatedly has no
+    further effect.</para>
+
+    <para>This allows OS vendors, image builders and system extensions (see
+    <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>) to
+    declare tags in a drop-in directory hierarchy, instead of setting them imperatively.</para>
+
+    <xi:include href="version-info.xml" xpointer="v263"/>
+  </refsect1>
+
+  <refsect1>
+    <title>Configuration Format</title>
+
+    <para>Each file contains a list of entries separated by whitespace (spaces, tabs, or newlines). Empty
+    lines and comments (lines starting with <literal>#</literal> or <literal>;</literal>) are ignored.
+    </para>
+
+    <para>An entry without prefix (or, equivalently, prefixed with <literal>+</literal>) adds a tag.  An
+    entry prefixed with <literal>-</literal> removes matching tags. The pattern may be a literal tag value,
+    or a shell-style glob, see
+    <citerefentry project='man-pages'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+    For example, <literal>-vendor.install.*</literal> removes all tags starting with
+    <literal>vendor.install.</literal>, <literal>-company.role=*</literal> removes any value assigned to the
+    <literal>company.role</literal> key, and <literal>-*</literal> removes all tags. Removing a tag that is
+    not set has no effect.</para>
+
+    <para>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
+    <literal><replaceable>key</replaceable>=<replaceable>value</replaceable></literal> is added and a
+    different value is already assigned to the same key, the previous assignment is replaced.</para>
+
+    <para>Each tag must be a valid machine tag, see
+    <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+    the syntax. Invalid entries are ignored with a warning, and the remaining entries are still applied.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Configuration Directories and Precedence</title>
+
+    <para>Configuration files are read from directories in <filename>/etc/</filename>,
+    <filename>/run/</filename>, <filename>/usr/local/lib/</filename>, and <filename>/usr/lib/</filename>, in
+    order of precedence, as listed in the SYNOPSIS section above. Files must have the
+    <literal>.tags</literal> extension. Files in <filename>/etc/</filename> override files with the same name
+    in <filename>/run/</filename>, <filename>/usr/local/lib/</filename>, and
+    <filename>/usr/lib/</filename>. Files in <filename>/run/</filename> override files with the same name
+    under <filename>/usr/</filename>.</para>
+
+    <para>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 <filename>/dev/null</filename> mask files in directories with lower priority.
+    </para>
+
+    <para>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
+    <literal>-</literal> entry in another file, or with <command>hostnamectl tags</command>.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Examples</title>
+    <example>
+      <title>/usr/lib/machine-tags.d/20-vendor.tags example:</title>
+
+      <programlisting># Tags declared by the OS vendor
+vendor.role=webserver
+vendor.env=production
+vendor.region=eu</programlisting>
+    </example>
+
+    <example>
+      <title>/etc/machine-tags.d/70-local.tags example:</title>
+
+      <programlisting># Drop the vendor's environment and region tags, but keep the role, and add a local tag
+-vendor.env=* -vendor.region=*
+local.rack=7</programlisting>
+    </example>
+
+    <para>After <command>hostnamectl tags --apply</command>, the configured tags include
+    <literal>local.rack=7</literal> and <literal>vendor.role=webserver</literal>, in addition to any tags
+    that were configured before.</para>
+  </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>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+    </simplelist></para>
+  </refsect1>
+
+</refentry>

man/rules/meson.build

@@ -50,6 +50,7 @@ manpages = [
  ['logind.conf', '5', ['logind.conf.d'], 'ENABLE_LOGIND'],
  ['machine-id', '5', [], ''],
  ['machine-info', '5', [], ''],
+ ['machine-tags.d', '5', [], 'ENABLE_HOSTNAMED'],
  ['machinectl', '1', [], 'ENABLE_MACHINED'],
  ['modules-load.d', '5', [], 'HAVE_KMOD'],
  ['networkctl', '1', [], 'ENABLE_NETWORKD'],

meson.build

@@ -161,6 +161,7 @@ rpmmacrosdir = get_option('rpmmacrosdir')
 if rpmmacrosdir != 'no'
         rpmmacrosdir = prefixdir / rpmmacrosdir
 endif
+machinetagsdir = prefixdir / 'lib/machine-tags.d'
 modprobedir = prefixdir / 'lib/modprobe.d'
 
 # Our own paths
@@ -276,6 +277,7 @@ conf.set_quoted('INCLUDE_DIR',                                includedir)
 conf.set_quoted('LIBDIR',                                     libdir)
 conf.set_quoted('LIBEXECDIR',                                 libexecdir)
 conf.set_quoted('KERNEL_INSTALL_DIR',                         kernelinstalldir)
+conf.set_quoted('MACHINE_TAGS_DIR',                           machinetagsdir)
 conf.set_quoted('MODPROBE_DIR',                               modprobedir)
 conf.set_quoted('MODULESLOAD_DIR',                            modulesloaddir)
 conf.set_quoted('PKGSYSCONFDIR',                              pkgsysconfdir)

src/core/systemd.pc.in

@@ -84,6 +84,8 @@ sysctldir=${sysctl_dir}
 binfmt_dir=${prefix}/lib/binfmt.d
 binfmtdir=${binfmt_dir}
 
+machine_tags_dir=${prefix}/lib/machine-tags.d
+
 modules_load_dir=${prefix}/lib/modules-load.d
 modulesloaddir=${modules_load_dir}
 

src/hostname/meson.build

@@ -22,3 +22,8 @@ install_data('org.freedesktop.hostname1.service',
              install_dir : dbussystemservicedir)
 install_data('org.freedesktop.hostname1.policy',
              install_dir : polkitpolicydir)
+
+install_emptydir(machinetagsdir)
+if install_sysconfdir
+        install_emptydir(sysconfdir / 'machine-tags.d')
+endif

src/rpm/macros.systemd.in

@@ -21,6 +21,7 @@
 %_user_tmpfilesdir {{USER_TMPFILES_DIR}}
 %_environmentdir {{ENVIRONMENT_DIR}}
 %_modulesloaddir {{MODULESLOAD_DIR}}
+%_machine_tags_dir {{MACHINE_TAGS_DIR}}
 %_modprobedir {{MODPROBE_DIR}}
 %_systemdgeneratordir {{SYSTEM_GENERATOR_DIR}}
 %_systemdusergeneratordir {{USER_GENERATOR_DIR}}