Changer durablement le nom d'hôte sous Linux : hostnamectl, /etc/hosts et cloud-init

Un serveur qui s'appelle debian, localhost ou vm-01 fonctionne parfaitement. Les choses ne se gâtent que lorsque trois machines de ce genre tournent en même temps, lorsque les lignes de journal ne se distinguent plus les unes des autres, ou lorsque le premier serveur de messagerie entre en jeu et que le serveur d'en face vérifie le nom. Ce guide modifie le nom d'hôte de telle sorte qu'il survive au prochain redémarrage, que sudo ne parte pas dans un timeout et que les services qui le lisent au démarrage le connaissent eux aussi.

Ce texte approfondit l'étape 6 de la checklist pour un nouveau serveur root. Vous y trouvez les deux commandes qui suffisent la plupart du temps. Ici, vous découvrez ce qui se passe derrière, et ce que vous devez faire lorsqu'elles ne suffisent pas.

Toutes les indications se rapportent à Debian 13 (trixie), Debian 12 (bookworm), Ubuntu 24.04 LTS et Ubuntu 22.04 LTS. Les commandes sont écrites pour une exécution en tant que root. Avec un compte utilisateur normal, faites précéder chaque commande de sudo.

Un serveur porte trois noms, pas un seul

La cause la plus fréquente d'un renommage à moitié réussi tient à ceci : Linux ne connaît pas un nom d'hôte, mais trois. Ils résident à des endroits différents et sont écrasés par des instances différentes.

Le nom transitoire est tenu par le noyau, et c'est celui que chaque programme reçoit via gethostname(). Le nom statique est le modèle à partir duquel il est défini au démarrage. Le nom descriptif a le droit de contenir des espaces et des caractères accentués, et il n'apparaît que dans les interfaces, jamais sur le réseau.

La deuxième distinction est tout aussi importante : quelle commande tire sa réponse de quelle source. Supposons que /etc/hostname contienne srv01 et que /etc/hosts contienne la ligne 127.0.1.1 srv01.example.com srv01, vous obtenez alors le tableau suivant.

La ligne décisive est hostname -f. Cette commande ne lit pas /etc/hostname : elle prend le nom du noyau et le fait passer par la résolution de noms. Le nom complet provient donc de /etc/hosts ou du DNS, jamais du fichier de nom d'hôte. Presque tous les problèmes décrits dans cet article remontent à ce malentendu.

Avant la première modification : le chemin du retour

Un renommage à lui seul ne coupe pas votre session SSH. C'est l'étape suivante qui est dangereuse : la modification de /etc/hosts. Si la ligne pour localhost y disparaît, des dizaines de programmes attendent dans des timeouts, Postfix ne démarre plus et sudo a besoin de plusieurs secondes par appel. Réglez donc trois points au préalable.

1. Une deuxième session reste ouverte

Ouvrez une deuxième fenêtre de terminal avec une connexion active et ne la fermez pas avant que tout soit vérifié. Une session déjà établie survit à n'importe quelle modification du nom d'hôte et de la résolution de noms. Si l'établissement de la connexion lui-même n'est pas encore au point, consultez Se connecter au serveur en SSH.

2. La voie qui contourne SSH

Les serveurs root KVM et les serveurs dédiés de KernelHost n'ont ni IPMI ni iDRAC. L'accès qui fonctionne encore lorsque plus rien ne répond dans le système invité, c'est la console VNC dans l'espace client. Elle est rattachée à la couche de virtualisation ou au raccordement lui-même, indépendamment de la résolution de noms du système invité. Connectez-vous-y une fois avant de commencer et assurez-vous de connaître le mot de passe root. Une voie de secours que l'on essaie pour la première fois en pleine urgence n'en est pas une.

3. Deux copies et un retour en arrière

cp -a /etc/hostname /root/hostname.bak
cp -a /etc/hosts /root/hosts.bak
hostnamectl > /root/hostnamectl-avant.txt

Le chemin du retour tient alors en deux lignes, que vous pouvez taper au besoin via la console :

cp -a /root/hosts.bak /etc/hosts
hostnamectl set-hostname "$(cat /root/hostname.bak)"

État des lieux en cinq commandes

