Agregar claves SSH a un sitio

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…

SSH access a un sitio Kapsule es únicamente basado en claves, así que antes de poder abrir una sesión de shell o SFTP necesitas registrar una clave pública contra el sitio en KPanel. Esta guía cubre dónde se encuentra, cómo agregar una clave que ya tienes, cómo hacer que Kapsule genere una para ti, y cómo revocar una clave en la que ya no confías.

Dónde se encuentra la página de claves SSH

Abre Websites, haz clic en el sitio, luego abre el menú Files en la pestaña del sitio y elige SSH Keys. La página se titula SSH access y contiene dos cosas: los detalles de conexión para este sitio, y la lista de claves públicas actualmente autorizadas a usarlas.

No hay un elemento SSH de nivel superior en la barra lateral principal. Las claves son por sitio, así que una clave que agregues aquí se autentica únicamente contra este sitio. Si ejecutas varios sitios, cada uno necesita su propia entrada, aunque sea la misma clave en tu laptop.

SSH access page for a site in KPanel

Agregar o revocar una clave requiere el permiso sites:write. Si estás en una cuenta de equipo con un rol de solo lectura, el botón Add key y el ícono de revocación están ocultos. Pide a un propietario de cuenta o administrador que realice el cambio.

Detalles de conexión

La tarjeta Connection details en la parte superior de la página muestra todo lo que tu cliente necesita:

Campo	Qué es
Host	El nombre de host al que conectarse
Port	El puerto SSH para este sitio
Username	El usuario del sistema en el que se ejecuta tu sitio
SSH	Un comando `ssh` listo para usar para este sitio
SFTP	Un comando `sftp` listo para usar para este sitio

Cada fila tiene un control de copia, y las filas SSH y SFTP copian todo el comando en lugar de solo el valor, así puedes pegarlo directamente en una terminal. Usa esos dos en lugar de escribir el comando tú mismo: ya contienen el usuario, host y puerto correctos.

Si la tarjeta no aparece en absoluto, el sitio aún no ha terminado de aprovisionar su usuario de shell. La API devuelve un error simple Site has no SSH user en ese caso. Espera a que la píldora de estado del sitio lea Active y recarga.

Agregar una clave que ya tienes

La mayoría de las personas ya tienen un par de claves en su máquina. Agrega la mitad pública aquí.

En tu propia computadora, imprime tu clave pública. En macOS y Linux suele ser cat ~/.ssh/id_ed25519.pub, o cat ~/.ssh/id_rsa.pub para una clave RSA más antigua. En Windows con OpenSSH es type %USERPROFILE%\.ssh\id_ed25519.pub.
Copia la línea única completa, comenzando con ssh-ed25519, ssh-rsa o ecdsa-sha2-nistp256.
En KPanel, haz clic en Add key.
Pon algo memorable en el campo Label, por ejemplo el nombre de la máquina donde reside la clave.
Pega la clave pública en el segundo campo.
Haz clic en Add key.

La clave aparece en la lista Authorised keys inmediatamente, con su huella digital debajo de la etiqueta. Puedes conectarte inmediatamente.

Kapsule también envía un correo electrónico a la dirección de la cuenta cada vez que se agrega una clave, citando la etiqueta, la huella digital y el sitio. Ese correo es intencional: el acceso SSH es de alta confianza, así que si aparece una clave que no agregaste, revócala y cambia tu contraseña inmediatamente.

Solo pega nunca el archivo .pub. Un archivo de clave privada no tiene extensión .pub y comienza con una línea como -----BEGIN OPENSSH PRIVATE KEY-----. Si pegas eso, es tu clave privada, y debe ser regenerada en lugar de reutilizada.

Si aún no tienes una clave

Genera una localmente con ssh-keygen -t ed25519 -C "your-label", acepta la ubicación de archivo predeterminada, y establece una frase de contraseña cuando se te pida. Eso produce ~/.ssh/id_ed25519 (mantenla privada) y ~/.ssh/id_ed25519.pub (pega esa).

Dejar que Kapsule genere el par de claves

Si prefieres no ejecutar ssh-keygen, KPanel puede hacer el par para ti.

Haz clic en Add key.
Completa el campo Label. Deja la caja de clave pública vacía.
Haz clic en Generate keypair.

Kapsule crea un par Ed25519, instala la mitad pública contra el sitio, y muestra un banner verde: Keypair generated: download the private key now. Haz clic en Download .pem para guardar la clave privada. El archivo se nombra según la etiqueta que elegiste.

La clave privada se muestra una vez y solo una vez. El banner lo dice claramente: esta es la única vez que puedes descargarla. Kapsule no guarda una copia que puedas recuperar más tarde. Si descartas el banner sin descargar, revoca la clave y genera un nuevo par.

Una clave generada no tiene una frase de contraseña, lo que la hace utilizable desde un script sin solicitar. Eso también significa que el archivo en sí es toda la credencial. Si quieres una frase de contraseña, genera el par tú mismo con ssh-keygen en su lugar y pega la mitad pública.

Una vez descargado, mueve el archivo a un lugar sensato y estricta sus permisos, porque SSH se niega a usar una clave privada legible por todos:

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>

Sustituye el nombre de usuario, host y puerto de la tarjeta Connection details.

Leer la lista de claves autorizadas

Cada fila en Authorised keys muestra:

La etiqueta que le diste a la clave.
La huella digital de la clave, que es cómo distingues dos claves cuando las etiquetas son similares.
Added con la fecha en que fue registrada.
Last used con la fecha de la autenticación más reciente, o Never used si aún no se ha autenticado.

La columna Last used es la útil durante una limpieza. Una clave que nunca se ha usado, o no se ha usado en meses, generalmente es un laptop que ha sido reemplazado o un contratista que se ha mudado.

Revocar una clave

Haz clic en el ícono rojo de basura en la fila de la clave. KPanel te pide que confirmes con Revoke SSH key? y una nota de que la clave ya no se autenticará contra este sitio. Haz clic en Revoke para terminar.

La revocación entra en vigor para nuevas conexiones. Una sesión SSH que ya está abierta no es cerrada por revocar la clave, así que si estás removiendo acceso de alguien que aún podría estar conectado, revoca la clave y luego cambia cualquier cosa que pudiera haberse llevado: contraseñas de base de datos, secretos de aplicación, y cualquier token almacenado en el sitio.

Mantén la lista de claves corta. Una clave por máquina, etiquetada con el nombre de la máquina, es mucho más fácil de auditar que un montón de claves llamadas "key1", "new key" y "temp".

Solución de problemas

Permission denied (publickey). La causa más común es que tu cliente ofrece una clave diferente de la que registraste. Fuerza la correcta con ssh -i /path/to/private_key ..., o verifica con ssh -v qué claves se están ofreciendo.

Connection refused o un timeout. Confirma que estés usando el puerto que aparece en Connection details y no el puerto predeterminado 22. Copia el comando SSH de la página en lugar de escribirlo.

Bad permissions on the private key. OpenSSH rechaza una clave privada que otros usuarios pueden leer. Ejecuta chmod 600 en el archivo.

The key works for SSH but not SFTP. Comparten las mismas credenciales, así que esto casi siempre es el cliente en lugar de la clave. Usa el comando SFTP copiado de la página, que ya contiene el puerto correcto.

A dónde ir después

Uploading Files With SFTP cubre el lado de transferencia de archivos de las mismas credenciales.
Connecting To Your Database Over an SSH Tunnel usa la clave que acabas de agregar para llegar a MySQL desde un cliente de escritorio.
Site Activity Log registra cada clave que agregas, así puedes verificar más tarde quién agregó qué y cuándo.