ssh-copy-id Command: Tutorial & Examples

Copy SSH keys to a remote server

The ssh-copy-id command is a handy utility that simplifies the process of setting up SSH key-based authentication on your Linux server. SSH (Secure Shell) is used for secure remote logins, and using public key authentication improves security by eliminating the need for password-based logins. This command is part of the OpenSSH package, available on almost all Linux distributions.

What ssh-copy-id does

The ssh-copy-id command copies the local host's public key to the remote host's ~/.ssh/authorized_keys file. It also automatically fixes the permissions of the remote user's home, ~/.ssh, and ~/.ssh/authorized_keys to prevent potential issues with ssh refusing to connect due to file permissions being too open.

How ssh-copy-id works

The ssh-copy-id command attempts to log into the specified machine using ssh. It assembles a list of one or more fingerprints (depending on the number of keys to be installed) and prompts the user for confirmation. Once confirmed, it appends the keys to the remote user's ~/.ssh/authorized_keys, ensuring secure access.

How to use ssh-copy-id

The basic syntax of the ssh-copy-id command is:

ssh-copy-id [-i [identity_file]] [user@]hostname

The -i option specifies the identity file. If this option is not provided, the command will use the default identity file. The user@hostname specifies the remote host where you want to copy the public key.

For example, to copy your public key to the remote server at 192.168.0.101 as user john, you would run:

ssh-copy-id john@192.168.0.101

You can also specify a different identity file:

ssh-copy-id -i ~/.ssh/my_key.pub john@192.168.0.101

Example output

After executing the command, you may see output similar to:

Number of keys added: 1

This indicates that the public key has been successfully copied to the remote server.

Importance of the ssh-copy-id command

The ssh-copy-id command is crucial because it streamlines the process of configuring SSH-based authentication. It manages the copying of keys while setting correct permissions, avoiding common pitfalls that could cause ssh to refuse connections. By using this command, users can ensure a more secure and efficient login process.

Common parameters

The ssh-copy-id command has several parameters:

-i [identity_file]: Specifies the identity file that the public key is read from.
-f: Forces the copy of the identity file even if it is already present on the remote system.
-n: Don't contact the remote system. Just print what would have been executed.

Example of using parameters:

To force copy an identity file while ignoring existing keys, you can run:

ssh-copy-id -f john@192.168.0.101

Potential problems and pitfalls

While ssh-copy-id is straightforward to use, you may encounter some issues:

Forgetting to replace user@hostname with the actual username and hostname of the remote server can lead to confusion.
Incorrect permissions on the remote server can prevent the command from succeeding. Ensure the user has write permissions to the ~/.ssh/authorized_keys file.
If the remote server lacks a ~/.ssh directory, the command will fail. However, this directory is automatically created when the user connects via ssh for the first time.

Typical Error Messages:

ssh: connect to host <hostname> port 22: Connection refused: This indicates that the SSH server is not running on the remote host or a network issue is blocking the connection.
Permission denied (publickey): This message indicates that the public key is not in the remote host's ~/.ssh/authorized_keys file or the user has entered an incorrect password.

To resolve these issues, ensure that the SSH server is running, check the network connection, and verify the correct username and password were used.

Best practices

When using ssh-copy-id, consider the following best practices:

Always ensure that the SSH server is configured to accept key-based authentication. Check the /etc/ssh/sshd_config file for PubkeyAuthentication yes.
Regularly monitor and manage the contents of your ~/.ssh/authorized_keys file to maintain security.
Use strong SSH keys and consider using a passphrase for added security.
After copying your key, verify access by logging into the remote server without a password.

Advanced usage

You can also copy keys to multiple servers at once by using a loop in a shell script:

for server in server1 server2 server3; do
    ssh-copy-id user@$server
done

This allows for efficient key distribution across multiple hosts.