gWLM A.03.00.00 manpages

gwlm(1M)
gwlmagent(1M)
gwlmcmsd(1M)
gwlmdeletekey(1M)
gwlmexportykey(1M)
gwlmimportkey(1M)
gwlmlistkeys(1M)
gwlminitconfig(1M)
gwlmplace(1M)
gwlmreport(1M)
gwlmsend(1M)
gwlmsslconfig(1M)
gwlmstatus(1M)

gwlmxml(4)

gwlm(5) Overview of gWLM

gwlm(1M)

Date: 2007/03/21 
Revision: 1.59 

NAME

      gwlm - Global Workload Manager

SYNOPSIS

      gwlm command [options]

AVAILABILITY

      This command is available only on gWLM Central Management Servers
      (systems where you run gwlmcmsd).

DESCRIPTION

      The gwlm command is a command-line interface for Global Workload
      Manager (gWLM).  It allows an administrator on the gWLM Central
      Management Server (CMS) to interact with gWLM when a web browser is
      unavailable or inconvenient.

      NOTE: The configuration repository mentioned below is created when you
      run the vseinitconfig --initconfig command on the CMS.

      Valid values for command are:

	   list	       List the contents of the configuration repository.


	   discover    Discover potential shared resource domains.


	   import      Import definitions for shared resource domains,
		       policies, or workloads into the configuration
		       repository.


	   export      Export all the definitions in the configuration
		       repository or only the definitions for the specified
		       shared resource domains, policies, and workloads.


	   deploy      Deploy a shared resource domain.


	   undeploy    Undeploy a shared resource domain.


	   manage      Manage an additional workload by associating it with
		       a deployed shared resource domain.


	   unmanage    Stop managing a workload by removing it from its
		       shared resource domain.


	   delete      Delete definitions for shared resource domains,
		       policies, or workloads from the configuration
		       repository.


	   rename      Rename a shared resource domain, policy, or workload.


	   license     Check gWLM software license status on managed nodes.


	   monitor     Monitor gWLM operation.


	   history     Manage historical data.


	   agentinfo   Display agent information.


	   reset       Reset agent configuration so host can be managed
		       again.

COMMANDS

      This section describes the use of each command.  A summary help
      message is available for each command by specifying the option --help
      with the command.	 Note that option arguments are introduced by two
      dash characters (--), not a single dash character (-).



    list [--policy[=policy]] [--workload[=workload]] [--srd[=SRD]] [...]

      List the contents of the configuration repository.

				 Arguments
      If you do not specify any arguments, the entire contents are listed.

      --policy[=policy]
		  List all policies. Limit the listing to a particular
		  policy by indicating the policy's name.

      --workload[=workload]
		  List all workloads.  Limit the listing to a particular
		  workload by indicating the workload's name.

      --srd[=SRD] List all shared resource domains.  Limit the listing to a
		  particular shared resource domain by indicating the SRD's
		  name.

    discover [--file=file] [--type=type] [--verbose] host [...]
      or

    discover [--file=file] --nested --type=type [...] [--verbose] host [...]

      Discover potential shared resource domains.  A summary of the results
      is written to stdout.

      To create an SRD, specify --file=file to save detailed results in XML
      format then use file as input for an import operation.

				 Arguments
      --file=file Save the results to the specified file in XML format.

      --nested	  Create SRDs with nested partitions, such as fss groups
		  inside vpars, with gWLM managing resources for all the
		  partition types.

		  NOTE: No more than one deployed SRD per complex should
		  have nested partitions.

		  --type is required when you specify --nested.	 Specifying
		  --type just once manages only compartments of that type
		  for all the given hosts.  Specifying --type for each host
		  manages different compartments for the different hosts.
		  (You can indicate each type and its host by specifying
		  --type immediately followed by its host for each type-host
		  combination. Alternatively, you can enter all the --type
		  options followed by all the hosts, with the type and host
		  matched based on the order.)

		  For example, if a complex is divided into four npars each
		  with Instant Capacity installed, two of the npars could be
		  further divided into fss groups and the other two npars
		  could be divided into vpars. gWLM would manage resource
		  allocations for the fss groups or vpars within a given
		  npar, but it could also migrate resources among the npars.
		  Such a command might look like:


		  # gwlm discover --file=/tmp/mySRD --nested \
		    --type=fss nparA --type=fss nparB \
		    --type=vpar nparC --type=vpar nparD

      --type=type Set discovery type to one of fss, pset, vpar, npar, or
		  hpvm.	 Compartments for your workloads are based on the
		  type.	 By default, all types are discovered. Seeing all
		  types allows you to better decide which type to use. Once
		  you decide on the type to use, this option allows you to
		  restrict the discovery results to that type.	(gWLM
		  manages only one compartment type in an SRD, unless you
		  use the discover --nested option.  You must specify --type
		  at least one time when you specify --nested.)

      --verbose	  Display verbose output, showing:

		  + All the discovered compartment data

		  + Diagnostic informational messages about the discovery
		    (Warnings are displayed regardless of whether --verbose
		    is used.)

		  Use this output to better understand how a discovered SRD
		  was formed or to determine discovery issues.

      host	  Hostname of a managed node to check for potential SRDs.
		  Specify multiple hosts separated by white space. (The
		  gwlmagent process must be running on each specified host.)

    import [--file=file] [--clobber] [--mute]
      Import a definition for a shared resource domain, policy, or workload
      into the configuration repository.  The input, in XML form, is taken
      from stdin unless you specify the --file option. (The XML is described
      in the gwlmxml(4) manpage.)

      If you import the definition of an SRD that has the same name as a
      deployed SRD, the newly imported SRD is deployed--taking the place of
      the first SRD. Similarly, if you import a workload definition or
      policy definition and a workload or policy of the same name is in a
      deployed SRD, the new definition is used immediately.

				 Arguments
      --file=file Read from the specified XML file.

      --clobber	  Force an overwrite of an existing definition.	 This option
		  is required if a definition being imported modifies a
		  definition in the repository that is more recent.

      --mute	  Suppress validation warnings. If there are validation
		  errors though, the validation errors and warnings are
		  displayed.


    export
    { --all | --policy=policy | --workload=workload | --srd=SRD } [...]
    [--file=file]
      Export all the definitions in the configuration repository or only the
      definitions for the specified shared resource domains, policies, and
      workloads.  The output is in XML format and is described in the
      gwlmxml(4) manpage.  Export multiple items by repeating arguments.


				 Arguments
      --all	  Export all the definitions in the configuration
		  repository.

      --policy=policy
		  Export the definition for the specified policy.

      --workload=workload
		  Export the definition for the specified workload.

      --srd=SRD	  Export the definition for the specified SRD.

      --file=file Redirect the XML output to the specified file.



    deploy --srd=SRD [...] [--force] [--mute]
      Deploy a shared resource domain, in either advisory mode or managed
      mode. (You set this mode in the SRD definition.) When an SRD is
      deployed in advisory mode, gWLM simply reports what the resource
      allocations would be--without actually affecting allocations on the
      system.  (Advisory mode is not available if the SRD contains virtual
      machines, psets, or fss groups.)	When you deploy an SRD in managed
      mode, gWLM begins managing the SRD, migrating resources among
      workloads as specified in your policies.

      Deploy multiple, nonoverlapping SRDs by repeating the --srd=SRD
      argument.

      NOTE: There are several properties you can set in the file
      /etc/opt/gwlm/conf/gwlmcms.properties that are read by gWLM only when
      deploying SRDs. Read the file and set any relevant properties before
      you deploy any SRDs.

				 Arguments
      --srd=SRD	  Deploy the named shared resource domain (SRD).

      --force	  Force the SRD to be considered deployed in the gWLM
		  configuration repository. This option is useful when the
		  gWLM CMS and an agent disagree about whether an SRD is
		  deployed or undeployed.

      --mute	  Suppress validation warnings. If there are validation
		  errors though, the validation errors and warnings are
		  displayed.


    undeploy --srd=SRD [...] [--force]
      Undeploy a shared resource domain. Undeploy multiple SRDs by repeating
      the --srd=SRD argument.

				 Arguments
      --srd=SRD	  Undeploy the specified shared resource domain.

      --force	  Force the SRD to be considered undeployed in the gWLM
		  configuration repository. This option is useful when the
		  gWLM CMS and an agent disagree about whether an SRD is
		  deployed or undeployed.

      NOTE: When undeploying SRDs based on pset compartments or fss group
      compartments, gWLM removes the compartments. gWLM does not remove
      virtual machine (hpvm) compartments, vpar compartments, or npar
      compartments.


    manage --host=host --type={ fss | pset | vpar | npar }
	   --workload=workload [--mute]
      or

    manage --host=host --type=hpvm
	   --workload=workload [--mute]
	   [--id=name_or_guid]
      Add an existing workload to the deployed SRD. The workload, which must
      already be defined in the configuration repository, is associated with
      a compartment of its own (of the specified type) on the named host.
      The workload automatically becomes a part of the SRD managing the
      specified compartment type on that host. To add multiple workloads,
      invoke gwlm manage multiple times.

      A workload can be in only one deployed SRD at a time. (The same
      workload can be in multiple undeployed SRDs.)

      NOTE: When you have workloads based on psets or fss groups: If you let
      processes run in the default pset or the default fss group, they will
      be competing against all the other processes that are not explicitly
      placed in workloads. To ensure appropriate resource allocations for
      your processes, place them in workloads by specifying <user> tags or
      <application> tags when defining workloads, as explained in the
      gwlmxml(4) manpage, or by using the gwlmplace command.

      NOTE: Placing an additional workload in an SRD affects resource
      allocations for the workloads originally in the SRD. After adding a
      workload, evaluate how allocations are affected using gwlm monitor
      --srd=SRD --view=policy.	Then adjust the associated policies if
      needed, as shown in the "ADJUSTING POLICIES AFTER A 'manage' OR
      'unmanage'" section below.

				 Arguments
      --host=host Specify the host on which the workload will run.

      --type={ fss | pset | vpar | npar | hpvm }
		  Specify the type of compartment in which the workload will
		  run. If you specify fss or pset, gWLM creates an fss group
		  or pset for the workload. If you specify vpar or npar, the
		  vpar/npar must already exist. If you specify hpvm, the
		  virtual machine must already exist.

      --workload=workload
		  Specify the name of the workload in the configuration
		  repository to add to the deployed SRD.

		  workload must have an associated policy (contain a policy
		  reference). Also, workload must not already be in a
		  deployed SRD.

		  Find names of workloads in the repository using the gwlm
		  list command.

      --mute	  Suppress validation warnings. If there are validation
		  errors though, the validation errors and warnings are
		  displayed.

      --id=name_or_guid
		  Specify, if desired, one of the following for the virtual
		  machine to be managed:

		  + The name of the virtual machine (as set using HP
		    Integrity Virtual Machines or HP Integrity Virtual
		    Machines Manager)

		  + The GUID of the virtual machine
		    (appears in the <nativeId> element in the XML)

		  gWLM attempts to determine this information automatically;
		  however, an error is generated if gWLM is not successful.

    unmanage --workload=workload [--mute]
      Stop managing a workload by removing it from its SRD. (The workload
      definition remains in the configuration repository, but it is no
      longer associated with its SRD.) To stop managing multiple workloads,
      invoke gwlm unmanage multiple times.

      You cannot unmanage the last workload in an SRD. To stop managing an
      SRD, use the undeploy command.

      With virtual machine (hpvm) compartments, you can only unmanage
      stopped virtual machines. An unmanaged virtual machine cannot be
      started while gWLM remains in control of the virtual machine host.

      If the workload's compartment is an fss group or a pset, gWLM destroys
      the compartment and moves the processes that were in the compartment
      to the default compartment. If the compartment is a vpar, npar, or
      virtual machine, gWLM does not destroy the compartment. (A compartment
      based on a vpar or npar must have a fixed policy to be unmanaged. A
      virtual machine must be stopped to be unmanaged.)

      NOTE: Unmanaging a workload affects resource allocations for the
      workloads remaining in the SRD. After unmanaging a workload, evaluate
      how allocations are affected using gwlm monitor --srd=SRD
      --view=policy.  Then adjust the associated policies if needed, as
      shown in the "ADJUSTING POLICIES AFTER A 'manage' OR 'unmanage'"
      section below.

				 Arguments
      --workload=workload
		  Stop managing the specified workload.

      --mute	  Suppress validation warnings. If there are validation
		  errors though, the validation errors and warnings are
		  displayed.


    delete { --policy=policy | --workload=workload | --srd=SRD } [...]
      Delete a definition for a policy, workload, or shared resource domain
      from the configuration repository. The definition cannot currently be
      in use as part of a deployed configuration. Delete multiple items by
      repeating the following arguments.

				 Arguments
      --policy=policy
		  Delete the definition for the specified policy.

      --workload=workload
		  Delete the definition for the specified workload.

      --srd=SRD	  Delete the definition for the specified shared resource
		  domain (SRD).


    rename { --policy | --workload | --srd } oldname newname
      Rename a policy, workload, or shared resource domain. To rename
      multiple items, invoke gwlm rename multiple times.

				 Arguments
      --policy	  Rename the policy about to be specified.

      --workload  Rename the workload about to be specified.

      --srd	  Rename the SRD about to be specified.

      oldname newname
		  Rename the policy, workload, or shared resource domain
		  that is named oldname to newname.

    license [--host=host] [...]
      Check the status of the gWLM software licenses on the managed nodes.

				 Arguments
      --host	  Check licenses for only the specified hosts.

				  Output
      Here is sample output for this command:

 SRD		Host	Status License
 ______________ _______ ______ _____________________________________________
 sys1.srd	sys1	OK     License is unrestricted.
 sys2.srd	sys2	OK     License will expire Thu Jun 16 14:01:43 2005.
 sys3.srd	sys3	Warn   License will expire Fri Feb 18 13:48:12 2005.
 sys4.srd	sys4	Error  License expired Thu Feb 17 12:48:12 2005.

      In the Status column, the three possible entries are:

      OK	  The managed node has a license installed that is either
		  unrestricted or expires more than seven days into the
		  future.

      Warn	  The managed node has a license that expires within seven
		  days.

      Error	  The managed node has an expired license.

    monitor [--count=n]
	    { --policy=policy
	    | --workload=workload [--view={ resource | policy }]
	    | --srd=SRD [--view=resource] [--nested]
	    | --srd=SRD --view=policy
	    | [--srd]}
      Monitor gWLM operation. When you specify no arguments, the output is
      the same as if you had specified --srd.  The output is described in
      the section "gwlm monitor OUTPUT DESCRIPTIONS" below.

				 Arguments
      --count=n	  Set the number of updates to display before exiting.	By
		  default, monitoring continues until interrupted or until
		  the item being monitored is no longer part of a deployed
		  SRD.

      --policy=policy
		  Monitor the specified policy in each deployed SRD in which
		  it is associated with a workload.

      --workload=workload [--view=view]
		  Monitor the specified workload. See --view for information
		  on selecting the view.

      --srd[=SRD [--view=view]]
		  Monitor deployed shared resource domains. Displays a
		  summary view of all deployed shared resource domains. If a
		  specific shared resource domain is given by SRD, a more
		  detailed view is presented. See --view for information on
		  selecting the view.

      --nested	  Monitor nested partitions for the named SRD.

      --view=view Choose a view, either resource or policy, for monitoring a
		  specific SRD or workload.  The resource view monitors
		  resource information for a workload, including size and
		  utilization. The policy view focuses on how well policies
		  are being met.  By default, the view is set to resource.

    history { --truncate=CCYY/MM/DD | --purge=days | --flush[=SRD] }
      Manage the historical data used in generating reports.

				 Arguments
      --truncate=CCYY/MM/DD

		  Perform the following operations:

		  + Locate the last successful configuration save before or
		    on CCYY/MM/DD and remove the configuration data prior to
		    that save

		  + Remove any historical monitoring data on the CMS that
		    has a timestamp earlier than CCYY/MM/DD.

		  For example, with CCYY/MM/DD equal to 2005/01/15 and the
		  last successful configuration save on 2005/01/10, all
		  configuration data before that save on 2005/01/10 is
		  removed. Also, all historical data up through the end of
		  January 14, 2005 is removed.

      --purge=days
		  Remove from the database all historical and configuration
		  data that is older than the specified number of days.

      --flush[=SRD]
		  Collect the historical data from the managed nodes in the
		  specified SRD, placing it in the historical database. If
		  no SRD is specified, collect all historical data from all
		  the managed nodes.

		  Use this command if:

		  + An SRD has been running for a long period of time
		    without any configuration changes and you want to view
		    historical data from the current day

		  + You are about to create an advanced report


    agentinfo [--host=host] [--srd=SRD]
      Display an agent's host, gWLM version, SRD, and CMS. (The agent must
      be in a deployed SRD.)

				 Arguments
      --host=host Display information for the agent on host.

      --srd=SRD	  Display information for the agents in the named SRD.

      With no arguments specified, agentinfo displays information for all
      deployed SRDs.


    reset --host=host [...]
      Reset the configuration on host so the host can be managed in an SRD
      again.

      reset is an advanced command for clearing an SRD. The recommended
      method for typically removing a host from management is to use the
      gwlm undeploy command.

      If gWLM is unable to reform an SRD that includes host after host or
      its gWLM agent loses contact with the CMS, use reset to clear the SRD
      on the specified host.

      After using reset, you can configure the host in a new SRD.

