1
1
mirror of https://github.com/systemd/systemd-stable.git synced 2025-02-04 17:47:03 +03:00

Merge pull request #18801 from keszybz/small-documentation-updates

Small documentation updates
This commit is contained in:
Lennart Poettering 2021-02-26 09:36:11 +01:00 committed by GitHub
commit 42d7904284
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
13 changed files with 103 additions and 72 deletions

View File

@ -1,6 +1,9 @@
<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % entities SYSTEM "custom-entities.ent" >
%entities;
]>
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
<refentry id="hostnamectl" conditional='ENABLE_HOSTNAMED'
@ -76,9 +79,13 @@
still following the validity rules of the specific name. This simplification of the hostname string is not done
if only the transient and/or static hostnames are set, and the pretty hostname is left untouched.</para>
<para>Pass the empty string <literal></literal> as the
hostname to reset the selected hostnames to their default
(usually <literal>localhost</literal>).</para></listitem>
<para>The static and transient hostnames must each be either a single DNS label (a string composed of
7-bit ASCII lower-case characters and no spaces or dots, limited to the format allowed for DNS domain
name labels), or a sequence of such labels separated by single dots that forms a valid DNS FQDN. The
hostname must be at most 64 characters, which is a Linux limitation (DNS allows longer names).</para>
<para>Pass the empty string <literal></literal> as the hostname to reset the selected hostnames to
their default (usually <literal>&FALLBACK_HOSTNAME;</literal>).</para></listitem>
</varlistentry>
<varlistentry>

View File

@ -325,7 +325,8 @@
present and no other configuration source specifies the hostname. Must be either a single DNS label
(a string composed of 7-bit ASCII lower-case characters and no spaces or dots, limited to the format
allowed for DNS domain name labels), or a sequence of such labels separated by single dots that forms
a valid DNS FQDN. The total length must be at most 64 characters.</para>
a valid DNS FQDN. The hostname must be at most 64 characters, which is a Linux limitation (DNS allows
longer names).</para>
<para>See
<citerefentry><refentrytitle>org.freedesktop.hostname1</refentrytitle><manvolnum>5</manvolnum></citerefentry>

View File

@ -74,7 +74,7 @@
should be read. See the table below for a complete list of allowed arguments and their types. Note that,
if the basic type is a pointer (e.g., <type>const char *</type> in the case of a string), the argument is
a pointer to a pointer, and also the pointer value that is written is only borrowed and the contents must
be copied if they are to be used after the end of the messages lifetime. If the type is
be copied if they are to be used after the end of the message's lifetime. If the type is
<literal>h</literal> (UNIX file descriptor), the descriptor is not duplicated by this call and the
returned descriptor remains in possession of the message object, and needs to be duplicated by the caller
in order to keep an open reference to it after the message object is freed.</para>

View File

@ -58,12 +58,12 @@
<parameter>type</parameter> is <constant>'s'</constant>, the object passed in <parameter>p</parameter>
should have type <type>const char **</type>. Note that, if the basic type is a pointer (e.g.,
<type>const char *</type> in the case of a string), the pointer is only borrowed and the contents must
be copied if they are to be used after the end of the messages lifetime. Similarly, during the lifetime
of such a pointer, the message must not be modified. If <parameter>type</parameter> is
be copied if they are to be used after the end of the message's lifetime. Similarly, during the
lifetime of such a pointer, the message must not be modified. If <parameter>type</parameter> is
<constant>'h'</constant> (UNIX file descriptor), the descriptor is not duplicated by this call and the
returned descriptor remains in possession of the message object, and needs to be duplicated by the caller
in order to keep an open reference to it after the message object is freed (for example by calling
<literal>fcntl(fd, FD_DUPFD_CLOEXEC, 3)</literal>). See the table below for a complete list of
returned descriptor remains in possession of the message object, and needs to be duplicated by the
caller in order to keep an open reference to it after the message object is freed (for example by
calling <literal>fcntl(fd, FD_DUPFD_CLOEXEC, 3)</literal>). See the table below for a complete list of
allowed types.
</para>

