# SSH

URL: https://docs.vaultpanel.net/guides/security/ssh

> Control root sign-in, password sign-in and sign-in attempts, move SSH to another port, manage authorized keys and set the login message.

VaultPanel manages the OpenSSH server on each server: who may sign in and how, which port SSH listens on, and the public keys of root and other login accounts. Every change is tested before SSH reloads, and the agent refuses any change that would leave no administrator able to sign in.

Open **Security > SSH** and pick a server, or the **SSH** card on a server's **Security** tab. Viewing needs `security.read`; changes need `security.manage`.

## Sign-in settings

| Setting | Options |
| --- | --- |
| **Root sign-in** | **Allowed**: root can sign in with a password or a key. **Keys only**: root can sign in only with an SSH key. **Not allowed**: root cannot sign in over SSH; use another user and `sudo`. |
| **Allow password sign-in** | Turn this off once you sign in with an SSH key. Keys cannot be guessed. |
| **Sign-in attempts per connection** | 1 to 10. Fewer attempts slow down password guessing. |

Click **Save SSH settings**. The agent writes `/etc/ssh/sshd_config.d/00-vaultpanel.conf`, tests it with `sshd -t`, checks the effective settings with `sshd -T`, then reloads SSH. Open sessions stay connected. If any step fails, the previous file is put back.

> **Tip:**
The safe setup is **Root sign-in: Keys only** with password sign-in off. Add your key first, then sign in with it in a second terminal before you turn passwords off.

### When a setting does not apply

`sshd` uses the first value it reads for an option. If `/etc/ssh/sshd_config` sets the same option above its `Include /etc/ssh/sshd_config.d/*.conf` line, the change fails with `SSHD_OVERRIDDEN`: remove or comment out that line and save again. VaultPanel's file is read before other drop-ins such as `50-cloud-init.conf`. `SSHD_CONFIG_INVALID` shows what `sshd -t` said; the previous settings stay.

## SSH keys

The keys card lists the authorized keys of root (`/root/.ssh/authorized_keys`) with their comment, type and fingerprint. From agent 0.34.0 the account menu next to **Add key** also lists every account people can sign in to: those with a login shell and a user ID from 1000.

**Add key** takes one public key line, for example the contents of `~/.ssh/id_ed25519.pub`. Supported types are `ssh-ed25519`, `ssh-rsa`, `ecdsa-sha2-nistp256`, `ecdsa-sha2-nistp384`, `ecdsa-sha2-nistp521`, `sk-ssh-ed25519@openssh.com` and `sk-ecdsa-sha2-nistp256@openssh.com`. Options in front of the key, such as `from=` or `command=`, are not accepted.

Create a key on your computer if you do not have one:

```bash
ssh-keygen -t ed25519
cat ~/.ssh/id_ed25519.pub
```

Another account's keys are written by a small helper that first switches to that account's own user, so a `.ssh` folder or key file replaced by a symbolic link cannot redirect the write. A symlinked `authorized_keys` is refused.

The **Administrator accounts** list shows root and the members of `sudo`, `admin` or `wheel`, with how many keys each has and whether a password is set.

## Lockout protection

The agent refuses an SSH settings change, or removing a key, that would leave no administrator account (root, or a member of `sudo`, `admin` or `wheel` with a login shell) able to sign in with a key or a password. The card warns you before you save when no administrator who could still sign in has a key. Refused changes fail with `LOCKOUT_REFUSED`.

## Change the SSH port

Moving SSH off port 22 cuts down on automated password guessing. This needs agent 0.34.0 or newer.

### Add the new port

Click **Change port** and enter a free port, usually from 1024 to 65535. Leave **Keep port 22 open too for now** ticked: SSH then listens on both ports while you move.

The agent refuses the panel's port, ports 80 and 443, and a port another program listens on (`PORT_IN_USE`). When the firewall is on, it opens the new port first. It then writes the `Port` lines, tests with `sshd -t` and `sshd -T`, and restarts SSH. The change is only kept once SSH answers on every port; otherwise the old file comes back (`SSH_NOT_LISTENING`). Open sessions stay connected.

### Sign in on the new port

```bash
ssh -p 2222 root@203.0.113.10
```

A firewall at your hosting provider, such as a cloud security group, may need the new port opened too.

### Close the old port

Back in the panel, click **Close port 22**. SSH then listens on the new port alone, and VaultPanel removes the firewall rule it had added for the old one.

Fail2ban's SSH jail follows the new ports automatically.

## Login message

The **Login message** card sets what someone sees when they sign in over SSH or open the [terminal](https://docs.vaultpanel.net/guides/servers/terminal). This needs agent 0.21.0 or newer.

| Mode | What is shown |
| --- | --- |
| **VaultPanel only** (default) | The VaultPanel banner with its links (website, documentation, best practices, the panel's address and the `vaultpanel` command), then the "Last login" line |
| **System message** | The operating system's own welcome text, help links, news and update notices |

**Show the system's message** and **Show only VaultPanel** switch between them. Switching back restores the system's message exactly as it was.

## Failed sign-ins

**Failed SSH sign-ins** summarizes failed attempts over the last 24 hours from the system journal, by address. **Block** adds a [firewall](https://docs.vaultpanel.net/guides/security/firewall) deny rule for one address. To block repeat offenders automatically, turn on [Fail2ban](https://docs.vaultpanel.net/guides/security/fail2ban-and-updates).

## If you get locked out

Use your hosting provider's web console, remove `/etc/ssh/sshd_config.d/00-vaultpanel.conf` and run `systemctl reload ssh`. After a port change, connect with `ssh -p <port>`, and check `journalctl -u ssh` if SSH did not answer on the new port.
