📘

Public Key Authentication

SSH public-key authentication provides a secure and convenient way to access your Ultra service. Your device keeps a private key, while your Ultra service stores the matching public key. During login, your SSH client proves that it holds the private key without sending that key to the server.

Keep your private key secure: Never upload, share, email, or paste your private key into your Ultra service. Only add the public key. Protect the private key with a passphrase whenever possible.

This guide explains how to:

Generate an SSH key pair with OpenSSH or PuTTYgen.
Add the public key to your Ultra service.
Connect with SSH key authentication.
Remove an old public key.
Troubleshoot common key-authentication problems.

Prepare for Setup

You will need:

An Ultra service with SSH access.
Your Ultra service username.
Your hostname or service IP address.
Your SSH/FTP password for the initial connection.
An SSH client such as OpenSSH or PuTTY.
Port 22.

Find your hostname, IP address, and username in the Connect tab of the User Control Panel.

Hostname: <servername>.usbx.me or <service-IP-address>
Username: <your-Ultra-username>
Password: <your-SSH/FTP-password>
Port: 22

Use your service username: Enter your Ultra service username when connecting with SSH. Do not enter your Client Area email address.

If you have not connected to your service before, see Connect to your Ultra slot via SSH.

Configure OpenSSH

OpenSSH is available on Linux, macOS, Windows 10, and Windows 11.

Generate an Ed25519 Key

Open PowerShell, Command Prompt, or a terminal on your device.
Run:

ssh-keygen -t ed25519

Press Enter to accept the default file location.

The default files are normally stored in the following locations:

Linux or macOS:
~/.ssh/id_ed25519
~/.ssh/id_ed25519.pub

Windows:
C:\Users\<username>\.ssh\id_ed25519
C:\Users\<username>\.ssh\id_ed25519.pub

Enter a strong passphrase when prompted.
Enter the same passphrase again.
The file without the .pub extension is your private key. Keep it on your device. The file ending in .pub is the public key that you can add to your Ultra service.

Do not expose the private key: Anyone with access to your private key and its passphrase may be able to access services that trust the key. Only copy or upload the file ending in .pub.

Generate an RSA Key

Use RSA only when you require compatibility with software that does not support Ed25519.

ssh-keygen -t rsa -b 4096

Do not generate DSA keys.

Add the Key With ssh-copy-id

Use ssh-copy-id when it is available on your device.
Run:

ssh-copy-id -i ~/.ssh/id_ed25519.pub <username>@<servername>.usbx.me

Replace the username and hostname with the values shown in the UCP Connect tab.
Review the host-key prompt.
Confirm that the hostname matches your Ultra service.
Enter yes if this is your first connection to the expected host.
Enter your SSH/FTP password.
The command adds the selected public key to ~/.ssh/authorized_keys on your Ultra service.
If macOS does not provide ssh-copy-id, install it with Homebrew:

brew install ssh-copy-id

Test the Key

Keep the current password-authenticated session open while testing the key.

Open a second terminal window.
Run:

ssh <username>@<servername>.usbx.me

Enter the private-key passphrase if prompted.
Confirm that the Ultra shell opens successfully.
If you saved the private key in a non-default location, specify its path:

ssh -i <path-to-private-key> <username>@<servername>.usbx.me

Close the original session only after confirming that key authentication works.

Add the Key Manually

Use this method if ssh-copy-id is unavailable.

Copy the Public Key

On Linux or macOS, display the public key with:

cat ~/.ssh/id_ed25519.pub

On Windows PowerShell, run:

Get-Content "$env:USERPROFILE\.ssh\id_ed25519.pub"

Copy the complete public-key line.
Confirm that it begins with a key type such as ssh-ed25519.

Copy only the public key: Copy the contents of the file ending in .pub. Never copy or paste the private-key file into your Ultra service.

Prepare the Key File

Connect to your Ultra service using your SSH/FTP password.
Run:

umask 077
mkdir -p ~/.ssh
touch ~/.ssh/authorized_keys
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
cat >> ~/.ssh/authorized_keys

Paste the complete public key as one uninterrupted line.
Press Enter.
Press Ctrl+D to finish.
The permissions allow your account to access the SSH configuration while preventing other users from changing it.

Test the Manual Setup

