man/systemd.path.xml

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