mirror of
https://github.com/Dasharo/systemd.git
synced 2026-03-06 15:02:31 -08:00
Merge pull request #15472 from keszybz/dbus-api-docs
A few more dbus api documentation updates
This commit is contained in:
Lennart Poettering
GitHub
20
NEWS
20
NEWS
@@ -280,7 +280,7 @@ CHANGES WITH 245:
|
||||
such files in version 243.
|
||||
|
||||
* systemd-logind will now validate access to the operation of changing
|
||||
the virtual terminal via a PolicyKit action. By default, only users
|
||||
the virtual terminal via a polkit action. By default, only users
|
||||
with at least one session on a local VT are granted permission.
|
||||
|
||||
* When systemd sets up PAM sessions that invoked service processes
|
||||
@@ -2032,7 +2032,7 @@ CHANGES WITH 239:
|
||||
lookup is likely to trigger nss-ldap which in turn might use NSS to
|
||||
ask systemd-resolved for hostname lookups. This will hence result in
|
||||
a deadlock: a user name lookup in order to start
|
||||
systemd-resolved.service will result in a host name lookup for which
|
||||
systemd-resolved.service will result in a hostname lookup for which
|
||||
systemd-resolved.service needs to be started already. There are
|
||||
multiple ways to work around this problem: pre-allocate the
|
||||
"systemd-resolve" user on such systems, so that nss-ldap won't be
|
||||
@@ -3001,7 +3001,7 @@ CHANGES WITH 235:
|
||||
A/AAAA resource record for the "_gateway" hostname, pointing to the
|
||||
current default IP gateway. Previously it did that for the "gateway"
|
||||
name, hampering adoption, as some distributions wanted to leave that
|
||||
host name open for local use. The old behaviour may still be
|
||||
hostname open for local use. The old behaviour may still be
|
||||
requested at build time.
|
||||
|
||||
* systemd-networkd's [Address] section in .network files gained a new
|
||||
@@ -4342,7 +4342,7 @@ CHANGES WITH 230:
|
||||
again don't consider turning this on in your stable, LTS or
|
||||
production release just yet. (Note that you have to enable
|
||||
nss-resolve in /etc/nsswitch.conf, to actually use systemd-resolved
|
||||
and its DNSSEC mode for host name resolution from local
|
||||
and its DNSSEC mode for hostname resolution from local
|
||||
applications.)
|
||||
|
||||
* systemd-resolve conveniently resolves DANE records with the --tlsa
|
||||
@@ -6160,14 +6160,14 @@ CHANGES WITH 218:
|
||||
for a unit, as declared in the (usually vendor-supplied)
|
||||
system preset files.
|
||||
|
||||
* nss-myhostname will now resolve the single-label host name
|
||||
* nss-myhostname will now resolve the single-label hostname
|
||||
"gateway" to the locally configured default IP routing
|
||||
gateways, ordered by their metrics. This assigns a stable
|
||||
name to the used gateways, regardless which ones are
|
||||
currently configured. Note that the name will only be
|
||||
resolved after all other name sources (if nss-myhostname is
|
||||
configured properly) and should hence not negatively impact
|
||||
systems that use the single-label host name "gateway" in
|
||||
systems that use the single-label hostname "gateway" in
|
||||
other contexts.
|
||||
|
||||
* systemd-inhibit now allows filtering by mode when listing
|
||||
@@ -7595,7 +7595,7 @@ CHANGES WITH 210:
|
||||
reported by uname()'s "machine" field.
|
||||
|
||||
* systemd-networkd now supports matching on the system
|
||||
virtualization, architecture, kernel command line, host name
|
||||
virtualization, architecture, kernel command line, hostname
|
||||
and machine ID.
|
||||
|
||||
* logind is now a lot more aggressive when suspending the
|
||||
@@ -7913,12 +7913,12 @@ CHANGES WITH 209:
|
||||
example, a line that creates /run/nologin).
|
||||
|
||||
* A new API "sd-resolve.h" has been added which provides a simple
|
||||
asynchronous wrapper around glibc NSS host name resolution
|
||||
asynchronous wrapper around glibc NSS hostname resolution
|
||||
calls, such as getaddrinfo(). In contrast to glibc's
|
||||
getaddrinfo_a(), it does not use signals. In contrast to most
|
||||
other asynchronous name resolution libraries, this one does
|
||||
not reimplement DNS, but reuses NSS, so that alternate
|
||||
host name resolution systems continue to work, such as mDNS,
|
||||
hostname resolution systems continue to work, such as mDNS,
|
||||
LDAP, etc. This API is based on libasyncns, but it has been
|
||||
cleaned up for inclusion in systemd.
|
||||
|
||||
@@ -9702,7 +9702,7 @@ CHANGES WITH 190:
|
||||
when he over-mounts a non-empty directory.
|
||||
|
||||
* There are new specifiers that are resolved in unit files,
|
||||
for the host name (%H), the machine ID (%m) and the boot ID
|
||||
for the hostname (%H), the machine ID (%m) and the boot ID
|
||||
(%b).
|
||||
|
||||
Contributions from: Allin Cottrell, Auke Kok, Brandon Philips,
|
||||
|
||||
2
TODO
2
TODO
@@ -1170,7 +1170,7 @@ Features:
|
||||
a carrier is lost on a link. It should be removed instantly.
|
||||
- expose in the API the following bits:
|
||||
- option 15, domain name and/or option 119, search list
|
||||
- option 12, host name and/or option 81, fqdn
|
||||
- option 12, hostname and/or option 81, fqdn
|
||||
- option 123, 144, geolocation
|
||||
- option 252, configure http proxy (PAC/wpad)
|
||||
- provide a way to define a per-network interface default metric value
|
||||
|
||||
@@ -424,7 +424,7 @@ layout: default
|
||||
|
||||
## Deadlocks
|
||||
|
||||
- Do not issue NSS requests (that includes user name and host name lookups)
|
||||
- Do not issue NSS requests (that includes user name and hostname lookups)
|
||||
from PID 1 as this might trigger deadlocks when those lookups involve
|
||||
synchronously talking to services that we would need to start up.
|
||||
|
||||
|
||||
@@ -87,7 +87,7 @@ And now, here's the list of (hopefully) all APIs that we have introduced with sy
|
||||
| [Boot Loader interface](https://systemd.io/BOOT_LOADER_INTERFACE) | EFI variables | yes | yes | gummiboot | yes | - | no |
|
||||
| [Service bus API](https://www.freedesktop.org/wiki/Software/systemd/dbus) | D-Bus | yes | yes | system-config-services | no | - | no |
|
||||
| [logind](https://www.freedesktop.org/wiki/Software/systemd/logind) | D-Bus | yes | yes | GNOME | no | - | no |
|
||||
| [sd-login.h API](https://www.freedesktop.org/software/systemd/man/sd-login.html) | C Library | yes | yes | GNOME, PolicyKit, ... | no | - | no |
|
||||
| [sd-login.h API](https://www.freedesktop.org/software/systemd/man/sd-login.html) | C Library | yes | yes | GNOME, polkit, ... | no | - | no |
|
||||
| [sd-daemon.h API](https://www.freedesktop.org/software/systemd/man/sd-daemon.html) | C Library or Drop-in | yes | yes | numerous | yes | - | yes |
|
||||
| [sd-id128.h API](https://www.freedesktop.org/software/systemd/man/sd-id128.html) | C Library | yes | yes | - | yes | - | no |
|
||||
| [sd-journal.h API](https://www.freedesktop.org/software/systemd/man/sd-journal.html) | C Library | yes | yes | - | maybe | - | no |
|
||||
|
||||
@@ -77,7 +77,8 @@ supports is directly available in these JSON records. Hence it makes sense for
|
||||
any user management UI to expose them directly.
|
||||
|
||||
`systemd-homed` exposes APIs to add, remove and make changes to local users via
|
||||
D-Bus, with full PolicyKit hook-up. On the command line this is exposed via the
|
||||
D-Bus, with full [polkit](https://www.freedesktop.org/software/polkit/docs/latest/)
|
||||
hook-up. On the command line this is exposed via the
|
||||
`homectl` command. A graphical UI that exposes similar functionality would be
|
||||
very useful, exposing the various new account settings, and in particular
|
||||
providing a stream-lined UI for enrolling new-style authentication tokens such
|
||||
|
||||
@@ -57,7 +57,7 @@
|
||||
|
||||
<para>Use
|
||||
<citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
||||
to initialize the system host name for mounted (but not booted)
|
||||
to initialize the system hostname for mounted (but not booted)
|
||||
system images.</para>
|
||||
</refsect1>
|
||||
|
||||
@@ -84,7 +84,7 @@
|
||||
simplified in regards to the character set used before the latter are updated. This is done by removing special
|
||||
characters and spaces. This ensures that the pretty and the static hostname are always closely related while
|
||||
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 host names are set, and the pretty host name is left untouched.</para>
|
||||
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
|
||||
|
||||
@@ -70,7 +70,7 @@
|
||||
<literal>Lennart's Computer</literal> an Internet hostname of
|
||||
<literal>lennarts-computer</literal> might be a good choice.
|
||||
If this parameter is not set, an application should fall back
|
||||
to the Internet host name for presentation
|
||||
to the Internet hostname for presentation
|
||||
purposes.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
||||
@@ -56,7 +56,7 @@
|
||||
</itemizedlist>
|
||||
|
||||
<para>Machines are identified by names that follow the same rules
|
||||
as UNIX and DNS host names. For details, see below.</para>
|
||||
as UNIX and DNS hostnames. For details, see below.</para>
|
||||
|
||||
<para>Machines are instantiated from disk or file system images that
|
||||
frequently — but not necessarily — carry the same name as machines running
|
||||
@@ -383,7 +383,7 @@
|
||||
image is optimized for file systems that support copy-on-write, and might not be efficient on others, due to
|
||||
file system limitations.</para>
|
||||
|
||||
<para>Note that this command leaves host name, machine ID and
|
||||
<para>Note that this command leaves hostname, machine ID and
|
||||
all other settings that could identify the instance
|
||||
unmodified. The original image and the cloned copy will hence
|
||||
share these credentials, and it might be necessary to manually
|
||||
@@ -851,7 +851,7 @@
|
||||
|
||||
<para>The <command>machinectl</command> tool operates on machines
|
||||
and images whose names must be chosen following strict
|
||||
rules. Machine names must be suitable for use as host names
|
||||
rules. Machine names must be suitable for use as hostnames
|
||||
following a conservative subset of DNS and UNIX/Linux
|
||||
semantics. Specifically, they must consist of one or more
|
||||
non-empty label strings, separated by dots. No leading or trailing
|
||||
|
||||
@@ -29,7 +29,7 @@
|
||||
<title>Description</title>
|
||||
|
||||
<para><command>nss-resolve</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of the
|
||||
GNU C Library (<command>glibc</command>) enabling it to resolve host names via the
|
||||
GNU C Library (<command>glibc</command>) enabling it to resolve hostnames via the
|
||||
<citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry> local network
|
||||
name resolution service. It replaces the <command>nss-dns</command> plug-in module that traditionally resolves
|
||||
hostnames via DNS.</para>
|
||||
|
||||
@@ -89,38 +89,6 @@ node /org/freedesktop/hostname1 {
|
||||
};
|
||||
</programlisting>
|
||||
|
||||
<!--method SetDeployment is not documented!-->
|
||||
|
||||
<!--method SetLocation is not documented!-->
|
||||
|
||||
<!--method GetProductUUID is not documented!-->
|
||||
|
||||
<!--property Hostname is not documented!-->
|
||||
|
||||
<!--property StaticHostname is not documented!-->
|
||||
|
||||
<!--property PrettyHostname is not documented!-->
|
||||
|
||||
<!--property IconName is not documented!-->
|
||||
|
||||
<!--property Chassis is not documented!-->
|
||||
|
||||
<!--property Deployment is not documented!-->
|
||||
|
||||
<!--property Location is not documented!-->
|
||||
|
||||
<!--property KernelName is not documented!-->
|
||||
|
||||
<!--property KernelRelease is not documented!-->
|
||||
|
||||
<!--property KernelVersion is not documented!-->
|
||||
|
||||
<!--property OperatingSystemPrettyName is not documented!-->
|
||||
|
||||
<!--property OperatingSystemCPEName is not documented!-->
|
||||
|
||||
<!--property HomeURL is not documented!-->
|
||||
|
||||
<!--Autogenerated cross-references for systemd.directives, do not edit-->
|
||||
|
||||
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.hostname1"/>
|
||||
@@ -173,7 +141,8 @@ node /org/freedesktop/hostname1 {
|
||||
|
||||
<para>Whenever the hostname or other metadata is changed via the daemon,
|
||||
<function>PropertyChanged</function> signals are sent out to subscribed clients. Changing a hostname
|
||||
using this interface is authenticated via PolicyKit.</para>
|
||||
using this interface is authenticated via
|
||||
<ulink url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink>.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
@@ -219,10 +188,6 @@ node /org/freedesktop/hostname1 {
|
||||
it could not be auto-detected. Set this property to the empty string to reenable the automatic detection of
|
||||
the chassis type from firmware information.</para>
|
||||
|
||||
<para>A client that wants to change the local hostname for DHCP/mDNS should invoke
|
||||
<code>SetHostname("newname", false)</code> as soon as the name is available and afterwards reset it via
|
||||
<code>SetHostname("")</code>.</para>
|
||||
|
||||
<para>Note that <filename>systemd-hostnamed</filename> starts only on request and terminates after a
|
||||
short idle period. This effectively means that <function>PropertyChanged</function> messages are not sent
|
||||
out for changes made directly on the files (as in: administrator edits the files with vi). This is
|
||||
@@ -244,33 +209,91 @@ node /org/freedesktop/hostname1 {
|
||||
<citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
for that. For more information on these files and syscalls see the respective man pages.</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 required.</para>
|
||||
<refsect2>
|
||||
<title>Methods and Properties</title>
|
||||
|
||||
<para>The PolicyKit action for <function>SetHostname()</function> is
|
||||
<interfacename>org.freedesktop.hostname1.set-hostname</interfacename>. For
|
||||
<function>SetStaticHostname()</function> and <function>SetPrettyHostname()</function> it is
|
||||
<interfacename>org.freedesktop.hostname1.set-static-hostname</interfacename>. For
|
||||
<function>SetIconName()</function> and <function>SetChassis()</function> it is
|
||||
<interfacename>org.freedesktop.hostname1.set-machine-info</interfacename>.</para>
|
||||
<para><function>SetHostname()</function> sets the transient (dynamic) hostname which is exposed by the
|
||||
<varname>Hostname</varname> property. If empty, the transient hostname is set to the static hostname.
|
||||
</para>
|
||||
|
||||
<para>Here are three examples show how the pretty hostname and the icon name should be used:
|
||||
<para><function>SetStaticHostname()</function> sets the static hostname which is exposed by the
|
||||
<varname>StaticHostname</varname> property. If empty, the built-in default of
|
||||
<literal>&FALLBACK_HOSTNAME;</literal> is used.</para>
|
||||
|
||||
<para><function>SetPrettyHostname()</function> sets the pretty hostname which is exposed by the
|
||||
<varname>PrettyHostname</varname> property.</para>
|
||||
|
||||
<para><function>SetIconName()</function>, <function>SetChassis()</function>,
|
||||
<function>SetDeployment()</function>, and <function>SetLocation()</function> set the properties
|
||||
<varname>IconName</varname> (the name of the icon representing for the machine),
|
||||
<varname>Chassis</varname> (the machine form factor), <varname>Deployment</varname> (the system
|
||||
deployment environment), and <varname>Location</varname> (physical system location), respectively.
|
||||
</para>
|
||||
|
||||
<para><varname>PrettyHostname</varname>, <varname>IconName</varname>, <varname>Chassis</varname>,
|
||||
<varname>Deployment</varname>, and <varname>Location</varname> are stored in
|
||||
<filename>/etc/machine-info</filename>. See
|
||||
<citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
|
||||
the semantics of those settings.</para>
|
||||
|
||||
<para><function>GetProductUUID()</function> returns the "product uuid" as exposed by the kernel based
|
||||
on DMI information in <filename>/sys/class/dmi/id/product_uuid</filename>. Reading the file directly
|
||||
requires root privileges, and this method allows access to unprivileged clients through the polkit
|
||||
framework.</para>
|
||||
|
||||
<para><varname>KernelName</varname>, <varname>KernelRelease</varname>, and
|
||||
<varname>KernelVersion</varname> expose the kernel name (e.g. <literal>Linux</literal>), release
|
||||
(e.g. <literal>5.0.0-11</literal>, and version (i.e. the build number, e.g. <literal>#11</literal>) as
|
||||
reported by
|
||||
<citerefentry project="man-pages"><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
|
||||
<varname>OperatingSystemPrettyName</varname>, <varname>OperatingSystemCPEName</varname>, and
|
||||
<varname>HomeURL</varname> expose the <varname>PRETTY_NAME=</varname>, <varname>CPE_NAME=</varname> and
|
||||
<varname>HOME_URL=</varname> fields from
|
||||
<citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
|
||||
purpose of those properties is to allow remote clients to access this information over D-Bus. Local
|
||||
clients can access the information directly.</para>
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
<title>Security</title>
|
||||
|
||||
<para>The <varname>interactive</varname> boolean parameters can be used to control whether polkit
|
||||
should interactively ask the user for authentication credentials if required.</para>
|
||||
|
||||
<para>The polkit action for <function>SetHostname()</function> is
|
||||
<interfacename>org.freedesktop.hostname1.set-hostname</interfacename>. For
|
||||
<function>SetStaticHostname()</function> and <function>SetPrettyHostname()</function> it is
|
||||
<interfacename>org.freedesktop.hostname1.set-static-hostname</interfacename>. For
|
||||
<function>SetIconName()</function> and <function>SetChassis()</function> it is
|
||||
<interfacename>org.freedesktop.hostname1.set-machine-info</interfacename>.</para>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Recommendations</title>
|
||||
|
||||
<para>Here are three examples that show how the pretty hostname and the icon name should be used:
|
||||
<itemizedlist>
|
||||
<listitem><para>When registering DNS-SD services: use the pretty hostname in the service name, and
|
||||
pass the icon name in the TXT data, if there is an icon name. Browsing clients can then show the server
|
||||
icon on each service. This is especially useful for WebDAV applications or UPnP media sharing.
|
||||
<listitem><para>When registering DNS-SD services: use the pretty hostname in the service name, and pass
|
||||
the icon name in the TXT data, if there is an icon name. Browsing clients can then show the server icon
|
||||
on each service. This is especially useful for WebDAV applications or UPnP media sharing.
|
||||
</para></listitem>
|
||||
|
||||
<listitem><para>Set the bluetooth name to the pretty hostname.</para></listitem>
|
||||
|
||||
<listitem><para>When your file browser has a "Computer" icon, replace the name with the pretty hostname if set, and the icon with the icon name, if it is set.</para></listitem>
|
||||
<listitem><para>When your file browser has a "Computer" icon, replace the name with the pretty hostname
|
||||
if set, and the icon with the icon name, if it is set.</para></listitem>
|
||||
</itemizedlist></para>
|
||||
|
||||
<para>To properly handle name lookups with changing local hostnames without having to edit
|
||||
<filename>/etc/hosts</filename>, we recommend using <filename>systemd-hostnamed</filename> in
|
||||
combination with <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||||
<filename>/etc/hosts</filename>, we recommend using <filename>systemd-hostnamed</filename> in combination
|
||||
with <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||||
</para>
|
||||
|
||||
<para>A client that wants to change the local hostname for DHCP/mDNS should invoke
|
||||
<code>SetHostname("newname", false)</code> as soon as the name is available and afterwards reset it via
|
||||
<code>SetHostname("")</code>.</para>
|
||||
|
||||
<para>Here are some recommendations to follow when generating a static (internet) hostname from a pretty
|
||||
name:
|
||||
<itemizedlist>
|
||||
@@ -314,7 +337,7 @@ node /org/freedesktop/hostname1 {
|
||||
</itemizedlist></para>
|
||||
|
||||
<para>Of course, an already valid internet hostname label you enter and pass through this
|
||||
conversion should stay unmodified, so that users have direct control of it, if they want -- by simply
|
||||
conversion should stay unmodified, so that users have direct control of it, if they want — by simply
|
||||
ignoring the fact that the pretty hostname is pretty and just edit it as if it was the normal internet
|
||||
name.</para>
|
||||
</refsect1>
|
||||
|
||||
@@ -126,7 +126,8 @@ 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
|
||||
<para>The <varname>interactive</varname> boolean parameters can be used to control whether
|
||||
<ulink url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink>
|
||||
should interactively ask the user for authentication credentials if required.</para>
|
||||
</refsect2>
|
||||
|
||||
@@ -160,9 +161,9 @@ node /org/freedesktop/locale1 {
|
||||
<refsect2>
|
||||
<title>Security</title>
|
||||
|
||||
<para>Changing the system locale or keymap using this interface is authenticated via PolicyKit. The
|
||||
PolicyKit action for <function>SetLocale()</function> is
|
||||
<constant>org.freedesktop.locale1.set-locale</constant>. The PolicyKit action for
|
||||
<para>Changing the system locale or keymap using this interface is authenticated via polkit. The
|
||||
polkit action for <function>SetLocale()</function> is
|
||||
<constant>org.freedesktop.locale1.set-locale</constant>. The polkit action for
|
||||
<function>SetX11Keyboard()</function> and <function>SetVConsoleKeyboard()</function> is
|
||||
<constant>org.freedesktop.locale1.set-keyboard</constant>.</para>
|
||||
</refsect2>
|
||||
|
||||
@@ -496,22 +496,24 @@ node /org/freedesktop/login1 {
|
||||
and seat are identified by their respective IDs.</para>
|
||||
|
||||
<para><function>SetUserLinger()</function> enables or disables user lingering. If enabled, the runtime
|
||||
directory of a user is kept around and he may continue to run processes while he is logged out. If
|
||||
directory of a user is kept around and they may continue to run processes while logged out. If
|
||||
disabled, the runtime directory goes away as soon as they log out. <function>SetUserLinger()</function>
|
||||
expects three arguments: the UID, a boolean whether to enable/disable and a boolean controlling the
|
||||
PolicyKit authorization interactivity (see below). Note that the user linger state is persistently
|
||||
<ulink url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink>
|
||||
authorization interactivity (see below). Note that the user linger state is persistently
|
||||
stored on disk.</para>
|
||||
|
||||
<para><function>AttachDevice()</function> may be used to assign a specific device to a specific
|
||||
seat. The device is identified by its /sys path and must be eligible for seat assignments. <function>AttachDevice()</function> takes three
|
||||
arguments: the seat id, the sysfs path, and a boolean for controlling PolicyKit interactivity (see
|
||||
below). Device assignments are persistently stored on disk. To create a new seat, simply specify a
|
||||
previously unused seat id. For more information about the seat assignment logic see
|
||||
seat. The device is identified by its <filename>/sys</filename> path and must be eligible for seat
|
||||
assignments. <function>AttachDevice()</function> takes three arguments: the seat id, the sysfs path,
|
||||
and a boolean for controlling polkit interactivity (see below). Device assignments are persistently
|
||||
stored on disk. To create a new seat, simply specify a previously unused seat id. For more information
|
||||
about the seat assignment logic see
|
||||
<ulink url="https://www.freedesktop.org/wiki/Software/systemd/multiseat">Multi-Seat for Linux</ulink>.
|
||||
</para>
|
||||
|
||||
<para><function>FlushDevices()</function> removes all explicit seat assignments for devices, resetting
|
||||
all assignments to the automatic defaults. The only argument it takes is the PolicyKit interactivity
|
||||
all assignments to the automatic defaults. The only argument it takes is the polkit interactivity
|
||||
boolean (see below).</para>
|
||||
|
||||
<para><function>PowerOff()</function>, <function>Reboot()</function>, <function>Halt()</function>,
|
||||
@@ -521,9 +523,9 @@ node /org/freedesktop/login1 {
|
||||
the machine is powered down). <function>HybridSleep()</function> results in the system entering a
|
||||
hybrid-sleep mode, i.e. the system is both hibernated and suspended.
|
||||
<function>SuspendThenHibernate()</function> results in the system being suspended, then later woken
|
||||
using an RTC timer and hibernated. The only argument is the PolicyKit interactivity boolean
|
||||
using an RTC timer and hibernated. The only argument is the polkit interactivity boolean
|
||||
<varname>interactive</varname> (see below). The main purpose of these calls is that they enforce
|
||||
PolicyKit policy and hence allow powering off/rebooting/suspending/hibernating even by unprivileged
|
||||
polkit policy and hence allow powering off/rebooting/suspending/hibernating even by unprivileged
|
||||
users. They also enforce inhibition locks. UIs should expose these calls as the primary mechanism to
|
||||
poweroff/reboot/suspend/hibernate the machine.</para>
|
||||
|
||||
@@ -678,7 +680,7 @@ node /org/freedesktop/login1 {
|
||||
<refsect2>
|
||||
<title>Security</title>
|
||||
|
||||
<para>A number of operations are protected via the PolicyKit privilege
|
||||
<para>A number of operations are protected via the polkit privilege
|
||||
system. <function>SetUserLinger()</function> requires the
|
||||
<interfacename>org.freedesktop.login1.set-user-linger</interfacename>
|
||||
privilege. <function>AttachDevice()</function> requires
|
||||
@@ -731,7 +733,7 @@ node /org/freedesktop/login1 {
|
||||
<interfacename>org.freedesktop.login1.inhibit-handle-lid-switch</interfacename> depending on the lock
|
||||
type and mode taken.</para>
|
||||
|
||||
<para>The <varname>interactive</varname> boolean parameters can be used to control whether PolicyKit
|
||||
<para>The <varname>interactive</varname> boolean parameters can be used to control whether polkit
|
||||
should interactively ask the user for authentication credentials if required.</para>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
@@ -846,8 +848,8 @@ node /org/freedesktop/login1/seat/seat0 {
|
||||
encoded in a structure consisting of the ID and the object path.</para>
|
||||
|
||||
<para>The <varname>IdleHint</varname>, <varname>IdleSinceHint</varname>, and
|
||||
<varname>IdleSinceHint</varname> properties encode the idle state, similar to the one exposed on the
|
||||
Manager object, but specific for this seat.</para>
|
||||
<varname>IdleSinceHintMonotonic</varname> properties encode the idle state, similar to the ones exposed
|
||||
on the <interfacename>Manager</interfacename> object, but specific for this seat.</para>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
|
||||
@@ -394,7 +394,7 @@ node /org/freedesktop/resolve1 {
|
||||
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
|
||||
is only enabled for resolving names, but the local hostname is not registered for other peers to
|
||||
use.</para>
|
||||
|
||||
<para>Similarly, the <function>SetLinkMulticastDNS()</function> method enables or disables MulticastDNS
|
||||
|
||||
@@ -40,9 +40,10 @@
|
||||
<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
|
||||
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
|
||||
<para>In contrast to most of the other services of the systemd suite, PID 1 does not use
|
||||
<ulink url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink>
|
||||
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 polkit 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 operations (such as shutdown/reboot/suspend) are made available through the D-Bus
|
||||
API of logind, see
|
||||
@@ -1463,7 +1464,7 @@ node /org/freedesktop/systemd1 {
|
||||
<title>Security</title>
|
||||
|
||||
<para>Read access is generally granted to all clients. Additionally, for unprivileged clients, some
|
||||
operations are allowed through the PolicyKit privilege system. Operations which modify unit state
|
||||
operations are allowed through the polkit privilege system. Operations which modify unit state
|
||||
(<function>StartUnit()</function>, <function>StopUnit()</function>, <function>KillUnit()</function>,
|
||||
<function>RestartUnit()</function> and similar, <function>SetProperty</function>) require
|
||||
<interfacename>org.freedesktop.systemd1.manage-units</interfacename>. Operations which modify unit file
|
||||
@@ -2127,7 +2128,7 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice {
|
||||
allowed for everyone. All operations are allowed for clients with the
|
||||
<constant>CAP_SYS_ADMIN</constant> capability or when the
|
||||
<interfacename>org.freedesktop.systemd1.manage-units</interfacename> privilege is granted by
|
||||
PolicyKit.</para>
|
||||
polkit.</para>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
|
||||
@@ -72,22 +72,6 @@ node /org/freedesktop/timedate1 {
|
||||
};
|
||||
</programlisting>
|
||||
|
||||
<!--method ListTimezones is not documented!-->
|
||||
|
||||
<!--property Timezone is not documented!-->
|
||||
|
||||
<!--property LocalRTC is not documented!-->
|
||||
|
||||
<!--property CanNTP is not documented!-->
|
||||
|
||||
<!--property NTP is not documented!-->
|
||||
|
||||
<!--property NTPSynchronized is not documented!-->
|
||||
|
||||
<!--property TimeUSec is not documented!-->
|
||||
|
||||
<!--property RTCTimeUSec is not documented!-->
|
||||
|
||||
<!--Autogenerated cross-references for systemd.directives, do not edit-->
|
||||
|
||||
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.timedate1"/>
|
||||
@@ -148,25 +132,51 @@ 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,
|
||||
<function>PropertyChanged</function> signals are sent out to which clients can subscribe. Changing the
|
||||
time settings using this interface is authenticated via PolicyKit.</para>
|
||||
<para><function>ListTimezones()</function> returns a list of time zones known on the local system as an
|
||||
array of names (<literal>["Africa/Abidjan", "Africa/Accra", ..., "UTC"]</literal>).</para>
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
<title>Properties</title>
|
||||
|
||||
<para><varname>Timezone</varname> shows the currently configured time zone.
|
||||
<varname>LocalRTC</varname> shows whether the RTC is configured to use UTC (false), or the local time
|
||||
zone (true). <varname>CanNTP</varname> shows whether a service to perform time synchronization over the
|
||||
network is available, and <varname>NTP</varname> shows whether such a service is enabled.</para>
|
||||
|
||||
<para><varname>NTPSynchronized</varname> shows whether the kernel reports the time as synchronized
|
||||
(c.f.
|
||||
<citerefentry project="man-pages"><refentrytitle>adjtimex</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
|
||||
<varname>TimeUSec</varname> and <varname>RTCTimeUSec</varname> show the current time on the system and
|
||||
in the RTC. The purpose of those three properties is to allow remote clients to access this information
|
||||
over D-Bus. Local clients can access the information directly.</para>
|
||||
|
||||
<para>Whenever the <varname>Timezone</varname> and <varname>LocalRTC</varname> settings are changed via
|
||||
the daemon, <function>PropertyChanged</function> signals are sent out to which clients can subscribe.
|
||||
</para>
|
||||
|
||||
<para>Note that this service will not inform you about system time changes. Use
|
||||
<citerefentry project="man-pages"><refentrytitle>timerfd</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
with <constant>CLOCK_REALTIME</constant> and <constant>TFD_TIMER_CANCEL_ON_SET</constant> for that.
|
||||
</para>
|
||||
</refsect2>
|
||||
|
||||
<para>The <varname>user_interaction</varname> boolean parameters can be used to control whether
|
||||
PolicyKit should interactively ask the user for authentication credentials if required.</para>
|
||||
<refsect2>
|
||||
<title>Security</title>
|
||||
|
||||
<para>The PolicyKit action for <function>SetTimezone()</function> is
|
||||
<para>The <varname>interactive</varname> boolean parameters can be used to control whether
|
||||
<ulink url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink>
|
||||
should interactively ask the user for authentication credentials if required.</para>
|
||||
|
||||
<para>The polkit action for <function>SetTimezone()</function> is
|
||||
<interfacename>org.freedesktop.timedate1.set-timezone</interfacename>. For
|
||||
<function>SetLocalRTC()</function> it is
|
||||
<interfacename>org.freedesktop.timedate1.set-local-rtc</interfacename>, for
|
||||
<function>SetTime()</function> it is <interfacename>org.freedesktop.timedate1.set-time</interfacename>
|
||||
and for <function>SetNTP()</function> it is
|
||||
<interfacename>org.freedesktop.timedate1.set-ntp</interfacename>.</para>
|
||||
<interfacename>org.freedesktop.timedate1.set-ntp</interfacename>.
|
||||
<function>ListTimezones()</function> does not require any privileges.
|
||||
</para>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
|
||||
@@ -45,7 +45,7 @@
|
||||
interface the data was discovered. It also contains information on whether the information could be
|
||||
authenticated. All data for which local DNSSEC validation succeeds is considered authenticated. Moreover all data
|
||||
originating from local, trusted sources is also reported authenticated, including resolution of the local host
|
||||
name, the <literal>localhost</literal> host name or all data from <filename>/etc/hosts</filename>.</para>
|
||||
name, the <literal>localhost</literal> hostname or all data from <filename>/etc/hosts</filename>.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
|
||||
@@ -68,7 +68,7 @@
|
||||
<varlistentry>
|
||||
<term><varname>Domains=</varname></term>
|
||||
<listitem><para>A space-separated list of domains. These domains are used as search suffixes when resolving
|
||||
single-label host names (domain names which contain no dot), in order to qualify them into fully-qualified
|
||||
single-label hostnames (domain names which contain no dot), in order to qualify them into fully-qualified
|
||||
domain names (FQDNs). Search domains are strictly processed in the order they are specified, until the name
|
||||
with the suffix appended is found. For compatibility reasons, if this setting is not specified, the search
|
||||
domains listed in <filename>/etc/resolv.conf</filename> are used instead, if that file exists and any domains
|
||||
|
||||
@@ -54,7 +54,7 @@
|
||||
|
||||
<listitem><para>The system time zone</para></listitem>
|
||||
|
||||
<listitem><para>The system host name</para></listitem>
|
||||
<listitem><para>The system hostname</para></listitem>
|
||||
|
||||
<listitem><para>The machine ID of the system</para></listitem>
|
||||
|
||||
@@ -133,7 +133,7 @@
|
||||
<term><option>--hostname=<replaceable>HOSTNAME</replaceable></option></term>
|
||||
|
||||
<listitem><para>Sets the system hostname. The argument should
|
||||
be a host name, compatible with DNS. This controls the
|
||||
be a hostname, compatible with DNS. This controls the
|
||||
<citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||
configuration file.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
@@ -238,7 +238,7 @@
|
||||
all subdirectories and subvolumes below it, but excluding any sub-mounts. May not be specified
|
||||
together with <option>--image=</option> or <option>--ephemeral</option>.</para>
|
||||
|
||||
<para>Note that this switch leaves host name, machine ID and
|
||||
<para>Note that this switch leaves hostname, machine ID and
|
||||
all other settings that could identify the instance
|
||||
unmodified.</para></listitem>
|
||||
</varlistentry>
|
||||
@@ -250,7 +250,7 @@
|
||||
<listitem><para>If specified, the container is run with a temporary snapshot of its file system that is removed
|
||||
immediately when the container terminates. May not be specified together with
|
||||
<option>--template=</option>.</para>
|
||||
<para>Note that this switch leaves host name, machine ID and all other settings that could identify
|
||||
<para>Note that this switch leaves hostname, machine ID and all other settings that could identify
|
||||
the instance unmodified. Please note that — as with <option>--template=</option> — taking the
|
||||
temporary snapshot is more efficient on file systems that support subvolume snapshots or 'reflinks'
|
||||
natively (<literal>btrfs</literal> or new <literal>xfs</literal>) than on more traditional file
|
||||
|
||||
@@ -53,7 +53,7 @@
|
||||
(<citerefentry project='man-pages'><refentrytitle>nss</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
|
||||
Usage of the glibc NSS module
|
||||
<citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry> is
|
||||
required in order to allow glibc's NSS resolver functions to resolve host names via
|
||||
required in order to allow glibc's NSS resolver functions to resolve hostnames via
|
||||
<command>systemd-resolved</command>.</para></listitem>
|
||||
|
||||
<listitem><para>Additionally, <command>systemd-resolved</command> provides a local DNS stub listener on
|
||||
@@ -120,8 +120,8 @@
|
||||
|
||||
<listitem><para>Single-label names are routed to all local interfaces capable of IP multicasting, using
|
||||
the LLMNR protocol. Lookups for IPv4 addresses are only sent via LLMNR on IPv4, and lookups for IPv6
|
||||
addresses are only sent via LLMNR on IPv6. Lookups for the locally configured host name and the
|
||||
<literal>_gateway</literal> host name are never routed to LLMNR.</para></listitem>
|
||||
addresses are only sent via LLMNR on IPv6. Lookups for the locally configured hostname and the
|
||||
<literal>_gateway</literal> hostname are never routed to LLMNR.</para></listitem>
|
||||
|
||||
<listitem><para>Multi-label names with the domain suffix <literal>.local</literal> are routed to all
|
||||
local interfaces capable of IP multicasting, using the MulticastDNS protocol. As with LLMNR IPv4
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user