dasharo/systemd
0
0
Fork 0
mirror of https://github.com/Dasharo/systemd.git synced 2026-03-06 15:02:31 -08:00
Code Issues Packages Projects Releases Wiki Activity

man: fixes from online review

Browse Source 
Also includes the issues pointed out by @boucman.
This commit is contained in:
Daan De Meyer
2020-04-14 13:43:11 +02:00
committed by Zbigniew Jędrzejewski-Szmek
parent ae53ea5226
commit ca264f7d96
10 changed files with 349 additions and 353 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
man/org.freedesktop.locale1.xml
View File

@@ -72,24 +72,24 @@ node /org/freedesktop/locale1 {
<refsect2>
<title>Methods</title>
<para>If you set a new system locale all old system locale settings will be dropped, and the new
settings will be saved to disk. It will also be passed to the system manager, and subsequently started
<para>If you set a new system locale all old system locale settings will be dropped and the new
settings will be saved to disk. The locale will also be passed to the system manager, and subsequently started
daemons will inherit the new system locale. Note that already running daemons will not learn about the
new value.</para>
<para>The <function>SetVConsoleKeyboard()</function> call may be used to set the key mapping on the
<para>The <function>SetVConsoleKeyboard()</function> call may be used to set the key mapping for the
virtual console. Similarly, <function>SetX11Keyboard()</function> may be used to set the default key
mapping of the X11 servers.</para>
mapping of any X11 servers.</para>
<para>Note that <function>SetVConsoleKeyboard()</function> instantly applies the new keymapping to the
<para>Note that <function>SetVConsoleKeyboard()</function> instantly applies the new key mapping to the
console, while <function>SetX11Keyboard()</function> simply sets a default that may be used by later
sessions.</para>
<para>The boolean argument <varname>convert</varname> may be set to optionally convert the console
keyboard configuration to X11 keyboard mappings and vice versa. If true and
<function>SetVConsoleKeyboard()</function> is used the nearest X11 keyboard setting for the chosen
<function>SetVConsoleKeyboard()</function> is used, the nearest X11 keyboard setting for the chosen
console setting is set. If true and <function>SetX11Keyboard()</function> is used, the nearest console
keyboard setting for the chosen X11 setting is set. Usually it is hence sufficient to call one of the
keyboard setting for the chosen X11 setting is set. Hence, it is usually sufficient to call only one of the
two functions.</para>
<para>For graphical UIs that need to set the system keyboard mapping simply invoke
@@ -99,7 +99,7 @@ node /org/freedesktop/locale1 {
<para>Use the empty string for the keymap parameters you wish not to set.</para>
<para>The <varname>interactive</varname> boolean parameters can be used to control whether PolicyKit
should interactively ask the user for authentication credentials if it needs to.</para>
should interactively ask the user for authentication credentials if required.</para>
</refsect2>
<refsect2>
@@ -124,7 +124,7 @@ node /org/freedesktop/locale1 {
<varname>X11Options</varname> properties show values configurable with
<function>SetX11Keyboard()</function> described above (or <function>SetVConsoleKeyboard()</function>
with <varname>convert=true</varname>). The <varname>VConsoleKeymap</varname> and
<varname>VConsoleKeymapToggle</varname> propries sohw values configurable with
<varname>VConsoleKeymapToggle</varname> properties show values configurable with
<function>SetVConsoleKeyboard()</function> (or <function>SetX11Keyboard()</function> with
<varname>convert=true</varname>).</para>
</refsect2>

228
man/org.freedesktop.login1.xml
View File

File diff suppressed because it is too large Load Diff

124
man/org.freedesktop.machine1.xml
View File

@@ -177,27 +177,27 @@ node /org/freedesktop/machine1 {
<title>Methods</title>
<para><function>GetMachine()</function> may be used to get the machine object path for the machine with
the specified name. Similarly, <function>GetMachineByPID()</function> get the machine object the
the specified name. Similarly, <function>GetMachineByPID()</function> gets the machine object the
specified PID belongs to if there is any.</para>
<para><function>GetImage()</function> may be used to the the image object path for the image with the
<para><function>GetImage()</function> may be used to get the image object path of the image with the
specified name.</para>
<para><function>ListMachines()</function> returns an array with all currently registered machines. The
<para><function>ListMachines()</function> returns an array of all currently registered machines. The
structures in the array consist of the following fields: machine name, machine class, an identifier for
the service that registered the machine and the machine object path.</para>
<para><function>ListImages()</function> returns an array with all currently known images. The
<para><function>ListImages()</function> returns an array of all currently known images. The
structures in the array consist of the following fields: image name, type, read-only flag, creation
time, modification time, current disk space, image object path.</para>
time, modification time, current disk space, and image object path.</para>
<para><function>CreateMachine()</function> may be used to register a new virtual machine or container
with <command>systemd-machined</command>, creating a scope unit for it. This takes as arguments: a
machine name chosen by the registrar, an optional UUID as 32 byte array, a string that identifies the
with <command>systemd-machined</command>, creating a scope unit for it. It accepts the following arguments: a
machine name chosen by the registrar, an optional UUID as a 32 byte array, a string that identifies the
service that registers the machine, a class string, the PID of the leader process of the machine, an
optional root directory of the container, and an array of additional properties to use for the scope
registration. The virtual machine name must be suitable as hostname, and hence should follow the usual
DNS hostname rules, as well as Linux hostname restrictions. Specifically: only 7 Bit ASCII is
registration. The virtual machine name must be suitable as a hostname, and hence should follow the usual
DNS hostname rules, as well as the Linux hostname restrictions. Specifically, only 7 bit ASCII is
permitted, a maximum length of 64 characters is enforced, only characters from the set
<literal>a-zA-Z0-9-_.</literal> are allowed, the name may not begin with a dot, and it may not contain
two dots immediately following each other. Container and VM managers should ideally use the hostname
@@ -206,51 +206,51 @@ node /org/freedesktop/machine1 {
<citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>. If
a container manager needs to embed characters outside of the indicated range, escaping is required,
possibly using <literal>_</literal> as the escape character. Another (somewhat natural) option would be
to utilize Internet IDNA encoding. The UUID is passed as 32 byte array, or if no suitable UUID is
available an empty array (zero length) or zeroed out array shall be passed. The UUID should identify
the virtual machine/container uniquely, and should ideally be the same one as
to utilize Internet IDNA encoding. The UUID is passed as a 32 byte array or, if no suitable UUID is
available, an empty array (zero length) or zeroed out array shall be passed. The UUID should identify
the virtual machine/container uniquely and should ideally be the same UUID that
<filename>/etc/machine-id</filename> in the VM/container is initialized from. The service string can be
free-form, but it is recommended to pass a short lowercase identifier like
<literal>systemd-nspawn</literal>, <literal>libvirt-lxc</literal> or similar. The class string should
be either <literal>container</literal> or <literal>vm</literal> indicating whether the machine to
register is of the respective class. The leader PID should be the host PID of the init process of the
container, or the encapsulating process of the VM. If the root directory of the container is known and
available in the host's hierarchy, it should be passed, otherwise use the empty string. Finally, the
container or the encapsulating process of the VM. If the root directory of the container is known and
available in the host's hierarchy, it should be passed. Otherwise, pass the empty string instead. Finally, the
scope properties are passed as array in the same way as to PID1's
<function>StartTransientUnit()</function>. This method call will internally register a transient scope
unit for the calling client (utilizing the passed scope_properties), and move the leader PID into
it. The call returns an object path for the registered machine object, implementing the
<function>StartTransientUnit()</function> method. Calling this method will internally register a transient scope
unit for the calling client (utilizing the passed scope_properties) and move the leader PID into
it. The call returns an object path for the registered machine object that implements the
<interfacename>org.freedesktop.machine1.Machine</interfacename> interface (see below). Also see the
<ulink url="https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New Control Group
Interfaces</ulink> for details about scope units, and how to alter resource control settings on the
Interfaces</ulink> for details about scope units and how to alter resource control settings on the
created machine at runtime.</para>
<para><function>RegisterMachine()</function> is similar to <function>CreateMachine()</function>,
however only registers a machine, but does not create a scope unit for it. The caller's unit will be
registered instead. This call is only recommended to be used for container or VM managers that are run
<para><function>RegisterMachine()</function> is similar to <function>CreateMachine()</function>.
However, it only registers a machine and does not create a scope unit for it. Instead, the caller's unit is
registered. We recommend to only use this method for container or VM managers that are run
multiple times, one instance for each container/VM they manage, and are invoked as system
services.</para>
<para><function>CreateMachineWithNetwork()</function> and
<function>RegisterMachineWithNetwork()</function> are similar to <function>CreateMachine()</function>
and <function>RegisterMachine()</function> but take an extra argument: an array of network interface
indexes that point towards the virtual machine or container. The interface indexes should reference one
or more network interfaces on the host that can be used to communicate with the guest. Commonly the
passed interface index refers to the host side of a "veth" link (in case of containers), or a
"tun"/"tap" link (in case of VMs) or the host side of a bridge interface that bridges access to the
indices that point towards the virtual machine or container. The interface indices should reference one
or more network interfaces on the host that can be used to communicate with the guest. Commonly, the
passed interface index refers to the host side of a "veth" link (in case of containers), a
"tun"/"tap" link (in case of VMs), or the host side of a bridge interface that bridges access to the
VM/container interfaces. Specifying this information is useful to enable support for link-local IPv6
communication to the machines, since the scope field of sockaddr_in6 can be initialized by the
communication to the machines since the scope field of sockaddr_in6 can be initialized by the
specified ifindex.
<citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>
makes use of this information.</para>
<para><function>KillMachine()</function> sends a UNIX signal to the machine's processes. It takes a
<para><function>KillMachine()</function> sends a UNIX signal to the machine's processes. As its arguments, it takes a
machine name (as originally passed to <function>CreateMachine()</function> or returned by
<function>ListMachines()</function>). An identifier what precisely to send the signal to being either
<literal>leader</literal> or <literal>all</literal>, plus a numeric UNIX signal integer.</para>
<function>ListMachines()</function>), an identifier that specifies what precisely to send the signal to (either
<literal>leader</literal> or <literal>all</literal>), and a numeric UNIX signal integer.</para>
<para><function>TerminateMachine()</function> terminates a virtual machine, killing its processes. It
takes a machine name as argument.</para>
takes a machine name as its only argument.</para>
<para><function>GetMachineAddresses()</function> retrieves the IP addresses of a container. This call
returns an array of pairs consisting of an address family specifier (<constant>AF_INET</constant> or
@@ -258,41 +258,41 @@ node /org/freedesktop/machine1 {
containers that make use of network namespacing.</para>
<para><function>GetMachineOSRelease()</function> retrieves the OS release information of a
container. This call returns an array of key value pairs read from the
container. This method returns an array of key value pairs read from the
<citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file in
the container, and is useful to identify the operating system used in a container.</para>
the container and is useful to identify the operating system used in a container.</para>
<para><function>OpenMachinePTY()</function> allocates a pseudo TTY in the container and returns a file
descriptor and its path. This is equivalent to transitioning into the container and invoking
<citerefentry><refentrytitle>posix_openpt</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
<para><function>OpenMachineLogin()</function> allocates a pseudo TTY in the container and ensures that
a getty loging prompt of the container is running on the other end. It returns the file descriptor of
the PTY plus the PTY path. This is useful for acquiring a pty with a login prompt from the
a getty login prompt of the container is running on the other end. It returns the file descriptor of
the PTY and the PTY path. This is useful for acquiring a pty with a login prompt from the
container.</para>
<para><function>OpenMachineShell()</function> allocates a pseudo TTY in the container, as the specified
user, and invokes an executable of the specified path, with a list of arguments (starting from
argv[0]), and an environment block. It then returns the file descriptor of the PTY plus the PTY
user, and invokes the executable at the specified path with a list of arguments (starting from
argv[0]) and an environment block. It then returns the file descriptor of the PTY and the PTY
path.</para>
<para><function>BindMountMachine()</function> bind mounts a file or directory from the host into the
container. Takes a machine name, the source directory on the host, and the destination directory in the
container as argument. Also takes two booleans, one indicating whether the bind mount shall be
container. Its arguments consist of a machine name, the source directory on the host, the destination directory in the
container, and two booleans, one indicating whether the bind mount shall be
read-only, the other indicating whether the destination mount point shall be created first, if it is
missing.</para>
<para><function>CopyFromMachine()</function> copies files or directories from a container into the
host. Takes a container name, a source directory in the container and a destination directory on the
host as argument. <function>CopyToMachine()</function> does the opposite and copies files from a source
host. It takes a container name, a source directory in the container and a destination directory on the
host as arguments. <function>CopyToMachine()</function> does the opposite and copies files from a source
directory on the host into a destination directory in the container.</para>
<para><function>RemoveImage()</function> removes the image by the specified name.</para>
<para><function>RemoveImage()</function> removes the image with the specified name.</para>
<para><function>RenameImage()</function> renames the specified image to a new name.</para>
<para><function>RenameImage()</function> renames the specified image.</para>
<para><function>CloneImage()</function> clones the specified image under a new name. Also takes a
boolean argument indicating whether the resuling image shall be read-only or not.</para>
<para><function>CloneImage()</function> clones the specified image under a new name. It also takes a
boolean argument indicating whether the resulting image shall be read-only or not.</para>
<para><function>MarkImageReadOnly()</function> toggles the read-only flag of an image.</para>
@@ -301,15 +301,15 @@ node /org/freedesktop/machine1 {
<para><function>SetImageLimit()</function> sets a per-image quota limit.</para>
<para><function>MapFromMachineUser()</function>, <function>MapToMachineUser()</function>,
<function>MapFromMachineGroup()</function>, <function>MapToMachineGroup()</function> may be used to map
UIDs/GIDs from the host user namespace to a container namespace or back.</para>
<function>MapFromMachineGroup()</function>, and <function>MapToMachineGroup()</function> may be used to map
UIDs/GIDs from the host user namespace to a container user namespace or vice versa.</para>
</refsect2>
<refsect2>
<title>Signals</title>
<para><function>MachineNew</function> and <function>MachineRemoved</function> are sent whenever a new
machine is registered or removed. These signals carry the machine name plus the object path to the
machine is registered or removed. These signals carry the machine name and the object path to the corresponding
<interfacename>org.freedesktop.machine1.Machine</interfacename> interface (see below).</para>
</refsect2>
@@ -393,47 +393,47 @@ node /org/freedesktop/machine1/machine/rawhide {
<refsect2>
<title>Methods</title>
<para><function>Terminate()</function> and <function>Kill()</function> terminate/kill the machine, and
<para><function>Terminate()</function> and <function>Kill()</function> terminate/kill the machine. These methods
take the same arguments as <function>TerminateMachine()</function> and
<function>KillMachine()</function> on the Manager interface.</para>
<function>KillMachine()</function> on the Manager interface, respectively.</para>
<para><function>GetAddresses()</function> and <function>GetOSRelease()</function> get IP address and OS
release information from the machine, and take the same arguments as
<para><function>GetAddresses()</function> and <function>GetOSRelease()</function> get the IP address and OS
release information from the machine. These methods take the same arguments as
<function>GetMachineAddresses()</function> and <function>GetMachineOSRelease()</function> of the
Manager interface, described above.</para>
Manager interface, respectively.</para>
</refsect2>
<refsect2>
<title>Properties</title>
<para><varname>Name</varname> is the machine name, as it was passed in during registration with
<para><varname>Name</varname> is the machine name as it was passed in during registration with
<function>CreateMachine()</function> on the manager object.</para>
<para><varname>Id</varname> is the machine UUID.</para>
<para><varname>Timestamp</varname> and <varname>TimestampMonotonic</varname> are the realtime and
monotonic timestamps when the virtual machines where created.</para>
monotonic timestamps when the virtual machines where created in microseconds since the epoch.</para>
<para><varname>Service</varname> contains a short string identifying the registering service, as passed
<para><varname>Service</varname> contains a short string identifying the registering service as passed
in during registration of the machine.</para>
<para><varname>Unit</varname> is the systemd scope or service unit name for the machine.</para>
<para><varname>Leader</varname> is the PID of the leader process of the machine.</para>
<para><varname>Class</varname> is the class of the machine and either the string "vm" (for real VMs
<para><varname>Class</varname> is the class of the machine and is either the string "vm" (for real VMs
based on virtualized hardware) or "container" (for light-weight userspace virtualization sharing the
same kernel as the host).</para>
<para><varname>RootDirectory</varname> is the root directory of the container if that is known and
applicable, or the empty string.</para>
<para><varname>RootDirectory</varname> is the root directory of the container if it is known and
applicable or the empty string.</para>
<para><varname>NetworkInterfaces</varname> contains an array of network interface indexes that point
towards the container or VM or the host. For details about this information see the description of
<para><varname>NetworkInterfaces</varname> contains an array of network interface indices that point
towards the container, the VM or the host. For details about this information see the description of
<function>CreateMachineWithNetwork()</function> above.</para>
<para><varname>State</varname> is the state of the machine, and one of <literal>opening</literal>,
<literal>running</literal>, <literal>closing</literal>. Note that the state machine is not considered
<para><varname>State</varname> is the state of the machine and is one of <literal>opening</literal>,
<literal>running</literal>, or <literal>closing</literal>. Note that the state machine is not considered
part of the API and states might be removed or added without this being considered API breakage.
</para>
</refsect2>

211
man/org.freedesktop.resolve1.xml
View File

@@ -29,14 +29,13 @@
<para>
<citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
is a system service that provides host name resolution and caching using DNS, LLMNR, and mDNS. It also
is a system service that provides hostname resolution and caching using DNS, LLMNR, and mDNS. It also
does DNSSEC validation. This page describes the resolve semantics and the D-Bus interface.</para>
<para>This page contains an API reference only. If you are looking for a longer explanation how to use
this API, please consult
<ulink url="https://wiki.freedesktop.org/www/Software/systemd/writing-network-configuration-managers">
Writing Network Configuration Managers</ulink>
and
Writing Network Configuration Managers</ulink> and
<ulink url="https://wiki.freedesktop.org/www/Software/systemd/writing-resolver-clients">Writing Resolver
Clients</ulink>.
</para>
@@ -184,37 +183,35 @@ node /org/freedesktop/resolve1 {
<refsect2>
<title>Methods</title>
<para><function>ResolveHostname()</function> takes a hostname and acquires one or more IP addresses for
it. As parameters it takes the Linux network interface index to execute the query on, or 0 if it may be
<para><function>ResolveHostname()</function> takes a hostname and resolves it to one or more IP addresses.
As parameters it takes the Linux network interface index to execute the query on, or 0 if it may be
done on any suitable interface. The <varname>name</varname> parameter specifies the hostname to
resolve. Note that IDNA conversion is applied to this name when necessary, and when it is resolved via
Unicast DNS, but not for resolution via LLMNR or MulticastDNS. The <varname>family</varname> parameter
specifies the address family of the IP address to retrieve. It may be <constant>AF_INET</constant>,
<constant>AF_INET6</constant> or <constant>AF_UNSPEC</constant>, to request addresses of a specific
family. If <constant>AF_UNSPEC</constant> is specified (recommended), both kinds are retrieved, subject
resolve. Note that if required, IDNA conversion is applied to this name unless it is resolved via LLMNR or MulticastDNS. The <varname>family</varname> parameter
limits the results to a specific address family. It may be <constant>AF_INET</constant>,
<constant>AF_INET6</constant> or <constant>AF_UNSPEC</constant>. If <constant>AF_UNSPEC</constant> is specified (recommended), both kinds are retrieved, subject
to local network configuration (i.e. if no local, routable IPv6 address is found, no IPv6 address is
retrieved; and similarly for IPv4). A 64-bit <varname>flags</varname> field may be used to alter
retrieved; and similarly for IPv4). A 64-bit <varname>flags</varname> field may be used to alter the
behaviour of the resolver operation (see below). The method returns an array of address records. Each
address record consists of an interface index the address belongs to, an address family as well as a
address record consists of the interface index the address belongs to, an address family as well as a
byte array with the actual IP address data (which either has 4 or 16 elements, depending on the address
family). The returned address family will be one of <constant>AF_INET</constant> or
<constant>AF_INET6</constant>. For IPv6, the returned address interface index should be used to
initialize the .sin6_scope_id field of a <structname>struct sockaddr_in6</structname>, to permit
initialize the .sin6_scope_id field of a <structname>struct sockaddr_in6</structname> instance to permit
support for resolution to link-local IP addresses. The address array is followed by the canonical name
of the host, which may or may not be identical to the name looked up. Finally, a 64-bit
<varname>flags</varname> field is returned, that is defined similarly to the <varname>flags</varname>
of the host, which may or may not be identical to the resolved hostname. Finally, a 64-bit
<varname>flags</varname> field is returned that is defined similarly to the <varname>flags</varname>
field that was passed in, but contains information about the resolved data (see below). If the hostname
passed in is an IPv4 or IPv6 address formatted as string, it is parsed, and the result returned. In
this case no network communication is done.</para>
passed in is an IPv4 or IPv6 address formatted as string, it is parsed, and the result is returned. In
this case, no network communication is done.</para>
<para><function>ResolveAddress()</function> executes the reverse operation: it takes an IP address and
acquires one or more hostnames for it. As parameters it takes the interface index to execute the query
on, or <constant>0</constant> if all suitable interfaces are OK. The <varname>family</varname>
parameter indicates the address family of the IP address to resolve, it may be either
parameter indicates the address family of the IP address to resolve. It may be either
<constant>AF_INET</constant> or <constant>AF_INET6</constant>. The <varname>address</varname> parameter
takes the raw IP address data (as either 4 or 16 byte array). The <varname>flags</varname> input
parameter may be used to alter the resolver operation (see below). The call returns an array of name
records, consisting of an interface index plus the name each. The <varname>flags</varname> output
takes the raw IP address data (as either a 4 or 16 byte array). The <varname>flags</varname> input
parameter may be used to alter the resolver operation (see below). The method returns an array of name
records, each consisting of an interface index and a hostname. The <varname>flags</varname> output
field contains additional information about the resolver operation (see below).</para>
<para><function>ResolveRecord()</function> takes a DNS resource record (RR) type, class and name, and
@@ -223,7 +220,7 @@ node /org/freedesktop/resolve1 {
any suitable interface. The <varname>name</varname> parameter specifies the RR domain name to look up
(no IDNA conversion is applied), followed by the 16-bit class and type fields (which may be
ANY). Finally, a <varname>flags</varname> field may be passed in to alter behaviour of the look-up (see
below). On return an array of RR items is returned. Each array entry consists of the network interface
below). On completion, an array of RR items is returned. Each array entry consists of the network interface
index the RR was discovered on, the type and class field of the RR found, and a byte array of the raw
RR discovered. The raw RR data starts with the RR's domain name, in the original casing, followed
by the RR type, class, TTL and RDATA, in the binary format documented in
@@ -231,91 +228,91 @@ node /org/freedesktop/resolve1 {
compression in the payload (such as MX or PTR), the compression is expanded in the returned
data.</para>
<para>Note that the class field has to be specified as IN or ANY currently, and specifying a different
<para>Note that currently, the class field has to be specified as IN or ANY. Specifying a different
class will return an error indicating that look-ups of this kind are unsupported. Similarly, some
special types are not supported either (AXFR, OPT, …). While <filename>systmed-resolved</filename> parses and validates resource
record of many types, it is crucial that clients using this API understand that the RR data originates
special types are not supported either (AXFR, OPT, …). While <filename>systemd-resolved</filename> parses and validates resource
records of many types, it is crucial that clients using this API understand that the RR data originates
from the network and should be thoroughly validated before use.</para>
<para><function>ResolveService()</function> may be used to resolve a DNS SRV service record, as the
<para><function>ResolveService()</function> may be used to resolve a DNS SRV service record, as well as the
hostnames referenced in it, and possibly an accompanying DNS-SD TXT record containing additional
service metadata. The primary benefit of using this call over <function>ResolveRecord()</function>
service metadata. The primary benefit of using this method over <function>ResolveRecord()</function>
specifying the SRV type is that it will resolve the SRV and TXT RRs as well as the hostnames referenced
in the SRV in a single operation. As parameters it takes a Linux network interface index, a service
name, a service type and a service domain. The call may be invoked in three different modes:</para>
name, a service type and a service domain. This method may be invoked in three different modes:</para>
<orderedlist>
<listitem><para>To resolve a DNS-SD service, specify the service name (e.g. <literal>Lennart's
Files</literal>), the service type (e.g. <literal>_webdav._tcp</literal>) and the domain to search in
(e.g. <literal>local</literal>) in the three service parameters. The service name must be in UTF-8
(e.g. <literal>local</literal>) as the three service parameters. The service name must be in UTF-8
format, and no IDNA conversion is applied to it in this mode (as mandated by the DNS-SD
specifications). However, if necessary IDNA conversion is applied to the domain parameter.</para>
specifications). However, if necessary, IDNA conversion is applied to the domain parameter.</para>
</listitem>
<listitem><para>To resolve a plain SRV record, set the service name parameter to the empty string,
<listitem><para>To resolve a plain SRV record, set the service name parameter to the empty string
and set the service type and domain properly. (IDNA conversion is applied to the domain, if
necessary.)</para></listitem>
<listitem><para>Alternatively, leave both the service name and type empty, and specify the full
<listitem><para>Alternatively, leave both the service name and type empty and specify the full
domain name of the SRV record (i.e. prefixed with the service type) in the domain parameter. (No IDNA
coversion is applied in this mode.)</para></listitem>
</orderedlist>
<para>The <varname>family</varname> parameter of the <function>ResolveService()</function> call encodes
<para>The <varname>family</varname> parameter of the <function>ResolveService()</function> method encodes
the desired family of the addresses to resolve (use <constant>AF_INET</constant>,
<constant>AF_INET6</constant>, <constant>AF_UNSPEC</constant>), if this is enabled (Use the
<constant>AF_INET6</constant>, or <constant>AF_UNSPEC</constant>). If this is enabled (Use the
<constant>NO_ADDRESS</constant> flag to turn address resolution off, see below). The
<varname>flags</varname> parameter takes a couple of flags that may be used to alter the resolver
operation.</para>
<para>On return, <function>ResolveService()</function> returns an array of SRV record structures. Each
item consists of the priority, weight and port fields and the hostname to contact, as encoded in the SRV
record. Immediately following is an array with the addresses of this hostname, with each item consisting
<para>On completion, <function>ResolveService()</function> returns an array of SRV record structures. Each
items consisting of the priority, weight and port fields as well as the hostname to contact, as encoded in the SRV
record. Immediately following is an array of the addresses of this hostname, with each item consisting
of the interface index, the address family and the address data in a byte array. This address array is
followed with the canonicalized hostname. After this array of SRV record structures an array of byte
arrays follows, that encodes the TXT RR strings, in case DNS-SD look-ups are enabled. The next parameters
followed by the canonicalized hostname. After this array of SRV record structures an array of byte
arrays follows that encodes the TXT RR strings, in case DNS-SD look-ups are enabled. The next parameters
are the canonical service name, type and domain. This may or may not be identical to the parameters
passed in. Finally, a <varname>flags</varname> field is returned that contains information about the
resolver operation performed.</para>
<para>The <function>ResetStatistics()</function> method resets to zero the various statistics counters
<filename>systmed-resolved</filename> maintains. (For details, see the statistics properties below.)</para>
<para>The <function>ResetStatistics()</function> method resets the various statistics counters that
<filename>systemd-resolved</filename> maintains to zero. (For details, see the statistics properties below.)</para>
<para>The <function>GetLink()</function> method takes a network interface index and returns the object
path to the <interfacename>org.freedesktop.resolve1.Link</interfacename> object corresponding to it.
</para>
<para>The <function>SetLinkDNS()</function> method sets the DNS servers to use on a specific
interface. This call (and the following ones) may be used by network management software to configure
interface. This method (and the following ones) may be used by network management software to configure
per-interface DNS settings. It takes a network interface index as well as an array of DNS server IP
address records. Each array item consists of an address family (either <constant>AF_INET</constant> or
<constant>AF_INET6</constant>), followed by a 4-byte or 16-byte array with the raw address data. This
call is a one-call shortcut for retrieving the Link object for a network interface using
<function>GetLink()</function> (see above) and then invoking the <function>SetDNS()</function> call
method is a one-step shortcut for retrieving the Link object for a network interface using
<function>GetLink()</function> (see above) and then invoking the <function>SetDNS()</function> method
(see below) on it.
</para>
<para>Network management software integrating with <filename>systmed-resolved</filename> is recommended
to invoke this method (and the five below) after the interface appeared in the kernel (and thus after a
network interface index has been assigned), but before the network interfaces is activated (set
<constant>IFF_UP</constant> on) so that all settings take effect during the full time the network
interface is up. It is safe to alter settings while the interface is up, however. Use the
<para>Network management software integrating with <filename>systemd-resolved</filename> should
call this method (and the five below) after the interface appeared in the kernel (and thus after a
network interface index has been assigned), but before the network interfaces is activated
(<constant>IFF_UP</constant> set) so that all settings take effect during the full time the network
interface is up. It is safe to alter settings while the interface is up, however. Use
<function>RevertLink()</function> (described below) to reset all per-interface settings.</para>
<para>The <function>SetLinkDomains()</function> method sets the search and routing domains to use on a
specific network interface for DNS look-ups. It take a network interface index plus an array of domains,
each with a boolean parameter indicating whether the specified domain shall be used as search domain
(false), or just as routing domain (true). Search domains are used for qualifying single-label names into
specific network interface for DNS look-ups. It takes a network interface index and an array of domains,
each with a boolean parameter indicating whether the specified domain shall be used as a search domain
(false), or just as a routing domain (true). Search domains are used for qualifying single-label names into
FQDN when looking up hostnames, as well as for making routing decisions on which interface to send
queries ending in the domain to. Routing domains are not used for single-label name qualification, and
are only used for routing decisions. Pass the search domains in the order they shall be used.</para>
queries ending in the domain to. Routing domains are only used for routing decisions and not used for single-label
name qualification. Pass the search domains in the order they should be used.</para>
<para>The <function>SetLinkLLMNR()</function> method enables or disables LLMNR support on a specific
network interface. It takes a network interface index as well as a string that either may be empty,
network interface. It takes a network interface index as well as a string that may either be empty or one of
<literal>yes</literal>, <literal>no</literal> or <literal>resolve</literal>. If empty, the systemd-wide
default LLMNR setting is used. If <literal>yes</literal> LLMNR is used for resolution of single-label
names, and the local hostname is registered on all local LANs for LLMNR resolution by peers. If
<literal>no</literal> LLMNR is turned off fully on this interface. If <literal>resolve</literal> LLMNR
default LLMNR setting is used. If <literal>yes</literal>, LLMNR is used for resolution of single-label
names and the local hostname is registered on all local LANs for LLMNR resolution by peers. If
<literal>no</literal>, LLMNR is turned off fully on this interface. If <literal>resolve</literal>, LLMNR
is only enabled for resolving names, but the local host name is not registered for other peers to
use.</para>
@@ -324,26 +321,26 @@ node /org/freedesktop/resolve1 {
described above.</para>
<para>The <function>SetLinkDNSSEC()</function> method enables or disables DNSSEC validation on a
specific network interface. It takes a network interface index as well as a string that either may be
empty, <literal>yes</literal>, <literal>no</literal> or <literal>allow-downgrade</literal>. If empty,
the system-wide default DNSSEC setting is used. If <literal>yes</literal> full DNSSEC validation is
done for all look-ups. If the selected DNS server does not support DNSSEC, look-ups will fail if this
mode is used. If <literal>no</literal> DNSSEC validation is fully disabled. If
<literal>allow-downgrade</literal> DNSSEC validation is enabled, but is turned off automatically if the
specific network interface. It takes a network interface index as well as a string that may either be
empty or one of <literal>yes</literal>, <literal>no</literal>, or <literal>allow-downgrade</literal>. When
empty, the system-wide default DNSSEC setting is used. If <literal>yes</literal>, full DNSSEC validation
is done for all look-ups. If the selected DNS server does not support DNSSEC, look-ups will fail if this
mode is used. If <literal>no</literal>, DNSSEC validation is fully disabled. If
<literal>allow-downgrade</literal>, DNSSEC validation is enabled, but is turned off automatically if the
selected server does not support it (thus opening up behaviour to downgrade attacks). Note that DNSSEC
only applies to traditional DNS, not to LLMNR or MulticastDNS.</para>
<para>The <function>SetLinkDNSSECNegativeTrustAnchors()</function> method may be used to configure DNSSEC
Negative Trust Anchors (NTAs) for a specific network interface. It takes a network interface index and a
list of domains as parameters.</para>
list of domains as arguments.</para>
<para>The <function>RevertLink()</function> method may be used to revert all per-link settings done with
the six calls described above to the defaults again.</para>
the six methods described above to the defaults again.</para>
<refsect3>
<title>The Flags Parameter</title>
<para>The four calls above accept and return a 64-bit flags value. In most cases passing 0 is sufficient
<para>The four methods above accept and return a 64-bit flags value. In most cases passing 0 is sufficient
and recommended. However, the following flags are defined to alter the look-up:</para>
<programlisting>
@@ -363,33 +360,33 @@ node /org/freedesktop/resolve1 {
classic unicast DNS, LLMNR via IPv4/UDP and IPv6/UDP respectively, as well as MulticastDNS via
IPv4/UDP and IPv6/UDP. If all of these five bits are off on input (which is strongly recommended) the
look-up will be done via all suitable protocols for the specific look-up. Note that these flags
operate as filter only, but cannot force a look-up to be done via a protocol. Specifically, <filename>systmed-resolved</filename>
operate as filter only, but cannot force a look-up to be done via a protocol. Specifically, <filename>systemd-resolved</filename>
will only route look-ups within the .local TLD to MulticastDNS (plus some reverse look-up address
domains), and single-label names to LLMNR (plus some reverse address lookup domains). It will route
neither of these to Unicast DNS servers. Also, it will do LLMNR and Multicast DNS only on interfaces
suitable for multicasting.</para>
suitable for multicast.</para>
<para>On output these five flags indicate which protocol was used to execute the operation, and hence
<para>On output, these five flags indicate which protocol was used to execute the operation, and hence
where the data was found.</para>
<para>The primary use case for these five flags are follow-up look-ups based on DNS data retrieved
<para>The primary use cases for these five flags are follow-up look-ups based on DNS data retrieved
earlier. In this case it is often a good idea to limit the follow-up look-up to the protocol that was
used to discover the first DNS data look-up.</para>
used to discover the first DNS result.</para>
<para>The NO_CNAME flag controls whether CNAME/DNAME resource records shall be followed during the
look-up. This flag is only available at input, none of the functions will return it on output. If a
CNAME/DNAME RR is discovered while resolving a hostname an error is returned instead. By default,
CNAME/DNAME RR is discovered while resolving a hostname, an error is returned instead. By default,
when the flag is off, CNAME/DNAME RRs are followed.</para>
<para>The NO_TXT and NO_ADDRESS flags influence operation of the
<function>ResolveService()</function> call only. They are only defined for input, not output. If
NO_TXT set, the DNS-SD TXT RR look-up is not done in the same operation. If NO_ADDRESS is specified
<para>The NO_TXT and NO_ADDRESS flags only influence operation of the
<function>ResolveService()</function> method. They are only defined for input, not output. If
NO_TXT set, the DNS-SD TXT RR look-up is not done in the same operation. If NO_ADDRESS is specified,
the hostnames discovered are not implicitly translated to their addresses.</para>
<para>The NO_SEARCH flag turns off the search domain logic. It is only defined for input in
<function>ResolveHostname()</function>. When specified, single-label hostnames are not qualified
using defined search domains, if any are configured. Note that <function>ResolveRecord()</function>
will not qualify single-label domain names using search domains in any case. Also note that
will never qualify single-label domain names using search domains. Also note that
multi-label hostnames are never subject to search list expansion.</para>
<para>The AUTHENTICATED bit is defined only in the output flags of the four functions. If set, the
@@ -398,7 +395,7 @@ node /org/freedesktop/resolve1 {
synthesized data, such as <literal>localhost</literal> or data from
<filename>/etc/hosts</filename>. Moreover, it is set for all LLMNR or mDNS RRs which originate from the
local host. Applications that require authenticated RR data for operation should check this flag before
trusting the data. Not that <filename>systmed-resolved</filename> will not return invalidated data in any case, hence this flag
trusting the data. Note that <filename>systemd-resolved</filename> will never return invalidated data, hence this flag
simply allows to discern the cases where data is known to be trustable, or where there is proof that
the data is "rightfully" unauthenticated (which includes cases where the underlying protocol or server
does not support authenticating data).</para>
@@ -414,8 +411,8 @@ node /org/freedesktop/resolve1 {
<citerefentry project="man-pages"><refentrytitle>gethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
but may differ if a conflict is detected on the network.
<para><varname>DNS</varname> contains an array containing all DNS servers currently used by
<filename>systmed-resolved</filename>. It contains similar information as the DNS server data written to
<para><varname>DNS</varname> contains an array of all DNS servers currently used by
<filename>systemd-resolved</filename>. It contains similar information as the DNS server data written to
/run/systemd/resolve/resolv.conf. Each structure in the array consists of a numeric network interface
index, an address family, and a byte array containing the DNS server address (either 4 bytes in length
for IPv4 or 16 bytes in lengths for IPv6). The array contains DNS servers configured system-wide,
@@ -424,26 +421,26 @@ node /org/freedesktop/resolve1 {
per-interface DNS server information either retrieved from
<citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
or configured by external software via <function>SetLinkDNS()</function> (see above). The network
interface index will be 0 for the system-wide configured services, and non-zero for the per-link
interface index will be 0 for the system-wide configured services and non-zero for the per-link
servers.</para>
<para>Similarly, the <varname>Domains</varname> property contains an array containing all search and
routing domains currently used by <filename>systmed-resolved</filename>. Each entry consists of a network interface index (again, 0
<para>Similarly, the <varname>Domains</varname> property contains an array of all search and
routing domains currently used by <filename>systemd-resolved</filename>. Each entry consists of a network interface index (again, 0
encodes system-wide entries), the actual domain name, and whether the entry is used only for routing
(true), or for both routing and searching (false).</para>
(true) or for both routing and searching (false).</para>
<para>The <varname>TransactionStatistics</varname> property contains information about the number of
transactions <filename>systmed-resolved</filename> has been processing. It contains a pair of unsigned 64-bit counters, the first
transactions <filename>systemd-resolved</filename> has processed. It contains a pair of unsigned 64-bit counters, the first
containing the number of currently ongoing transactions, the second the number of total transactions
<filename>systmed-resolved</filename> is processing or has processed. The latter value may be reset using the
<function>ResetStatistics()</function> call described above. Note that the number of transaction does
not directly map to the number of resolver bus calls issued. While simple look-ups usually require a
<filename>systemd-resolved</filename> is processing or has processed. The latter value may be reset using the
<function>ResetStatistics()</function> method described above. Note that the number of transactions does
not directly map to the number of issued resolver bus method calls. While simple look-ups usually require a
single transaction only, more complex look-ups might result in more, for example when CNAMEs or DNSSEC
are in use.</para>
<para>The <varname>CacheStatistics</varname> property contains information about the executed cache
operations so far. It exposes three 64-bit counters: the first being the total number of current cache
entries (both positive and negative), the second number of cache hits, and the third the number of
entries (both positive and negative), the second the number of cache hits, and the third the number of
cache misses. The latter counters may be reset using <function>ResetStatistics()</function> (see
above). </para>
@@ -453,15 +450,15 @@ node /org/freedesktop/resolve1 {
each non-existance proof. The secure counter is increased for each operation that successfully verified
a signed reply, the insecure counter is increased for each operation that successfully verified that an
unsigned reply is rightfully unsigned. The bogus counter is increased for each operation where the
validation did not check out, and the data is likely to have been tempered with. Finally the
validation did not check out and the data is likely to have been tempered with. Finally the
indeterminate counter is increased for each operation which did not complete because the necessary keys
could not be acquired or the cryptographic algorithms were unknown.</para>
<para>The <varname>DNSSECSupported</varname> boolean property reports whether DNSSEC is enabled and
the selected DNS servers support it. It combines information about system-wide and per-link DNS
settings (see below), and only reports true if DNSSEC is enabled and supported on every interface for
which DNS is configured and for the system-wide settings if there are any. Note that <filename>systmed-resolved</filename> assumes
DNSSEC is supported by DNS servers until it verified that this is not the case. Thus, the reported
which DNS is configured and for the system-wide settings if there are any. Note that <filename>systemd-resolved</filename> assumes
DNSSEC is supported by DNS servers until it verifies that this is not the case. Thus, the reported
value may initially be true, until the first transactions are executed.</para>
</refsect2>
</refsect1>
@@ -546,7 +543,7 @@ node /org/freedesktop/resolve1/link/_34 {
<!--property DNSSECNegativeTrustAnchors is not documented!-->
<para>For each Linux network interface a "Link" object is created, which exposes per-link DNS
<para>For each Linux network interface a "Link" object is created which exposes per-link DNS
configuration and state. Use <function>GetLink()</function> on the Manager interface to retrieve the
object path for a link object given the network interface index (see above).</para>
@@ -556,32 +553,32 @@ node /org/freedesktop/resolve1/link/_34 {
<para>The various methods exposed by the Link interface are equivalent to their similarly named
counterparts on the Manager interface. e.g. <function>SetDNS()</function> on the Link object maps to
<function>SetLinkDNS()</function> on the Manager object, the main difference being that the later
expects an interface index to be speicified. Invoking the calls on the Manager interface has the
expects an interface index to be specified. Invoking the methods on the Manager interface has the
benefit of reducing roundtrips, as it is not necessary to first request the Link object path via
<function>GetLink()</function> before invoking the methods. For further details on these calls see the
Manager documentation above. </para>
<function>GetLink()</function> before invoking the methods. For further details on these methods see
the <interfacename>Manager</interfacename> documentation above.</para>
</refsect2>
<refsect2>
<title>Properties</title>
<para><varname>ScopesMask</varname> defines which resolver scopes are currently active on this
interface. This 64-bit unsigned integer field is a bit mask, consisting of a subset of the bits as the
interface. This 64-bit unsigned integer field is a bit mask consisting of a subset of the bits of the
flags parameter describe above. Specifically, it may have the DNS, LLMNR and MDNS bits (the latter in
IPv4 and IPv6 flavours) set. Each individual bit is set when the protocol applies to a specific
interface and is enabled for it. It is unset otherwise. Specifically, a multicast-capable interface in
"UP" state with an IP address is suitable for LLMNR or MulticastDNS, and any interface that is UP and
the "UP" state with an IP address is suitable for LLMNR or MulticastDNS, and any interface that is UP and
has an IP address is suitable for DNS. Note the relationship of the bits exposed here with the LLMNR
and MulticastDNS properties also exposed on the Link interface. The latter expose what is *configured*
to be used on the interface, the former expose what is actually used on the interface, taking into
account the abilities of the interface.</para>
<para><varname>DNSSECSupported</varname> exposes a boolean field that indicates whether DNSSEC is
currently configured and in use on the interface. Note that if DNSSEC is enabled on an interface it is
currently configured and in use on the interface. Note that if DNSSEC is enabled on an interface, it is
assumed available until it is detected that the configured server does not actually support it. Thus,
this property may initially report that DNSSEC is supported on an interface.</para>
<para>The other properties reflect the state of the various configuration settings for the link, which
<para>The other properties reflect the state of the various configuration settings for the link which
may be set with the various methods calls such as SetDNS() or SetLLMNR().</para>
</refsect2>
</refsect1>
@@ -589,17 +586,17 @@ node /org/freedesktop/resolve1/link/_34 {
<refsect1>
<title>Common Errors</title>
<para>Many bus calls <filename>systmed-resolved</filename> exposes (in particular the resolver calls such
as <function>ResolveHostname()</function> on the <interfacename>Manager</interfacename> interface) return
<para>Many bus methods <filename>systemd-resolved</filename> exposes (in particular the resolver methods such
as <function>ResolveHostname()</function> on the <interfacename>Manager</interfacename> interface) may return
some of the following errors:</para>
<variablelist>
<varlistentry><term><constant>org.freedesktop.resolve1.NoNameServers</constant></term>
<listitem><para>No suitable DNS servers have been found to resolve a request.</para></listitem>
<listitem><para>No suitable DNS servers were found to resolve a request.</para></listitem>
</varlistentry>
<varlistentry><term><constant>org.freedesktop.resolve1.InvalidReply</constant></term>
<listitem><para>A response from the selected DNS server could not be understood.</para></listitem>
<listitem><para>A response from the selected DNS server was not understood.</para></listitem>
</varlistentry>
<varlistentry><term><constant>org.freedesktop.resolve1.NoSuchRR</constant></term>
@@ -611,7 +608,7 @@ node /org/freedesktop/resolve1/link/_34 {
</varlistentry>
<varlistentry><term><constant>org.freedesktop.resolve1.Aborted</constant></term>
<listitem><para>The look-up was aborted, because the selected protocol became unavailable while the
<listitem><para>The look-up was aborted because the selected protocol became unavailable while the
operation was ongoing.</para></listitem>
</varlistentry>
@@ -624,7 +621,7 @@ node /org/freedesktop/resolve1/link/_34 {
</varlistentry>
<varlistentry><term><constant>org.freedesktop.resolve1.NoTrustAnchor</constant></term>
<listitem><para>No chain of trust could be established for the response, to a configured DNSSEC trust
<listitem><para>No chain of trust could be established for the response to a configured DNSSEC trust
anchor.</para></listitem>
</varlistentry>
@@ -640,7 +637,7 @@ node /org/freedesktop/resolve1/link/_34 {
</para></listitem></varlistentry>
<varlistentry><term><constant>org.freedesktop.resolve1.LinkBusy</constant></term>
<listitem><para>The requested configuration change can not be made, because
<listitem><para>The requested configuration change could not be made because
<citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
already took possession of the interface and supplied configuration data for it.</para></listitem>
</varlistentry>

83
man/org.freedesktop.systemd1.xml
View File

@@ -16,7 +16,7 @@
<refnamediv>
<refname>org.freedesktop.systemd1</refname>
<refpurpose>The D-Bus interface of systemd-systemdd</refpurpose>
<refpurpose>The D-Bus interface of systemd</refpurpose>
</refnamediv>
<refsect1>
@@ -24,27 +24,27 @@
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> and its
auxiliary daemons expose a number of APIs over D-Bus. This page describes the various APIs exposed by the
system and service manager itself, and does not cover the auxiliary daemons.
auxiliary daemons expose a number of APIs over D-Bus. This page only describes the various APIs exposed by the
system and service manager itself. It does not cover the auxiliary daemons.
</para>
<para>The service manager exposes a number of objects on the bus: one
<interfacename>Manager</interfacename> object as central entry point for clients, and individual objects
<interfacename>Manager</interfacename> object as a central entry point for clients along with individual objects
for each unit and for each queued job. The unit objects each implement a generic
<interfacename>Unit</interfacename> interface plus a type-specific interface. For example, service units
implement <interfacename>org.freedesktop.systemd1.Unit</interfacename> as well as
<interfacename>org.freedesktop.system1.Service</interfacename>. The manager object can be used to list
unit and job objects, or to directly convert a unit name or job id into a bus path of the corresponding
<interfacename>Unit</interfacename> interface as well as a type-specific interface. For example, service units
implement both <interfacename>org.freedesktop.systemd1.Unit</interfacename> and
<interfacename>org.freedesktop.system1.Service</interfacename>. The manager object can list
unit and job objects or directly convert a unit name or job id into a bus path of the corresponding
D-Bus object.</para>
<para>Properties exposing time values are usually encoded in microseconds (usec) on the bus, even if
their corresponding settings in the unit files are in seconds.</para>
<para>In contrast to most of the other services of the systemd suite PID 1 does not use PolicyKit for
<para>In contrast to most of the other services of the systemd suite, PID 1 does not use PolicyKit for
controlling access to privileged operations, but relies exclusively on the low-level D-Bus policy
language. (This is done in order to avoid a cyclic dependency between PolicyKit and systemd/PID 1.) This
means that sensitive operations exposed by PID 1 on the bus are generally not available to unprivileged
processes directly. However some (such as shutdown/reboot/suspend) are made available through the D-Bus
processes directly. However, some operations (such as shutdown/reboot/suspend) are made available through the D-Bus
API of logind, see
<citerefentry><refentrytitle>org.freedesktop.login1</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
@@ -245,76 +245,75 @@ node /org/freedesktop/systemd1 {
<refsect2>
<title>Methods</title>
<para>Note that many of the calls exist twice: once on the <interfacename>Manager</interfacename>
object, and once on the respective unit objects. This is to optimize access times so that methods that
<para>Note that many of the methods exist twice: once on the <interfacename>Manager</interfacename>
object and once on the respective unit objects. This is to optimize access times so that methods that
belong to unit objects do not have to be called with a resolved unit path, but can be called with only
the unit id, too.</para>
<para><function>GetUnit()</function> may be used to get the unit object path for a unit name. It takes
the unit name and returns the object path. If a unit has not been loaded yet by this name this call
the unit name and returns the object path. If a unit has not been loaded yet by this name this method
will fail.</para>
<para><function>GetUnitByPID()</function> may be used to get the unit object path of the unit a process
ID belongs to. Takes a UNIX PID and returns the object path. The PID must refer to an existing process
of the system.</para>
ID belongs to. It takes a UNIX PID and returns the object path. The PID must refer to an existing system process.</para>
<para><function>LoadUnit()</function> is similar to <function>GetUnit()</function> but will load the
unit from disk if possible.</para>
<para><function>StartUnit()</function> enqeues a start job, and possibly depending jobs. Takes the unit
to activate, plus a mode string. The mode needs to be one of <literal>replace</literal>,
<literal>fail</literal>, <literal>isolate</literal>, <literal>ignore-dependencies</literal>,
<literal>ignore-requirements</literal>. If <literal>replace</literal> the call will start the unit and
its dependencies, possibly replacing already queued jobs that conflict with this. If
<literal>fail</literal> the call will start the unit and its dependencies, but will fail if this would
change an already queued job. If <literal>isolate</literal> the call will start the unit in question
and terminate all units that aren't dependencies of it. If <literal>ignore-dependencies</literal> it
will start a unit but ignore all its dependencies. If <literal>ignore-requirements</literal> it will
<para><function>StartUnit()</function> enqueues a start job and possibly depending jobs. It takes the unit
to activate and a mode string as arguments. The mode needs to be one of <literal>replace</literal>,
<literal>fail</literal>, <literal>isolate</literal>, <literal>ignore-dependencies</literal>, or
<literal>ignore-requirements</literal>. If <literal>replace</literal>, the method will start the unit and
its dependencies, possibly replacing already queued jobs that conflict with it. If
<literal>fail</literal>, the method will start the unit and its dependencies, but will fail if this would
change an already queued job. If <literal>isolate</literal>, the method will start the unit in question
and terminate all units that aren't dependencies of it. If <literal>ignore-dependencies</literal>, it
will start a unit but ignore all its dependencies. If <literal>ignore-requirements</literal>, it will
start a unit but only ignore the requirement dependencies. It is not recommended to make use of the
latter two options. Returns the newly created job object.</para>
latter two options. On completion, this method returns the newly created job object.</para>
<para><function>StartUnitReplace()</function> is similar to <function>StartUnit()</function> but
replaces a job that is queued for one unit by a job for another.</para>
replaces a job that is queued for one unit by a job for another unit.</para>
<para><function>StopUnit()</function> is similar to <function>StartUnit()</function> but stops the
specified unit rather than starting it. Note that <literal>isolate</literal> mode is invalid for this
call.</para>
specified unit rather than starting it. Note that the <literal>isolate</literal> mode is invalid for this
method.</para>
<para><function>ReloadUnit()</function>, <function>RestartUnit()</function>,
<function>TryRestartUnit()</function>, <function>ReloadOrRestartUnit()</function>,
<function>ReloadOrTryRestartUnit()</function> may be used to restart and/or reload a unit, and takes
<function>TryRestartUnit()</function>, <function>ReloadOrRestartUnit()</function>, or
<function>ReloadOrTryRestartUnit()</function> may be used to restart and/or reload a unit. These methods take
similar arguments as <function>StartUnit()</function>. Reloading is done only if the unit is already
running and fails otherwise. If a service is restarted that isn't running it will be started, unless
running and fails otherwise. If a service is restarted that isn't running, it will be started unless
the "Try" flavor is used in which case a service that isn't running is not affected by the restart. The
"ReloadOrRestart" flavors attempt a reload if the unit supports it and use a restart otherwise.</para>
<para><function>KillUnit()</function> may be used to kill (i.e. send a signal to) all processes of a
unit. Takes the unit <varname>name</varname>, an enum <varname>who</varname> and a UNIX
unit. It takes the unit <varname>name</varname>, an enum <varname>who</varname> and a UNIX
<varname>signal</varname> number to send. The <varname>who</varname> enum is one of
<literal>main</literal>, <literal>control</literal> or <literal>all</literal>. If
<literal>main</literal>, only the main process of a unit is killed. If <literal>control</literal> only
the control process of the unit is killed, if <literal>all</literal> all processes are killed. A
<literal>main</literal>, only the main process of the unit is killed. If <literal>control</literal>, only
the control process of the unit is killed. If <literal>all</literal>, all processes are killed. A
<literal>control</literal> process is for example a process that is configured via
<varname>ExecStop=</varname> and is spawned in parallel to the main daemon process, in order to shut it
<varname>ExecStop=</varname> and is spawned in parallel to the main daemon process in order to shut it
down.</para>
<para><function>GetJob()</function> returns the job object path for a specific job, identified by its
id.</para>
<para><function>CancelJob()</function> cancels a specific job identified by its numer ID. This
operation is also available in the <function>Cancel()</function> method of Job objects (see below), and
<para><function>CancelJob()</function> cancels a specific job identified by its numeric ID. This
operation is also available in the <function>Cancel()</function> method of Job objects (see below) and
exists primarily to reduce the necessary round trips to execute this operation. Note that this will not
have any effect on jobs whose execution has already begun.</para>
<para><function>ClearJobs()</function> flushes the job queue, removing all jobs that are still
queued. Note that this does not have any effect on jobs whose execution has already begun, it only
queued. Note that this does not have any effect on jobs whose execution has already begun. It only
flushes jobs that are queued and have not yet begun execution.</para>
<para><function>ResetFailedUnit()</function> resets the "failed" state of a specific unit.</para>
<para><function>ResetFailed()</function> resets the "failed" state of all units.</para>
<para><function>ListUnits()</function> returns an array with all currently loaded units. Note that
<para><function>ListUnits()</function> returns an array of all currently loaded units. Note that
units may be known by multiple names at the same name, and hence there might be more unit names loaded
than actual units behind them. The array consists of structures with the following elements:
<itemizedlist>
@@ -336,7 +335,7 @@ node /org/freedesktop/systemd1 {
<listitem><para>The unit object path</para></listitem>
<listitem><para>If there is a job queued for the job unit the numeric job id, 0
<listitem><para>If there is a job queued for the job unit, the numeric job id, 0
otherwise</para></listitem>
<listitem><para>The job type as string</para></listitem>
@@ -361,8 +360,8 @@ node /org/freedesktop/systemd1 {
</itemizedlist></para>
<para><function>Subscribe()</function> enables most bus signals to be sent out. Clients which are
interested in signals need to call this function. Signals are only sent out if at least one client
invoked this function. <function>Unsubscribe()</function> undoes the signal subscription that
interested in signals need to call this method. Signals are only sent out if at least one client
invoked this method. <function>Unsubscribe()</function> reverts the signal subscription that
<function>Subscribe()</function> implements. It is not necessary to invoke
<function>Unsubscribe()</function> as clients are tracked. Signals are no longer sent out as soon as
all clients which previously asked for <function>Subscribe()</function> either closed the bus

20
man/org.freedesktop.timedate1.xml
View File

@@ -25,7 +25,7 @@
<para>
<citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
is a system service that can be used to control the system time and related settings. This page
is a system service that can be used to control the system time and related settings. This page
describes the D-Bus interface.</para>
</refsect1>
@@ -93,8 +93,8 @@ node /org/freedesktop/timedate1 {
<para>Use <function>SetTime()</function> to change the system clock. Pass a value of microseconds since
the UNIX epoch (1 Jan 1970 UTC). If <varname>relative</varname> is true, the passed usec value will be
added to the current system time, if it is false the current system time will be set to the passed usec
value. If the system time is set with this call the RTC will be updated as well.</para>
added to the current system time. If it is false, the current system time will be set to the passed usec
value. If the system time is set with this method, the RTC will be updated as well.</para>
<para>Use <function>SetTimezone()</function> to set the system timezone. Pass a value like
<literal>Europe/Berlin</literal> to set the timezone. Valid timezones are listed in
@@ -102,11 +102,11 @@ node /org/freedesktop/timedate1 {
time, it will be updated accordingly.</para>
<para>Use <function>SetLocalRTC()</function> to control whether the RTC is in local time or UTC. It is
strongly recommended to maintain the RTC in UTC. Some OSes (Windows) however maintain the RTC in local
time, which might make it necessary to enable this feature. However, this creates various problems as
daylight changes might be missed. If <varname>fix_system</varname> is passed <literal>true</literal>,
the time from the RTC is read again and the system clock adjusted according to the new setting. If
<varname>fix_system</varname> is passed <literal>false</literal> the system time is written to the RTC
strongly recommended to maintain the RTC in UTC. However, some OSes (Windows) maintain the RTC in local
time, which might make it necessary to enable this feature. Note that this might create various problems as
daylight changes could be missed. If <varname>fix_system</varname> is <literal>true</literal>,
the time from the RTC is read again and the system clock is adjusted according to the new setting. If
<varname>fix_system</varname> is <literal>false</literal>, the system time is written to the RTC
taking the new setting into account. Use <varname>fix_system=true</varname> in installers and livecds
where the RTC is probably more reliable than the system time. Use <varname>fix_system=false</varname>
in configuration UIs that are run during normal operation and where the system clock is probably more
@@ -116,7 +116,7 @@ node /org/freedesktop/timedate1 {
network using <filename>systemd-timesyncd</filename>. This will enable and start or disable and stop
the chosen time synchronization service.</para>
<para>Whenever the timezone and local_rtc settings are changed via the daemon
<para>Whenever the timezone and local_rtc settings are changed via the daemon,
<function>PropertyChanged</function> signals are sent out to which clients can subscribe. Changing the
time settings using this interface is authenticated via PolicyKit.</para>
@@ -126,7 +126,7 @@ node /org/freedesktop/timedate1 {
</para>
<para>The <varname>user_interaction</varname> boolean parameters can be used to control whether
PolicyKit should interactively ask the user for authentication credentials if it needs to.</para>
PolicyKit should interactively ask the user for authentication credentials if required.</para>
<para>The PolicyKit action for <function>SetTimezone()</function> is
<interfacename>org.freedesktop.timedate1.set-timezone</interfacename>. For

10
man/systemd-hostnamed.service.xml
View File

@@ -30,18 +30,18 @@
<title>Description</title>
<para><filename>systemd-hostnamed.service</filename> is a system service that may be used to change the
system's hostname and related machine meta data from user programs. It is automatically activated on
system's hostname and related machine metadata from user programs. It is automatically activated on
request and terminates itself when unused.</para>
<para>It currently offers access to five variables:
<itemizedlist>
<listitem><para>The current host name (Example: <literal>dhcp-192-168-47-11</literal>)</para>
<listitem><para>The current hostname (Example: <literal>dhcp-192-168-47-11</literal>)</para>
</listitem>
<listitem><para>The static (configured) host name (Example:
<listitem><para>The static (configured) hostname (Example:
<literal>lennarts-computer</literal>)</para></listitem>
<listitem><para>The pretty host name (Example: <literal>Lennart's Computer</literal>)</para>
<listitem><para>The pretty hostname (Example: <literal>Lennart's Computer</literal>)</para>
</listitem>
<listitem><para>A suitable icon name for the local host (Example:
@@ -55,7 +55,7 @@
<citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
is a command line client to this service.</para>
<para>See the
<para>See
<citerefentry><refentrytitle>org.freedesktop.hostname1</refentrytitle><manvolnum>1</manvolnum></citerefentry>
for a description of the D-Bus API.</para>
</refsect1>

2
man/systemd-localed.service.xml
View File

@@ -40,7 +40,7 @@
<citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
is a command line client to this service.</para>
<para>See the
<para>See
<citerefentry><refentrytitle>org.freedesktop.locale1</refentrytitle><manvolnum>1</manvolnum></citerefentry>
for a description of the D-Bus API.</para>
</refsect1>

4
man/systemd-logind.service.xml
View File

@@ -80,7 +80,7 @@
<para>See
<citerefentry><refentrytitle>org.freedesktop.login1</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for for information about the D-Bus APIs <filename>systemd-logind</filename> provides.</para>
for information about the D-Bus APIs <filename>systemd-logind</filename> provides.</para>
<para>For more information on the inhibition logic see the <ulink
url="https://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor
@@ -88,7 +88,7 @@
<para>If you are interested in writing a display manager that makes use of logind, please have look at
<ulink url="https://www.freedesktop.org/wiki/Software/systemd/writing-display-managers">Writing Display
Manager</ulink>.
Managers</ulink>.
If you are interested in writing a desktop environment that makes use of logind, please have look at
<ulink url="http://www.freedesktop.org/wiki/Software/systemd/writing-desktop-environments">Writing
Desktop Environments</ulink>.</para>

2
man/systemd-machined.service.xml
View File

@@ -67,7 +67,7 @@
containers, connecting to the container's init system for that.</para></listitem>
<listitem><para>systemctl's <option>--recursive</option> switch has the effect of not only showing the
locally running services, but recursively the services of all registered containers.</para></listitem>
locally running services, but recursively showing the services of all registered containers.</para></listitem>
<listitem><para>The <command>machinectl</command> command provides access to a number of useful
operations on registered containers, such as introspecting them, rebooting, shutting them down, and