[systemd.git] / man / systemd.path.html

<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>systemd.path</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
    a.headerlink {
      color: #c60f0f;
      font-size: 0.8em;
      padding: 0 4px 0 4px;
      text-decoration: none;
      visibility: hidden;
    }

    a.headerlink:hover {
      background-color: #c60f0f;
      color: white;
    }

    h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
      visibility: visible;
    }
  </style><a href="index.html">Index </a>·
  <a href="systemd.directives.html">Directives </a>·
  <a href="../python-systemd/index.html">Python </a>·
  <a href="../libudev/index.html">libudev </a>·
  <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 218</span><hr><div class="refentry"><a name="systemd.path"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>systemd.path — Path unit configuration</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><p><code class="filename"><em class="replaceable"><code>path</code></em>.path</code></p></div><div class="refsect1"><a name="idm140390669445136"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p>A unit configuration file whose name ends in
                "<code class="literal">.path</code>" encodes information about
                a path monitored by systemd, for
                path-based activation.</p><p>This man page lists the configuration options
                specific to this unit type. See
                <a href="systemd.unit.html"><span class="citerefentry"><span class="refentrytitle">systemd.unit</span>(5)</span></a>
                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.</p><p>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 <code class="filename">foo.path</code> activates a
                matching service <code class="filename">foo.service</code>. The
                unit to activate may be controlled by
                <code class="varname">Unit=</code> (see below).</p><p>Internally, path units use the
                <a href="inotify.html"><span class="citerefentry"><span class="refentrytitle">inotify</span>(7)</span></a>
                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.</p><p>If a path unit is beneath another mount
                point in the file system hierarchy, a dependency
                between both units is created automatically.</p><p>Unless <code class="varname">DefaultDependencies=false</code>
                is used, path units will implicitly have dependencies of
                type <code class="varname">Conflicts=</code> and
                <code class="varname">Before=</code> on
                <code class="filename">shutdown.target</code>. 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 this option.
                </p></div><div class="refsect1"><a name="idm140390669434336"></a><h2 id="Options">Options<a class="headerlink" title="Permalink to this headline" href="#Options">¶</a></h2><p>Path files must include a [Path] section,
                which carries information about the path(s) it
                monitors. The options specific to the [Path] section
                of path units are the following:</p><div class="variablelist"><dl class="variablelist"><dt id="PathExists="><span class="term"><code class="varname">PathExists=</code>, </span><span class="term"><code class="varname">PathExistsGlob=</code>, </span><span class="term"><code class="varname">PathChanged=</code>, </span><span class="term"><code class="varname">PathModified=</code>, </span><span class="term"><code class="varname">DirectoryNotEmpty=</code></span><a class="headerlink" title="Permalink to this term" href="#PathExists=">¶</a></dt><dd><p>Defines paths to
                                monitor for certain changes:
                                <code class="varname">PathExists=</code> may be
                                used to watch the mere existence of a
                                file or directory. If the file
                                specified exists, the configured unit
                                is
                                activated. <code class="varname">PathExistsGlob=</code>
                                works similar, but checks for the
                                existence of at least one file
                                matching the globbing pattern
                                specified. <code class="varname">PathChanged=</code>
                                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. <code class="varname">PathModified=</code>
                                is similar, but additionally it is
                                activated also on simple writes to the
                                watched file.
                                <code class="varname">DirectoryNotEmpty=</code>
                                may be used to watch a directory and
                                activate the configured unit whenever
                                it contains at least one file.</p><p>The arguments of these
                                directives must be absolute file
                                system paths.</p><p>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.</p><p>If a path already exists
                                (in case of
                                <code class="varname">PathExists=</code> and
                                <code class="varname">PathExistsGlob=</code>) or
                                a directory already is not empty (in
                                case of
                                <code class="varname">DirectoryNotEmpty=</code>)
                                at the time the path unit is
                                activated, then the configured unit is
                                immediately activated as
                                well. Something similar does not apply
                                to <code class="varname">PathChanged=</code> and
                                <code class="varname">PathModified=</code>.</p><p>If the path itself or any of the
                                containing directories are not
                                accessible, <span class="command"><strong>systemd</strong></span>
                                will watch for permission changes and
                                notice that conditions are satisfied
                                when permissions allow that.
                                </p></dd><dt id="Unit="><span class="term"><code class="varname">Unit=</code></span><a class="headerlink" title="Permalink to this term" href="#Unit=">¶</a></dt><dd><p>The unit to activate
                                when any of the configured paths
                                changes. The argument is a unit name,
                                whose suffix is not
                                "<code class="literal">.path</code>". 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.</p></dd><dt id="MakeDirectory="><span class="term"><code class="varname">MakeDirectory=</code></span><a class="headerlink" title="Permalink to this term" href="#MakeDirectory=">¶</a></dt><dd><p>Takes a boolean
                                argument. If true, the directories to
                                watch are created before
                                watching. This option is ignored for
                                <code class="varname">PathExists=</code>
                                settings. Defaults to
                                <code class="option">false</code>.</p></dd><dt id="DirectoryMode="><span class="term"><code class="varname">DirectoryMode=</code></span><a class="headerlink" title="Permalink to this term" href="#DirectoryMode=">¶</a></dt><dd><p>If
                                <code class="varname">MakeDirectory=</code> is
                                enabled, use the mode specified here to
                                create the directories in
                                question. Takes an access mode in
                                octal notation. Defaults to
                                <code class="option">0755</code>.</p></dd></dl></div></div><div class="refsect1"><a name="idm140390673388432"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
                          <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
                          <a href="systemctl.html"><span class="citerefentry"><span class="refentrytitle">systemctl</span>(1)</span></a>,
                          <a href="systemd.unit.html"><span class="citerefentry"><span class="refentrytitle">systemd.unit</span>(5)</span></a>,
                          <a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a>,
                          <a href="inotify.html"><span class="citerefentry"><span class="refentrytitle">inotify</span>(7)</span></a>,
                          <a href="systemd.directives.html"><span class="citerefentry"><span class="refentrytitle">systemd.directives</span>(7)</span></a>
                  </p></div></div></body></html>