Regardez d'abord ce qui s'applique en ce moment et qui a son mot à dire.

hostnamectl
cat /etc/hostname
cat /etc/hosts
grep '^hosts:' /etc/nsswitch.conf
command -v cloud-init >/dev/null && cloud-init status --long || echo "cloud-init n'est pas installé"

La sortie de hostnamectl mérite un examen attentif. Elle commence normalement par Static hostname:. Si une ligne Transient hostname: apparaît en plus, le nom statique et le nom en cours d'exécution divergent, et quelque chose modifie le nom activement : presque toujours cloud-init ou un client DHCP. Cela doit être désactivé en premier, sinon votre modification aura de nouveau disparu après le prochain redémarrage.

La ligne hosts: de /etc/nsswitch.conf fixe l'ordre de la résolution de noms. Les quatre entrées que l'on y rencontre signifient ceci :

• files : /etc/hosts est lu.
• dns : le résolveur interroge les serveurs de noms indiqués dans /etc/resolv.conf.
• resolve : la requête part vers systemd-resolved.
• myhostname : un module de systemd qui fait correspondre le nom de la machine aux adresses IP configurées localement, même sans entrée dans /etc/hosts.

Le dernier point explique, plus bas dans cet article, pourquoi la même erreur passe inaperçue pendant des années sur certains serveurs.

Choisir le nom : FQDN ou nom court

Sont autorisés les lettres, les chiffres et le trait d'union. Pas de tiret bas, pas de point au début ni à la fin, pas de trait d'union au début d'un label. Écrivez en minuscules : le DNS compare sans tenir compte de la casse, alors que beaucoup de programmes comparent littéralement. Un label (la portion comprise entre deux points) peut compter 63 caractères, le nom complet dans le DNS 253. Le noyau, lui, n'accepte que 64 caractères au maximum pour le nom d'hôte : un FQDN très long risque donc de ne pas y tenir du tout. Choisissez le nom sous un domaine qui vous appartient : .local est réservé au mDNS, et des terminaisons inventées comme .lan peuvent devenir à tout moment de véritables domaines de premier niveau.

Reste la question de ce qui figure dans /etc/hostname. Les deux variantes fonctionnent, elles se distinguent par ce qui vous sera affiché ensuite un peu partout.

Sous Debian et Ubuntu, la première variante est recommandée : le nom court dans /etc/hostname, le nom complet comme première entrée dans /etc/hosts. L'invite de commande et les lignes de journal restent ainsi courtes, et le FQDN est malgré tout correct. La seconde variante est tout aussi propre, tant qu'elle est tenue jusqu'au bout. La véritable erreur, c'est le mélange : un FQDN dans /etc/hostname et un autre dans /etc/hosts.

Créez de préférence dès maintenant l'enregistrement A (ou l'enregistrement AAAA en IPv6) pour le nouveau nom. Il ne coûte rien, il rend hostname -f correct même sans /etc/hosts, et il est la condition préalable à tout certificat portant ce nom.

Dompter cloud-init avant de définir quoi que ce soit

Sur les images équipées de cloud-init, et c'est le cas de pratiquement toutes celles d'Ubuntu, le nom d'hôte est défini au démarrage à partir des métadonnées de l'instance. Les modules concernés sont set_hostname et update_hostname, auxquels s'ajoute update_etc_hosts pour le fichier /etc/hosts. Tous les trois s'exécutent tôt, avant même le démarrage de vos propres services. Deux réglages pilotent cela :

grep -rE '^(preserve_hostname|manage_etc_hosts)' /etc/cloud/cloud.cfg /etc/cloud/cloud.cfg.d/ 2>/dev/null

Sur les images serveur d'Ubuntu, /etc/cloud/cloud.cfg contient la ligne preserve_hostname: false : cloud-init a donc le droit de toucher au nom. Le réglage inverse n'a pas sa place dans ce fichier, parce qu'une mise à jour de paquet le remplacerait, mais dans /etc/cloud/cloud.cfg.d/. Les fichiers de ce répertoire sont lus par ordre alphabétique et le dernier l'emporte, d'où le 99 :

