SSH

Unlike other providers, the native way to create things and work on your Uberspace is the command-line via SSH. If you are inexperienced with this, please first head over to our how to Use SSH keys Guide.

Connection basics

You can connect to your Asteroid with a basic ssh command:

[localuser@localhost ~]$ ssh isabell@moondust.uberspace.de
Welcome to Uberspace 8!

Current version: v8.0.56

Manual: https://u8manual.uberspace.de
Lab - guides and inspirations for apps: https://lab.uberspace.de

Watch out for changes at: https://u8manual.uberspace.de/changelog
Follow us in the fediverse for updates: https://uberspace.social/@ubernauten

Is something unclear or does not work as expected?
 => check the server status: https://is.uberspace.online
 => reach out to our team: hallo@uberspace.de

[isabell@moondust ~]#

Tip:

USERNAME is the name of your Asteroid, HOSTNAME is the name of the server where your Asteroid is located

Using a config file

Especially when using connections to multiple Asteroids, it helps to manage them in a SSH config file.

On your local system, create a file ~/.ssh/config and set the correct permissions:

[localuser@localhost ~]$ touch ~/.ssh/config
[localuser@localhost ~]$ chmod 600 ~/.ssh/config
[localuser@localhost ~]$

Add a basic config like this:

Host uberspace.isabell
  Hostname moondust.uberspace.de
  User isabell

From then on, you can connect with:

[localuser@localhost ~]$ ssh uberspace.isabell
Welcome to Uberspace 8!

Current version: v8.0.56

Manual: https://u8manual.uberspace.de
Lab - guides and inspirations for apps: https://lab.uberspace.de

Watch out for changes at: https://u8manual.uberspace.de/changelog
Follow us in the fediverse for updates: https://uberspace.social/@ubernauten

Is something unclear or does not work as expected?
 => check the server status: https://is.uberspace.online
 => reach out to our team: hallo@uberspace.de

[isabell@moondust ~]#

You’re free to choose the Host name. You can also use wildcards (*) and many other config options.

Authentification

SSH keys

You can authenticate with public key authentication. Authorized keys enable secure login by verifying a user's public key against a corresponding private key on the server.

See our how to Use SSH keys Guide for more information and a step by step guide to get you started with your own keys.

Don't edit ~/.ssh/authorized_keys_uberspace

We use two authorized keys files: ~/.ssh/authorized_keys and ~/.ssh/authorized_keys_uberspace. If you want to add keys manually please only use ~/.ssh/authorized_keys.

You can add your public keys using the web interface and with the uberspace tool:

[isabell@moondust ~]$ uberspace sshkey

Usage: uberspace sshkey [OPTIONS] COMMAND [ARGS]...

Manage SSH keys for asteroids on this host.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                  │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ add    Add SSH key to existing asteroid on this host.                        │
│ list   List SSH keys for an existing Asteroid on this host.                  │
│ del    Delete SSH key for an existing Asteroid on this host.                 │
╰──────────────────────────────────────────────────────────────────────────────╯

Let's add a key:

[isabell@moondust ~]$ uberspace sshkey add "ssh-rsa AAAAB3NzaC...tHgV4YxQ== isabell laptop"

List your keys with uberspace sshkey list:

[isabell@moondust ~]$ uberspace sshkey list
PK: 16
ssh-rsa AAAAB3NzaC...tHgV4YxQ== isabell laptop

Remove a key with uberspace sshkey del:

[isabell@moondust ~]$ uberspace sshkey del 16
OK: The SSH key 'ssh-rsa AAAAB3NzaC...tHgV4YxQ==
isabell laptop' has been removed from your Asteroid

Password

You can also use a password to authentificate your identity against your Asteroid. Use the uberspace tool:

[isabell@moondust ~]$ uberspace ssh password set MySuperSecretPassword
OK: Set SSH password to your Asteroid

You can also remove an existing password to only be able to use keys:

[isabell@moondust ~]$ uberspace ssh password del
OK: Delete SSH password from your Asteroid

Troubleshooting

If your connection fails, SSH may not show a clear error. Use verbose mode with -v, or even -vvv for more details:

[localuser@localhost ~]$ ssh isabell@moondust.uberspace.de -vvv
[…]

The output can help identify whether the correct keys and configs are used.