Commit	Line	Data
663996b3 MS	1	<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>systemd.path</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
	2	a.headerlink {
	3	color: #c60f0f;
	4	font-size: 0.8em;
	5	padding: 0 4px 0 4px;
	6	text-decoration: none;
	7	visibility: hidden;
	8	}
	9
	10	a.headerlink:hover {
	11	background-color: #c60f0f;
	12	color: white;
	13	}
	14
	15	h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
	16	visibility: visible;
	17	}
	18	</style><a href="index.html">Index </a>·
	19	<a href="systemd.directives.html">Directives </a>·
	20	<a href="../python-systemd/index.html">Python </a>·
	21	<a href="../libudev/index.html">libudev </a>·
f47781d8	22	<a href="../libudev/index.html">gudev </a><span style="float:right">systemd 218</span><hr><div class="refentry"><a name="systemd.path"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>systemd.path — Path unit configuration</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><p><code class="filename"><em class="replaceable"><code>path</code></em>.path</code></p></div><div class="refsect1"><a name="idm140390669445136"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p>A unit configuration file whose name ends in
14228c0d	23	"<code class="literal">.path</code>" encodes information about
663996b3 MS	24	a path monitored by systemd, for
	25	path-based activation.</p><p>This man page lists the configuration options
	26	specific to this unit type. See
	27	<a href="systemd.unit.html"><span class="citerefentry"><span class="refentrytitle">systemd.unit</span>(5)</span></a>
	28	for the common options of all unit configuration
	29	files. The common configuration items are configured
	30	in the generic [Unit] and [Install] sections. The
	31	path specific configuration options are configured in
	32	the [Path] section.</p><p>For each path file, a matching unit file must
	33	exist, describing the unit to activate when the path
	34	changes. By default, a service by the same name as the
	35	path (except for the suffix) is activated. Example: a
	36	path file <code class="filename">foo.path</code> activates a
	37	matching service <code class="filename">foo.service</code>. The
	38	unit to activate may be controlled by
	39	<code class="varname">Unit=</code> (see below).</p><p>Internally, path units use the
	40	<a href="inotify.html"><span class="citerefentry"><span class="refentrytitle">inotify</span>(7)</span></a>
	41	API to monitor file systems. Due to that, it suffers by the
	42	same limitations as inotify, and for example cannot be
	43	used to monitor files or directories changed by other
	44	machines on remote NFS file systems.</p><p>If a path unit is beneath another mount
	45	point in the file system hierarchy, a dependency
	46	between both units is created automatically.</p><p>Unless <code class="varname">DefaultDependencies=false</code>
	47	is used, path units will implicitly have dependencies of
	48	type <code class="varname">Conflicts=</code> and
	49	<code class="varname">Before=</code> on
	50	<code class="filename">shutdown.target</code>. These ensure
	51	that path units are terminated cleanly prior to system
	52	shutdown. Only path units involved with early boot or
	53	late system shutdown should disable this option.
f47781d8	54	</p></div><div class="refsect1"><a name="idm140390669434336"></a><h2 id="Options">Options<a class="headerlink" title="Permalink to this headline" href="#Options">¶</a></h2><p>Path files must include a [Path] section,
663996b3 MS	55	which carries information about the path(s) it
	56	monitors. The options specific to the [Path] section
	57	of path units are the following:</p><div class="variablelist"><dl class="variablelist"><dt id="PathExists="><span class="term"><code class="varname">PathExists=</code>, </span><span class="term"><code class="varname">PathExistsGlob=</code>, </span><span class="term"><code class="varname">PathChanged=</code>, </span><span class="term"><code class="varname">PathModified=</code>, </span><span class="term"><code class="varname">DirectoryNotEmpty=</code></span><a class="headerlink" title="Permalink to this term" href="#PathExists=">¶</a></dt><dd><p>Defines paths to
	58	monitor for certain changes:
	59	<code class="varname">PathExists=</code> may be
	60	used to watch the mere existence of a
	61	file or directory. If the file
