.de hP
.IP
\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
..
.ie t .ds o \(bu
.el .ds o o
.
.TH sshsvc-mkauthkeys 1 "23 April 2015" "distorted.org.uk" "Utilities"
.SH NAME
sshsvc-mkauthkeys \- build authorized_keys files for SSH services
.SH SYNOPSIS
.B sshsvc-mkauthkeys
.RB [ \-c
.IR config ]
.RB [ \-k
.IR keysdir ]
.RB [ \-o
.IR output ]
.br
\&\h'8n'
.RB [ \-H
.IR head ]
.RB [ \-T
.IR tail ]
.SH DESCRIPTION
The
.B sshsvc-mkauthkeys
script constructs an OpenSSH
.B authorized_keys
file
from a collection of SSH public keys
and some configuration in the form of shell variable and function
definitions.
The script expects to be run from a makefile
within a
.B .ssh/
directory
and reads and writes files with fixed relative pathnames by default.
These can be overridden using command-line options.
.SS "Command line options"
.TP
.BI \-c " config"
Source configuration from
.I config
instead of the default
.BR sshsvc.conf .
.TP
.BI \-k " keysdir"
Collect user keys from
.I keysdir
instead of the default
.BR keys/ .
.TP
.BI \-o " output"
Write the output to
.I output
instead of the default
.BR authorized_keys .
.TP
.BI \-H " head"
Read initial raw entries from
.I head
(if it exists)
instead of the default
.BR sshsvc-authkeys.head .
.TP
.BI \-T " tail"
Read final raw entries from
.I tail
(if it exists)
instead of the default
.BR sshsvc-authkeys.tail .
.SS "Overall operation"
The
.I output
file
.RB ( authorized_keys
by default)
is constructed as follows.
.hP 0.
A comment is written to
the very top of
the output file
explaining that it was generated by
.BR sshsvc-mkauthkeys .
.hP 1.
If the
.I head
file
.RB ( sshsvc-authkeys.head
by default)
exists then its contents are written unchanged to the output.
.hP 2.
Each of the files
.IB keysdir / user\fR[ ! label\fR] .pub
is processed in turn
(see below)
in ascending lexicographic order
to make a single-line entry
in the output file.
The default
.I keysdir
is
.BR keys/ .
.hP 3.
If the
.I tail
file
.RB ( sshsvc-authkeys.tail
by default)
exists then its contents are written unchanged to the output.
.hP 4.
A commend is written to
the very bottom of
the output file
explaining that it was generated by
.BR sshsvc-mkauthkeys .
.SS "Configuration"
The configuration
for a particular SSH service
is read from
.BR sshsvc.conf .
This file must exist
in the current working directory,
though it needn't have any content
since all configurable parameters have sensible
(though not necessarily useful)
defaults.
.SS "The make_full_key_line function"
The most general configuration hook
(and therefore the one requiring most effort from the user)
is the
.B make_full_key_line
function.
It is given the key file's
.I user
name as an argument and
expected to write
the
.I options
portion of an
.B authorized_keys
entry to standard output.
.PP
The default implementation is likely to be suitable
for almost all services.  It calls
.B make_key_line
(see below)
to construct
environment variable settings
and other per-user configuration settings,
and attaches general policy settings.
.PP
It uses the following variables.
.TP
.B allow_port_forwarding
If not
.B yes
then forbid port forwarding
(include
.B no-port-forwarding
in the line).
The default is
.BR no .
.TP
.B allow_x11_forwarding
If not
.B yes
then forbid X11 connection forwarding
(include
.B no-X11-forwarding
in the line).
The default is
.BR no .
.TP
.B allow_agent_forwarding
If not
.B yes
then forbid SSH agent forwarding
(include
.B no-agent-forwarding
in the line).
The default is
.BR no .
It's probably not a good idea to enable this.
.TP
.B allow_pty
If not
.B yes
then forbid pty allocation
(include
.B no-pty
in the line).
The default is
.BR no .
This is usually what you want
unless your service needs an interactive terminal
(e.g., a console for a virtual machine).
.TP
.B cmd
If set to any value
and the line from
.B make_key_line
doesn't already contain a
.RB ` command= ...'
option,
then always run
.I cmd
(with the service user's shell)
rather than using the client's requested command line,
which is left in
.B SSH_ORIGINAL_COMMAND
(include
.BI command="" cmd ""
in the line).
The default is
.BR bin/sshsvc .
.SS "The make_key_line function"
The
.B make_key_line
function is called with
the key file's
.I user
name as its only argument,
and is expected to write any per-user
(and unusual)
options to standard output.
Mostly it will be sufficient to generate an
.RB ` environment= ...'
option
and leave the rest to
.BR make_full_key_line .
.PP
The default
.B make_key_line
function is suitable for simple cases.
It examines the
.B env
variable,
replacing
.B @user
placeholders with the key's
.I user
name,
and emits the line
.BI environment= env\fR.
The default value of
.B env
is
.B SSHSVC_USER=@user
which may be good enough for services
explicitly written to work with it.
.SH FILES
.TP
.BR sshsvc.conf
Read for configuration
(shell variable and function definitions).
.TP
.BI keys/ user\fR[ ! label\fR] .pub
Input public keys to process.
.TP
.B sshsvc-authkeys.head
Pre-cooked
.B authorized_keys
entries to write at the top of the output.
.TP
.B sshsvc-authkeys.tail
Pre-cooked
.B authorized_keys
entries to write at the bottom of the output.
.TP
.B authorized_keys
Output file.
.SH BUGS
Perfection guaranteed.
Satisfaction, or your money back.
.SH "SEE ALSO"
.BR ssh (1),
.BR sshd (8).
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>