Added --state option to nimbus-admin

Created documentation for nimbus-admin and nimbus-nodes in reference.html

docs/src/admin/reference.html

@@ -196,6 +196,26 @@ <h2>Nimbus 2.8 Admin Reference</h2>
 
     </li>
 
+	<li>
+		<p>
+			<a href="#nimbusadministration">Nimbus Administration Tools</a>
+		</p>
+		<ul>
+			<li>
+				<a href="#nimbus-admin">nimbus-admin</a>
+			</li>
+			<li>
+				<a href="#nimbus-nodes">nimbus-nodes</a>
+			</li>
+			<li>
+				<a href="#gen-opts">General Options</a>
+			</li>
+			<li>
+				<a href="#output-opts">Output Options</a>
+			</li>
+		</ul>
+	</li>
+
 
 
 
@@ -2470,10 +2490,193 @@ <h3>Image Cache Configuration _NAMELINK(imagecache-config)</h3>
 <i>cachedir</i> is the path to the image cache and <i>cache_size</i> is 
 the maximum size of the cache.  When these values are enabled the cache
 will be in effect.
+</p>
 
+<a name="nimbusadministration"> </a>
+<h2>Nimbus Administration _NAMELINK(nimbusadministration)</h2>
+<p>
+The nimbus administration tools, nimbus-admin and nimbus-nodes, can be
+used for a number of useful things by an administrator of a nimbus
+service. The nimbus-nodes tool is used for administrating all the VMM
+nodes running on the service. With this tool you are able to list,
+add, update and remove nodes on the service. 
+The nimbus-admin tool allows you to administrate all the running
+virtual machines running on the service. With this tool you can
+list the running VMs in a variety of contexts, as well as manually
+shutdown currently running VMs.
+</p>
+<p>
+Both tools also have a host of reporting output options which will
+be covered later in the following sections.
+</p>
+
+<a name="nimbus-admin"> </a>
+<h3>Nimbus Admin _NAMELINK(nimbus-admin)</h3>
+<p>
+To start using the nimbus-admin tool first go to your nimbus home
+directory. $NIMBUS_HOME/bin where you will find the script
+nimbus-admin. Run ./nimbus-admin --help to see the help file which
+lists all available commands. 
+</p>
+<p>
+<b>List:</b><br />
+The --list command will display a list of virtual machines with the
+following information:<br />
+<b>id:</b> the VM id number<br />
+<b>node:</b> the physical VMM node the VM is running on<br />
+<b>group_id:</b> the group id number this VM is associated with<br />
+<b>group_name:</b> the group name this VM is associated with<br />
+<b>creator:</b> The users DN name who started this VM<br />
+<b>state:</b> Current state of the VM (Running, propagated, etc)<br />
+<b>start time:</b> Time when the VM was created<br />
+<b>end time:</b> Time when the VM gets destroyed<br />
+<b>memory:</b> Amount of memory being used by this VM<br />
+<b>cpu count:</b> Number of cpu cores being used by this VM<br />
+<b>uri:</b> Image and repo information of this VM<br />
+</p>
+<p>
+The following commands can be used with list<br />
+--list (-l)          List the VMs known to the IaaS service<br />
+        --user (-u)     -Option to list VMs by user display name<br />
+        --dn (-d)       -Option to list VMs by user DN name<br />
+        --gid (-g)      -Option to list VMs by group id<br />
+        --gname (-gn)   -Option to list VMs by group name<br />
+        --host (-hn)    -Option to list VMs running under particular host<br />
+<br />
+So an example command would look like:<br />
+./nimbus-admin --list --host localhost
+<br />
+</p>
+<p>
+<b>Shutdown:</b><br />
+The --shutdown command destroys all the virtual machines specified.
+When shutting down a VM, a soft shutdown is called first, which puts
+the VM in "propagated" mode. Once the VM is propagated, it is then
+fully destroyed. VMs can be shutdown in the following ways:<br />
+--all (-a)       -Option to shutdown all running VMs on service<br />
+--id (-i)        -Option to shutdown VM by VM id<br />
+--user (-u)      -Option to shutdown VM by user display name<br />
+--dn (-d)        -Option to shutdown VM by user DN name<br />
+--gid (-g)       -Option to shutdown VM by group id<br />
+--gname (-gn)    -Option to shutdown VM by group name<br />
+--host (-hn)     -Option to shutdown all VMs with specified host<br />
+--seconds (-s)   -Amount of time to wait for VMs to shutdown to
+                            propagation mode before being trashed. If
+                            seconds option not specified, default is a
+                            maximum of 30 seconds
+<br /><br />
+Example: ./nimbus-admin --shutdown --all<br /><br />
+The --shutdown command also allows you to shutdown a list of VMs at once
+by using a comma-separated list.<br />
+Example: ./nimbus-admin --shutdown --id 3,4,5,6,10,13<br />
+</p>
+<p>
+<b>Nodes:</b><br />
+The --nodes command shows a list of all the VMM nodes running on the
+service with a list of VM ids each one is running.
+Example: ./nimbus-admin --nodes<br /><br />
+node1: 3,4,5<br />
+node2: 1,2,6<br /><br />
+</p>
+
+<a name="nimbus-nodes"> </a>
+<h3>Nimbus Nodes _NAMELINK(nimbus-nodes)</h3>
+<p>
+To start using the nimbus-nodes tool first go to your nimbus home
+directory. $NIMBUS_HOME/bin where you will find the script
+nimbus-nodes. Run ./nimbus-nodes --help to see the help file which
+lists all available commands.
+</p>
+<p>
+<b>List:</b><br />
+The --list command of nimbus-nodes lists all the VMM nodes running
+on the service. You can also input a comma separated list of VMMs
+to list if you want to specify which VMMs you want to see. The
+list function outputs the following information about each node:
+<br /><br />
+<b>hostname:</b>the VMM node name<br />
+<b>pool:</b>Resource pool name for this node<br />
+<b>memory:</b>total memory available for this node<br />
+<b>memory available:</b>current memory available on the node<br />
+<b>networks:</b>list of networks associated with this node.
+Value of * means all available networks<br />
+<b>in_use:</b>whether or not this node is being used<br />
+<b>active:</b>whether or not this node is currently running<br />
+<br />
+</p>
+<p>
+<b>Add:</b><br />
+The --add (-a) HOSTS command adds the specified VMM nodes to the
+pool. Node paramets can be specified as additional arguments and
+if no parameter is specified a default will be read from the
+config file.
+</p>
+<p>
+<b>Update:</b><br />
+The --update (-u) HOSTS command updates the configuration values
+of VMM nodes. At least one node parameter must be specified as
+an additional argument. 
+</p>
+<p>
+<b>VMM Node Parameters</b><br />
+The following node parameters can be used as additional arguments
+for the --add and --update commands. 
+<br /><br />
+<i>--active (-A)</i> Allow VMM nodes to take on new virtual machines.
+Default for new nodes.<br />
+<i>--inactive (-i)</i> Prevent VMM nodes from accepting new VMs.
+This will not terminate any already running VMs.<br />
+<i>--memory (-m)</i> Maximum memory available on node for VMs<br />
+<i>--networks (-n)</i> List of networks associated with a node.
+A value of * means all available networks<br />
+<i>--pool (-p)</i> Resource pool name for this VMM node<br />
+</p>
+<p>
+<b>Remove</b><br />
+The --remove (-d) command removes VMM nodes from the nimbus resource 
+pool. In use nodes cannot be removed.
+</p>
+<p>
+<b>Network Pool Allocation</b><br />
+The --allocation (-N) command provides network pool allocation
+information. Outputs the following information for each pool
+entry: hostname, ip, mac address, broadcast, subnet mask, gateway,
+in_use, explicit mac.<br /><br />
+This command also has three optional commands.<br/>
+<b>--pool</b> allows you to enter a pool name and only displays
+entries from that pool<br />
+<b>--free</b> displays only entries that are not in_use<br />
+<b>--used</b> displays only entries that are in_use<br />
+</p>
 