14228c0d	62	specified exists, the configured unit
663996b3 MS	63	is
	64	activated. <code class="varname">PathExistsGlob=</code>
	65	works similar, but checks for the
	66	existence of at least one file
	67	matching the globbing pattern
	68	specified. <code class="varname">PathChanged=</code>
	69	may be used to watch a file or
	70	directory and activate the configured
	71	unit whenever it changes. It is not
	72	activated on every write to the
	73	watched file but it is activated if
	74	the file which was open for writing
	75	gets
	76	closed. <code class="varname">PathModified=</code>
	77	is similar, but additionally it is
	78	activated also on simple writes to the
	79	watched file.
	80	<code class="varname">DirectoryNotEmpty=</code>
	81	may be used to watch a directory and
	82	activate the configured unit whenever
	83	it contains at least one file.</p><p>The arguments of these
	84	directives must be absolute file
	85	system paths.</p><p>Multiple directives may be
	86	combined, of the same and of different
	87	types, to watch multiple paths. If the
	88	empty string is assigned to any of
14228c0d	89	these options, the list of paths to
663996b3 MS	90	watch is reset, and any prior
	91	assignments of these options will not
	92	have any effect.</p><p>If a path already exists
	93	(in case of
	94	<code class="varname">PathExists=</code> and
	95	<code class="varname">PathExistsGlob=</code>) or
	96	a directory already is not empty (in
	97	case of
	98	<code class="varname">DirectoryNotEmpty=</code>)
	99	at the time the path unit is
	100	activated, then the configured unit is
	101	immediately activated as
	102	well. Something similar does not apply
	103	to <code class="varname">PathChanged=</code> and
	104	<code class="varname">PathModified=</code>.</p><p>If the path itself or any of the
	105	containing directories are not
	106	accessible, <span class="command"><strong>systemd</strong></span>
	107	will watch for permission changes and
	108	notice that conditions are satisfied
	109	when permissions allow that.
	110	</p></dd><dt id="Unit="><span class="term"><code class="varname">Unit=</code></span><a class="headerlink" title="Permalink to this term" href="#Unit=">¶</a></dt><dd><p>The unit to activate
	111	when any of the configured paths
	112	changes. The argument is a unit name,
	113	whose suffix is not
14228c0d	114	"<code class="literal">.path</code>". If not
663996b3 MS	115	specified, this value defaults to a
	116	service that has the same name as the
	117	path unit, except for the suffix. (See
	118	above.) It is recommended that the
	119	unit name that is activated and the
	120	unit name of the path unit are named
	121	identical, except for the
	122	suffix.</p></dd><dt id="MakeDirectory="><span class="term"><code class="varname">MakeDirectory=</code></span><a class="headerlink" title="Permalink to this term" href="#MakeDirectory=">¶</a></dt><dd><p>Takes a boolean
14228c0d	123	argument. If true, the directories to
663996b3 MS	124	watch are created before
	125	watching. This option is ignored for
	126	<code class="varname">PathExists=</code>
	127	settings. Defaults to
	128	<code class="option">false</code>.</p></dd><dt id="DirectoryMode="><span class="term"><code class="varname">DirectoryMode=</code></span><a class="headerlink" title="Permalink to this term" href="#DirectoryMode=">¶</a></dt><dd><p>If
	129	<code class="varname">MakeDirectory=</code> is
14228c0d	130	enabled, use the mode specified here to
663996b3 MS	131	create the directories in
	132	question. Takes an access mode in
	133	octal notation. Defaults to
f47781d8	134	<code class="option">0755</code>.</p></dd></dl></div></div><div class="refsect1"><a name="idm140390673388432"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
663996b3	135	<a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
5eef597e	136	<a href="systemctl.html"><span class="citerefentry"><span class="refentrytitle">systemctl</span>(1)</span></a>,
663996b3 MS	137	<a href="systemd.unit.html"><span class="citerefentry"><span class="refentrytitle">systemd.unit</span>(5)</span></a>,
	138	<a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a>,
	139	<a href="inotify.html"><span class="citerefentry"><span class="refentrytitle">inotify</span>(7)</span></a>,
	140	<a href="systemd.directives.html"><span class="citerefentry"><span class="refentrytitle">systemd.directives</span>(7)</span></a>
	141	</p></div></div></body></html>