SSH Manual for Beginners: Connect to a Server, Use Keys, and Fix Common Errors

Overview

This guide is a step by step SSH beginner tutorial built around the tasks most people actually need: connect once, connect repeatedly without a password, and recover when something breaks.

SSH, short for Secure Shell, is a secure way to open a remote terminal session on another machine. In practice, that usually means connecting from your local computer to a Linux server over the network. You type commands on your machine, but they run on the remote host.

For beginners, the core SSH workflow is simpler than the surrounding terminology makes it seem:

• You need a server address or hostname.
• You need a username on that server.
• You need a way to authenticate, usually a password at first or an SSH key pair for long-term use.
• You need the SSH service on the server to accept your connection.

A basic SSH connection command usually looks like this:

ssh username@server-ip-or-hostname

Example:

ssh admin@203.0.113.10

If the server listens on a non-default port, include it with -p:

ssh -p 2222 admin@203.0.113.10

The first time you connect, SSH usually asks you to confirm the server fingerprint. This is normal. It is there to help you verify that you are connecting to the expected machine rather than an impostor host.

For repeated access, key-based authentication is generally the cleaner setup. You generate a private key and a public key. The private key stays on your device. The public key goes to the server in the correct account. Once permissions and paths are correct, SSH can authenticate without asking for the account password each time.

If you are brand new, think of SSH as three layers:

1. Network reachability: can your computer contact the server and port?
2. Server acceptance: is the SSH service running and configured to allow your account and auth method?
3. Identity: did you present the right username, password, or key?

Most SSH troubleshooting falls neatly into one of those three layers.

Checklist by scenario

Use these checklists as a quick start guide depending on what you are trying to do.

Scenario 1: First-time SSH login with a password

Use this when a host is already provisioned and you were given a server IP, username, and password.

1. Open a terminal on macOS or Linux. On Windows, use PowerShell, Windows Terminal, or another SSH-capable terminal.
2. Run:

ssh username@server-ip

3. If a host authenticity prompt appears, verify the host details if possible, then accept.
4. Enter the password when prompted. It will not display as you type.
5. Once connected, confirm where you are:

whoami
hostname
pwd

If login fails immediately, check the username first. A surprising number of SSH issues come from using the wrong account, such as root when only a standard admin user is allowed.

Scenario 2: Generate an SSH key pair

This is the foundation of any SSH key setup tutorial. Create the key pair on the device you will connect from.

1. Open a terminal.
2. Generate a modern key pair. A common choice is:

ssh-keygen -t ed25519 -C "your-email-or-label"

3. Press Enter to accept the default save path unless you need a custom filename.
4. Set a passphrase if you want extra protection for the private key.
5. Confirm the generated files exist, typically in ~/.ssh/. You will usually see a private key and a matching .pub file.

The private key must remain private. The public key is the one you copy to servers.

Scenario 3: Copy your public key to the server

The goal is to place your public key in the remote user's ~/.ssh/authorized_keys file.

If your environment supports a helper command, use it:

ssh-copy-id username@server-ip

If not, do it manually:

1. Display your public key:

cat ~/.ssh/id_ed25519.pub

2. Copy the entire single-line output.
3. Log in to the server with your password.
4. Create the SSH directory if needed:

mkdir -p ~/.ssh
chmod 700 ~/.ssh

5. Append the public key to the authorized keys file:

nano ~/.ssh/authorized_keys

6. Paste the key on its own line, save, then set permissions:

chmod 600 ~/.ssh/authorized_keys

7. Log out and test a fresh connection.

Scenario 4: Connect with a specific key

If you use multiple identities or a non-default filename, point SSH to the right private key.

ssh -i ~/.ssh/my_key username@server-ip

If this works and you do not want to type the full command every time, create a local SSH config entry:

Host myserver
    HostName 203.0.113.10
    User admin
    IdentityFile ~/.ssh/my_key
    Port 22

Save that in ~/.ssh/config, then connect with:

ssh myserver

This is one of the easiest quality-of-life improvements in any SSH instruction manual.

Scenario 5: Use an SSH agent so you do not retype your passphrase constantly

If your private key has a passphrase, an SSH agent can cache it for your session.

1. Start the agent if your environment does not already do so.
2. Add your key:

ssh-add ~/.ssh/id_ed25519

3. Enter your key passphrase once.
4. Try connecting again.

This does not remove the passphrase from the key. It simply reduces repetition while preserving a useful security layer.

Scenario 6: Transfer a file over SSH

Once SSH works, file transfer often comes next. Use scp for simple cases:

scp localfile.txt username@server-ip:/remote/path/

Or copy a remote file to your machine:

scp username@server-ip:/remote/path/file.txt .

If you are automating API checks or testing endpoints after login, you may also want to pair SSH access with command-line tools. See the cURL Command Guide for Beginners for a practical walkthrough.

Scenario 7: Basic SSH troubleshooting checklist

When SSH fails, check these in order before changing server settings randomly:

1. Are you using the correct hostname or IP address?
2. Are you using the correct port?
3. Are you using the correct username?
4. Can you reach the host over the network?
5. Is the server's SSH service running?
6. Does your account allow the authentication method you are trying?
7. Are key file permissions correct on both client and server?
8. Are you offering the key you think you are offering?

That sequence saves time because it moves from simple input errors to more specific configuration issues.

What to double-check