gwlm monitor OUTPUT DESCRIPTIONS

      The columns you see in the various gwlm monitor output are described
      below.

      Allocation
	   The amount of a resource, such as CPU, that gWLM sets aside for a
	   workload after arbitrating resource requests from the policies
	   for all the workloads.

	   A double-dash entry (--) indicates the workload contains nested
	   partitions. For allocation information, see each individual
	   nested partition.

	   In managed mode, gWLM makes an allocation available to a
	   workload. In advisory mode, however, gWLM simply reports what the
	   allocation would be--without actually affecting resource
	   allocations on a system.  (Advisory mode is not available for
	   SRDs containing virtual machines, psets, or fss groups.)

      Measured
	   For fixed policies: A compartment's size is the amount of CPU
	   resources allocated to the compartment.

	   For all other policies: The current value of a metric being used
	   in the policy. This metric could be CPU utilization or a metric
	   you provide in a custom policy.

      Policy
	   The name of a policy.

      Request
	   The amount of a system resource that a policy asks gWLM to give
	   to the policy's workload. (Parameters you specify in defining a
	   policy restrict its request.)

      Shared Resource Domain
	   The name of a shared resource domain.

      Size
	   The amount of a resource a compartment actually has.

	   A size appearing in parentheses indicates the item contains
	   nested partitions. Such a size corresponds to the sum of the
	   sizes of the nested partitions the item contains.

	   When gWLM is deployed in advisory mode, size may differ from the
	   allocation. In advisory mode, utilization is the percentage
	   resulting from dividing a workload's consumption (how much it is
	   using) by its size.

      Target
	   For fixed policies: The target CPU allocation.

	   For utilization and OwnBorrow policies: The target utilization
	   percentage.

	   For custom policies: The target value entered when creating the
	   policy.

      Type
	   The compartment type.

      Utilization
	   The percentage resulting from dividing a workload's consumption
	   (how much it is using) by its allocation (how much gWLM gave it).

	   A utilization appearing in parentheses indicates the item
	   contains nested partitions. Such a utilization corresponds to an
	   average of the utilizations of the nested partitions the item
	   contains.


      Workload
	   The name of a workload.

	   With --nested, workload names are indented to indicate the
	   nesting of partitions.  Items appearing in parentheses contain
	   nested partitions.

ADJUSTING POLICIES AFTER A 'manage' OR 'unmanage'

      The manage and unmanage operations both change the set of workloads in
      an SRD. Such a change can affect resource allocations for the SRD's
      new set of workloads. Consequently, you should evaluate allocations in
      the new SRD (using gwlm monitor --srd=SRD --view=policy) to determine
      whether policy changes are needed to ensure resource allocations are
      as desired.

      NOTE: When using gWLM A.01.00 agents or A.01.01.x agents, gWLM limits
      the combinations of policies. For example, you cannot deploy an SRD
      that has both utilization policies and OwnBorrow policies being used.

      If policy changes are needed, you have several options:

	 + Change which policy is associated with a workload

	   1. Export the workload's definition:
	      gwlm export --workload=workload --file=file

	   2. Edit the definition to use a different policy:
	      Change the "<policyReference>" entry

	   3. Import the definition:
	      gwlm import --file=file

	 + Edit the policy definition

	   1. Export a policy being used:
	      gwlm export --policy=policy --file=file

	   2. Edit the definition, as explained in the gwlmxml(4) manpage.

	   3. Import the definition:
	      gwlm import --file=file

	   This new definition will supersede the policy in effect for all
	   workloads referencing the given policy's name.

	 + Create a new policy

	   You can create a new policy and then import it into the
	   configuration repository. You would then change the workload's
	   definition--as described earlier in this example--to reference
	   the new policy.

