fg-shell-new

To invoke the FutureGrid shell please use the following command:

./futuregrid/fg-shell.py

Or if you have followed the deployment as discussed in the deployment manual, just type fg-shell.

You will see that the shell will be started and you will be greeted with a FutureGrid shell prompt "fg>".

Features

The shell has a number of important features hat make it convenient for users to use. One of its features is the use of a context switch that allows the activation of specific commands in a context. This simplifies the amount of typing to execute commands and allows the integration of independently developed command tools into the shell. To illustrate a context let us assume we want to first list all repositories and than upload a new image. Than list all users, add a user and have this user be able to access the image

This can be achieved in a normal shell environment as follows

user -list
user -add -name "Gregor von Laszewski" -id gregor
repo -list
repo -add image.img
repo -access -id gregor

Alternatively whie using a context we can formulate the same task as

use user
list
add -name "Gregor von Laszewski" -id gregor
use repo
add image.img
access -id gregor

Activating a context invokes loading of the context into memory. This allows us to have a lean shell that gets expanded based on the users need. 

Here a summary of important features:

  • CONTEXT concept. (Important to understand how to use the shell) A context is an environment specialized for a particular tool or service. Thus, this is useful to use only the components that we are interested on. For example, if we want to use the image repository we only initialize this service by typing "use repo" and only the image repository commands will be available. See "contexts" and "use" commands.
  • Autocompletion by pressing tab key.
  • Execute system commands when the typed command doesn't exists in the shell or if the command is preceded by the ! character.

Generic Commands

This commands are available in any context.

Help Related Commands

help  [command] List all available commands or detailed information about the specified command.

This command provide the list of all available commands organized by context if we are in the generic context "fg>" (see use and show commands). However, if we are in a specific context (e.g. "fg-repo>") it only show the generic commands and the specific commands of this particular context.  Moreover, you can see the detailed help of a particular command by typing: help command

manual

List detailed information about all commands

shortcuts

List all shortcuts

 

CONTEXT Related Commands

contexts

List of available contexts.

use [context]   

Change the Shell CONTEXT to use a specific FG component. If no argument is provided it returns to the default context.

 

History Related Commands

history, hist and hi 

Show list of executed commands

historysession, hists and his 

Show list of the commands executed in the current session

l, li

List last executed command    

save [N]

Save session history to a file. N => Number of command (from historysession), or `*`.  Most recent command if omitted

 

Execution Related Commands    

load <filename>, exec <filename>

Load commands from an script and stay in the shell

pause [text]

Displays the specified text then waits for the user to press RETURN.

py [command]

py  <command>: Executes a Python command.
py: Enters interactive Python mode. End with ``Ctrl-D`` (Unix) / ``Ctrl-Z`` (Windows), ``quit()``, '`exit()``.

run, r

Re-run the last executed command

script [filename]

When Script is active, all commands executed are stored in a file. Activate it by executing: script [file]. If no argument is provided, the file will be called 'script' and will be located in your current directory. To finish and store the commands use: script end

 

User-Settable Parameters Related Commands

set [parameter] [value]

Sets a cmd2 parameter. Call without arguments for a list of settable parameters with their values.

show

List of settable parameters with their values.

 

Image Repository Commands

This commands are only available when image repository context is active. To activate this context execute "use repo". If we execute help, we will see which commands are generic and which ones are specific of this context.

Image Management Commands

Image management command are activated by

use repo

list [queryString]

List all the images that are visible to the user, or images meeting the criteria defined by the queryString. This feature might provide only basic but the most significant functionalities for Phase II, and it will be augmented during iterative design and development.

setpermission <imgId> <permissionString>

Change the permission of a particular image. This only can be done by the owner and the options are "public" or "private"

get <imgId>

Get an image by specifying its imgId, a unique identifier for an image in the repository. The image will be downloaded to the user's current directory.

put <imgFile> <attributeString>

Store an predefined image provided by the user and register it to the repository. A unique identifier should be returned if successful for later reference and operation.

AttributeString is something like that: vmtype=xen & imgtype=opennebula & os=linux & arch=x86_64. For more information execute "help put" in the image repository context

modify <imgId> <attributeString>

