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