View File

@ -181,13 +181,13 @@
<entry>A virtual tunnel interface like vti/vti6 but with several advantages.</entry></row>
<row><entry><varname>ifb</varname></entry>
<entry> The Intermediate Functional Block (ifb) pseudo network interface acts as a QoS concentrator for multiple different sources of traffic.</entry></row>
<entry>The Intermediate Functional Block (ifb) pseudo network interface acts as a QoS concentrator for multiple different sources of traffic.</entry></row>
<row><entry><varname>bareudp</varname></entry>
<entry> Bare UDP tunnels provide a generic L3 encapsulation support for tunnelling different L3 protocols like MPLS, IP etc. inside of an UDP tunnel.</entry></row>
<entry>Bare UDP tunnels provide a generic L3 encapsulation support for tunnelling different L3 protocols like MPLS, IP etc. inside of an UDP tunnel.</entry></row>
<row><entry><varname>batadv</varname></entry>
<entry> (<ulink url="https://www.open-mesh.org/projects/open-mesh/wiki">B.A.T.M.A.N. Advanced</ulink>) is a routing protocol for multi-hop mobile ad hoc networks which operates on layer2.</entry></row>
<entry><ulink url="https://www.open-mesh.org/projects/open-mesh/wiki">B.A.T.M.A.N. Advanced</ulink> is a routing protocol for multi-hop mobile ad-hoc networks which operates on layer 2.</entry></row>
</tbody>
</tgroup>
</table>

View File

