diff options
Diffstat (limited to 'man')
57 files changed, 1622 insertions, 350 deletions
diff --git a/man/busctl.xml b/man/busctl.xml index d8c1085021..26d778d4dd 100644 --- a/man/busctl.xml +++ b/man/busctl.xml @@ -448,7 +448,7 @@ ARRAY "s" { <example> <title>Invoking a Method</title> - <para>The following command invokes a the + <para>The following command invokes the <literal>StartUnit</literal> method on the <literal>org.freedesktop.systemd1.Manager</literal> interface of the diff --git a/man/dnssec-trust-anchors.d.xml b/man/dnssec-trust-anchors.d.xml new file mode 100644 index 0000000000..4bdc167f79 --- /dev/null +++ b/man/dnssec-trust-anchors.d.xml @@ -0,0 +1,200 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="dnssec-trust-anchors.d" conditional='ENABLE_RESOLVED' + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>dnssec-trust-anchors.d</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>dnssec-trust-anchors.d</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>dnssec-trust-anchors.d</refname> + <refname>systemd.positive</refname> + <refname>systemd.negative</refname> + <refpurpose>DNSSEC trust anchor configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/dnssec-trust-anchors.d/*.positive</filename></para> + <para><filename>/run/dnssec-trust-anchors.d/*.positive</filename></para> + <para><filename>/usr/lib/dnssec-trust-anchors.d/*.positive</filename></para> + <para><filename>/etc/dnssec-trust-anchors.d/*.negative</filename></para> + <para><filename>/run/dnssec-trust-anchors.d/*.negative</filename></para> + <para><filename>/usr/lib/dnssec-trust-anchors.d/*.negative</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The DNSSEC trust anchor configuration files define positive + and negative trust anchors + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + bases DNSSEC integrity proofs on.</para> + </refsect1> + + <refsect1> + <title>Positive Trust Anchors</title> + + <para>Positive trust anchor configuration files contain DNSKEY and + DS resource record definitions to use as base for DNSSEC integrity + proofs. See <ulink + url="https://tools.ietf.org/html/rfc4035#section-4.4">RFC 4035, + Section 4.4</ulink> for more information about DNSSEC trust + anchors.</para> + + <para>Positive trust anchors are read from files with the suffix + <filename>.positive</filename> located in + <filename>/etc/dnssec-trust-anchors.d/</filename>, + <filename>/run/dnssec-trust-anchors.d/</filename> and + <filename>/usr/lib/dnssec-trust-anchors.d/</filename>. These + directories are searched in the specified order, and a trust + anchor file of the same name in an earlier path overrides a trust + anchor files in a later path. To disable a trust anchor file + shipped in <filename>/usr/lib/dnssec-trust-anchors.d/</filename> + it is sufficient to provide an identically-named file in + <filename>/etc/dnssec-trust-anchors.d/</filename> or + <filename>/run/dnssec-trust-anchors.d/</filename> that is either + empty or a symlink to <filename>/dev/null</filename> ("masked").</para> + + <para>Positive trust anchor files are simple text files resembling + DNS zone files, as documented in <ulink + url="https://tools.ietf.org/html/rfc1035#section-5">RFC 1035, Section + 5</ulink>. One DS or DNSKEY resource record may be listed per + line. Empty lines and lines starting with a semicolon + (<literal>;</literal>) are ignored and considered comments. A DS + resource record is specified like in the following example:</para> + + <programlisting>. IN DS 19036 8 2 49aac11d7b6f6446702e54a1607371607a1a41855200fd2ce1cdde32f24e8fb5</programlisting> + + <para>The first word specifies the domain, use + <literal>.</literal> for the root domain. The domain may be + specified with or without trailing dot, which is considered + equivalent. The second word must be <literal>IN</literal> the + third word <literal>DS</literal>. The following words specify the + key tag, signature algorithm, digest algorithm, followed by the + hex-encoded key fingerprint. See <ulink + url="https://tools.ietf.org/html/rfc4034#section-5">RFC 4034, + Section 5</ulink> for details about the precise syntax and meaning + of these fields.</para> + + <para>Alternatively, DNSKEY resource records may be used to define + trust anchors, like in the following example:</para> + + <programlisting>. IN DNSKEY 257 3 8 AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0=</programlisting> + + <para>The first word specifies the domain again, the second word + must be <literal>IN</literal>, followed by + <literal>DNSKEY</literal>. The subsequent words encode the DNSKEY + flags, protocol and algorithm fields, followed by the key data + encoded in Base64. See <ulink + url="https://tools.ietf.org/html/rfc4034#section-2">RFC 4034, + Section 2</ulink> for details about the precise syntax and meaning + of these fields.</para> + + <para>If multiple DS or DNSKEY records are defined for the same + domain (possibly even in different trust anchor files), all keys + are used and are considered equivalent as base for DNSSEC + proofs.</para> + + <para>Note that <filename>systemd-resolved</filename> will + automatically use a built-in trust anchor key for the Internet + root domain if no positive trust anchors are defined for the root + domain. In most cases it is hence unnecessary to define an + explicit key with trust anchor files. The built-in key is disabled + as soon as at least one trust anchor key for the root domain is + defined in trust anchor files.</para> + + <para>It is generally recommended to encode trust anchors in DS + resource records, rather than DNSKEY resource records.</para> + + <para>If a trust anchor specified via a DS record is found revoked + it is automatically removed from the trust anchor database for the + runtime. See <ulink url="https://tools.ietf.org/html/rfc5011">RFC + 5011</ulink> for details about revoked trust anchors. Note that + <filename>systemd-resolved</filename> will not update its trust + anchor database from DNS servers automatically. Instead, it is + recommended to update the resolver software or update the new + trust anchor via adding in new trust anchor files.</para> + + <para>The current DNSSEC trust anchor for the Internet's root + domain is available at the <ulink + url="https://data.iana.org/root-anchors/root-anchors.xml">IANA + Trust Anchor and Keys</ulink> page.</para> + </refsect1> + + <refsect1> + <title>Negative Trust Anchors</title> + + <para>Negative trust anchors define domains where DNSSEC + validation shall be turned off. Negative trust anchor files are + found at the same location as positive trust anchor files, and + follow the same overriding rules. They are text files with the + <filename>.negative</filename> suffix. Empty lines and lines whose + first character is <literal>;</literal> are ignored. Each line + specifies one domain name where DNSSEC validation shall be + disabled on.</para> + + <para>Negative trust anchors are useful to support private DNS + subtrees that are not referenced from the Internet DNS hierarchy, + and not signed.</para> + + <para><ulink url="https://tools.ietf.org/html/rfc7646">RFC + 7646</ulink> for details on negative trust anchors.</para> + + <para>If no negative trust anchor files are configured a built-in + set of well-known private DNS zone domains is used as negative + trust anchors.</para> + + <para>It is also possibly to define per-interface negative trust + anchors using the <varname>DNSSECNegativeTrustAnchors=</varname> + setting in + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> + files.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/file-hierarchy.xml b/man/file-hierarchy.xml index 345c56cefa..538a592f8d 100644 --- a/man/file-hierarchy.xml +++ b/man/file-hierarchy.xml @@ -63,7 +63,7 @@ and restrictions systemd makes on the file system hierarchy.</para> - <para>Many of the paths described here are queriable + <para>Many of the paths described here can be queried with the <citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry> tool.</para> diff --git a/man/journal-remote.conf.xml b/man/journal-remote.conf.xml index fc60258d0b..2d345963d9 100644 --- a/man/journal-remote.conf.xml +++ b/man/journal-remote.conf.xml @@ -72,6 +72,13 @@ <literal>[Remote]</literal> section:</para> <variablelist> + <varlistentry> + <term><varname>Seal=</varname></term> + + <listitem><para>Periodically sign the data in the journal using Forward Secure Sealing. + </para></listitem> + </varlistentry> + <varlistentry> <term><varname>SplitMode=</varname></term> @@ -105,7 +112,7 @@ <refsect1> <title>See Also</title> <para> - <citerefentry><refentrytitle>systemd-journal-remote</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-journal-remote</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> </para> diff --git a/man/journalctl.xml b/man/journalctl.xml index b57afb6ebf..b281f26b45 100644 --- a/man/journalctl.xml +++ b/man/journalctl.xml @@ -91,8 +91,14 @@ paths may be specified. If a file path refers to an executable file, this is equivalent to an <literal>_EXE=</literal> match for the canonicalized binary path. Similarly, if a path refers - to a device node, this is equivalent to a - <literal>_KERNEL_DEVICE=</literal> match for the device.</para> + to a device node then match is added for the kernel name of the + device (<literal>_KERNEL_DEVICE=</literal>). Also, matches for the + kernel names of all the parent devices are added automatically. + Device node paths are not stable across reboots, therefore match + for the current boot id (<literal>_BOOT_ID=</literal>) is + always added as well. Note that only the log entries for + the existing device nodes maybe queried by providing path to + the device node.</para> <para>Additional constraints may be added using options <option>--boot</option>, <option>--unit=</option>, etc., to @@ -572,6 +578,13 @@ </varlistentry> <varlistentry> + <term><option>-N</option></term> + <term><option>--fields</option></term> + + <listitem><para>Print all field names currently used in all entries of the journal.</para></listitem> + </varlistentry> + + <varlistentry> <term><option>--system</option></term> <term><option>--user</option></term> diff --git a/man/kernel-command-line.xml b/man/kernel-command-line.xml index 309220632e..42d5e006bb 100644 --- a/man/kernel-command-line.xml +++ b/man/kernel-command-line.xml @@ -91,6 +91,7 @@ <term><varname>systemd.default_standard_output=</varname></term> <term><varname>systemd.default_standard_error=</varname></term> <term><varname>systemd.setenv=</varname></term> + <term><varname>systemd.machine_id=</varname></term> <listitem> <para>Parameters understood by the system and service manager to control system behavior. For details, see diff --git a/man/logind.conf.xml b/man/logind.conf.xml index 94376656d5..597759e33a 100644 --- a/man/logind.conf.xml +++ b/man/logind.conf.xml @@ -288,21 +288,17 @@ <varname>TasksMax=</varname> setting of the per-user slice unit, see <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. Defaults to 4096.</para></listitem> + for details. Defaults to 12288 (12K).</para></listitem> </varlistentry> <varlistentry> <term><varname>RemoveIPC=</varname></term> - <listitem><para>Controls whether System V and POSIX IPC - objects belonging to the user shall be removed when the user - fully logs out. Takes a boolean argument. If enabled, the user - may not consume IPC resources after the last of the user's - sessions terminated. This covers System V semaphores, shared - memory and message queues, as well as POSIX shared memory and - message queues. Note that IPC objects of the root user are - excluded from the effect of this setting. Defaults to - <literal>yes</literal>.</para></listitem> + <listitem><para>Controls whether System V and POSIX IPC objects belonging to the user shall be removed when the + user fully logs out. Takes a boolean argument. If enabled, the user may not consume IPC resources after the + last of the user's sessions terminated. This covers System V semaphores, shared memory and message queues, as + well as POSIX shared memory and message queues. Note that IPC objects of the root user and other system users + are excluded from the effect of this setting. Defaults to <literal>yes</literal>.</para></listitem> </varlistentry> </variablelist> diff --git a/man/machine-id.xml b/man/machine-id.xml index db72c2a01c..d318ec54ec 100644 --- a/man/machine-id.xml +++ b/man/machine-id.xml @@ -84,6 +84,12 @@ at install time. Use <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> to initialize it on mounted (but not booted) system images.</para> + + <para>The machine-id may also be set, for example when network + booting, by setting the <varname>systemd.machine_id=</varname> + kernel command line parameter or passing the option + <option>--machine-id=</option> to systemd. A machine-id may not + be set to all zeros.</para> </refsect1> <refsect1> diff --git a/man/machinectl.xml b/man/machinectl.xml index a7288c249b..0e07c201bd 100644 --- a/man/machinectl.xml +++ b/man/machinectl.xml @@ -247,7 +247,7 @@ <literal>checksum</literal> is specified, the download is checked for integrity after the transfer is complete, but no signatures are verified. If <literal>signature</literal> is - specified, the checksum is verified and the images's signature + specified, the checksum is verified and the image's signature is checked against a local keyring of trustable vendors. It is strongly recommended to set this option to <literal>signature</literal> if the server and protocol @@ -768,10 +768,9 @@ image is read from standard input, in which case the second argument is mandatory.</para> - <para>Similar as with <command>pull-tar</command>, - <command>pull-raw</command> the file system - <filename>/var/lib/machines.raw</filename> is increased in - size of necessary and appropriate. Optionally, the + <para>Both <command>pull-tar</command> and <command>pull-raw</command> + will resize <filename>/var/lib/machines.raw</filename> and the + filesystem therein as necessary. Optionally, the <option>--read-only</option> switch may be used to create a read-only container or VM image. No cryptographic validation is done when importing the images.</para> diff --git a/man/resolved.conf.xml b/man/resolved.conf.xml index 4680b6a4e5..920ce9e89b 100644 --- a/man/resolved.conf.xml +++ b/man/resolved.conf.xml @@ -68,44 +68,46 @@ <refsect1> <title>Options</title> + <para>The following options are available in the <literal>[Resolve]</literal> section:</para> + <variablelist class='network-directives'> <varlistentry> <term><varname>DNS=</varname></term> - <listitem><para>A space-separated list of IPv4 and IPv6 - addresses to be used as system DNS servers. DNS requests are - sent to one of the listed DNS servers in parallel to any - per-interface DNS servers acquired from - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - For compatibility reasons, if this setting is not specified, - the DNS servers listed in - <filename>/etc/resolv.conf</filename> are used instead, if - that file exists and any servers are configured in it. This - setting defaults to the empty list.</para></listitem> + <listitem><para>A space-separated list of IPv4 and IPv6 addresses to use as system DNS servers. DNS requests + are sent to one of the listed DNS servers in parallel to suitable per-link DNS servers acquired from + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> or + set at runtime by external applications. For compatibility reasons, if this setting is not specified, the DNS + servers listed in <filename>/etc/resolv.conf</filename> are used instead, if that file exists and any servers + are configured in it. This setting defaults to the empty list.</para></listitem> </varlistentry> <varlistentry> <term><varname>FallbackDNS=</varname></term> - <listitem><para>A space-separated list of IPv4 and IPv6 - addresses to be used as the fallback DNS servers. Any - per-interface DNS servers obtained from + <listitem><para>A space-separated list of IPv4 and IPv6 addresses to use as the fallback DNS servers. Any + per-link DNS servers obtained from <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - take precedence over this setting, as do any servers set via - <varname>DNS=</varname> above or - <filename>/etc/resolv.conf</filename>. This setting is hence - only used if no other DNS server information is known. If this - option is not given, a compiled-in list of DNS servers is used - instead.</para></listitem> + take precedence over this setting, as do any servers set via <varname>DNS=</varname> above or + <filename>/etc/resolv.conf</filename>. This setting is hence only used if no other DNS server information is + known. If this option is not given, a compiled-in list of DNS servers is used instead.</para></listitem> </varlistentry> <varlistentry> <term><varname>Domains=</varname></term> - <listitem><para>A space-separated list of search domains. For - compatibility reasons, if this setting is not specified, the - search domains listed in <filename>/etc/resolv.conf</filename> - are used instead, if that file exists and any domains are - configured in it. This setting defaults to the empty - list.</para></listitem> + <listitem><para>A space-separated list of domains. These domains are used as search suffixes when resolving + single-label host names (domain names which contain no dot), in order to qualify them into fully-qualified + domain names (FQDNs). Search domains are strictly processed in the order they are specified, until the name + with the suffix appended is found. For compatibility reasons, if this setting is not specified, the search + domains listed in <filename>/etc/resolv.conf</filename> are used instead, if that file exists and any domains + are configured in it. This setting defaults to the empty list.</para> + + <para>Specified domain names may optionally be prefixed with <literal>~</literal>. In this case they do not + define a search path, but preferably direct DNS queries for the indicated domains to the DNS servers configured + with the system <varname>DNS=</varname> setting (see above), in case additional, suitable per-link DNS servers + are known. If no per-link DNS servers are known using the <literal>~</literal> syntax has no effect. Use the + construct <literal>~.</literal> (which is composed of <literal>~</literal> to indicate a routing domain and + <literal>.</literal> to indicate the DNS root domain that is the implied suffix of all DNS domains) to use the + system DNS server defined with <varname>DNS=</varname> preferably for all domains.</para></listitem> </varlistentry> <varlistentry> @@ -119,11 +121,87 @@ <literal>resolve</literal>, only resolution support is enabled, but responding is disabled. Note that <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - also maintains per-interface LLMNR settings. LLMNR will be - enabled on an interface only if the per-interface and the + also maintains per-link LLMNR settings. LLMNR will be + enabled on a link only if the per-link and the global setting is on.</para></listitem> </varlistentry> + <varlistentry> + <term><varname>DNSSEC=</varname></term> + <listitem><para>Takes a boolean argument or + <literal>allow-downgrade</literal>. If true all DNS lookups are + DNSSEC-validated locally (excluding LLMNR and Multicast + DNS). If the response to a lookup request is detected to be invalid + a lookup failure is returned to applications. Note that + this mode requires a DNS server that supports DNSSEC. If the + DNS server does not properly support DNSSEC all validations + will fail. If set to <literal>allow-downgrade</literal> DNSSEC + validation is attempted, but if the server does not support + DNSSEC properly, DNSSEC mode is automatically disabled. Note + that this mode makes DNSSEC validation vulnerable to + "downgrade" attacks, where an attacker might be able to + trigger a downgrade to non-DNSSEC mode by synthesizing a DNS + response that suggests DNSSEC was not supported. If set to + false, DNS lookups are not DNSSEC validated.</para> + + <para>Note that DNSSEC validation requires retrieval of + additional DNS data, and thus results in a small DNS look-up + time penalty.</para> + + <para>DNSSEC requires knowledge of "trust anchors" to prove + data integrity. The trust anchor for the Internet root domain + is built into the resolver, additional trust anchors may be + defined with + <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Trust anchors may change at regular intervals, and old trust + anchors may be revoked. In such a case DNSSEC validation is + not possible until new trust anchors are configured locally or + the resolver software package is updated with the new root + trust anchor. In effect, when the built-in trust anchor is + revoked and <varname>DNSSEC=</varname> is true, all further + lookups will fail, as it cannot be proved anymore whether + lookups are correctly signed, or validly unsigned. If + <varname>DNSSEC=</varname> is set to + <literal>allow-downgrade</literal> the resolver will + automatically turn off DNSSEC validation in such a case.</para> + + <para>Client programs looking up DNS data will be informed + whether lookups could be verified using DNSSEC, or whether the + returned data could not be verified (either because the data + was found unsigned in the DNS, or the DNS server did not + support DNSSEC or no appropriate trust anchors were known). In + the latter case it is assumed that client programs employ a + secondary scheme to validate the returned DNS data, should + this be required.</para> + + <para>It is recommended to set <varname>DNSSEC=</varname> to + true on systems where it is known that the DNS server supports + DNSSEC correctly, and where software or trust anchor updates + happen regularly. On other systems it is recommended to set + <varname>DNSSEC=</varname> to + <literal>allow-downgrade</literal>.</para> + + <para>In addition to this global DNSSEC setting + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + also maintains per-link DNSSEC settings. For system DNS + servers (see above), only the global DNSSEC setting is in + effect. For per-link DNS servers the per-link + setting is in effect, unless it is unset in which case the + global setting is used instead.</para> + + <para>Site-private DNS zones generally conflict with DNSSEC + operation, unless a negative (if the private zone is not + signed) or positive (if the private zone is signed) trust + anchor is configured for them. If + <literal>allow-downgrade</literal> mode is selected, it is + attempted to detect site-private DNS zones using top-level + domains (TLDs) that are not known by the DNS root server. This + logic does not work in all private zone setups.</para> + + <para>Defaults to off.</para> + </listitem> + </varlistentry> + </variablelist> </refsect1> @@ -133,7 +211,8 @@ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>resolv.conf</refentrytitle><manvolnum>4</manvolnum></citerefentry> + <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>4</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd-bus.xml b/man/sd-bus.xml new file mode 100644 index 0000000000..336dd33ea0 --- /dev/null +++ b/man/sd-bus.xml @@ -0,0 +1,123 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd-bus" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd-bus</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Documentation</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd-bus</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd-bus</refname> + <refpurpose>A lightweight D-Bus and kdbus client library</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + </funcsynopsis> + + <cmdsynopsis> + <command>pkg-config --cflags --libs libsystemd</command> + </cmdsynopsis> + + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>sd-bus.h</filename> provides an implementation + of a D-Bus client. It can interoperate both with the traditional + <citerefentry project='man-pages'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + and with kdbus. See + <ulink url="http://www.freedesktop.org/software/dbus/" /> + for more information about the big picture. + </para> + + <important> + <para>Interfaces described here have not been declared stable yet, + and are not accessible from <filename>libsystemd.so</filename>. + This documentation is provided in hope it might be useful for + developers, without any guarantees of availability or stability. + </para> + </important> + + <para>See + <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_request_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append_array</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append_string_memfd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append_strv</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_get_cookie</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_negotiate_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_path_encode</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information about the functions available.</para> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <ulink url="https://developer.gnome.org/gio/stable/gdbus.html">gdbus</ulink> + </para> + </refsect1> + +</refentry> diff --git a/man/sd-event.xml b/man/sd-event.xml index 47989f4421..fc615f0906 100644 --- a/man/sd-event.xml +++ b/man/sd-event.xml @@ -136,7 +136,7 @@ <listitem><para>Event sources may be assigned a 64bit priority value, that controls the order in which event sources are - dispatched if multiple are pending simultanously. See + dispatched if multiple are pending simultaneously. See <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> <listitem><para>The event loop may automatically send watchdog diff --git a/man/sd-journal.xml b/man/sd-journal.xml index 9b1a52207f..09747a480c 100644 --- a/man/sd-journal.xml +++ b/man/sd-journal.xml @@ -77,13 +77,17 @@ <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_query_enumerate</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_enumerate_fields</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_cutoff_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_usage</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_catalog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>sd_journal_get_catalog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_has_runtime_files</refentrytitle><manvolnum>3</manvolnum></citerefentry> and - <citerefentry><refentrytitle>sd_journal_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>sd_journal_has_persistent_files</refentrytitle><manvolnum>3</manvolnum></citerefentry> for more information about the functions implemented.</para> <para>Command line access for submitting entries to the journal is @@ -109,6 +113,8 @@ <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_query_enumerate</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_enumerate_fields</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_cutoff_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, @@ -116,6 +122,8 @@ <citerefentry><refentrytitle>sd_journal_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_query_unique</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_catalog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_has_runtime_files</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_has_persistent_files</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> diff --git a/man/sd_bus_creds_get_pid.xml b/man/sd_bus_creds_get_pid.xml index aec12bda16..3bcda46656 100644 --- a/man/sd_bus_creds_get_pid.xml +++ b/man/sd_bus_creds_get_pid.xml @@ -470,7 +470,7 @@ modified by the caller.</para> <para>All functions that take a <parameter>char***</parameter> - parameter will store the answer there as an address of a an array + parameter will store the answer there as an address of an array of strings. Each individual string is NUL-terminated, and the array is NULL-terminated as a whole. It will be valid as long as <parameter>c</parameter> remains valid, and should not be freed or diff --git a/man/sd_event_add_child.xml b/man/sd_event_add_child.xml index d4b180cf03..bc732db7fa 100644 --- a/man/sd_event_add_child.xml +++ b/man/sd_event_add_child.xml @@ -127,7 +127,7 @@ <constant>SD_EVENT_OFF</constant> with <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - <para>If the the second parameter of + <para>If the second parameter of <function>sd_event_add_child()</function> is passed as NULL no reference to the event source object is returned. In this case the event source is considered "floating", and will be destroyed diff --git a/man/sd_event_add_defer.xml b/man/sd_event_add_defer.xml index 6a13ede76e..d9ebd3b179 100644 --- a/man/sd_event_add_defer.xml +++ b/man/sd_event_add_defer.xml @@ -108,7 +108,7 @@ handler will be called once (<constant>SD_EVENT_ONESHOT</constant>). Note that if the event source is set to <constant>SD_EVENT_ON</constant> the event loop - will never go to sleep again, but continously call the handler, + will never go to sleep again, but continuously call the handler, possibly interleaved with other event sources.</para> <para><function>sd_event_add_post()</function> adds a new event diff --git a/man/sd_event_add_io.xml b/man/sd_event_add_io.xml index 4cc0428e29..c3749164cd 100644 --- a/man/sd_event_add_io.xml +++ b/man/sd_event_add_io.xml @@ -120,36 +120,35 @@ returned in the <parameter>source</parameter> parameter. The <parameter>fd</parameter> parameter takes the UNIX file descriptor to watch, which may refer to a socket, a FIFO, a message queue, a - serial connection, a character device or any other file descriptor - compatible with Linux <citerefentry - project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The - <parameter>events</parameter> parameter takes a bit mask of I/O - events to watch the file descriptor for, a combination of the - following event flags: <constant>EPOLLIN</constant>, - <constant>EPOLLOUT</constant>, <constant>EPOLLRDHUP</constant>, - <constant>EPOLLPRI</constant> and <constant>EPOLLET</constant>, - see <citerefentry - project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + serial connection, a character device, or any other file descriptor + compatible with Linux + <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The + <parameter>events</parameter> parameter takes a bit mask of events + to watch for, a combination of the following event flags: + <constant>EPOLLIN</constant>, <constant>EPOLLOUT</constant>, + <constant>EPOLLRDHUP</constant>, <constant>EPOLLPRI</constant>, + and <constant>EPOLLET</constant>, see + <citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details. The <parameter>handler</parameter> shall reference a - function to call when the I/O event source is triggered. The - handler function will be passed the - <parameter>userdata</parameter> pointer, which may be chosen - freely by the caller. The handler will also be passed the file - descriptor the event was seen on as well as the actual event flags - seen. It's generally a subset of the events watched, however may - additionally have <constant>EPOLLERR</constant> and - <constant>EPOLLHUP</constant> set.</para> - - <para>By default, the I/O event source will stay enabled - continously (<constant>SD_EVENT_ON</constant>), but this may be + function to call when the event source is triggered. The + <parameter>userdata</parameter> pointer will be passed to the + handler function, and may be chosen freely by the caller. The + handler will also be passed the file descriptor the event was seen + on, as well as the actual event flags. It's generally a subset of + the events watched, however may additionally include + <constant>EPOLLERR</constant> and <constant>EPOLLHUP</constant>. + </para> + + <para>By default, an event source will stay enabled + continuously (<constant>SD_EVENT_ON</constant>), but this may be changed with <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If the handler function returns a negative error code, it will be disabled after the invocation, even if the <constant>SD_EVENT_ON</constant> mode was requested before. Note - that an I/O event source set to <constant>SD_EVENT_ON</constant> will - fire continously unless data is read or written to the file - descriptor in order to reset the mask of events seen. + that an event source set to <constant>SD_EVENT_ON</constant> will + fire continuously unless data is read from or written to the file + descriptor to reset the mask of events seen. </para> <para>Setting the I/O event mask to watch for to 0 does not mean @@ -164,16 +163,17 @@ <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, but note that the event source is only removed from the event loop when all references to the event source are dropped. To make sure - an event source does not fire anymore, even when there's still a - reference to it kept, consider setting the event source to - <constant>SD_EVENT_OFF</constant> with - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + an event source does not fire anymore, even if it is still referenced, + disable the event source using + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + with <constant>SD_EVENT_OFF</constant>.</para> - <para>If the the second parameter of - <function>sd_event_add_io()</function> is passed as NULL no - reference to the event source object is returned. In this case the - event source is considered "floating", and will be destroyed - implicitly when the event loop itself is destroyed.</para> + <para>If the second parameter of + <function>sd_event_add_io()</function> is + <constant>NULL</constant> no reference to the event source object + is returned. In this case the event source is considered + "floating", and will be destroyed implicitly when the event loop + itself is destroyed.</para> <para>It is recommended to use <function>sd_event_add_io()</function> only in conjunction with @@ -181,24 +181,24 @@ ensure that all I/O operations from invoked handlers are properly asynchronous and non-blocking. Using file descriptors without <constant>O_NONBLOCK</constant> might result in unexpected - starving of other event sources. See <citerefentry - project='man-pages'><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + starvation of other event sources. See + <citerefentry project='man-pages'><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details on enabling <constant>O_NONBLOCK</constant> mode.</para> <para><function>sd_event_source_get_io_events()</function> retrieves - the configured I/O event mask to watch of an I/O event source created + the configured mask of watched I/O events of an event source created previously with <function>sd_event_add_io()</function>. It takes the event source object and a pointer to a variable to store the - event mask in.</para> + mask in.</para> - <para><function>sd_event_source_set_io_events()</function> changes the - configured I/O event mask to watch of an I/O event source created previously - with <function>sd_event_add_io()</function>. It takes the event - source object and the new event mask to set.</para> + <para><function>sd_event_source_set_io_events()</function> + configures the mask of watched I/O events of an event source created + previously with <function>sd_event_add_io()</function>. It takes the + event source object and the new event mask.</para> <para><function>sd_event_source_get_io_revents()</function> retrieves the I/O event mask of currently seen but undispatched - events from an I/O event source created previously with + events from an event source created previously with <function>sd_event_add_io()</function>. It takes the event source object and a pointer to a variable to store the event mask in. When called from a handler function on the handler's event @@ -214,15 +214,15 @@ source types, the latter only to I/O event sources.</para> <para><function>sd_event_source_get_io_fd()</function> retrieves - the UNIX file descriptor of an I/O event source created previously + the UNIX file descriptor of an event source created previously with <function>sd_event_add_io()</function>. It takes the event - source object and returns the positive file descriptor in the return - value, or a negative error number on error (see below).</para> + source object and returns the non-negative file descriptor + or a negative error number on error (see below).</para> <para><function>sd_event_source_set_io_fd()</function> changes the UNIX file descriptor of an I/O event source created previously with <function>sd_event_add_io()</function>. It takes - the event source object and the new file descriptor to set.</para> + the event source object and the new file descriptor.</para> </refsect1> <refsect1> @@ -230,13 +230,13 @@ <para>On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error - code. </para> + code.</para> </refsect1> <refsect1> <title>Errors</title> - <para>Returned errors may indicate the following problems:</para> + <para>Returned values may indicate the following problems:</para> <variablelist> <varlistentry> diff --git a/man/sd_event_add_signal.xml b/man/sd_event_add_signal.xml index b5312735d2..e98f1d2682 100644 --- a/man/sd_event_add_signal.xml +++ b/man/sd_event_add_signal.xml @@ -123,24 +123,23 @@ <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, but note that the event source is only removed from the event loop when all references to the event source are dropped. To make sure - an event source does not fire anymore, even when there's still a - reference to it kept, consider setting the event source to - <constant>SD_EVENT_OFF</constant> with - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - - <para>If the the second parameter of - <function>sd_event_add_signal()</function> is passed as NULL no - reference to the event source object is returned. In this case the - event source is considered "floating", and will be destroyed - implicitly when the event loop itself is destroyed.</para> - - <para><function>sd_event_source_get_signal()</function> retrieves - the configured UNIX process signal number of a signal event source - created previously with - <function>sd_event_add_signal()</function>. It takes the event - source object as the <parameter>source</parameter> + an event source does not fire anymore, even if it is still referenced, + disable the event source using + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + with <constant>SD_EVENT_OFF</constant>.</para> + + <para>If the second parameter of + <function>sd_event_add_signal()</function> is + <constant>NULL</constant> no reference to the event source object + is returned. In this case the event source is considered + "floating", and will be destroyed implicitly when the event loop + itself is destroyed.</para> + + <para><function>sd_event_source_get_signal()</function> returns + the configured signal number of an event source created previously + with <function>sd_event_add_signal()</function>. It takes the + event source object as the <parameter>source</parameter> parameter.</para> - </refsect1> <refsect1> @@ -148,7 +147,7 @@ <para>On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error - code. </para> + code.</para> </refsect1> <refsect1> @@ -167,7 +166,6 @@ <term><constant>-EINVAL</constant></term> <listitem><para>An invalid argument has been passed.</para></listitem> - </varlistentry> <varlistentry> @@ -175,21 +173,18 @@ <listitem><para>A handler is already installed for this signal or the signal was not blocked previously.</para></listitem> - </varlistentry> <varlistentry> <term><constant>-ESTALE</constant></term> <listitem><para>The event loop is already terminated.</para></listitem> - </varlistentry> <varlistentry> <term><constant>-ECHILD</constant></term> <listitem><para>The event loop has been created in a different process.</para></listitem> - </varlistentry> <varlistentry> diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml index df38f52fc9..a2c0d54b56 100644 --- a/man/sd_event_add_time.xml +++ b/man/sd_event_add_time.xml @@ -114,41 +114,28 @@ <refsect1> <title>Description</title> - <para><function>sd_event_add_time()</function> adds a new timer - event source to an event loop. The event loop object is specified - in the <parameter>event</parameter> parameter, the event source - object is returned in the <parameter>source</parameter> - parameter. The <parameter>clock</parameter> parameter takes a - clock identifier, one of <constant>CLOCK_REALTIME</constant>, - <constant>CLOCK_MONOTONIC</constant>, - <constant>CLOCK_BOOTTIME</constant>, - <constant>CLOCK_REALTIME_ALARM</constant> or - <constant>CLOCK_BOOTTIME_ALARM</constant>. See - <citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details regarding the various types of clocks. The - <parameter>usec</parameter> parameter takes a time value in - microseconds (µs), relative to the clock's epoch, specifying when - the timer shall elapse the earliest. If a time that already lies - in the past is specified (including 0), the timer source is - dispatched immediately in the next event loop iterations. The - <parameter>accuracy</parameter> parameter takes an additional - accuracy value in µs specifying a time the timer event may be - delayed. Specify 0 for selecting the default accuracy - (250ms). Specify 1µs for most accurate timers. Consider specifying - 60000000µs or larger (1min) for long-running events that may be - delayed substantially. Picking higher accuracy values allows the - system to coalesce timer events more aggressively, thus improving - power efficiency. The <parameter>handler</parameter> parameter - shall reference a function to call when the timer elapses. The - handler function will be passed the - <parameter>userdata</parameter> pointer, which may be chosen - freely by the caller. The handler is also passed the configured - time it was triggered, however it might actually have been called - at a slightly later time, subject to the specified accuracy value, - the kernel timer slack (see - <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>) - and additional scheduling latencies. To query the actual time the - handler was called use + <para><function>sd_event_add_time()</function> adds a new timer event source to an event loop. The event loop + object is specified in the <parameter>event</parameter> parameter, the event source object is returned in the + <parameter>source</parameter> parameter. The <parameter>clock</parameter> parameter takes a clock identifier, one + of <constant>CLOCK_REALTIME</constant>, <constant>CLOCK_MONOTONIC</constant>, <constant>CLOCK_BOOTTIME</constant>, + <constant>CLOCK_REALTIME_ALARM</constant>, or <constant>CLOCK_BOOTTIME_ALARM</constant>. See + <citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details + regarding the various types of clocks. The <parameter>usec</parameter> parameter specifies the earliest time, in + microseconds (µs), relative to the clock's epoch, when the timer shall be triggered. If a time already in the past + is specified (including <constant>0</constant>), this timer source "fires" immediately and is ready to be + dispatched. If the paramater is specified as <constant>UINT64_MAX</constant> the timer event will never elapse, + which may be used as an alternative to explicitly disabling a timer event source with + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The + <parameter>accuracy</parameter> parameter specifies an additional accuracy value in µs specifying how much the + timer event may be delayed. Use <constant>0</constant> to select the default accuracy (250ms). Use 1µs for maximum + accuracy. Consider specifying 60000000µs (1min) or larger for long-running events that may be delayed + substantially. Picking higher accuracy values allows the system to coalesce timer events more aggressively, + improving power efficiency. The <parameter>handler</parameter> parameter shall reference a function to call when + the timer elapses. The handler function will be passed the <parameter>userdata</parameter> pointer, which may be + chosen freely by the caller. The handler is also passed the configured trigger time, even if it is actually called + slightly later, subject to the specified accuracy value, the kernel timer slack (see + <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>), and additional + scheduling latencies. To query the actual time the handler was called use <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> <para>By default, the timer will elapse once @@ -159,7 +146,7 @@ disabled after the invocation, even if the <constant>SD_EVENT_ON</constant> mode was requested before. Note that a timer event set to <constant>SD_EVENT_ON</constant> will - fire continously unless its configured time is updated using + fire continuously unless its configured time is updated using <function>sd_event_source_set_time()</function>. </para> @@ -167,22 +154,24 @@ <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, but note that the event source is only removed from the event loop when all references to the event source are dropped. To make sure - an event source does not fire anymore, even when there's still a - reference to it kept, consider setting the event source to - <constant>SD_EVENT_OFF</constant> with - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - - <para>If the the second parameter of - <function>sd_event_add_time()</function> is passed as NULL no - reference to the event source object is returned. In this case the - event source is considered "floating", and will be destroyed - implicitly when the event loop itself is destroyed.</para> + an event source does not fire anymore, even if it is still referenced, + disable the event source using + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + with <constant>SD_EVENT_OFF</constant>.</para> + + <para>If the second parameter of + <function>sd_event_add_time()</function> is + <constant>NULL</constant> no reference to the event source object + is returned. In this case the event source is considered + "floating", and will be destroyed implicitly when the event loop + itself is destroyed.</para> <para>If the <parameter>handler</parameter> to - <function>sd_event_add_time()</function> is passed as NULL, and - the event source fires, this will be considered a request to exit - the event loop. In this case, the <parameter>userdata</parameter> - parameter, cast to an integer is used for the exit code passed to + <function>sd_event_add_time()</function> is + <constant>NULL</constant>, and the event source fires, this will + be considered a request to exit the event loop. In this case, the + <parameter>userdata</parameter> parameter, cast to an integer, is + used for the exit code passed to <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> <para>Use <constant>CLOCK_BOOTTIME_ALARM</constant> and @@ -192,7 +181,7 @@ <para>In order to set up relative timers (that is, relative to the current time), retrieve the current time via <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - add the desired timespan to sleep to it, and pass the result as + add the desired timespan to it, and use the result as the <parameter>usec</parameter> parameter to <function>sd_event_add_time()</function>.</para> @@ -212,30 +201,30 @@ latency will keep accumulating on the timer.</para> <para><function>sd_event_source_get_time()</function> retrieves - the configured time value of a timer event source created + the configured time value of an event source created previously with <function>sd_event_add_time()</function>. It takes the event source object and a pointer to a variable to store the - time, relative to the selected clock's epoch, in µs in.</para> + time in, relative to the selected clock's epoch, in µs.</para> <para><function>sd_event_source_set_time()</function> changes the - configured time value of a timer event source created previously - with <function>sd_event_add_time()</function>. It takes the event - source object and a time relative to the selected clock's - epoch, in µs.</para> + time of an event source created previously with + <function>sd_event_add_time()</function>. It takes the event + source object and a time relative to the selected clock's epoch, + in µs.</para> <para><function>sd_event_source_get_time_accuracy()</function> - retrieves the configured accuracy value of a timer event source + retrieves the configured accuracy value of a event source created previously with <function>sd_event_add_time()</function>. It takes the event source object and a pointer to a variable to store - the accuracy in µs in.</para> + the accuracy in. The accuracy is specified in µs.</para> <para><function>sd_event_source_set_time_accuracy()</function> changes the configured accuracy of a timer event source created previously with <function>sd_event_add_time()</function>. It takes - the event source object and an accuracy, in µs.</para> + the event source object and accuracy, in µs.</para> <para><function>sd_event_source_get_time_clock()</function> - retrieves the configured clock of a timer event source created + retrieves the configured clock of a event source created previously with <function>sd_event_add_time()</function>. It takes the event source object and a pointer to a variable to store the clock identifier in.</para> @@ -252,7 +241,7 @@ <refsect1> <title>Errors</title> - <para>Returned errors may indicate the following problems:</para> + <para>Returned values may indicate the following problems:</para> <variablelist> <varlistentry> diff --git a/man/sd_event_exit.xml b/man/sd_event_exit.xml index 4f34f3b122..9846a3eaf4 100644 --- a/man/sd_event_exit.xml +++ b/man/sd_event_exit.xml @@ -76,7 +76,7 @@ exit. The <parameter>code</parameter> parameter may be any integer value and is returned as-is by <citerefentry><refentrytitle>sd_event_loop</refentrytitle><manvolnum>3</manvolnum></citerefentry> - after the last event loop iteration. It may also be be queried + after the last event loop iteration. It may also be queried using <function>sd_event_get_exit_code()</function>, see below. </para> diff --git a/man/sd_event_now.xml b/man/sd_event_now.xml index f577e44c0e..2c83b0bcb5 100644 --- a/man/sd_event_now.xml +++ b/man/sd_event_now.xml @@ -65,45 +65,44 @@ <refsect1> <title>Description</title> - <para><function>sd_event_now()</function> returns the timestamp - the most recent event loop iteration began. This timestamp is - taken right after after returning from the event sleep, and before + <para><function>sd_event_now()</function> returns the time when + the most recent event loop iteration began. A timestamp + is taken right after returning from the event sleep, and before dispatching any event sources. The <parameter>event</parameter> - parameter takes the even loop object to retrieve the timestamp + parameter specifies the event loop object to retrieve the timestamp from. The <parameter>clock</parameter> parameter specifies the clock to retrieve the timestamp for, and is one of - <constant>CLOCK_REALTIME</constant> (or its equivalent + <constant>CLOCK_REALTIME</constant> (or equivalently <constant>CLOCK_REALTIME_ALARM</constant>), - <constant>CLOCK_MONOTONIC</constant> or - <constant>CLOCK_BOOTTIME</constant> (or its equivalent - <constant>CLOCK_BOOTTIME_ALARM</constant>), see <citerefentry - project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> + <constant>CLOCK_MONOTONIC</constant>, or + <constant>CLOCK_BOOTTIME</constant> (or equivalently + <constant>CLOCK_BOOTTIME_ALARM</constant>), see + <citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> for more information on the various clocks. The retrieved timestamp is stored in the <parameter>usec</parameter> parameter, in µs since the clock's epoch. If this function is invoked before - the first event loop iteration the current time is returned, as + the first event loop iteration, the current time is returned, as reported by <function>clock_gettime()</function>. To distinguish this case from a regular invocation the return value will be - positive non-zero in this case, while it is zero when the returned - timestamp refers to the actual event loop iteration.</para> + positive, and zero when the returned timestamp refers to an actual + event loop iteration.</para> </refsect1> <refsect1> <title>Return Value</title> <para>If the first event loop iteration has not run yet - <function>sd_event_now()</function> returns the requested - timestamp in <parameter>usec</parameter> and returns a positive, - non-zero return value. Otherwise, on success it will return the - iteration's timestamp in <parameter>usec</parameter> and 0 as - return value. On failure, the call returns a negative errno-style + <function>sd_event_now()</function> writes current time to + <parameter>usec</parameter> and returns a positive return value. + Otherwise, it will write the requested timestamp to <parameter>usec</parameter> + and return 0. On failure, the call returns a negative errno-style error code.</para> </refsect1> <refsect1> <title>Errors</title> - <para>Returned errors may indicate the following problems:</para> + <para>Returned values may indicate the following problems:</para> <variablelist> <varlistentry> @@ -115,12 +114,18 @@ </varlistentry> <varlistentry> + <term><constant>-EOPNOTSUPP</constant></term> + + <listitem><para>Unsupported clock type. + </para></listitem> + </varlistentry> + + <varlistentry> <term><constant>-ECHILD</constant></term> <listitem><para>The event loop object was created in a different process.</para></listitem> </varlistentry> - </variablelist> </refsect1> diff --git a/man/sd_event_source_get_pending.xml b/man/sd_event_source_get_pending.xml index 1c06e81fe0..7f88bd1b87 100644 --- a/man/sd_event_source_get_pending.xml +++ b/man/sd_event_source_get_pending.xml @@ -87,7 +87,7 @@ <para>For I/O event sources, as created with <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, the call - <citerefentry><refentrytitle>sd_event_get_io_revents</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>sd_event_source_get_io_revents</refentrytitle><manvolnum>3</manvolnum></citerefentry> may be used to query the type of event pending in more detail.</para> diff --git a/man/sd_event_source_set_enabled.xml b/man/sd_event_source_set_enabled.xml index 74c02e87bb..6844f29a49 100644 --- a/man/sd_event_source_set_enabled.xml +++ b/man/sd_event_source_set_enabled.xml @@ -105,7 +105,7 @@ with calls such as <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. However, - depending on the event source type they are enabled continously + depending on the event source type they are enabled continuously (<constant>SD_EVENT_ON</constant>) or only for a single invocation of the event source handler (<constant>SD_EVENT_ONESHOT</constant>). For details see the diff --git a/man/sd_event_source_set_prepare.xml b/man/sd_event_source_set_prepare.xml index 7066a55306..24861d01d9 100644 --- a/man/sd_event_source_set_prepare.xml +++ b/man/sd_event_source_set_prepare.xml @@ -71,7 +71,7 @@ <title>Description</title> <para><function>sd_event_source_set_prepare()</function> may be - used to set a prepartion callback for the event source object + used to set a preparation callback for the event source object specified as <parameter>source</parameter>. The callback function specified as <parameter>callback</parameter> will be invoked immediately before the event loop goes to sleep to wait for diff --git a/man/sd_event_source_set_priority.xml b/man/sd_event_source_set_priority.xml index cc0f5a0103..9234f4233e 100644 --- a/man/sd_event_source_set_priority.xml +++ b/man/sd_event_source_set_priority.xml @@ -111,7 +111,7 @@ dispatched is undefined, but the event loop generally tries to dispatch them in the order it learnt about events on them. As the backing kernel primitives do not provide accurate information - about the order in which events occured this is not necessarily + about the order in which events occurred this is not necessarily reliable. However, it is guaranteed that if events are seen on multiple same-priority event sources at the same time, each one is not dispatched again until all others have been dispatched diff --git a/man/sd_event_wait.xml b/man/sd_event_wait.xml index 1eefa80700..f2aea00e98 100644 --- a/man/sd_event_wait.xml +++ b/man/sd_event_wait.xml @@ -107,7 +107,7 @@ and <citerefentry><refentrytitle>sd_event_loop</refentrytitle><manvolnum>3</manvolnum></citerefentry> for higher-level functions that execute individual but complete - iterations of an event loop or run it continously.</para> + iterations of an event loop or run it continuously.</para> <para><function>sd_event_prepare()</function> checks for pending events and arms necessary timers. If any events are ready to be @@ -169,7 +169,7 @@ <term><constant>SD_EVENT_PREPARING</constant></term> <listitem><para>An event source is currently being prepared, - i.e. the preparation handler is currently being excuted, as + i.e. the preparation handler is currently being executed, as set with <citerefentry><refentrytitle>sd_event_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This state is only seen in the event source preparation handler diff --git a/man/sd_journal_enumerate_fields.xml b/man/sd_journal_enumerate_fields.xml new file mode 100644 index 0000000000..fa5884106b --- /dev/null +++ b/man/sd_journal_enumerate_fields.xml @@ -0,0 +1,161 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_journal_enumerate_fields"> + + <refentryinfo> + <title>sd_journal_enumerate_fields</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_journal_enumerate_fields</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_enumerate_fields</refname> + <refname>sd_journal_restart_fields</refname> + <refname>SD_JOURNAL_FOREACH_FIELD</refname> + <refpurpose>Read used field names from the journal</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_enumerate_fields</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>const char **<parameter>field</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_journal_restart_fields</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef><function>SD_JOURNAL_FOREACH_FIELD</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>const char *<parameter>field</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_enumerate_fields()</function> may be used to iterate through all field names used in the + opened journal files. On each invocation the next field name is returned. The order of the returned field names is + not defined. It takes two arguments: the journal context object, plus a pointer to a constant string pointer where + the field name is stored in. The returned data is in a read-only memory map and is only valid until the next + invocation of <function>sd_journal_enumerate_fields()</function>. Note that this call is subject to the data field + size threshold as controlled by <function>sd_journal_set_data_threshold()</function>.</para> + + <para><function>sd_journal_restart_fields()</function> resets the field name enumeration index to the beginning of + the list. The next invocation of <function>sd_journal_enumerate_fields()</function> will return the first field + name again.</para> + + <para>The <function>SD_JOURNAL_FOREACH_FIELD()</function> macro may be used as a handy wrapper around + <function>sd_journal_restart_fields()</function> and <function>sd_journal_enumerate_fields()</function>.</para> + + <para>These functions currently are not influenced by matches set with <function>sd_journal_add_match()</function> + but this might change in a later version of this software.</para> + + <para>To retrieve the possible values a specific field can take use + <citerefentry><refentrytitle>sd_journal_query_unique</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_journal_enumerate_fields()</function> returns a + positive integer if the next field name has been read, 0 when no + more field names are known, or a negative errno-style error code. + <function>sd_journal_restart_fields()</function> returns + nothing.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_enumerate_fields()</function> and <function>sd_journal_restart_fields()</function> + interfaces are available as a shared library, which can be compiled and linked to with the + <constant>libsystemd</constant> <citerefentry + project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para>Use the <function>SD_JOURNAL_FOREACH_FIELD</function> macro to iterate through all field names in use in the + current journal.</para> + + <programlisting>#include <stdio.h> +#include <string.h> +#include <systemd/sd-journal.h> + +int main(int argc, char *argv[]) { + sd_journal *j; + const char *field; + int r; + + r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); + if (r < 0) { + fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); + return 1; + } + SD_JOURNAL_FOREACH_FIELD(j, field) + printf("%s\n", field); + sd_journal_close(j); + return 0; +}</programlisting> + + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_query_unique</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_journal_has_runtime_files.xml b/man/sd_journal_has_runtime_files.xml new file mode 100644 index 0000000000..237e649206 --- /dev/null +++ b/man/sd_journal_has_runtime_files.xml @@ -0,0 +1,95 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Jan Synáček + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_journal_has_runtime_files"> + + <refentryinfo> + <title>sd_journal_has_runtime_files</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Jan</firstname> + <surname>Synáček</surname> + <email>jan.synacek@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_journal_has_runtime_files</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_has_runtime_files</refname> + <refname>sd_journal_has_persistent_files</refname> + <refpurpose>Query availability of runtime or persistent journal files.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_has_runtime_files</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_has_persistent_files</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_has_runtime_files()</function> returns a positive value + if runtime journal files (present in /run/systemd/journal/) have been found. + Otherwise returns 0.</para> + + <para><function>sd_journal_has_persistent_files()</function> returns a positive value + if persistent journal files (present in /var/log/journal/) have been found. + Otherwise returns 0.</para> + </refsect1> + + <refsect1> + <title>Return value</title> + <para>Both <function>sd_journal_has_runtime_files()</function> + and <function>sd_journal_has_persistent_files()</function> return -EINVAL + if their argument is NULL. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_journal_query_unique.xml b/man/sd_journal_query_unique.xml index ac0e5f633f..dbff55c105 100644 --- a/man/sd_journal_query_unique.xml +++ b/man/sd_journal_query_unique.xml @@ -128,6 +128,11 @@ <para>Note that these functions currently are not influenced by matches set with <function>sd_journal_add_match()</function> but this might change in a later version of this software.</para> + + <para>To enumerate all field names currently in use (and thus all suitable field parameters for + <function>sd_journal_query_unique()</function>), use the + <citerefentry><refentrytitle>sd_journal_enumerate_fields</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call.</para> </refsect1> <refsect1> @@ -167,25 +172,25 @@ #include <systemd/sd-journal.h> int main(int argc, char *argv[]) { - sd_journal *j; - const void *d; - size_t l; - int r; - - r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); - if (r < 0) { - fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); - return 1; - } - r = sd_journal_query_unique(j, "_SYSTEMD_UNIT"); - if (r < 0) { - fprintf(stderr, "Failed to query journal: %s\n", strerror(-r)); - return 1; - } - SD_JOURNAL_FOREACH_UNIQUE(j, d, l) - printf("%.*s\n", (int) l, (const char*) d); - sd_journal_close(j); - return 0; + sd_journal *j; + const void *d; + size_t l; + int r; + + r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); + if (r < 0) { + fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); + return 1; + } + r = sd_journal_query_unique(j, "_SYSTEMD_UNIT"); + if (r < 0) { + fprintf(stderr, "Failed to query journal: %s\n", strerror(-r)); + return 1; + } + SD_JOURNAL_FOREACH_UNIQUE(j, d, l) + printf("%.*s\n", (int) l, (const char*) d); + sd_journal_close(j); + return 0; }</programlisting> </refsect1> @@ -198,6 +203,7 @@ int main(int argc, char *argv[]) { <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_enumerate_fields</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> diff --git a/man/sd_notify.xml b/man/sd_notify.xml index dbf6330453..bd6cfdcd29 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -242,7 +242,7 @@ multiple file descriptors are submitted at once, the specified name will be assigned to all of them. In order to assign different names to submitted file descriptors, submit them in - seperate invocations of + separate invocations of <function>sd_pid_notify_with_fds()</function>. The name may consist of any ASCII character, but must not contain control characters or <literal>:</literal>. It may not be longer than diff --git a/man/sd_seat_get_active.xml b/man/sd_seat_get_active.xml index 6e1d505dce..c5e6ddab02 100644 --- a/man/sd_seat_get_active.xml +++ b/man/sd_seat_get_active.xml @@ -192,7 +192,7 @@ <function>sd_seat_get_sessions()</function>, <function>sd_seat_can_multi_session()</function>, <function>sd_seat_can_tty()</function> and - <function>sd_seat_can_grapical()</function> interfaces are + <function>sd_seat_can_graphical()</function> interfaces are available as a shared library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> diff --git a/man/systemctl.xml b/man/systemctl.xml index 1fb056874c..cce7861139 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -683,14 +683,11 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <para>Start (activate) one or more units specified on the command line.</para> - <para>Note that glob patterns operate on a list of currently - loaded units. Units which are not active and are not in a - failed state usually are not loaded, and would not be - matched by any pattern. In addition, in case of - instantiated units, systemd is often unaware of the - instance name until the instance has been started. Therefore, - using glob patterns with <command>start</command> - has limited usefulness.</para> + <para>Note that glob patterns operate on the set of primary names of currently loaded units. Units which + are not active and are not in a failed state usually are not loaded, and will not be matched by any + pattern. In addition, in case of instantiated units, systemd is often unaware of the instance name until + the instance has been started. Therefore, using glob patterns with <command>start</command> has limited + usefulness. Also, secondary alias names of units are not considered.</para> </listitem> </varlistentry> <varlistentry> @@ -736,9 +733,9 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <listitem> <para>Restart one or more units specified on the command line if the units are running. This does nothing if units are not - running. Note that, for compatibility with Red Hat init - scripts, <command>condrestart</command> is equivalent to this - command.</para> + running.</para> + <!-- Note that we don't document condrestart here, as that is just compatibility support, and we generally + don't document that. --> </listitem> </varlistentry> <varlistentry> @@ -751,14 +748,14 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service </listitem> </varlistentry> <varlistentry> - <term><command>reload-or-try-restart <replaceable>PATTERN</replaceable>...</command></term> + <term><command>try-reload-or-restart <replaceable>PATTERN</replaceable>...</command></term> <listitem> <para>Reload one or more units if they support it. If not, restart them instead. This does nothing if the units are not - running. Note that, for compatibility with SysV init scripts, - <command>force-reload</command> is equivalent to this - command.</para> + running.</para> + <!-- Note that we don't document force-reload here, as that is just compatibility support, and we generally + don't document that. --> </listitem> </varlistentry> <varlistentry> @@ -832,7 +829,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service output. If you are looking for computer-parsable output, use <command>show</command> instead. By default, this function only shows 10 lines of output and ellipsizes - lines to fit in the terminal window. This can be changes + lines to fit in the terminal window. This can be changed with <option>--lines</option> and <option>--full</option>, see above. In addition, <command>journalctl --unit=<replaceable>NAME</replaceable></command> or @@ -1137,7 +1134,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <tbody> <row> <entry><literal>enabled</literal></entry> - <entry morerows='1'>Enabled through a symlink in a <filename>.wants/</filename> or <filename>.requires/</filename> subdirectory of <filename>/etc/systemd/system/</filename> (persistently) or <filename>/run/systemd/system/</filename> (transiently).</entry> + <entry morerows='1'>Enabled through creating symlinks encoded in the <literal>[Install]</literal> section (permanently or just in <filename>/run</filename>).</entry> <entry morerows='1'>0</entry> </row> <row> @@ -1176,7 +1173,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service </row> <row> <entry><literal>bad</literal></entry> - <entry>Unit file is invalid or another error occured. Note that <command>is-enabled</command> will not actually return this state, but print an error message instead. However the unit file listing printed by <command>list-unit-files</command> might show it.</entry> + <entry>Unit file is invalid or another error occurred. Note that <command>is-enabled</command> will not actually return this state, but print an error message instead. However the unit file listing printed by <command>list-unit-files</command> might show it.</entry> <entry>> 0</entry> </row> </tbody> @@ -1724,11 +1721,10 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service are equivalent to: <programlisting># systemctl status dev-sda.device # systemctl status home.mount</programlisting> - In the second case, shell-style globs will be matched against - currently loaded units; literal unit names, with or without - a suffix, will be treated as in the first case. This means that - literal unit names always refer to exactly one unit, but globs - may match zero units and this is not considered an error.</para> + In the second case, shell-style globs will be matched against the primary names of all currently loaded units; + literal unit names, with or without a suffix, will be treated as in the first case. This means that literal unit + names always refer to exactly one unit, but globs may match zero units and this is not considered an + error.</para> <para>Glob patterns use <citerefentry project='man-pages'><refentrytitle>fnmatch</refentrytitle><manvolnum>3</manvolnum></citerefentry>, @@ -1736,11 +1732,12 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <literal>*</literal>, <literal>?</literal>, <literal>[]</literal> may be used. See <citerefentry project='man-pages'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for more details. The patterns are matched against the names of + for more details. The patterns are matched against the primary names of currently loaded units, and patterns which do not match anything are silently skipped. For example: <programlisting># systemctl stop sshd@*.service</programlisting> - will stop all <filename>sshd@.service</filename> instances. + will stop all <filename>sshd@.service</filename> instances. Note that alias names of units, and units that aren't + loaded are not considered for glob expansion. </para> <para>For unit file commands, the specified diff --git a/man/systemd-activate.xml b/man/systemd-activate.xml index 5fe1a39057..c950a0836d 100644 --- a/man/systemd-activate.xml +++ b/man/systemd-activate.xml @@ -78,6 +78,9 @@ to <command>systemd-activate</command> will be passed through to the daemon, in the original positions. Other sockets specified with <option>--listen</option> will use consecutive descriptors. + By default, <command>systemd-activate</command> listens on a + stream socket, use <option>--datagram</option> to listen on + a datagram socket instead (see below). </para> </refsect1> @@ -104,6 +107,13 @@ </varlistentry> <varlistentry> + <term><option>-d</option></term> + <term><option>--datagram</option></term> + + <listitem><para>Listen on a datagram socket, instead of a stream socket.</para></listitem> + </varlistentry> + + <varlistentry> <term><option>-E <replaceable>VAR</replaceable><optional>=<replaceable>VALUE</replaceable></optional></option></term> <term><option>--setenv=<replaceable>VAR</replaceable><optional>=<replaceable>VALUE</replaceable></optional></option></term> diff --git a/man/systemd-ask-password.xml b/man/systemd-ask-password.xml index 6fb322e849..2a4d24349b 100644 --- a/man/systemd-ask-password.xml +++ b/man/systemd-ask-password.xml @@ -149,7 +149,7 @@ possible to cache multiple passwords under the same keyname, in which case they will be stored as NUL-separated list of passwords. Use - <citerefentry><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + <citerefentry project='die-net'><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to access the cached key via the kernel keyring directly. Example: <literal>--keyname=cryptsetup</literal></para></listitem> </varlistentry> @@ -209,7 +209,7 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> </para> diff --git a/man/systemd-detect-virt.xml b/man/systemd-detect-virt.xml index 5d19322cdc..2b7f4e69ab 100644 --- a/man/systemd-detect-virt.xml +++ b/man/systemd-detect-virt.xml @@ -59,7 +59,7 @@ <para><command>systemd-detect-virt</command> detects execution in a virtualized environment. It identifies the virtualization - technology and can distinguish full VM virtualization from + technology and can distinguish full machine virtualization from container virtualization. <filename>systemd-detect-virt</filename> exits with a return value of 0 (success) if a virtualization technology is detected, and non-zero (error) otherwise. By default, @@ -88,7 +88,7 @@ </thead> <tbody> <row> - <entry morerows="9">VM</entry> + <entry valign="top" morerows="9">VM</entry> <entry><varname>qemu</varname></entry> <entry>QEMU software virtualization</entry> </row> @@ -139,7 +139,7 @@ </row> <row> - <entry morerows="5">Container</entry> + <entry valign="top" morerows="5">Container</entry> <entry><varname>openvz</varname></entry> <entry>OpenVZ/Virtuozzo</entry> </row> @@ -173,8 +173,8 @@ </table> <para>If multiple virtualization solutions are used, only the - "innermost" is detected and identified. That means if both VM - virtualization and container virtualization are used in + "innermost" is detected and identified. That means if both + machine and container virtualization are used in conjunction, only the latter will be identified (unless <option>--vm</option> is passed).</para> </refsect1> @@ -197,8 +197,7 @@ <term><option>-v</option></term> <term><option>--vm</option></term> - <listitem><para>Only detects VM virtualization (i.e. full - hardware virtualization).</para></listitem> + <listitem><para>Only detects hardware virtualization).</para></listitem> </varlistentry> <varlistentry> diff --git a/man/systemd-escape.xml b/man/systemd-escape.xml index 5407773f23..dbb3869a24 100644 --- a/man/systemd-escape.xml +++ b/man/systemd-escape.xml @@ -64,7 +64,7 @@ used to escape and to undo escaping of strings.</para> <para>The command takes any number of strings on the command line, - and will process them individually, one after the other. It will + and will process them individually, one after another. It will output them separated by spaces to stdout.</para> <para>By default, this command will escape the strings passed, diff --git a/man/systemd-journal-gatewayd.service.xml b/man/systemd-journal-gatewayd.service.xml index 6df2248578..e32ac26850 100644 --- a/man/systemd-journal-gatewayd.service.xml +++ b/man/systemd-journal-gatewayd.service.xml @@ -193,7 +193,7 @@ </varlistentry> <varlistentry> - <term><constant>application/event-stream</constant></term> + <term><constant>text/event-stream</constant></term> <listitem><para>Entries are formatted as JSON data structures, wrapped in a format suitable for <ulink diff --git a/man/systemd-journal-remote.xml b/man/systemd-journal-remote.xml index ebaca2657f..3899f175d4 100644 --- a/man/systemd-journal-remote.xml +++ b/man/systemd-journal-remote.xml @@ -293,15 +293,24 @@ journalctl -o export | systemd-journal-remote -o /tmp/dir - </programlisting> </para> - <para>Retrieve events from a remote + <para>Retrieve all available events from a remote <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry> instance and store them in - <filename>/var/log/journal/some.host/remote-some~host.journal</filename>: + <filename>/var/log/journal/remote/remote-some.host.journal</filename>: <programlisting> systemd-journal-remote --url http://some.host:19531/ </programlisting> </para> - </refsect1> + + <para>Retrieve current boot events and wait for new events from a remote + <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + instance, and store them in + <filename>/var/log/journal/remote/remote-some.host.journal</filename>: + <programlisting> +systemd-journal-remote --url http://some.host:19531/entries?boot&follow + </programlisting> + </para> +</refsect1> <refsect1> <title>See Also</title> diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index a97b7c44eb..86cdb4e124 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -249,15 +249,75 @@ </varlistentry> <varlistentry> + <term><option>-a</option></term> + <term><option>--as-pid2</option></term> + + <listitem><para>Invoke the shell or specified program as process ID (PID) 2 instead of PID 1 (init). By + default, if neither this option nor <option>--boot</option> is used, the selected binary is run as process with + PID 1, a mode only suitable for programs that are aware of the special semantics that the process with PID 1 + has on UNIX. For example, it needs to reap all processes reparented to it, and should implement + <command>sysvinit</command> compatible signal handling (specifically: it needs to reboot on SIGINT, reexecute + on SIGTERM, reload configuration on SIGHUP, and so on). With <option>--as-pid2</option> a minimal stub init + process is run as PID 1 and the selected binary is executed as PID 2 (and hence does not need to implement any + special semantics). The stub init process will reap processes as necessary and react appropriately to + signals. It is recommended to use this mode to invoke arbitrary commands in containers, unless they have been + modified to run correctly as PID 1. Or in other words: this switch should be used for pretty much all commands, + except when the command refers to an init or shell implementation, as these are generally capable of running + correctly as PID 1). This option may not be combined with <option>--boot</option> or + <option>--share-system</option>.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>-b</option></term> <term><option>--boot</option></term> - <listitem><para>Automatically search for an init binary and - invoke it instead of a shell or a user supplied program. If - this option is used, arguments specified on the command line - are used as arguments for the init binary. This option may not - be combined with <option>--share-system</option>. - </para></listitem> + <listitem><para>Automatically search for an init binary and invoke it as PID 1, instead of a shell or a user + supplied program. If this option is used, arguments specified on the command line are used as arguments for the + init binary. This option may not be combined with <option>--as-pid2</option> or + <option>--share-system</option>.</para> + + <para>The following table explains the different modes of invocation and relationship to + <option>--as-pid2</option> (see above):</para> + + <table> + <title>Invocation Mode</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname="switch" /> + <colspec colname="explanation" /> + <thead> + <row> + <entry>Switch</entry> + <entry>Explanation</entry> + </row> + </thead> + <tbody> + <row> + <entry>Neither <option>--as-pid2</option> nor <option>--boot</option> specified</entry> + <entry>The passed parameters are interpreted as command line, which is executed as PID 1 in the container.</entry> + </row> + + <row> + <entry><option>--as-pid2</option> specified</entry> + <entry>The passed parameters are interpreted as command line, which are executed as PID 2 in the container. A stub init process is run as PID 1.</entry> + </row> + + <row> + <entry><option>--boot</option> specified</entry> + <entry>An init binary as automatically searched and run as PID 1 in the container. The passed parameters are used as invocation parameters for this process.</entry> + </row> + + </tbody> + </tgroup> + </table> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--chdir=</option></term> + + <listitem><para>Change to the specified working directory before invoking the process in the container. Expects + an absolute path in the container's file system namespace.</para></listitem> </varlistentry> <varlistentry> @@ -770,8 +830,8 @@ <option>yes</option>, full volatile mode is enabled. This means the root directory is mounted as a mostly unpopulated <literal>tmpfs</literal> instance, and - <filename>/usr</filename> from the OS tree is mounted into it, - read-only (the system thus starts up with read-only OS + <filename>/usr</filename> from the OS tree is mounted into it + in read-only mode (the system thus starts up with read-only OS resources, but pristine state and configuration, any changes to the either are lost on shutdown). When the mode parameter is specified as <option>state</option>, the OS tree is diff --git a/man/systemd-path.xml b/man/systemd-path.xml index da6026e3b3..e2b23eec51 100644 --- a/man/systemd-path.xml +++ b/man/systemd-path.xml @@ -60,7 +60,7 @@ <para><command>systemd-path</command> may be used to query system and user paths. The tool makes many of the paths described in <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry> - queriable.</para> + available for querying.</para> <para>When invoked without arguments, a list of known paths and their current values is shown. When at least one argument is diff --git a/man/systemd-resolve.xml b/man/systemd-resolve.xml new file mode 100644 index 0000000000..f1e663c5bb --- /dev/null +++ b/man/systemd-resolve.xml @@ -0,0 +1,277 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-resolve" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-resolve</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-resolve</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-resolve</refname> + <refpurpose>Resolve domain names, IPV4 and IPv6 addresses, DNS resource records, and services</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-resolve</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain" rep="repeat"><replaceable>HOSTNAME</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>systemd-resolve</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain" rep="repeat"><replaceable>ADDRESS</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>systemd-resolve</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <command> --type=<replaceable>TYPE</replaceable></command> + <arg choice="plain" rep="repeat"><replaceable>RRDOMAIN</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>systemd-resolve</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <command> --service</command> + <arg choice="plain"><arg choice="opt"><arg choice="opt"><replaceable>NAME</replaceable></arg> + <replaceable>TYPE</replaceable></arg> <replaceable>DOMAIN</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>systemd-resolve</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <command> --statistics</command> + </cmdsynopsis> + + <cmdsynopsis> + <command>systemd-resolve</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <command> --reset-statistics</command> + </cmdsynopsis> + + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-resolve</command> may be used to resolve domain names, IPv4 and IPv6 addresses, DNS resource + records and services with the + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + resolver service. By default, the specified list of parameters will be resolved as hostnames, retrieving their IPv4 + and IPv6 addresses. If the parameters specified are formatted as IPv4 or IPv6 operation the reverse operation is + done, and a hostname is retrieved for the specified addresses.</para> + + <para>The <option>--type=</option> switch may be used to specify a DNS resource record type (A, AAAA, SOA, MX, ...) in + order to request a specific DNS resource record, instead of the address or reverse address lookups. + The special value <literal>help</literal> may be used to list known values.</para> + + <para>The <option>--service</option> switch may be used to resolve <ulink + url="https://tools.ietf.org/html/rfc2782">SRV</ulink> and <ulink + url="https://tools.ietf.org/html/rfc6763">DNS-SD</ulink> services (see below). In this mode, between one and three + arguments are required. If three parameters are passed the first is assumed to be the DNS-SD service name, the + second the SRV service type, and the third the domain to search in. In this case a full DNS-SD style SRV and TXT + lookup is executed. If only two parameters are specified, the first is assumed to be the SRV service type, and the + second the domain to look in. In this case no TXT RR is requested. Finally, if only one parameter is specified, it + is assumed to be a domain name, that is already prefixed with an SRV type, and an SRV lookup is done (no + TXT).</para> + + <para>The <option>--statistics</option> switch may be used to show resolver statistics, including information about + the number of succesful and failed DNSSEC validations.</para> + + <para>The <option>--reset-statistics</option> may be used to reset various statistics counters maintained the + resolver, including those shown in the <option>--statistics</option> output. This operation requires root + privileges.</para> + </refsect1> + + <refsect1> + <title>Options</title> + <variablelist> + <varlistentry> + <term><option>-4</option></term> + <term><option>-6</option></term> + + <listitem><para>By default, when resolving a hostname, both IPv4 and IPv6 + addresses are acquired. By specifying <option>-4</option> only IPv4 addresses are requested, by specifying + <option>-6</option> only IPv6 addresses are requested.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-i</option> <replaceable>INTERFACE</replaceable></term> + <term><option>--interface=</option><replaceable>INTERFACE</replaceable></term> + + <listitem><para>Specifies the network interface to execute the query on. This may either be specified as numeric + interface index or as network interface string (e.g. <literal>en0</literal>). Note that this option has no + effect if system-wide DNS configuration (as configured in <filename>/etc/resolv.conf</filename> or + <filename>/etc/systemd/resolve.conf</filename>) in place of per-link configuration is used.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-p</option> <replaceable>PROTOCOL</replaceable></term> + <term><option>--protocol=</option><replaceable>PROTOCOL</replaceable></term> + + <listitem><para>Specifies the network protocol for the query. May be one of <literal>dns</literal> + (i.e. classic unicast DNS), <literal>llmnr</literal> (<ulink + url="https://tools.ietf.org/html/rfc4795">Link-Local Multicast Name Resolution</ulink>), + <literal>llmr-ipv4</literal>, <literal>llmnr-ipv6</literal> (LLMNR via the indicated underlying IP + protocols). By default the lookup is done via all protocols suitable for the lookup. If used, limits the set of + protocols that may be used. Use this option multiple times to enable resolving via multiple protocols at the + same time. The setting <literal>llmnr</literal> is identical to specifying this switch once with + <literal>llmnr-ipv4</literal> and once via <literal>llmnr-ipv6</literal>. Note that this option does not force + the service to resolve the operation with the specified protocol, as that might require a suitable network + interface and configuration. + The special value <literal>help</literal> may be used to list known values. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-t</option> <replaceable>TYPE</replaceable></term> + <term><option>--type=</option><replaceable>TYPE</replaceable></term> + <term><option>-c</option> <replaceable>CLASS</replaceable></term> + <term><option>--class=</option><replaceable>CLASS</replaceable></term> + + <listitem><para>Specifies the DNS resource record type (e.g. A, AAAA, MX, …) and class (e.g. IN, ANY, …) to + look up. If these options are used a DNS resource record set matching the specified class and type is + requested. The class defaults to IN if only a type is specified. + The special value <literal>help</literal> may be used to list known values. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--service</option></term> + + <listitem><para>Enables service resolution. This enables DNS-SD and simple SRV service resolution, depending + on the specified list of parameters (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--service-address=</option><replaceable>BOOL</replaceable></term> + + <listitem><para>Takes a boolean parameter. If true (the default), when doing a service lookup with + <option>--service</option> the hostnames contained in the SRV resource records are resolved as well.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--service-txt=</option><replaceable>BOOL</replaceable></term> + + <listitem><para>Takes a boolean parameter. If true (the default), when doing a DNS-SD service lookup with + <option>--service</option> the TXT service metadata record is resolved as well.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--cname=</option><replaceable>BOOL</replaceable></term> + + <listitem><para>Takes a boolean parameter. If true (the default), DNS CNAME or DNAME redirections are + followed. Otherwise, if a CNAME or DNAME record is encountered while resolving, an error is + returned.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--search=</option><replaceable>BOOL</replaceable></term> + + <listitem><para>Takes a boolean parameter. If true (the default), any specified single-label hostnames will be + searched in the domains configured in the search domain list, if it is non-empty. Otherwise, the search domain + logic is disabled.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--legend=</option><replaceable>BOOL</replaceable></term> + + <listitem><para>Takes a boolean parameter. If true (the default), column headers and meta information about the + query response are shown. Otherwise, this output is suppressed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--statistics</option></term> + + <listitem><para>If specified general resolver statistics are shown, including information whether DNSSEC is + enabled and available, as well as resolution and validation statistics.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--reset-statistics</option></term> + + <listitem><para>Resets the statistics counters shown in <option>--statistics</option> to zero.</para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + + <example> + <title>Retrieve the addresses of the <literal>www.0pointer.net</literal> domain</title> + + <programlisting>$ systemd-resolve www.0pointer.net</programlisting> + </example> + + <example> + <title>Retrieve the domain of the <literal>85.214.157.71</literal> IP address</title> + + <programlisting>$ systemd-resolve 85.214.157.71</programlisting> + </example> + + <example> + <title>Retrieve the MX record of the <literal>0pointer.net</literal> domain</title> + + <programlisting>$ systemd-resolve -t MX 0pointer.net</programlisting> + </example> + + <example> + <title>Resolve an SRV service</title> + + <programlisting>$ systemd-resolve --service _xmpp-server._tcp gmail.com</programlisting> + </example> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> +</refentry> diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml index 43d568c6f7..4e144b5c98 100644 --- a/man/systemd-resolved.service.xml +++ b/man/systemd-resolved.service.xml @@ -56,15 +56,15 @@ <refsect1> <title>Description</title> - <para><command>systemd-resolved</command> is a system service that - manages network name resolution. It implements a caching DNS stub - resolver and an LLMNR resolver and responder. It also generates - <filename>/run/systemd/resolve/resolv.conf</filename> for - compatibility which may be symlinked from - <filename>/etc/resolv.conf</filename>. The glibc NSS module - <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry> - is necessary to allow libc's NSS resolver functions to resolve - host names via <command>systemd-resolved</command>.</para> + <para><command>systemd-resolved</command> is a system service that provides network name resolution to local + applications. It implements a caching and validating DNS/DNSSEC stub resolver, as well as an LLMNR resolver and + responder. In addition it maintains the <filename>/run/systemd/resolve/resolv.conf</filename> file for + compatibility with traditional Linux programs. This file may be symlinked from + <filename>/etc/resolv.conf</filename>.</para> + + <para>The glibc NSS module + <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry> is required to + permit glibc's NSS resolver functions to resolve host names via <command>systemd-resolved</command>.</para> <para>The DNS servers contacted are determined from the global settings in <filename>/etc/systemd/resolved.conf</filename>, the @@ -104,7 +104,7 @@ <itemizedlist> <listitem><para>Lookups for the special hostname <literal>localhost</literal> are never routed to the - network.</para></listitem> + network. (A few other, special domains are handled the same way.)</para></listitem> <listitem><para>Single-label names are routed to all local interfaces capable of IP multicasting, using the LLMNR @@ -117,7 +117,7 @@ <listitem><para>Multi-label names are routed to all local interfaces that have a DNS sever configured, plus the globally configured DNS server if there is one. Address lookups from the - link-local addres range are never routed to + link-local address range are never routed to DNS.</para></listitem> </itemizedlist> @@ -133,10 +133,8 @@ per-interface domains are exclusively routed to the matching interfaces.</para> - <para>Note that - <filename>/run/systemd/resolve/resolv.conf</filename> should not - be used directly, but only through a symlink from - <filename>/etc/resolv.conf</filename>.</para> + <para>Note that <filename>/run/systemd/resolve/resolv.conf</filename> should not be used directly by applications, + but only through a symlink from <filename>/etc/resolv.conf</filename>.</para> </refsect1> <refsect1> @@ -144,7 +142,10 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-resolve</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> </para> diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 5f98ef163c..f0f77c5091 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -807,6 +807,35 @@ </varlistentry> <varlistentry> + <term><varname>AmbientCapabilities=</varname></term> + + <listitem><para>Controls which capabilities to include in the + ambient capability set for the executed process. Takes a + whitespace-separated list of capability names as read by + <citerefentry project='mankier'><refentrytitle>cap_from_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + e.g. <constant>CAP_SYS_ADMIN</constant>, + <constant>CAP_DAC_OVERRIDE</constant>, + <constant>CAP_SYS_PTRACE</constant>. This option may appear more than + once in which case the ambient capability sets are merged. + If the list of capabilities is prefixed with <literal>~</literal>, all + but the listed capabilities will be included, the effect of the + assignment inverted. If the empty string is + assigned to this option, the ambient capability set is reset to + the empty capability set, and all prior settings have no effect. + If set to <literal>~</literal> (without any further argument), the + ambient capability set is reset to the full set of available + capabilities, also undoing any previous settings. Note that adding + capabilities to ambient capability set adds them to the process's + inherited capability set. + </para><para> + Ambient capability sets are useful if you want to execute a process + as a non-privileged user but still want to give it some capabilities. + Note that in this case option <constant>keep-caps</constant> is + automatically added to <varname>SecureBits=</varname> to retain the + capabilities over the user change.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>SecureBits=</varname></term> <listitem><para>Controls the secure bits set for the executed process. Takes a space-separated combination of options from diff --git a/man/systemd.generator.xml b/man/systemd.generator.xml index b36aab3259..62658fb115 100644 --- a/man/systemd.generator.xml +++ b/man/systemd.generator.xml @@ -315,7 +315,7 @@ </example> <example> - <title>Debuging a generator</title> + <title>Debugging a generator</title> <programlisting>dir=$(mktemp -d) SYSTEMD_LOG_LEVEL=debug &systemgeneratordir;/systemd-fstab-generator \ diff --git a/man/systemd.netdev.xml b/man/systemd.netdev.xml index 16e41e05b3..b697d0c9a6 100644 --- a/man/systemd.netdev.xml +++ b/man/systemd.netdev.xml @@ -493,6 +493,25 @@ VXLAN Group Policy </ulink> document. Defaults to false.</para> </listitem> </varlistentry> + <varlistentry> + <term><varname>DestinationPort=</varname></term> + <listitem> + <para>Configures the default destination UDP port on a per-device basis. + If destination port is not specified then Linux kernel default will be used. + Set destination port 4789 to get the IANA assigned value, + and destination port 0 to get default values.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>PortRange=</varname></term> + <listitem> + <para>Configures VXLAN port range. VXLAN bases source + UDP port based on flow to help the receiver to be able + to load balance based on outer header flow. It + restricts the port range to the normal UDP local + ports, and allows overriding via configuration.</para> + </listitem> + </varlistentry> </variablelist> </refsect1> <refsect1> diff --git a/man/systemd.network.xml b/man/systemd.network.xml index e6dedb027d..f88751b672 100644 --- a/man/systemd.network.xml +++ b/man/systemd.network.xml @@ -228,7 +228,7 @@ <literal>ipv4</literal>, or <literal>ipv6</literal>.</para> <para>Note that DHCPv6 will by default be triggered by Router - Advertisment, if that is enabled, regardless of this parameter. + Advertisement, if that is enabled, regardless of this parameter. By enabling DHCPv6 support explicitly, the DHCPv6 client will be started regardless of the presence of routers on the link, or what flags the routers pass. See @@ -277,10 +277,59 @@ <varlistentry> <term><varname>LLMNR=</varname></term> <listitem> - <para>A boolean or <literal>resolve</literal>. When true, enables - Link-Local Multicast Name Resolution on the link. When set to - <literal>resolve</literal>, only resolution is enabled, but not - announcement. Defaults to true.</para> + <para>A boolean or <literal>resolve</literal>. When true, + enables <ulink + url="https://tools.ietf.org/html/rfc4795">Link-Local + Multicast Name Resolution</ulink> on the link. When set to + <literal>resolve</literal>, only resolution is enabled, + but not host registration and announcement. Defaults to + true. This setting is read by + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MulticastDNS=</varname></term> + <listitem> + <para>A boolean or <literal>resolve</literal>. When true, + enables <ulink + url="https://tools.ietf.org/html/rfc6762">Multicast + DNS</ulink> support on the link. When set to + <literal>resolve</literal>, only resolution is enabled, + but not host or service registration and + announcement. Defaults to false. This setting is read by + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DNSSEC=</varname></term> + <listitem> + <para>A boolean or + <literal>allow-downgrade</literal>. When true, enables + <ulink + url="https://tools.ietf.org/html/rfc4033">DNSSEC</ulink> + DNS validation support on the link. When set to + <literal>allow-downgrade</literal>, compatibility with + non-DNSSEC capable networks is increased, by automatically + turning off DNSEC in this case. This option defines a + per-interface setting for + <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>'s + global <varname>DNSSEC=</varname> option. Defaults to + false. This setting is read by + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DNSSECNegativeTrustAnchors=</varname></term> + <listitem><para>A space-separated list of DNSSEC negative + trust anchor domains. If specified and DNSSEC is enabled, + look-ups done via the interface's DNS server will be subject + to the list of negative trust anchors, and not require + authentication for the specified domains, or anything below + it. Use this to disable DNSSEC authentication for specific + private domains, that cannot be proven valid using the + Internet DNS hierarchy. Defaults to the empty list. This + setting is read by + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> </listitem> </varlistentry> <varlistentry> @@ -346,19 +395,38 @@ <para>A DNS server address, which must be in the format described in <citerefentry project='man-pages'><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - This option may be specified more than once.</para> + This option may be specified more than once. This setting is read by + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> </listitem> </varlistentry> <varlistentry> <term><varname>Domains=</varname></term> <listitem> - <para>The domains used for DNS resolution over this link.</para> + <para>The domains used for DNS host name resolution on this link. Takes a list of DNS domain names which + are used as search suffixes for extending single-label host names (host names containing no dots) to become + fully qualified domain names (FQDNs). If a single-label host name is resolved on this interface, each of + the specified search domains are appended to it in turn, converting it into a fully qualified domain name, + until one of them may be successfully resolved.</para> + + <para>The specified domains are also used for routing of DNS queries: look-ups for host names ending in the + domains specified here are preferably routed to the DNS servers configured for this interface. If a domain + name is prefixed with <literal>~</literal>, the domain name becomes a pure "routing" domain, is used for + DNS query routing purposes only and is not used in the described domain search logic. By specifying a + routing domain of <literal>~.</literal> (the tilda indicating definition of a routing domain, the dot + referring to the DNS root domain which is the implied suffix of all valid DNS names) it is possible to + route all DNS traffic preferably to the DNS server specified for this interface. The route domain logic is + particularly useful on multi-homed hosts with DNS servers serving particular private DNS zones on each + interface.</para> + + <para>This setting is read by + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> </listitem> </varlistentry> <varlistentry> <term><varname>NTP=</varname></term> <listitem> - <para>An NTP server address. This option may be specified more than once.</para> + <para>An NTP server address. This option may be specified more than once. This setting is read by + <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> </listitem> </varlistentry> <varlistentry> @@ -649,15 +717,20 @@ <varlistentry> <term><varname>UseDomains=</varname></term> <listitem> - <para>When true (not the default), the domain name - received from the DHCP server will be used for DNS - resolution over this link. When a name cannot be resolved - as specified, the domain name will be used a suffix and - name resolution of that will be attempted.</para> + <para>Takes a boolean argument, or a the special value <literal>route</literal>. When true, the domain name + received from the DHCP server will be used as DNS search domain over this link, similar to the effect of + the <option>Domains=</option> setting. If set to <literal>route</literal>, the domain name received from + the DHCP server will be used for routing DNS queries only, but not for searching, similar to the effect of + the <option>Domains=</option> setting when the argument is prefixed with <literal>~</literal>. Defaults to + false.</para> + + <para>It is recommended to enable this option only on trusted networks, as setting this affects resolution + of all host names, in particular to single-label names. It is generally safer to use the supplied domain + only as routing domain, rather than as search domain, in order to not have it affect local resolution of + single-label names.</para> - <para>This corresponds to the <option>domain</option> - option in <citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and should not be enabled on untrusted networks.</para> + <para>When set to true, this setting corresponds to the <option>domain</option> option in <citerefentry + project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </listitem> </varlistentry> <varlistentry> @@ -673,7 +746,7 @@ <term><varname>UseTimezone=</varname></term> <listitem><para>When true, the timezone received from the - DHCP server will be set as as timezone of the local + DHCP server will be set as timezone of the local system. Defaults to <literal>no</literal>.</para></listitem> </varlistentry> @@ -1011,9 +1084,10 @@ DHCP=yes <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> + <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/systemd.nspawn.xml b/man/systemd.nspawn.xml index e952688331..c07a4b0243 100644 --- a/man/systemd.nspawn.xml +++ b/man/systemd.nspawn.xml @@ -141,15 +141,21 @@ <varlistentry> <term><varname>Boot=</varname></term> - <listitem><para>Takes a boolean argument, which defaults to off. If - enabled, <command>systemd-nspawn</command> will automatically - search for an <filename>init</filename> executable and invoke - it. In this case, the specified parameters using - <varname>Parameters=</varname> are passed as additional - arguments to the <filename>init</filename> process. This - setting corresponds to the <option>--boot</option> switch on - the <command>systemd-nspawn</command> command - line. </para></listitem> + <listitem><para>Takes a boolean argument, which defaults to off. If enabled, <command>systemd-nspawn</command> + will automatically search for an <filename>init</filename> executable and invoke it. In this case, the + specified parameters using <varname>Parameters=</varname> are passed as additional arguments to the + <filename>init</filename> process. This setting corresponds to the <option>--boot</option> switch on the + <command>systemd-nspawn</command> command line. This option may not be combined with + <varname>ProcessTwo=yes</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ProcessTwo=</varname></term> + + <listitem><para>Takes a boolean argument, which defaults to off. If enabled, the specified program is run as + PID 2. A stub init process is run as PID 1. This setting corresponds to the <option>--as-pid2</option> switch + on the <command>systemd-nspawn</command> command line. This option may not be combined with + <varname>Boot=yes</varname>.</para></listitem> </varlistentry> <varlistentry> @@ -187,12 +193,20 @@ </varlistentry> <varlistentry> + <term><varname>WorkingDirectory=</varname></term> + + <listitem><para>Selects the working directory for the process invoked in the container. Expects an absolute + path in the container's file system namespace. This corresponds to the <option>--chdir=</option> command line + switch.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>Capability=</varname></term> <term><varname>DropCapability=</varname></term> <listitem><para>Takes a space-separated list of Linux process capabilities (see - <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details). The <varname>Capability=</varname> setting specifies additional capabilities to pass on top of the default set of capabilities. The diff --git a/man/systemd.resource-control.xml b/man/systemd.resource-control.xml index b1106c759d..b6b38fde58 100644 --- a/man/systemd.resource-control.xml +++ b/man/systemd.resource-control.xml @@ -459,6 +459,12 @@ this setting is the parent slice. Since the name of a slice unit implies the parent slice, it is hence redundant to ever set this parameter directly for slice units.</para> + + <para>Special care should be taken when relying on the default slice assignment in templated service units + that have <varname>DefaultDependencies=no</varname> set, see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, section + "Automatic Dependencies" for details.</para> + </listitem> </varlistentry> diff --git a/man/systemd.service.xml b/man/systemd.service.xml index b998a1f81f..4cd36ac70e 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -113,6 +113,16 @@ involved with early boot or late system shutdown should disable this option.</para> + <para>Instanced service units (i.e. service units with an <literal>@</literal> in their name) are assigned by + default a per-template slice unit (see + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>), named after the + template unit, containing all instances of the specific template. This slice is normally stopped at shutdown, + together with all template instances. If that is not desired, set <varname>DefaultDependencies=no</varname> in the + template unit, and either define your own per-template slice unit file that also sets + <varname>DefaultDependencies=no</varname>, or set <varname>Slice=system.slice</varname> (or another suitable slice) + in the template unit. Also see + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + <para>Additional implicit dependencies may be added as result of execution and resource control parameters as documented in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> @@ -373,6 +383,11 @@ used to start long-running processes. All processes forked off by processes invoked via <varname>ExecStartPre=</varname> will be killed before the next service process is run.</para> + + <para>Note that if any of the commands specified in <varname>ExecStartPre=</varname>, + <varname>ExecStart=</varname>, or <varname>ExecStartPost=</varname> fail (and are not prefixed with + <literal>-</literal>, see above) or time out before the service is fully up, execution continues with commands + specified in <varname>ExecStopPost=</varname>, the commands in <varname>ExecStop=</varname> are skipped.</para> </listitem> </varlistentry> @@ -428,21 +443,36 @@ <constant>SIGKILL</constant> immediately after the command exited, this would not result in a clean stop. The specified command should hence be a synchronous operation, not an - asynchronous one.</para></listitem> + asynchronous one.</para> + + <para>Note that the commands specified in <varname>ExecStop=</varname> are only executed when the service + started successfuly first. They are not invoked if the service was never started at all, or in case its + start-up failed, for example because any of the commands specified in <varname>ExecStart=</varname>, + <varname>ExecStartPre=</varname> or <varname>ExecStartPost=</varname> failed (and weren't prefixed with + <literal>-</literal>, see above) or timed out. Use <varname>ExecStopPost=</varname> to invoke commands when a + service failed to start up correctly and is shut down again.</para> + + <para>It is recommended to use this setting for commands that communicate with the service requesting clean + termination. When the commands specified with this option are executed it should be assumed that the service is + still fully up and is able to react correctly to all commands. For post-mortem clean-up steps use + <varname>ExecStopPost=</varname> instead.</para></listitem> </varlistentry> <varlistentry> <term><varname>ExecStopPost=</varname></term> - <listitem><para>Additional commands that are executed after - the service was stopped. This includes cases where the - commands configured in <varname>ExecStop=</varname> were used, - where the service does not have any - <varname>ExecStop=</varname> defined, or where the service - exited unexpectedly. This argument takes multiple command - lines, following the same scheme as described for - <varname>ExecStart=</varname>. Use of these settings is - optional. Specifier and environment variable substitution is - supported.</para></listitem> + <listitem><para>Additional commands that are executed after the service is stopped. This includes cases where + the commands configured in <varname>ExecStop=</varname> were used, where the service does not have any + <varname>ExecStop=</varname> defined, or where the service exited unexpectedly. This argument takes multiple + command lines, following the same scheme as described for <varname>ExecStart=</varname>. Use of these settings + is optional. Specifier and environment variable substitution is supported. Note that – unlike + <varname>ExecStop=</varname> – commands specified with this setting are invoked when a service failed to start + up correctly and is shut down again.</para> + + <para>It is recommended to use this setting for clean-up operations that shall be executed even when the + service failed to start up correctly. Commands configured with this setting need to be able to operate even if + the service failed starting up half-way and left incompletely initialized data around. As the service's + processes have been terminated already when the commands specified with this setting are executed they should + not attempt to communicate with them.</para></listitem> </varlistentry> <varlistentry> @@ -460,7 +490,7 @@ configured time, the service will be considered failed and will be shut down again. Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass - <literal>0</literal> to disable the timeout logic. Defaults to + <literal>infinity</literal> to disable the timeout logic. Defaults to <varname>DefaultTimeoutStartSec=</varname> from the manager configuration file, except when <varname>Type=oneshot</varname> is used, in which case the @@ -479,7 +509,7 @@ <varname>KillMode=</varname> in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). Takes a unit-less value in seconds, or a time span value such - as "5min 20s". Pass <literal>0</literal> to disable the + as "5min 20s". Pass <literal>infinity</literal> to disable the timeout logic. Defaults to <varname>DefaultTimeoutStopSec=</varname> from the manager configuration file (see @@ -496,6 +526,16 @@ </varlistentry> <varlistentry> + <term><varname>RuntimeMaxSec=</varname></term> + + <listitem><para>Configures a maximum time for the service to run. If this is used and the service has been + active for longer than the specified time it is terminated and put into a failure state. Note that this setting + does not have any effect on <varname>Type=oneshot</varname> services, as they terminate immediately after + activation completed. Pass <literal>infinity</literal> (the default) to configure no runtime + limit.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>WatchdogSec=</varname></term> <listitem><para>Configures the watchdog timeout for a service. The watchdog is activated when the start-up is completed. The diff --git a/man/systemd.special.xml b/man/systemd.special.xml index 54e7c49a9e..0a37f65956 100644 --- a/man/systemd.special.xml +++ b/man/systemd.special.xml @@ -92,6 +92,7 @@ <filename>shutdown.target</filename>, <filename>sigpwr.target</filename>, <filename>sleep.target</filename>, + <filename>slices.target</filename>, <filename>smartcard.target</filename>, <filename>sockets.target</filename>, <filename>sound.target</filename>, @@ -503,10 +504,23 @@ </listitem> </varlistentry> <varlistentry> + <term><filename>slices.target</filename></term> + <listitem> + <para>A special target unit that sets up all slice units (see + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + details) that shall be active after boot. By default the generic <filename>user.slice</filename>, + <filename>system.slice</filename>, <filename>machines.slice</filename> slice units, as well as the the root + slice unit <filename>-.slice</filename> are pulled in and ordered before this unit (see below).</para> + + <para>It's a good idea to add <varname>WantedBy=slices.target</varname> lines to the <literal>[Install]</literal> + section of all slices units that may be installed dynamically.</para> + </listitem> + </varlistentry> + <varlistentry> <term><filename>sockets.target</filename></term> <listitem> <para>A special target unit that sets up all socket - units.(see + units (see <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details) that shall be active after boot.</para> @@ -587,7 +601,7 @@ <varlistentry> <term><filename>umount.target</filename></term> <listitem> - <para>A special target unit that umounts all mount and + <para>A special target unit that unmounts all mount and automount points on system shutdown.</para> <para>Mounts that shall be unmounted on system shutdown diff --git a/man/systemd.timer.xml b/man/systemd.timer.xml index cfa13015b0..29e235e2dc 100644 --- a/man/systemd.timer.xml +++ b/man/systemd.timer.xml @@ -284,7 +284,7 @@ unloaded. Turning this off is particularly useful for transient timer units that shall disappear after they first elapse. Note that this setting has an effect on repeatedly - starting the a timer unit that only elapses once: if + starting a timer unit that only elapses once: if <varname>RemainAfterElapse=</varname> is on, it will not be started again, and is guaranteed to elapse only once. However, if <varname>RemainAfterLeapse=</varname> is off, it might be diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 5b12378eda..a95c160954 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -191,6 +191,17 @@ <literal>.d/</literal> subdirectory and reads its <literal>.conf</literal> files.</para> + <para>In addition to <filename>/etc/systemd/system</filename>, + the drop-in <literal>.conf</literal> files for system services + can be placed in <filename>/usr/lib/systemd/system</filename> or + <filename>/run/systemd/system</filename> directories. Drop-in + files in <filename>/etc</filename> take precedence over those in + <filename>/run</filename> which in turn take precedence over + those in <filename>/usr/lib</filename>. Drop-in files under any of + these directories take precedence over unit files wherever located. + (Of course, since <filename>/run</filename> is temporary and + <filename>/usr/lib</filename> is for vendors, it is unlikely + drop-ins should be used in either of those places.)</para> <!-- Note that we do not document .include here, as we consider it mostly obsolete, and want people to use .d/ drop-ins instead. --> @@ -875,7 +886,7 @@ <para><varname>ConditionSecurity=</varname> may be used to check whether the given security module is enabled on the - system. Currently, the recognized values values are + system. Currently, the recognized values are <varname>selinux</varname>, <varname>apparmor</varname>, <varname>ima</varname>, @@ -918,7 +929,7 @@ <filename>/var</filename> on the next following boot. Units making use of this condition should order themselves before <citerefentry><refentrytitle>systemd-update-done.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - to make sure they run before the stamp files's modification + to make sure they run before the stamp file's modification time gets reset indicating a completed update.</para> <para><varname>ConditionFirstBoot=</varname> takes a boolean @@ -1402,6 +1413,7 @@ PrivateTmp=yes</programlisting> cannot be reset to an empty list, so dependencies can only be added in drop-ins. If you want to remove dependencies, you have to override the entire unit.</para> + </example> </refsect1> diff --git a/man/systemd.xml b/man/systemd.xml index 6de18f8294..b8d91b8943 100644 --- a/man/systemd.xml +++ b/man/systemd.xml @@ -255,6 +255,14 @@ <option>inherit</option>.</para></listitem> </varlistentry> + <varlistentry> + <term><option>--machine-id=</option></term> + + <listitem><para>Override the machine-id set on the hard drive, + useful for network booting or for containers. May not be set + to all zeros.</para></listitem> + </varlistentry> + <xi:include href="standard-options.xml" xpointer="help" /> <xi:include href="standard-options.xml" xpointer="version" /> </variablelist> @@ -827,6 +835,13 @@ </varlistentry> <varlistentry> + <term><varname>$SYSTEMD_COLORS</varname></term> + + <listitem><para>Controls whether colorized output should be generated. + </para></listitem> + </varlistentry> + + <varlistentry> <term><varname>$LISTEN_PID</varname></term> <term><varname>$LISTEN_FDS</varname></term> <term><varname>$LISTEN_FDNAMES</varname></term> @@ -977,6 +992,15 @@ </varlistentry> <varlistentry> + <term><varname>systemd.machine_id=</varname></term> + + <listitem><para>Takes a 32 character hex value to be + used for setting the machine-id. Intended mostly for + network booting where the same machine-id is desired + for every boot.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>quiet</varname></term> <listitem><para>Turn off status output at boot, much like diff --git a/man/sysusers.d.xml b/man/sysusers.d.xml index 42b53b2759..18ee3800d6 100644 --- a/man/sysusers.d.xml +++ b/man/sysusers.d.xml @@ -113,7 +113,7 @@ u root 0 "Superuser" /root</programlisting> <varlistentry> <term><varname>m</varname></term> <listitem><para>Add a user to a group. If the user or group - are not existing yet, they will be implicitly + do not exist yet, they will be implicitly created.</para></listitem> </varlistentry> diff --git a/man/timesyncd.conf.xml b/man/timesyncd.conf.xml index 10c2de89f6..8c86fd0074 100644 --- a/man/timesyncd.conf.xml +++ b/man/timesyncd.conf.xml @@ -68,6 +68,8 @@ <refsect1> <title>Options</title> + <para>The following settings are configured in the <literal>[Time]</literal> section:</para> + <variablelist class='network-directives'> <varlistentry> diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml index 5bf1f2956b..3b6b1e3f11 100644 --- a/man/tmpfiles.d.xml +++ b/man/tmpfiles.d.xml @@ -264,7 +264,8 @@ be removed and be replaced by the symlink. If the argument is omitted, symlinks to files with the same name residing in the directory <filename>/usr/share/factory/</filename> are - created.</para></listitem> + created. Note that permissions and ownership on symlinks + are ignored.</para></listitem> </varlistentry> <varlistentry> @@ -421,7 +422,7 @@ <command>systemd-tmpfiles</command> will automatically add the required base entries for user and group based on the access mode of the file, unless base entries already exist - or are explictly specified. The mask will be added if not + or are explicitly specified. The mask will be added if not specified explicitly or already present. Lines of this type accept shell-style globs in place of normal path names. This can be useful for allowing additional access to certain diff --git a/man/udev_device_new_from_syspath.xml b/man/udev_device_new_from_syspath.xml index 11db1a0fab..0bb71c8e91 100644 --- a/man/udev_device_new_from_syspath.xml +++ b/man/udev_device_new_from_syspath.xml @@ -134,7 +134,7 @@ a <filename>uevent</filename> file. <function>udev_device_new_from_devnum</function> takes a device type, which can be <constant>b</constant> for block devices or <constant>c</constant> for character devices, as well as a devnum (see - <citerefentry><refentrytitle>makedev</refentrytitle><manvolnum>3</manvolnum></citerefentry>). + <citerefentry project='man-pages'><refentrytitle>makedev</refentrytitle><manvolnum>3</manvolnum></citerefentry>). <function>udev_device_new_from_subsystem_sysname</function> looks up devices based on the provided subsystem and sysname (see <citerefentry><refentrytitle>udev_device_get_subsystem</refentrytitle><manvolnum>3</manvolnum></citerefentry> @@ -171,7 +171,7 @@ <para><function>udev_device_new_from_environment</function> creates a device from the current environment (see - <citerefentry><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>). + <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>). Each key-value pair is interpreted in the same way as if it was received in an uevent (see <citerefentry><refentrytitle>udev_monitor_receive_device</refentrytitle><manvolnum>3</manvolnum></citerefentry>). @@ -189,7 +189,8 @@ <function>udev_device_new_from_device_id()</function> and <function>udev_device_new_from_environment()</function> return a pointer to the allocated udev device. On failure, - <constant>NULL</constant> is returned. + <constant>NULL</constant> is returned, + and <varname>errno</varname> is set appropriately. <function>udev_device_ref()</function> returns the argument that it was passed, unmodified. <function>udev_device_unref()</function> always returns |