From a3036d974c8c25eda6c50e6f997c826d4b8cea02 Mon Sep 17 00:00:00 2001 From: Sebastian Wagner Date: Thu, 18 Feb 2021 15:20:59 +0100 Subject: [PATCH] doc/cephadm: Move FQDN chapter to host mgmt.rst Signed-off-by: Sebastian Wagner --- doc/cephadm/concepts.rst | 68 -------------------------------- doc/cephadm/host-management.rst | 69 +++++++++++++++++++++++++++++++++ 2 files changed, 69 insertions(+), 68 deletions(-) diff --git a/doc/cephadm/concepts.rst b/doc/cephadm/concepts.rst index 3f98757416bd8..1cb40d74e3a04 100644 --- a/doc/cephadm/concepts.rst +++ b/doc/cephadm/concepts.rst @@ -1,74 +1,6 @@ Cephadm Concepts ================ -.. _cephadm-fqdn: - -Fully qualified domain names vs bare host names ------------------------------------------------ - -cephadm has very minimal requirements when it comes to resolving host -names etc. When cephadm initiates an ssh connection to a remote host, -the host name can be resolved in four different ways: - -- a custom ssh config resolving the name to an IP -- via an externally maintained ``/etc/hosts`` -- via explicitly providing an IP address to cephadm: ``ceph orch host add `` -- automatic name resolution via DNS. - -Ceph itself uses the command ``hostname`` to determine the name of the -current host. - -.. note:: - - cephadm demands that the name of the host given via ``ceph orch host add`` - equals the output of ``hostname`` on remote hosts. - -Otherwise cephadm can't be sure, the host names returned by -``ceph * metadata`` match the hosts known to cephadm. This might result -in a :ref:`cephadm-stray-host` warning. - -When configuring new hosts, there are two **valid** ways to set the -``hostname`` of a host: - -1. Using the bare host name. In this case: - -- ``hostname`` returns the bare host name. -- ``hostname -f`` returns the FQDN. - -2. Using the fully qualified domain name as the host name. In this case: - -- ``hostname`` returns the FQDN -- ``hostname -s`` return the bare host name - -Note that ``man hostname`` recommends ``hostname`` to return the bare -host name: - - The FQDN (Fully Qualified Domain Name) of the system is the - name that the resolver(3) returns for the host name, such as, - ursula.example.com. It is usually the hostname followed by the DNS - domain name (the part after the first dot). You can check the FQDN - using ``hostname --fqdn`` or the domain name using ``dnsdomainname``. - - .. code-block:: none - - You cannot change the FQDN with hostname or dnsdomainname. - - The recommended method of setting the FQDN is to make the hostname - be an alias for the fully qualified name using /etc/hosts, DNS, or - NIS. For example, if the hostname was "ursula", one might have - a line in /etc/hosts which reads - - 127.0.1.1 ursula.example.com ursula - -Which means, ``man hostname`` recommends ``hostname`` to return the bare -host name. This in turn means that Ceph will return the bare host names -when executing ``ceph * metadata``. This in turn means cephadm also -requires the bare host name when adding a host to the cluster: -``ceph orch host add ``. - -.. - TODO: This chapter needs to provide way for users to configure - Grafana in the dashboard, as this is right no very hard to do. Cephadm Scheduler ----------------- diff --git a/doc/cephadm/host-management.rst b/doc/cephadm/host-management.rst index 6f40bfb219660..e1dbd51004969 100644 --- a/doc/cephadm/host-management.rst +++ b/doc/cephadm/host-management.rst @@ -218,3 +218,72 @@ There are two ways to customize this configuration for your environment: manually distributed to the mgr data directory (``/var/lib/ceph//mgr.`` on the host, visible at ``/var/lib/ceph/mgr/ceph-`` from inside the container). + +.. _cephadm-fqdn: + +Fully qualified domain names vs bare host names +=============================================== + +cephadm has very minimal requirements when it comes to resolving host +names etc. When cephadm initiates an ssh connection to a remote host, +the host name can be resolved in four different ways: + +- a custom ssh config resolving the name to an IP +- via an externally maintained ``/etc/hosts`` +- via explicitly providing an IP address to cephadm: ``ceph orch host add `` +- automatic name resolution via DNS. + +Ceph itself uses the command ``hostname`` to determine the name of the +current host. + +.. note:: + + cephadm demands that the name of the host given via ``ceph orch host add`` + equals the output of ``hostname`` on remote hosts. + +Otherwise cephadm can't be sure, the host names returned by +``ceph * metadata`` match the hosts known to cephadm. This might result +in a :ref:`cephadm-stray-host` warning. + +When configuring new hosts, there are two **valid** ways to set the +``hostname`` of a host: + +1. Using the bare host name. In this case: + +- ``hostname`` returns the bare host name. +- ``hostname -f`` returns the FQDN. + +2. Using the fully qualified domain name as the host name. In this case: + +- ``hostname`` returns the FQDN +- ``hostname -s`` return the bare host name + +Note that ``man hostname`` recommends ``hostname`` to return the bare +host name: + + The FQDN (Fully Qualified Domain Name) of the system is the + name that the resolver(3) returns for the host name, such as, + ursula.example.com. It is usually the hostname followed by the DNS + domain name (the part after the first dot). You can check the FQDN + using ``hostname --fqdn`` or the domain name using ``dnsdomainname``. + + .. code-block:: none + + You cannot change the FQDN with hostname or dnsdomainname. + + The recommended method of setting the FQDN is to make the hostname + be an alias for the fully qualified name using /etc/hosts, DNS, or + NIS. For example, if the hostname was "ursula", one might have + a line in /etc/hosts which reads + + 127.0.1.1 ursula.example.com ursula + +Which means, ``man hostname`` recommends ``hostname`` to return the bare +host name. This in turn means that Ceph will return the bare host names +when executing ``ceph * metadata``. This in turn means cephadm also +requires the bare host name when adding a host to the cluster: +``ceph orch host add ``. + +.. + TODO: This chapter needs to provide way for users to configure + Grafana in the dashboard, as this is right no very hard to do. -- 2.39.5