=encoding utf8
=head1 NAME
restricted-ssh-commands - Restrict SSH users to a predefined set of commands
=head1 SYNOPSIS
B</usr/lib/restricted-ssh-commands> [I<config>]
=head1 DESCRIPTION
restricted-ssh-commands is intended to be called by SSH to restrict a
user to only run specific commands. A list of allowed regular
expressions can be configured in F</etc/restricted-ssh-commands/>. The
requested command has to match at least one regular expression.
Otherwise it will be rejected.
restricted-ssh-commands is useful to grant restricted access via SSH to
do only certain task. For example, it could allow a user to upload a Debian
packages via scp and run reprepro processincoming.
The optional I<config> parameter is the name of the configuration inside
F</etc/restricted-ssh-commands/> that should be used. If I<config> is omitted,
the user name will be used.
=head1 USAGE
Create a configuration file in F</etc/restricted-ssh-commands/$config> and add
following line to F<~/.ssh/authorized_keys> to use it
command="/usr/lib/restricted-ssh-commands",no-port-forwarding,\
no-X11-forwarding,no-agent-forwarding,no-pty ssh-rsa [...]
To enable debug output, set the RSC_VERBOSE environment variable to a nonzero
value, e.g. by adding it to authorized_keys:
command="RSC_VERBOSE=1 /usr/lib/restricted-ssh-commands"
=head1 EXIT STATUS
B<restricted-ssh-commands> will exit with the exit status from the called
command if the command is allowed and therefore executed. If the command
is rejected, B<restricted-ssh-commands> will exit with one of the following
exit codes.
=over 8
=item C<124>
A configuration file was found and contains at least one regular expression, but
the requested command does not match any of those regular expressions.
=item C<125>
The configuration file is missing or does not contain any regular expressions.
Thus all commands are rejected.
=back
=head1 EXAMPLES
Imagine you have a Debian package repository on a host using reprepro and
you want to allow package upload to it. Assuming the user is reprepro and the
package configuration is stored in F</srv/reprepro>, you would create the
configuration file F</etc/restricted-ssh-commands/reprepro> containing these
three regular expressions:
^scp -p( -d)? -t( --)? /srv/reprepro/incoming(/[-A-Za-z0-9+~_.]*[-A-Za-z0-9+~_])?$
^chmod 0644( /srv/reprepro/incoming/[-A-Za-z0-9+~_.]*[-A-Za-z0-9+~_])+$
^reprepro ( -V)? -b /srv/reprepro processincoming foobar$
=head1 SECURITY NOTES
It is dangerous and not recommended to use negative bracket expressions
(like [^ /]). Characters like CR LF $ & ; ( ) and so on can be abused to execute
arbitrary commands. For example, the rule
^echo [^ /]$
can be abused to execute these commands
echo foo&echo owned
echo foo&rm -rf $(printf "\x2f")
where a TAB is used instead of spaces after the first ampersand. Therefore
only use positive bracked expressions (like [a-z]).
=head1 FILES
The configuration files are placed in F</etc/restricted-ssh-commands/>. Each
line in the configuration file represents one POSIX extended regular expression
(ERE). Lines starting with # are considered as comments and are ignored. Empty
lines (containing only whitespaces) are ignored, too.
=head1 SEE ALSO
Regular expressions on
http://tldp.org/LDP/Bash-Beginners-Guide/html/sect_04_01.html
Section 9.4 Extended Regular Expressions (ERE) on
http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html
=head1 AUTHOR
B<restricted-ssh-commands> and this manpage have been written by Benjamin Drung
<benjamin.drung@profitbricks.com>.