Debian Codegraph @

upstream/debian-unstable/man1/ssh-copy-id.1

raw
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