SymbX/systemd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #6840 from keszybz/more-docs

Browse Source 
Some more documentation updates
This commit is contained in:
Lennart Poettering
2017-09-17 11:56:24 +02:00
committed by GitHub
parent d75b31837c 1245e4132b
commit 27cb01b0f0
9 changed files with 101 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.mailmap
+1
View File
@@ -124,3 +124,4 @@ Josef Andersson <josef.andersson@fripost.org>
Josef Andersson <l10nl18nsweja@gmail.com>
Hendrik Westerberg <hendrik@gestorf.com>
Stefan Pietsch <mail.ipv4v6@gmail.com>
Jérémy Rosen <jeremy.rosen@enst-bretagne.fr>
man/machinectl.xml
+18 -8
View File
@@ -79,17 +79,18 @@
OS kernel with the host OS, in order to run
OS userspace instances on top the host OS.</para></listitem>
<listitem><para>The host system itself</para></listitem>
<listitem><para>The host system itself.</para></listitem>
</itemizedlist>
<para>Machines are identified by names that follow the same rules
as UNIX and DNS host names, for details, see below. Machines are
instantiated from disk or file system images that frequently — but not
necessarily — carry the same name as machines running from
them. Images in this sense are considered:</para>
as UNIX and DNS host names. For details, see below.</para>
<para>Machines are instantiated from disk or file system images that
frequently — but not necessarily — carry the same name as machines running
from them. Images in this sense may be:</para>
<itemizedlist>
<listitem><para>Directory trees containing an OS, including its
<listitem><para>Directory trees containing an OS, including the
top-level directories <filename>/usr</filename>,
<filename>/etc</filename>, and so on.</para></listitem>
@@ -299,7 +300,16 @@
</varlistentry>
<xi:include href="user-system-options.xml" xpointer="host" />
<xi:include href="user-system-options.xml" xpointer="machine" />
<varlistentry>
<term><option>-M</option></term>
<term><option>--machine=</option></term>
<listitem><para>Connect to
<citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
running in a local container, to perform the specified operation within
the container.</para></listitem>
</varlistentry>
<xi:include href="standard-options.xml" xpointer="no-pager" />
<xi:include href="standard-options.xml" xpointer="no-legend" />
@@ -809,7 +819,7 @@
qcow2 or raw disk image, possibly compressed with xz, gzip or
bzip2. If the second argument (the resulting image name) is
not specified, it is automatically derived from the file
name. If the file name is passed as <literal>-</literal>, the
name. If the filename is passed as <literal>-</literal>, the
image is read from standard input, in which case the second
argument is mandatory.</para>
man/sd_is_fifo.xml
+1 -1
View File
@@ -183,7 +183,7 @@
whether the specified file descriptor refers to a special file. If
the <parameter>path</parameter> parameter is not
<constant>NULL</constant>, it is checked whether the file
descriptor is bound to the specified file name. Special files in
descriptor is bound to the specified filename. Special files in
this context are character device nodes and files in
<filename>/proc</filename> or <filename>/sys</filename>.</para>
</refsect1>
man/systemd-journald.service.xml
+48 -6
View File
@@ -70,19 +70,18 @@
<itemizedlist>
<listitem><para>Kernel log messages, via kmsg</para></listitem>
<listitem><para>Simple system log messages, via the libc
<citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
<listitem><para>Simple system log messages, via the <filename>libc</filename> <citerefentry
project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
call</para></listitem>
<listitem><para>Structured system log messages via the native
Journal API, see
<citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>4</manvolnum></citerefentry></para></listitem>
<listitem><para>Standard output and standard error of system
services</para></listitem>
<listitem><para>Standard output and standard error of service units. For further details see
below.</para></listitem>
<listitem><para>Audit records, via the audit
subsystem</para></listitem>
<listitem><para>Audit records, originating from the kernel audit subsystem</para></listitem>
</itemizedlist>
<para>The daemon will implicitly collect numerous metadata fields
@@ -111,6 +110,49 @@ systemd-tmpfiles --create --prefix /var/log/journal</programlisting>
for information about the configuration of this service.</para>
</refsect1>
<refsect1>
<title>Stream logging</title>
<para>The systemd service manager invokes all service processes with standard output and standard error connected
to the journal by default. This behaviour may be altered via the
<varname>StandardOutput=</varname>/<varname>StandardError=</varname> unit file settings, see
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. The
journal converts the log byte stream received this way into individual log records, splitting the stream at newline
(<literal>\n</literal>, ASCII <constant>10</constant>) and <constant>NUL</constant> bytes.</para>
<para>If <filename>systemd-journald.service</filename> is stopped, the stream connections associated with all
services are terminated. Further writes to those streams by the service will result in <constant>EPIPE</constant>
errors. In order to react gracefully in this case it is recommended that programs logging to standard output/error
ignore such errors. If the the <constant>SIGPIPE</constant> UNIX signal handler is not blocked or turned off, such
write attempts will also result in such process signals being generated, see
<citerefentry><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>. To mitigate this issue,
systemd service manager explicitly turns off the <constant>SIGPIPE</constant> signal for all invoked processes by
default (this may be changed for each unit individually via the <varname>IgnoreSIGPIPE=</varname> option, see
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
details). After the standard output/standard error streams have been terminated they may not be recovered until the
services they are associated with are restarted. Note that during normal operation,
<filename>systemd-journald.service</filename> stores copies of the file descriptors for those streams in the
service manager. If <filename>systemd-journald.service</filename> is restarted using <command>systemctl
restart</command> or equivalent operation instead of a pair of separate <command>systemctl stop</command> and
<command>systemctl start</command> commands (or equivalent operations), these stream connections are not terminated
and survive the restart. It is thus safe to restart <filename>systemd-journald.service</filename>, but stopping it
is not recommended.</para>
<para>Note that the log record metadata for records transferred via such standard output/error streams reflect the
metadata of the peer the stream was originally created for. If the stream connection is passed on to other
processes (such as further child processes forked off the main service process), the log records will not reflect
their metadata, but will continue to describe the original process. This is different from the other logging
transports listed above, which are inherently record based and where the metadata is always associated with the
individual record.</para>
<para>In addition to the the implicit standard output/error logging of services, stream logging is also available
via the <citerefentry><refentrytitle>systemd-cat</refentrytitle><manvolnum>1</manvolnum></citerefentry> command
line tool.</para>
<para> Currently, the number of parallel log streams <filename>systemd-journald</filename> will accept is limited
to 4096.</para>
</refsect1>
<refsect1>
<title>Signals</title>
man/systemd-networkd.service.xml
+24 -7
View File
@@ -64,13 +64,30 @@
networks, see
<citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
<para>Network configurations applied before networkd is started
are not removed, and static configuration applied by networkd is
not removed when networkd exits. Dynamic configuration applied by
networkd may also optionally be left in place on shutdown. This
ensures restarting networkd does not cut the network connection,
and, in particular, that it is safe to transition between the
initrd and the real root, and back.</para>
<para><command>systemd-networkd</command> will create network devices based
on the configuration in
<citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>
files, respecting the [Match] sections in those files.</para>
<para><command>systemd-networkd</command> will manage network addresses and
routes for any link for which it finds a <filename>.network</filename> file
with an appropriate [Match] section, see
<citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
For those links, it will flush existing network addresses and routes when
bringing up the device. Any links not matched by one of the
<filename>.network</filename> files will be ignored. It is also possible to
explicitly tell <filename>systemd-networkd</filename> to ignore a link by
using <varname>Unmanaged=yes</varname> option, see
<citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
<para>When <filename>systemd-networkd</filename> exits, it generally leaves
existing network devices and configuration intact. This makes it possible to
transition from the initrams and to restart the service without breaking
connectivity. This also means that when configuration is updated and
<filename>systemd-networkd</filename> is restarted, netdev interfaces for
which configuration was removed will not be dropped, and may need to be
cleaned up manually.</para>
</refsect1>
<refsect1><title>Configuration Files</title>
man/systemd.resource-control.xml
+1 -1
View File
@@ -506,7 +506,7 @@
<filename>/proc/devices</filename>. The latter is useful to
whitelist all current and future devices belonging to a
specific device group at once. The device group is matched
according to file name globbing rules, you may hence use the
according to filename globbing rules, you may hence use the
<literal>*</literal> and <literal>?</literal>
wildcards. Examples: <filename>/dev/sda5</filename> is a
path to a device node, referring to an ATA or SCSI block
man/systemd.service.xml
+2 -12
View File
@@ -262,7 +262,7 @@
<varlistentry>
<term><varname>PIDFile=</varname></term>
<listitem><para>Takes an absolute file name pointing to the
<listitem><para>Takes an absolute filename pointing to the
PID file of this daemon. Use of this option is recommended for
services where <varname>Type=</varname> is set to
<option>forking</option>. systemd will read the PID of the
@@ -302,7 +302,7 @@
<varname>ExecStop=</varname> are not valid.)</para>
<para>For each of the specified commands, the first argument must be an absolute path to an
executable. Optionally, this file name may be prefixed with a number of special characters:</para>
executable. Optionally, this filename may be prefixed with a number of special characters:</para>
<table>
<title>Special executable prefixes</title>
@@ -753,16 +753,6 @@
considered clean service terminations.
</para>
<para>Note that if a process has a signal handler installed
and exits by calling
<citerefentry><refentrytitle>_exit</refentrytitle><manvolnum>2</manvolnum></citerefentry>
in response to a signal, the information about the signal is
lost. Programs should instead perform cleanup and kill
themselves with the same signal instead. See
<ulink url="http://www.cons.org/cracauer/sigint.html">Proper
handling of SIGINT/SIGQUIT — How to be a proper
program</ulink>.</para>
<para>This option may appear more than once, in which case the
list of successful exit statuses is merged. If the empty
string is assigned to this option, the list is reset, all
man/systemd.unit.xml
+1 -1
View File
@@ -1137,7 +1137,7 @@
<term><varname>Alias=</varname></term>
<listitem><para>A space-separated list of additional names this unit shall be installed under. The names listed
here must have the same suffix (i.e. type) as the unit file name. This option may be specified more than once,
here must have the same suffix (i.e. type) as the unit filename. This option may be specified more than once,
in which case all listed names are used. At installation time, <command>systemctl enable</command> will create
symlinks from these names to the unit filename. Note that not all unit types support such alias names, and this
setting is not supported for them. Specifically, mount, slice, swap, and automount units do not support
man/udevadm.xml
+5 -3
View File
@@ -308,9 +308,11 @@
<term><option>-y</option></term>
<term><option>--sysname-match=<replaceable>PATH</replaceable></option></term>
<listitem>
<para>Trigger events for devices with a matching sys
device path. This option can be specified multiple times
and supports shell style pattern matching.</para>
<para>Trigger events for devices for which the last component
(i.e. the filename) of the <filename>/sys</filename> path matches
the specified <replaceable>PATH</replaceable>. This option can be
specified multiple times and also supports shell style pattern
matching.</para>
</listitem>
</varlistentry>
<varlistentry>