Connexions et become
Comment Volant atteint un hôte, les variables d'hôte et les paramètres d'ansible.cfg qu'il lit, et comment become fonctionne avec sudo et su.
Cette page répond à ces questions : comment Volant atteint vos hôtes, quelles variables contrôlent la connexion, et comment exécuter des tâches sous un autre utilisateur avec become.
Volant atteint un hôte géré, y dépose un petit agent statique (un programme qui exécute vos tâches et rend compte), puis lui parle sur la même connexion jusqu’à la fin de l’exécution.
Types de connexion
Section intitulée « Types de connexion »ansible_connection choisit le transport. Sa valeur par défaut est ssh, comme dans Ansible.
| Valeur | Ce qu’elle fait |
|---|---|
ssh |
Lance le client OpenSSH de votre PATH. Volant construit lui-même la ligne de commande, sans enveloppe et sans bibliothèque SSH en Rust : votre ~/.ssh/config s’applique donc. |
local |
Lance l’agent comme processus fils sur le contrôleur, sans réseau. |
docker |
Lance l’agent dans un conteneur en marche via docker exec -i, comme community.docker.docker. Voir Conteneurs Docker. |
podman |
Lance l’agent dans un conteneur Podman en marche via podman exec -i, rootless ou non, comme containers.podman.podman. Voir Conteneurs Podman. |
chroot |
Lance l’agent dans une arborescence du contrôleur via chroot, comme community.general.chroot. Voir Répertoires chroot. |
buildah |
Lance l’agent dans un conteneur de travail Buildah via buildah run, comme containers.podman.buildah. Voir Conteneurs de travail Buildah. |
lxd |
Lance l’agent dans une instance LXD via lxc exec, comme community.general.lxd ; community.general.incus fait de même pour Incus. Voir Instances LXD et Incus. |
kubectl |
Lance l’agent dans un conteneur d’un pod Kubernetes via kubectl exec, comme kubernetes.core.kubectl. Voir Pods Kubernetes. |
aws_ssm |
Lance l’agent sur une instance EC2 via une session AWS Systems Manager, comme amazon.aws.aws_ssm. Voir Sessions AWS Systems Manager. |
paramiko_ssh |
Lance le client OpenSSH à la place de la connexion paramiko, dépréciée dans ansible-core ; paramiko est la même. Voir Paramiko. |
Tout autre nom est résolu par l’ansible-core du contrôleur, comme ansible-playbook le résout, une fois par nom et par exécution. ansible.builtin.ssh et ansible.builtin.local se résolvent vers les deux plugins ci-dessus et s’exécutent. Un nom court qu’une collection a repris à ansible-core est routé vers cette collection quand elle est installée :
| Nom court | Se résout en | Collection dans le paquet ansible 12.3.0 |
|---|---|---|
docker |
community.docker.docker |
community.docker 4.8.5 |
podman |
containers.podman.podman |
containers.podman 1.18.0 |
buildah |
containers.podman.buildah |
containers.podman 1.18.0 |
kubectl |
kubernetes.core.kubectl |
kubernetes.core 6.2.0 |
lxd |
community.general.lxd |
community.general 11.4.2 |
chroot |
community.general.chroot |
community.general 11.4.2 |
aws_ssm |
community.aws.aws_ssm, que community.aws 10.0.0 renvoie vers amazon.aws.aws_ssm |
amazon.aws 10.1.2 |
incus |
pas de nom court : écrivez community.general.incus |
community.general 11.4.2 |
Avec -vvv, un nom routé affiche redirecting (type: connection) ansible.builtin.chroot to community.general.chroot sous la première tâche qui l’utilise sur un hôte, une ligne par étape.
Un nom qui se résout vers un plugin que Volant ne pilote pas lui-même, comme winrm, psrp, community.general.jail ou un plugin dans un répertoire connection_plugins/ à côté du playbook, prend la deuxième voie : voir Connexions que seul ansible-core possède. Sans l’ansible-core du contrôleur à interroger, un tel nom rend l’hôte injoignable avec connection '<full name>' is not supported, et le reste de l’exécution continue. La matrice de prise en charge liste tous les plugins de connexion des collections du paquet.
Un nom qui ne se résout vers rien fait échouer la tâche avec the connection plugin '<name>' was not found, comme dans Ansible. Cela comprend un nom court routé vers une collection qui n’est pas installée, comme docker sans community.docker, après l’avertissement qu’ansible-core affiche pour lui, et ansible.builtin.paramiko, qu’ansible-core 2.19.12 ne porte pas sous ce nom. Cela vaut que la valeur soit la connexion de l’hôte lui-même, celle d’une cible de delegate_to, ou celle de l’hôte qui exécute une tâche run_once.
Un mot de passe vient de -k, de --connection-password-file ou de la variable ansible_password. Volant le transmet à ssh par SSH_ASKPASS et un fichier temporaire privé supprimé à la fin de l’exécution, ce qui demande OpenSSH 8.4 ou plus récent. ssh s’exécute alors avec BatchMode=no et NumberOfPasswordPrompts=1 : une seule mauvaise réponse met fin à la tentative. Le mot de passe n’apparaît jamais dans une ligne de commande, dans l’environnement d’un programme ni dans la sortie, -vvvv compris. Un ansible_password chiffré avec vault fonctionne comme toute variable chiffrée. Sans mot de passe, ssh s’exécute avec BatchMode=yes et ne pose jamais de question : un hôte qui demanderait un mot de passe ou une phrase secrète est signalé injoignable au lieu de bloquer l’exécution.
Avec -vvv, le lien d’un hôte local affiche ESTABLISH LOCAL CONNECTION FOR USER: <user> et EXEC <the command line>. Ces lignes nomment la commande avec laquelle Volant démarre l’agent, une fois par lien, et log_verbosity les envoie au journal même quand elles ne sont pas affichées.
Conteneurs Docker
Section intitulée « Conteneurs Docker »ansible_connection: docker, ou community.docker.docker, exécute un play dans un conteneur en marche, sans sshd dedans ni chemin réseau jusqu’à lui. Les deux noms demandent community.docker installé sur le contrôleur, comme pour ansible-playbook. Volant lance le programme docker de votre PATH, si bien que DOCKER_HOST, DOCKER_CONTEXT et DOCKER_CONFIG l’atteignent par l’environnement.
L’agent monte par docker exec -i, donc l’image doit avoir /bin/sh et les outils habituels : uname, id, ls, mkdir, df, awk, head, wc, chmod, mv et find. Une image Alpine ou Debian minimale les a. Une image sans shell, comme distroless, reçoit l’agent par docker cp à la place : Volant demande à docker inspect l’architecture de l’image, copie l’agent dans le /tmp du conteneur, et l’agent se place lui-même dans son répertoire de cache, avec les mêmes contrôles. Le conteneur doit avoir un /tmp, remote_tmp doit être absolu ou commencer par ~ pour un utilisateur qui a un répertoire personnel, et become est refusé, faute de shell pour lancer sudo. La copie dans /tmp reste quand l’utilisateur du conteneur ne peut pas la supprimer.
| Variable | Rôle |
|---|---|
ansible_docker_host |
Le nom ou l’identifiant du conteneur. Elle l’emporte sur ansible_host, qui l’emporte sur le nom d’inventaire. |
ansible_docker_user |
L’utilisateur sous lequel les commandes s’exécutent, docker exec -u. Elle l’emporte sur ansible_user, le mot-clé remote_user et -u. Non définie, l’utilisateur du conteneur lui-même. |
ansible_docker_extra_args |
Des arguments placés après docker et avant exec, découpés sur les espaces simples et non comme des mots de shell. La valeur par défaut vient de [docker_connection] extra_cli_args. |
ansible_docker_extra_env |
Un dictionnaire de variables posées avec docker exec -e. Chaque valeur doit être du texte : un nombre ou un booléen sans guillemets est refusé. |
ansible_docker_privileged |
docker exec --privileged. La valeur par défaut vient de ANSIBLE_DOCKER_PRIVILEGED ou de [docker_connection] privileged. |
ansible_docker_working_dir |
docker exec -w. La valeur par défaut vient de ANSIBLE_DOCKER_WORKING_DIR ou de [docker_connection] working_dir. |
ansible_docker_timeout |
Les secondes que docker peut mettre à répondre à la première commande. La valeur par défaut vient de ANSIBLE_DOCKER_TIMEOUT, puis de [docker_connection] timeout, puis du délai de connexion. |
become avec sudo passe par le sudo du conteneur. su est refusé, parce que docker exec ne lui donne pas de terminal. Un conteneur qui n’existe pas ou qui est arrêté, ou un utilisateur que l’image n’a pas, rend l’hôte injoignable avec le message de docker lui-même. ansible-core signale ces trois cas comme Failed to create temporary directory : ce message diffère donc volontairement.
Avec -vvvv, les lignes affichent ESTABLISH DOCKER CONNECTION FOR USER: <user>, puis une ligne EXEC [...] par commande, qui sont les commandes propres à Volant. Quand le play ne nomme pas d’utilisateur, il vient de docker inspect : root quand l’image n’en nomme aucun, ? quand docker ne peut pas le dire.
Conteneurs Podman
Section intitulée « Conteneurs Podman »ansible_connection: podman, ou containers.podman.podman, exécute un play dans un conteneur Podman, rootless ou non, sans démon ni ssh. Les deux noms demandent containers.podman installé sur le contrôleur. L’agent monte comme pour docker : par podman exec -i quand l’image a un shell, par podman cp quand elle n’en a pas.
Volant lit les options comme les lit le code source du plugin, qui diffère de sa documentation. Le conteneur est ansible_host, sinon le nom d’inventaire ; le ansible_podman_host documenté n’est pas lu. L’utilisateur est ansible_user, le mot-clé remote_user ou -u, passé en podman exec --user.
| Variable | Rôle |
|---|---|
ansible_podman_executable |
Le programme podman, un nom cherché dans votre PATH ou un chemin. La valeur par défaut vient de ANSIBLE_PODMAN_EXECUTABLE. |
ansible_podman_extra_args |
Des arguments placés après podman et avant la sous-commande, découpés comme le ferait un shell. La valeur par défaut vient de ANSIBLE_PODMAN_EXTRA_ARGS ou de [defaults] podman_extra_args. |
Le plugin lance podman exec sans -i, il ne peut donc pas passer son stdin à une commande. L’agent en a besoin, alors Volant lance podman exec -i ; c’est le seul mot que ses lignes de commande ajoutent. Volant ne lance jamais podman mount. become avec sudo passe par le sudo du conteneur, et su est refusé. Avec -vvvv, chaque commande s’affiche en ligne RUN [...], comme le plugin l’écrit, sans ligne ESTABLISH.
Répertoires chroot
Section intitulée « Répertoires chroot »ansible_connection: chroot, ou community.general.chroot, exécute un play dans une arborescence du contrôleur : construction d’image, arbre debootstrap, dépannage. Le nom d’inventaire, ou ansible_host, est le répertoire. Les deux noms demandent community.general installé sur le contrôleur. L’exécution demande root, parce que chroot le demande.
| Variable | Rôle |
|---|---|
ansible_chroot_exe |
Le programme chroot, un nom cherché dans votre PATH ou un chemin absolu. La valeur par défaut vient de ANSIBLE_CHROOT_EXE ou de [chroot_connection] exe. |
ansible_chroot_disable_root_check |
Saute la vérification que le contrôleur tourne en root. La valeur par défaut vient de ANSIBLE_CHROOT_DISABLE_ROOT_CHECK ou de [chroot_connection] disable_root_check. |
ansible_executable |
Le shell sous lequel les commandes s’exécutent, /bin/sh par défaut. La valeur par défaut vient de ANSIBLE_EXECUTABLE ou de [defaults] executable. |
Avant que rien ne s’exécute, la tâche échoue, comme sous ansible-core, pour un chemin qui n’est pas un répertoire, pour une arborescence sans bin/sh, et pour un contrôleur qui n’est pas root sauf si la vérification est désactivée. L’agent monte par chroot <dir> /bin/sh, donc le script qui l’écrit tourne dans l’arborescence, et aucun chemin qu’il écrit ne peut en sortir, quels que soient les liens symboliques qu’elle contient. Quand df ne peut pas dire combien de place il reste, comme dans une arborescence sans /proc monté, la vérification d’espace est omise. become fonctionne quand l’arborescence a sudo. Avec -vvvv, les lignes affichent THIS IS A LOCAL CHROOT DIR, puis une ligne EXEC [...] par commande.
Conteneurs de travail Buildah
Section intitulée « Conteneurs de travail Buildah »ansible_connection: buildah, ou containers.podman.buildah, configure le conteneur de travail que crée buildah from <image>, pour qu’un play construise une image couche par couche, que buildah commit enregistre ensuite. Les deux noms demandent containers.podman installé sur le contrôleur. Comme pour podman, le conteneur est ansible_host, sinon le nom d’inventaire, et l’utilisateur est ansible_user, le mot-clé remote_user ou -u ; root n’ajoute aucune option. Le programme est le buildah de votre PATH, et les variables BUILDAH_* l’atteignent par l’environnement.
L’agent démarre par buildah run [--user U] <conteneur> -- <agent>. Volant ne lance jamais buildah mount, qui demande buildah unshare pour un utilisateur rootless : un conteneur de travail sans shell reçoit l’agent par buildah copy. buildah en rootless écrit des avertissements sur les capacités à chaque commande, donc le stderr de l’agent n’est pas affiché. Avec -vvvv, chaque commande s’affiche en ligne RUN [...], sans ligne ESTABLISH.
Instances LXD et Incus
Section intitulée « Instances LXD et Incus »ansible_connection: lxd, ou community.general.lxd, exécute un play dans une instance LXD, locale ou sur un serveur distant, via la commande lxc. community.general.incus fait de même pour Incus avec la commande incus ; il n’a pas de nom court dans ansible-core. Les deux demandent community.general installé sur le contrôleur.
| Variable | Rôle |
|---|---|
ansible_lxd_host, ansible_incus_host |
L’instance, jusqu’au premier point : web.example.com est web. Elle l’emporte sur ansible_host, qui l’emporte sur le nom d’inventaire. |
ansible_lxd_remote, ansible_incus_remote |
Le serveur distant, local par défaut. |
ansible_lxd_project, ansible_incus_project |
Le projet. Incus en passe toujours un, default par défaut. |
ansible_lxd_executable, ansible_incus_executable |
Le shell sous lequel les commandes s’exécutent. Elle l’emporte sur ansible_executable ; /bin/sh par défaut. |
L’utilisateur est ansible_user, le mot-clé remote_user ou -u, root par défaut. Pour tout autre utilisateur, chaque commande passe par la méthode d’élévation, /bin/su <user> -c sauf si lxd_become_method ou incus_become_method en nomme une autre. Une instance sans shell reçoit l’agent par lxc file push ou incus file push quand l’utilisateur est root. Une instance absente ou arrêtée rend l’hôte injoignable avec les mots du plugin, comme instance not running: web ; Incus y ajoute le serveur distant et le projet. Avec -vvvv, les lignes affichent ESTABLISH LXD CONNECTION FOR USER: <user> (Incus pour Incus), la ligne INFO: du plugin pour un utilisateur autre que root, puis une ligne EXEC [...] par commande.
Pods Kubernetes
Section intitulée « Pods Kubernetes »ansible_connection: kubectl, ou kubernetes.core.kubectl, exécute un play dans un conteneur d’un pod via kubectl exec -i. Les deux noms demandent kubernetes.core installé sur le contrôleur et kubectl dans votre PATH.
| Variable | Rôle |
|---|---|
ansible_kubectl_pod |
Le pod. Sans elle, le pod est ansible_host, sinon le nom d’inventaire. |
ansible_kubectl_container |
Le conteneur, pour un pod qui en a plusieurs. |
ansible_kubectl_namespace |
Le namespace. |
ansible_kubectl_kubeconfig, ansible_kubectl_config |
Le fichier kubeconfig. Un kubeconfig donné sous forme de mapping va dans un fichier temporaire privé, supprimé à la fin de l’exécution. |
ansible_kubectl_extra_args |
Des arguments de plus pour kubectl, découpés sur les espaces. |
ansible_kubectl_local_env_vars |
Un mapping de variables placées dans l’environnement de chaque commande kubectl. |
ansible_kubectl_context |
Le contexte dans le kubeconfig. |
ansible_kubectl_server, ansible_kubectl_host |
Le serveur d’API. |
ansible_kubectl_username, ansible_kubectl_user, ansible_kubectl_password |
Un nom d’utilisateur et un mot de passe pour le serveur d’API. |
ansible_kubectl_token, ansible_kubectl_api_key |
Un jeton bearer pour le serveur d’API. |
ansible_kubectl_client_cert, ansible_kubectl_cert_file, ansible_kubectl_client_key, ansible_kubectl_key_file |
Le certificat client et sa clé. |
ansible_kubectl_ca_cert, ansible_kubectl_ssl_ca_cert |
L’autorité de certification du serveur d’API. |
ansible_kubectl_validate_certs, ansible_kubectl_verify_ssl |
Passée telle quelle après --insecure-skip-tls-verify, comme le fait le plugin : true donne True, et false n’ajoute rien. |
Chaque option peut aussi venir de la variable d’environnement K8S_AUTH_* que lit le plugin, sur laquelle une variable d’hôte l’emporte. Les options arrivent à kubectl dans l’ordre du plugin. Les commandes s’exécutent sous l’utilisateur du conteneur : le plugin ne peut pas en choisir un, donc ansible_user est ignoré. Un conteneur sans shell ne peut pas recevoir l’agent, car kubectl cp y demande tar. Un pod absent, un namespace absent ou un pod terminé rendent l’hôte injoignable avec ce qu’a dit kubectl. Avec -vvvv, les lignes affichent ESTABLISH kubectl CONNECTION, puis une ligne EXEC [...] par commande, où le mot de passe et le jeton apparaissent comme ********.
Sessions AWS Systems Manager
Section intitulée « Sessions AWS Systems Manager »ansible_connection: amazon.aws.aws_ssm exécute un play sur une instance EC2 via AWS Systems Manager Session Manager, sans port entrant, sans paire de clés ni bastion. Le nom court aws_ssm y mène par community.aws, qu’il faut donc aussi installer. Le contrôleur a besoin de session-manager-plugin et de boto3 dans son Python, et l’instance de l’agent SSM.
| Variable | Rôle |
|---|---|
ansible_aws_ssm_instance_id |
L’instance. Sans elle, l’instance est ansible_host, sinon le nom d’inventaire. |
ansible_aws_ssm_region |
La région, sinon AWS_DEFAULT_REGION ou AWS_REGION ; us-east-1 par défaut. |
ansible_aws_ssm_profile |
Le profil AWS, sinon AWS_PROFILE. |
ansible_aws_ssm_access_key_id, ansible_aws_ssm_secret_access_key, ansible_aws_ssm_session_token |
Les identifiants, sinon les variables d’environnement AWS_* de même nom, sinon ce que trouve boto3. Ils ne sont jamais affichés, -vvvv compris. |
ansible_aws_ssm_plugin |
Le programme session-manager-plugin, sinon AWS_SESSION_MANAGER_PLUGIN, /usr/local/bin/session-manager-plugin ou celui de votre PATH. |
ansible_aws_ssm_document |
Le document SSM que la session démarre ; le shell par défaut du compte s’il n’est pas défini. |
ansible_aws_ssm_timeout |
Le nombre de secondes dont la session dispose pour répondre à chaque étape de la connexion ; 60 par défaut. |
Les commandes s’exécutent sous l’utilisateur de la session, ssm-user sur Amazon Linux. become en choisit un autre, et ansible_user est ignoré, comme avec le plugin. Volant n’envoie rien par S3 : les variables ansible_aws_ssm_bucket_* dont le plugin a besoin ne sont pas lues. Le terminal de la session ne renvoie que de l’UTF-8 valide, donc l’agent parle au contrôleur en lignes base64, à environ 400 Kio/s dans chaque sens, et la première exécution sur une instance y envoie l’agent une fois, en une dizaine de secondes. Une instance que l’agent SSM ne gère pas, ou des identifiants refusés, rendent l’hôte injoignable avec les mots de boto3, là où le plugin fait échouer la tâche. À la fin de l’exécution, ou si le contrôleur est tué, la session se ferme et l’agent s’arrête avec elle. Avec -vvvv, les lignes affichent ESTABLISH SSM CONNECTION TO: <instance>, puis une ligne EXEC: <commande> par commande.
Paramiko
Section intitulée « Paramiko »ansible_connection: paramiko_ssh est la connexion d’ansible-core par la bibliothèque Python paramiko. ansible-core 2.19.12 la déclare dépréciée et la retire en 2.21. Volant joint ces hôtes avec le programme ssh, donc paramiko n’a pas besoin d’être installé. Chaque option du plugin devient l’option ssh la plus proche, et le premier hôte qui se connecte affiche l’avertissement d’ansible-core une fois par exécution :
[DEPRECATION WARNING]: The paramiko connection plugin is deprecated. This feature will be removed from ansible-core version 2.21.deprecation_warnings = False le fait taire. paramiko, _paramiko_ssh et ansible.builtin.paramiko_ssh désignent le même plugin.
| Variable | Effet |
|---|---|
ansible_paramiko_host |
L’adresse. Elle l’emporte sur ansible_ssh_host, qui l’emporte sur ansible_host, puis sur le nom d’inventaire. |
ansible_paramiko_port |
ssh -p. L’emporte sur ansible_ssh_port et ansible_port, puis sur le mot-clé port, ANSIBLE_REMOTE_PARAMIKO_PORT, ANSIBLE_REMOTE_PORT, [paramiko_connection] remote_port et [defaults] remote_port. |
ansible_paramiko_user |
ssh -l. L’emporte sur ansible_ssh_user et ansible_user, puis sur le mot-clé remote_user, ANSIBLE_PARAMIKO_REMOTE_USER, [paramiko_connection] remote_user et les réglages habituels de l’utilisateur distant. |
ansible_paramiko_private_key_file |
ssh -i. L’emporte sur ansible_ssh_private_key_file et ansible_private_key_file, puis sur ANSIBLE_PARAMIKO_PRIVATE_KEY_FILE, [paramiko_connection] private_key_file et les réglages habituels de clé. |
ansible_paramiko_password, ansible_paramiko_pass |
Le mot de passe, transmis à ssh comme pour un hôte ssh. Elles l’emportent sur ansible_ssh_password, ansible_ssh_pass et ansible_password. |
ansible_paramiko_timeout |
ConnectTimeout. L’emporte sur ansible_ssh_timeout, puis sur ANSIBLE_PARAMIKO_TIMEOUT, ANSIBLE_SSH_TIMEOUT, [paramiko_connection] timeout, [ssh_connection] timeout et le délai de connexion. ansible_timeout n’est pas lu, comme avec le plugin. |
ansible_paramiko_host_key_checking, ansible_ssh_host_key_checking, ansible_host_key_checking |
Si la clé de l’hôte est vérifiée, dans cet ordre, puis ANSIBLE_PARAMIKO_HOST_KEY_CHECKING, ANSIBLE_SSH_HOST_KEY_CHECKING, ANSIBLE_HOST_KEY_CHECKING, [paramiko_connection] host_key_checking et [defaults] host_key_checking. Désactivée, ssh reçoit StrictHostKeyChecking=no et UserKnownHostsFile=/dev/null. |
ansible_paramiko_use_rsa_sha2_algorithms |
Désactivée, ssh reçoit HostKeyAlgorithms=+ssh-rsa et PubkeyAcceptedAlgorithms=+ssh-rsa, pour un serveur qui ne connaît les clés RSA que sous ssh-rsa. Avec un serveur qui propose des signatures SHA-2, ssh les préfère toujours. Aussi ANSIBLE_PARAMIKO_USE_RSA_SHA2_ALGORITHMS et [paramiko_connection] use_rsa_sha2_algorithms. |
ansible_paramiko_proxy_command |
ProxyCommand, où ssh remplace %h, %p et %r comme paramiko. Aussi ANSIBLE_PARAMIKO_PROXY_COMMAND et [paramiko_connection] proxy_command. |
Les options sans variable viennent de ANSIBLE_PARAMIKO_<NAME> ou de [paramiko_connection] :
| Option | Ce que reçoit ssh |
|---|---|
host_key_auto_add |
Activée, avec la vérification des clés activée : StrictHostKeyChecking=accept-new. La clé d’un nouvel hôte est acceptée, une clé modifiée reste refusée. |
record_host_keys |
Désactivée, avec la vérification des clés activée : UserKnownHostsFile=/dev/null ~/.ssh/known_hosts ~/.ssh/known_hosts2. ssh vérifie avec les fichiers habituels et écrit une nouvelle clé dans le premier, qui ne garde rien. |
look_for_keys |
Désactivée, avec un fichier de clé donné : IdentitiesOnly=yes, seule cette clé est essayée. Sans fichier de clé, elle ne change rien. |
pty |
Désactivée : pas de terminal, comme ansible_ssh_use_tty: false pour ssh. |
banner_timeout |
Lue et vérifiée, sans effet : ssh n’a pas ce réglage. |
Ce qui diffère du plugin :
~/.ssh/configet/etc/ssh/ssh_configne sont pas lus, comme avec paramiko : chaquesshreçoit-F /dev/null.ansible_ssh_common_args,ansible_ssh_extra_argsetansible_ssh_executablene sont pas lus non plus.- Une clé d’hôte inconnue, avec la vérification activée et
host_key_auto_adddésactivée, rend l’hôte injoignable avec le message dessh. Le plugin pose la question sur le terminal. - Les messages d’échec sont ceux de
ssh, pour une clé d’hôte inconnue comme pour une connexion refusée, et l’hôte est injoignable dans les deux cas, comme avec le plugin. - Avec
look_for_keysdésactivée et un fichier de clé donné, les clés dessh-agentne sont pas proposées non plus. paramiko les propose toujours. - La connexion à un hôte est partagée entre les tâches, comme pour
ssh.
Avec -vvvv, la première ligne est ESTABLISH PARAMIKO SSH CONNECTION FOR USER: <user> on PORT <port> TO <address>, suivie des lignes SSH: EXEC d’un hôte ssh.
Connexions que seul ansible-core possède
Section intitulée « Connexions que seul ansible-core possède »Volant joint un hôte par l’une de deux voies. Pour ssh, local et les connexions listées plus haut, il lance son agent sur l’hôte et lui envoie les tâches. Pour tout autre plugin de connexion que l’ansible-core du contrôleur sait charger, aucun agent ne tourne : chaque tâche qui a besoin de l’hôte va à l’assistant Python de Volant, qui charge le plugin de connexion, se connecte, exécute par lui le plugin d’action de la tâche comme ansible-playbook le ferait, puis referme la connexion une fois la tâche finie. Les éléments d’une boucle partagent une seule connexion, comme sous ansible-playbook. ansible-core lit chaque option du plugin dans les variables de l’hôte, dans ansible.cfg et dans l’environnement, comme toujours.
Tout le reste de l’exécution est inchangé : boucles, when, register, changed_when, failed_when, until et retries, ignore_errors, no_log, serial, delegate_to, handlers, async avec poll: 0 et async_status, le mode vérification et le récapitulatif. Une tâche qui s’exécute sur le contrôleur, comme debug ou set_fact, s’y exécute comme avant.
- Un plugin qui ne peut pas se connecter rend l’hôte injoignable avec son propre message.
- Les lignes que le plugin affiche à
-vvv, comme<host> ESTABLISH ... CONNECTION, s’affichent sous la tâche à la même verbosité. ansible_password, les autres variables secrètes du plugin et le mot de passe de become sont écrits********dans chaque ligne et chaque résultat.- Jamais plus de processus assistants ne tournent à la fois que
forksne le permet. becomeprend la méthode d’escalade de la tâche,sudoousu, que la tâche, son bloc ou son play le demande. Écrit comme un template, par exemplebecome: "{{ item }}", il est rendu pour chaque élément de la boucle.
Chaque tâche paie le démarrage de la connexion du plugin, comme avec ansible-playbook, donc cette voie est plus lente par tâche que celle de l’agent.
Connexions qui gardent un processus
Section intitulée « Connexions qui gardent un processus »network_cli, netconf et httpapi gardent leur connexion à l’équipement dans un processus à part, comme sous ansible-playbook. Avant la première tâche qui a besoin de l’équipement, le helper lance le stub ansible-connection d’ansible-core avec le Python, les chemins de plugins et la verbosité du helper. Le stub démarre le processus, qui écoute sur un socket sous ~/.ansible/pc, réglé par ANSIBLE_PERSISTENT_CONTROL_PATH_DIR ou [persistent_connection] control_path_dir. Le nom du socket est une empreinte de l’adresse, du port, de l’utilisateur et de l’exécution : toute tâche suivante pour le même équipement réutilise le processus, depuis n’importe quel helper.
- Un processus qui ne démarre pas fait échouer la tâche avec son erreur, pas l’hôte.
-vvvajoute sa trace. meta: reset_connectiontermine le processus de l’hôte, et la fin de chaque play termine tous les processus que ses tâches ont démarrés, comme le faitansible-playbook. Un processus resté inactifpersistent_connect_timeoutsecondes (30 par défaut) s’arrête de lui-même, et une commande attend au pluspersistent_command_timeoutsecondes (30).- À
-vvvv, les lignes qu’ansible-core affiche en démarrant le processus, comme<address> attempting to start connectionet<address> local domain socket path is ..., s’affichent sous la tâche. persistent_log_messagesjournalise chaque échange avec l’équipement, mots de passe compris, et ansible-core prévient avec son propre texte.
Équipements réseau
Section intitulée « Équipements réseau »ansible_connection: network_cli, netconf ou httpapi, ou leurs noms complets sous ansible.netcommon, atteignent un switch, un routeur ou un pare-feu par les plugins d’ansible.netcommon, qu’ansible-core charge dans le helper Python de Volant. Le contrôleur a besoin d’ansible.netcommon et d’ansible.utils, et de la collection de la plateforme de l’équipement, comme cisco.ios. ansible_network_os nomme cette plateforme (cisco.ios.ios). Un hôte network_cli qui ne l’a pas est injoignable avec Unable to automatically determine host network os.
Les modules des collections réseau, comme ansible.netcommon.cli_command ou cisco.ios.ios_config, tournent sur le contrôleur comme sous ansible-playbook et atteignent l’équipement par le processus persistant de la connexion. Un module qui demande une autre connexion que celle de l’hôte échoue avec le message de sa collection, comme Connection type local is not valid for this module.
Chaque connexion a besoin de paquets Python qu’ansible-core n’apporte pas : paramiko ou ansible-pylibssh pour network_cli, ncclient pour netconf. Avec le runtime géré de Volant, volant runtime install --extras network les installe, et une exécution qui en a besoin s’arrête avant la première connexion tant qu’ils manquent. Avec VOLANT_PYTHON, installez-les dans cet environnement.
Les plugins lisent eux-mêmes leurs options dans les variables de l’hôte, ansible.cfg et l’environnement, comme ansible-doc -t connection ansible.netcommon.network_cli les liste.
Variables d’hôte
Section intitulée « Variables d’hôte »Volant lit celles-ci par hôte, depuis l’inventaire ou depuis toute autre source de variables. Un test compare cette liste aux noms que lit le code de connexion : elle reste donc synchronisée avec le moteur.
| Variable | Effet |
|---|---|
ansible_connection |
ssh (par défaut) ou local |
ansible_host, ansible_ssh_host |
Adresse à laquelle se connecter. Par défaut, le nom dans l’inventaire. Une valeur qui commence par - ou contient une espace ou un caractère de contrôle est refusée avant le lancement de ssh. |
ansible_port, ansible_ssh_port |
ssh -p. Un nombre entre guillemets fonctionne comme un nombre nu. |
ansible_user, ansible_ssh_user |
ssh -l |
ansible_password, ansible_ssh_pass, ansible_ssh_password |
Le mot de passe de connexion, proposé à ssh comme décrit plus haut. |
ansible_private_key_file, ansible_ssh_private_key_file |
ssh -i |
ansible_timeout, ansible_ssh_timeout |
Secondes pendant lesquelles ssh attend la connexion, ssh -o ConnectTimeout. |
ansible_ssh_executable |
Le programme ssh à lancer. Par défaut, le ssh de votre PATH. |
ansible_ssh_common_args |
Arguments ssh supplémentaires, découpés comme le ferait un shell |
ansible_ssh_extra_args |
Les mêmes, ajoutés après les arguments communs |
ansible_ssh_use_tty |
Exécute les commandes raw et script sur un terminal, comme ssh -tt. Actif sauf si la valeur est false. La valeur par défaut vient de usetty. |
ansible_remote_tmp |
Répertoire qui contient le cache de l’agent sur cet hôte |
ansible_become |
Élever les privilèges ou non, en remplaçant le mot-clé become |
ansible_become_user, ansible_sudo_user, ansible_su_user |
Utilisateur cible de l’élévation |
ansible_become_method |
sudo ou su |
ansible_become_password, ansible_become_pass, ansible_sudo_pass, ansible_su_pass |
Mot de passe de l’élévation |
ansible_become_exe, ansible_sudo_exe, ansible_su_exe |
Le programme d’élévation |
ansible_become_flags, ansible_sudo_flags, ansible_su_flags |
Ses options |
ansible_su_prompt_l10n |
Une liste d’invites que su peut afficher, ou une chaîne qui les sépare par des virgules. Elle remplace celles qui sont intégrées. |
ansible_sudo_chdir |
Le répertoire depuis lequel sudo est lancé. Un répertoire qui n’existe pas fait échouer la tâche. |
Quand un hôte définit une variable et un de ses alias, celui qu’Ansible fait gagner s’applique. Le tableau les liste du plus fort au plus faible, avec le mot-clé qui règle la même chose :
| Réglage | Variables | Mot-clé |
|---|---|---|
| Adresse | ansible_ssh_host, ansible_host |
|
| Port | ansible_ssh_port, ansible_port |
port |
| Utilisateur | ansible_ssh_user, ansible_user |
remote_user |
| Fichier de clé | ansible_ssh_private_key_file, ansible_private_key_file |
|
| Délai | ansible_ssh_timeout, ansible_timeout |
|
| Mot de passe | ansible_ssh_password, ansible_ssh_pass, ansible_password |
|
| Connexion | ansible_connection |
connection |
| Utilisateur, programme et options de l’élévation | ansible_sudo_* ou ansible_su_* (ceux de la méthode), puis ansible_become_* |
become_user, become_exe, become_flags |
| Mot de passe de l’élévation | ansible_sudo_pass ou ansible_su_pass, puis ansible_become_pass, puis ansible_become_password |
Une variable de mot de passe l’emporte sur -k et --connection-password-file, et une variable réglée sur une chaîne vide ne propose aucun mot de passe. Une variable de connexion fonctionne à tous les niveaux qui définissent des variables : inventaire, group_vars, vars d’un play, bloc, vars d’une tâche et -e.
Les mots-clés fonctionnent sur un play, un bloc et une tâche, et -c définit la connexion des hôtes qui n’en nomment aucune. L’ordre est celui d’Ansible : une variable d’hôte comme ansible_user l’emporte, puis la tâche, le bloc et le play, puis la ligne de commande et ansible.cfg. Les facts qu’un hôte rapporte sur lui-même ne choisissent jamais son utilisateur, son port ni sa connexion. Un mot-clé écrit sous forme de modèle est rendu une fois par tâche. Ces valeurs font échouer la tâche : un nom d’utilisateur qui commence par - ou contient une espace, un guillemet ou un caractère de contrôle, un port hors de 1-65535, et un nom de connexion qui contient autre chose que des lettres, des chiffres, _ et .. Une tâche déléguée utilise le remote_user et le port de la tâche, sauf si l’hôte délégué définit son propre ansible_user ou ansible_port.
Un guillemet non fermé dans ansible_ssh_common_args ou ansible_ssh_extra_args fait échouer l’hôte au lieu d’être ignoré. Cela compte derrière un bastion : abandonner silencieusement un ProxyCommand ouvrirait une connexion directe vers une adresse qui peut appartenir à une autre machine.
Les paramètres d’ansible.cfg qui touchent les connexions, comme timeout, remote_user, host_key_checking et forks, sont listés dans Configuration.
Le cache de l’agent
Section intitulée « Le cache de l’agent »L’agent est un petit programme statique, d’environ 1.2 MB pour Linux x86_64. Volant le téléverse une fois par hôte et le réutilise à chaque exécution suivante : un hôte ne contient donc que l’agent et, quand des modules Python ont tourné, un cache de charges utiles.
Il se trouve dans <remote_tmp>/volant-agent-<version>-<uid>/volant-agent, donc, avec le remote_tmp par défaut, sous ~/.ansible/tmp/ dans un répertoire personnel. La version dans le chemin est celle du contrôleur, ce qui évite à un contrôleur mis à jour de lancer un ancien agent. Une tâche qui élève ses privilèges exécute son propre agent sous l’identité du become_user, mis en cache dans le répertoire personnel de cet utilisateur : un hôte porte donc un cache par compte sous lequel l’exécution agit.
Quand des modules Python ont tourné, un second répertoire, volant-blobs-<version>-<uid>, se trouve à côté du répertoire de l’agent dans le même remote_tmp et contient les charges utiles de modules que Volant a envoyées.
La façon dont l’agent arrive dépend de la cible. Par ssh, et dans un conteneur qui a un shell, l’agent est passé à un script shell sur la connexion, qui contrôle le répertoire et écrit le fichier. Dans un conteneur sans shell, la commande de copie du runtime y dépose l’agent, et l’agent se place lui-même avec les mêmes contrôles ; docker le fait avec docker cp.
Pour effacer les deux, supprimez les deux répertoires. Rien d’autre ne reste :
ssh web1 'rm -rf ~/.ansible/tmp/volant-agent-* ~/.ansible/tmp/volant-blobs-*'Avec ANSIBLE_KEEP_REMOTE_FILES=1, ou keep_remote_files dans ansible.cfg, un module sans plugin propre s’exécute comme ansible-core l’exécute. ansible-core construit son wrapper AnsiballZ, Volant le copie dans <remote_tmp>/ansible-tmp-*/AnsiballZ_<module>.py et l’y laisse, et ses commandes explode et execute fonctionnent. L’hôte a besoin de Python pour cela, et chacune de ces tâches est plus lente qu’à travers l’agent. -vvv affiche chaque PUT et EXEC. copy, template et les autres plugins dont Volant a sa propre version ne laissent pas de wrapper, et une tâche qui escalade vers un autre utilisateur que root reste à l’agent.
ansible_pipelining: false sur un hôte fait la même chose pour cet hôte, sauf qu’ansible-core supprime le wrapper et son répertoire après chaque tâche. Sans cette variable, l’agent reste en place, bien que le défaut d’ansible-core soit sans pipelining. Une valeur qui vient seulement d’ansible.cfg ou d’ANSIBLE_PIPELINING laisse aussi l’agent en place.
L’agent sur vos hôtes couvre le téléversement, la réparation d’un cache cassé et les contrôles de permissions.
Connexions persistantes
Section intitulée « Connexions persistantes »Un hôte garde sa connexion à l’agent pendant toute l’exécution, d’un play à l’autre. Les tâches circulent sur cette connexion unique au lieu d’en ouvrir une nouvelle à chaque fois. Si la connexion meurt entre deux plays, Volant se reconnecte une fois, et un second échec signale l’hôte injoignable.
Les hôtes joints en local partagent plutôt leurs agents. Chacun de ces agents tourne sur le contrôleur sous le même utilisateur, donc un hôte qui attend les autres passe son agent au prochain hôte qui s’exécute, et le run garde au plus forks agents inactifs. Un play sur 500 hôtes locaux garde environ autant d’agents que forks le permet, pas 500. Un agent local escaladé reste avec son hôte.
Certaines tâches ajoutent une connexion :
- L’élévation de privilèges. Un hôte qui utilise
becomedétient une seconde connexion, vers un agent qui tourne sous l’utilisateur cible. Elle est gardée jusqu’à la fin du play : un play de tâches élevées démarre donc un seul agent élevé, pas un par tâche. Un hôte ne détient qu’une connexion élevée à la fois : passer à un autre utilisateur la remplace. - La délégation. Une tâche déléguée s’exécute sur la connexion propre à l’hôte délégué, avec les réglages de ce dernier. Un hôte dont le play délègue à trois autres hôtes détient ces trois connexions en plus de la sienne.
Une connexion par hôte
Section intitulée « Une connexion par hôte »Tous les lancements de ssh que fait Volant pour un hôte de l’inventaire partagent une seule connexion OpenSSH : seul le premier paie l’échange de clés et l’authentification. La connexion partagée reste ouverte 30 secondes après sa dernière session. OpenSSH fait le travail : ~/.ssh/config, Match, Include, ProxyJump et votre ssh-agent s’appliquent exactement comme pour ansible-playbook.
Volant vous laisse gérer le partage quand vos propres arguments ssh ou votre configuration définissent déjà ControlMaster, ControlPath ou ControlPersist pour l’hôte. Réglez [volant] ssh_control_master = false ou VOLANT_SSH_CONTROL_MASTER=0 pour le désactiver, voir Configuration.
Chaque connexion coûte trois descripteurs de fichier au contrôleur. Une limite stricte de 1024 fichiers ouverts arrête une exécution à environ 330 connexions, ou à environ 169 hôtes qui élèvent leurs privilèges. L’agent sur vos hôtes donne l’emplacement du socket, les réglages de keepalive et la vérification à faire avant une exécution large.
become exécute des tâches sous un autre utilisateur par sudo ou su.
- hosts: web become: true tasks: - name: Install nginx apt: name: nginx state: present
- name: Check the app as its own user command: /opt/app/bin/healthcheck become_user: appFonctionnement
Section intitulée « Fonctionnement »Volant n’enveloppe pas chaque tâche dans sudo. Il démarre un second agent pour l’utilisateur cible :
sudo -H <form> -u <user> -- volant-agent<form> est -n ou -k -S -p '', selon une sonde décrite plus bas. Volant ajoute -H seulement quand aucun become_flags n’est défini : une liste d’options le remplace. Les tâches qui n’élèvent pas leurs privilèges continuent d’utiliser l’agent non privilégié. L’agent lui-même ne sait rien de l’élévation. La fiche de décision 0004 explique pourquoi.
L’agent élevé est gardé jusqu’à la fin du play : un play de tâches élevées paie donc sudo une fois par hôte.
Sur une connexion local, sudo tourne comme le lance la connexion local d’ansible-core. Il n’y a pas de sonde : l’agent démarre derrière un shell qui affiche d’abord une ligne de succès, comme la commande d’ansible-core affiche son BECOME-SUCCESS-<random>, donc rien de ce qu’un wrapper become_exe affiche d’abord n’est lu comme la sortie de l’agent. Avec un mot de passe, sudo reçoit -S -p "[sudo via ansible, key=<random>] password:", et le mot de passe part quand cette invite s’affiche sur stdout ou stderr. Sans mot de passe, il reçoit -S -n. ansible_local_become_success_timeout limite l’attente de la ligne de succès, 10 secondes par défaut. Une tâche raw qui s’élève par cet agent montre dans son stderr ce que sudo y a affiché après l’invite. Avec ansible_local_become_strip_preamble: false, elle montre tout ce que les deux flux ont dit avant le démarrage de l’agent, invite et ligne de succès comprises, et ces tâches ont un agent à elles.
Quel réglage l’emporte
Section intitulée « Quel réglage l’emporte »become, become_user et become_method sont acceptés sur un play, un bloc et une tâche. Mesuré par rapport à Ansible :
- Les variables d’hôte
ansible_becomeetansible_become_userl’emportent sur les deux mots-clés, dans les deux sens. - Le mot-clé de la tâche l’emporte sur celui du play.
- Les valeurs par défaut d’
ansible.cfget-b,--become-useret--become-methods’appliquent en dernier.
become_method vaut sudo ou su. Toute autre méthode n’est pas encore prise en charge, de même que les écritures qualifiées ansible.builtin.sudo et ansible.builtin.su. Volant s’arrête avant l’exécution d’une tâche et nomme la méthode, plutôt que d’élever les privilèges par un mécanisme que vous n’avez pas demandé. Quand une exécution élève ses privilèges et que la méthode vient de --become-method, d’ansible.cfg ou de ansible_become_method, l’exécution se termine avec le code 2 avant toute tâche.
become_user peut être un modèle comme {{ app_user }}. Un modèle qui change à chaque élément de boucle est refusé, parce qu’un lot s’élève vers un seul utilisateur.
become_exe et become_flags sont lus depuis le mot-clé et depuis ansible_become_exe et ansible_become_flags, la variable d’hôte l’emportant. Les deux sont découpés en mots comme le fait un shell, et un guillemet non fermé fait échouer la tâche.
Le mot de passe become
Section intitulée « Le mot de passe become »Le mot de passe vient de l’une de ces sources :
-K(--ask-become-pass), qui désactive l’écho du terminal sous Unix.--become-password-file, qui lit la première ligne d’un fichier.ansible_become_password,ansible_become_pass, ouansible_sudo_passouansible_su_passpropres à la méthode, qui l’emportent sur les deux autres. Variables d’hôte liste la variable qui gagne.
Il est écrit une seule fois sur l’entrée standard de sudo. Il n’apparaît jamais dans une ligne de commande, un journal ou un résultat : les types qui le portent affichent <redacted> dans la sortie de débogage, et la sortie d’erreur de sudo en est expurgée avant d’atteindre un message.
La sonde sudo
Section intitulée « La sonde sudo »Sauf sur une connexion local, Volant demande à sudo quelle forme employer au lieu d’en supposer une. Il essaie d’abord sudo -n, et ne se rabat sur sudo -k -S -p '' que lorsque sudo lui-même rejette la demande faute d’authentification. La fiche de décision 0004 explique pourquoi une supposition bloquerait le lien. Sur un hôte qui a déjà servi, Volant démarre d’abord l’agent en cache sous sudo -n dans la même session ssh que ses vérifications, et ne lance la sonde que si cela échoue, comme le décrit L’agent sur vos hôtes.
Quand l’élévation échoue, faute de mot de passe, avec un mauvais mot de passe ou à cause d’une règle sudoers qui interdit la commande, la tâche échoue et l’hôte reste joignable. Les messages sont ceux d’Ansible : Missing sudo password ou Incorrect sudo password. Une tâche qui reçoit un autre mot de passe a son propre agent, donc un mauvais mot de passe échoue même après que le bon a fonctionné, et ignore_errors couvre cet échec comme n’importe quel autre. Sur une connexion local, les messages sont ceux de la connexion local d’ansible-core : Premature end of stream waiting for become success, suivi de ce que chaque flux a dit, et Duplicate become password prompt encountered pour un mauvais mot de passe. Timed out waiting for become success rend l’hôte injoignable.
su n’a pas d’option pour lire un mot de passe sans terminal : Volant répond donc à son invite. Le mot de passe est écrit une seule fois dans l’invite, jamais placé dans une ligne de commande, un journal ni la sortie de -vvv. Un mauvais mot de passe fait échouer la tâche avec Incorrect su password. Une invite qui ne vient jamais met fin à la tâche avec Timeout (12s) waiting for privilege escalation prompt, comme dans ansible-core.
Sur une connexion local, su s’exécute sur un terminal à part. Un mauvais mot de passe fait échouer la tâche avec Premature end of stream waiting for become success. et ce que su a affiché, comme le fait ansible-core dans ce cas. L’attente de l’invite est toujours de 12 secondes sur une connexion locale, quelle que soit la valeur de -T. Une invite qui ne vient jamais rend l’hôte injoignable avec Timed out waiting for become success or become password prompt.
Pas encore disponible
Section intitulée « Pas encore disponible »- Les hôtes Windows.
- Les plugins de connexion autres que
sshetlocal, listés dans la matrice de prise en charge. doas,pbrunet les autres méthodes become. Elles pourront être ajoutées comme autres façons de démarrer l’agent, sans changer le protocole.
Mots-clés est la liste complète, générée à partir des tables que lit le moteur.