mkdir -p /etc/cloud/cloud.cfg.d
printf 'preserve_hostname: true\n' > /etc/cloud/cloud.cfg.d/99_hostname.cfg

Le second réglage concerne /etc/hosts. On l'oublie volontiers, alors qu'il fait plus de dégâts.

Si la valeur y est true et que vous avez besoin de vos propres entrées, passez la valeur à localhost ou maintenez plutôt le modèle (sous Debian et Ubuntu hosts.debian.tmpl). Modifier à la main un fichier qui est écrasé à chaque démarrage produit exactement le genre d'erreur que l'on ne remarque que des semaines plus tard.

Ce que cloud-init a défini en dernier, il le mémorise sous /var/lib/cloud/data/. C'est cet état qu'efface cloud-init clean. Ne faites surtout pas cela sur un serveur déjà configuré : au démarrage suivant, tous les modules repartent comme si la machine était neuve.

Le deuxième à réécrire le nom : DHCP

Si le serveur obtient son adresse par DHCP, le client peut reprendre le nom d'hôte transitoire contenu dans la réponse (option 12). Le nom statique reste intact, ce qui complique le diagnostic : hostnamectl --static affiche votre nom, hostname en affiche un autre. Sous netplan, vous désactivez cela ainsi :

network:
  version: 2
  ethernets:
    eth0:
      dhcp4: true
      dhcp4-overrides:
        use-hostname: false

Activez avec netplan try plutôt qu'avec netplan apply : try annule la modification de lui-même au bout de 120 secondes si vous ne confirmez pas. Avec systemd-networkd configuré directement, le réglage s'appelle UseHostname=no dans la section [DHCPv4].

Définir le nom d'hôte

hostnamectl set-hostname srv01

Sans autre option, hostnamectl définit conjointement le nom statique et le nom transitoire. C'est exactement ce que vous voulez. Avec --static, vous ne modifiez que /etc/hostname, et si un nom transitoire est actif, la machine continuerait de tourner sous l'ancien jusqu'au redémarrage. Les versions récentes de systemd connaissent en plus la forme courte hostnamectl hostname srv01, tandis que set-hostname fonctionne sur les quatre systèmes.

Contrôle de réussite : les deux noms doivent concorder et le fichier doit porter le nouveau contenu.

hostnamectl --static
hostnamectl --transient
cat /etc/hostname

Deux remarques en marge. Premièrement, hostname srv01 sans ctl ne modifie que le nom transitoire et il aura disparu après le redémarrage. Deuxièmement, votre shell en cours continue d'afficher l'ancien nom dans l'invite, parce que bash lit le nom d'hôte une seule fois, au démarrage de la session. Ce n'est pas un échec, c'est une ancienne session. Reconnectez-vous.

Vous pouvez éventuellement enregistrer un nom descriptif, qui apparaît dans les interfaces et a le droit de contenir des espaces :

hostnamectl set-hostname --pretty "Serveur web Francfort"
cat /etc/machine-info

Écrire correctement /etc/hosts

hostnamectl ne touche pas à /etc/hosts. Ce fichier reste votre affaire, et c'est la raison pour laquelle un renommage n'a si souvent qu'un effet partiel.

Une ligne se compose d'une adresse IP, du nom canonique et d'un nombre quelconque d'alias. Le premier nom après l'adresse est le nom canonique, et c'est précisément lui que renvoie hostname -f. C'est pourquoi le nom complet vient devant et le nom court derrière, jamais l'inverse.

127.0.0.1       localhost
127.0.1.1       srv01.example.com srv01

::1             localhost ip6-localhost ip6-loopback
ff02::1         ip6-allnodes
ff02::2         ip6-allrouters

Pourquoi 127.0.1.1 et pas 127.0.0.1 : Debian et Ubuntu séparent délibérément le nom de la machine de localhost. Si vous accrochez le nom du serveur comme alias à la ligne localhost, le nom canonique de celle-ci reste localhost, et hostname -f répond localhost. Les programmes qui en déduisent leur propre nom inscrivent ensuite localhost dans les journaux et dans les en-têtes des e-mails.

Une entrée manquante s'ajoute à la fin, une ligne existante se modifie :

grep -n '^127\.0\.1\.1' /etc/hosts
printf '127.0.1.1\tsrv01.example.com\tsrv01\n' >> /etc/hosts

