Ajouter des clés SSH à un site

SSH access to a Kapsule site is key-based only, so before you can open a shell or an SFTP session you need to register a public key against the site in KPanel. This guide covers where that lives…

L'accès SSH à un site Kapsule est basé sur les clés uniquement. Avant de pouvoir ouvrir un shell ou une session SFTP, vous devez enregistrer une clé publique sur le site dans KPanel. Ce guide explique où se trouve cette option, comment ajouter une clé que vous possédez déjà, comment faire générer une clé par Kapsule, et comment révoquer une clé en laquelle vous n'avez plus confiance.

Où se trouve la page des clés SSH

Ouvrez Websites, cliquez sur le site, puis ouvrez le menu Files dans la bande d'onglets du site et choisissez SSH Keys. La page s'intitule SSH access et elle contient deux éléments : les détails de connexion de ce site et la liste des clés publiques actuellement autorisées à les utiliser.

Il n'y a pas d'élément SSH de haut niveau dans la barre latérale principale. Les clés sont par site, donc une clé que vous ajoutez ici s'authentifie uniquement contre ce site. Si vous exécutez plusieurs sites, chacun a besoin de sa propre entrée, même s'il s'agit de la même clé sur votre ordinateur portable.

SSH access page for a site in KPanel

L'ajout ou la révocation d'une clé nécessite la permission sites:write. Si vous disposez d'un compte d'équipe avec un rôle en lecture seule, le bouton Add key et l'icône de révocation sont masqués. Demandez à un propriétaire ou à un administrateur du compte d'effectuer la modification.

Détails de connexion

La carte Connection details en haut de la page affiche tout ce dont votre client a besoin :

Champ	Ce que c'est
Host	Le nom d'hôte auquel se connecter
Port	Le port SSH de ce site
Username	L'utilisateur système sous lequel s'exécute votre site
SSH	Une commande `ssh` prête à l'emploi pour ce site
SFTP	Une commande `sftp` prête à l'emploi pour ce site

Chaque ligne dispose d'un contrôle de copie, et les lignes SSH et SFTP copient la commande complète plutôt que seulement la valeur, vous pouvez donc la coller directement dans un terminal. Utilisez ces deux plutôt que de taper la commande vous-même : elles contiennent déjà l'utilisateur, l'hôte et le port corrects.

Si la carte n'apparaît pas du tout, le site n'a pas encore fini de provisionner son utilisateur shell. L'API renvoie une erreur simple Site has no SSH user dans ce cas. Attendez que la pilule d'état du site affiche Active et rechargez la page.

Ajouter une clé que vous possédez déjà

La plupart des gens ont déjà une paire de clés sur leur machine. Ajoutez la moitié publique ici.

Sur votre propre ordinateur, affichez votre clé publique. Sur macOS et Linux, c'est généralement cat ~/.ssh/id_ed25519.pub, ou cat ~/.ssh/id_rsa.pub pour une clé RSA plus ancienne. Sur Windows avec OpenSSH, c'est type %USERPROFILE%\.ssh\id_ed25519.pub.
Copiez la ligne unique complète, commençant par ssh-ed25519, ssh-rsa ou ecdsa-sha2-nistp256.
Dans KPanel, cliquez sur Add key.
Mettez quelque chose de mémorable dans le champ Label, par exemple le nom de la machine sur laquelle se trouve la clé.
Collez la clé publique dans le deuxième champ.
Cliquez sur Add key.

La clé apparaît immédiatement dans la liste Authorised keys, avec son empreinte numérique sous le label. Vous pouvez vous connecter immédiatement.

Kapsule envoie également un email à l'adresse du compte chaque fois qu'une clé est ajoutée, en citant le label, l'empreinte numérique et le site. Cet email est volontaire : l'accès SSH est une question de confiance élevée, donc si une clé apparaît que vous n'avez pas ajoutée, révoquez-la et changez votre mot de passe immédiatement.

Ne collez jamais que le fichier .pub. Un fichier de clé privée n'a pas d'extension .pub et commence par une ligne comme -----BEGIN OPENSSH PRIVATE KEY-----. Si vous collez cela, c'est votre clé privée, et elle doit être régénérée plutôt que réutilisée.

Si vous n'avez pas encore de clé

Générez-en une localement avec ssh-keygen -t ed25519 -C "your-label", acceptez l'emplacement de fichier par défaut, et définissez une phrase de passe lorsque vous y êtes invité. Cela produit ~/.ssh/id_ed25519 (gardez-la privée) et ~/.ssh/id_ed25519.pub (collez celle-ci).

