man: document that "systemctl mask" doesn't work for units whose file is in /etc

Fixes: #27965

diff --git a/man/systemctl.xml b/man/systemctl.xml
index 29e5fc65c226405df6ae24942f3697f73c12b5e4..537d0aa1571be314015728b722654ebad0c810b8 100644 (file)
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -1003,13 +1003,24 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
           <term><command>mask <replaceable>UNIT</replaceable>…</command></term>
 
           <listitem>
-            <para>Mask one or more units, as specified on the command line. This will link these unit files to
-            <filename>/dev/null</filename>, making it impossible to start them. This is a stronger version of
-            <command>disable</command>, since it prohibits all kinds of activation of the unit, including enablement
-            and manual activation. Use this option with care. This honors the <option>--runtime</option> option to only
-            mask temporarily until the next reboot of the system. The <option>--now</option> option may be used to
-            ensure that the units are also stopped. This command expects valid unit names only, it does not accept unit
-            file paths.</para>
+            <para>Mask one or more units, as specified on the command line. This will link these unit files
+            to <filename>/dev/null</filename>, making it impossible to start them. This is a stronger version
+            of <command>disable</command>, since it prohibits all kinds of activation of the unit, including
+            enablement and manual activation. Use this option with care. This honors the
+            <option>--runtime</option> option to only mask temporarily until the next reboot of the
+            system. The <option>--now</option> option may be used to ensure that the units are also
+            stopped. This command expects valid unit names only, it does not accept unit file paths.</para>
+
+            <para>Note that this will create a symlink under the unit's name in
+            <filename>/etc/systemd/system/</filename> (in case <option>--runtime</option> is not specified)
+            or <filename>/run/systemd/system/</filename> (in case <option>--runtime</option> is
+            specified). If a matching unit file already exists under these directories this operation will
+            hence fail. This means that the operation is primarily useful to mask units shipped by the vendor
+            (as those are shipped in <filename>/usr/lib/systemd/system/</filename> and not the aforementioned
+            two directories), but typically doesn't work for units created locally (as those are typically
+            placed precisely in the two aforementioned directories). Similar restrictions apply for
+            <option>--user</option> mode, in which case the directories are below the user's home directory
+            however.</para>
           </listitem>
         </varlistentry>