EXAMPLES

    Creating SRDs
      The only way to create SRDs is through discovery, as described below:

      1. Run the gwlm discover command as follows to form an SRD based on
	 vpars:

	 # gwlm discover host --file=file --type=vpar

	 Use the discover command without the --type option if you would
	 like to see a listing of the compartment types available on host
	 before committing to a certain type.

      2. Edit file to change the SRD's generated name or mode, if desired.

      3. Import the XML file into the configuration repository:

	 # gwlm import --file=file

      4. Deploy the SRD:

	 # gwlm deploy --srd=SRD

	 where SRD is the name of the SRD as specified in file, when you are
	 ready for gWLM to manage the resource allocation for the workloads
	 in the SRD.

    Adding a new workload to an SRD
      To add a workload to a deployed SRD:

      1. Define a workload, as explained in the gwlmxml(4) manpage, in an
	 XML file, called file for example.

	 NOTE: When you have workloads based on psets or fss groups: If you
	 let processes run in the default pset or the default fss group,
	 they will be competing against all the other processes that are not
	 explicitly placed in workloads. To ensure appropriate resource
	 allocations for your processes, place them in workloads by
	 specifying <user> tags or <application> tags when defining
	 workloads or by using the gwlmplace command.

      2. Import the XML file into the configuration repository:

	 # gwlm import --file=file

      3. Display the names of the deployed SRDs to which you can add the
	 workload.

	 Use either of the following commands:


	 # gwlm monitor --count=1

	 # gwlm --list=srd

	 With the second command, look for SRDs with "deployed=true".

	 NOTE: You can go to Step 5 if you already know the name of the SRD
	 to which you want to add the workload.

      4. Export the SRDs to determine what hosts and types of compartments
	 they manage:

	 # gwlm export --srd=SRD

	 Repeatedly invoke this command, replacing SRD for each SRD found in
	 the gwlm monitor output in the previous step until you find the SRD
	 to which you want to add the workload.

      5. Add the workload to a deployed SRD of the desired compartment type
	 using the manage command:

	 # gwlm manage --host=host --type=type --workload=workload

      6. Adjust policies for other workloads if needed. See the section
	 "ADJUSTING POLICIES AFTER A 'manage' OR 'unmanage'" above for
	 additional information.

    Removing a workload from an SRD
      To remove a workload from an SRD, leaving the workload's definition in
      the configuration repository:

      1. Determine the name of the workload to remove:

	 # gwlm list --workload

      2. For a workload in an npar or a vpar compartment, set its associated
	 policy to a fixed policy before unmanaging the workload.

      3. Remove the workload from its SRD:

	 # gwlm unmanage --workload=workload

	 NOTE: For psets and fss groups, if you unmanage the corresponding
	 workload, any processes running in the compartment are moved. gWLM
	 places these processes in new compartments based on application
	 records or user records. If those compartments do not exist or no
	 records exist, gWLM places the processes in the default pset or
	 default fss group. (You create records with the "<user>" and
	 "<application>" tags in your XML file, as explained in the
	 gwlmxml(4) manpage.  You can also create records through HP Systems
	 Insight Manager using gWLM's Edit Workloads window.)
      4. Adjust policies for other workloads if needed. See the section
	 "ADJUSTING POLICIES AFTER A 'manage' OR 'unmanage'" above for
	 additional information.

    Monitoring
      The gwlm monitor command offers the output shown below. (Some of the
      output has been modified for formatting purposes.)

      For an explanation of the column headings, see the section above
      called "gwlm monitor OUTPUT DESCRIPTIONS."

      The first example lists the deployed SRDs. (You get the same output if
      you enter the command gwlm monitor --srd.)

      # gwlm monitor

      Wed Dec 13 14:16:00 2006
      Number of deployed Shared Resource Domains: 1

      Shared Resource Domain	Allocation	      Size  Utilization
      ______________________  ____________  ______________  ___________
      mysystem1.srd		   8 Cores	   8 Cores	 20.1 %

      From the previous command, we got the name of an SRD. We can use that
      name to get either a resource view (the default) or policy view of the
      SRD, as shown in the following two examples.

      # gwlm monitor --srd=mysystem1.srd --view=resource

      Wed Dec 13 14:16:30 2006
      Shared Resource Domain: mysystem1.srd

      Workload		      Type    Allocation	    Size  Utilization
      __________________  ________  ____________  ______________  ___________
      mysystem1.OTHER	      pset	 4 Cores	 4 Cores	3.3 %
      mysystem1.prod	      pset	 4 Cores	 4 Cores	3.0 %
      __________________  ________  ____________  ______________  ___________
      Totals				 8 Cores	 8 Cores	3.2 %

      # gwlm monitor --srd=mysystem1.srd --view=policy

      Wed Dec 13 14:18:00 2006
      Shared Resource Domain: mysystem1.srd

      Policy	       Workload		     Target	Measured      Request
      _______________  _______________ ____________ ____________ ____________
      Owns_4-Max_8     mysystem1.OTHER	    75.00 %	  5.67 %      1 Cores
      Owns_4-Max_8     mysystem1.prod	    75.00 %	  4.51 %      1 Cores

      From the last two commands, we now have the names of workloads in the
      SRD. Using one of those names, we can focus our monitoring on a single
      workload in the next two examples, getting the default resource view
      and the policy view.

      # gwlm monitor --workload=mysystem1.prod --view=resource

      Wed Dec 13 14:21:30 2006
      Workload: mysystem1.prod

      Shared Resource Domain	Allocation	      Size  Utilization
      ______________________  ____________  ______________  ___________
      mysystem1.srd		   4 Cores	   4 Cores	  4.4 %

      # gwlm monitor --workload=mysystem1.prod --view=policy

      Wed Dec 13 14:27:30 2006
      Workload: mysystem1.prod

      Policy	       Shared Resource Dom	 Target	    Measured	Request
      _______________  ___________________ ____________ ____________ __________
      Owns_4-Max_8     mysystem1.srd	    75.00 %	  4.21 %	1 Cores

      We can also focus on a single policy, getting a list of all the
      workloads being affected by the policy:

      # gwlm monitor --policy=Owns_4-Max_8

      Wed Dec 13 14:31:45 2006
      Policy: Owns_4-Max_8

      Shared Resource Dom  Workload	       Target	  Measured	Request
      ___________________  ________________ _________ ____________ ____________
      mysystem1.srd	   mysystem1.OTHER   75.00 %	2.62 %		1 Cores
      mysystem1.srd	   mysystem1.prod    75.00 %	3.39 %		1 Cores

      This next example shows output for an SRD consisting of nested
      partitions.

      # gwlm monitor --srd=mysystem1.srd --nested

      Thu May 04 10:56:50 2006
      Shared Resource Domain: mysystem1.srd

      Workload			   Type	   Allocation	       Size  Utilization
      __________________________ ______	 ____________  ____________  ___________
      mysystem1.mydomain.com	   npar	   3.00 Cores	 3.00 Cores	   1.3 %
      (mysystem)		   npar		 --    (8.00 Cores)	 (1.5 %)
	mysystema.mydomain.com	   vpar	   3.00 Cores	 3.00 Cores	   1.6 %
	(mysystemb)		   vpar		 --    (3.00 Cores)	 (1.1 %)
	    mysystemb.OTHER	    fss	   3.00 Cores	 3.00 Cores	   1.1 %
	(mysystemc)		   vpar		 --    (2.00 Cores)	 (2.0 %)
	    mysystemc.OTHER	    fss	   2.00 Cores	 2.00 Cores	   2.0 %
      (mysystem2)		   npar		 --    (3.00 Cores)	 (1.5 %)
	    mysystem2.OTHER	    fss	   3.00 Cores	 3.00 Cores	   1.5 %
      __________________________ ______	 ____________  ____________  ___________
      Totals				  14.00 Cores	14.00 Cores	   1.5 %

WARNINGS

    Compatibility with Outside CPU (Core) / System Control
      gWLM expects to have complete control of the CPUs, or cores, available
      on a system. However, when you must make manual adjustments to system
      resources, you can do so as follows:

	   1. Undeploy the SRD containing the systems that you want to
	      adjust

	   2. Make your adjustments

	   3. Re-create and re-deploy the SRD

      Use the above steps whenever you must perform any of the following
      manual adjustments:

      + Adjustments to the number of cores on systems where gWLM is running

      + Adjustments to Temporary Instant Capacity resources, Instant
	Capacity resources, virtual machines, vpars (including changes in
	core binding), or npars

      + Adjustments to entitlements for virtual machines

      + Changes to a virtual machine's number of virtual CPUs while gWLM is
	managing the virtual machine

      + Creation or deletion of a pset using psrset on a system where gWLM
	is managing pset compartments

      + Moving memory from one vpar to another using vparmodify

      + Performing online cell operations using parolrad

      + Enabling/disabling Hyper-Threading

AUTHOR

      gwlm was developed by HP.

FILES

      gwlmcmsd	      gWLM daemon that runs on the gWLM CMS

      /var/opt/gwlm/gwlmcommand.log.0
		      Log* of gwlm command

      * The name of the current log always ends in .log.0. Once this file
      grows to a certain size, it is moved to a filename ending in .log.1
      and a new .log.0 file is started. If a .log.1 file already exists, it
      is renamed .log.2. If a .log.2 file already exists, it is overwritten.
      (By default, the log file size is limited to 20 Mbytes and the number
      of log files is limited to 3. You can change these defaults by adding
      the following properties:

	   com.hp.gwlm.util.Log.logFileSize = 20
	   com.hp.gwlm.util.Log.logNFiles = 3

      to /etc/opt/gwlm/conf/gwlmcms.properties and changing the values.)

SEE ALSO

      gwlm(5), gwlmxml(4), vseinitconfig(1M), gwlmplace(1M)

gwlmcmsd(1M) / gwlmagent(1M)

Date: 2007/03/21 
Revision: 1.26 

NAME

      gwlmcmsd, gwlmagent - Global Workload Manager (gWLM) daemons

SYNOPSIS

      gwlmcmsd
      gwlmcmsd --disable_start_on_boot
      gwlmcmsd --enable_start_on_boot
      gwlmcmsd --stop
      gwlmcmsd --help

      gwlmagent
      gwlmagent --disable_start_on_boot
      gwlmagent --enable_start_on_boot
      gwlmagent --stop
      gwlmagent --restart
      gwlmagent --help

DESCRIPTION

      gWLM has the following daemons:

      gwlmcmsd	  Runs on the HP-UX central management server (CMS) in an HP
		  Systems Insight Manager environment with gWLM installed.
		  This daemon:

		  + Collects and records historical data for viewing through
		    HP Systems Insight Manager

		  + Delivers events from the managed nodes for viewing
		    through HP Systems Insight Manager

		  gwlmcmsd is started when you run the
		  /opt/vse/bin/vseinitconfig command. You can also start it
		  manually:

		  /opt/gwlm/bin/gwlmcmsd

		  Compatibility with agents / OpenVMS
		  The gWLM A.03.00.00.x gwlmcmsd runs on HP-UX 11i v1
		  (B.11.11), HP-UX 11i v2 (B.11.23), and HP-UX 11i v3
		  (B.11.31). It works with the following versions of the
		  agents:

		  + gWLM A.01.01.02: HP-UX 11i v1, HP-UX 11i v2

		  + gWLM A.01.01.03 / A.01.01.04: OpenVMS Version 7.3-2 and
		    later for Alpha servers, OpenVMS 8.2-1 and later for HP
		    Integrity servers

		  + gWLM A.02.00.00.x: HP-UX 11i v1, HP-UX 11i v2


		  + gWLM A.02.50.00.x: HP-UX 11i v1, HP-UX 11i v2, OpenVMS
		    Version 7.3-2 and later for Alpha servers, OpenVMS 8.2-1
		    and later for HP Integrity servers

		  + gWLM A.03.00.00.x: HP-UX 11i v1, HP-UX 11i v2,  HP-UX
		    11i v3, OpenVMS Version 7.3-2 and later for Alpha
		    servers, OpenVMS 8.2-1 and later for HP Integrity
		    servers

		  NOTE: While gWLM does support earlier agent versions, you
		  are encouraged to upgrade to the latest version.

		  Using a gWLM A.03.00.00.x CMS does not allow you to use
		  A.03.00.00.x functionality with older agents: The policy
		  combinations and potential compartment types available
		  originally with the older agents are still enforced. Also,
		  nested partitions are generally available only with
		  A.02.50.00.x and later.

		  Also, all gWLM agents within an SRD must be of the same
		  revision. For example, a gWLM CMS can manage an SRD that
		  uses only A.03.00.00.x agents, only A.02.50.00.x agents,
		  and so forth.

		  Configurable properties
		  For information on properties you can configure for
		  gwlmcmsd, see the file
		  /etc/opt/gwlm/conf/gwlmcms.properties.

      gwlmagent	  Runs on HP-UX systems where you want gWLM to manage the
		  system resources. (HP Systems Insight Manager does not
		  need to be installed on these systems.) The gwlmagent
		  daemon arbitrates CPU requests from policies on the
		  system, deciding the CPU allocations that each workload's
		  compartment receives.

		  By default, you must start gwlmagent manually:

		  /opt/gwlm/bin/gwlmagent

		  To start gwlmagent automatically whenever a system boots,
		  edit the file /etc/rc.config.d/gwlmCtl or use the
		  following command to edit the file for you:

		  gwlmagent --enable_start_on_boot

		  Configurable properties
		  For information on properties you can configure for
		  gwlmagent, see the file
		  /etc/opt/gwlm/conf/gwlmagent.properties.

OPTIONS

      The options for the daemons are described below.

      Note that option arguments are introduced by two dash characters (--),
      not a single dash character (-).

      No options  Starts the daemon.

      --disable_start_on_boot
		  Prevents the daemon from starting whenever the system
		  boots. The daemon is prevented from starting by assigning
		  the value 0 to the variable GWLM_CMS_START (when used with
		  gwlmcmsd) or GWLM_AGENT_START (when used with gwlmagent)
		  in the file /etc/rc.config.d/gwlmCtl The daemon
		  immediately exits after updating the file.

		  NOTE: Setting GWLM_CMS_START to 0 prevents automatic use
		  at boot of HP Integrity Essentials Virtualization Manager
		  and HP Integrity Essentials Capacity Advisor.

      --enable_start_on_boot
		  Sets the daemon to start whenever the system boots. The
		  daemon is set to start by assigning the value 1 to the
		  variable GWLM_CMS_START (when used with gwlmcmsd) or
		  GWLM_AGENT_START (when used with gwlmagent) in the file
		  /etc/rc.config.d/gwlmCtl The daemon immediately exits
		  after updating the file.

      --stop	  Stops the daemon.

      --restart	  Stops and restarts the daemon.

      --help	  Displays a usage message and exits.

AUTHOR

      gwlmcmsd and gwlmagent were developed by HP.

FILES

      /etc/rc.config.d/gwlmCtl	      (HP-UX systems) gWLM start-up control
				      file

      /etc/opt/gwlm/conf/gwlmcms.properties
				      Properties file for the gWLM CMS


      /etc/opt/gwlm/conf/gwlmagent.properties
				      Properties file for the gWLM agent

      /var/opt/gwlm/gwlmcmsd.pid      File indicating the PID of the running
				      gwlmcmsd

      /var/opt/gwlm/gwlmagent.pid     File indicating the PID of the running
				      gwlmagent

      /var/opt/gwlm/gwlmcmsd.log.0    Log* of gwlmcmsd

      /var/opt/gwlm/gwlmagent.log.0   Log* of gwlmagent

      /var/opt/gwlm/gwlm.log.0	      Log* of gWLM interface in HP Systems
				      Insight Manager

      /var/opt/gwlm/gwlmcommand.log.0 Log* of gwlm command

      * The name of the current log always ends in .log.0. Once this file
      grows to a certain size, it is moved to a filename ending in .log.1
      and a new .log.0 file is started. If a .log.1 file already exists, it
      is renamed .log.2. If a .log.2 file already exists, it is overwritten.
      (By default, the log file size is limited to 20 Mbytes and the number
      of log files is limited to 3. You can change these defaults using the
      following properties:

	   com.hp.gwlm.util.Log.logFileSize = 20
	   com.hp.gwlm.util.Log.logNFiles = 3

      For the gwlmagent log, change the values of these properties in
      /etc/opt/gwlm/conf/gwlmagent.properties. For all the other log files,
      add these properties to /etc/opt/gwlm/conf/gwlmcms.properties and
      change the values.)

SEE ALSO

      gwlm(5)

gwlmdeletekey(1M) / gwlmexportykey(1M) / gwlmimportkey(1M) / gwlmlistkeys(1M) / gwlmsslconfig(1M)

Date: 2007/03/21 
Revision: 1.20 

NAME

      gwlmsslconfig, gwlmexportkey, gwlmimportkey, gwlmlistkeys,
      gwlmdeletekey - secure network communications for Global Workload
      Manager (gWLM).

SYNOPSIS

      gwlmsslconfig

      gwlmexportkey [ -f file ]

      gwlmimportkey -f file -a alias

      gwlmlistkeys

      gwlmdeletekey -a alias

AVAILABILITY

      These commands are available on both gWLM Central Management Servers
      (systems where you run gwlmcmsd) and managed nodes (systems where you
      run gwlmagent).

DESCRIPTION

      The gwlmsslconfig, gwlmexportkey, and gwlmimportkey commands help you
      enable secure gWLM communications between the central management
      server (CMS) and the managed nodes. Both the gWLM interface in HP
      Systems Insight Manager and the gWLM command-line interface use the
      secure communications, once enabled.

      The gwlmlistkeys and gwlmdeletekey commands are useful when you have
      alias conflicts.

      NOTE: By default, gWLM's communications are not secure, meaning:

	   + The communications between the CMS and the managed nodes are
	     not encrypted

	   + The source and destination of gWLM's communications are not
	     authenticated

COMMANDS

      The options, if any, for the commands are described below.

    gwlmsslconfig
      Run gwlmsslconfig on every system on which you are going to run gWLM.
      (However, you do not need to run the command on your CMS, assuming you
      have already run vseinitconfig (with no options) or
      vseinitconfig --initconfig there.)

      This command sets values in the gWLM agent properties file so that the
      keystore provided by HP Systems Insight Manager is used, if available.
      Otherwise, the command creates a gWLM-specific keystore and sets the
      gWLM properties file accordingly.

    gwlmexportkey [ -f file ]
      Exports a key from the local system. You later use gwlmimportkey to
      import this key to the keystores on other systems.

      Systems can initiate secure communications with any system from which
      they have a key imported in their keystores.

				  Option
      -f file
	 Places the exported key in file, instead of in the default
	 hostname.cer.

    gwlmimportkey -f file -a alias
      Imports a key to the local keystore, allowing the local system to
      initiate secure communications with the system from which the key
      originated.

				  Options
      -f file	  Imports a key from the specified file.  You can only
		  import one key at a time.

      -a alias	  Associates the name alias with the key. Given a particular
		  key, gWLM attempts to communicate with the associated
		  system referring to it as alias.

		  The output of the command hostname, run on the system
		  where the key was generated, is often a good value to use
		  for alias.  However, you can use values other than the
		  hostname, especially if gwlmimportkey fails because the
		  alias already exists. You can also use gwlmlistkeys and
		  gwlmdeletekey to manage alias conflicts.

    gwlmlistkeys
      Lists all the keys in the local keystore.

    gwlmdeletekey -a alias
      Deletes the key associated with alias in the local keystore.

				  Options
      -a alias	  Specifies the alias associated with the key to be deleted.

HOW TO SECURE COMMUNICATIONS

      You can secure gWLM communications through the gWLM interface in HP
      Systems Insight Manager, as described in the online help topic
      "Securing gWLM Communications". Alternatively, you can secure
      communications on the command line, as described below.

      To secure gWLM communications on the command line:

      1. Log in as root

      2. Run gwlmsslconfig on every system on which you are going to run
	 gWLM:

	 # /opt/gwlm/bin/gwlmsslconfig

	 However, you do not have to run this command on CMS systems where
	 you have already run the command vseinitconfig (with no options) or
	 vseinitconfig --initconfig.

      3. Edit the gWLM agent properties file to ensure the property
	 com.hp.gwlm.security.secureRMI is set to true:


	    com.hp.gwlm.security.secureRMI=true

	 in the file /etc/opt/gwlm/conf/gwlmagent.properties on every
	 system--including the CMS--on which you are going to run gWLM.
	 (Even with gwlmagent not running on the CMS, gWLM makes use of the
	 gwlmagent.properties file for security purposes.)

	 The com.hp.gwlm.security.secureRMI property is added to the
	 properties file (with a value of 'false') when you run the
	 gwlmsslconfig command.

      4. Export the keys on the CMS and on each system in the shared
	 resource domain (SRD)

	 For example, if you have three systems, such as a CMS called
	 system1 and an SRD with two managed nodes called system2 and
	 system3, run gwlmexportkey on each system:


	    system1# gwlmexportkey -f system1.cer


	    system2# gwlmexportkey -f system2.cer


	    system3# gwlmexportkey -f system3.cer

      5. Distribute the exported keys

	 The CMS must have the key from every system in the SRD. Also, each
	 system in the SRD must have the key from the CMS as well as the key
	 from every other system in the SRD.

	 Distribute the keys using the secure cp command, scp:



	    system1# scp system1.cer system2:/tmp/keys


	    system1# scp system1.cer system3:/tmp/keys


	    system2# scp system2.cer system1:/tmp/keys


	    system2# scp system2.cer system3:/tmp/keys


	    system3# scp system3.cer system1:/tmp/keys


	    system3# scp system3.cer system2:/tmp/keys

	 NOTE: If scp is not available, you can exchange the keys through
	 other secure methods, such as by using physical media.

      6. Import all the keys on the CMS and on each system in the SRD from
	 every other system:


	    system1# gwlmimportkey -f /tmp/keys/system2.cer -a system2


	    system1# gwlmimportkey -f /tmp/keys/system3.cer -a system3


	    system2# gwlmimportkey -f /tmp/keys/system1.cer -a system1


	    system2# gwlmimportkey -f /tmp/keys/system3.cer -a system3


	    system3# gwlmimportkey -f /tmp/keys/system1.cer -a system1


	    system3# gwlmimportkey -f /tmp/keys/system2.cer \
	    -a system2.CERTIFICATE

	 On system3, system2.cer was imported with the alias
	 system2.CERTIFICATE. This alias was chosen to show that an alias
	 does not have to match the hostname of the system where it was
	 generated.

      7. Restart gWLM


	 Restart gWLM--on each system--so that it uses secure
	 communications.

	 On the CMS:

	 NOTE: Stopping gwlmcmsd disables HP Integrity Essentials
	 Virtualization Manager and HP Integrity Essentials Capacity
	 Advisor.


	    # /opt/gwlm/bin/gwlmcmsd --stop


	    # /opt/gwlm/bin/gwlmcmsd

	 On each managed node:


	    # /opt/gwlm/bin/gwlmagent --restart

DISABLING SECURE COMMUNICATIONS

      To disable gWLM's use of secure communications:

      1. Edit the gWLM agent properties file

	 Ensure the property com.hp.gwlm.security.secureRMI is set to false:


	    com.hp.gwlm.security.secureRMI=false

	 in the file /etc/opt/gwlm/conf/gwlmagent.properties on every
	 system--including the CMS. (Even with gwlmagent not running on the
	 CMS, gWLM makes use of the gwlmagent.properties file for security
	 purposes.)

      2. Restart HP Systems Insight Manager and gWLM

	 Restart the software--on each system--so that it stops using secure
	 communications.

	 On the CMS:


	    # /opt/mx/bin/mxstop


	    # /opt/mx/bin/mxstart

	 NOTE: Stopping gwlmcmsd disables HP Integrity Essentials
	 Virtualization Manager and HP Integrity Essentials Capacity
	 Advisor.

	    # /opt/gwlm/bin/gwlmcmsd --stop


	    # /opt/gwlm/bin/gwlmcmsd

	 On each managed node:


	    # /opt/gwlm/bin/gwlmagent --restart

RETURN VALUES

      The return values for these commands are as follows:

	   0	Success

	   1	Failure

AUTHOR

      gwlmsslconfig, gwlmexportkey, gwlmimportkey, gwlmlistkeys, and
      gwlmdeletekey were developed by HP.

FILES

      /etc/opt/gwlm/conf/gwlmagent.properties
		      Properties file for the gWLM agent

SEE ALSO

      gwlm(5)

gwlminitconfig(1M)

Date: 2006/09/12 
Revision: 1.20 

NAME

      gwlminitconfig - perform the initial configuration of a system for use
      as a central management server (CMS) for Global Workload Manager
      (gWLM)

COMMAND REPLACED

      The gwlminitconfig functionality is now available in the vseinitconfig
      command. Please use vseinitconfig in place of gwlminitconfig.

      For command information, see vseinitconfig(1M).

gwlmplace(1M)

Date: 2007/03/21 
Revision: 1.24 

NAME

      gwlmplace - place a process in a gWLM workload

SYNOPSIS

      gwlmplace [--help] [--recurse] --workload=workload --pid=PID [...]

AVAILABILITY

      This command is available only on gWLM managed nodes (systems where
      you run gwlmagent).

DESCRIPTION

      Use gwlmplace to place a process in a gWLM workload that is based on a
      pset compartment or on an fss group compartment.

      Use gwlmplace only when the process cannot be placed by a gWLM
      application record or user record. (You create these records in gWLM
      when creating or editing workloads.)

      Once gwlmplace has placed a process, application records, user
      records, and process maps no longer affect that process.

      For information on how process placement can be lost, see the
      LIMITATIONS section below.

OPTIONS

      gwlmplace recognizes the following options:

      --help
	   Print usage and exit.

      --recurse
	   Place the process with the specified PID and any of its
	   descendant processes. The default is to not recurse, just placing
	   the single specified process.

      --workload=workload
	   Name the workload in which to place the process.

      --pid=PID
	   Specify the PID for the process to place. You must specify a PID.
	   Specify multiple PIDs by preceding each PID with a --pid.  All
	   the processes are moved to the same target workload that you
	   specified with the --workload option.

EXAMPLES

				 Example 1
      Place process 1234 on myhost in workload myhost01. This overrides any
      application records or user records in the deployed SRD configuration.

      Note: This command must be run on the machine 'myhost'. Running from
      another managed node produces an error.

	   gwlmplace --workload=myhost01 --pid=1234

				 Example 2
      Place processes 1234, 3456, and 4567 on myhost in workload myhost01.

	   gwlmplace --workload=myhost01 --pid=1234 --pid=3456 --pid=4567

				 Example 3
      Place the current shell's process in myhost03. This is useful in a
      script to move the script itself to a workload. Because workload and
      compartment membership is inherited by child processes, placing the
      parent script process like this causes all subsequent child processes
      to be run in that workload's compartment as well.

	   gwlmplace --workload=myhost03 --pid=$$

				 Example 4
      Place process 234 and its descendant processes in workload myhost01.
      (The descendants are all processes whose parent process ID in the
      process hierarchy leads back to process 234. These processes could be
      children, grandchildren, or later generations.)

	   gwlmplace --recurse --workload=myhost01 --pid=234

ERRORS

				 Exit codes
      If gwlmplace exits with a:

	 Zero exit code
	   It was successful in its placements.

	 Nonzero exit code
	   It failed because the processes to be placed or the target
	   workload did not exist.  gwlmplace reports an error in addition
	   to exiting with a nonzero code.

		Failed placements when placing several processes
      When requesting the placement of several processes (using multiple
      --pid items or --recurse), the failure of just one placement results
      in:

	 + A nonzero exit code

	 + An error indicating the PIDs of the processes that were not
	   successfully placed

      However, any placements that were possible were completed.

	       Attempted placements with workloads based on
		     virtual machines, vpars, or npars
      If the workload compartment type is a virtual machine (hpvm), vpar, or
      npar, gwlmplace cannot move the process to a different virtual
      machine, vpar, or npar. As a result, an error message and code are
      returned indicating that placement does not work on the given
      compartment type.

				  Logging
      Regardless of success, a message is logged in the gWLM agent log file
      for each PID for which a placement is attempted and a move to a new
      workload is required:

	 Successful placements
	    Generate messages at the INFO level

	 Unsuccessful placements or missing workloads
	    Generate messages at the WARNING level

	 Attempted placements where the PID is already in the correct workload
	    Produce no log message because no move is required

LIMITATIONS

			       Must run as root
      You must be root to run gwlmplace.

			      Must run locally
      You must run gwlmplace on the local managed node where the target
      processes are running.

			  Loss of process placement
      All process placement with gwlmplace on a managed node is lost if:

	 + The managed node is rebooted

	 + The local gwlmagent daemon is restarted

	 + You undeploy the current SRD

      In these cases, processes are placed according to any application
      records or user records that apply. If no records exist, nonroot
      processes are placed in the default pset or default fss group; root
      processes are left where they are. To restore the process placements
      that existed before the reboot or restart, use gwlmplace again, using
      the same arguments as before.

DEPENDENCIES

      Requires the gWLM agent to be installed and running on the local
      managed node.

FILES

      /var/opt/glwm/gwlmagent.log.0   Log* of gwlmagent

      * The name of the current log always ends in .log.0. Once this file
      grows to a certain size, it is moved to a filename ending in .log.1
      and a new .log.0 file is started. If a .log.1 file already exists, it
      is renamed .log.2. If a .log.2 file already exists, it is
      overwritten--or moved to yet another file (up to a configurable number
      of files you can set in /etc/opt/gwlm/conf/gwlmcms.properties).

SEE ALSO

      gwlm(1M), gwlm(5), gwlmagent(1M)

gwlmreport(1M)

Date: 2007/03/21 
Revision: 1.57 

NAME

      gwlmreport - produce advanced textual summary reports for workload
      resource utilization

SYNOPSIS

      gwlmreport command [options]

AVAILABILITY

      This command is available only on gWLM Central Management Servers
      (systems where you run gwlmcmsd).

DESCRIPTION

      Use gwlmreport to extract data for a given set of workloads over a
      given date range, and either create summary reports or write that data
      to comma-separated value (CSV) output.  gwlmreport can get data from
      one of two sources: By default, it pulls data from the gWLM database.
      It can also use CSV input, which you point it to using the --inputpath
      option.

      NOTE: To ensure data from the current day is included in any reports
      you create, run the following command on your CMS:

	   # gwlm history --flush

      Valid values for command are:

	   extract	  Extract data from the gWLM database into
			  CSV format

	   resourceaudit  Generate a resource audit report
			  (Provides an overview of resource usage)

	   topborrowers	  Generate a top borrowers report
			  (Helps identify workloads that may require
			  additional resources)

	   abnormalutil	  Generate an abnormal utilization report
			  (Shows CPU utilization over various time periods
			  so you have a "normal" utilization pattern against
			  which to compare abnormal utilization)

	   ovpafeed	  Extract data to use with OpenView Performance
			  Agent (OVPA) via data source integration (DSI)

	   config	  Generate a report showing configuration history

COMMANDS

      This section describes the syntax of each command. Note that option
      arguments are introduced by two dash characters (--), not a single
      dash character (-).

      The options are described in the next section.

	   extract [--workload=workload] [...]
		   [--help]
		   [--policy=policy]
		   [--startdate=YYYY/mm/dd]
		   [--enddate=YYYY/mm/dd]
		   [--duration=n{ days | weeks | months }]
		   [--inputpath=path]
		   [--outputpath=path]
		   [--dataversion=version]
		   [--columnhelp]
		   [--datestamps]
		   [--columns=colname1[,colname2,...]]

	   resourceaudit [--workload=workload] [...]
			 [--help]
			 [--policy=policy]
			 [--startdate=YYYY/mm/dd]
			 [--enddate=YYYY/mm/dd]
			 [--duration=n{ days | weeks | months }]
			 [--inputpath=path]
			 [--outputpath=path]

	   topborrowers [--workload=workload] [...]
			[--help]
			[--policy=policy]
			[--startdate=YYYY/mm/dd]
			[--enddate=YYYY/mm/dd]
			[--duration=n{ days | weeks | months }]
			[--inputpath=path]
			[--outputpath=path]

	   abnormalutil [--workload=workload] [...]
			[--help]
			[--policy=policy]
			[--startdate=YYYY/mm/dd]
			[--enddate=YYYY/mm/dd]
			[--duration=n{ days | weeks | months }]
			[--inputpath=path]
			[--outputpath=path]
			[--targetdate=YYYY/mm/dd[:hh]]

	   ovpafeed [--workload=workload] [...]
		    [--help]
		    [--policy=policy]
		    [--startdate=YYYY/mm/dd]
		    [--enddate=YYYY/mm/dd]
		    [--duration=n{ days | weeks | months }]
		    [--inputpath=path]
		    [--outputpath=path]
		    [--dataversion=version]
		    [--setup]

	   config [--help]
		  [--dates]
		  [--targetdate=YYYY/mm/dd[:hh:mm:ss[.SSS]]]
		  [[--diff] --startdate=YYYY/mm/dd[:hh:mm:ss[.SSS]]
			    --enddate=YYYY/mm/dd[:hh:mm:ss[.SSS]]]
		  [--outputpath=path]

OPTIONS

      The gwlmreport commands recognize the following options:

      --workload=workload
	   Generate a report for workload.  To create reports for:

	   + Multiple (but not all) workloads: Repeat --workload=workload
	     with different values for workload

	   + All workloads: Do not specify --workload (The absence of the
	     option indicates gwlmreport should get data for all workloads.
	     You cannot omit this option and use --inputpath.)

      --help
	   Print usage and exit.

      --policy=policy
	   Filter data to show only those periods when policy was in effect.

	   If you do not specify --policy, there is no filtering.

      --startdate=date
	   Base the report on data starting from date.	Specify date in
	   YYYY/mm/dd format, such as 2004/06/09 for June 9th, 2004.  (With
	   the config command, you can also specify the ":hh:mm:ss[.SSS]"
	   component. SSS represents milliseconds.)

	   If you do not specify --startdate, gWLM sets date to one calendar
	   month before today. (However, if you specify --enddate, you must
	   explicitly set --startdate.)

	   When you specify --startdate but not --enddate, you get data for
	   the one month period following date.

	   When running gwlmreport config --diff, you must specify both
	   --startdate and --enddate.

	   When running gwlmreport ovpafeed multiple times, be sure not to
	   use overlapping --startdate and --enddate arguments.

      --enddate=date
	   Base the report on data ending date.	 Specify date in YYYY/mm/dd
	   format, such as 2004/06/09 for June 9th, 2004.  (With the config
	   command, you can also specify the ":hh:mm:ss[.SSS]" component.
	   SSS represents milliseconds.)

	   You cannot specify --enddate with --duration.

	   The default end date is the current date. (However, if you
	   specify --startdate, the default end date is one month after the
	   date given with --startdate.)

	   When running gwlmreport config --diff, you must specify both
	   --startdate and --enddate.

	   When running gwlmreport ovpafeed multiple times, be sure not to
	   use overlapping --startdate and --enddate arguments.

      --duration=n{ days | weeks | months }
	   Run the report with data from

	   date
	   to
	   date + n{ days | weeks | months }

	   where date is the value you specified in --startdate=date.

	   If you specify --duration, you must also specify --startdate.
	   You cannot specify --duration with --enddate.

	   The input format is n{ days | weeks | months }.  Examples of
	   valid choices are: 5weeks, 2months.

	   If you do not specify --duration, gWLM uses a duration of one
	   month.

      --inputpath=path
	   Specify the path for the CSV data being used to generate the
	   report.

	   You must specify --workload when you specify --inputpath.

	   There are three valid choices for path:

	   + A single dash "-" to read all CSV data from stdin

	   + An absolute path to a single file containing CSV data for all
	     workloads specified with the --workload option

	   + A directory containing a group of CSV files, one per workload

	     For example, if the workloads specified are wl1 and wl2 and the
	     input path is /tmp, gwlmreport will attempt to read the CSV
	     info for workload wl1 from file /tmp/wl1.csv and the CSV info
	     for workload wl2 from file /tmp/wl2.csv.

      --outputpath=path
	   Specify the path for the report output.  The default path is to
	   send report output to stdout.

	   There are three valid choices for path:

	   + A single dash "-" to write all report output to stdout

	   + An absolute path to a single file to which all report data is
	     to be written

	     If a single file is specified and that file already exists, the
	     file is overwritten.

	   + A directory

	     If a directory is specified, each report is placed in a file
	     named after its workload (unless you are using the topborrowers
	     command). The filenames change based on the report type. For
	     example, the following commands result in the indicated files:

	     gwlmreport resourceaudit -w wkldA -w wkldB --outputpath=/tmp/
		  Files: /tmp/wkldA.resaud, /tmp/wkldB.resaud

	     gwlmreport extract -w wkldA -w wkldB --outputpath=/tmp/
		  Files: /tmp/wkldA.csv, /tmp/wkldB.csv

	     gwlmreport abnormalutil -w wkldA -w wkldB --outputpath=/tmp/
		  Files: /tmp/wkldA.abutil, /tmp/wkldB.abutil

	     gwlmreport topborrowers -w wkldA -w wkldB --outputpath=/tmp/
		  File: /tmp/allworkloads.topbor

	     gwlmreport config --outputpath=/tmp/
		  File: /tmp/config.YYYY-mm-dd:hh:mm:ss

	   NOTE: Using --outputpath with ovpafeed directs data to the given
	   path instead of to the logfileset.

      --dataversion=version
	   Specify the version of data to use for the intermediate file.
	   Valid choices are: 1.0, 2.0, and 3.0. (This version is
	   independent of the version of the gWLM product.)

	   If you do not specify --dataversion, gWLM sets version to 3.0.

	   You can convert from one data version to another by reading a
	   database or CVS source that is one version, say 1.0, and
	   specifying the --dataversion option with the other version (for
	   example, 3.0). New fields (when going from 1.0 to 3.0) are filled
	   as best as possible, while missing fields (going from 3.0 to 1.0)
	   are dropped.

	   When using ovpafeed, you can change the version as desired
	   because each version's data goes into a separate logfileset,
	   maintaining different sets of OpenView Performance Agent metrics
	   as provided by the given version.

      --columnhelp
	   List the names for the all the columns of data in the extract
	   output. Use the names shown when you use the --columns option to
	   limit the number of columns displayed.

	   The list of column names changes based on the --dataversion
	   value.

      --datestamps
	   Convert timestamps to human-readable datestamps.

	   NOTE: If you use --datestamps and save the output to a file
	   (using --outputpath), that file cannot be used later as input
	   with the --inputpath option.

      --columns=colname1[,colname2,...]]
	   Extract data only for the specified columns. (Separate column
	   names using only commas; do not use spaces.) To display a list of
	   column names, use the --columnhelp option. (The columns available
	   change based on the --dataversion value.)

	   NOTE: If you use --columns and save the output to a file (using
	   --outputpath), that file cannot be used later as input with the
	   --inputpath option.

      --targetdate=YYYY/mm/dd[:hh:mm:ss[.SSS]]
	   Focus the report on the specified date.

	   The ":mm:ss[.SSS]" component is allowed only with the config
	   command. (SSS represents milliseconds.)

      --setup
	   Sets up the DSI logfileset needed for feeding data to OpenView
	   Performance Agent. Data is placed in logfilesets in
	   /var/opt/dsi/version/gwlm*.

	   NOTE: The ovpafeed command is available only on HP-UX systems
	   with the HPUX11i-OE-Ent.MeasureWare.PERFDSI fileset or its
	   equivalent installed.  (One equivalent is the
	   B3701AA.MeasureWare.PERFDSI fileset, which is installed when you
	   install HP GlancePlus/UX Pak, version C.03.85.00 or later.) You
	   must be root to use the command.

	   NOTE: Running gwlmreport ovpafeed --setup modifies your
	   /var/opt/perf/perflbd.rc file. Restart perflbd to see new feed in
	   the OpenView tools. For more information, search for "mwa restart
	   server" in the mwa(1) manpage.

	   You must run gwlmreport ovpafeed --setup before using any other
	   gwlmreport ovpafeed commands.

      --dates
	   Display the dates when there were configurations saved.

      --diff --startdate=date --enddate=date
	   Display any changes in configurations saved between
	   --startdate=date and --enddate=date.

