table of contents
lshell(1) | General Commands Manual | lshell(1) |
NAME¶
lshell - Limited ShellSYNOPSIS¶
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
[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 to syslog in order to log to syslog
- 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]
- syslogname
- in case you are using syslog, set your logname (default: lshell)
[default] and/or [username] and/or [grp:groupname]¶
- aliases
- command aliases list (similar to bash's alias directive)
- allowed
- a list of the allowed commands or set to 'all' to allow all commands in user's PATH
- allowed_cmd_path
- a list of path; all executable files inside these path will be allowed
- env_path
- update the environment variable $PATH of the user (optional)
- env_vars
- set environment variables (optional)
- forbidden
- a list of forbidden characters or commands
- history_file
- set the history filename. A wildcard can be used:
%u ->
username (e.g. '/home/%u/.lhistory')
- history_size
- set the maximum size (in lines) of the history file
- home_path (deprecated)
- set the home folder of your user. If not specified, the home directory is set to the $HOME environment variable. This variable will be removed in the next version of lshell, please use your system's tools to set a user's home directory. A wildcard can be used:
%u ->
username (e.g. '/home/%u')
- intro
- set the introduction to print at login
- passwd
- password of specific user (default is empty)
- path
- list of path to restrict the user geographically. It is possible to use wildcards (e.g. '/var/log/ap*').
- prompt
- set the user's prompt format (default: username)
%u ->
username
%h ->
hostname
- prompt_short
- set sort prompt current directory update - set to 1 or 0 overssh list of command allowed to execute over ssh (e.g. rsync, rdiff-backup, scp, etc.)
- scp
- allow or forbid the use of scp connection - set to 1 or 0
- scpforce
- force files sent through scp to a specific directory
- scp_download
- set to 0 to forbid scp downloads (default is 1)
- scp_upload
- set to 0 to forbid scp uploads (default is 1)
- sftp
- allow or forbid the use of sftp connection - set to 1 or 0
- sudo_commands
- a list of the allowed commands that can be used with sudo(8)
- timer
- a value in seconds for the session timer
- 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)
- warning_counter
- number of warnings when user enters a forbidden value
before getting exited from lshell. Set to -1 to disable the
counter, and just warn the user.
SHELL BUILTIN COMMANDS¶
Here is the set of commands that are always available with lshell:- clear
- clears the terminal
- help, ?
- print the list of allowed commands
- history
- print the commands history
- lpath
- lists all allowed and forbidden path
- lsudo
- lists all sudo allowed commands
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)
# 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:
# addgroup --system lshell # mkdir /var/log/lshell # chown :lshell /var/log/lshell # chmod 770 /var/log/lshell
# usermod -aG lshell user_name
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>March 13, 2012 | v0.9.15 |