shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-12-23 21:35:11 +03:00
Code
4c42df8166
systemd/man/hostnamectl.xml

229 lines
10 KiB
XML
Raw Normal View History

hostname: add new hostnamectl tool as text client for hostnamed
2012-10-17 23:23:30 +04:00
<?xml version='1.0'?> <!--*-nxml-*-->
man: use same header for all files The "include" files had type "book" for some raeason. I don't think this is meaningful. Let's just use the same everywhere. $ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
2019-03-14 16:40:58 +03:00
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
man: use same version in public and system ident.
2023-12-25 17:48:33 +03:00
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
man: say that hostname must can be a fqdn or not Fixes #18426
2021-02-25 16:14:39 +03:00
<!ENTITY % entities SYSTEM "custom-entities.ent" >
%entities;
]>
license: LGPL-2.1+ -> LGPL-2.1-or-later
2020-11-09 07:23:58 +03:00
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
hostname: add new hostnamectl tool as text client for hostnamed
2012-10-17 23:23:30 +04:00
man: xinclude --help/--version/--no-pager
2014-02-13 23:33:51 +04:00
<refentry id="hostnamectl" conditional='ENABLE_HOSTNAMED'
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>hostnamectl</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>hostnamectl</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv>
<refname>hostnamectl</refname>
<refpurpose>Control the system hostname</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>hostnamectl</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
<arg choice="req">COMMAND</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
man/hostnamectl,hostaned,hostname1: adjust the docs to match reality The semantics were significantly changed in c779a44222161155c039a7fd2fd304c006590ac7 ("hostnamed: Fix the way that static and transient host names interact", Feb. 2014), but when the dbus api documentation was imported much later, it wasn't properly adjusted to describe those new semantics. 34293dfafd2a81d80727938199769906dab321bd which added systemd.hostname= also added new behaviour. Let's ove various bits and pieces around so that they are in more appropriate places. Drop recommendations to set the hostname for DHCP or mDNS purposes. Nowadays we expect tools that want to expose some different hostname to the outside to manage that internally without affecting visible state. Also drop mentions of DHCP or mDNS directly setting the hostname, since nowadays network management software is expected to (and does) go through hostnamed. Also, add a high-level description of semantics. It glosses over the details of handling of localhost-style names. Later commits will remove this special handling anyway.
2020-12-04 17:16:24 +03:00
<para><command>hostnamectl</command> may be used to query and change the system hostname and related
settings.</para>
<para><citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
and this tool distinguish three different hostnames: the high-level "pretty" hostname which might include
all kinds of special characters (e.g. "Lennart's Laptop"), the "static" hostname which is the
user-configured hostname (e.g. "lennarts-laptop"), and the transient hostname which is a fallback value
hostnamed: stop discriminating against "localhost" in /etc/hostname We would sometimes ignore localhost-style names in /etc/hostname. That is brittle. If the user configured some hostname, it's most likely because they want to use that as the hostname. If they don't want to use such a hostname, they should just not create the config. Everything becomes simples if we just use the configured hostname as-is. This behaviour seems to have been a workaround for Anaconda installer and other tools writing out /etc/hostname with the default of "localhost.localdomain". Anaconda PR to stop doing that: https://github.com/rhinstaller/anaconda/pull/3040. That might have been useful as a work-around for other programs misbehaving if /etc/hostname was not present, but nowadays it's not useful because systemd mostly controls the hostname and it is perfectly happy without that file. Apart from making things simpler, this allows users to set a hostname like "localhost" and have it honoured, if such a whim strikes them.
2020-12-04 21:56:49 +03:00
received from network configuration (e.g. "node12345678"). If a static hostname is set to a valid value,
then the transient hostname is not used.</para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
man: document that static/transient hostnames may be 64 chars at max
2016-08-19 12:02:24 +03:00
<para>Note that the pretty hostname has little restrictions on the characters and length used, while the static and
transient hostnames are limited to the usually accepted characters of Internet domain names, and 64 characters at
maximum (the latter being a Linux limitation).</para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<para>Use
man/hostnamectl,hostaned,hostname1: adjust the docs to match reality The semantics were significantly changed in c779a44222161155c039a7fd2fd304c006590ac7 ("hostnamed: Fix the way that static and transient host names interact", Feb. 2014), but when the dbus api documentation was imported much later, it wasn't properly adjusted to describe those new semantics. 34293dfafd2a81d80727938199769906dab321bd which added systemd.hostname= also added new behaviour. Let's ove various bits and pieces around so that they are in more appropriate places. Drop recommendations to set the hostname for DHCP or mDNS purposes. Nowadays we expect tools that want to expose some different hostname to the outside to manage that internally without affecting visible state. Also drop mentions of DHCP or mDNS directly setting the hostname, since nowadays network management software is expected to (and does) go through hostnamed. Also, add a high-level description of semantics. It glosses over the details of handling of localhost-style names. Later commits will remove this special handling anyway.
2020-12-04 17:16:24 +03:00
<citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> to
initialize the system hostname for mounted (but not booted) system images.</para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</refsect1>
man: mention that 'status' is the default command for `hostnamectl`
2018-03-14 08:06:50 +03:00
<refsect1>
<title>Commands</title>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<para>The following commands are understood:</para>
<variablelist>
<varlistentry>
<term><command>status</command></term>
hostnamectl: deprecate set-* methods and expose getters by only using nouns in commands
2021-04-23 21:41:45 +03:00
<listitem><para>Show system hostname and related information. If no command is specified,
man: update version information As I noticed a lot of missing information when trying to implement checking for missing info. I reimplemented the version information script to be more robust, and here is the result. Follow up to ec07c3c80b2b1bfa6788500202006ff85f5ae4f4
2023-09-18 18:03:38 +03:00
this is the implied default.</para>
<xi:include href="version-info.xml" xpointer="v195"/></listitem>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</varlistentry>
<varlistentry>
hostnamectl: deprecate set-* methods and expose getters by only using nouns in commands
2021-04-23 21:41:45 +03:00
<term><command>hostname</command> [<replaceable>NAME</replaceable>]</term>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
hostnamectl: deprecate set-* methods and expose getters by only using nouns in commands
2021-04-23 21:41:45 +03:00
<listitem><para>If no argument is given, print the system hostname. If an
optional argument <replaceable>NAME</replaceable> is provided then the command changes the
system hostname to <replaceable>NAME</replaceable>. By default, this will alter the
man: don't claim we replace spaces by dashes when cleaning up hostnames Let's make sure the man page actually documents what is implemented, i.e. "Lennart's PC" turns into "LennartsPC" when we clean up the name.
2016-08-19 12:02:55 +03:00
pretty, the static, and the transient hostname alike; however, if one or more of <option>--static</option>,
<option>--transient</option>, <option>--pretty</option> are used, only the selected hostnames are changed. If
the pretty hostname is being set, and static or transient are being set as well, the specified hostname will be
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
tree-wide: use "hostname" spelling everywhere It's not that I think that "hostname" is vastly superior to "host name". Quite the opposite — the difference is small, and in some context the two-word version does fit better. But in the tree, there are ~200 occurrences of the first, and >1600 of the other, and consistent spelling is more important than any particular spelling choice.
2020-04-14 11:37:40 +03:00
if only the transient and/or static hostnames are set, and the pretty hostname is left untouched.</para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
man: say that hostname must can be a fqdn or not Fixes #18426
2021-02-25 16:14:39 +03:00
<para>The static and transient hostnames must each be either a single DNS label (a string composed of
7-bit ASCII lower-case characters and no spaces or dots, limited to the format allowed for DNS domain
name labels), or a sequence of such labels separated by single dots that forms a valid DNS FQDN. The
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
hostname must be at most 64 characters, which is a Linux limitation (DNS allows longer names).</para>
<xi:include href="version-info.xml" xpointer="v249"/></listitem>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</varlistentry>
<varlistentry>
hostnamectl: deprecate set-* methods and expose getters by only using nouns in commands
2021-04-23 21:41:45 +03:00
<term><command>icon-name</command> [<replaceable>NAME</replaceable>]</term>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
hostnamectl: deprecate set-* methods and expose getters by only using nouns in commands
2021-04-23 21:41:45 +03:00
<listitem><para>If no argument is given, print the icon name of the system. If an
optional argument <replaceable>NAME</replaceable> is provided then the command changes the
icon name to <replaceable>NAME</replaceable>. The icon name is used by some
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
graphical applications to visualize this host. The icon name
should follow the <ulink
Use https for freedesktop.org grep -l -r http:// | xargs sed -E -i s'#http://(.*).freedesktop.org#https://\1.freedesktop.org#'
2022-06-28 13:00:47 +03:00
url="https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">Icon
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
Naming Specification</ulink>.</para>
<xi:include href="version-info.xml" xpointer="v249"/></listitem>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</varlistentry>
<varlistentry>
hostnamectl: deprecate set-* methods and expose getters by only using nouns in commands
2021-04-23 21:41:45 +03:00
<term><command>chassis</command> [<replaceable>TYPE</replaceable>]</term>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
hostnamectl: deprecate set-* methods and expose getters by only using nouns in commands
2021-04-23 21:41:45 +03:00
<listitem><para>If no argument is given, print the chassis type. If an
optional argument <replaceable>TYPE</replaceable> is provided then the command changes the
chassis type to <replaceable>TYPE</replaceable>. The chassis type is used by
some graphical applications to visualize the host or alter user interaction.
Currently, the following chassis types are defined:
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<literal>desktop</literal>,
<literal>laptop</literal>,
hostname: add 'convertible' chassis type Add the 'convertible' type to the set of allowed chassis. This applies to all devices that can be transformed by the user from laptop style to tablet style. This does not add any auto-detection, yet. It only makes 'set-chassis' accept 'convertible' as valid input.
2017-02-28 13:54:52 +03:00
<literal>convertible</literal>,
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<literal>server</literal>,
<literal>tablet</literal>,
<literal>handset</literal>,
<literal>watch</literal>,
<literal>embedded</literal>,
as well as the special chassis types
<literal>vm</literal> and
<literal>container</literal> for virtualized systems that lack
an immediate physical chassis.</para>
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
<xi:include href="version-info.xml" xpointer="v249"/>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</listitem>
</varlistentry>
<varlistentry>
hostnamectl: deprecate set-* methods and expose getters by only using nouns in commands
2021-04-23 21:41:45 +03:00
<term><command>deployment</command> [<replaceable>ENVIRONMENT</replaceable>]</term>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
hostnamectl: deprecate set-* methods and expose getters by only using nouns in commands
2021-04-23 21:41:45 +03:00
<listitem><para>If no argument is given, print the deployment environment. If an
optional argument <replaceable>ENVIRONMENT</replaceable> is provided then the command changes the
deployment environment to <replaceable>ENVIRONMENT</replaceable>.
Argument <replaceable>ENVIRONMENT</replaceable>
must be a single word without any control characters. One of the following is suggested:
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<literal>development</literal>,
<literal>integration</literal>,
<literal>staging</literal>,
<literal>production</literal>.
</para>
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
<xi:include href="version-info.xml" xpointer="v249"/>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</listitem>
</varlistentry>
<varlistentry>
hostnamectl: deprecate set-* methods and expose getters by only using nouns in commands
2021-04-23 21:41:45 +03:00
<term><command>location</command> [<replaceable>LOCATION</replaceable>]</term>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
hostnamectl: deprecate set-* methods and expose getters by only using nouns in commands
2021-04-23 21:41:45 +03:00
<listitem><para>If no argument is given, print the location string for the system. If an
optional argument <replaceable>LOCATION</replaceable> is provided then the command changes the
location string for the system to <replaceable>LOCATION</replaceable>.
Argument <replaceable>LOCATION</replaceable> should be a
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
human-friendly, free-form string describing the physical
location of the system, if it is known and applicable. This
may be as generic as <literal>Berlin, Germany</literal> or as
specific as <literal>Left Rack, 2nd Shelf</literal>.</para>
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
<xi:include href="version-info.xml" xpointer="v249"/>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</listitem>
</varlistentry>
</variablelist>
</refsect1>
Move the Commands section above Options section For executables which take a verb, we should list the verbs first, and then options which modify those verbs second. The general layout of the man page is from general description to specific details, usually Overview, Commands, Options, Return Value, Examples, References.
2019-10-08 18:58:44 +03:00
<refsect1>
<title>Options</title>
<para>The following options are understood:</para>
<variablelist>
<varlistentry>
<term><option>--no-ask-password</option></term>
<listitem><para>Do not query the user for authentication for
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
privileged operations.</para>
<xi:include href="version-info.xml" xpointer="v195"/></listitem>
Move the Commands section above Options section For executables which take a verb, we should list the verbs first, and then options which modify those verbs second. The general layout of the man page is from general description to specific details, usually Overview, Commands, Options, Return Value, Examples, References.
2019-10-08 18:58:44 +03:00
</varlistentry>
<varlistentry>
<term><option>--static</option></term>
<term><option>--transient</option></term>
<term><option>--pretty</option></term>
<listitem><para>If <command>status</command> is invoked (or no explicit command is given) and one of these
switches is specified, <command>hostnamectl</command> will print out just this selected hostname.</para>
Update hostnamectl.xml set-hostname is obsolete
2022-11-15 19:11:36 +03:00
<para>If used with <command>hostname</command>, only the selected hostnames will be updated. When more
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
than one of these switches are specified, all the specified hostnames will be updated. </para>
<xi:include href="version-info.xml" xpointer="v195"/></listitem>
Move the Commands section above Options section For executables which take a verb, we should list the verbs first, and then options which modify those verbs second. The general layout of the man page is from general description to specific details, usually Overview, Commands, Options, Return Value, Examples, References.
2019-10-08 18:58:44 +03:00
</varlistentry>
<xi:include href="user-system-options.xml" xpointer="host" />
<xi:include href="user-system-options.xml" xpointer="machine" />
<xi:include href="standard-options.xml" xpointer="help" />
<xi:include href="standard-options.xml" xpointer="version" />
hostnamectl: add --json= switch for JSON output This wraps the new Describe() bus call of hostnamed.
2021-04-29 12:29:46 +03:00
<xi:include href="standard-options.xml" xpointer="json" />
hostnamectl: add -j switch for quick json output We already support -j as shortcut for JSON mode in various tools. Let's add one more. We probably should add this systematically (at least where it doesn't conflict with an existing -j switch with other purpose). But I am too lazy to add that now.
2024-01-19 17:49:33 +03:00
<xi:include href="standard-options.xml" xpointer="j" />
Move the Commands section above Options section For executables which take a verb, we should list the verbs first, and then options which modify those verbs second. The general layout of the man page is from general description to specific details, usually Overview, Commands, Options, Return Value, Examples, References.
2019-10-08 18:58:44 +03:00
</variablelist>
</refsect1>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<refsect1>
<title>Exit status</title>
<para>On success, 0 is returned, a non-zero failure code
otherwise.</para>
</refsect1>
<refsect1>
<title>See Also</title>
man: use <simplelist> for 'See also' sections This is just a slight markup improvement; there should be no difference in rendering.
2023-12-22 21:09:32 +03:00
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
</simplelist></para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</refsect1>
hostname: add new hostnamectl tool as text client for hostnamed
2012-10-17 23:23:30 +04:00
</refentry>
Copy Permalink