EXAMPLES

    Example 1
      Produce a resource audit report for myworkloadA for the calendar month
      prior to the current date (time at which gwlmreport is run). The
      workload data is read from the gWLM database.

	      gwlmreport resourceaudit \
		  --workload=myworkloadA

    Example 2
      Produce a resource audit report for workloads myworkloadA,
      myworkloadB, and myworkloadC for the three calendar months starting
      Sep 01, 2004. The workload data is read from the gWLM database.

	      gwlmreport resourceaudit \
		  --workload=myworkloadA \
		  --workload=myworkloadB \
		  --workload=myworkloadC \
		  --startdate=2004/09/01 \
		  --duration=3months

    Example 3
      Produce a topborrowers report for workloads myworkloadA, myworkloadB
      and myworkloadC for the calendar month starting Sep 01, 2004. The
      workload data is read from the gWLM database.

	      gwlmreport topborrowers \
		  --workload=myworkloadA \
		  --workload=myworkloadB \
		  --workload=myworkloadC \
		  --startdate=2004/09/01 \
		  --duration=1month
    Example 4
      Walk through the CSV file /tmp/previously_extracted_data.csv and
      produce a resource audit report for workload myworkloadA under the
      policy myOwnBorrowPol for the three calendar months starting Sep 01,
      2004. Print it to stdout.

	      gwlmreport resourceaudit \
		  --workload=myworkloadA \
		  --policy=myOwnBorrowPol \
		  --startdate=2004/09/01 \
		  --duration=3months \
		  --inputpath=/tmp/previously_extracted_data.csv

    Example 5
      Extract the data for myworkloadA, for the three calendar months
      starting Sep 01, 2004. Print it to stdout. The workload data is read
      from the gWLM database.

	      gwlmreport extract \
		  --workload=myworkloadA \
		  --startdate=2004/09/01 \
		  --duration=3months

    Example 6
      Extract the data for myworkloadA (formatting it as CSV data), for the
      three calendar months starting Sep 01, 2004. The CSV data is stored in
      a file called /tmp/mydata.csv. The workload data is read from the gWLM
      database.

	      gwlmreport extract \
		  --workload=myworkloadA \
		  --startdate=2004/09/01 \
		  --duration=3months \
		  --outputpath=/tmp/mydata.csv

    Example 7
      Extract the data for myworkloadA and myworkloadB (formatting it as CSV
      data), for the three calendar months starting Sep 01, 2004. Because
      the --outputpath option points to a directory, the CSV data for
      myworkloadA is stored in a file called /tmp/myworkloadA.csv, and the
      CSV data for myworkloadB is stored in /tmp/myworkloadB.csv. The
      workload data is read from the gWLM database.

	      gwlmreport extract \
		  --workload=myworkloadA \
		  --workload=myworkloadB \
		  --startdate=2004/09/01 \
		  --duration=3months \
		  --outputpath=/tmp/


    Example 8
      Read the data for myworkloadA and myworkloadB from
      /tmp/myworkloadA.csv and /tmp/myworkloadB.csv for the three calendar
      months starting Sep 01, 2004, and use it to produce an audit report
      for each workload.

	      gwlmreport resourceaudit \
		  --workload=myworkloadA \
		  --workload=myworkloadB \
		  --startdate=2004/09/01 \
		  --duration=3months \
		  --inputpath=/tmp/

    Example 9
      Compare recent CPU utilization of a poorly performing workload against
      its utilization when it was performing as desired. Say the poor
      performance is noticed on 2005/10/21 around 10am. To compare that
      utilization to the utilization in periods related to that time, run a
      report as follows:

	   gwlmreport abnormalutil \
	       --workload=myworkloadA \
	       --startdate=2005/10/01 \
	       --enddate=2005/10/30 \
	       --targetdate=2005/10/21:10

      The resulting report would show all the historical samples for
      workload utilization for several time periods:

	   + The whole period (10/01 through 10/30)

	   + All the Friday 10-10:59 am time periods (10/21 is a Friday)

	   + The week (7 calendar days) prior to 10/21

	   + The hour prior to 10:21:10

	   + The sample immediately before 10:21:10

      Comparing the data during the target period with these other periods,
      you can see if the allocation and utilization are normal for a Friday
      10am slot, and for a given week or month.	 If the allocation seems
      normal but the utilization is high, perhaps there is extra demand or
      an application problem. If the allocation seems too low compared to
      the other time periods of interest, perhaps the workload is not
      getting enough resources and a policy adjustment is needed.

      You might then rerun the report with the same start and end dates, but
      different targetdates, say 2005/10/21:11 and 2005/10/21:12, to compare
      the original 10am report with an 11am and a noon-based report. These
      variations quickly give a feel for the behavior of the application.

    Example 10
      Show the configuration changes made in September of 2006:

	   gwlmreport config --diff --startdate=2006/09/01 --enddate=2006/09/30

    Example 11
      Extract data for viewing with OpenView by running the following
      commands:

      1. Set up the DSI logfileset:


	      gwlmreport ovpafeed --setup --dataversion=3.0

	 NOTE: This command fails if the DSI-related OV tools are not
	 present or you are not running on HP-UX.

	 This step adds a line to the /var/opt/perf/perflbd.rc file.

      2. Restart the mwa servers

	 You must restart the mwa servers so that perflbd and other OV tools
	 can see the new data stream. The restart command is:


	      mwa restart server

      3. Extract the data:


	      gwlmreport ovpafeed \
		  --workload=myworkloadA \
		  --startdate=2005/10/01 \
		  --enddate=2005/10/30 \
		  --dataversion=3.0

	 This step shows the data being used from the gWLM database. You can
	 use --inputpath to use CSV files as input instead.

	 Data is placed in a logfileset in /var/opt/dsi/version/gwlm* on the
	 CMS by default. These files grow with each run of gwlmreport
	 ovpafeed.  Starting with gWLM A.02.00.00.x, the logfileset is set
	 up to hold enough historical samples to accommodate 90 days of data
	 for 20 workloads with 5-minute historical samples before the
	 logfileset 'rolls' and starts overwriting older data. This rolling
	 limits the maximum disk space that will be consumed by
	 /var/opt/gwlm/dsi.

	 You can see the raw data that is being reported to OVPA by
	 specifying a --outputpath to stdout or a file and then viewing the
	 contents. However, when you use --outputpath, data is sent to the
	 file or stdout instead of being sent via DSI to OVPA.

      4. Access the data using OpenView tools:

	 Available tools include:
	 + /opt/perf/bin/extract
	 + OpenView Performance Manager (OVPM) and other OpenView reporting
	 tools

	 For example, to see the data just added via the command line, run
	 the command:

		/opt/perf/bin/extract -xp -C workloads DETAIL \
		    -l /var/opt/gwlm/dsi/version/gwlm \
		    -b 10/01/05 -e 10/30/05

	 Alternatively, you can view the data graphically using OVPM on the
	 CMS. When creating a new report in OVPM, the Metric Selection
	 screen will have an entry named GWLM_3_0:WORKLOADS. Select that
	 entry to see the possible gWLM metrics (including compCpuAlloc,
	 compCpuUtil, and polCpuRequest). Select the metrics of interest.
	 Add a filter for wlName == myworkloadA. Name and save the new
	 report. Then display it for the time period 2005/10/01 to
	 2005/10/30.

      5. Repeat step 3 and step 4 for other workloads and/or time periods of
	 interest.

      To automate use of gwlmreport ovpafeed, you can feed gWLM workload
      data to OVPA regularly. For example, you could use a snippet similar
      to the one below executed by cron to feed data to OVPA daily:

      YESTERDAY=`TZ=GMT+24 date +%Y/%m/%d`
      /opt/gwlm/bin/gwlmreport ovpafeed \
	      --startdate $YESTERDAY \
	      --enddate $YESTERDAY

      Using yesterday for both the start and end dates gives all data from
      yesterday.

    Example 12
      Set up an automatic report using a cron entry to run a resource audit
      report on the first of each month for workload myworkloadB's resource
      use during the previous month:

	   0  00  * 1 *	 /opt/gwlm/bin/gwlmreport resourceaudit \
	   --workload=myworkloadB | /usr/bin/mail the_admin@mycompany.com 2>&1

