diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/logind.conf.xml | 16 | ||||
| -rw-r--r-- | man/resolved.conf.xml | 76 | ||||
| -rw-r--r-- | man/sd-bus.xml | 123 | ||||
| -rw-r--r-- | man/sd_event_add_io.xml | 92 | ||||
| -rw-r--r-- | man/sd_event_add_signal.xml | 35 | ||||
| -rw-r--r-- | man/sd_event_add_time.xml | 80 | ||||
| -rw-r--r-- | man/sd_event_now.xml | 43 | ||||
| -rw-r--r-- | man/sd_event_source_get_pending.xml | 2 | ||||
| -rw-r--r-- | man/systemd-activate.xml | 10 | ||||
| -rw-r--r-- | man/systemd-ask-password.xml | 4 | ||||
| -rw-r--r-- | man/systemd-journal-remote.xml | 15 | ||||
| -rw-r--r-- | man/systemd-resolve.xml | 272 | ||||
| -rw-r--r-- | man/systemd-resolved.service.xml | 27 | ||||
| -rw-r--r-- | man/systemd.network.xml | 47 | ||||
| -rw-r--r-- | man/systemd.nspawn.xml | 2 | ||||
| -rw-r--r-- | man/systemd.unit.xml | 12 | ||||
| -rw-r--r-- | man/systemd.xml | 7 | ||||
| -rw-r--r-- | man/udev_device_new_from_syspath.xml | 4 |
18 files changed, 651 insertions, 216 deletions
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/resolved.conf.xml b/man/resolved.conf.xml index 5da2d5488e..3aa9c3acb1 100644 --- a/man/resolved.conf.xml +++ b/man/resolved.conf.xml @@ -72,40 +72,40 @@ <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,28 +119,12 @@ <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>MulticastDNS=</varname></term> - <listitem><para>Takes a boolean argument or - <literal>resolve</literal>. Controls Multicast DNS support - (<ulink url="https://tools.ietf.org/html/rfc6762">RFC - 6762</ulink>) on the local host. If true, enables full - Multicast DNS responder and resolver support. If false, - disables both. If set to <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 Multicast DNS settings. Multicast - DNS will be enabled on an interface only if the per-interface - 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 @@ -197,9 +181,9 @@ <para>In addition to this global DNSSEC setting <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - also maintains per-interface DNSSEC settings. For system DNS + also maintains per-link DNSSEC settings. For system DNS servers (see above), only the global DNSSEC setting is in - effect. For per-interface DNS servers the per-interface + 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> @@ -226,7 +210,7 @@ <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>resolv.conf</refentrytitle><manvolnum>4</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_add_io.xml b/man/sd_event_add_io.xml index eeb406ba5b..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 + 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 continuously 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 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> + <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 a2aabd3c1a..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> + 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 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> + <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 b58d740bd8..142fa80f8f 100644 --- a/man/sd_event_add_time.xml +++ b/man/sd_event_add_time.xml @@ -122,31 +122,31 @@ clock identifier, one of <constant>CLOCK_REALTIME</constant>, <constant>CLOCK_MONOTONIC</constant>, <constant>CLOCK_BOOTTIME</constant>, - <constant>CLOCK_REALTIME_ALARM</constant> or + <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 + <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. 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, thus improving + 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 - time it was triggered, however it might actually have been called - at a slightly later time, subject to the specified accuracy value, + 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>) + <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> @@ -167,22 +167,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> + 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 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> + <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 +194,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 +214,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 +254,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_now.xml b/man/sd_event_now.xml index 58d7375eac..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 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/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-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-resolve.xml b/man/systemd-resolve.xml new file mode 100644 index 0000000000..c5ad6a0e3e --- /dev/null +++ b/man/systemd-resolve.xml @@ -0,0 +1,272 @@ +<?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.</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.</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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--service</option></term> + + <listitem><para>Enables service resolution. This enables DNS-SD and simple SRV service resolution, dependending + 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 8e1ca1c092..ba36c5d9f0 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 @@ -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> @@ -146,6 +144,7 @@ <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><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> diff --git a/man/systemd.network.xml b/man/systemd.network.xml index 5a6383cfc2..f88751b672 100644 --- a/man/systemd.network.xml +++ b/man/systemd.network.xml @@ -396,21 +396,37 @@ described in <citerefentry project='man-pages'><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This option may be specified more than once. This setting is read by - <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></para> + <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. This setting is read by - <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></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. This setting is read by - <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></para> + <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> </listitem> </varlistentry> <varlistentry> @@ -701,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>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>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>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> diff --git a/man/systemd.nspawn.xml b/man/systemd.nspawn.xml index e952688331..f39e1ad42c 100644 --- a/man/systemd.nspawn.xml +++ b/man/systemd.nspawn.xml @@ -192,7 +192,7 @@ <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.unit.xml b/man/systemd.unit.xml index 9846659134..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. --> @@ -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 b5570a4347..b8d91b8943 100644 --- a/man/systemd.xml +++ b/man/systemd.xml @@ -835,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> diff --git a/man/udev_device_new_from_syspath.xml b/man/udev_device_new_from_syspath.xml index 11db1a0fab..c71356a75a 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>). |