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/