REPORT OUTPUT DESCRIPTIONS

      gwlmreport produces the following types of reports, depending on the
      command you specify:

	   resourceaudit  resource audit report

	   topborrowers	  top borrowers report

	   extract	  CSV report

	   abnormalutil	  abnormal utilization report

	   ovpafeed	  Data for use with OpenView Performance Agent via
			  data source integration (DSI)

	   config	  configuration history report

      The sections below describe the contents of these reports. (Search for
      "Report:" to find the start of each section.)

    Report: resource audit
      The resource audit report has the following sections:

	   + Configuration

	   + Samples

	   + Utilization

	   + Footnotes

			   Configuration section
		(SRD, Policy, and Compartment information)
      This section presents configuration data that is (usually) constant
      over the report duration. If any of these items change during the
      report duration, a footnote (see section below) is appended to the
      report and the *most recent value* is displayed in the report.

      ReportDateRange
	   Calendar dates covered by report.

      Workload
	   The name of the workload.

      TotalSamples
	   The total number of samples received from the data source (either
	   the gWLM database or the CSV input) that fall within the report
	   date range for the given workload. This is identical to the Total
	   value in the Samples section. Samples during times when the
	   workload was in advisory mode are not counted.  TotalSamples may
	   be less than PossibleSamples if gWLM was not on for the whole
	   period.

	   A footnote is produced if this value differs from PossibleSamples
	   by more than 10%.
      AvgSampleDuration
	   Length of sample in minutes.

      PossibleSamples
	   Calculated maximum number of samples that are possible in
	   ReportDateRange.  Basically ReportDateRange divided by
	   AvgSampleDuration.

      SRDName
	   Name of workload's shared resource domain. If the name changed
	   over the report time, the most recent shared resource domain's
	   info is displayed and a footnote is produced.

      SRDMode
	   Tells whether the workload's SRD was in managed mode or advisory
	   mode.

      PolicyName
	   Name of workload's policy. If this has changed over the report
	   time, the most recent policy's info is displayed.

      PolicyType
	   Fixed, OwnBorrow, Utilization, or Custom.

      PolicySettings

	   For Fixed policies:	      target

	   For OwnBorrow policies:    min/owned/max

	   For Utilization policies:  min/max

	   For Custom policies:	      min/max

      CompartmentName
	   Name of workload's compartment. If the name changed over the
	   report time, the most recent compartment's info is displayed and
	   a footnote is produced.  Some compartments have no name, so this
	   field may be empty.

      CompartmentType
	   hpvm, npar, vpar, fss, or pset.

      CompartmentHost
	   Hostname of the workload's compartment.

			      Samples section
      Total (same as TotalSamples)
	   The total number of samples received from the data source (either
	   the gWLM database or the CSV input) that fall within the report
	   date range for the given workload.
	   For any sample, the workload must be in exactly one of three
	   states: OwnedOnly, Borrowing, or Lending. Total is the sum of the
	   number of samples for the workload in each of the three states.
	   Consequently, Total is equal to the TotalSamples metric described
	   above. (The Total count excludes times when the workload was in
	   advisory mode.)

	   The following metrics are not included in Total:


	   + Able2Lend
	   + Want2Borrow
	   + CompClipped
	   + PolClipped
	   + PriClipped

	   Able2Lend and Want2Borrow can both describe a sample where the
	   workload is in the OwnedOnly state. The remaining metrics
	   indicate forms of clipping, most likely describing a sample where
	   the workload is in the Borrowing state. To avoid double-counting,
	   these metrics are not included in the Total metric.

      OwnedOnly
	   Percentage and count of samples where Owned is within 95% to 105%
	   of Size.

	   Custom policies and Utilization policies treat their Min Size
	   values as their Owned values. Because gWLM always honors Min Size
	   values, these types of policies always honor their Owned values,
	   never going below them (that is, never lending CPU resources).
	   So, workloads with either of these policy types will only own or
	   borrow.

	   Workloads with Fixed policies will have all their samples
	   attributed to OwnedOnly.

      Borrowing
	   Percentage and count of samples borrowing (that is, samples where
	   Size > '105% of Owned')

      Lending
	   Percentage and count of samples where the user lent resources
	   (that is, samples where Size < '95% of Owned').

      Able2Lend
	   Percentage and count of samples where request was less than 95%
	   of Owned. This metric is not included the Total or TotalSamples
	   metrics.

      Want2Borrow
	   Percentage and count of samples where request was more than 105%
	   of Owned. This metric is not included the Total or TotalSamples
	   metrics.

      CompClipped
	   Compartment Clipped - percentage and count of samples where the
	   workload could not borrow or acquire as much as it wanted because
	   it is already allocated the compartment maximum. If this
	   condition persists, there may be different remedies based on
	   compartment type. For workloads based on virtual machines, psets,
	   or fss groups, the remedies are: buy a bigger server, move the
	   workload to a server with more room, or move some other workload
	   off the server.  For workloads based on vpars, the same remedies
	   apply but you can also fix the problem by reducing the number of
	   bound CPUs (cores) on the virtual partitions. For workloads based
	   on npars, the remedies for workloads based on psets or fss groups
	   apply; additional Instant Capacity resources can help as well.

      PolClipped
	   Policy Clipped - occurs when the workload is allocated the
	   maximum CPU resource per its policy, but its utilization is above
	   the target, and thus cannot request any more.  If this condition
	   persists, a potential remedy is to increase the policy maximum.

      PriClipped
	   Priority Clipped - occurs when all the workloads' compartments at
	   higher priority levels or at the same priority level are
	   allocated their requested resources, not leaving enough resources
	   for the compartments remaining at the same or lower priority
	   levels.  The remedy is to raise the priority, or, if using
	   OwnBorrow policies, edit the policy (or associate a new policy)
	   to give associated workloads a larger owned amount of CPU
	   resources.

			    Utilization section
      AvgUtil
	   The average utilization of the workload during the reporting
	   duration.

      MaxUtil
	   The maximum utilization of the workload during the reporting
	   duration. A date is displayed showing when the maximum occurred.

      TradeBalance
	   Compute grade based on how often (and how much) the workload
	   lends or borrows. A running total is kept while samples are read:
	   For each sample that is lending, the total lent amount is
	   subtracted from the running total. For each sample that is
	   borrowing, a total lent amount is added to the running total. The
	   end TradeBalance is the running total divided by the total sample
	   count, so a net negative amount means a net lender, while a net
	   positive amount means a net borrower. The magnitude is the
	   average amount lent or borrowed.

      AvgUtilWhileLending
	   The average utilization during samples when this workload is
	   lending.

      MaxUtilWhileLending
	   The maximum utilization encountered during a sample when this
	   workload is lending. If this is nonzero, a date is displayed
	   showing when this maximum occurred. Too large a value may
	   indicate that this workload is being unfairly penalized.

				 Footnotes
      Along with metrics in the detailed reports, a set of footnotes is
      printed to show warnings or alerts for particular reports. These are
      to alert you that there was some kind of exceptional event during the
      report durations that could affect the data.

      Note that the data samples during the exceptional conditions are still
      included in the reports (as best the tools can manage).

      For each type of condition shown below, one footnote is printed per
      workload per report showing the type, the date it first occurred, and
      the total number of times it occurred.

      Advisory mode
	   This workload's SRD was in advisory mode, not managed mode,
	   during one or more samples. This can mean that the allocations do
	   not track the requests because gWLM is advising only, not making
	   changes. The samples in advisory mode are not used to compute
	   state counts and other metrics.

      Time gap
	   This workload's history does not extend through the entire
	   reporting period, or there are gaps in the sample stream of at
	   least one hour.

      Compartment change
	   There was one or more significant compartment changes during the
	   report period. This could be changes to name, id, type, and so
	   on.

      Policy change
	   There was one or more significant policy changes during the
	   report period. This could be changes to name, id, type, and so
	   on.

      Overlapping samples
	   The timestamps for two or more samples show they overlap in time,
	   or are out of order.	 gwlmreport expects non-overlapping samples
	   in order by time-of-century.
      Sample size changed
	   During the report period, the sample size changed by at least
	   10%. Because all samples are counted equally, this sort of change
	   will skew the results toward the data for the shorter samples.
	   (This size is set in minutes using the property
	   com.hp.gwlm.node.samples in the file
	   /etc/opt/gwlm/conf/gwlmcms.properties.)

    Report: top borrowers
      The top borrowers report is a table view of workloads sorted by
      TradeBalance. All the metrics and footnotes are identical to the
      Resource Audit metrics, so see the section above for the metric
      definitions.

    Report: extract (CSV)
      The extract report extracts raw historical data from the gWLM
      database, formats it as comma-separated values, and prints it to a
      specified file or stdout.

      To help consumers of the data, the first line of an extract report is
      a Schema Version line, which gives the gWLM schema and extract-file
      format versions. As there can be changes in one or both of these in
      any gWLM release, all consumers should check the version numbers and
      confirm they understand the data to follow.

      The second line in the extract report is a comma-separated list of
      column headers. These are the names of columns. The number and order
      of the columns is fixed for a given extract version number. For
      information on the order of the columns, see the section "CSV Column
      Header Lines" below.

      The remaining lines in an extract report are lines of metrics in CSV
      format.

      Consumers of the CSV data should ignore any lines:

	   + Starting with a # sign, as these are comments

	   + Consisting only of whitespace

      While neither of these types of lines is generated in the v3.0 extract
      report, they may be added in future versions.

		     CSV File and Schema Version Lines
      Here is the format of the CSV File and Schema Version line from
      gwlmreport v3.0:

	   schemaVersion=gWLM3.0 extractFormatVersion=3.0

      The schemaVersion specifies the version of the gWLM schema used to
      produce the data. The extractFormatVersion specifies the version of
      the extract tool used to extract the data.  For example, running the
      following command

	      gwlmreport extract --dataversion=1.0

      against a gWLM v3.0 database would result in a CSV file with a
      "schemaVersion=gWLM3.0 extractFormatVersion=1.0" header.	This header
      shows that the data is from a 3.0 source (DB or CSV file) and is in
      1.0 extract form. (Being in 1.0 extract form, the list and order of
      columns would match what a 1.0-based extract would have returned.)

      At least one version line must be read before column headers or metric
      data lines are read so the tools know what names and how many metrics
      to expect. If a column header line or metric data line is encountered
      before a valid version line, gwlmreport exits with an error to stderr.

      If you have concatenated several CSV files, you may have duplicate
      version lines. Only the first version line is used (later version
      lines are ignored).

			  CSV Column Header Lines
      The format of the CSV Column header line from gwlmreport v3.0 is:

	   sampleStart, sampleEnd, srdName, srdId, srdMode, srdTicapMode,
	   compName, compId, compType, compHost, compCpuMin, compCpuMax,
	   compCpuSize, compCpuAlloc, compCpuUtil, wlName, wlId, polName,
	   polId, polType, polCpuMin, polCpuMax, polCpuRate, polCpuWeight,
	   polCpuTarget, polCpuRequest, polCpuReading, polCpuOwned,
	   polTicapEnabled, polActiveId

      The v3.0 format includes all the v2.0 headers plus polTicapEnabled and
      polActiveId.

      The format of the CSV Column header line from gwlmreport v2.0 is:

	   sampleStart, sampleEnd, srdName, srdId, srdMode, srdTicapMode,
	   compName, compId, compType, compHost, compCpuMin, compCpuMax,
	   compCpuSize, compCpuAlloc, compCpuUtil, wlName, wlId, polName,
	   polId, polType, polCpuMin, polCpuMax, polCpuRate, polCpuWeight,
	   polCpuTarget, polCpuRequest, polCpuReading, polCpuOwned

      The v2.0 format includes all the v1.0 headers plus srdTicapMode and
      polCpuOwned.

      Here is the format of the CSV Column header line from gwlmreport v1.0:

	   sampleStart, sampleEnd, srdName, srdId, srdMode, compName,
	   compId, compType, compHost, compCpuMin, compCpuMax, compCpuSize,
	   compCpuAlloc, compCpuUtil, wlName, wlId, polName, polId, polType,
	   polCpuMin, polCpuMax, polCpuRate, polCpuWeight, polCpuTarget,
	   polCpuRequest, polCpuReading
      All the column headers are described below.

      sampleStart
	   Indicates the start time (in milliseconds since Jan 1, 1970) for
	   the sample.

      sampleEnd
	   Indicates the end time (in milliseconds since Jan 1, 1970) for
	   the sample.

      srdName
	   Corresponds to SRDName, which is described above in the
	   Configuration section.

      srdId
	   Is an ID for the SRD.

      srdMode
	   Corresponds to SRDMode, which is described above in the
	   Configuration section.

      srdTicapMode
	   Indicates whether the SRD was configured to use Temporary Instant
	   Capacity (TiCAP). Possible entries in this column are:

	   none
	     Default setting--or the system does not support Temporary
	     Instant Capacity.

	   off
	     Temporary Instant Capacity is supported on the system but is
	     not being used to satisfy policy requests.

	   all
	     Temporary Instant Capacity is supported on the system and can
	     be used to satisfy policy requests.

      compName
	   Corresponds to CompartmentName, which is described above in the
	   Configuration section.

      compId
	   Is an ID for the compartment.

      compType
	   Corresponds to CompartmentType, which is described above in the
	   Configuration section.

      compHost
	   Corresponds to CompartmentHost, which is described above in the
	   Configuration section.
      compCpuMin
	   Is the minimum amount of CPU resources that a compartment can
	   have. This value is the minimum resource allocation required by
	   the underlying compartment.

      compCpuMax
	   Is the maximum amount of CPU resources that a compartment can
	   have. This value is the maximum resource allocation allowed by
	   the underlying compartment. However, gWLM may reduce this number
	   at times because an SRD has a large number of compartments and
	   each compartment must receive a minimum portion of the resources.

      compCpuSize
	   Is the amount of CPU resources a compartment actually has. Size
	   may differ from the allocation when gWLM is deployed in advisory
	   mode.

      compCpuAlloc
	   Is the amount of CPU resources that gWLM sets aside for a
	   compartment after arbitrating resource requests from the policies
	   for all the compartments.

      compCpuUtil
	   Is the percentage resulting from dividing a workload's CPU
	   consumption by its CPU allocation.

      wlName
	   Corresponds to Workload, which is described above in the
	   Configuration section.

      wlId Is an ID for the workload.

      polName
	   Corresponds to PolicyName, which is described above in the
	   Configuration section.

      polId
	   Is an ID for the policy.

      polType
	   Corresponds to PolicyType, which is described above in the
	   Configuration section.

      polCpuMin
	   Is the minimum amount of CPU resources that a policy will request
	   for any workload with which it is associated.

      polCpuMax
	   Is the maximum amount of CPU resources that a policy will request
	   for any workload with which it is associated.

      polCpuRate
	   Is the convergence rate for the policy.

	   The default rate is 1.0. Larger values produce larger changes in
	   the allocation, resulting in a faster convergence on the policy's
	   target.  Similarly, smaller values slow down convergence on the
	   target.

      polCpuWeight
	   Is the CPU weight for the policy. gWLM distributes CPU resources
	   in proportion to weights when there are not enough resources to
	   satisfy all requests at a given priority. gWLM also distributes
	   CPU resources in proportion to weights if there are resources
	   remaining once all requests at all priorities have been
	   satisfied. (For OwnBorrow policies in gWLM A.01.00 / A.01.01.x,
	   the Owned value is used as the weight. Starting with gWLM
	   A.02.00.00.x, these values are separate.)

      polCpuTarget
	   Is the target value that drives a policy, influencing its
	   resource requests to gWLM.

	   For example, with utilization and OwnBorrow policies, the
	   polCpuTarget is target CPU utilization. With a target CPU
	   utilization, gWLM attempts to keep a workload's CPU utilization
	   below the target by adding CPU resources when the workload is
	   using too much of its current CPU allocation.

	   With a custom policy, polCpuTarget can be either a value to stay
	   below or to exceed. (You provide this value to gWLM using the
	   gwlmsend command).  For example, response time would be a value
	   to stay below. Adding CPU resources should help the workload stay
	   below a certain response time. As an example of a value to
	   exceed, polCpuTarget could be x transactions per second. Adding
	   resources in this case helps the workload maintain or even exceed
	   the number of transactions.

      polCpuRequest
	   Is the amount of CPU resources that a policy asks gWLM to give to
	   the policy's workloads.

      polCpuReading

	   + Utilization policies / OwnBorrow policies:
	     Is utilization.

	   + Fixed policies:
	     Is the amount of CPU resources allocated to the compartment of
	     any associated workload.


	   + Custom policies:
	     Is the value of the metric you update using the gwlmsend
	     command.

      polCpuOwned
	   Is the number of CPUs (cores) owned by the policy.

      polTicapEnabled
	   Indicates whether the policy was configured to use Temporary
	   Instant Capacity (TiCAP). If a policy is enabled to use TiCAP, it
	   can do so regardless of whether TiCAP use is enabled on the SRD
	   level, which is indicated in the srdTicapMode column.

	   Possible entries in this column are:

	   true
	     The policy is enabled to use TiCAP, if available, to satisfy
	     policy requests.

	   false
	     Default setting--the policy is not allowed to use TiCAP.

      polActiveId
	   Is an ID for the effective policy. This value matches the polId
	   value unless a conditional policy is being used, in which case
	   the value identifies the policy in effect as a result of a
	   condition being met.

      Whitespace (tabs, spaces) within a line is ignored.

      At least one column header line must be read before metric data lines
      are read. If a metric data line is encountered before a valid column
      header line, gwlmreport exits with an error to stderr.

      If you have concatenated several CSV files, you may have duplicate
      header lines. Only the first header line is used (later header lines
      are ignored).

			     CSV Metric lines
      After getting a version line and a column header line, the rest of the
      file should be comma-delimited metrics. The number of metrics must
      match the column headers and extract file version type. If they do
      not, the data is discarded and gwlmreport exits with an error.

      Here is an example line from gwlmreport v1.0:

	   1170655245009, 1170655545009, MySystem.srd, 6, Managed, none, ,
	   13, pset, MySystem.hp.com, 1.0, 7.0, 4.0, 4.0, 0.0368,
	   MySystem.build, 24, Owns_4-Max_8, 12, OwnBorrow, 1.0, 8.0, 0.0,
	   4.0, 75.0, 1.0, 3.6812, 4.0, false, 12

      Whitespace (tabs, spaces) within a line is ignored.

    Report: abnormal utilization
      The abnormal utilization report has the following sections:

	   + Report information

	   + Workload context information

	   + Samples and utilization by period

	   + Period daterange and timeslot info

	   + Footnotes

      Reports are generated for each workload specified or for all possible
      workloads if none are specified. The components of each section are
      described below.

			    Report information
      This section gives information about the report itself.

      ReportDate
	   The date and time when the report was generated.

      Workload
	   The name of the workload.

      ReportDateRange
	   Calendar dates covered by report.

      PossibleSamples
	   The total number of samples that is possible during the
	   ReportDateRange.  (This number is the sample length divided into
	   the ReportDateRange.)

      SeenDataRange
	   The date of the first sample from the gWLM database or the CSV
	   file used as input to the date of the last sample

      TargetDate
	   Date the report is focused upon. This date was specified when the
	   report was requested. (If no date was specified, this value
	   matches the enddate value.)

		       Workload context information
      Provides contextual information for the workload, such as its SRD,
      policy, and compartment.

      The workload context information generated with the abnormalutil
      report matches the information produced with the resource audit
      report. For descriptions of this information, refer to the
      Configuration Section in the "Report: resource audit" section.

		     Samples and utilization by period
      This section shows CPU utilization over time, showing the "normal"
      utilization for a workload. If a workload misbehaves for a certain
      period, you can compare its utilization during that period against the
      data shown in this section to help determine what has changed. The
      section provides the following metrics:

      AvgUtil
	   Average CPU utilization.

      AvgReq
	   Average CPU allocation request for the workload by its policy.

      AvgAlloc
	   Average CPU allocation gWLM gave to the workload.

      ActSamp
	   The actual number of samples seen in a given time period (column
	   heading in the report) from the current data source.

      PossSamp
	   The number of possible samples for a given time period (column
	   heading in the report).

      AvgSampDur
	   Average duration of each sample.

      PolMin
	   The policy's minimum core value.

      PolOwn
	   The policy's owned core value.

      PolMax
	   The policy's maximum core value.

		    Period daterange and timeslot info
      This section indicates dates and times for the samples. It gives a
      more full explanation of the column headings from the table in the
      "Samples and Utilization by period" section.

      Previous Sample
	   Dates/times for the sample immediately before the TargetDate.

      Previous Hour
	   The hour previous to the TargetDate.


	   DesiredDateRange
		Shows the date/time for the previous hour.

	   ActualDateRange
		Shows the date/time actually used. This value matches
		DesiredDateRange if the workload existed for the entire
		period. Otherwise, "null" indicates that samples were not
		available at the beginning and/or end of the time period.

	   Samples
		Indicates the number of samples collected from the given
		time period.

      Previous 24 Hours
	   The 24 hours previous to the TargetDate.

	   DesiredDateRange, ActualDateRange, and Samples are as described
	   for "Previous Hour" above.

      Weekly Timeslot
	   The one hour matching the hour used with TargetDate, but from the
	   week before the TargetDate.

	   Samples indicates the number of samples collected from the given
	   time period.

      All Samples
	   DesiredDateRange, ActualDateRange, and Samples are as described
	   for "Previous Hour" above.

      So if --targetdate is 2005/07/14:12, then:

      Previous Sample
	   is the sample immediately before 2005/07/14:12

      Previous Hour
	   is the period 2005/07/14:11:00:00 to 2005/07/14:11:59:59

      Previous 24 Hours
	   is 2005/07/13:12:00:00 to 2005/07/14:11:59:59

      Weekly Timeslot
	   is any Monday from 12:00:00 to 12:59:59

      All Samples
	   includes any samples that fell within ReportDateRange

				 Footnotes
      Footnotes are printed to warn or alert you that there was some kind of
      exceptional event during the report durations that could affect the
      data.
      The footnotes generated with the abnormalutil report match the
      footnotes produced with the resource audit report. For descriptions of
      the footnotes, refer to the Footnotes subsection of the "Report:
      resource audit" section.

    Report: ovpafeed
      The gwlmreport ovpafeed command does not generate a text report;
      rather, it produces data in a DSI logfileset in
      /var/opt/dsi/version/gwlm* for use by the OVPA subsystem.

      The data is a subset of gWLM's historical data and the data presented
      in gWLM's advanced reports. Making it available to OV tools is
      intended as a service for customers that already use OVPA or OpenView
      Service Reporter in their normal work. If you do not need to view gWLM
      data with OVPA or OVSR, there is no need to run gwlmreport ovpafeed.

      If you no longer need the data from the ovpafeed reports or you simply
      want to erase all your DSI data and start over, you can delete the
      /var/opt/gwlm/dsi/version/* directory. You must then run gwlmreport
      ovpafeed --setup again before doing further ovpafeed reports.

      For information on using the ovpafeed command, see Example 11 in the
      EXAMPLES section above.

    Report: config
      The config report summarizes the current configuration. With --diff,
      it summarizes configuration changes between the specified start and
      end dates.

      The report contents are self-explanatory.

ERRORS, WARNINGS, and FOOTNOTES

    ERRORS
      If gwlmreport is successful, it exits with a zero.

      For any error, a message is printed to stderr and gwlmreport exits
      with a nonzero value.

      Errors include:

      The --inputpath directory does not exist or is unreadable.

      The --outputpath directory does not exist or is unwritable.

      Cannot connect to gWLM database--gWLM is not running

	   If gWLM has difficulties retrieving historical data for a
	   workload, errors are logged to the gwlmcmsd log file and possibly
	   to the gwlmagent log file. For information on these log files,
	   see the gwlmcmsd(1M) manpage.

      Unexpected line numbers in errors

	   When specifying --inputpath=path and multiple --workload=workload
	   arguments, gwlmreport combines the CSV files for all the
	   specified workloads into a single input stream.  As a result, any
	   line numbers given in error messages are for the single input
	   stream--not the individual CSV files. For example, if you have 3
	   files each of 1000 lines, an error might mention line 1711. This
	   would actually be a problem around line 711 in the CSV file for
	   the second workload specified in your gwlmreport command line.

    WARNINGS
      gwlmreport produces warnings to stderr of irregularities seen while
      extracting the data and building any reports.

      If no workloads match the target workload names, a warning is reported
      that no samples were found for the given workloads.  Similarly, if no
      samples are found in the database or CSV input that match the
      specified reporting time frame, policy name, or no Managed samples
      were found, a warning is printed:

	   "No audit report possible for workload "mywkld" as it had zero
	   matching samples.  There are several potential reasons for this:
	   there may be no workload by that name, no matching data for the
	   given dates, only samples that are Advisory or the wrong policy
	   name."

    FOOTNOTES
      For the resourceaudit, topborrowers, and abnormalutil reports, many
      input data irregularities are detected and warnings produced via
      footnotes in the report.

LIMITATIONS

      You must be root to run gwlmreport.  Also, you must run gwlmreport on
      the gWLM central management server (the system where gwlmcmsd is
      running.)

gwlmsend(1M)

Date: 2006/12/20 
Revision: 1.21 

NAME

      gwlmsend - send metric data to gWLM for use in a custom policy

SYNOPSIS

      gwlmsend [-h] [-w wait_time] metric [value]

AVAILABILITY

      This command is available only on gWLM managed nodes (systems where
      you run gwlmagent).

DESCRIPTION

      gwlmsend updates values for metrics named in gWLM's custom policies.
      You define these metrics by specifying them in a custom policy.  gWLM
      then depends on you to provide values for the metrics. gWLM compares
      these values against targets you specify, and then adjusts resource
      allocations accordingly.

      Use gwlmsend in a script or on the command line to provide either a
      single metric value or a stream of values separated by white space on
      standard input.

      Presumably, you will use a command to collect or provide values for
      your metrics. Ensure this command provides a continuous stream of
      metrics for your custom policy's use by starting it in a boot script
      or by having cron start it.

      Metric-collection points are used to transfer the values for metrics
      to gwlmagent.  gwlmsend does not create the metric-collection points;
      this is done by gwlmagent.  However, gwlmsend can be told to wait for
      the creation of the metric-collection point through a command-line
      option.

OPTIONS

      -h   Displays usage information and exits. This option overrides all
	   other options.

      -w wait_time
	   Instructs gwlmsend to wait wait_time seconds for the metric-
	   collection point to be created before exiting. The default
	   wait_time is 5 seconds.

	   Being able to specify this delay is useful when gWLM management
	   starts with a system boot: You may need to give the gwlmagent
	   daemon more time to create the metric-collection point.

      metric
	   Specifies that the gWLM metric with