Insights

SSH remote access: connect, choose a method and troubleshoot

Learn how to connect with SSH, set up an Ubuntu server, use keys, choose a jump host or service tunnel, and troubleshoot login failures.

Illustration of desktop terminal with integrated keyboard.
On this page

Secure Shell (SSH) lets you log into a remote computer and run commands over an encrypted connection. With an SSH client installed, run ssh username@host using your account on that computer.

In short:

  • Remote access. SSH gives you an encrypted remote shell, not a full desktop.
  • Connection requirements. You need a running SSH server, an approved network route and an account password or SSH key.
  • Server identity. Check the server's host-key fingerprint against a trusted record before accepting it.

Make your first connection

Most Linux and macOS systems have an SSH client available through Terminal. On Windows, check that the OpenSSH Client feature is installed, then use PowerShell.

Only connect to devices you're authorized to access. Keep any working session open while you test a new connection.

1. Get the remote account and address.

You need a valid remote username and a hostname or Internet Protocol (IP) address. In the commands below, replace username with your account on the remote computer and host with its name or address. Confirm the SSH port and approved network route with the administrator.

2. Start the connection from your own computer.

Run this in Linux or macOS Terminal, or Windows PowerShell with OpenSSH installed:

ssh username@host

3. Check the server's identity before accepting it.

On a first connection, compare the displayed host-key fingerprint with a trusted record or the administrator. A fingerprint identifies the server's SSH key. Don't accept an unknown key just to get past the prompt.

After that check, authenticate with your account password or configured SSH key. A protected private key may ask for its passphrase.

4. Confirm that you reached the remote shell.

A remote command prompt indicates that login succeeded. Check that it identifies the expected computer and account before running commands. Commands you enter in that session run on the remote computer.

5. End the session when you're done.

exit

You should return to your local prompt. That shows the remote shell session has ended.

If your administrator specifies a custom port, supply it with -p. This is a hypothetical example using port 2222, not a recommended port change:

ssh -p 2222 username@host

SSH normally uses port 22. Changing it isn't a substitute for strong authentication and network access restrictions.

Set up the server and key login

The remote device needs an SSH server to accept connections. The server installation steps below apply only to Ubuntu.

Only change a device you own or administer. Retain local or console access, and keep a working SSH session open while testing a new login.

1. Install and start the SSH server on Ubuntu.

Run these commands on the Ubuntu device, not on your client:

sudo apt update
sudo apt install openssh-server
sudo systemctl enable --now ssh

2. Check the service and listening port on Ubuntu.

sudo systemctl status ssh
ss -tlnp | grep ':22'

Look for an active service and a listening entry for the SSH port. Those results show that the server is running and listening locally. They don't prove another device can reach it.

If either result is missing, check the service state and configured port before trying remote login. Don't open broad network access to compensate for an unexplained failure.

3. Generate a new key on your client.

Run this in Linux or macOS Terminal, or Windows PowerShell with OpenSSH installed:

ssh-keygen -t ed25519

Choose an unused filename at the save prompt. Don't overwrite an existing key. Protect the new private key with an SSH key passphrase.

The command creates a private key and a matching public key. Keep the private key on your client. Only the public key, usually the file ending in .pub, belongs on the remote account.

4. Install the public key in the remote account.

On Linux or macOS, use ssh-copy-id when it's available and password login is authorized. Replace /path/to/new_key.pub with your new public-key file:

ssh-copy-id -i /path/to/new_key.pub username@host

On Windows, give the public-key file to the administrator for installation in your authorized account. Don't assume that ssh-copy-id is installed, and don't send the private key.

5. Test a fresh login from your client.

ssh username@host

If you saved the key under a custom filename, select it explicitly. Replace /path/to/new_key with the private-key path:

ssh -i /path/to/new_key username@host

Successful key login reaches the remote prompt without asking for the remote account password. Your private key's passphrase may still be required. If you're still asked for the account password, check which key the client offers and whether its public key is installed in the correct account.

Choose what you want to do remotely

An SSH shell is a text interface, not a full remote desktop. For files, SSH File Transfer Protocol (SFTP) lets you manage transfers over SSH. The scp secure-copy tool is another SSH-based file-transfer option.

Use this table to match your task to the method and its requirements.

