summaryrefslogtreecommitdiff
path: root/man
diff options
context:
space:
mode:
authorLennart Poettering <lennart@poettering.net>2010-07-03 19:54:00 +0200
committerLennart Poettering <lennart@poettering.net>2010-07-03 19:54:00 +0200
commit62adf224d1d3e225de072a2815dd50e973230f5c (patch)
tree27e8fd16e51aa779e4190a34e41ff17fea99bb89 /man
parentaf65a09126e216d468592f069aee50dfe0382d3a (diff)
man: various man page updates
Diffstat (limited to 'man')
-rw-r--r--man/daemon.xml369
-rw-r--r--man/systemd.path.xml11
-rw-r--r--man/systemd.service.xml69
-rw-r--r--man/systemd.socket.xml15
-rw-r--r--man/systemd.special.xml.in81
-rw-r--r--man/systemd.target.xml14
-rw-r--r--man/systemd.timer.xml11
-rw-r--r--man/systemd.unit.xml36
8 files changed, 505 insertions, 101 deletions
diff --git a/man/daemon.xml b/man/daemon.xml
index 1cddf38f74..853b3bb814 100644
--- a/man/daemon.xml
+++ b/man/daemon.xml
@@ -21,7 +21,7 @@
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
-<refentry id="systemd.special">
+<refentry id="daemon">
<refentryinfo>
<title>daemon</title>
@@ -55,8 +55,9 @@
functionality to other processes. Traditionally,
daemons are implemented following a scheme originating
in SysV Unix. Modern daemons should follow a simpler
- yet more powerful scheme here called "new-style"
- daemons, as implemented by systemd. </para>
+ yet more powerful scheme (here called "new-style"
+ daemons), as implemented by
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. </para>
<refsect2>
<title>SysV Daemons</title>
@@ -64,7 +65,7 @@
<para>When a traditional SysV daemon
starts, it should execute the following steps
as part of the initialization. Note that these
- steps are unnecessary for new-style daemons,
+ steps are unnecessary for new-style daemons (see below),
and should only be implemented if compatibility
with SysV is essential.</para>
@@ -80,7 +81,7 @@
<filename>/proc/self/fd</filename>,
with a fallback of iterating from file
descriptor 3 to the value returned by
- getrlimit() for
+ <function>getrlimit()</function> for
RLIMIT_NOFILE.</para></listitem>
<listitem><para>Reset all signal
@@ -91,23 +92,30 @@
SIG_DFL.</para></listitem>
<listitem><para>Reset the signal mask
- using sigprocmask().</para></listitem>
+ using
+ <function>sigprocmask()</function>.</para></listitem>
- <listitem><para>Call fork(),
+ <listitem><para>Sanitize the
+ environment block, removing or
+ resetting environment variables that
+ might negatively impact daemon
+ runtime.</para></listitem>
+
+ <listitem><para>Call <function>fork()</function>,
to create a background
process.</para></listitem>
<listitem><para>In the child, call
- setsid() to detach from any terminal
- and create an independent
- session.</para></listitem>
+ <function>setsid()</function> to
+ detach from any terminal and create an
+ independent session.</para></listitem>
<listitem><para>In the child, call
- fork() again, to ensure the daemon can
- never re-aquire a terminal
- again.</para></listitem>
+ <function>fork()</function> again, to
+ ensure the daemon can never re-aquire
+ a terminal again.</para></listitem>
- <listitem><para>Call exit() in the
+ <listitem><para>Call <function>exit()</function> in the
first child, so that only the second
child (the actual daemon process)
stays around. This ensures that the
@@ -122,7 +130,7 @@
<listitem><para>In the daemon process,
reset the umask to 0, so that the file
- modes passed to open(), mkdir() and
+ modes passed to <function>open()</function>, <function>mkdir()</function> and
suchlike directly control the access
mode of the created files and
directories.</para></listitem>
@@ -135,6 +143,23 @@
unmounted.</para></listitem>
<listitem><para>In the daemon process,
+ write the daemon PID (as returned by
+ <function>getpid()</function>) to a
+ PID file, for example
+ <filename>/var/run/foobar.pid</filename>
+ (for a hypothetical daemon "foobar"),
+ to ensure that the daemon cannot be
+ started more than once. This must be
+ implemented in race-free fashion so
+ that the PID file is only updated when
+ at the same time it is verified that
+ the PID previously stored in the PID
+ file no longer exists or belongs to a
+ foreign process. Commonly some kind of
+ file locking is employed to implement
+ this logic.</para></listitem>
+
+ <listitem><para>In the daemon process,
drop privileges, if possible and
applicable.</para></listitem>
@@ -144,21 +169,25 @@
complete. This can be implemented via
an unnamed pipe or similar
communication channel that is created
- before the first fork() and available
- in both processes.</para></listitem>
+ before the first
+ <function>fork()</function> and hence
+ available in both the original and the
+ daemon process.</para></listitem>
- <listitem><para>Call exit() in the
+ <listitem><para>Call
+ <function>exit()</function> in the
original process. The process that
invoked the daemon must be able to
- rely that this exit() happens after
- initialization is complete and all
- external communication channels
+ rely that this
+ <function>exit()</function> happens
+ after initialization is complete and
+ all external communication channels
established and
accessible.</para></listitem>
</orderedlist>
- <para>The BSD daemon() function should not be
- used, as it does only a subset of these steps.</para>
+ <para>The BSD <function>daemon()</function> function should not be
+ used, as it implements only a subset of these steps.</para>
<para>A daemon that needs to provide
compatibility with SysV systems should
@@ -190,6 +219,17 @@
execute them when run as new-style
service.</para>
+ <para>Note that new-style init systems
+ guarantee execution of daemon processes in
+ clean process contexts: it is guaranteed that
+ the environment block is sanitized, that the
+ signal handlers and mask is reset and that no
+ left-over file descriptors are passed. Daemons
+ will be executed in their own session, and
+ STDIN/STDOUT/STDERR connected to
+ <filename>/dev/null</filename> unless
+ otherwise configured. The umask is reset.</para>
+
<para>It is recommended for new-style daemons
to implement the following:</para>
@@ -207,9 +247,10 @@
this is used by the init system to
detect service errors and problems. It
is recommended to follow the exit code
- scheme as defined in LSB
- recommendations for SysV init scripts
- (http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html).</para></listitem>
+ scheme as defined in the <ulink
+ url="http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
+ recommendations for SysV init
+ scripts</ulink>.</para></listitem>
<listitem><para>As much as possible,
rely on systemd's functionality to
@@ -220,7 +261,10 @@
implementing your own, rely on
systemd's privilege dropping code
instead of implementing it in the
- daemon, and similar.</para></listitem>
+ daemon, and similar. See
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for the available
+ controls.</para></listitem>
<listitem><para>If possible and
applicable expose the daemon's control
@@ -239,8 +283,8 @@
boot-up speed; your daemon can be
restarted on failure, without losing
any bus requests, as the bus queues
- requests for activatable
- services.</para></listitem>
+ requests for activatable services. See
+ below for details.</para></listitem>
<listitem><para>If your daemon
provides services to other local
@@ -255,20 +299,21 @@
protocols (such as syslog, DNS) a
daemon implementing socket-based
activation can be restarted without
- losing a single
- request.</para></listitem>
+ losing a single request. See below for
+ details.</para></listitem>
<listitem><para>If applicable a daemon
should notify the init system about
- startup completion or status
- updates via the sd_notify()
+ startup completion or status updates
+ via the
+ <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
interface.</para></listitem>
<listitem><para>Instead of using the
- syslog() call to log directly to the
+ <function>syslog()</function> call to log directly to the
system logger, a new-style daemon may
choose to simply log to STDERR via
- fprintf(), which is then forwarded to
+ <function>fprintf()</function>, which is then forwarded to
syslog by the init system. If log
priorities are necessary these can be
encoded by prefixing individual log
@@ -276,30 +321,259 @@
(for log priority 4 "WARNING" in the
syslog priority scheme), following a
similar style as the Linux kernel's
- printk() priority system. In fact, using
- this style of logging also enables the
- init system to optionally direct all
- application logging to the kernel log
- buffer (kmsg), as accessible via
- dmesg.</para></listitem>
+ <function>printk()</function> priority system. In fact,
+ using this style of logging also
+ enables the init system to optionally
+ direct all application logging to the
+ kernel log buffer (kmsg), as
+ accessible via
+ <citerefentry><refentrytitle>dmesg</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This
+ kind of logging may be enabled by
+ setting
+ <varname>StandardError=syslog</varname>
+ in the service unit file. For details
+ see
+ <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ and
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
</orderedlist>
+
+ <para>These recommendations are similar but
+ not identical to the <ulink
+ url="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/Articles/LaunchOnDemandDaemons.html#//apple_ref/doc/uid/TP40001762-104738">Apple
+ MacOS X Daemon Requirements</ulink>.</para>
</refsect2>
<refsect2>
- <title>Bus Activation</title>
+ <title>Socket-Based Activation</title>
</refsect2>
<refsect2>
- <title>Socket Activation</title>
+ <title>Bus-Based Activation</title>
</refsect2>
<refsect2>
- <title>Writing Service Files</title>
+ <title>Path-Based Activation</title>
+ </refsect2>
+
+ <refsect2>
+ <title>Writing Systemd Unit Files</title>
+
+ <para>When writing systemd unit files, it is
+ recommended to consider the following
+ suggestions:</para>
+
+ <orderedlist>
+ <listitem><para>If possible do not use
+ the <varname>Type=forking</varname>
+ setting in service files. But if you
+ do, make sure to set the PID file path
+ using <varname>PIDFile=</varname>. See
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details.</para></listitem>
+
+ <listitem><para>If your daemon
+ registers a D-Bus name on the bus,
+ make sure to use
+ <varname>Type=dbus</varname> if
+ possible.</para></listitem>
+
+ <listitem><para>Make sure to set a
+ good human-readable description string
+ with
+ <varname>Description=</varname>.</para></listitem>
+
+ <listitem><para>Do not disable
+ <varname>DefaultDependencies=</varname>,
+ unless you really know what you do and
+ your unit is involved in early boot or
+ late system shutdown.</para></listitem>
+
+ <listitem><para>Normally, little if
+ any dependencies should need to
+ be defined explicitly. However, if you
+ do configure explicit dependencies, only refer to
+ unit names listed on
+ <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ or names introduced by your own
+ package to keep the unit file
+ operating
+ system-independent.</para></listitem>
+
+ <listitem><para>Make sure to include
+ an <literal>[Install]</literal> section including
+ installation information for the unit
+ file. See
+ <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details. To activate your service
+ on boot make sure to add a
+ <varname>WantedBy=multi-user.target</varname>
+ or
+ <varname>WantedBy=graphical.target</varname> directive.</para></listitem>
+
+ </orderedlist>
</refsect2>
<refsect2>
<title>Installing Service Files</title>
+
+ <para>At the build installation time
+ (e.g. <command>make install</command> during
+ package build) packages are recommended to
+ install their systemd unit files in the
+ directory returned by <command>pkg-config
+ systemd
+ --variable=systemdsystemnunitdir</command>
+ (for system services),
+ resp. <command>pkg-config systemd
+ --variable=systemdsessionunitdir</command>
+ (for session services). This will make the
+ services available in the system on explicit
+ request but not activate them automatically
+ during boot. Optionally, during package
+ installation (e.g. <command>rpm -i</command>
+ by the administrator) symlinks should be
+ created in the systemd configuration
+ directories via the
+ <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ tool, to activate them automatically on
+ boot.</para>
+
+ <para>Packages using
+ <citerefentry><refentrytitle>autoconf</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ are recommended to use a configure script
+ excerpt like the following to determine the
+ unit installation path during source
+ configuration:</para>
+
+ <programlisting>PKG_PROG_PKG_CONFIG
+AC_ARG_WITH([systemdsystemunitdir],
+ AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files]),
+ [], [with_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd)])
+AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])
+AM_CONDITIONAL(HAVE_SYSTEMD, [test -n "$with_systemdsystemunitdir"])</programlisting>
+
+ <para>This snippet allows automatic
+ installation of the unit files on systemd
+ machines, and optionally allows their
+ installation even on machines lacking
+ systemd. (Modification of this snippet for the
+ session unit directory is left as excercise to the
+ reader.)</para>
+
+ <para>Additionally, to ensure that
+ <command>make distcheck</command> continues to
+ work, it is recommended to add the following
+ to the top-level <filename>Makefile.am</filename>
+ file in
+ <citerefentry><refentrytitle>automake</refentrytitle><manvolnum>1</manvolnum></citerefentry>-based
+ projects:</para>
+
+ <programlisting>DISTCHECK_CONFIGURE_FLAGS = \
+ --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir)</programlisting>
+
+ <para>Finally, unit files should be installed in the system with an automake excerpt like the following:</para>
+
+ <programlisting>if HAVE_SYSTEMD
+systemdsystemunit_DATA = \
+ foobar.socket \
+ foobar.service
+endif</programlisting>
+
+ <para>In the
+ <citerefentry><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ <filename>.spec</filename> file use a snippet like
+ the following to enable/disable the service
+ during installation/deinstallation. Consult
+ the packaging guidelines of your distribution
+ for details and the equivalent for other
+ packaging managers:</para>
+
+ <programlisting>%post
+/usr/bin/systemd-install enable foobar.service foobar.socket >/dev/null 2>&amp;1 || :
+
+%preun
+if [ "$1" -eq 0 ]; then
+ /usr/bin/systemd-install disable foobar.service foobar.socket >/dev/null 2>&amp;1 || :
+fi</programlisting>
+
+ </refsect2>
+
+ <refsect2>
+ <title>Porting Existing Daemons</title>
+
+ <para>Since new-style init systems such as
+ systemd are compatible with traditional SysV
+ init systems it is not strictly necessary to
+ port existing daemons to the new
+ style. However doing this offers additional
+ functionality to the daemons as well as it
+ simplifies integration into new-style init
+ systems.</para>
+
+ <para>To port an existing SysV compatible
+ daemon the following steps are
+ recommended:</para>
+
+ <orderedlist>
+ <listitem><para>If not already
+ implemented, add an optional command
+ line switch to the daemon to disable
+ daemonization. This is useful not only
+ for using the daemon in new-style init
+ systems, but also to ease debugging.</para></listitem>
+
+ <listitem><para>If the daemon offers
+ interfaces to other software running
+ on the local system via local AF_UNIX
+ sockets, consider implementing
+ socket-based activation (see
+ above). Usually a minimal patch is
+ sufficient to implement this: Extend
+ the socket creation in the daemon code
+ so that
+ <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ is checked for already passed sockets
+ first. If sockets are passed
+ (i.e. when
+ <function>sd_listen_fds()</function>
+ returns a positive value), skip the
+ socket createn step and use the passed
+ sockets. Secondly, ensure that the
+ file-system socket nodes for local
+ AF_UNIX sockets used in the
+ socket-based activation are not
+ removed when the daemon shuts down, if
+ sockets have been passed. Third, if
+ the daemon normally closes all
+ remaining open file descriptors as
+ part of its initialization, the
+ sockets passed from the init system
+ must be spared. Since new-style init
+ systems guarantee that no left-over
+ file descriptors are passed to
+ executed processes, it might be a good
+ choice to simply skip the closing of
+ all remaining open file descriptors if
+ file descriptors are
+ passed.</para></listitem>
+
+ <listitem><para>Write and install a
+ systemd unit file for the service (and
+ the sockets if socket-based activation
+ is used, as well as a path unit file,
+ if the daemon processes a spool
+ directory), see above for
+ details.</para></listitem>
+
+ <listitem><para>If the daemon exposes
+ interfaces via D-Bus, write and
+ install a D-Bus activation file for
+ the service, see above for
+ details.</para></listitem>
+ </orderedlist>
+
</refsect2>
</refsect1>
@@ -309,8 +583,11 @@
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
diff --git a/man/systemd.path.xml b/man/systemd.path.xml
index 772190096d..d910d2c5c8 100644
--- a/man/systemd.path.xml
+++ b/man/systemd.path.xml
@@ -87,6 +87,17 @@
<para>If an path unit is beneath another mount
point in the file system hierarchy, a dependency
between both units is created automatically.</para>
+
+ <para>Unless <varname>DefaultDependencies=</varname>
+ is set to <option>false</option>, path units will
+ implicitly have dependencies of type
+ <varname>Conflicts=</varname> and
+ <varname>Before=</varname> on
+ <filename>shutdown.target</filename>. 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.</para>
</refsect1>
<refsect1>
diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index b01641f1e4..91d6d09409 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -64,27 +64,44 @@
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for the common options of all unit configuration
files. The common configuration items are configured
- in the generic [Unit] and [Install] sections. The
- service specific configuration options are configured
- in the [Service] section.</para>
+ in the generic <literal>[Unit]</literal> and
+ <literal>[Install]</literal> sections. The service
+ specific configuration options are configured in the
+ <literal>[Service]</literal> section.</para>
<para>Additional options are listed in
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
which define the execution environment the commands
are executed in.</para>
+
+ <para>Unless <varname>DefaultDependencies=</varname>
+ is set to <option>false</option>, service units will
+ implicitly have dependencies of type
+ <varname>Requires=</varname> and
+ <varname>After=</varname> on
+ <filename>basic.target</filename> as well as
+ dependencies of type <varname>Conflicts=</varname> and
+ <varname>Before=</varname> on
+ <filename>shutdown.target</filename>. These ensure
+ that normal service units pull in basic system
+ initialization, and are terminated cleanly prior to
+ system shutdown. Only services involved with early
+ boot or late system shutdown should disable this
+ option.</para>
</refsect1>
<refsect1>
<title>Options</title>
- <para>Service files must include a [Service] section,
- which carries information about the service and the
- process it supervises. A number of options that may be
- used in this section are shared with other unit
- types. These options are documented in
+ <para>Service files must include a
+ <literal>[Service]</literal> section, which carries
+ information about the service and the process it
+ supervises. A number of options that may be used in
+ this section are shared with other unit types. These
+ options are documented in
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
- options specific to the [Service] section of service
- units are the following:</para>
+ options specific to the <literal>[Service]</literal>
+ section of service units are the following:</para>
<variablelist>
<varlistentry>
@@ -143,14 +160,18 @@
<para>Behaviour of
<option>dbus</option> is similar to
- <option>simple</option>, however it
- is expected that the daemon acquires a
+ <option>simple</option>, however it is
+ expected that the daemon acquires a
name on the D-Bus bus, as configured
by
<varname>BusName=</varname>. systemd
will proceed starting follow-up units
after the D-Bus bus name has been
- acquired.</para>
+ acquired. Service units with this
+ option configured implicitly have
+ dependencies on the
+ <filename>dbus.target</filename>
+ unit.</para>
<para>Behaviour of
<option>notify</option> is similar to
@@ -163,10 +184,13 @@
starting follow-up units after this
notification message has been sent. If
this option is used
- <option>NotifyAccess=</option> (see
+ <varname>NotifyAccess=</varname> (see
below) must be set to open access to
the notification socket provided by
- systemd.</para>
+ systemd. If
+ <varname>NotifyAccess=</varname> is not
+ set, it will be implicitly set to
+ <option>main</option>.</para>
</listitem>
</varlistentry>
@@ -220,11 +244,12 @@
services. This option may not be
specified more than once. Optionally,
if the absolute file name is prefixed
- with @, the second token will be
- passed as argv[0] to the executed
- process, followed by the further
- arguments specified. Unless
- <option>Type=forking</option> is set,
+ with <literal>@</literal>, the second
+ token will be passed as
+ <literal>argv[0]</literal> to the
+ executed process, followed by the
+ further arguments specified. Unless
+ <varname>Type=forking</varname> is set,
the process started via this command
line will be considered the main
process of the
@@ -312,7 +337,7 @@
forcibly via SIGTERM, and after
another delay of this time with
SIGKILL. (See
- <option>KillMode=</option>
+ <varname>KillMode=</varname>
below.) Takes a unit-less value in seconds, or a
time span value such as "5min
20s". Pass 0 to disable the timeout
@@ -450,7 +475,7 @@
<para>Processes will first be
terminated via SIGTERM. If then after
a delay (configured via the
- <option>TimeoutSec=</option> option)
+ <varname>TimeoutSec=</varname> option)
processes still remain, the
termination request is repeated with
the SIGKILL signal. See
diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml
index 986ef8c018..6154b304e8 100644
--- a/man/systemd.socket.xml
+++ b/man/systemd.socket.xml
@@ -95,6 +95,21 @@
which services are instantiated for each incoming
connection.</para>
+ <para>Unless <varname>DefaultDependencies=</varname>
+ is set to <option>false</option>, socket units will
+ implicitly have dependencies of type
+ <varname>Requires=</varname> and
+ <varname>After=</varname> on
+ <filename>sysinit.target</filename> as well as
+ dependencies of type <varname>Conflicts=</varname> and
+ <varname>Before=</varname> on
+ <filename>shutdown.target</filename>. These ensure
+ that socket units pull in basic system
+ initialization, and are terminated cleanly prior to
+ system shutdown. Only sockets involved with early
+ boot or late system shutdown should disable this
+ option.</para>
+
<para>Socket units may be used to implement on-demand
starting of services, as well as parallelized starting
of services.</para>
diff --git a/man/systemd.special.xml.in b/man/systemd.special.xml.in
index 79c6db1a5b..49dc3892c0 100644
--- a/man/systemd.special.xml.in
+++ b/man/systemd.special.xml.in
@@ -51,6 +51,7 @@
<para><filename>basic.target</filename>,
<filename>ctrl-alt-del.target</filename>,
<filename>@SPECIAL_DBUS_SERVICE@</filename>,
+ <filename>dbus.target</filename>,
<filename>default.target</filename>,
<filename>display-manager.service</filename>,
<filename>emergency.service</filename>,
@@ -78,8 +79,8 @@
<filename>sockets.target</filename>,
<filename>swap.target</filename>,
<filename>sysinit.target</filename>,
- <filename>syslog.target</filename>,
<filename>@SPECIAL_SYSLOG_SERVICE@</filename>,
+ <filename>syslog.target</filename>,
<filename>systemd-initctl.service</filename>,
<filename>systemd-initctl.socket</filename>,
<filename>systemd-logger.service</filename>,
@@ -141,6 +142,28 @@
up systemd will connect to it
and register its
service.</para>
+
+ <para>Units should generally
+ avoid depending on this unit
+ directly and instead refer to
+ the
+ <filename>dbus.target</filename>
+ unit instead, which pulls this
+ one in directly or indirectly
+ via socket-based activation.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>dbus.target</filename></term>
+ <listitem>
+ <para>Administrators should
+ ensure that this target pulls
+ in a service unit with the
+ name or alias of
+ <filename>@SPECIAL_DBUS_SERVICE@</filename>
+ (or a socket unit that
+ activates this
+ service).</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -523,28 +546,6 @@
</listitem>
</varlistentry>
<varlistentry>
- <term><filename>syslog.target</filename></term>
- <listitem>
- <para>systemd automatically
- adds dependencies of type
- After for this target unit to
- all SysV init script service
- units with an LSB header
- referring to the
- <literal>$syslog</literal>
- facility.</para>
-
- <para>Administrators should
- ensure that this target pulls
- in a service unit with the
- name or alias of
- <filename>@SPECIAL_SYSLOG_SERVICE@</filename>
- (or a socket unit that
- activates this
- service).</para>
- </listitem>
- </varlistentry>
- <varlistentry>
<term><filename>sysinit.target</filename></term>
<listitem>
<para>A special target unit
@@ -571,11 +572,37 @@
and use it for logging if it
has been configured for
that.</para>
- <para>Applications should
- generally not depend on this
- service, and depend on
+
+ <para>Units should generally
+ avoid depending on this unit
+ directly and instead refer to
+ the
<filename>syslog.target</filename>
- instead.</para>
+ unit instead, which pulls this
+ one in directly or indirectly
+ via socket-based activation.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>syslog.target</filename></term>
+ <listitem>
+ <para>systemd automatically
+ adds dependencies of type
+ After for this target unit to
+ all SysV init script service
+ units with an LSB header
+ referring to the
+ <literal>$syslog</literal>
+ facility.</para>
+
+ <para>Administrators should
+ ensure that this target pulls
+ in a service unit with the
+ name or alias of
+ <filename>@SPECIAL_SYSLOG_SERVICE@</filename>
+ (or a socket unit that
+ activates this
+ service).</para>
</listitem>
</varlistentry>
<varlistentry>
diff --git a/man/systemd.target.xml b/man/systemd.target.xml
index 88a9e6eada..6f3bc182dc 100644
--- a/man/systemd.target.xml
+++ b/man/systemd.target.xml
@@ -76,12 +76,22 @@
dependencies between units. Among other things, target
units are a more flexible replacement for SysV
runlevels in the classic SysV init system. (And for
- compatibility reasons there exist special
+ compatibility reasons special
target units such as
- <filename>runlevel3.target</filename> which are used by
+ <filename>runlevel3.target</filename> exist which are used by
the SysV runlevel compatibility code in systemd. See
<citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for details).</para>
+
+ <para>Unless
+ <varname>DefaultDependencies=</varname> is set to
+ <option>false</option>, target units will
+ implicitly complement all configured dependencies of type
+ <varname>Wants=</varname>,
+ <varname>Requires=</varname>,
+ <varname>RequiresOverridable=</varname> with
+ dependencies of type <varname>After=</varname>.
+ </para>
</refsect1>
<refsect1>
diff --git a/man/systemd.timer.xml b/man/systemd.timer.xml
index 7a4cd34887..ef89693f14 100644
--- a/man/systemd.timer.xml
+++ b/man/systemd.timer.xml
@@ -76,6 +76,17 @@
matching service <filename>foo.service</filename>. The
unit to activate may be controlled by
<varname>Unit=</varname> (see below).</para>
+
+ <para>Unless <varname>DefaultDependencies=</varname>
+ is set to <option>false</option>, timer units will
+ implicitly have dependencies of type
+ <varname>Conflicts=</varname> and
+ <varname>Before=</varname> on
+ <filename>shutdown.target</filename>. These ensure
+ that timer units are stopped cleanly prior to system
+ shutdown. Only timer units involved with early boot or
+ late system shutdown should disable this
+ option.</para>
</refsect1>
<refsect1>
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 9c4269f3d2..26272c4410 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -215,10 +215,10 @@
<varlistentry>
<term><varname>Description=</varname></term>
<listitem><para>A free-form string
- describing the unit. This is intended for use
- in UIs wanting to show
- descriptive information along with the
- unit name.</para></listitem>
+ describing the unit. This is intended
+ for use in UIs to show descriptive
+ information along with the unit
+ name.</para></listitem>
</varlistentry>
<varlistentry>
@@ -451,6 +451,34 @@
<option>false</option>.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>DefaultDependencies=</varname></term>
+
+ <listitem><para>Takes a boolean
+ argument. If <option>true</option>
+ (the default), a few default
+ dependencies will implicitly be
+ created for the unit. The actual
+ dependencies created depend on the
+ unit type. For example, for service
+ units, these dependencies ensure that
+ the service is started only after
+ basic system initialization is
+ complete and is properly terminated on
+ system shutdown. See the respective
+ man pages for details. Generally, only
+ services involved with early boot or
+ late shutdown should set this option
+ to <option>false</option>. It is
+ highly recommended to leave this
+ option enabled for the majority of
+ common units. If set to
+ <option>false</option> this option
+ does not disable all implicit
+ dependencies, just non-essential
+ ones.</para></listitem>
+ </varlistentry>
+
</variablelist>
<para>Unit file may include a [Install] section, which