#####################################
# LSHELL - Limited Shell - README #
#####################################
#
# $Id: README,v 1.27 2010/10/16 09:41:38 ghantoos Exp $
Contact: Ignace Mouzannar (ghantoos) <ghantoos@ghantoos.org>
http://ghantoos.org/limited-shell-lshell/
#####################################
I've commented the source file (lshell.py) and the template configuration \
file (lshell.conf) as much as thought would be enough.
All this information is in the man (man lshell)
###
1- Installation:
###
You have 3 options:
* Use the setup.py present in the source tar.gz. It uses python \
distutils to install everything in the right place:
- Extract the files:
# tar xvfz lshell.tar.gz
- On Linux:
# python setup.py install --no-compile --install-scripts=/usr/bin/
- On *BSD:
# python setup.py install --no-compile --install-data=/usr/{pkg,local}/
* Install the rpm:
- # rpm -Uvh lshell-x.x-x.noarch.rpm
* Install the deb:
- # dpkg -i lshell-x.x-x.deb
Files to be installed are:
* etc/lshell.conf
* bin/lshell
* lshellmodule/lshell.py
* man/man1/lshell.1.gz
* CHANGES
* COPYING
* README
###
2- Configuration:
###
lshell.conf presents a template configuration file. Fields to fill are:
[global]
* logpath : log directory (default /var/log/lshell/ )
* loglevel : 0, 1, 2, 3 or 4 (0: no logs -> 4: logs everything)
* logfilename : set log file name, e.g. %u-%y%m%d
(i.e foo-20091009.log)
%u -> username
%d -> day [1..31]
%m -> month [1..12]
%y -> year [00..99]
%h -> time [00:00..23:59]
[default]
or [username] (UNIX username)
or [grp:groupname] (UNIX groupname)
* allowed : a list of the allowed commands
* forbidden : a list of forbidden character or commands
* warning_counter : number of warnings when user enters a forbidden \
value before getting exited from lshell.
* timer : a value in seconds for the session timer
* passwd : password of specific user
* path : list of path to restrict the user geographically
* home_path : set the home folder of your user. If not specified,\
the home_path is set to the $HOME env. variable
* env_path : update the environment variable $PATH of the user
* scp : 1 or 0 to allow or not the use of scp
* sftp : 1 or 0 to allow of forbid the use of sftp
* overssh : list of command allowed to execute over ssh (e.g. \
rsync, rdiff-backup, scp, etc.)
* strict : 1 or 0 - If set to 1, any unknown command is \
considered as forbidden, as warning counter is \
decreased. If set to 0, command is considered as \
unknown
* scpforce : force files sent through scp to a specific directory
* aliases : command aliases list (similar to bashs alias \
directive)
A [default] profile is available for all users using lshell. Nevertheless, \
you can create a [username] section or a [grp:groupname] section to \
customize users' preferences.
Order of priority when loading preferences is the following:
1- User configuration
2- Group configuration
3- Default configuration
The primary goal of lshell, was to be able to create shell accounts \
with ssh access and restrict their environment to a couple a needed \
commands.
For example User 'foo' and user 'bar' both belong to the 'users' UNIX group:
User foo:
- must be able to access /usr and /var but not /usr/local
- user all command in his PATH but 'su'
- has a warning counter set to 5
- has his home path set to '/home/users'
User bar:
- must be able to access /etc and /usr but not /usr/local
- is allowed default commands plus 'ping' minus 'ls'
- strictness is set to 1 (meaning he is not allowed to type an unknown \
command)
In this case, my configuration file will look something like this:
# CONFIGURATION START
[global]
logpath : /var/log/lshell/
loglevel : 2
[default]
allowed : ['ls','pwd']
forbidden : [';', '&', '|']
warning_counter : 2
timer : 0
path : ['/etc', '/usr']
env_path : ':/sbin:/usr/foo'
scp : 1 # or 0
sftp : 1 # or 0
overssh : ['rsync','ls']
aliases : {'ls':'ls --color=auto','ll':'ls -l'}
[grp:users]
warning_counter : 5
overssh : - ['ls']
[foo]
allowed : 'all' - ['su']
path : ['/var', '/usr'] - ['/usr/local']
home_path : '/home/users'
[bar]
allowed : + ['ping'] - ['ls']
path : - ['/usr/local']
strict : 1
scpforce : '/home/bar/uploads/'
# CONFIGURATION END
###
3- Usage:
###
To launch the Limited Shell, just execute lshell specifying the \
location of your configuration file:
$> lshell --config /path/to/configuration/file
By default lshell will try to launch using /${CONFPATH}/lshell.conf unless \
specified otherwise (using --config), where ${CONFPATH} is :
- "/etc/" for Linux
- "/usr/{pkg,local}/etc/" for *BSD
In order to log a user, you will have to add him to the lshellg group:
# usermod -aG lshellg username
###
5- Use case 1: /etc/passwd
###
In order to configure a user account to use lshell by default, you must:
- On Linux:
# chsh -s /usr/bin/lshell user_name
- On *BSD:
# chsh -s /usr/{pkg,local}/bin/lshell user_name
After this, whichever method is used by the user to log into his account, \
he will end up using the limited shell you configured for him!
###
4- Use case 2: OpenSSH & authorized_keys
###
In order to launch lshell limited to the 'ssh' command, I used ssh's \
authorized_keys:
$> vi /home/foo/.ssh/authorized_keys
and add :
command="/usr/bin/lshell --config /path/to/lshell.conf",no-port-for \
warding,no-X11-forwarding,no-agent-forwarding,no-pty
just before the "ssh-dss blabla" part.
This will have the effect of executing lshell upon user's connection.
The great thing about it, is that when the user exist lshell, the ssh \
session is automatically ended! : )
Your authorized_keys should look something like this:
no-port-forwarding,no-X11-forwarding,no-agent-forwarding,command= \
"/path/to/lshell.py /path/to/lshell.conf" ssh-dss AAAAHadWj4caz5T \
AA6Xgonf2FjpmpgpquvN+6cQsGTEOwm6R+oEaFBU1VyfuwlEklqn3TWnWzACBAKNJ \
cJFr6pJsECEz5LZFtGu7b4tYNu8/vne11SjZBrOqm7WuQiWpOguzyldk6IJSnIKrn \
WoT/fGgXeED2UingA65bKIvOh0B3NzaC1kc3McsrBEDjQ3NAAAAFQDP6OHwkLNSA1 \
PyKqIMzqiCpAmJE7gRgFu8Pxc7i1TZvmiXSCjdXRaXZNncxPj6eOUng4QFDAoZc6n \
N8iUYCwKJ2pl2ryMqC/hnBVL5SRne+FqcRKbzWXkh7NI6KtJ4XxI32NI/OIpZAo2e \
G/8rdCgShZflCbpFZL865fKmUH2pefSZwl/12VXWDqQmukNp6+XrA3LPXdElIeQAA \
ACAHoQ3GpC4/BcxuHj1TBNg7Hw3KxZMeL1vQNVF2+cfJ22U1hERNBcRuUjqe5Gv9Q \
GoCMcsNpG8/FtV5Pnoq8nPPWuUkrBeBxY6KSgzaZ/DTSd+WvPOwNonntRkEwxpSdk \
lSqXpmqNlw2fPodg6QAAAIEVdZiSZZ9EoH+4MJjKDSvE= foo@somewhere.somet \
hing
Now, when "sshing" to your machine, with the foo user, he will be \
forced to lshell! And when quitting lshell, the ssh session is \
automatically ended! : )
###
6- Contact
###
If you want to contribute to this project, please do not hesitate.
Send me a patch, or just your new lshell.py so I can check it out.
You can use the interface on sourceforge.net:
http://sourceforge.net/projects/lshell/
Cheers,
Ignace Mouzannar ((ghantoos)) <ghantoos@ghantoos.org>