Modify the metadata associated with a particular image

remove <imgId>

Deregister and remove an image from the repository

histimg [imgId]

This return a list of raw data related to the image historical usage information. This is to facilitate other sub-systems like Performance monitoring to get certain statistics of the image usage. For now, we provide information about times accessed, last accessed, created date.

 

User Management Related Commands

User management commands

use user

usage [userId]

This return a list of raw data related to user activities on the repository. For now, we provide information about disk space used, owned images, last access time. Only users with the "admin" role can use this command with no parameters. Normal users only can access to their own reports.

add <userId>

Add new user to the database. Its status will be pending and you need to activate it using  The userId must be the same as the user name in the system. Only users with the "admin" role can use this command. NOTE: The first user created in the database will have the role = "admin" and status = "active".

remove <userId>

Remove user from the database. Only users with the "admin" role can use this command.

list

Get the list of users from the database. Only users with the "admin" role can use this command.

quota -set <userId> <quota>

Modify the quota of a user. The quota is given in bytes, but math expressions are allowed (4*1024*1024). By default each user has 4GB of disk space. Only users with the "admin" role can use this command.

role  -set <userId> <role>

Modify the role of a user. Currently, we only have the "admin" and "user" roles. Only users with the "admin" role can use this command.

status -set <userId> <status>

Modify the status of a user. Currently, the options available are: "pending", "active", "inactive". Only users with the "admin" role can use this command.

 

Examples

Context Usage

  • Show list of available contexts
$fg-shell

fg> contexts

  • The output shows all available contexts

FG Contexts:
-------------
repo
rain
hadoop

  • You can select any of these contexts with the "use" command. Then, the environment of this particular context is initialized.

fg> use repo
fg-repo>
  • Return to the normal context
fg-repo> use
fg>

 

Help Usage

  • List available commands in the generic context
$fg-shell

fg> help
  • The output is something like this. We can see the list of generic commands, the list of commands that are available in the image repository and in the hadoop contexts. Note that the commands listed for each context are only available when you are in this particular context.
A complete manual can be found in http://archive.futuregrid.org/man/fg-shell

Generic Documented commands (type help <topic>):
================================================
contexts  help     historysession  load   py    run   script  shortcuts  use
exec      history  li              pause  quit  save  set     show     

Image Repository commands. Execute "use repo" to use them. (type help <topic>):
===============================================================================
get      histuser  modify  remove         setuserquota  setuserstatus  userdel
histimg  list      put     setpermission  setuserrole   useradd        userlist

Apache Hadoop commands. Execute "use hadoop" to use them. (type help <topic>):
==============================================================================
runjob

Please select a CONTEXT by executing use <context_name>
Execute 'contexts' command to see the available context names
  • List available commands in the hadoop context
fg> use hadoop
fg-hadoop> help      

  • The output is something like this.

A complete manual can be found in http://archive.futuregrid.org/man/fg-shell

General documented commands in the hadoop context (type help <topic>):
======================================================================
contexts  help     historysession  load   py    run   script  shortcuts  use
exec      history  li              pause  quit  save  set     show     

Specific documented commands in the hadoop context (type help <topic>):
=======================================================================
runjob

 

General Shell Usage

  • Session example
$fg-shell

fg> use repo
fg-repo> get img 123123123
fg-repo> list
fg-repo> add javi

  • Create an script file that can be loaded

$fg-shell
fg> script myscript.txt
fg> use repo
fg-repo> put /tmp/image.img vmtype=xen & imgtype=opennebula & os=linux & arch=x86_64
fg-repo> list
fg-repo> script end
  • This will create a file called myscript.txt with this content:
use repo
put /tmp/image.img vmtype=xen & imgtype=opennebula & os=linux & arch=x86_64
list
  • Execute shell commands stored in a file. Then exits from the shell
$ cat myscript.txt| fg-shell

  • Execute shell commands stored in a file from the shell. This stay in the shell.

$ fg-shell
fg> load myscript.txt

More information about cmd and cmd2

http://docs.python.org/library/cmd.html
http://wiki.python.org/moin/CmdModule
http://www.doughellmann.com/PyMOTW/cmd/
http://packages.python.org/cmd2/