CLISH Documentation

0.7.3

Abstract

A modular framework for implementing a CISCO-like CLI on a *NIX system. Arbitary command menus and actions can be defined using XML files. This software handles the user interaction, and forks the appropriate system commands to perform any actions.

Downloads

This project is hosted on sourceforge. from where the source-code can be downloaded.

Background

The CISCO-like CLI has become a de-facto standard in the domain of network devices. It is a much more restricted interface than traditional *NIX shells, hence is simpler to use and inherently more secure. As more devices move to using an embedded *NIX operating systems, a simple, scalable means of producing such a CLI becomes valuable.

Existing Solutions

Libcli

Libcli provides a similar facility but has the following main limitations:-

1) In order to add new commands a monolithic executable (which uses the library) needs to be recompiled, after editing the source code to add the newly required commands and actions.

2) libcli takes responsiblity for attaching to a socket (telnet-like). This limits the usage of the CLI; difficult to use over SSH for example, similarly cannot get the menus directly from an existing shell.

3) The implementation of the command actions is hard-linked into the monolithic executable, this can cause licence concerns/issues when a commercial company wishes to control proprietry software from within the CLI.

4) libcli takes responsiblity for the authentication of the user. This is different from other "shells" which do not deal with authentication, but are simply spawned as the required user.

GNU-zebra

Zebra is a routing package, and comes with it's own integrated CLI, to handle its configuration (VTYSH).

CLISH Project

The project is written (mostly) in ANSI-C and provides two example executables which can be used as a drop-in replacement for a more conventional "shell".

The software was initially developed as part of some internal work at 3Com and due to the dependancy on 3rd party open-source packages, and it's self contained nature, it is being released into the public domain.

It is designed to run on any *NIX system e.g. Linux, BSD, Cygwin and makes use of the following other opensource packages (glibc,tinyxml,doxygen)

clish (pronounced see-lish)

This application is a standard UNIX shell replacement. The ACTION tags in the XML specification are mapped to the system() call and hence will be interpreted as a Bourne-shell script.

tclish (pronounced tickle-ish)

This application is built if the TCL libraries are present on the build system. The name of the executable produced will reflect the version of TCL used. e.g. tclish8.4 will be generated if TCL8.4 is present on the system.

This application will spawn a TCL interpreter when started, and the contents of the ACTION tags will be interpreted as TCL scripts within that interpreter for the duration of the shell.

Features

The "clish" shell has the following features:-

"clish" makes use of multiple XML files to define it's behaviour these...

xml-example directory

This directory contains some example XML files which indicate some
of what can be acheived with the CLISH library.

The action fields are 'sh' scripts and were developed and
tested on a cygwin system so some  of the command options to
things like "ping" may be different on different systems. 
(you should only need to change the ACTION tag to get them to work...) 

To use these files set CLISH_PATH to point to this directory and 
launch clish.

\note
Thanks to Tom Williams who gave me the basis for the
"clock" command example.

Some of the example files are put here for reference:

global-command.xml

<?xml version="1.0" encoding="UTF-8"?>
<CLISH_MODULE xmlns="http://clish.sourceforge.net/XMLSchema" 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xsi:schemaLocation="http://clish.sourceforge.net/XMLSchema
                     http://clish.sourceforge.net/XMLSchema/clish.xsd">
    <!--=======================================================-->
    <COMMAND name="help"
             help="Display an overview of the CLI syntax">
        <ACTION builtin="clish_overview"/>
    </COMMAND>
    <!--=======================================================-->
    <COMMAND name="logout"
             help="Logout of the current CLI session">
        <ACTION builtin="clish_close"/>
    </COMMAND>
    <!--=======================================================-->
    <COMMAND name="top"
             help="Return to the default mode"
             view="root-view"
             viewid=""/>
    <!--=======================================================-->
    <COMMAND name="debug"
             help="Change to the debug mode"
             view="debug-view">
       <ACTION>echo "Entering debug mode..."</ACTION>
    </COMMAND>
    <!--=======================================================-->
    <COMMAND name="script"
             help="Change to the script demo mode"
             view="script-view"/>
    <!--=======================================================-->
    <COMMAND name="history"
             help="Display the current session's command line history">
        <PARAM name="limit"
               help="Set the size of history list (zero means unbounded)"
              ptype="UINT"
            default=""/>
        <ACTION builtin="clish_history">${limit}</ACTION>
    </COMMAND>
    <!--=======================================================-->
</CLISH_MODULE>

startup.xml

