1.ig \" -*- nroff -*- 2Copyright (c) 1999-2023 hands.com Ltd. <http://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 p Ar port 38.Op Fl o Ar ssh_option 39.Op Fl t Ar target_path 40.Op Ar user Ns @ Ns 41.Ar hostname 42.Nm 43.Fl h | Fl ? 44.br 45.Sh DESCRIPTION 46.Nm 47is a script that uses 48.Xr ssh 1 49to log into a remote machine (presumably using a login password, 50so password authentication should be enabled, unless you've done some 51clever use of multiple identities). 52It assembles a list of one or more fingerprints (as described below) 53and tries to log in with each key, 54to see if any of them are already installed (of course, if you are not using 55.Xr ssh-agent 1 56this may result in you being repeatedly prompted for pass-phrases). 57It then assembles a list of those that failed to log in and, using 58.Xr ssh 1 , 59enables logins with those keys on the remote server. 60By default it adds the keys by appending them to the remote user's 61.Pa ~/.ssh/authorized_keys 62(creating the file, and directory, if necessary). 63It is also capable of detecting if the remote system is a NetScreen, 64and using its 65.Ql set ssh pka-dsa key ... 66command instead. 67.Pp 68The options are as follows: 69.Bl -tag -width Ds 70.It Fl i Ar identity_file 71Use only the key(s) contained in 72.Ar identity_file 73(rather than looking for identities via 74.Xr ssh-add 1 75or in the 76.Ic default_ID_file ) . 77If the filename does not end in 78.Pa .pub 79this is added. 80If the filename is omitted, the 81.Ic default_ID_file 82is used. 83.Pp 84Note that this can be used to ensure that the keys copied have the 85comment one prefers and/or extra options applied, by ensuring that the 86key file has these set as preferred before the copy is attempted. 87.It Fl f 88Forced mode: doesn't check if the keys are present on the remote server. 89This means that it does not need the private key. 90Of course, this can result in more than one copy of the key being installed 91on the remote system. 92.It Fl n 93do a dry-run. 94Instead of installing keys on the remote system simply 95prints the key(s) that would have been installed. 96.It Fl s 97SFTP mode: usually the public keys are installed 98by executing commands on the remote side. 99With this option the user's 100.Pa ~/.ssh/authorized_keys 101file will be downloaded, modified locally and uploaded with sftp. 102This option is useful if the server has restrictions 103on commands which can be used on the remote side. 104.It Fl t Ar target_path 105the path on the target system where the keys should be added 106(defaults to ".ssh/authorized_keys") 107.It Fl p Ar port , Fl o Ar ssh_option 108These two options are simply passed through untouched, along with their 109argument, to allow one to set the port or other 110.Xr ssh 1 111options, respectively. 112.Pp 113Rather than specifying these as command line options, 114it is often better to use (per-host) settings in 115.Xr ssh 1 Ns 's 116configuration file: 117.Xr ssh_config 5 . 118.It Fl x 119This option is for debugging the 120.Nm 121script itself. 122It sets the shell's -x flag, so that you can see the commands being run. 123.It Fl h , Fl ? 124Print Usage summary 125.El 126.Pp 127Default behaviour without 128.Fl i , 129is to check if 130.Ql ssh-add -L 131provides any output, and if so those keys are used. 132Note that this results in the comment on the key 133being the filename that was given to 134.Xr ssh-add 1 135when the key was loaded into your 136.Xr ssh-agent 1 137rather than the comment contained in that file, which is a bit of a shame. 138Otherwise, if 139.Xr ssh-add 1 140provides no keys contents of the 141.Ic default_ID_file 142will be used. 143.Pp 144The 145.Ic default_ID_file 146is the most recent file that matches: 147.Pa ~/.ssh/id*.pub , 148(excluding those that match 149.Pa ~/.ssh/*-cert.pub ) 150so if you create a key that is not the one you want 151.Nm 152to use, just use 153.Xr touch 1 154on your preferred key's 155.Pa .pub 156file to reinstate it as the most recent. 157.Sh EXAMPLES 158If you have already installed keys from one system on a lot of remote 159hosts, and you then create a new key, on a new client machine, say, 160it can be difficult to keep track of which systems on which you've 161installed the new key. 162One way of dealing with this is to load both the new key and old key(s) 163into your 164.Xr ssh-agent 1 . 165Load the new key first, without the 166.Fl c 167option, then load one or more old keys into the agent, possibly by 168ssh-ing to the client machine that has that old key, using the 169.Fl A 170option to allow agent forwarding: 171.Pp 172.D1 user@newclient$ ssh-add 173.D1 user@newclient$ ssh -A old.client 174.D1 user@oldl$ ssh-add -c 175.D1 No ... prompt for pass-phrase ... 176.D1 user@old$ logoff 177.D1 user@newclient$ ssh someserver 178.Pp 179now, if the new key is installed on the server, you'll be allowed in 180unprompted, whereas if you only have the old key(s) enabled, you'll be 181asked for confirmation, which is your cue to log back out and run 182.Pp 183.D1 user@newclient$ ssh-copy-id -i someserver 184.Pp 185The reason you might want to specify the 186.Fl i 187option in this case is to 188ensure that the comment on the installed key is the one from the 189.Pa .pub 190file, rather than just the filename that was loaded into your agent. 191It also ensures that only the id you intended is installed, rather than 192all the keys that you have in your 193.Xr ssh-agent 1 . 194Of course, you can specify another id, or use the contents of the 195.Xr ssh-agent 1 196as you prefer. 197.Pp 198Having mentioned 199.Xr ssh-add 1 Ns 's 200.Fl c 201option, you might consider using this whenever using agent forwarding 202to avoid your key being hijacked, but it is much better to instead use 203.Xr ssh 1 Ns 's 204.Ar ProxyCommand 205and 206.Fl W 207option, 208to bounce through remote servers while always doing direct end-to-end 209authentication. 210This way the middle hop(s) don't get access to your 211.Xr ssh-agent 1 . 212A web search for 213.Ql ssh proxycommand nc 214should prove enlightening (NB the modern approach is to use the 215.Fl W 216option, rather than 217.Xr nc 1 ) . 218.Sh "SEE ALSO" 219.Xr ssh 1 , 220.Xr ssh-agent 1 , 221.Xr sshd 8 222