1.ig \" -*- nroff -*- 2Copyright (c) 1999-2024 Philip Hands <phil@hands.com> 3 4Redistribution and use in source and binary forms, with or without 5modification, are permitted provided that the following conditions 6are met: 71. Redistributions of source code must retain the above copyright 8 notice, this list of conditions and the following disclaimer. 92. Redistributions in binary form must reproduce the above copyright 10 notice, this list of conditions and the following disclaimer in the 11 documentation and/or other materials provided with the distribution. 12 13THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 14IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 15OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 16IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 17INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 18NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 19DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 20THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 21(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 22THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 23.. 24.Dd $Mdocdate: June 17 2010 $ 25.Dt SSH-COPY-ID 1 26.Os 27.Sh NAME 28.Nm ssh-copy-id 29.Nd use locally available keys to authorise logins on a remote machine 30.Sh SYNOPSIS 31.Nm 32.Op Fl f 33.Op Fl n 34.Op Fl s 35.Op Fl x 36.Op Fl i Op Ar identity_file 37.Op Fl t Ar target_path 38.Op Fl F Ar ssh_config 39.Op Bo Fl o Ar ssh_option Bc ... 40.Op Fl p Ar port 41.Op Ar user Ns @ Ns 42.Ar hostname 43.Nm 44.Fl h | Fl ? 45.br 46.Sh DESCRIPTION 47.Nm 48is a script that uses 49.Xr ssh 1 50to log into a remote machine (presumably using a login password, 51so password authentication should be enabled, unless you've done some 52clever use of multiple identities). 53It assembles a list of one or more fingerprints (as described below) 54and tries to log in with each key, 55to see if any of them are already installed (of course, if you are not using 56.Xr ssh-agent 1 57this may result in you being repeatedly prompted for pass-phrases). 58It then assembles a list of those that failed to log in and, using 59.Xr ssh 1 , 60enables logins with those keys on the remote server. 61By default it adds the keys by appending them to the remote user's 62.Pa ~/.ssh/authorized_keys 63(creating the file, and directory, if necessary). 64It is also capable of detecting if the remote system is a NetScreen, 65and using its 66.Ql set ssh pka-dsa key ... 67command instead. 68.Pp 69The options are as follows: 70.Bl -tag -width Ds 71.It Fl i Op Ar identity_file 72Use only the key(s) contained in 73.Ar identity_file 74(rather than looking for identities via 75.Xr ssh-add 1 76or in the 77.Ic default_ID_file ) . 78If the filename does not end in 79.Pa .pub 80this is added. 81If the filename is omitted, the 82.Ic default_ID_file 83is used. 84.Pp 85Note that this can be used to ensure that the keys copied have the 86comment one prefers and/or extra options applied, by ensuring that the 87key file has these set as preferred before the copy is attempted. 88.It Fl f 89Forced mode: doesn't check if the keys are present on the remote server. 90This means that it does not need the private key. 91Of course, this can result in more than one copy of the key being installed 92on the remote system. 93.It Fl n 94do a dry-run. 95Instead of installing keys on the remote system simply 96prints the key(s) that would have been installed. 97.It Fl s 98SFTP mode: usually the public keys are installed 99by executing commands on the remote side. 100With this option the user's 101.Pa ~/.ssh/authorized_keys 102file will be downloaded, modified locally and uploaded with sftp. 103This option is useful if the server has restrictions 104on commands which can be used on the remote side. 105.It Fl t Ar target_path 106the path on the target system where the keys should be added 107(defaults to ".ssh/authorized_keys") 108.It Fl p Ar port 109Specifies the port to connect to on the remote host. 110.It Fl F Ar ssh_config , Fl o Ar ssh_option 111These options are simply passed through untouched (with their argument) 112to ssh/sftp, 113allowing one to set an alternative config file, 114or other options, respectively. 115.Pp 116Rather than specifying these as command line options, 117it is often better to use (per-host) settings in 118.Xr ssh 1 Ns 's 119configuration file: 120.Xr ssh_config 5 . 121.It Fl x 122This option is for debugging the 123.Nm 124script itself. 125It sets the shell's -x flag, so that you can see the commands being run. 126.It Fl h , Fl ? 127Print Usage summary 128.El 129.Pp 130Default behaviour without 131.Fl i , 132is to check if 133.Ql ssh-add -L 134provides any output, and if so those keys are used. 135Note that this results in the comment on the key 136being the filename that was given to 137.Xr ssh-add 1 138when the key was loaded into your 139.Xr ssh-agent 1 140rather than the comment contained in that file, which is a bit of a shame. 141Otherwise, if 142.Xr ssh-add 1 143provides no keys contents of the 144.Ic default_ID_file 145will be used. 146.Pp 147The 148.Ic default_ID_file 149is the most recent file that matches: 150.Pa ~/.ssh/id*.pub , 151(excluding those that match 152.Pa ~/.ssh/*-cert.pub ) 153so if you create a key that is not the one you want 154.Nm 155to use, just use 156.Xr touch 1 157on your preferred key's 158.Pa .pub 159file to reinstate it as the most recent. 160.Sh EXAMPLES 161If you have already installed keys from one system on a lot of remote 162hosts, and you then create a new key, on a new client machine, say, 163it can be difficult to keep track of which systems on which you've 164installed the new key. 165One way of dealing with this is to load both the new key and old key(s) 166into your 167.Xr ssh-agent 1 . 168Load the new key first, without the 169.Fl c 170option, then load one or more old keys into the agent, possibly by 171ssh-ing to the client machine that has that old key, using the 172.Fl A 173option to allow agent forwarding: 174.Pp 175.D1 user@newclient$ ssh-add 176.D1 user@newclient$ ssh -A old.client 177.D1 user@oldl$ ssh-add -c 178.D1 No ... prompt for pass-phrase ... 179.D1 user@old$ logoff 180.D1 user@newclient$ ssh someserver 181.Pp 182now, if the new key is installed on the server, you'll be allowed in 183unprompted, whereas if you only have the old key(s) enabled, you'll be 184asked for confirmation, which is your cue to log back out and run 185.Pp 186.D1 user@newclient$ ssh-copy-id -i someserver 187.Pp 188The reason you might want to specify the 189.Fl i 190option in this case is to 191ensure that the comment on the installed key is the one from the 192.Pa .pub 193file, rather than just the filename that was loaded into your agent. 194It also ensures that only the id you intended is installed, rather than 195all the keys that you have in your 196.Xr ssh-agent 1 . 197Of course, you can specify another id, or use the contents of the 198.Xr ssh-agent 1 199as you prefer. 200.Pp 201Having mentioned 202.Xr ssh-add 1 Ns 's 203.Fl c 204option, you might consider using this whenever using agent forwarding 205to avoid your key being hijacked, but it is much better to instead use 206.Xr ssh 1 Ns 's 207.Ar ProxyCommand 208and 209.Fl W 210option, 211to bounce through remote servers while always doing direct end-to-end 212authentication. 213This way the middle hop(s) don't get access to your 214.Xr ssh-agent 1 . 215A web search for 216.Ql ssh proxycommand nc 217should prove enlightening (NB the modern approach is to use the 218.Fl W 219option, rather than 220.Xr nc 1 ) . 221.Sh "SEE ALSO" 222.Xr ssh 1 , 223.Xr ssh-agent 1 , 224.Xr sshd 8 225