X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=9704d6f2277a1b645f0c510739f04a33f3f44052;hb=78eb158a20e2bee772f6e49d8b432b98f68cbb55;hp=803eff24aa691e918e0e74939ac758222d286ca3;hpb=f189ab18de69d3dee81117d7925fb370cd038f0f;p=elogind.git
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 803eff24a..9704d6f22 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -211,6 +211,10 @@
template .d/ subdirectory and reads
its .conf files.
+
+
Note that while systemd offers a flexible
dependency system between units it is recommended to
use this functionality only sparingly and instead rely
@@ -225,12 +229,17 @@
the file system namespace. If this applies, a special
way to escape the path name is used, so that the
result is usable as part of a filename. Basically,
- given a path, "/" is replaced by "-", and all
- unprintable characters and the "-" are replaced by
- C-style "\x2d" escapes. The root directory "/" is
- encoded as single dash, while otherwise the initial
- and ending "/" is removed from all paths during
- transformation. This escaping is reversible.
+ given a path, "/" is replaced by "-" and all other
+ characters which are not ASCII alphanumerics are
+ replaced by C-style "\x2d" escapes (except that "_"
+ is never replaced and "." is only replaced when it
+ would be the first character in the escaped path).
+ The root directory "/" is encoded as single dash,
+ while otherwise the initial and ending "/" are removed
+ from all paths during transformation. This escaping
+ is reversible. Properly escaped paths can be generated
+ using the systemd-escape1
+ command.
Optionally, units may be instantiated from a
template file at runtime. This allows creation of
@@ -279,7 +288,7 @@
When systemd is running in user mode
() and the variable
- $SYSTEMD_UNIT_PATH is set, this
+ $SYSTEMD_UNIT_PATH is set, the
contents of this variable overrides the unit load
path. If $SYSTEMD_UNIT_PATH ends
with an empty component (:), the
@@ -950,7 +959,11 @@
ConditionDirectoryNotEmpty=ConditionFileNotEmpty=ConditionFileIsExecutable=
- ConditionNull=
+
+
Before starting a unit
verify that the specified condition is
@@ -1080,14 +1093,15 @@
ConditionSecurity=
may be used to check whether the given
security module is enabled on the
- system. Currently the recognized values
- values are selinux,
+ system. Currently the recognized
+ values values are
+ selinux,
apparmor,
- ima and
- smack.
- The test may be negated by prepending
- an exclamation
- mark.
+ ima,
+ smack and
+ audit. The test may
+ be negated by prepending an
+ exclamation mark.ConditionCapability=
may be used to check whether the given
@@ -1229,15 +1243,6 @@
exists, is a regular file and marked
executable.
- Finally,
- ConditionNull= may
- be used to add a constant condition
- check value to the unit. It takes a
- boolean argument. If set to
- false, the condition
- will always fail, otherwise
- succeed.
-
If multiple conditions are
specified, the unit will be executed if
all of them apply (i.e. a logical AND
@@ -1263,6 +1268,38 @@
have no effect.
+
+ AssertArchitecture=
+ AssertVirtualization=
+ AssertHost=
+ AssertKernelCommandLine=
+ AssertSecurity=
+ AssertCapability=
+ AssertACPower=
+ AssertNeedsUpdate=
+ AssertFirstBoot=
+ AssertPathExists=
+ AssertPathExistsGlob=
+ AssertPathIsDirectory=
+ AssertPathIsSymbolicLink=
+ AssertPathIsMountPoint=
+ AssertPathIsReadWrite=
+ AssertDirectoryNotEmpty=
+ AssertFileNotEmpty=
+ AssertFileIsExecutable=
+
+ Similar to the
+ ConditionArchitecture=,
+ ConditionVirtualization=,
+ ... condition settings described above
+ these settings add assertion checks to
+ the start-up of the unit. However,
+ unlike the conditions settings any
+ assertion setting that is not met
+ results in failure of the start
+ job it was triggered by.
+
+
SourcePath=A path to a
@@ -1524,6 +1561,181 @@
+
+ Please note that specifiers
+ %U, %h,
+ %s are mostly useless when systemd
+ is running in system mode. PID 1 cannot query the
+ user account database for information, so the
+ specifiers only work as shortcuts for things which are
+ already specified in a different way in the unit
+ file. They are fully functional when systemd is
+ running in mode.
+
+
+
+ Examples
+
+
+ Allowing units to be enabled
+
+ The following snippet (highlighted)
+ allows a unit (e.g.
+ foo.service) to be
+ enabled via
+ systemctl enable:
+
+ [Unit]
+Description=Foo
+
+[Service]
+ExecStart=/usr/sbin/foo-daemon
+
+[Install]
+WantedBy=multi-user.target
+
+ After running
+ systemctl enable, a symlink
+ /etc/systemd/system/multi-user.target.wants/foo.service
+ linking to the actual unit will be created. It
+ tells systemd to pull in the unit when starting
+ multi-user.target. The
+ inverse systemctl disable
+ will remove that symlink again.
+
+
+
+ Overriding vendor settings
+
+ There are two methods of overriding
+ vendor settings in unit files: copying the unit
+ file from
+ /usr/lib/systemd/system
+ to /etc/systemd/system and
+ modifying the chosen settings. Alternatively,
+ one can create a directory named
+ unit.d/
+ within
+ /etc/systemd/system and
+ place a drop-in file
+ name.conf
+ there that only changes the specific settings
+ one is interested in. Note that multiple such
+ drop-in files are read if present.
+
+ The advantage of the first method is
+ that one easily overrides the complete unit,
+ the vendor unit is not parsed at all anymore.
+ It has the disadvantage that improvements to
+ the unit file by the vendor are not
+ automatically incorporated on updates.
+
+ The advantage of the second method is
+ that one only overrides the settings one
+ specifically wants, where updates to the unit
+ by the vendor automatically apply. This has the
+ disadvantage that some future updates by the
+ vendor might be incompatible with the local
+ changes.
+
+ Note that for drop-in files, if one wants
+ to remove entries from a setting that is parsed
+ as a list (and is not a dependency), such as
+ ConditionPathExists= (or
+ e.g. ExecStart= in service
+ units), one needs to first clear the list
+ before re-adding all entries except the one
+ that is to be removed. See below for an
+ example.
+
+ This also applies for user instances of
+ systemd, but with different locations for the
+ unit files. See the section on unit load paths
+ for further details.
+
+ Suppose there is a vendor-supplied unit
+ /usr/lib/systemd/system/httpd.service
+ with the following contents:
+
+ [Unit]
+Description=Some HTTP server
+After=remote-fs.target sqldb.service
+Requires=sqldb.service
+AssertPathExists=/srv/webserver
+
+[Service]
+Type=notify
+ExecStart=/usr/sbin/some-fancy-httpd-server
+Nice=5
+
+[Install]
+WantedBy=multi-user.target
+
+ Now one wants to change some settings as
+ an administrator: firstly, in the local setup,
+ /srv/webserver might not
+ exit, because the HTTP server is configured to
+ use /srv/www instead.
+ Secondly, the local configuration makes the
+ HTTP server also depend on a memory cache
+ service,
+ memcached.service, that
+ should be pulled in
+ (Requires=) and also be
+ ordered appropriately
+ (After=). Thirdly, in order
+ to harden the service a bit more, the
+ administrator would like to set the
+ PrivateTmp=
+ setting (see
+ systemd.service5
+ for details). And lastly, the administrator
+ would like to reset the niceness of the service
+ to its default value of 0.
+
+ The first possibility is to copy the unit
+ file to
+ /etc/systemd/system/httpd.service
+ and change the chosen settings:
+
+ [Unit]
+Description=Some HTTP server
+After=remote-fs.target sqldb.service memcached.service
+Requires=sqldb.service memcached.service
+AssertPathExists=/srv/www
+
+[Service]
+Type=notify
+ExecStart=/usr/sbin/some-fancy-httpd-server
+Nice=0
+PrivateTmp=yes
+
+[Install]
+WantedBy=multi-user.target
+
+ Alternatively, the administrator could
+ create a drop-in file
+ /etc/systemd/system/httpd.service.d/local.conf
+ with the following contents:
+
+ [Unit]
+After=memcached.service
+Requires=memcached.service
+# Reset all assertions and then re-add the condition we want
+AssertPathExists=
+AssertPathExists=/srv/www
+
+[Service]
+Nice=0
+PrivateTmp=yes
+
+ Note that dependencies
+ (After=, etc.) cannot be
+ reset to an empty list, so dependencies can
+ only be added in drop-ins. If you want to
+ remove dependencies, you have to override the
+ entire unit.
+
@@ -1545,7 +1757,7 @@
systemd.scope5,
systemd.slice5,
systemd.time7,
- systemd-verify1,
+ systemd-analyze1,
capabilities7,
systemd.directives7,
uname1