ssh-copy-id - Copy SSH Key to Server to Provision Access

ssh-copy-id install an SSH key on a server as an authorized key. This facilitates automated, passwordless logins and single sign-on using the SSH protocol.

Generating SSH Keys


With OpenSSH, an SSH key is created using ssh-keygen. In the simplest form, just run ssh-keygen and answer the questions. The following example illustates this.

# ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key (/home/ylo/.ssh/id_rsa): mykey
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in mykey.
Your public key has been saved in
The key fingerprint is:
SHA256:GKW7yzA1J1qkr1Cr9MhUwAbHbF2NrIPEgZXeOUOz3Us ylo@klar
The key's randomart image is:
+---[RSA 2048]----+
|.*++ o.o.        |
|.+B + oo.        |
| +++ *+.         |
| .o.Oo.+E        |
|    ++B.S.       |
|   o * =.        |
|  + = o          |
| + = = .         |
|  + o o          |

Creating a key pair (public key and private key) only takes a minute. The keys are usually stored in the ~/.ssh directory.

Tectia SSH

In Tectia SSH, keys are created using the ssh-keygen-g3 command. Its usage is similar to the ssh-keygen command in OpenSSH.

Copying Key to a Server

Once a key has been created, the ssh-copy-id command can be used to install it as an authorized key on the server. Once the key has been authorized for SSH, it grants access to the server without a password. The key based authentication is called public key authentication.

Use a command like the following to copy the key to a server:

ssh-copy-id -i ~/.ssh/mykey user@host

This logs into the server (possibly prompting for a password), and then installs the key. Only the public key is copied to the server. The private key should never be copied to another machine.

Testing the New Key

Once the key has been copied, it is best to test it:

ssh -i ~/.ssh/mykey user@host

The login should now complete without asking for a password. Note, however, that the command might ask for the passphrase you specified for the key.


There are a number of reasons why the test might fail:

  • The server might not be configured to accept public key authentication. Make sure /etc/ssh/sshd_config on the server contains PubkeyAuthentication yes.
  • If trying to login as root, the server might not be configured to allow root logins. Make sure /etc/sshd_config includes PermitRootLogin yes, PermitRootLogin prohibit-password, or without-password. If it is set to forced-commands-only, the key must be manually configured to use a forced command (see command= option in authorized_keys.
  • Make sure the client allows public key authentication. Check that /etc/ssh/config includes PubkeyAuthentication yes.
  • Try adding -v option to the ssh command used for the test. Read the output to see what it says about whether the key is tried and what authentication methods the server is willing to accept.
  • OpenSSH only allows a maximum of five keys to be authomatically. If you have more keys, you must specify which key to use using the -i option to ssh.

How It Works

ssh-copy-id uses the SSH protocol to connect to the target host and upload the SSH user key. The command edits the authorized_keys file on the server. It creates the .ssh directory if it doesn't exist. It creates the authorized keys file if it doesn't exist. It may also fix permissions of the user's home directory if they are inappropriate.

The program also checks if the key already exists on the server. Unless the -f option is given, it is only added to the authorized keys file once.

Using a Passphrase

It is recommended that keys used for single sign-on have a passphrase to prevent use of the key if it is stolen or inadvertatly leaked. The ssh-agent and ssh-add programs can be used to avoid having to enter the passphrase every time the key is used.

Keys without a passphrase are useful for fully automated processes. They allow shell scripts, programs, and management tools to log into servers unattended. This is often used for backups and data transfers between information systems.

Managing SSH Keys

It is easy to create many SSH keys and many organization accumulate keys over the years. Some of the largest IT environments have turned out to have several million SSH keys configured as authorized on their servers. This can introduce major security risks that could be used to spread an attack throughout a Fortune 500 and destroy it. Even smaller organization can easily accumulate hundreds to thousands of keys. Very often, the keys are not removed when people leave the organization.

The ssh-copy-id tool is dangerous. It can easily accidentally install multiple keys or unintended keys as authorized. The logic for choosing which key to install is convoluted. Extra authorized keys grant permanent access. They can later be used to spread attacks host-to-host, and the more keys there are, the higher the risk. It also violates all regulatory compliance requirements.

The Universal SSH Key Manager is a widely used tool for managing SSH keys.

ssh-copy-id options

The sample below presents ssh-copy-id command line syntax:

ssh-copy-id [-f] [-n] [-i identity file] [-p port] [-o ssh_option] [user@]hostname

The options have the following meaning:

-f Don't check if the key is already configured as an authorized key on the server. Just add it. This can result in multiple copies of the key in authorized_keys files.

-i Specifies the identity file that is to be used (default is ~/.ssh/id_rsa). If this option is not provided, this adds all keys listed by ssh-add -L. Note: it can be multiple keys and adding extra authorized keys can easily happen accidentally! If ssh-add -L returns no keys, then the most recently modified key matching ~/.ssh/id*.pub, excluding those matching ~/.ssh/*, will be used.

-n Just print the key(s) that would be installed, without actually installing them.

-o ssh_option Pass -o ssh_option to the SSH client when making the connection. This can be used for overriding configuration settings for the client. See ssh command line options and the possible configuration options in ssh_config.

-p port Connect to the specifed SSH port on the server, instead of the default port 22.

-h or -? Print usage summary.