+<a name="gen-opts"> </a>
+<h3>General Options _NAMELINK(gen-opts)</h3>
+<p>
+These options are for general usage of nimbus-nodes and nimbus-admin
+<br /><br />
+<b>--help (-h)</b> Prints help file<br />
+<b>--conf (-c)</b> Use to specify an alternate configuration file.<br />
+<b>--debug</b> Enables debug output for troubleshooting
+</p>
+
+<a name="output-opts"> </a>
+<h3>Reporting Output Options _NAMELINK(output-opts)</h3>
+<p>
+nimbus-nodes and nimbus-admin also have various reporting outputs
+that can be used. These options work with any of the commands listed
+above.
+<br /><br />
+<b>--report (-r) FIELDS: </b>Only report specified fields. Argument
+is a comma-separated list<br />
+<b>--batch (-b): </b>Report results with one record perline, using
+an optional delimiter.<br />
+<b>--delimiter (-D): </b>Delimiter between fields in batch mode.
+Default is a single space.<br />
+<b>--json (-j): </b>Report results in JSON format.<br />
+<b>--output (-o) FILE:</b>Write results to FILE instead of stdout.
 </p>
 
+
 
 <br />
 <br />

service-api/java/source/src/org/nimbustools/api/services/admin/RemoteAdminToolsManagement.java

@@ -41,6 +41,7 @@ public interface RemoteAdminToolsManagement extends Remote {
     public String getAllVMsByHost(String hostname) throws RemoteException;
     public String getAllVMsByGroupId(String groupId) throws RemoteException;
     public String getAllVMsByGroupName(String groupName) throws RemoteException;
+    public String getVMsByState(String state) throws RemoteException;
     public Hashtable<String, String[]> showVMsForAllHosts() throws RemoteException;
     public String shutdown(int type, String typeID, String seconds) throws RemoteException;
 }