This section is your SSH troubleshooting guide for the details that commonly cause a connection to fail even when the overall setup seems correct.

Username and account type

Different providers use different default usernames. Some systems expect a named admin account instead of root. Others disable direct root login altogether. If password or key authentication keeps failing, verify the account name before anything else.

Port number

SSH defaults to port 22, but some servers use another port. If the port is wrong, you may see a timeout, a refusal, or a misleading sense that the host is down.

Private key versus public key

The file ending in .pub is the public key and belongs on the server. The file without that extension is the private key and stays on your local machine. Mixing them up is a classic beginner problem.

Permissions on the server

SSH can reject a valid key if the remote directory or file permissions are too open. The common safe pattern is:

• ~/.ssh set to 700
• ~/.ssh/authorized_keys set to 600

If you copied the key correctly but authentication still falls back to a password, check permissions next.

Permissions on your local private key

Your local private key should not be world-readable. A typical safe permission is:

chmod 600 ~/.ssh/id_ed25519

Some SSH clients will warn or refuse to use a private key if the file permissions are too broad.

Wrong identity being offered

If you have several keys on one workstation, the client may offer the wrong one first. In that case, use -i to specify the key explicitly or configure the host in ~/.ssh/config.

Host key mismatch warnings

If SSH warns that the remote host identification has changed, pause before deleting anything. A changed host key can be harmless, such as after rebuilding a server, but it can also mean you are connecting to a different machine than expected. Confirm the change before removing the old known host entry.

Firewall and network path

If the connection hangs, the problem may be outside SSH itself. The server may be unreachable, the port may be blocked, or the machine may be offline. This is especially worth checking if you recently changed cloud security rules, office networks, VPN settings, or home router rules.

Verbose output for diagnosis

When you need more detail, ask SSH to explain what it is doing:

ssh -v username@server-ip

For more detail, you can use -vv or -vvv. Read the output for clues about which key is offered, whether a config file is being used, and where the connection stops.

Common mistakes

If you want to know how to fix SSH problems quickly, avoid these common errors first. They account for a large share of beginner support requests.

Trying to solve every issue from the client side only

Sometimes the problem is simply that the SSH service is not running on the server, the server has a bad firewall rule, or the account is not enabled. Client commands cannot fix a server that is not accepting connections.

Pasting the public key with extra breaks or missing characters

An SSH public key should usually be one uninterrupted line in authorized_keys. If your terminal, clipboard tool, or text editor wraps or truncates it, the key may become invalid.

Editing the wrong user's home directory

If you log in as one user and paste the key into another user's intended account path incorrectly, key login will fail. Make sure the public key is placed in the home directory of the exact account you plan to use.

Disabling password authentication too early

Before tightening SSH access, test that key login works in a separate session. Otherwise, you may lock yourself out of the server. This is one of the most important items to remember before hardening SSH.

Assuming all keys and defaults are interchangeable forever

SSH defaults evolve over time. Key preferences, supported algorithms, and service configuration choices can change across operating systems and distributions. If a tutorial worked years ago, re-check it against your current environment before forcing old settings into a new system.

Ignoring local config files

Your own ~/.ssh/config can silently influence hostnames, ports, users, and identity files. If SSH behaves differently from what the command suggests, inspect that file.

Skipping basic security hygiene

Use a passphrase on important private keys, keep backups of keys you cannot easily recreate, and remove public keys from servers when a device is retired or a team member no longer needs access. If you are building a broader admin setup, pairing SSH with account protection is a good next step; see How to Set Up Two-Factor Authentication on Google, Microsoft, Apple, and GitHub for a practical security checklist.

When to revisit

This final checklist is the one to return to whenever your SSH workflow changes. SSH is not a one-time setup guide; it is a small system that should be reviewed whenever devices, servers, or access rules change.

Revisit your SSH setup when:

• You buy a new laptop or move to a new workstation.
• You rebuild, replace, or clone a server.
• You switch hosting providers, VM images, or operating system versions.
• You change usernames, ports, or login policies.
• You add a new team member or remove an old one.
• You suspect a lost device, exposed private key, or stale access path.
• Your old commands suddenly stop working after an update.

Use this practical refresh routine:

1. Confirm inventory: list the servers and host aliases you still use.
2. Review keys: identify which private keys are active on your machine and which public keys remain on servers.
3. Prune old access: remove unused keys from authorized_keys and clean obsolete entries from ~/.ssh/config.
4. Retest access: open a fresh connection to each important host and verify the expected username, port, and key are used.
5. Document exceptions: note non-standard ports, jump hosts, or service-specific login rules so you do not rediscover them during an outage.
6. Check dependent workflows: if you use SSH for Git, file sync, deployments, or remote API testing, verify those tasks still work too.

A simple personal SSH user manual can help: keep one note with your host aliases, expected usernames, key names, and any non-default ports. That small habit turns future SSH troubleshooting from guesswork into routine maintenance.

If your machine itself is acting unpredictably while you troubleshoot terminal sessions, network behavior, or local key handling, it may help to resolve local performance issues first. For that, see How to Fix a Slow Computer: Step-by-Step Checks for Windows and Mac.

In short, the reusable SSH checklist is: verify host, verify user, verify port, verify auth method, verify permissions, then inspect verbose output before changing anything major. If you follow that order, most connection issues become easier to explain and faster to fix.