picnoir
/
Systemd
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

man: reorder hostname1(5)

This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2020-04-14 10:28:50 +02:00
parent 33b58dfb41
commit debf2ddd28
1 changed files with 29 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
man/org.freedesktop.hostname1.xml
View File

@ -219,10 +219,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 +240,46 @@ 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>Security</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>The <varname>interactive</varname> boolean parameters can be used to control whether PolicyKit
should interactively ask the user for authentication credentials if required.</para>
<para>Here are three examples show how the pretty hostname and the icon name should be used:
<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>
</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 +323,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>