Si la première commande renvoie déjà une ligne, modifiez celle-ci au lieu d'en ajouter une seconde. Avec deux lignes pour la même adresse, c'est la première qui l'emporte, et vous modifieriez ensuite une ligne que plus personne ne lit.

Contrôle de réussite :

getent hosts srv01
getent hosts srv01.example.com
hostname -f
hostname -s

Les deux appels à getent doivent renvoyer chacun une ligne, hostname -f le nom complet et hostname -s le nom court. Si rien ne revient, l'entrée n'est pas active, par exemple parce que la ligne porte un caractère de commentaire.

Une décision reste à prendre : 127.0.1.1 ou l'adresse publique du serveur. Certains logiciels s'attachent à l'adresse sur laquelle leur propre nom se résout, ou bien l'inscrivent dans la liste des membres d'un cluster. Dans ce cas, le FQDN doit pointer sur l'adresse publique. Avec une adresse fixe, c'est la variante la plus propre, avec une adresse changeante c'est 127.0.1.1, parce qu'elle fonctionne aussi sans connexion réseau.

Pourquoi une entrée manquante ralentit sudo

sudo détermine à chaque appel le nom de la machine et le fait résoudre. Il en a besoin pour la ligne de journal et pour la comparaison avec les indications de machine figurant dans /etc/sudoers.

La résolution suit la ligne hosts: de /etc/nsswitch.conf. Si le nom figure dans /etc/hosts, l'affaire est réglée après un accès au fichier, donc en moins d'une milliseconde. S'il n'y figure pas, la requête passe à l'entrée suivante, en règle générale dns, et le résolveur interroge les serveurs de noms de /etc/resolv.conf au sujet d'un nom qui n'existe pas dans le DNS. Les valeurs par défaut de la glibc sont de cinq secondes de timeout et de deux tentatives par serveur de noms. Si personne ne répond, cela s'additionne, et ce à chaque appel.

Un facteur aggravant s'y ajoute : un nom court ne contient pas de point et se situe donc en dessous de la valeur par défaut ndots:1. Le résolveur commence par ajouter chaque domaine de recherche de /etc/resolv.conf et n'interroge le nom lui-même qu'ensuite. Deux domaines de recherche, cela fait trois séries de requêtes au lieu d'une.

Cela devient visible avec cet avertissement, placé en tête de chaque appel :

sudo: unable to resolve host srv01: Name or service not known

Mesurer plutôt qu'estimer :

time getent hosts "$(hostname)"
time sudo -n true

Les deux doivent rester bien en dessous d'un dixième de seconde. Tout ce qui dépasse est du temps d'attente sur un serveur de noms.

Et voici maintenant la raison pour laquelle l'erreur ne saute pas aux yeux partout : si la ligne hosts: contient l'entrée myhostname, ce module répond lui-même à la requête portant sur le nom de la machine, sans DNS et sans /etc/hosts. À cet endroit, l'avertissement n'apparaît pas, bien que le fichier soit incomplet. Dès que le même montage passe sur un système dépourvu de cette entrée, l'erreur est de retour.

Un second problème, plus rare, concerne l'attribution des droits : dans /etc/sudoers, chaque règle peut être limitée à certains noms de machine. Les règles livrées par Debian et Ubuntu utilisent ALL et ne posent pas de problème. Vos propres règles comportant un nom de machine perdent en revanche leur effet, et l'utilisateur concerné n'a ensuite plus le droit de rien faire. À vérifier avant :

grep -rhvE '^[[:space:]]*(#|$)' /etc/sudoers /etc/sudoers.d/

Les services qui lisent le nom au démarrage

Beaucoup de programmes interrogent le nom d'hôte exactement une fois, au démarrage, puis continuent de travailler avec l'ancien nom. Cela explique une bonne partie de la confusion qui suit un renommage.