<?xml version="1.0" encoding="UTF-8"?>
<CLISH_MODULE xmlns="http://clish.sourceforge.net/XMLSchema" 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xsi:schemaLocation="http://clish.sourceforge.net/XMLSchema
                     http://clish.sourceforge.net/XMLSchema/clish.xsd">
    <!--=======================================================-->
    <OVERVIEW>
CONTEXT SENSITIVE HELP
[?] - Display context sensitive help. This is either a list of possible
      command completions with summaries, or the full syntax of the 
      current command. A subsequent repeat of this key, when a command
      has been resolved, will display a detailed reference.

AUTO-COMPLETION
The following keys both perform auto-completion for the current command line.
If the command prefix is not unique then the bell will ring and a subsequent
repeat of the key will display possible completions.

[enter] - Auto-completes, syntax-checks then executes a command. If there is 
          a syntax error then offending part of the command line will be
          highlighted and explained.

[space] - Auto-completes, or if the command is already resolved inserts a space.

MOVEMENT KEYS
[CTRL-A] - Move to the start of the line
[CTRL-E] - Move to the end of the line.
[up]     - Move to the previous command line held in history.
[down]   - Move to the next command line held in history.
[left]   - Move the insertion point left one character.
[right]  - Move the insertion point right one character.

DELETION KEYS
[CTRL-C]    - Delete and abort the current line
[CTRL-D]    - Delete the character to the right on the insertion point.
[CTRL-K]    - Delete all the characters to the right of the insertion point.
[CTRL-U]    - Delete the whole line.
[backspace] - Delete the character to the left of the insertion point.

ESCAPE SEQUENCES
!!  - Subsitute the the last command line.
!N  - Substitute the Nth command line (absolute as per 'history' command)
!-N - Substitute the command line entered N lines before (relative)
    </OVERVIEW>
    <!--=======================================================-->
    <STARTUP view="root-view">
        <DETAIL>
********************************************
*         CLISH (see-lish)                 *
*                                          *
*      WARNING: Authorised Access Only     *
********************************************
        </DETAIL>
        <ACTION>echo "Welcome `whoami` it is `date`"</ACTION>
    </STARTUP>
    <!--=======================================================-->
</CLISH_MODULE>

types.xml

<?xml version="1.0" encoding="UTF-8"?>
<CLISH_MODULE xmlns="http://clish.sourceforge.net/XMLSchema" 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xsi:schemaLocation="http://clish.sourceforge.net/XMLSchema
                     http://clish.sourceforge.net/XMLSchema/clish.xsd">
    <!--=======================================================-->
    <PTYPE name="VLAN_ID" 
        pattern="(409[0-5]|40[0-8][0-9]|[1-3][0-9]{3}|[1-9][0-9]{2}|[1-9][0-9]|[1-9])"
           help="Number in the range 1-4095"/>
    <!--=======================================================-->
    <PTYPE name="IP_ADDR"
        pattern="(((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?))"
           help="IP address AAA.BBB.CCC.DDD where each part is in the range 0-255"/>
    <!--=======================================================-->
    <PTYPE name="UINT"
        pattern="[0-9]+"
           help="Unsigned integer"/>
    <!--=======================================================-->
    <PTYPE name="STRING"
        pattern="[^\-]+"
           help="String"/>
    <!--=======================================================-->
    <PTYPE name="BOOL"
        pattern="true(1) false(0)"
           help="Boolean choice"/>
    <!--=======================================================-->
</CLISH_MODULE>

debug-view.xml

<?xml version="1.0" encoding="UTF-8"?>
<CLISH_MODULE xmlns="http://clish.sourceforge.net/XMLSchema" 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xsi:schemaLocation="http://clish.sourceforge.net/XMLSchema
                     http://clish.sourceforge.net/XMLSchema/clish.xsd">
    <VIEW name="debug-view" prompt="debug> ">
        <COMMAND name="sh"
                 help="launch a full shell">
            <ACTION>bash</ACTION>
        </COMMAND>

        <COMMAND name="ps"
                 help="give details of current processes">
            <ACTION>ps -f</ACTION>
        </COMMAND>

        <COMMAND name="ls"
                 help="List the files in the current directory">
                <ACTION>echo ${PWD};ls -F -l -a</ACTION>
        </COMMAND>

        <COMMAND name="exit"
                 help="Go back to main menu"
                 view="root-view">
            <ACTION>echo "Leaving diagnostic mode..."</ACTION>
        </COMMAND>
    </VIEW>

</CLISH_MODULE>

Generated on Tue Apr 29 13:41:07 2008 for CLISH by  doxygen 1.5.1