ssh-copy-id.1 revision 248613
1180740Sdes.ig \" -*- nroff -*- 2248613SdesCopyright (c) 1999-2013 hands.com Ltd. <http://hands.com/> 3180740Sdes 4248613SdesRedistribution and use in source and binary forms, with or without 5248613Sdesmodification, are permitted provided that the following conditions 6248613Sdesare met: 7248613Sdes1. Redistributions of source code must retain the above copyright 8248613Sdes notice, this list of conditions and the following disclaimer. 9248613Sdes2. Redistributions in binary form must reproduce the above copyright 10248613Sdes notice, this list of conditions and the following disclaimer in the 11248613Sdes documentation and/or other materials provided with the distribution. 12180740Sdes 13248613SdesTHIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 14248613SdesIMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 15248613SdesOF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 16248613SdesIN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 17248613SdesINCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 18248613SdesNOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 19248613SdesDATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 20248613SdesTHEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 21248613Sdes(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 22248613SdesTHIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 23180740Sdes.. 24248613Sdes.Dd $Mdocdate: June 17 2010 $ 25248613Sdes.Dt SSH-COPY-ID 1 26248613Sdes.Os 27248613Sdes.Sh NAME 28248613Sdes.Nm ssh-copy-id 29248613Sdes.Nd use locally available keys to authorise logins on a remote machine 30248613Sdes.Sh SYNOPSIS 31248613Sdes.Nm 32248613Sdes.Op Fl n 33248613Sdes.Op Fl i Op Ar identity_file 34248613Sdes.Op Fl p Ar port 35248613Sdes.Op Fl o Ar ssh_option 36248613Sdes.Op Ar user Ns @ Ns 37248613Sdes.Ar hostname 38248613Sdes.Nm 39248613Sdes.Fl h | Fl ? 40180740Sdes.br 41248613Sdes.Sh DESCRIPTION 42248613Sdes.Nm 43248613Sdesis a script that uses 44248613Sdes.Xr ssh 1 45248613Sdesto log into a remote machine (presumably using a login password, 46248613Sdesso password authentication should be enabled, unless you've done some 47248613Sdesclever use of multiple identities). It assembles a list of one or more 48248613Sdesfingerprints (as described below) and tries to log in with each key, to 49248613Sdessee if any of them are already installed (of course, if you are not using 50248613Sdes.Xr ssh-agent 1 51248613Sdesthis may result in you being repeatedly prompted for pass-phrases). 52248613SdesIt then assembles a list of those that failed to log in, and using ssh, 53248613Sdesenables logins with those keys on the remote server. By default it adds 54248613Sdesthe keys by appending them to the remote user's 55248613Sdes.Pa ~/.ssh/authorized_keys 56248613Sdes(creating the file, and directory, if necessary). It is also capable 57248613Sdesof detecting if the remote system is a NetScreen, and using its 58248613Sdes.Ql set ssh pka-dsa key ... 59248613Sdescommand instead. 60248613Sdes.Pp 61248613SdesThe options are as follows: 62248613Sdes.Bl -tag -width Ds 63248613Sdes.It Fl i Ar identity_file 64248613SdesUse only the key(s) contained in 65248613Sdes.Ar identity_file 66248613Sdes(rather than looking for identities via 67248613Sdes.Xr ssh-add 1 68248613Sdesor in the 69248613Sdes.Ic default_ID_file ) . 70248613SdesIf the filename does not end in 71248613Sdes.Pa .pub 72248613Sdesthis is added. If the filename is omitted, the 73248613Sdes.Ic default_ID_file 74248613Sdesis used. 75248613Sdes.Pp 76248613SdesNote that this can be used to ensure that the keys copied have the 77248613Sdescomment one prefers and/or extra options applied, by ensuring that the 78248613Sdeskey file has these set as preferred before the copy is attempted. 79248613Sdes.It Fl n 80248613Sdesdo a dry-run. Instead of installing keys on the remote system simply 81248613Sdesprints the key(s) that would have been installed. 82248613Sdes.It Fl h , Fl ? 83248613SdesPrint Usage summary 84248613Sdes.It Fl p Ar port , Fl o Ar ssh_option 85248613SdesThese two options are simply passed through untouched, along with their 86248613Sdesargument, to allow one to set the port or other 87248613Sdes.Xr ssh 1 88248613Sdesoptions, respectively. 89248613Sdes.Pp 90248613SdesRather than specifying these as command line options, it is often better to use (per-host) settings in 91248613Sdes.Xr ssh 1 Ns 's 92248613Sdesconfiguration file: 93248613Sdes.Xr ssh_config 5 . 94248613Sdes.El 95248613Sdes.Pp 96248613SdesDefault behaviour without 97248613Sdes.Fl i , 98248613Sdesis to check if 99248613Sdes.Ql ssh-add -L 100248613Sdesprovides any output, and if so those keys are used. Note that this results in 101248613Sdesthe comment on the key being the filename that was given to 102248613Sdes.Xr ssh-add 1 103248613Sdeswhen the key was loaded into your 104248613Sdes.Xr ssh-agent 1 105248613Sdesrather than the comment contained in that file, which is a bit of a shame. 106248613SdesOtherwise, if 107248613Sdes.Xr ssh-add 1 108248613Sdesprovides no keys contents of the 109248613Sdes.Ic default_ID_file 110248613Sdeswill be used. 111248613Sdes.Pp 112248613SdesThe 113248613Sdes.Ic default_ID_file 114248613Sdesis the most recent file that matches: 115248613Sdes.Pa ~/.ssh/id*.pub , 116248613Sdes(excluding those that match 117248613Sdes.Pa ~/.ssh/*-cert.pub ) 118248613Sdesso if you create a key that is not the one you want 119248613Sdes.Nm 120248613Sdesto use, just use 121248613Sdes.Xr touch 1 122248613Sdeson your preferred key's 123248613Sdes.Pa .pub 124248613Sdesfile to reinstate it as the most recent. 125248613Sdes.Pp 126248613Sdes.Sh EXAMPLES 127248613SdesIf you have already installed keys from one system on a lot of remote 128248613Sdeshosts, and you then create a new key, on a new client machine, say, 129248613Sdesit can be difficult to keep track of which systems on which you've 130248613Sdesinstalled the new key. One way of dealing with this is to load both 131248613Sdesthe new key and old key(s) into your 132248613Sdes.Xr ssh-agent 1 . 133248613SdesLoad the new key first, without the 134248613Sdes.Fl c 135248613Sdesoption, then load one or more old keys into the agent, possibly by 136248613Sdesssh-ing to the client machine that has that old key, using the 137248613Sdes.Fl A 138248613Sdesoption to allow agent forwarding: 139248613Sdes.Pp 140248613Sdes.D1 user@newclient$ ssh-add 141248613Sdes.D1 user@newclient$ ssh -A old.client 142248613Sdes.D1 user@oldl$ ssh-add -c 143248613Sdes.D1 No ... prompt for pass-phrase ... 144248613Sdes.D1 user@old$ logoff 145248613Sdes.D1 user@newclient$ ssh someserver 146248613Sdes.Pp 147248613Sdesnow, if the new key is installed on the server, you'll be allowed in 148248613Sdesunprompted, whereas if you only have the old key(s) enabled, you'll be 149248613Sdesasked for confirmation, which is your cue to log back out and run 150248613Sdes.Pp 151248613Sdes.D1 user@newclient$ ssh-copy-id -i someserver 152248613Sdes.Pp 153248613SdesThe reason you might want to specify the -i option in this case is to 154248613Sdesensure that the comment on the installed key is the one from the 155248613Sdes.Pa .pub 156248613Sdesfile, rather than just the filename that was loaded into you agent. 157248613SdesIt also ensures that only the id you intended is installed, rather than 158248613Sdesall the keys that you have in your 159248613Sdes.Xr ssh-agent 1 . 160248613SdesOf course, you can specify another id, or use the contents of the 161248613Sdes.Xr ssh-agent 1 162248613Sdesas you prefer. 163248613Sdes.Pp 164248613SdesHaving mentioned 165248613Sdes.Xr ssh-add 1 Ns 's 166248613Sdes.Fl c 167248613Sdesoption, you might consider using this whenever using agent forwarding 168248613Sdesto avoid your key being hijacked, but it is much better to instead use 169248613Sdes.Xr ssh 1 Ns 's 170248613Sdes.Ar ProxyCommand 171248613Sdesand 172248613Sdes.Fl W 173248613Sdesoption, 174248613Sdesto bounce through remote servers while always doing direct end-to-end 175248613Sdesauthentication. This way the middle hop(s) don't get access to your 176248613Sdes.Xr ssh-agent 1 . 177248613SdesA web search for 178248613Sdes.Ql ssh proxycommand nc 179248613Sdesshould prove enlightening (N.B. the modern approach is to use the 180248613Sdes.Fl W 181248613Sdesoption, rather than 182248613Sdes.Xr nc 1 ) . 183248613Sdes.Sh "SEE ALSO" 184248613Sdes.Xr ssh 1 , 185248613Sdes.Xr ssh-agent 1 , 186248613Sdes.Xr sshd 8 187