@ -63,6 +63,25 @@
url="https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New
Control Group Interfaces</ulink> for an introduction on how to make
use of resource control APIs from programs.</para>
<refsect2>
<title>Setting resource controls for a group of related units</title>
<para>As described in
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, the
settings listed here may be set through the main file of a unit and drop-in snippets in
<filename index="false">*.d/</filename> directories. The list of directories searched for drop-ins
includes names formed by repeatedly truncating the unit name after all dashes. This is particularly
convenient to set resource limits for a group of units with similar names.</para>
<para>For example, every user gets their own slice
<filename>user-<replaceable>nnn</replaceable>.slice</filename>. Drop-ins with local configuration that
affect user 1000 may be placed in
<filename index="false">/etc/systemd/system/user-1000.slice</filename>,
<filename index="false">/etc/systemd/system/user-1000.slice.d/*.conf</filename>, but also
<filename index="false">/etc/systemd/system/user-.slice.d/*.conf</filename>. This last directory
applies to all user slices.</para>
</refsect2>
</refsect1>
<refsect1>
@ -918,31 +937,30 @@ DeviceAllow=/dev/loop-control
<term><varname>ManagedOOMPreference=none|avoid|omit</varname></term>
<listitem>
<para>Allows deprioritizing or omitting this unit's cgroup as a candidate when <command>systemd-oomd</command>
needs to act. Requires support for extended attributes (see
<para>Allows deprioritizing or omitting this unit's cgroup as a candidate when
<command>systemd-oomd</command> needs to act. Requires support for extended attributes (see
<citerefentry project='man-pages'><refentrytitle>xattr</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
in order to use <option>avoid</option> or <option>omit</option>. Additionally, <command>systemd-oomd</command>
will ignore these extended attributes if the unit's cgroup is not owned by the root user.</para>
in order to use <option>avoid</option> or <option>omit</option>. Additionally,
<command>systemd-oomd</command> will ignore these extended attributes if the unit's cgroup is not
owned by the root user.</para>
<para>If this property is set to <option>avoid</option>, the service manager will set the
"user.oomd_avoid" extended attribute on the unit's cgroup to "1". If <command>systemd-oomd</command> sees
this extended attribute on a cgroup set to "1" when choosing between candidates, it will only select the
cgroup with "user.oomd_avoid" if there are no other viable candidates.</para>
<para>If this property is set to <option>avoid</option>, the service manager will convey this to
<command>systemd-oomd</command>, which will only select this cgroup if there are no other viable
candidates.</para>
<para>If this property is set to <option>omit</option>, the service manager will set the "user.oomd_omit"
extended attribute on the unit's cgroup to "1". If <command>systemd-oomd</command> sees the this extended
attribute on the cgroup set to "1", it will ignore the cgroup as a candidate and will not perform any actions
on the cgroup.</para>
<para>If this property is set to <option>omit</option>, the service manager will convey this to
<command>systemd-oomd</command>, which will ignore this cgroup as a candidate and will not perform
any actions on it.</para>
<para>It is recommended to use <option>avoid</option> and <option>omit</option> sparingly as it can adversely
affect <command>systemd-oomd</command>'s kill behavior. Also note that these extended attributes are not
applied recursively to cgroups under this unit's cgroup.</para>
<para>It is recommended to use <option>avoid</option> and <option>omit</option> sparingly, as it
can adversely affect <command>systemd-oomd</command>'s kill behavior. Also note that these extended
attributes are not applied recursively to cgroups under this unit's cgroup.</para>
<para>Defaults to <option>none</option> which means no extended attributes will be set and systemd-oomd will
sort this unit's cgroup as defined in
<para>Defaults to <option>none</option> which means <command>systemd-oomd</command> will rank this
unit's cgroup as defined in
<citerefentry><refentrytitle>systemd-oomd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
and <citerefentry><refentrytitle>oomd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> (if this
unit's cgroup becomes a candidate).</para>
and <citerefentry><refentrytitle>oomd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
</listitem>
</varlistentry>
</variablelist>

View File

@ -190,8 +190,8 @@
headers. For instantiated units, this logic will first look for the instance <literal>.d/</literal> subdirectory
(e.g. <literal>foo@bar.service.d/</literal>) and read its <literal>.conf</literal> files, followed by the template
<literal>.d/</literal> subdirectory (e.g. <literal>foo@.service.d/</literal>) and the <literal>.conf</literal>
files there. Moreover for units names containing dashes (<literal>-</literal>), the set of directories generated by
truncating the unit name after all dashes is searched too. Specifically, for a unit name
files there. Moreover for unit names containing dashes (<literal>-</literal>), the set of directories generated by
repeatedly truncating the unit name after all dashes is searched too. Specifically, for a unit name
<filename>foo-bar-baz.service</filename> not only the regular drop-in directory
<filename>foo-bar-baz.service.d/</filename> is searched but also both <filename>foo-bar-.service.d/</filename> and
<filename>foo-.service.d/</filename>. This is useful for defining common drop-ins for a set of related units, whose

View File

@ -47,54 +47,59 @@
<varlistentry>
<term><varname>NTP=</varname></term>
<listitem><para>A space-separated list of NTP server host
names or IP addresses. During runtime this list is combined
with any per-interface NTP servers acquired from
<listitem><para>A space-separated list of NTP server host names or IP addresses. During runtime this
list is combined with any per-interface NTP servers acquired from
<citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
systemd-timesyncd will contact all configured system or
per-interface servers in turn until one is found that
responds. When the empty string is assigned, the list of
NTP servers is reset, and all assignments prior to this one
will have no effect. This setting defaults to an empty
list.</para></listitem>
<command>systemd-timesyncd</command> will contact all configured system or per-interface servers in
turn, until one responds. When the empty string is assigned, the list of NTP servers is reset, and
all prior assignments will have no effect. This setting defaults to an empty list.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>FallbackNTP=</varname></term>
<listitem><para>A space-separated list of NTP server host
names or IP addresses to be used as the fallback NTP servers.
Any per-interface NTP servers obtained from
<listitem><para>A space-separated list of NTP server host names or IP addresses to be used as the
fallback NTP servers. Any per-interface NTP 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>NTP=</varname> above. This setting is hence only used
if no other NTP server information is known. When the empty
string is assigned, the list of NTP servers is reset,
and all assignments prior to this one will have no effect.
If this option is not given, a compiled-in list of NTP servers
is used instead.</para></listitem>
take precedence over this setting, as do any servers set via <varname>NTP=</varname> above. This
setting is hence only relevant if no other NTP server information is known. When the empty string is
assigned, the list of NTP servers is reset, and all prior assignments will have no effect. If this
option is not given, a compiled-in list of NTP servers is used.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>RootDistanceMaxSec=</varname></term>
<listitem><para>Maximum acceptable root distance. Takes a time value (in seconds).
<listitem><para>Maximum acceptable root distance, i.e. the maximum estimated time required for a
packet to travel to the server we are connected to from the server with the reference clock. If
the current server does not satisfy this limit, <command>systemd-timesyncd</command> will switch
to a different server.</para>
<para>Takes a time value. The default unit is seconds, but other units may be specified, see
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
Defaults to 5 seconds.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>PollIntervalMinSec=</varname></term>
<term><varname>PollIntervalMaxSec=</varname></term>
<listitem><para>The minimum and maximum poll intervals for NTP messages.
Each setting takes a time value (in seconds).
<varname>PollIntervalMinSec=</varname> must not be smaller than 16 seconds.
<varname>PollIntervalMaxSec=</varname> must be larger than <varname>PollIntervalMinSec=</varname>.
<varname>PollIntervalMinSec=</varname> defaults to 32 seconds, and
<varname>PollIntervalMaxSec=</varname> defaults to 2048 seconds.</para></listitem>
<listitem><para>The minimum and maximum poll intervals for NTP messages. Polling starts at the
minimum poll interval, and is adjusted within the specified limits in response to received packets.
</para>
<para>Each setting takes a time value. The default unit is seconds, but other units may be specified,
see <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
<varname>PollIntervalMinSec=</varname> defaults to 32 seconds and must not be smaller than
16 seconds. <varname>PollIntervalMaxSec=</varname> defaults to 34 min 8 s (2048 seconds) and must be
larger than <varname>PollIntervalMinSec=</varname>.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>ConnectionRetrySec=</varname></term>
<listitem><para>Specifies the delaying attempts to contact servers after network is online. Takes a time value (in seconds).
Defaults to 30 seconds and must not be smaller than 1 seconds.</para></listitem>
<listitem><para>Specifies the minimum delay before subsequent attempts to contact a new NTP server
are made.</para>
<para>Takes a time value. The default unit is seconds, but other units may be specified, see
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
Defaults to 30 seconds and must not be smaller than 1 second.</para></listitem>
</varlistentry>
</variablelist>

View File

@ -125,7 +125,7 @@
<title>Values</title>
<para>Values are written as double quoted strings, such as ("string").
To include a quotation mark (") in the value, precede it by a backslash (\").
Any other occurrences of a character followed by a backslash are not further unescaped.
Any other occurrences of a backslash followed by a character are not unescaped.
That is, "\t\n" is treated as four characters:
backslash, lowercase t, backslash, lowercase n.</para>
@ -459,7 +459,7 @@
<para>Specify a program to be executed after processing of all the rules for the event. With
<literal>+=</literal>, this invocation is added to the list, and with <literal>=</literal> or
<literal>:=</literal>, it replaces any previous contents of the list. Please note that both
<literal>program</literal> and <literal>builtin</literal> types described below use a single
<literal>program</literal> and <literal>builtin</literal> types described below share a common
list, so clearing the list with <literal>:=</literal> and <literal>=</literal> affects both
types.</para>

View File

@ -165,7 +165,7 @@ static const sd_bus_vtable manager_vtable[] = {
SD_BUS_PROPERTY("FallbackNTPServers", "as", property_get_servers, offsetof(Manager, fallback_servers), SD_BUS_VTABLE_PROPERTY_CONST),
SD_BUS_PROPERTY("ServerName", "s", property_get_current_server_name, offsetof(Manager, current_server_name), 0),
SD_BUS_PROPERTY("ServerAddress", "(iay)", property_get_current_server_address, offsetof(Manager, current_server_address), 0),
SD_BUS_PROPERTY("RootDistanceMaxUSec", "t", bus_property_get_usec, offsetof(Manager, max_root_distance_usec), SD_BUS_VTABLE_PROPERTY_CONST),
SD_BUS_PROPERTY("RootDistanceMaxUSec", "t", bus_property_get_usec, offsetof(Manager, root_distance_max_usec), SD_BUS_VTABLE_PROPERTY_CONST),
SD_BUS_PROPERTY("PollIntervalMinUSec", "t", bus_property_get_usec, offsetof(Manager, poll_interval_min_usec), SD_BUS_VTABLE_PROPERTY_CONST),
SD_BUS_PROPERTY("PollIntervalMaxUSec", "t", bus_property_get_usec, offsetof(Manager, poll_interval_max_usec), SD_BUS_VTABLE_PROPERTY_CONST),
SD_BUS_PROPERTY("PollIntervalUSec", "t", bus_property_get_usec, offsetof(Manager, poll_interval_usec), 0),

View File

@ -21,7 +21,7 @@ struct ConfigPerfItem;
Time.NTP, config_parse_servers, SERVER_SYSTEM, 0
Time.Servers, config_parse_servers, SERVER_SYSTEM, 0
Time.FallbackNTP, config_parse_servers, SERVER_FALLBACK, 0
Time.RootDistanceMaxSec, config_parse_sec, 0, offsetof(Manager, max_root_distance_usec)
Time.RootDistanceMaxSec, config_parse_sec, 0, offsetof(Manager, root_distance_max_usec)
Time.PollIntervalMinSec, config_parse_sec, 0, offsetof(Manager, poll_interval_min_usec)
Time.PollIntervalMaxSec, config_parse_sec, 0, offsetof(Manager, poll_interval_max_usec)
Time.ConnectionRetrySec, config_parse_sec, 0, offsetof(Manager, connection_retry_usec)

View File

@ -34,7 +34,7 @@
#define ADJ_SETOFFSET 0x0100 /* add 'time' to current time */
#endif
/* expected accuracy of time synchronization; used to adjust the poll interval */
/* Expected accuracy of time synchronization; used to adjust the poll interval */
#define NTP_ACCURACY_SEC 0.2
/*
@ -45,7 +45,7 @@
#define NTP_MAX_ADJUST 0.4
/* Default of maximum acceptable root distance in microseconds. */
#define NTP_MAX_ROOT_DISTANCE (5 * USEC_PER_SEC)
#define NTP_ROOT_DISTANCE_MAX_USEC (5 * USEC_PER_SEC)
/* Maximum number of missed replies before selecting another source. */
#define NTP_MAX_MISSED_REPLIES 2
@ -507,7 +507,7 @@ static int manager_receive_response(sd_event_source *source, int fd, uint32_t re
}
root_distance = ntp_ts_short_to_d(&ntpmsg.root_delay) / 2 + ntp_ts_short_to_d(&ntpmsg.root_dispersion);
if (root_distance > (double) m->max_root_distance_usec / (double) USEC_PER_SEC) {
if (root_distance > (double) m->root_distance_max_usec / (double) USEC_PER_SEC) {
log_info("Server has too large root distance. Disconnecting.");
return manager_connect(m);
}
@ -1081,7 +1081,7 @@ int manager_new(Manager **ret) {
if (!m)
return -ENOMEM;
m->max_root_distance_usec = NTP_MAX_ROOT_DISTANCE;
m->root_distance_max_usec = NTP_ROOT_DISTANCE_MAX_USEC;
m->poll_interval_min_usec = NTP_POLL_INTERVAL_MIN_USEC;
m->poll_interval_max_usec = NTP_POLL_INTERVAL_MAX_USEC;

View File

@ -79,7 +79,7 @@ struct Manager {
} samples[8];
unsigned samples_idx;
double samples_jitter;
usec_t max_root_distance_usec;
usec_t root_distance_max_usec;
/* last change */
bool jumped;