Commit | Line | Data |
---|---|---|
b9ee4e83 MW |
1 | .de hP |
2 | .IP | |
3 | \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c | |
4 | .. | |
5 | .ie t .ds o \(bu | |
6 | .el .ds o o | |
7 | . | |
8 | .TH sshsvc-mkauthkeys 1 "23 April 2015" "distorted.org.uk" "Utilities" | |
9 | .SH NAME | |
10 | sshsvc-mkauthkeys \- build authorized_keys files for SSH services | |
11 | .SH SYNOPSIS | |
12 | .B sshsvc-mkauthkeys | |
13 | .RB [ \-c | |
14 | .IR config ] | |
15 | .RB [ \-k | |
16 | .IR keysdir ] | |
17 | .RB [ \-o | |
18 | .IR output ] | |
19 | .br | |
20 | \&\h'8n' | |
21 | .RB [ \-H | |
22 | .IR head ] | |
23 | .RB [ \-T | |
24 | .IR tail ] | |
25 | .SH DESCRIPTION | |
26 | The | |
27 | .B sshsvc-mkauthkeys | |
28 | script constructs an OpenSSH | |
29 | .B authorized_keys | |
30 | file | |
31 | from a collection of SSH public keys | |
32 | and some configuration in the form of shell variable and function | |
33 | definitions. | |
34 | The script expects to be run from a makefile | |
35 | within a | |
36 | .B .ssh/ | |
37 | directory | |
38 | and reads and writes files with fixed relative pathnames by default. | |
39 | These can be overridden using command-line options. | |
40 | .SS "Command line options" | |
41 | .TP | |
42 | .BI \-c " config" | |
43 | Source configuration from | |
44 | .I config | |
45 | instead of the default | |
46 | .BR sshsvc.conf . | |
47 | .TP | |
48 | .BI \-k " keysdir" | |
49 | Collect user keys from | |
50 | .I keysdir | |
51 | instead of the default | |
52 | .BR keys/ . | |
53 | .TP | |
54 | .BI \-o " output" | |
55 | Write the output to | |
56 | .I output | |
57 | instead of the default | |
58 | .BR authorized_keys . | |
59 | .TP | |
60 | .BI \-H " head" | |
61 | Read initial raw entries from | |
62 | .I head | |
63 | (if it exists) | |
64 | instead of the default | |
65 | .BR sshsvc-authkeys.head . | |
66 | .TP | |
67 | .BI \-T " tail" | |
68 | Read final raw entries from | |
69 | .I tail | |
70 | (if it exists) | |
71 | instead of the default | |
72 | .BR sshsvc-authkeys.tail . | |
73 | .SS "Overall operation" | |
74 | The | |
75 | .I output | |
76 | file | |
77 | .RB ( authorized_keys | |
78 | by default) | |
79 | is constructed as follows. | |
80 | .hP 0. | |
81 | A comment is written to | |
82 | the very top of | |
83 | the output file | |
84 | explaining that it was generated by | |
85 | .BR sshsvc-mkauthkeys . | |
86 | .hP 1. | |
87 | If the | |
88 | .I head | |
89 | file | |
90 | .RB ( sshsvc-authkeys.head | |
91 | by default) | |
92 | exists then its contents are written unchanged to the output. | |
93 | .hP 2. | |
94 | Each of the files | |
95 | .IB keysdir / user\fR[ ! label\fR] .pub | |
96 | is processed in turn | |
97 | (see below) | |
98 | in ascending lexicographic order | |
99 | to make a single-line entry | |
100 | in the output file. | |
101 | The default | |
102 | .I keysdir | |
103 | is | |
104 | .BR keys/ . | |
105 | .hP 3. | |
106 | If the | |
107 | .I tail | |
108 | file | |
109 | .RB ( sshsvc-authkeys.tail | |
110 | by default) | |
111 | exists then its contents are written unchanged to the output. | |
112 | .hP 4. | |
113 | A commend is written to | |
114 | the very bottom of | |
115 | the output file | |
116 | explaining that it was generated by | |
117 | .BR sshsvc-mkauthkeys . | |
118 | .SS "Configuration" | |
119 | The configuration | |
120 | for a particular SSH service | |
121 | is read from | |
122 | .BR sshsvc.conf . | |
123 | This file must exist | |
124 | in the current working directory, | |
125 | though it needn't have any content | |
126 | since all configurable parameters have sensible | |
127 | (though not necessarily useful) | |
128 | defaults. | |
129 | .SS "The make_full_key_line function" | |
130 | The most general configuration hook | |
131 | (and therefore the one requiring most effort from the user) | |
132 | is the | |
133 | .B make_full_key_line | |
134 | function. | |
135 | It is given the key file's | |
136 | .I user | |
137 | name as an argument and | |
138 | expected to write | |
139 | the | |
140 | .I options | |
141 | portion of an | |
142 | .B authorized_keys | |
143 | entry to standard output. | |
144 | .PP | |
145 | The default implementation is likely to be suitable | |
146 | for almost all services. It calls | |
147 | .B make_key_line | |
148 | (see below) | |
149 | to construct | |
150 | environment variable settings | |
151 | and other per-user configuration settings, | |
152 | and attaches general policy settings. | |
153 | .PP | |
154 | It uses the following variables. | |
155 | .TP | |
156 | .B allow_port_forwarding | |
157 | If not | |
158 | .B yes | |
159 | then forbid port forwarding | |
160 | (include | |
161 | .B no-port-forwarding | |
162 | in the line). | |
163 | The default is | |
164 | .BR no . | |
165 | .TP | |
166 | .B allow_x11_forwarding | |
167 | If not | |
168 | .B yes | |
169 | then forbid X11 connection forwarding | |
170 | (include | |
171 | .B no-X11-forwarding | |
172 | in the line). | |
173 | The default is | |
174 | .BR no . | |
175 | .TP | |
176 | .B allow_agent_forwarding | |
177 | If not | |
178 | .B yes | |
179 | then forbid SSH agent forwarding | |
180 | (include | |
181 | .B no-agent-forwarding | |
182 | in the line). | |
183 | The default is | |
184 | .BR no . | |
185 | It's probably not a good idea to enable this. | |
186 | .TP | |
187 | .B allow_pty | |
188 | If not | |
189 | .B yes | |
190 | then forbid pty allocation | |
191 | (include | |
192 | .B no-pty | |
193 | in the line). | |
194 | The default is | |
195 | .BR no . | |
196 | This is usually what you want | |
197 | unless your service needs an interactive terminal | |
198 | (e.g., a console for a virtual machine). | |
199 | .TP | |
200 | .B cmd | |
201 | If set to any value | |
202 | and the line from | |
203 | .B make_key_line | |
204 | doesn't already contain a | |
205 | .RB ` command= ...' | |
206 | option, | |
207 | then always run | |
208 | .I cmd | |
209 | (with the service user's shell) | |
210 | rather than using the client's requested command line, | |
211 | which is left in | |
212 | .B SSH_ORIGINAL_COMMAND | |
213 | (include | |
214 | .BI command="" cmd "" | |
215 | in the line). | |
216 | The default is | |
217 | .BR bin/sshsvc . | |
218 | .SS "The make_key_line function" | |
219 | The | |
220 | .B make_key_line | |
221 | function is called with | |
222 | the key file's | |
223 | .I user | |
224 | name as its only argument, | |
225 | and is expected to write any per-user | |
226 | (and unusual) | |
227 | options to standard output. | |
228 | Mostly it will be sufficient to generate an | |
229 | .RB ` environment= ...' | |
230 | option | |
231 | and leave the rest to | |
232 | .BR make_full_key_line . | |
233 | .PP | |
234 | The default | |
235 | .B make_key_line | |
236 | function is suitable for simple cases. | |
237 | It examines the | |
238 | .B env | |
239 | variable, | |
240 | replacing | |
241 | .B @user | |
242 | placeholders with the key's | |
243 | .I user | |
244 | name, | |
245 | and emits the line | |
246 | .BI environment= env\fR. | |
247 | The default value of | |
248 | .B env | |
249 | is | |
250 | .B SSHSVC_USER=@user | |
251 | which may be good enough for services | |
252 | explicitly written to work with it. | |
253 | .SH FILES | |
254 | .TP | |
255 | .BR sshsvc.conf | |
256 | Read for configuration | |
257 | (shell variable and function definitions). | |
258 | .TP | |
259 | .BI keys/ user\fR[ ! label\fR] .pub | |
260 | Input public keys to process. | |
261 | .TP | |
262 | .B sshsvc-authkeys.head | |
263 | Pre-cooked | |
264 | .B authorized_keys | |
265 | entries to write at the top of the output. | |
266 | .TP | |
267 | .B sshsvc-authkeys.tail | |
268 | Pre-cooked | |
269 | .B authorized_keys | |
270 | entries to write at the bottom of the output. | |
271 | .TP | |
272 | .B authorized_keys | |
273 | Output file. | |
274 | .SH BUGS | |
275 | Perfection guaranteed. | |
276 | Satisfaction, or your money back. | |
277 | .SH "SEE ALSO" | |
278 | .BR ssh (1), | |
279 | .BR sshd (8). | |
280 | .SH AUTHOR | |
281 | Mark Wooding, <mdw@distorted.org.uk> |