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