pshell

A Lightweight, Process-Specific, Embedded Command Line Shell/CLI for C/C++/Python/Go Applications

Overview Getting started Installation Building Documentation Interactive clients     UDP/Unix (datagram) clients         pshell UDP/Unix client         pshellAggregator UDP/Unix client     TCP clients Security Demo programs     pshellServerDemo     traceFilterDemo     traceLogDemo     pshellControlDemo     pshellNoServerDemo     pshellAggregatorDemo     pshellReadlineDemo

Overview

This package contains all the necessary code, documentation and examples for building C/C++/Python/Go applications that incorporate a Process Specific Embedded Command Line Shell (PSHELL). PSHELL is a multi-language, cross platform framework that provides a simple mechanism to embed interactive functions/commands within any C/C++/Python/Go application. Those functions can be invoked interactively either via a separate remote client program, directly from within the application itself, or externally from another process via the control API.

The Python, C/C++, and Go versions are consistent with each other at the API level (i.e. similar functional API, usage, process interaction etc) and fully interoperable with each other at the protocol level and can be mixed and matched in any combination.

The functions/commands are registered as callback functions to the framework. The prototype for the callback functions follow the paradigms of the main for each language. Pshell callback functions can be thought of as a collection of mini mains within the given process that are invoked via their registered keywords. The arguments are passed into each function just like they would be passed into the main from the host's native command line shell (i.e. bash) for each language as shown below. See the included demo programs for language specific examples.

C/C++ callback:

void myFunc(int argc, char *argv[])

Python callback:

def myFunc(argv)

Go callback:

func myFunc(argv []string)

Pshell functions can also display information back to the interactive clients via a mechanism similar to the familiar 'printf' as follows:

C/C++ printf:

void pshell_printf(const char *format, ...)

Python printf:

def printf(string)

Go printf:

func Printf(format string, message ...interface{})

These functions can be invoked via several methods depending on how the internal PSHELL server is configured. The following shows the various PSHELL server types along with their associated invokation method:

• TCP Server : Uses standard telnet interactive client to invoke functions
• UDP Server : Uses included pshell/pshellAggregator interactive clients or control API to invoke functions
• UNIX Server : Uses included pshell/pshellAggregator interactive clients or control API to invoke functions
• LOCAL Server : No client program needed, functions invoked directly from within application itself via local command line interactive prompting

The functions are dispatched via its registered command name (keyword), along with 0 or more command line arguments, similar to command line shell processing.

There is also a control API provided by where any external program can invoke another program's registered pshell functions (only supported for UDP or UNIX pshell servers). This will provide direct programmatic control of a remote process' pshell functions without having to fork the calling process to call the pshell command line client program via the system call. This provides functionality similar to the familiar Remote Procedure Call (RPC) mechanism.

The control API can function as a simple control plane IPC mechanism for inter-process communication and control. If all inter-process control is implemented as a collection of pshell commands, a user can get a programmatic IPC mechanism along with manual CLI/Shell access via the same code base. There is no need to write separate code for CLI/Shell processing and control/message event processing. All inter-process control can then be driven and tested manually via one of the interactive client programs (pshell or pshellAggregator).

The control API supports both unicast and 'multicast' (not true subscriber based multicast like IGMP, it's more like sender based aggregated unicast) messaging paradigms. It also supports messaging to broadcast pshell servers (i.e. UDP server running at a subnet broadcast address, e.g. x.y.z.255).

The following block diagram shows the various server types along with their associated remote client access methods.

See the full README file for a complete description of all the components, installation, building, and usage.

Note, this package was originally hosted at code.google.com as RDB-Lite, it was re-christened as 'pshell' when it was migrated to this hosting service.

Getting started

The following sections describe an overview of getting started with the basic features of the framework.

Installation

All of the included binaries should work for most modern x86_64 based Linux systems as-is. They have been tested on Mint, Ubuntu, and CentOS. To install, there is an install.sh script provided. To see the usage of the install script, from the top level pshell directory run:

$ ./install.sh -h

Usage: install.sh [-local [<shellEnvFile>]]

  This install script will either install this package on a system
  wide basis or will setup a local install environment.  A system
  install must be done as 'root' and will copy all libraries, binaries,
  include files, conf files, and manpages to their customary system
  locations.  A local install will not copy/move any files.  It will
  only create a pshell env file (.pshellrc) that can be sourced in the
  current shell or can be added to your shell env file (i.e. .bashrc)
  that will allow use of the package features from a local directory.

  The location of the local install environment will be the directory
  where this script resides.

  where:
    local        - install locally, omit for system install
    shellEnvFile - name of shell environment file to modify
                   (e.g. full path to your .bashrc)

The simplest install is a local install, from the top level pshell directory run:

$ ./install.sh -local

This will create an environment file, .pshellrc that should be sourced in your system's local command line shell (e.g. bash), it should also be sourced in your host's shell env file, i.e. .bashrc. This will setup several softlinks and environment variables that will allow access to the various parts of the framework.

Building

For targets other than Linux x86_64, the C/C++ and Go code will need to be built from source. This framework has been successfully built and run on Raspbian/Kali ARM Linux, MAC OSX, and Windows Cygwin. To build the C/C++ and Go source, a makefile is provided along with a default make config file, defconfig.

To see the make options, type:

$ make

Usage: make {all | client | lib | demo | install | clean} [verbose=y] [local=y [shellEnvFile=<file>]]

  where:
    all          - build all components of the pshell package
    client       - build the pshell UDP/UNIX stand-alone client programs only
    lib          - build the pshell link libraries only (shared, static and stub)
    demo         - build the pshell stand-alone demo programs only
    install      - build and install all pshell components
    clean        - clean all binaries (libs & executables)
    verbose      - print verbose messages from build process
    local        - specify local install (install target only)
    shellEnvFile - shell env file (i.e. .bashrc) to modify for local install

  NOTE: The install target option will either install this package on a
        system wide basis or will setup a local install environment.  A system
        install must be done as 'root' and will copy all libraries, binaries,
        include files, conf files, and manpages to their customary system
        locations.  A local install will not copy/move any files.  It will
        only create a pshell env file (.pshellrc) that can be sourced in the
        current shell or can be added to your shell env file (i.e. .bashrc)
        that will allow use of the package features from a local directory.

        The location of the local install environment will be the directory
        where this script resides.

To do a make and local install, run:

$ make install local=y

This will compile all the C/C++ and Go code and run the above install.sh script for a local install. Note, to build the C/C++ code, you must have the g++ compiler installed on your host, to build the Go code, you must have the go compiler installed on your host.

Documentation

See the PPT presentation PSHELL-Framework.ppt at the top level directory for an overview of the main features and capabilities of the framework.

There is also documentation for the C/C++ API in the form of manpages in the c/man directory. The following manpages are provided:

pshell(1) pshellAggregator(1) PshellServer(3) PshellControl(3) PshellReadline(3) TraceFilter(3) TraceLog(3)

The following HTML 'pydoc' generated documentation is available in the python/doc directory, the user can also use the command line 'pydoc' to see the embedded documentation on all the corresponding python modules.

pshell.html pshellAggregator.html PshellServer.html PshellControl.html PshellReadline.html TraceLog.html

The following HTML 'godoc' generated documentation is available in the [go/doc](https://github.com/RonIovine/pshell/tree/master/go/