lshell(1)

NAME

lshell - Limited Shell

SYNOPSIS

lshell [OPTIONS]

DESCRIPTION

lshell provides a limited shell configured per user. The configuration is done quite simply using a configuration file. Coupled with ssh's authorized_keys or with /etc/shells and /etc/passwd , it becomes very easy to restrict user's access to a limited set of command.

OPTIONS

--config <FILE>

Specify config file

--log <DIR>

Specify the log directory

-h, --help

Show help message

--version

Show version

CONFIGURATION

You can configure lshell through its configuration file:

On Linux -> /etc/lshell.conf On *BSD -> /usr/{pkg,local}/etc/lshell.conf

lshell configuration has 4 types of sections:

[global] -> lshell system configuration (only 1) [default] -> lshell default user configuration (only 1) [foo] -> UNIX username "foo" specific configuration [grp:bar] -> UNIX groupname "bar" specific configuration

Order of priority when loading preferences is the following:

1- User configuration
2- Group configuration
3- Default configuration

[global]

logpath

config path (default is /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] and/or [username] and/or [grp:groupname]

allowed

a list of the allowed commands or set to 'all' to allow all commands in user's PATH

forbidden

a list of forbidden characters 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 (default is empty)

path list of path to restrict the user geographically

home_path

set the home folder of your user. If not specified, the home directory is set to the $HOME environment variable. A wildcard can be used:

%u -> username (e.g. '/home/%u')

env_path

update the environment variable $PATH of the user (optional)

scp allow or forbid the use of scp connection - set to 1 or 0

sftp allow or forbid the use of sftp connection - set to 1 or

overssh

list of command allowed to execute over ssh (e.g. rsync, rdiff-backup, scp, etc.)

strict logging strictness. If set to 1, any unknown command is

considered as forbidden, and user's warning counter is decreased. If set to 0, command is considered as unknown, and user is only warned (i.e. *** unknown synthax)

scpforce

force files sent through scp to a specific directory

aliases

command aliases list (similar to bash's alias directive)

EXAMPLES

$ lshell

Tries to run lshell using default ${PREFIX}/etc/lshell.conf as configuration file. If it fails a warning is printed and lshell is interrupted. lshell options are loaded from the configuration file

$ lshell --config /path/to/myconf.file --log /path/to/mylog.log

This will override the default options specified for configuration and/or log file

USE CASE

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. In this 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:

# CONFIURATION 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/bin/' 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/' # CONFIURATION END

NOTES

In order to log a user's warnings into the logging directory (default /var/log/lshell/) , you must firt create the folder (if it doesn't exist yet) and chown it to lshell group:

# mkdir /var/log/lshell # chown :lshell /var/log/lshell # chmod 770 /var/log/lshell

then add the user to the lshell group:

# usermod -aG lshell user_name

In order to set lshell as default shell for a user:

On Linux:
# chsh -s /usr/bin/lshell user_name

On *BSD:
# chsh -s /usr/{pkg,local}/bin/lshell user_name

AUTHOR

Currently maintained by Ignace Mouzannar (ghantoos)

EMAIL

Feel free to send me your recommendations at <ghantoos@ghantoos.org>

v0.9.8 November 30, 2009 lshell(1)