Keep the current session open while testing the key.

Open another terminal.
Run:

ssh <username>@<servername>.usbx.me

Enter the private-key passphrase if prompted.
Confirm that the Ultra shell opens.
If you saved the key in a non-default location, run:

ssh -i <path-to-private-key> <username>@<servername>.usbx.me

Configure PuTTY

PuTTY and PuTTYgen provide a graphical SSH workflow for Windows.

Download PuTTY from the official PuTTY download page.
Install PuTTY.
Open PuTTYgen.

Generate an Ed25519 Key

Select Ed25519 under Parameters.
Click Generate.
Move the pointer within the blank area if PuTTYgen requests additional randomness.
Enter a descriptive value in Key comment.
Enter a strong passphrase in Key passphrase.
Enter the same passphrase in Confirm passphrase.
Click Save private key.
Save the private key as a .ppk file in a secure location.

Use a key passphrase: A passphrase encrypts the private-key file stored on your device. Avoid saving an unencrypted private key unless you have a specific requirement and understand the security risk.

Copy the PuTTY Public Key

Copy the complete value from Public key for pasting into OpenSSH authorized_keys file.
Confirm that the public key remains on one line.
Connect to your Ultra service using your SSH/FTP password.
Run:

umask 077
mkdir -p ~/.ssh
touch ~/.ssh/authorized_keys
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
cat >> ~/.ssh/authorized_keys

Paste the public key.
Press Enter.
Press Ctrl+D.

Use the OpenSSH public-key value: Copy the value from Public key for pasting into OpenSSH authorized_keys file. Do not paste the contents of the .ppk file.

Select the PuTTY Private Key

Open PuTTY.
Load your saved Ultra session.
Go to Connection → SSH → Auth → Credentials.
Find Private key file for authentication.
Click Browse.
Select the .ppk private-key file.
Return to Session.
Click Save.
Open the connection.
Enter the private-key passphrase when prompted.

Keep an existing password-authenticated connection open until the PuTTY key login succeeds.

Remove an Old Public Key

Remove a public key when you replace it, lose the corresponding device, or suspect that the private key was exposed.

Connect to your Ultra service with another working key or your SSH/FTP password.
Open the authorized-keys file:

nano ~/.ssh/authorized_keys

Find the complete line for the old public key.
Delete that line.
Save the file by pressing Ctrl+O.
Press Enter to confirm the filename.
Exit by pressing Ctrl+X.
Confirm that another authentication method works before closing the current session.

Replace exposed keys immediately: If someone may have obtained your private key, remove its public key from authorized_keys and generate a new key pair.

Troubleshoot Key Authentication

Fix Permission Denied

If SSH displays Permission denied (publickey):

Confirm that you are using your Ultra service username.
Confirm that the hostname or IP address matches the UCP Connect tab.
Confirm that the port is 22.
Confirm that the public key is one uninterrupted line in ~/.ssh/authorized_keys.
Confirm that you added the public key, not the private key.
Apply the required permissions:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

If the private key uses a non-default filename, specify it with i.
Run a verbose connection test:

ssh -v -i <path-to-private-key> <username>@<servername>.usbx.me

Review logs before sharing them: Verbose SSH output may contain usernames, hostnames, IP addresses, and other identifying information. Remove sensitive information before posting the output or sending it to another person.

Select the Correct Key

If SSH tries the wrong key, specify the required private key:

ssh -i <path-to-private-key> <username>@<servername>.usbx.me

When using ssh-copy-id, specify the matching public key:

ssh-copy-id -i <path-to-public-key.pub> <username>@<servername>.usbx.me

Enter the Key Passphrase

A private-key passphrase prompt is normal. The passphrase protects the private-key file stored on your device.

The key passphrase is separate from your Ultra SSH/FTP password.

Handle a Changed Host Key

If SSH displays REMOTE HOST IDENTIFICATION HAS CHANGED:

Do not bypass the warning without confirming why the host key changed.
Check whether your Ultra service was recently migrated or moved.
Confirm that you are using the current hostname or IP address from the UCP.
Contact Ultra support if the change is unexpected.

Stop if the change is unexpected: An unexpected host-key change can indicate that you entered the wrong hostname or that another system is intercepting the connection.

If you require further assistance, you can open a support ticket here.