mdw@git.distorted.org.uk Git - misc/blob - sshsvc-mkauthkeys.1

   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>