The Usher Shell

The Usher Shell (ush) is a client which provides an interactive command line interface to the Usher system.

Requirements

Requirements for ush are the same as those for Usher clients listed on the Documentation page. I've repeated them below:

The latest Usher release
Python (>=2.3.0)
Twisted (>=2.4.0)
ConfigObj (>=4.4.0)

Download

ush (latest nightly snapshot)
client archives
Mercurial Repository

Installation

Before installing ush, make sure your system has the requisite software for clients listed in the Usher Clients section of the Usher Documentation page. In addition to those requirements, you'll need to have the Usher system installed since ush relies upon modules there. Go to the Usher Downloads page to get the latest version of Usher if you don't already have it installed.

After meeting these requirements, simply download the ush package and run:

$ tar xvzf ush-latest.tgz
$ cd ush-revXXX
$ python setup.py install

You should now have ush installed and ready to use. Run it from the command line as 'ush'. Ush comes with verbose online help. Use it to get general or command specific help. Simply run ush and type '?' at the prompt to get started.

Configuration

Optionally, you can create an ush config file and/or a client API configuration file for use by ush. A sample ush configuration file named ush.config.orig is included in the package. All valid ush configuration options are documented there. You may also want to check out the Client Configuration Files section of the Clients web page to see how client application and client api configuration files work together.

Adding Options

In addition to specifying configuration options, ush gives administrators the ability to create or replace command options through its configuration file. Since Usher is a very modular framework, we can't know all options every plugin will need for every command. Additional option values are passed in the 'kw' parameter to the command for which the option is added.

These additional options are placed under the [extra_options] section. An administrator would typically add options for her infrastructure to a site-wide ush configuration file (i.e. /etc/usher/ush.config). To add an option to a command, first uncomment the [extra_options] header, then add subsections for each option you want to add. In each option subsection, create a sub-subsection for each command you want the option added. In each command sub-subsection, place the attributes for the new option. Typically, you'll just define 'help' and 'type' for your option. A default value can also be specified using 'default'. For boolean options, you'll use 'action=store_true' or 'action=store_false' for what happens when the option is set. To do anything more extravagant, read the optparse documentation.

Sometimes, new options are meant to replace existing options. For example, an IP address handling plugin may replace the 'ip_addrs' option to start with it's own option. To replace the 'ip_addrs', simply put a 'replaces=<option>' in the command subsubsection (E.g. replaces=ip_addrs).

Here's an example of adding an ip_range option to the start command:

[extra_options]

  # Here's the subsection for the option we want to add
  [[ip_range]]

  helpstr=named ip address range from which VM ip addresses should be taken.
  dflt=domU

    # Here's the sub-subsection for the command for which we want to add the option
    [[[start]]]
 
    help = ${helpstr}
    default = ${dflt}
    replaces=ip_addrs

Additional details about adding options to commands can be found in the ush.config.orig file bundled with ush.