#####################################
#  LSHELL - Limited Shell - README  #
#####################################
#
# $Id: README,v 1.27 2010-10-16 09:41:38 ghantoos Exp $

Contact : Ignace Mouzannar (ghantoos) <[email protected]>
Homepage: http://lshell.ghantoos.org
Sources : https://github.com/ghantoos/lshell
#####################################

I've commented the source file (lshell.py) and the template configuration      \
file (lshell.conf) as much as thought would be enough.

All this information is in the man (man lshell)

###
1- Installation:
###
    You have 3 options:
        * Use the setup.py present in the source tar.gz. It uses python        \
          distutils to install everything in the right place:
            - Extract the files:
        # tar xvfz lshell.tar.gz
            - On Linux:
        # python setup.py install --no-compile --install-scripts=/usr/bin/
            - On *BSD:
        # python setup.py install --no-compile --install-data=/usr/{pkg,local}/

        * Install the rpm:
            - # rpm -Uvh lshell-x.x-x.noarch.rpm

        * Install the deb:
            - # dpkg -i lshell-x.x-x.deb

    Files to be installed are: 
        * etc/lshell.conf
        * bin/lshell
        * lshellmodule/lshell.py
        * man/man1/lshell.1.gz
        * CHANGES
        * COPYING
        * README

###
2- Configuration:
###
    lshell.conf presents a template configuration file. Fields to fill are:
    [global]
        * logpath         : log directory (default /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] 
    or [username] (UNIX username)
    or [grp:groupname] (UNIX groupname)
        * allowed         : a list of the allowed commands
        * forbidden       : a list of forbidden character 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
        * path            : list of path to restrict the user geographically
        * home_path       : set the home folder of your user. If not specified,\ 
                            the home_path is set to the $HOME env. variable
        * env_path        : update the environment variable $PATH of the user
        * scp             : 1 or 0 to allow or not the use of scp
        * sftp            : 1 or 0 to allow of forbid the use of sftp
        * overssh         : list of command allowed to execute over ssh (e.g.  \
                            rsync, rdiff-backup, scp, etc.)
        * strict          : 1 or 0 - If set to 1, any unknown command is       \
                            considered as forbidden, as warning counter is     \
                            decreased. If set to 0, command is considered as   \
                            unknown
        * scpforce       : force files sent through scp to a specific directory
        * aliases        : command aliases list (similar to bashs alias        \
                           directive)

    A [default] profile is available for all users using lshell. Nevertheless, \
    you can create a [username] section or a [grp:groupname] section to        \
    customize users' preferences.
    Order of priority when loading preferences is the following:
        1- User configuration
        2- Group configuration
        3- Default configuration

    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. 
    For 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:

    # CONFIGURATION 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/foo'
    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/'
    # CONFIGURATION END

###
3- Usage:
###
    To launch the Limited Shell, just execute lshell specifying the            \
    location of your configuration file:
    $> lshell --config /path/to/configuration/file

    By default lshell will try to launch using /${CONFPATH}/lshell.conf unless \
    specified otherwise (using --config), where ${CONFPATH} is :
        - "/etc/" for Linux
        - "/usr/{pkg,local}/etc/" for *BSD

    In order to log a user, you will have to add him to the lshellg group:
    # usermod -aG lshellg username

###
5- Use case 1: /etc/passwd
###
    In order to configure a user account to use lshell by default, you must:
     - On Linux:
     # chsh -s /usr/bin/lshell user_name
     - On *BSD:
     # chsh -s /usr/{pkg,local}/bin/lshell user_name

    After this, whichever method is used by the user to log into his account,  \
    he will end up using the limited shell you configured for him!

###
4- Use case 2: OpenSSH & authorized_keys
###
    
    In order to launch lshell limited to the 'ssh' command, I used ssh's       \
    authorized_keys:
    $> vi /home/foo/.ssh/authorized_keys
    and add :
        command="/usr/bin/lshell --config /path/to/lshell.conf",no-port-for    \
        warding,no-X11-forwarding,no-agent-forwarding,no-pty
    just before the "ssh-dss blabla" part.

    This will have the effect of executing lshell upon user's connection.
    The great thing about it, is that when the user exist lshell, the ssh      \
    session is automatically ended! : )

    Your authorized_keys should look something like this:

    no-port-forwarding,no-X11-forwarding,no-agent-forwarding,command=          \
    "/path/to/lshell.py /path/to/lshell.conf" ssh-dss AAAAHadWj4caz5T          \
    AA6Xgonf2FjpmpgpquvN+6cQsGTEOwm6R+oEaFBU1VyfuwlEklqn3TWnWzACBAKNJ          \
    cJFr6pJsECEz5LZFtGu7b4tYNu8/vne11SjZBrOqm7WuQiWpOguzyldk6IJSnIKrn          \
    WoT/fGgXeED2UingA65bKIvOh0B3NzaC1kc3McsrBEDjQ3NAAAAFQDP6OHwkLNSA1          \
    PyKqIMzqiCpAmJE7gRgFu8Pxc7i1TZvmiXSCjdXRaXZNncxPj6eOUng4QFDAoZc6n          \
    N8iUYCwKJ2pl2ryMqC/hnBVL5SRne+FqcRKbzWXkh7NI6KtJ4XxI32NI/OIpZAo2e          \
    G/8rdCgShZflCbpFZL865fKmUH2pefSZwl/12VXWDqQmukNp6+XrA3LPXdElIeQAA          \
    ACAHoQ3GpC4/BcxuHj1TBNg7Hw3KxZMeL1vQNVF2+cfJ22U1hERNBcRuUjqe5Gv9Q          \
    GoCMcsNpG8/FtV5Pnoq8nPPWuUkrBeBxY6KSgzaZ/DTSd+WvPOwNonntRkEwxpSdk          \
    lSqXpmqNlw2fPodg6QAAAIEVdZiSZZ9EoH+4MJjKDSvE= [email protected]          \
    hing

    Now, when "sshing" to your machine, with the foo user, he will be          \
    forced to lshell! And when quitting lshell, the ssh session is             \
    automatically ended! : )

###
6- Contact
###
    If you want to contribute to this project, please do not hesitate.
    Send me a patch, or just your new lshell.py so I can check it out.
    You can use the interface on sourceforge.net: 
    http://sourceforge.net/projects/lshell/

    Cheers,
    Ignace Mouzannar ((ghantoos)) <[email protected]>