How to Set Up SSH on macOS: A Step-by-Step Guide for Beginners

Introduction / Why This Is Needed

SSH (Secure Shell) is a protocol for secure remote management of servers and other computers. On macOS, the SSH client is built-in by default, making it a convenient tool for developers, system administrators, and anyone working with remote systems. In this guide, you will learn how to configure an SSH connection on your Mac, generate cryptographic keys for authentication, and troubleshoot common issues. After completing these steps, you will be able to quickly and securely connect to Linux servers, virtual machines, or other devices that support SSH.

Prerequisites / Preparation

Before you begin, ensure that:

• You have access to macOS (version 12 Monterey or newer).
• You have basic knowledge of using Terminal.
• You have credentials (username and hostname or IP address) for the remote server you wish to connect to.
• The server must have an SSH daemon running (usually port 22) and allow connections from your IP (if a firewall is configured).
• Generating keys requires free disk space (a few kilobytes).

If you are connecting to your own server, ensure that SSH is installed and configured on the server side (for example, on Ubuntu: sudo apt install openssh-server).

Step 1: Verifying SSH Installation

macOS comes with a pre-installed OpenSSH client. To confirm it is available, open Terminal (via Spotlight or Finder → Applications → Utilities) and run:

ssh -V

Expected output: OpenSSH_x.x.x, ... (where x.x.x is the version). If the command is not found, SSH may be removed or corrupted; in this case, you may need to reinstall macOS or install it via Homebrew: brew install openssh.

💡 Tip: For quick access to Terminal, use the shortcut Cmd + Space, start typing "Terminal", and press Enter.

Step 2: Generating SSH Keys

For passwordless secure connections, key-based authentication is recommended. Generate a key pair (private and public). By default, the Ed25519 algorithm is used, which provides good security and performance.

In Terminal, run:

ssh-keygen -t ed25519 -C "your_email@example.com"

Replace "your_email@example.com" with your email or any comment to identify the key. The command will prompt you to specify a save location (default ~/.ssh/id_ed25519) and a passphrase. For automation, you can leave the passphrase empty, but for enhanced security, setting a strong passphrase is recommended.

Example session:

Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/username/.ssh/id_ed25519): [Enter]
Enter passphrase (empty for no passphrase): [Enter your password or leave empty]
Enter same passphrase again: [Repeat]
Your identification has been saved in /Users/username/.ssh/id_ed25519
Your public key has been saved in /Users/username/.ssh/id_ed25519.pub

After generation, the public key (id_ed25519.pub) needs to be copied to the server.

Step 3: Copying the Public Key to the Server

The simplest method is to use the ssh-copy-id utility, which automatically adds your public key to the ~/.ssh/authorized_keys file on the remote server.

Run:

ssh-copy-id username@hostname

Replace username with your username on the server and hostname with the server's IP address or domain name. You will be prompted to enter the server user's password (once). Upon successful completion, the key is added.

If ssh-copy-id is unavailable (for example, on older systems), copy the key manually:

1. Display the public key's contents:

   cat ~/.ssh/id_ed25519.pub
   

   
   Copy the output (starts with ssh-ed25519 ...).
2. Connect to the server:

   ssh username@hostname
   

3. On the server, create the .ssh directory if it doesn't exist, and add the key:

   mkdir -p ~/.ssh
   echo "copied_key" >> ~/.ssh/authorized_keys
   chmod 700 ~/.ssh
   chmod 600 ~/.ssh/authorized_keys
   

⚠️ Important: Permissions on the .ssh directory and authorized_keys file must be strict, otherwise SSH will reject key-based authentication.

Step 4: Configuring SSH Settings (Optional)

For convenience, you can create a configuration file ~/.ssh/config on your Mac to store connection parameters for frequently used servers. This allows connecting simply by using an alias.

Create or edit the file:

nano ~/.ssh/config

Add a block for each server:

Host myserver
    HostName server.example.com
    User username
    Port 22
    IdentityFile ~/.ssh/id_ed25519

Here:

• Host — the alias used in the ssh myserver command.
• HostName — the actual hostname or IP.
• User — the username on the server.
• Port — the SSH port (default 22, if unchanged).
• IdentityFile — path to the private key (if non-standard).

Save the file (in nano: Ctrl + O, then Enter, and Ctrl + X to exit). Now the connection simplifies to ssh myserver.

Step 5: Connecting to the Remote Server

After setting up keys and configuration, perform a test connection. If you used the config, connect by alias:

ssh myserver

Or directly:

ssh username@hostname

If everything is configured correctly, you will log in to the server without a password prompt (if the key has no passphrase) or with a key passphrase prompt (if set). On the first connection, a host fingerprint warning may appear — verify that the fingerprint matches the expected one (for example, via the server administrator) and confirm.

Verifying the Result

To ensure SSH is working correctly:

• You should receive the remote server's command prompt (for example, username@hostname:~$).
• Check that you can run commands on the server, such as ls or pwd.
• If key-based authentication is used, a password should not be requested (if the key has no passphrase).
• For debugging, use the -v option (or -vvv for verbose output): ssh -v username@hostname.

Common Issues

Error "Permission denied (publickey,password)"

• Cause: The public key is not found or file permissions on the server are incorrect.
• Solution: Check that ~/.ssh/authorized_keys on the server contains your public key, and permissions are: chmod 700 ~/.ssh and chmod 600 ~/.ssh/authorized_keys. Ensure the owner is the user you are connecting as.

Error "Connection refused" or timeout

• Cause: The SSH daemon is not running on the server, the port is blocked by a firewall, or the host/port is incorrect.
• Solution: Verify that sshd is running on the server (for example, sudo systemctl status ssh). Ensure port 22 (or custom) is open in the firewall and that AllowUsers in the SSH config includes your user.

Warning about an unknown host (fingerprint)

• Cause: SSH remembers the host's fingerprint on first connection. If the host changes (for example, OS reinstallation), a warning appears.
• Solution: If you trust the new host, confirm. If not, check with the administrator. To reset the record, delete the host's line from ~/.ssh/known_hosts.

Missing ssh-copy-id command

• Solution: Install via Homebrew: brew install ssh-copy-id or use the manual copying method described above.

Permissions issues with keys on Mac

• Cause: The private key must be readable only by the owner.
• Solution: Run chmod 600 ~/.ssh/id_ed25519 (or the corresponding key file).