Connect via SSH¶

SSH gives you an encrypted connection to your Asteroid's shell. You type commands on your computer; once connected, they run on your Asteroid. This Howto takes you from opening a terminal to finding your website directory.

Starting your local shell¶

Open Terminal on macOS or Linux, or Windows Terminal / PowerShell on Windows. Your terminal's colors and prompt may look different from ours.

In the examples, [localuser@localhost ~]$ marks a command on your computer; [isabell@moondust ~]$ marks one on the Asteroid. Type only what follows the $, then press Enter. All output below is illustrative.

[localuser@localhost ~]$ whoami
localuser

Use your terminal's copy and paste shortcuts. On many Linux terminals they are Ctrl+Shift+C and Ctrl+Shift+V; on macOS they are Command+C and Command+V. Ctrl+C usually interrupts a running command.

Connecting via SSH¶

Prepare the SSH command¶

Check that an SSH client is available:

[localuser@localhost ~]$ ssh -V
OpenSSH_10.0p2, OpenSSL 3.5.0 8 Apr 2025

Your version will vary. If the command is missing, install your operating system's OpenSSH client. On Windows, see Microsoft's OpenSSH installation instructions. You do not need to run an SSH server on your computer.

Sign in to the Uberspace dashboard, select your Uberspace 8 Asteroid, and find its connection details:

Username: the Asteroid's name, for example isabell.
Hostname: its server, for example moondust.uberspace.de.
Authentication: an SSH password configured for that Asteroid, or an SSH key you have already added.

The dashboard password and the Asteroid's SSH password are separate. If you want to start with a password, set an SSH password in the selected Asteroid's SSH settings first. Do not use the fictional hostname in our examples.

Replace both the username and hostname with your own:

[localuser@localhost ~]$ ssh isabell@moondust.uberspace.de
The authenticity of host 'moondust.uberspace.de (...)' can't be established.
ED25519 key fingerprint is SHA256:<fingerprint shown by SSH>.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

Before accepting, compare the host key fingerprint with the same key type in your Asteroid's dashboard connection details. It identifies the server, not your personal SSH key. The placeholder above is not a real fingerprint.

If the fingerprints differ, stop and check the hostname. If it is correct, contact support. Do not bypass the check or delete a saved host key merely to silence a warning.

Continue and provide password¶

When the fingerprint matches, answer yes. SSH remembers the host for future connections. Enter your SSH password when prompted; nothing appears as you type, not even dots. Example, with the welcome message shortened:

Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added 'moondust.uberspace.de' (ED25519) to the list of known hosts.
isabell@moondust.uberspace.de's password:
Welcome to Uberspace 8!

Current version: v8.0.97
...
[isabell@moondust ~]$

The server prompt means you are connected. Commands now run on your Asteroid.

First steps on your uberspace shell¶

Find your current directory and your web directory:

[isabell@moondust ~]$ pwd
/home/isabell
[isabell@moondust ~]$ cd /var/www/virtual/$USER/html
[isabell@moondust html]$ pwd
/var/www/virtual/isabell/html
[isabell@moondust html]$ ls
nocontent.html

cd changes the directory and prints nothing on success; ls lists its contents, which depend on what you have installed. $USER expands to your Asteroid's username. On Uberspace 8, ~/www/html also reaches this default DocumentRoot.

Return to your home directory, then close the connection:

[isabell@moondust html]$ cd
[isabell@moondust ~]$ exit
logout
Connection to moondust.uberspace.de closed.

You are back in your local shell. Next, set up SSH keys or publish a website. The SSH chapter in the Manual covers connection aliases and troubleshooting.