.\" .\" Man page for the Limited Shell (lshell) project. .\" .TH lshell 1 "July, 2015" "v0.9.18" .SH NAME lshell \- Limited Shell .SH SYNOPSIS .B lshell [\fIOPTIONS\fR] .SH DESCRIPTION \fBlshell\fR provides a limited shell configured per user. The configuration is done quite simply using a configuration file. Coupled with ssh's .I authorized_keys or with .I /etc/shells and .I /etc/passwd , it becomes very easy to restrict user's access to a limited set of command. .SH OPTIONS .TP .B \--config \fI\fR Specify config file .TP .B \--log \fI\fR Specify the log directory .TP .B \-- \fI\fR where is *any* config file parameter .TP .B \-h, --help Show help message .TP .B \--version Show version .SH CONFIGURATION You can configure lshell through its configuration file: .RS .ft 3 .nf .sp On Linux \-> /etc/lshell.conf On *BSD \-> /usr/{pkg,local}/etc/lshell.conf .ft .LP .RE .fi The configuration is dynamically reloaded. Which means that you can edit the configuration, and all the connected users will automatically load it. In case you are using multiple configuration files (see include_dir), you will need to refresh the main configuration's timestamp, in order to reload the configuration: .RS .ft 3 .nf .sp touch /path/to/lshell.conf .ft .LP .RE .fi \fBlshell\fR configuration has 4 types of sections: .RS .ft 3 .nf .sp [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 .ft .LP .RE .fi Order of priority when loading preferences is the following: .RS .ft 3 .nf .sp 1- User configuration 2- Group configuration 3- Default configuration .ft .LP .RE .fi .SS [global] .TP .I logpath config path (default is /var/log/lshell/) .TP .I loglevel 0, 1, 2, 3 or 4 (0: no logs -> 4: logs everything) .TP .I logfilename \- set to \fBsyslog\fR in order to log to syslog .RS \- set log file name, e.g. %u-%y%m%d (i.e foo-20091009.log): .BR \ \ \ \ %u -> username .RE .RS .BR \ \ \ \ %d -> day [1..31] .RE .RS .BR \ \ \ \ %m -> month [1..12] .RE .RS .BR \ \ \ \ %y -> year [00..99] .RE .RS .BR \ \ \ \ %h -> time [00:00..23:59] .RE .TP .I syslogname in case you are using syslog, set your logname (default: lshell) .TP .I include_dir include a directory containing multiple configuration files. These files can only contain default/user/group configuration. The global configuration will only be loaded from the default configuration file. This variable will be expanded (e.g. /path/*.conf). .TP .I path_noexec set path to sudo noexec library. This path is usually autodetected, only set this variable to use alternate path. If set and the shared object is not found, lshell will exit immediately. Otherwise, please check your logs to verify that a standard path is detected. .RS .SS [default] and/or [username] and/or [grp:groupname] .TP .TP .I aliases command aliases list (similar to bash's alias directive) .TP .I allowed a list of the allowed commands or set to 'all' to allow all commands in user's \ PATH if sudo(8) is installed and sudo_noexec.so is available, it will be loaded before running every command, preventing it from running further commands itself. If not available, beware of commands like vim/find/more/etc. that will allow users to execute code (e.g. /bin/sh) from within the application, thus easily escaping lshell. See variable 'path_noexec' to use an alternative path to library. .TP .I allowed_shell_escape a list of the allowed commands that are permitted to execute other programs (e.g. shell scripts with exec(3)). Setting this variable to 'all' is NOT allowed. Warning: do not put here any command that can execute arbitrary commands (e.g. find, vim, xargs). important: commands defined in 'allowed_shell_escape' override their definition in the \'allowed\' variable. .TP .I allowed_cmd_path a list of path; all executable files inside these path will be allowed .TP .I env_path update the environment variable $PATH of the user (optional) .TP .I env_vars set environment variables (optional) .TP .I forbidden a list of forbidden characters or commands .TP .I history_file set the history filename. A wildcard can be used: .RS .BR \ \ \ \ %u -> username (e.g. '/home/%u/.lhistory') .RE .TP .I history_size set the maximum size (in lines) of the history file .TP .I 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: .RS .BR \ \ \ \ %u -> username (e.g. '/home/%u') .RE .TP .I intro set the introduction to print at login .TP .I login_script define the script to run at user login .TP .I passwd password of specific user (default is empty) .TP .I path list of path to restrict the user geographically. It is possible to use \ wildcards (e.g. '/var/log/ap*'). .TP .I prompt set the user's prompt format (default: username) .RS .BR \ \ \ \ %u -> username .RE .RS .BR \ \ \ \ %h -> hostname .RE .TP .I prompt_short set prompt style for current directory - 0, 1 or 2. Default is 0. .RS .BR \ \ \ \ 0 -> will show the current directory as compared to home directory ~/current/dir .RE .RS .BR \ \ \ \ 1 -> will only show the current directory name .RE .RS .BR \ \ \ \ 2 -> will show the complete path to the current directory .RE .TP .I overssh list of command allowed to execute over ssh (e.g. rsync, rdiff-backup, scp, \ etc.) .TP .I scp allow or forbid the use of scp connection - set to 1 or 0 .TP .I scpforce force files sent through scp to a specific directory .TP .I scp_download set to 0 to forbid scp downloads (default is 1) .TP .I scp_upload set to 0 to forbid scp uploads (default is 1) .TP .I sftp allow or forbid the use of sftp connection - set to 1 or 0. WARNING: This option will not work if you are using OpenSSH's \ internal-sftp service (e.g. when configured in chroot) .TP .I sudo_commands a list of the allowed commands that can be used with sudo(8). If set to \ \'all', all the 'allowed' commands will be accessible through sudo(8). It is possible to use the -u sudo flag in order to run a command as a \ different user than the default root. .TP .I timer a value in seconds for the session timer .TP .I 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) .TP .I warning_counter number of warnings when user enters a forbidden value before getting exited \ from lshell. Set to \fB\-1\fR to disable the counter, and just warn the user. .TP .I winscp enable support for WinSCP with scp mode (NOT sftp) When enabled, the following parameters will be overridden: .RS .BR \ \ \ \ scp_upload : 1 (uses scp(1) from within session) .RE .RS .BR \ \ \ \ scp_download: 1 (uses scp(1) from within session) .RE .RS .BR \ \ \ \ scpforce : ignored (uses scp(1) from within session) .RE .RS .BR \ \ \ \ forbidden : -[';'] .RE .RS .BR \ \ \ \ allowed : +['scp', 'env', 'pwd', 'groups', 'unset', 'unalias'] .RE .SH SHELL BUILTIN COMMANDS Here is the set of commands that are always available with lshell: .TP .I clear clears the terminal .TP .I export name of exported shell variable. Disabled by default, enable it by adding it \ to allowed commands. .TP .I help, ? print the list of allowed commands .TP . I history print the commands history .TP . I lpath lists all allowed and forbidden path .TP . I lsudo lists all sudo allowed commands .SH EXAMPLES .TP .B $ lshell .RS 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 .RE .TP .B $ lshell --config /path/to/myconf.file --log /path/to/mylog.log .RS This will override the default options specified for configuration and/or log \ file .RE .SH 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: .TP .B User foo: .RS - 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' .RE .TP .B User bar: .RS - 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) .RE In this case, my configuration file will look something like this: .RS .ft 3 .nf .sp # 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 .ft .LP .RE .fi .SH NOTES .TP In order to log a user's warnings into the logging directory (default \ \fI/var/log/lshell/\fR) , you must firt create the folder (if it doesn't \ exist yet) and chown it to lshell group: .RS .ft 3 .nf .sp # addgroup \-\-system lshell # mkdir /var/log/lshell # chown :lshell /var/log/lshell # chmod 770 /var/log/lshell .ft .LP .RE .fi then add the user to the \fIlshell\fR group: .RS .ft 3 .nf .sp # usermod \-aG lshell user_name .ft .LP .RE .fi In order to set lshell as default shell for a user: .RS .ft 3 .nf .sp On Linux: # chsh \-s /usr/bin/lshell user_name On *BSD: # chsh \-s /usr/{pkg,local}/bin/lshell user_name .ft .LP .RE .fi .SH AUTHOR Currently maintained by Ignace Mouzannar (ghantoos) .SH EMAIL Feel free to send me your recommendations at