GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  LSHELL (1)

NAME

lshell - Limited Shell

CONTENTS

Synopsis
Description
Options
Configuration
Shell Builtin Commands
Examples
Use Case
Notes
Author
Email

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
--<param> <value>
  where <param> is *any* config file parameter
-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
login_script
  define the script to run at user 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>
Search for    or go to Top of page |  Section 1 |  Main Index


v0.9.16 LSHELL (1) August 14, 2013

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.