Laisser Kapsule générer la paire de clés

Si vous préférez ne pas exécuter ssh-keygen, KPanel peut créer la paire pour vous.

Cliquez sur Add key.
Remplissez le champ Label. Laissez la boîte de clé publique vide.
Cliquez sur Generate keypair.

Kapsule crée une paire Ed25519, installe la moitié publique sur le site, et affiche une bannière verte : Keypair generated: download the private key now. Cliquez sur Download .pem pour enregistrer la clé privée. Le fichier est nommé d'après le label que vous avez choisi.

La clé privée est affichée une seule fois. La bannière l'indique clairement : c'est la seule occasion de la télécharger. Kapsule ne conserve pas de copie que vous pourriez récupérer plus tard. Si vous ignorez la bannière sans télécharger, révoquez la clé et générez une nouvelle paire.

Une clé générée n'a pas de phrase de passe, ce qui la rend utilisable à partir d'un script sans invite. Cela signifie également que le fichier lui-même est l'intégralité de la credential. Si vous voulez une phrase de passe, générez la paire vous-même avec ssh-keygen et collez la moitié publique.

Une fois téléchargé, placez le fichier quelque part de sensé et resserrez ses permissions, car SSH refuse d'utiliser une clé privée lisible par tous :

mv ~/Downloads/my-laptop_id_ed25519.pem ~/.ssh/kapsule-mysite.pem
chmod 600 ~/.ssh/kapsule-mysite.pem
ssh -i ~/.ssh/kapsule-mysite.pem <username>@<host> -p <port>

Remplacez le nom d'utilisateur, l'hôte et le port par ceux de la carte Connection details.

Lire la liste des clés autorisées

Chaque ligne dans Authorised keys affiche :

Le label que vous avez donné à la clé.
L'empreinte numérique de la clé, c'est-à-dire comment vous distinguez deux clés lorsque les labels sont similaires.
Added avec la date d'enregistrement.
Last used avec la date de la dernière authentification, ou Never used si elle ne s'est pas encore authentifiée.

La colonne Last used est celle qui est utile lors d'un nettoyage. Une clé qui n'a jamais été utilisée, ou qui n'a pas été utilisée depuis des mois, est généralement un ordinateur portable qui a été remplacé ou un entrepreneur qui a déménagé.

Révoquer une clé

Cliquez sur l'icône de la corbeille rouge sur la ligne de la clé. KPanel vous demande de confirmer avec Revoke SSH key? et une note indiquant que la clé n'authentifiera plus ce site. Cliquez sur Revoke pour terminer.

La révocation prend effet pour les nouvelles connexions. Une session SSH déjà ouverte ne sera pas fermée en révoquant la clé, donc si vous supprimez l'accès à quelqu'un qui pourrait encore être connecté, révoquez la clé, puis modifiez tout ce qu'il aurait pu prendre avec lui : les mots de passe de base de données, les secrets d'application et tous les jetons stockés sur le site.

Gardez la liste des clés courte. Une clé par machine, étiquetée avec le nom de la machine, est bien plus facile à vérifier qu'un tas de clés appelées « key1 », « new key » et « temp ».

Dépannage

Permission denied (publickey). La cause la plus courante est que votre client propose une clé différente de celle que vous avez enregistrée. Forcez la bonne avec ssh -i /path/to/private_key ..., ou vérifiez avec ssh -v quelles clés sont proposées.

Connection refused ou un délai d'expiration. Confirmez que vous utilisez le port indiqué dans Connection details et non le port 22 par défaut. Copiez la commande SSH de la page plutôt que de la taper.

Bad permissions on the private key. OpenSSH refuse une clé privée que d'autres utilisateurs peuvent lire. Exécutez chmod 600 sur le fichier.

La clé fonctionne pour SSH mais pas pour SFTP. Elles partagent les mêmes credentials, donc c'est presque toujours le client plutôt que la clé. Utilisez la commande SFTP copiée de la page, qui porte déjà le bon port.

Où aller ensuite

Uploading Files With SFTP couvre le côté transfert de fichier des mêmes credentials.
Connecting To Your Database Over an SSH Tunnel utilise la clé que vous venez d'ajouter pour accéder à MySQL à partir d'un client de bureau.
Site Activity Log enregistre chaque clé que vous ajoutez, vous pouvez donc vérifier ultérieurement qui a ajouté quoi et quand.