Your taskSSH methodMain requirement
Interactive commandsRemote shellAuthorized SSH login
One remote commandSSH with commandLogin and command permission
File transferSFTP or scpLogin and file permissions
One application portLocal port forwardingSSH connection and reachable service
Remote developmentVS Code Remote - SSHSupported remote host and server component

SSH normally leaves you in an interactive shell. Adding a command runs that command remotely and closes the connection afterward.

Only run commands and use services you're authorized to access. Keep a working terminal session available while trying a new workflow.

1. Run one harmless command on a Linux remote target.

From Linux or macOS Terminal, or Windows PowerShell with OpenSSH installed:

ssh username@host "ls -l"

The SSH client runs locally. The quoted ls -l command runs on the Linux target. A directory listing shows that the remote command ran, and the connection then closes.

VS Code Remote - SSH installs its VS Code Server component on the remote operating system. Its commands and remote extensions run there, so the host must support that workflow. Prove that terminal login works before adding the editor.

Reach a server on a private network

Choose the route from three facts: whether your client can reach the target's SSH port, whether an approved intermediary can reach it, and whether you need a login or access to one application. An address alone doesn't prove reachability.

Use direct SSH when your client has an approved route to the target's SSH port. The target still needs a running SSH server and an account you can use.

Use a jump host when an approved intermediary provides the route to the target. Your client first connects to the jump host, which forwards the connection toward the target's SSH server. The jump host must be reachable and permitted to forward that traffic.

Use only an existing, authorized jump host and approved services. Keep a working connection or console access while testing the route.

For Linux, macOS or Windows OpenSSH clients that support -J, this hypothetical command connects through one jump host:

ssh -J jumpuser@jump-host targetuser@target-host

Replace jumpuser and jump-host with the intermediary's account and address. Replace targetuser and target-host with the final server's account and address. You must authenticate to both hosts and check each host's key against a trusted record.

Use local port forwarding when you need one service through an SSH connection. It carries traffic from a port on your own computer through SSH to the chosen service. It doesn't replace the SSH server or create a route to an otherwise unreachable SSH endpoint.

For example, remote development may require access to an application port that isn't publicly exposed. VS Code documents forwarding such a port through SSH. Keep the local listener on the loopback address, which limits access to your own device.

Before adding an editor or service tunnel, write down:

  • Destination: the final SSH server or application you need
  • Approved route: direct access or the authorized jump host
  • Goal: remote login or access to one service port

You should be able to name all three and complete terminal login through the chosen route. If login fails, check the SSH connection before adding another workflow. None of these methods grants account permissions or bypasses an administrator's access policy.

Find where the connection fails

Use the error to choose the next check, not to name a cause without evidence. Only inspect clients and servers you're authorized to administer. Keep working access and existing trust records while you investigate, and remove sensitive details before sharing logs.

These checks separate Domain Name System (DNS) name lookup, connection failures, host identity and account authentication.

What you seeNext checkWhat it shows
Name lookup failureHost spelling and DNS resultAddress returned for the name
Timeout or refusalDestination, port, route and server stateWhere connection progress stops
Host-key warningFingerprint against trusted recordWhether the key matches expectations
Authentication rejectedAccount, offered key and server logsCredentials offered and rejection details

A timeout doesn't prove a firewall caused it. A refusal or closed connection doesn't identify one faulty device or intermediary. An authentication rejection doesn't prove that the private key is missing.

1. Collect client-side connection details.

On Linux or macOS Terminal, or Windows PowerShell with OpenSSH installed:

ssh -vvv username@host

Look for the destination and port, connection progress, host-key checks and authentication attempts. These details help locate the stage that fails. They don't necessarily name the underlying cause.

2. Compare server events on Ubuntu.

On the authorized Ubuntu server, watch the SSH service log while retrying from the client:

sudo journalctl -fu ssh

A matching event shows that the server recorded the attempt and may explain a rejection. If no matching event appears, check the destination, port and route. A missing log entry alone doesn't prove which part failed.

3. Check changed host keys independently.

SSH warns when a stored server fingerprint changes. Confirm the current key through the administrator or another trusted channel before changing your trust record. Don't automatically delete the old entry or accept the new key.

Where doxx.net fits. doxx.net is a private network for people and agents, run on its own IP space, DNS root and hardware. SSH server setup and account permissions remain separate requirements, but you can create a doxx.net account, download the app and connect a device or agent to try the private network.

Ask an AI assistant

Share this article

Private Everywhere

Stop giving the internet everything

Keep your browsing, messages, files, and agents private.