lshell(1)						      General Commands Manual							 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 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)

       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:

	      # addgroup --system lshell
	      # 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.15 							  March 13, 2012							 lshell(1)