=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]

=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 parameter is the name of the configuration inside F</etc/restricted-ssh-commands/> that should be used. If I 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 will exit with the exit status from the called command if the command is allowed and therefore executed. If the command is rejected, B 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 and this manpage have been written by Benjamin Drung benjamin.drung@profitbricks.com.