man: various man page updates

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