• Le shell en cours. L'invite affiche l'ancien nom. Ouvrez une nouvelle session, et c'est réglé.
• rsyslog, là où il est installé. Un systemctl restart rsyslog suffit. Debian 12 et 13 n'embarquent pas rsyslog dans les installations minimales, c'est journald qui y écrit.
• Les entrées de journal déjà écrites conservent l'ancien nom, et c'est très bien ainsi. Si l'ancien nom apparaît en revanche dans de nouvelles entrées, redémarrez le service qui les écrit.
• MariaDB et MySQL dérivent du nom d'hôte les noms de fichiers par défaut, comme le journal d'erreurs et le journal binaire, tant que les chemins ne figurent pas explicitement dans la configuration.
• Les applications Java. InetAddress.getLocalHost() lève une java.net.UnknownHostException dès que le nom de la machine ne se résout pas. Les serveurs d'applications sont concernés au même titre que les serveurs de jeu.
• Les agents de supervision portent souvent le nom dans leur propre fichier de configuration. Sans quoi le même serveur apparaît deux fois après le renommage.

systemctl list-units --type=service --state=running

Si une fenêtre de maintenance est de toute façon prévue, un redémarrage est la solution la plus complète. Comment déclarer proprement vos propres programmes sous forme d'unit, afin qu'ils survivent à un redémarrage, c'est expliqué dans Créer un service systemd.

Serveur de messagerie : le nom que les autres voient

Pour l'envoi de courrier, le nom d'hôte n'est plus une question de cosmétique. Le serveur d'en face le voit dans le EHLO et le vérifie. Trois éléments doivent concorder :

1. Le nom sous lequel votre serveur de messagerie se présente (avec Postfix myhostname).
2. L'enregistrement PTR de votre adresse IP, c'est-à-dire la résolution inverse.
3. Un enregistrement A (un enregistrement AAAA en IPv6) pour exactement ce nom, qui pointe de nouveau vers la même adresse.

Si la chaîne ne se referme pas, beaucoup de destinataires déclassent le message ou le refusent. Vérification sans paquets supplémentaires :

hostname -f
getent hosts 203.0.113.10
getent hosts srv01.example.com

C'est plus précis avec dig, issu du paquet bind9-dnsutils :

apt install -y bind9-dnsutils
dig +short -x 203.0.113.10
dig +short srv01.example.com A

L'enregistrement PTR n'appartient pas au serveur. Il est rattaché à l'adresse IP et se gère chez l'exploitant du réseau, chez KernelHost via l'espace client. Aucun appel à hostnamectl n'y change quoi que ce soit, et c'est exactement là que les renommages tournent mal sur les serveurs de messagerie.

Postfix ne reprend pas le renommage de lui-même. Sous Debian et Ubuntu, le paquet écrit une valeur fixe dans /etc/postfix/main.cf lors de la configuration, et à côté se trouve /etc/mailname, qui contient le nom que Postfix utilise comme domaine d'expéditeur pour le courrier local. Les deux restent inchangés :

postconf myhostname mydomain myorigin
cat /etc/mailname

À adapter puis à redémarrer, sachant que /etc/mailname relève d'une décision distincte et ne porte pas obligatoirement la même valeur que myhostname :

postconf -e "myhostname = srv01.example.com"
postfix check
systemctl restart postfix

SPF, DKIM et DMARC dépendent en revanche du domaine d'expéditeur et non du nom d'hôte. Un renommage ne répare donc aucun problème de remise dont la cause se situe à cet endroit.

Certificats

Le nom du système ne figure dans aucun certificat, car un certificat couvre les noms DNS qui figuraient dans la demande. Un renommage se répercute malgré tout à trois endroits.

Premièrement, sur la demande. Si vous obtenez un certificat sur le nom du serveur lui-même, par exemple pour le serveur de messagerie, ce nom doit exister dans le DNS avant que l'autorité de certification n'aille vérifier. Sinon, l'exécution se termine par un message du type DNS problem: NXDOMAIN looking up A for srv01.example.com. L'enregistrement A vient avant la demande, pas après.

Deuxièmement, sur les certificats existants. Ils continuent de tourner sur les anciens noms et continuent d'être renouvelés jusqu'à ce que vous les supprimiez :

certbot certificates
certbot delete --cert-name alt.example.com

Ne supprimez qu'une fois qu'aucun service ne pointe plus vers le chemin, sinon le serveur web ne démarrera plus au prochain rechargement.