service/service/java/source/src/org/globus/workspace/remoting/admin/client/Opts.java

@@ -207,13 +207,18 @@ public Options getOptions() {
     public final Option NODE_LIST_OPT =
                 OptionBuilder.withLongOpt(NODE_LIST_LONG).create(NODE_LIST);
 
+    public static final String STATE = "S";
+    public static final String STATE_LONG = "state";
+    public final Option STATE_OPT =
+                OptionBuilder.withLongOpt(STATE_LONG).hasArg().create(STATE);
+
     public final Option[] ALL_ENABLED_OPTIONS = {
             HELP_OPT, DEBUG_OPT, CONFIG_OPT, BATCH_OPT, DELIMITER_OPT,
             REPORT_OPT, JSON_OPT, OUTPUT_OPT, ADD_NODES_OPT, LIST_NODES_OPT,
             REMOVE_NODES_OPT, UPDATE_NODES_OPT, POOL_AVAILABILITY_OPT, NETWORKS_OPT, MEMORY_OPT, POOL_OPT,
             ACTIVE_OPT, INACTIVE_OPT, LIST_VMS_OPT, SHUTDOWN_VMS_OPT, USER_OPT, ID_OPT,
             SECONDS_OPT, ALL_VMS_OPT, HOST_OPT, DN_OPT, GROUP_ID_OPT,
-            GROUP_NAME_OPT, FREE_OPT, USED_OPT, NODE_LIST_OPT
+            GROUP_NAME_OPT, FREE_OPT, USED_OPT, NODE_LIST_OPT, STATE_OPT
     };
 
 }

service/service/java/source/src/org/globus/workspace/remoting/admin/client/RemoteAdminToolsMain.java

@@ -63,6 +63,7 @@ public class RemoteAdminToolsMain extends RMIConfig {
     private String groupName;
     private String hostname;
     private String seconds;
+    private String state;
     private List<String> vmIDs;
     private List<String> userList;
     private List<String> DNList;
@@ -222,6 +223,14 @@ private void loadArgs(String[] args) throws ParameterProblem {
                     this.hostname = hostname;
                     numOpts++;
                 }
+                if(line.hasOption(Opts.STATE)) {
+                    final String state = line.getOptionValue(Opts.STATE);
+                    if(state == null || state.trim().length() == 0) {
+                        throw new ParameterProblem("State value is empty");
+                    }
+                    this.state = state;
+                    numOpts++;
+                }
         }
         else if(this.action == ToolAction.ShutdownVMs) {
                 if(line.hasOption(Opts.ALL_VMS)) {
@@ -394,6 +403,14 @@ else if(this.hostname != null) {
                 }
                 vms = gson.fromJson(vmsJson, VMTranslation[].class);
             }
+            else if(this.state != null) {
+                final String vmsJson = this.remoteAdminToolsManagement.getVMsByState(state);
+                if(vmsJson == null) {
+                    System.err.println("No vms with state " + state + " found");
+                    return;
+                }
+                vms = gson.fromJson(vmsJson, VMTranslation[].class);
+            }
             else {
                 final String vmsJson = this.remoteAdminToolsManagement.getAllRunningVMs();
                 vms = gson.fromJson(vmsJson, VMTranslation[].class);

service/service/java/source/src/org/globus/workspace/remoting/admin/client/adminHelp.txt

@@ -21,6 +21,7 @@ Actions
         --gid (-g)          -Option to list VMs by group id
         --gname (-gn)       -Option to list VMs by group name
         --host (-hn)        -Option to list VMs running under particular host
+        --state (-S)        -Option to list VMs by their current state
 
     --nodes              Lists all nodes on the service with a list of all
                          VM ids running on each particular node

service/service/java/source/src/org/globus/workspace/remoting/admin/defaults/DefaultRemoteAdminToolsMgmt.java

@@ -160,6 +160,25 @@ public String getVMsByUser(String user) throws RemoteException {
         }
     }
 
+    public String getVMsByState(String state) throws RemoteException {
+        try {
+            VM[] vms = manager.getGlobalAll();
+            final List<VMTranslation> vmts = new ArrayList<VMTranslation>();
+            for(VM vm : vms) {
+                if(vm.getState().getState().equalsIgnoreCase(state))
+                    vmts.add(translateVM(vm));
+            }
+
+            if(vmts.size() == 0)
+                return null;
+
+            return gson.toJson(vmts);
+        }
+        catch(ManageException e) {
+            throw new RemoteException(e.getMessage());
+        }
+    }
+
     public Hashtable<String, String[]> showVMsForAllHosts() throws RemoteException {
         try {
             List<String> hostnames = new ArrayList<String>();