man/systemd.path.xml - systemd - Git at Google

 <?xml version='1.0'?> <!--*-nxml-*-->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->

 <refentry id="systemd.path" xmlns:xi="http://www.w3.org/2001/XInclude">
   <refentryinfo>
     <title>systemd.path</title>
     <productname>systemd</productname>
   </refentryinfo>

   <refmeta>
     <refentrytitle>systemd.path</refentrytitle>
     <manvolnum>5</manvolnum>
   </refmeta>

   <refnamediv>
     <refname>systemd.path</refname>
     <refpurpose>Path unit configuration</refpurpose>
   </refnamediv>

   <refsynopsisdiv>
     <para><filename><replaceable>path</replaceable>.path</filename></para>
   </refsynopsisdiv>

   <refsect1>
     <title>Description</title>

     <para>A unit configuration file whose name ends in
     <literal>.path</literal> encodes information about a path
     monitored by systemd, for path-based activation.</para>

     <para>This man page lists the configuration options specific to
     this unit type. See
     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
     for the common options of all unit configuration files. The common
     configuration items are configured in the generic [Unit] and
     [Install] sections. The path specific configuration options are
     configured in the [Path] section.</para>

     <para>For each path file, a matching unit file must exist,
     describing the unit to activate when the path changes. By default,
     a service by the same name as the path (except for the suffix) is
     activated. Example: a path file <filename>foo.path</filename>
     activates a matching service <filename>foo.service</filename>. The
     unit to activate may be controlled by <varname>Unit=</varname>
     (see below).</para>

     <para>Internally, path units use the
     <citerefentry project='man-pages'><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry>
     API to monitor file systems. Due to that, it suffers by the same
     limitations as inotify, and for example cannot be used to monitor
     files or directories changed by other machines on remote NFS file
     systems.</para>

     <para>When a service unit triggered by a path unit terminates (regardless whether it exited successfully
     or failed), monitored paths are checked immediately again, and the service accordingly restarted
     instantly. As protection against busy looping in this trigger/start cycle, a start rate limit is enforced
     on the service unit, see <varname>StartLimitIntervalSec=</varname> and
     <varname>StartLimitBurst=</varname> in
     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Unlike
     other service failures, the error condition that the start rate limit is hit is propagated from the
     service unit to the path unit and causes the path unit to fail as well, thus ending the loop.</para>
   </refsect1>

   <refsect1>
     <title>Automatic Dependencies</title>

     <refsect2>
       <title>Implicit Dependencies</title>

       <para>The following dependencies are implicitly added:</para>

       <itemizedlist>
         <listitem><para>If a path unit is beneath another mount unit in the file
         system hierarchy, both a requirement and an ordering dependency
         between both units are created automatically.</para></listitem>

         <listitem><para>An implicit <varname>Before=</varname> dependency is added
         between a path unit and the unit it is supposed to activate.</para></listitem>
       </itemizedlist>
     </refsect2>

     <refsect2>
       <title>Default Dependencies</title>

       <para>The following dependencies are added unless <varname>DefaultDependencies=no</varname> is set:</para>

       <itemizedlist>
         <listitem><para>Path units will automatically have dependencies of type <varname>Before=</varname> on
         <filename>paths.target</filename>,
         dependencies of type <varname>After=</varname> and <varname>Requires=</varname> on
         <filename>sysinit.target</filename>, and have dependencies of type <varname>Conflicts=</varname> and
         <varname>Before=</varname> on <filename>shutdown.target</filename>. These ensure that path units are terminated
         cleanly prior to system shutdown. Only path units involved with early boot or late system shutdown should
         disable <varname>DefaultDependencies=</varname> option.</para></listitem>
       </itemizedlist>

       <para></para>
     </refsect2>
   </refsect1>

   <refsect1>
     <title>Options</title>

     <para>Path unit files may include [Unit] and [Install] sections, which are described in
     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
     </para>

     <para>Path unit files must include a [Path] section, which carries information about the path or paths it
     monitors. The options specific to the [Path] section of path units are the following:</para>

     <variablelist class='unit-directives'>
       <varlistentry>
         <term><varname>PathExists=</varname></term>
         <term><varname>PathExistsGlob=</varname></term>
         <term><varname>PathChanged=</varname></term>
         <term><varname>PathModified=</varname></term>
         <term><varname>DirectoryNotEmpty=</varname></term>

         <listitem><para>Defines paths to monitor for certain changes:
         <varname>PathExists=</varname> may be used to watch the mere
         existence of a file or directory. If the file specified
         exists, the configured unit is activated.
         <varname>PathExistsGlob=</varname> works similarly, but checks
         for the existence of at least one file matching the globbing
         pattern specified. <varname>PathChanged=</varname> may be used
         to watch a file or directory and activate the configured unit
         whenever it changes. It is not activated on every write to the
         watched file but it is activated if the file which was open
         for writing gets closed. <varname>PathModified=</varname> is
         similar, but additionally it is activated also on simple
         writes to the watched file.
         <varname>DirectoryNotEmpty=</varname> may be used to watch a
         directory and activate the configured unit whenever it
         contains at least one file.</para>

         <para>The arguments of these directives must be absolute file
         system paths.</para>

         <para>Multiple directives may be combined, of the same and of
         different types, to watch multiple paths. If the empty string
         is assigned to any of these options, the list of paths to
         watch is reset, and any prior assignments of these options
         will not have any effect.</para>

         <para>If a path already exists (in case of
         <varname>PathExists=</varname> and
         <varname>PathExistsGlob=</varname>) or a directory already is
         not empty (in case of <varname>DirectoryNotEmpty=</varname>)
         at the time the path unit is activated, then the configured
         unit is immediately activated as well. Something similar does
         not apply to <varname>PathChanged=</varname> and
         <varname>PathModified=</varname>.</para>

         <para>If the path itself or any of the containing directories
         are not accessible, <command>systemd</command> will watch for
         permission changes and notice that conditions are satisfied
         when permissions allow that. </para></listitem>
       </varlistentry>
       <varlistentry>
         <term><varname>Unit=</varname></term>

         <listitem><para>The unit to activate when any of the
         configured paths changes. The argument is a unit name, whose
         suffix is not <literal>.path</literal>. If not specified, this
         value defaults to a service that has the same name as the path
         unit, except for the suffix. (See above.) It is recommended
         that the unit name that is activated and the unit name of the
         path unit are named identical, except for the
         suffix.</para></listitem>
       </varlistentry>
       <varlistentry>
         <term><varname>MakeDirectory=</varname></term>

         <listitem><para>Takes a boolean argument. If true, the
         directories to watch are created before watching. This option
         is ignored for <varname>PathExists=</varname> settings.
         Defaults to <option>false</option>.</para></listitem>
       </varlistentry>
       <varlistentry>
         <term><varname>DirectoryMode=</varname></term>

         <listitem><para>If <varname>MakeDirectory=</varname> is
         enabled, use the mode specified here to create the directories
         in question. Takes an access mode in octal notation. Defaults
         to <option>0755</option>.</para></listitem>
       </varlistentry>
       <varlistentry>
         <term><varname>TriggerLimitIntervalSec=</varname></term>
         <term><varname>TriggerLimitBurst=</varname></term>

         <listitem><para>Configures a limit on how often this path unit may be activated within a specific
         time interval. The <varname>TriggerLimitIntervalSec=</varname> may be used to configure the length of
         the time interval in the usual time units <literal>us</literal>, <literal>ms</literal>,
         <literal>s</literal>, <literal>min</literal>, <literal>h</literal>, … and defaults to 2s. See
         <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
         details on the various time units understood. The <varname>TriggerLimitBurst=</varname> setting takes
         a positive integer value and specifies the number of permitted activations per time interval, and
         defaults to 200. Set either to 0 to disable any form of trigger rate limiting. If the limit is hit,
         the unit is placed into a failure mode, and will not watch the paths anymore until restarted. Note
         that this limit is enforced before the service activation is enqueued.</para></listitem>
       </varlistentry>
     </variablelist>

     <xi:include href="systemd.service.xml" xpointer="shared-unit-options" />
   </refsect1>

   <refsect1>
       <title>See Also</title>
       <para>Environment variables with details on the trigger will be set for triggered units. See the
       <literal>Environment Variables Set on Triggered Units</literal> section in
       <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
       for more details.</para>
       <para>
         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
         <citerefentry project='man-pages'><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
         <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
       </para>
   </refsect1>

 </refentry>
	<?xml version='1.0'?> <!---nxml--->
	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
	<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->

	<refentry id="systemd.path" xmlns:xi="http://www.w3.org/2001/XInclude">
	<refentryinfo>
	<title>systemd.path</title>
	<productname>systemd</productname>
	</refentryinfo>

	<refmeta>
	<refentrytitle>systemd.path</refentrytitle>
	<manvolnum>5</manvolnum>
	</refmeta>

	<refnamediv>
	<refname>systemd.path</refname>
	<refpurpose>Path unit configuration</refpurpose>
	</refnamediv>

	<refsynopsisdiv>
	<para><filename><replaceable>path</replaceable>.path</filename></para>
	</refsynopsisdiv>

	<refsect1>
	<title>Description</title>

	<para>A unit configuration file whose name ends in
	<literal>.path</literal> encodes information about a path
	monitored by systemd, for path-based activation.</para>

	<para>This man page lists the configuration options specific to
	this unit type. See
	<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	for the common options of all unit configuration files. The common
	configuration items are configured in the generic [Unit] and
	[Install] sections. The path specific configuration options are
	configured in the [Path] section.</para>

	<para>For each path file, a matching unit file must exist,
	describing the unit to activate when the path changes. By default,
	a service by the same name as the path (except for the suffix) is
	activated. Example: a path file <filename>foo.path</filename>
	activates a matching service <filename>foo.service</filename>. The
	unit to activate may be controlled by <varname>Unit=</varname>
	(see below).</para>

	<para>Internally, path units use the
	<citerefentry project='man-pages'><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry>
	API to monitor file systems. Due to that, it suffers by the same
	limitations as inotify, and for example cannot be used to monitor
	files or directories changed by other machines on remote NFS file
	systems.</para>

	<para>When a service unit triggered by a path unit terminates (regardless whether it exited successfully
	or failed), monitored paths are checked immediately again, and the service accordingly restarted
	instantly. As protection against busy looping in this trigger/start cycle, a start rate limit is enforced
	on the service unit, see <varname>StartLimitIntervalSec=</varname> and
	<varname>StartLimitBurst=</varname> in
	<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Unlike
	other service failures, the error condition that the start rate limit is hit is propagated from the
	service unit to the path unit and causes the path unit to fail as well, thus ending the loop.</para>
	</refsect1>

	<refsect1>
	<title>Automatic Dependencies</title>

	<refsect2>
	<title>Implicit Dependencies</title>

	<para>The following dependencies are implicitly added:</para>

	<itemizedlist>
	<listitem><para>If a path unit is beneath another mount unit in the file
	system hierarchy, both a requirement and an ordering dependency
	between both units are created automatically.</para></listitem>

	<listitem><para>An implicit <varname>Before=</varname> dependency is added
	between a path unit and the unit it is supposed to activate.</para></listitem>
	</itemizedlist>
	</refsect2>

	<refsect2>
	<title>Default Dependencies</title>

	<para>The following dependencies are added unless <varname>DefaultDependencies=no</varname> is set:</para>

	<itemizedlist>
	<listitem><para>Path units will automatically have dependencies of type <varname>Before=</varname> on
	<filename>paths.target</filename>,
	dependencies of type <varname>After=</varname> and <varname>Requires=</varname> on
	<filename>sysinit.target</filename>, and have dependencies of type <varname>Conflicts=</varname> and
	<varname>Before=</varname> on <filename>shutdown.target</filename>. These ensure that path units are terminated
	cleanly prior to system shutdown. Only path units involved with early boot or late system shutdown should
	disable <varname>DefaultDependencies=</varname> option.</para></listitem>
	</itemizedlist>

	<para></para>
	</refsect2>
	</refsect1>

	<refsect1>
	<title>Options</title>

	<para>Path unit files may include [Unit] and [Install] sections, which are described in
	<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
	</para>

	<para>Path unit files must include a [Path] section, which carries information about the path or paths it
	monitors. The options specific to the [Path] section of path units are the following:</para>

	<variablelist class='unit-directives'>
	<varlistentry>
	<term><varname>PathExists=</varname></term>
	<term><varname>PathExistsGlob=</varname></term>
	<term><varname>PathChanged=</varname></term>
	<term><varname>PathModified=</varname></term>
	<term><varname>DirectoryNotEmpty=</varname></term>

	<listitem><para>Defines paths to monitor for certain changes:
	<varname>PathExists=</varname> may be used to watch the mere
	existence of a file or directory. If the file specified
	exists, the configured unit is activated.
	<varname>PathExistsGlob=</varname> works similarly, but checks
	for the existence of at least one file matching the globbing
	pattern specified. <varname>PathChanged=</varname> may be used
	to watch a file or directory and activate the configured unit
	whenever it changes. It is not activated on every write to the
	watched file but it is activated if the file which was open
	for writing gets closed. <varname>PathModified=</varname> is
	similar, but additionally it is activated also on simple
	writes to the watched file.
	<varname>DirectoryNotEmpty=</varname> may be used to watch a
	directory and activate the configured unit whenever it
	contains at least one file.</para>

	<para>The arguments of these directives must be absolute file
	system paths.</para>

	<para>Multiple directives may be combined, of the same and of
	different types, to watch multiple paths. If the empty string
	is assigned to any of these options, the list of paths to
	watch is reset, and any prior assignments of these options
	will not have any effect.</para>

	<para>If a path already exists (in case of
	<varname>PathExists=</varname> and
	<varname>PathExistsGlob=</varname>) or a directory already is
	not empty (in case of <varname>DirectoryNotEmpty=</varname>)
	at the time the path unit is activated, then the configured
	unit is immediately activated as well. Something similar does
	not apply to <varname>PathChanged=</varname> and
	<varname>PathModified=</varname>.</para>

	<para>If the path itself or any of the containing directories
	are not accessible, <command>systemd</command> will watch for
	permission changes and notice that conditions are satisfied
	when permissions allow that. </para></listitem>
	</varlistentry>
	<varlistentry>
	<term><varname>Unit=</varname></term>

	<listitem><para>The unit to activate when any of the
	configured paths changes. The argument is a unit name, whose
	suffix is not <literal>.path</literal>. If not specified, this
	value defaults to a service that has the same name as the path
	unit, except for the suffix. (See above.) It is recommended
	that the unit name that is activated and the unit name of the
	path unit are named identical, except for the
	suffix.</para></listitem>
	</varlistentry>
	<varlistentry>
	<term><varname>MakeDirectory=</varname></term>

	<listitem><para>Takes a boolean argument. If true, the
	directories to watch are created before watching. This option
	is ignored for <varname>PathExists=</varname> settings.
	Defaults to <option>false</option>.</para></listitem>
	</varlistentry>
	<varlistentry>
	<term><varname>DirectoryMode=</varname></term>

	<listitem><para>If <varname>MakeDirectory=</varname> is
	enabled, use the mode specified here to create the directories
	in question. Takes an access mode in octal notation. Defaults
	to <option>0755</option>.</para></listitem>
	</varlistentry>
	<varlistentry>
	<term><varname>TriggerLimitIntervalSec=</varname></term>
	<term><varname>TriggerLimitBurst=</varname></term>

	<listitem><para>Configures a limit on how often this path unit may be activated within a specific
	time interval. The <varname>TriggerLimitIntervalSec=</varname> may be used to configure the length of
	the time interval in the usual time units <literal>us</literal>, <literal>ms</literal>,
	<literal>s</literal>, <literal>min</literal>, <literal>h</literal>, … and defaults to 2s. See
	<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
	details on the various time units understood. The <varname>TriggerLimitBurst=</varname> setting takes
	a positive integer value and specifies the number of permitted activations per time interval, and
	defaults to 200. Set either to 0 to disable any form of trigger rate limiting. If the limit is hit,
	the unit is placed into a failure mode, and will not watch the paths anymore until restarted. Note
	that this limit is enforced before the service activation is enqueued.</para></listitem>
	</varlistentry>
	</variablelist>

	<xi:include href="systemd.service.xml" xpointer="shared-unit-options" />
	</refsect1>

	<refsect1>
	<title>See Also</title>
	<para>Environment variables with details on the trigger will be set for triggered units. See the
	<literal>Environment Variables Set on Triggered Units</literal> section in
	<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	for more details.</para>
	<para>
	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	<citerefentry project='man-pages'><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
	</para>
	</refsect1>

	</refentry>