man/systemd.path.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7
   8   This file is part of systemd.
   9
  10   Copyright 2010 Lennart Poettering
  11 -->
  12
  13 <refentry id="systemd.path">
  14   <refentryinfo>
  15     <title>systemd.path</title>
  16     <productname>systemd</productname>
  17
  18     <authorgroup>
  19       <author>
  20         <contrib>Developer</contrib>
  21         <firstname>Lennart</firstname>
  22         <surname>Poettering</surname>
  23         <email>lennart@poettering.net</email>
  24       </author>
  25     </authorgroup>
  26   </refentryinfo>
  27
  28   <refmeta>
  29     <refentrytitle>systemd.path</refentrytitle>
  30     <manvolnum>5</manvolnum>
  31   </refmeta>
  32
  33   <refnamediv>
  34     <refname>systemd.path</refname>
  35     <refpurpose>Path unit configuration</refpurpose>
  36   </refnamediv>
  37
  38   <refsynopsisdiv>
  39     <para><filename><replaceable>path</replaceable>.path</filename></para>
  40   </refsynopsisdiv>
  41
  42   <refsect1>
  43     <title>Description</title>
  44
  45     <para>A unit configuration file whose name ends in
  46     <literal>.path</literal> encodes information about a path
  47     monitored by systemd, for path-based activation.</para>
  48
  49     <para>This man page lists the configuration options specific to
  50     this unit type. See
  51     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  52     for the common options of all unit configuration files. The common
  53     configuration items are configured in the generic [Unit] and
  54     [Install] sections. The path specific configuration options are
  55     configured in the [Path] section.</para>
  56
  57     <para>For each path file, a matching unit file must exist,
  58     describing the unit to activate when the path changes. By default,
  59     a service by the same name as the path (except for the suffix) is
  60     activated. Example: a path file <filename>foo.path</filename>
  61     activates a matching service <filename>foo.service</filename>. The
  62     unit to activate may be controlled by <varname>Unit=</varname>
  63     (see below).</para>
  64
  65     <para>Internally, path units use the
  66     <citerefentry project='man-pages'><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry>
  67     API to monitor file systems. Due to that, it suffers by the same
  68     limitations as inotify, and for example cannot be used to monitor
  69     files or directories changed by other machines on remote NFS file
  70     systems.</para>
  71   </refsect1>
  72
  73   <refsect1>
  74     <title>Automatic Dependencies</title>
  75
  76     <refsect2>
  77       <title>Implicit Dependencies</title>
  78
  79       <para>The following dependencies are implicitly added:</para>
  80
  81       <itemizedlist>
  82         <listitem><para>If a path unit is beneath another mount unit in the file
  83         system hierarchy, both a requirement and an ordering dependency
  84         between both units are created automatically.</para></listitem>
  85
  86         <listitem><para>An implicit <varname>Before=</varname> dependency is added
  87         between a path unit and the unit it is supposed to activate.</para></listitem>
  88       </itemizedlist>
  89     </refsect2>
  90
  91     <refsect2>
  92       <title>Default Dependencies</title>
  93
  94       <para>The following dependencies are added unless <varname>DefaultDependencies=no</varname> is set:</para>
  95
  96       <itemizedlist>
  97         <listitem><para>Path units will automatically have dependencies of type <varname>Before=</varname> on
  98         <filename>paths.target</filename>,
  99         dependencies of type <varname>After=</varname> and <varname>Requires=</varname> on
 100         <filename>sysinit.target</filename>, and have dependencies of type <varname>Conflicts=</varname> and
 101         <varname>Before=</varname> on <filename>shutdown.target</filename>. These ensure that path units are terminated
 102         cleanly prior to system shutdown. Only path units involved with early boot or late system shutdown should
 103         disable <varname>DefaultDependencies=</varname> option.</para></listitem>
 104       </itemizedlist>
 105
 106       <para></para>
 107     </refsect2>
 108   </refsect1>
 109
 110   <refsect1>
 111     <title>Options</title>
 112
 113     <para>Path files must include a [Path] section, which carries
 114     information about the path(s) it monitors. The options specific to
 115     the [Path] section of path units are the following:</para>
 116
 117     <variablelist class='unit-directives'>
 118       <varlistentry>
 119         <term><varname>PathExists=</varname></term>
 120         <term><varname>PathExistsGlob=</varname></term>
 121         <term><varname>PathChanged=</varname></term>
 122         <term><varname>PathModified=</varname></term>
 123         <term><varname>DirectoryNotEmpty=</varname></term>
 124
 125         <listitem><para>Defines paths to monitor for certain changes:
 126         <varname>PathExists=</varname> may be used to watch the mere
 127         existence of a file or directory. If the file specified
 128         exists, the configured unit is activated.
 129         <varname>PathExistsGlob=</varname> works similar, but checks
 130         for the existence of at least one file matching the globbing
 131         pattern specified. <varname>PathChanged=</varname> may be used
 132         to watch a file or directory and activate the configured unit
 133         whenever it changes. It is not activated on every write to the
 134         watched file but it is activated if the file which was open
 135         for writing gets closed. <varname>PathModified=</varname> is
 136         similar, but additionally it is activated also on simple
 137         writes to the watched file.
 138         <varname>DirectoryNotEmpty=</varname> may be used to watch a
 139         directory and activate the configured unit whenever it
 140         contains at least one file.</para>
 141
 142         <para>The arguments of these directives must be absolute file
 143         system paths.</para>
 144
 145         <para>Multiple directives may be combined, of the same and of
 146         different types, to watch multiple paths. If the empty string
 147         is assigned to any of these options, the list of paths to
 148         watch is reset, and any prior assignments of these options
 149         will not have any effect.</para>
 150
 151         <para>If a path already exists (in case of
 152         <varname>PathExists=</varname> and
 153         <varname>PathExistsGlob=</varname>) or a directory already is
 154         not empty (in case of <varname>DirectoryNotEmpty=</varname>)
 155         at the time the path unit is activated, then the configured
 156         unit is immediately activated as well. Something similar does
 157         not apply to <varname>PathChanged=</varname> and
 158         <varname>PathModified=</varname>.</para>
 159
 160         <para>If the path itself or any of the containing directories
 161         are not accessible, <command>systemd</command> will watch for
 162         permission changes and notice that conditions are satisfied
 163         when permissions allow that. </para></listitem>
 164       </varlistentry>
 165       <varlistentry>
 166         <term><varname>Unit=</varname></term>
 167
 168         <listitem><para>The unit to activate when any of the
 169         configured paths changes. The argument is a unit name, whose
 170         suffix is not <literal>.path</literal>. If not specified, this
 171         value defaults to a service that has the same name as the path
 172         unit, except for the suffix. (See above.) It is recommended
 173         that the unit name that is activated and the unit name of the
 174         path unit are named identical, except for the
 175         suffix.</para></listitem>
 176       </varlistentry>
 177       <varlistentry>
 178         <term><varname>MakeDirectory=</varname></term>
 179
 180         <listitem><para>Takes a boolean argument. If true, the
 181         directories to watch are created before watching. This option
 182         is ignored for <varname>PathExists=</varname> settings.
 183         Defaults to <option>false</option>.</para></listitem>
 184       </varlistentry>
 185       <varlistentry>
 186         <term><varname>DirectoryMode=</varname></term>
 187
 188         <listitem><para>If <varname>MakeDirectory=</varname> is
 189         enabled, use the mode specified here to create the directories
 190         in question. Takes an access mode in octal notation. Defaults
 191         to <option>0755</option>.</para></listitem>
 192       </varlistentry>
 193     </variablelist>
 194   </refsect1>
 195
 196   <refsect1>
 197       <title>See Also</title>
 198       <para>
 199         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 200         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 201         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 202         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 203         <citerefentry project='man-pages'><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 204         <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 205       </para>
 206   </refsect1>
 207
 208 </refentry>