<para>The service exposes the following interfaces on the bus:</para>
- <programlisting>
-$ gdbus introspect --system \
- --dest org.freedesktop.hostname1 \
- --object-path /org/freedesktop/hostname1
-
+ <programlisting executable="systemd-hostnamed" node="/org/freedesktop/hostname1" interface="org.freedesktop.hostname1">
node /org/freedesktop/hostname1 {
interface org.freedesktop.hostname1 {
methods:
};
</programlisting>
- <!--method SetDeployment is not documented!-->
+ <!--Autogenerated cross-references for systemd.directives, do not edit-->
+
+ <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.hostname1"/>
+
+ <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.hostname1"/>
+
+ <variablelist class="dbus-method" generated="True" extra-ref="SetHostname()"/>
+
+ <variablelist class="dbus-method" generated="True" extra-ref="SetStaticHostname()"/>
+
+ <variablelist class="dbus-method" generated="True" extra-ref="SetPrettyHostname()"/>
+
+ <variablelist class="dbus-method" generated="True" extra-ref="SetIconName()"/>
- <!--method SetLocation is not documented!-->
+ <variablelist class="dbus-method" generated="True" extra-ref="SetChassis()"/>
- <!--method GetProductUUID is not documented!-->
+ <variablelist class="dbus-method" generated="True" extra-ref="SetDeployment()"/>
- <!--property Hostname is not documented!-->
+ <variablelist class="dbus-method" generated="True" extra-ref="SetLocation()"/>
- <!--property StaticHostname is not documented!-->
+ <variablelist class="dbus-method" generated="True" extra-ref="GetProductUUID()"/>
- <!--property PrettyHostname is not documented!-->
+ <variablelist class="dbus-property" generated="True" extra-ref="Hostname"/>
- <!--property IconName is not documented!-->
+ <variablelist class="dbus-property" generated="True" extra-ref="StaticHostname"/>
- <!--property Chassis is not documented!-->
+ <variablelist class="dbus-property" generated="True" extra-ref="PrettyHostname"/>
- <!--property Deployment is not documented!-->
+ <variablelist class="dbus-property" generated="True" extra-ref="IconName"/>
- <!--property Location is not documented!-->
+ <variablelist class="dbus-property" generated="True" extra-ref="Chassis"/>
- <!--property KernelName is not documented!-->
+ <variablelist class="dbus-property" generated="True" extra-ref="Deployment"/>
- <!--property KernelRelease is not documented!-->
+ <variablelist class="dbus-property" generated="True" extra-ref="Location"/>
- <!--property KernelVersion is not documented!-->
+ <variablelist class="dbus-property" generated="True" extra-ref="KernelName"/>
- <!--property OperatingSystemPrettyName is not documented!-->
+ <variablelist class="dbus-property" generated="True" extra-ref="KernelRelease"/>
- <!--property OperatingSystemCPEName is not documented!-->
+ <variablelist class="dbus-property" generated="True" extra-ref="KernelVersion"/>
- <!--property HomeURL is not documented!-->
+ <variablelist class="dbus-property" generated="True" extra-ref="OperatingSystemPrettyName"/>
+
+ <variablelist class="dbus-property" generated="True" extra-ref="OperatingSystemCPEName"/>
+
+ <variablelist class="dbus-property" generated="True" extra-ref="HomeURL"/>
+
+ <!--End of Autogenerated section-->
<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>
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
<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><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><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>
- <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>
+ <refsect1>
+ <title>Recommendations</title>
- <para>Here are three examples show how the pretty hostname and the icon name should be used:
+ <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>
</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>
the usual interface versioning guidelines</ulink>.</para>
</refsect1>
+ <refsect1>
+ <title>Examples</title>
+
+ <example>
+ <title>Introspect <interfacename>org.freedesktop.hostname1</interfacename> on the bus</title>
+
+ <programlisting>$ gdbus introspect --system \
+ --dest org.freedesktop.hostname1 \
+ --object-path /org/freedesktop/hostname1
+ </programlisting>
+ </example>
+ </refsect1>
+
<refsect1>
<title>See also</title>
projects / thirdparty / systemd.git / blobdiff