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

man: reorder hostname1(5)

Browse source
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 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> 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 <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 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 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> <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> 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 <refsect2>
should interactively ask the user for authentication credentials if required.</para> <title>Security</title>
<para>The PolicyKit action for <function>SetHostname()</function> is <para>The <varname>interactive</varname> boolean parameters can be used to control whether PolicyKit
<interfacename>org.freedesktop.hostname1.set-hostname</interfacename>. For should interactively ask the user for authentication credentials if required.</para>
<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>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> <itemizedlist>
<listitem><para>When registering DNS-SD services: use the pretty hostname in the service name, and <listitem><para>When registering DNS-SD services: use the pretty hostname in the service name, and pass
pass the icon name in the TXT data, if there is an icon name. Browsing clients can then show the server the icon name in the TXT data, if there is an icon name. Browsing clients can then show the server icon
icon on each service. This is especially useful for WebDAV applications or UPnP media sharing. on each service. This is especially useful for WebDAV applications or UPnP media sharing.
</para></listitem> </para></listitem>
<listitem><para>Set the bluetooth name to the pretty hostname.</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> </itemizedlist></para>
<para>To properly handle name lookups with changing local hostnames without having to edit <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 <filename>/etc/hosts</filename>, we recommend using <filename>systemd-hostnamed</filename> in combination
combination with <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>. with <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para> </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 <para>Here are some recommendations to follow when generating a static (internet) hostname from a pretty
name: name:
<itemizedlist> <itemizedlist>
@ -314,7 +323,7 @@ node /org/freedesktop/hostname1 {
</itemizedlist></para> </itemizedlist></para>
<para>Of course, an already valid internet hostname label you enter and pass through this <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 ignoring the fact that the pretty hostname is pretty and just edit it as if it was the normal internet
name.</para> name.</para>
</refsect1> </refsect1>