Troisièmement, sur le serveur de messagerie. Si Postfix se présente avec le nouveau nom mais propose un certificat pour l'ancien, les serveurs d'en face qui vérifient le nom strictement échouent. Le certificat et myhostname doivent porter le même nom.

Il n'existe aucun lien entre le nom du système et server_name dans nginx. nginx décide d'après l'en-tête Host de la requête, pas d'après le nom de la machine. Si vous obtenez la mauvaise page après un renommage, cherchez dans la configuration du serveur, pas du côté du nom d'hôte. Les bases sur ce sujet dans Installer nginx sur Debian et Ubuntu.

Erreurs fréquentes et solutions

sudo: unable to resolve host srv01: Name or service not known
Le nom de la machine ne figure pas dans /etc/hosts et il est inconnu du DNS. Ajoutez la ligne 127.0.1.1 srv01.example.com srv01. Tant qu'elle manque, chaque appel attend un timeout du résolveur.

hostname: Name or service not known
La réponse de hostname -f lorsque le nom du noyau ne peut être résolu nulle part. Même cause, même solution. Vérifiez ensuite avec getent hosts "$(hostname)" que quelque chose revient réellement.

Could not set property: Access denied
hostnamectl a été appelé sans les droits root, ou bien l'appel a eu lieu dans un conteneur (container) qui n'a pas le droit de modifier le nom du noyau. Sur un serveur qui vous appartient, sudo règle le problème. Dans un conteneur non privilégié, vous définissez le nom dans la configuration de celui-ci, pas à l'intérieur.

fatal: unable to use my own hostname
Issu du journal de Postfix. La valeur de myhostname ne se résout pas. Ajoutez l'entrée dans /etc/hosts, puis systemctl restart postfix.

504 5.5.2 <srv01>: Helo command rejected: need fully-qualified hostname
Votre serveur de messagerie se présente avec le nom court, le serveur d'en face exige un nom complet. Passez myhostname sur le FQDN et redémarrez Postfix.

450 4.7.1 Client host rejected: cannot find your reverse hostname
Aucun enregistrement PTR n'existe pour votre adresse IP, ou bien il pointe dans le vide. Cela ne se corrige pas sur le serveur, mais uniquement chez l'exploitant du réseau IP.

java.net.UnknownHostException: srv01
Une application Java a voulu résoudre son propre nom et a échoué. Encore /etc/hosts. Une fois l'entrée ajoutée, l'application doit être redémarrée.

DNS problem: NXDOMAIN looking up A for srv01.example.com
Le nouveau nom n'existe pas encore dans le DNS. Créez l'enregistrement A, attendez la propagation, relancez la demande.

Le nom est redevenu l'ancien après le redémarrage.
À vérifier dans cet ordre : preserve_hostname: true est-il défini sous /etc/cloud/cloud.cfg.d/, le client DHCP ne fournit-il plus de nom, /etc/hostname contient-il réellement le nouveau nom. Si hostnamectl affiche une ligne Transient hostname: après le démarrage, l'une de ces sources agit encore.

/etc/hosts est de nouveau vidé après chaque redémarrage.
manage_etc_hosts: true est défini, cloud-init recrée le fichier à partir du modèle. Passez sur localhost ou maintenez le modèle.

Différences entre distributions

Identique sur les quatre systèmes : hostnamectl ne modifie jamais /etc/hosts, et aucun outil du système d'exploitation ne crée d'enregistrement DNS ou PTR. Ces deux étapes restent du travail manuel.

Le contrôle final

Une commande sans message d'erreur ne prouve rien. Le seul test qui tienne vraiment, c'est le redémarrage, puis ces cinq lignes :

hostnamectl --static
hostname -f
getent hosts "$(hostname)"
time sudo -n true
grep -c '^127\.0\.1\.1' /etc/hosts

Vous devez obtenir : le nouveau nom court, le nouveau nom complet, une ligne issue de /etc/hosts, un temps d'exécution nettement inférieur à un dixième de seconde et exactement une ligne pour 127.0.1.1. Ce n'est que lorsque les cinq résultats sont corrects que le renommage est terminé, et c'est seulement alors que vous avez le droit de fermer la deuxième fenêtre de terminal.