Use SSH keys¶

An SSH key pair lets your Asteroid recognize your computer without asking for the Asteroid's SSH password. Keep the private key on your computer and give Uberspace only the public key. Protect the private key with a passphrase.

Use a separate pair for each device, so you can revoke a lost device's access without replacing all your keys. First, open your local terminal. Outputs below are examples; paths and fingerprints differ on your computer.

Generate the key on your local system¶

Run this on your own computer, not on the Asteroid:

[localuser@localhost ~]$ ssh-keygen -t ed25519 -a 100
Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/localuser/.ssh/id_ed25519):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/localuser/.ssh/id_ed25519
Your public key has been saved in /home/localuser/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:<your new key fingerprint> localuser@localhost
...

Accept the suggested filename only if it does not already exist. Do not overwrite an existing key: it may still be needed elsewhere. You can use an existing key or choose another filename; use that filename in later commands. The default directory is under /Users/ on macOS and your user profile on Windows.

Enter a strong passphrase twice. The terminal hides your input. The OpenSSH key generator creates:

id_ed25519: your private key. Never upload or paste it into a dashboard.
id_ed25519.pub: your public key, which you can add to your Asteroid.

Add the public ssh key to your Uberspace¶

Display the public file locally, or open it in a text editor:

[localuser@localhost ~]$ cat ~/.ssh/id_ed25519.pub
ssh-ed25519 AAAA...your-public-key... localuser@localhost

The example is shortened. Copy the entire line from your own file, starting with ssh-ed25519, including its comment if present.

Add the public ssh key via Uberspace Dashboard¶

Open the dashboard, select your Uberspace 8 Asteroid, and add the public key in its SSH settings. This also works if you have not configured an SSH password.

Add the public ssh key on your Uberspace¶

If you are already connected, you can instead add the public key with Uberspace 8's CLI. Replace the shortened example with the full line from your .pub file. Example output is abbreviated:

[isabell@moondust ~]$ uberspace ssh key add 'ssh-ed25519 AAAA...your-public-key... localuser@localhost'
OK: Added SSH key 'ssh-ed25519 AAAA...your-public-key... localuser@localhost' to your Asteroid
...

Allow the configuration change to finish before testing a new login.

Keep Uberspace's key file intact

Uberspace 8 manages platform keys separately in ~/.ssh/authorized_keys_uberspace. Do not edit that file. If you choose to manage authorized keys manually, use ~/.ssh/authorized_keys and preserve its existing entries. The dashboard or CLI is enough for the setup described here.

Keep your current connection open and test from a second local terminal. Explicitly selecting the private key also works if you chose a custom filename:

[localuser@localhost ~]$ ssh -i ~/.ssh/id_ed25519 isabell@moondust.uberspace.de
Enter passphrase for key '/home/localuser/.ssh/id_ed25519':
Welcome to Uberspace 8!
...
[isabell@moondust ~]$

The passphrase unlocks your local private key. It is not your dashboard password or your Asteroid's SSH password. SSH may skip this prompt when an agent has already unlocked the key. If it asks for the Asteroid's password instead, check the key, username, and selected Asteroid before removing any working login method.

Add your key to the ssh-agent¶

An SSH agent can hold an unlocked key in memory during your local session. If an agent is available, add your key on your computer:

[localuser@localhost ~]$ ssh-add ~/.ssh/id_ed25519
Enter passphrase for /home/localuser/.ssh/id_ed25519:
Identity added: /home/localuser/.ssh/id_ed25519 (localuser@localhost)

If no agent is running, follow your operating system's instructions for starting one. Agent setup differs between Linux, macOS, and Windows. You can continue to use the key with its passphrase without an agent.

See the Manual's SSH chapter for listing and removing keys. If a device is lost, remove its public key from every Asteroid where you added it.