ksysrppmgr command

Purpose

Manage the POWER® Enterprise Pool resources and the Elastic Capacity on Demand (CoD) resources, which was formerly known as On/Off CoD. The ksysrppmgr command adjusts available resources on the managed hosts; you do not need to check the current available resources. This command also minimizes your resource costs by optimizing the local consumption of pool resources. For example, this command can convert Elastic (On/Off) CoD resources to Enterprise Pool CoD resources automatically. The ksysrppmgr command can also be used if the current level of resources is sufficient for your requirements. In this case, the command might release unnecessary resources.

Syntax

ksysrppmgr -o action
  -h [hmc_name]:hmc_uri:hmc_user
  [-m ms_name:ms_action:[onoff_use(n|y[nb_days])]:[mem_amount]:[proc_amount]]
  [-M ms_uuid:ms_action:[onoff_use(n|y[nb_days])]:[mem_amount]:[proc_amount]]
  [-e enterprisepool_name]
  [-E enterprisepool_uuid]
  [-v] [-r] [-l none|logfile_path] [-p logfile_prefix]

Description

When you run the ksysrppmgr command, the HMC retrieves information about the topology of the managed hosts and resources. Then, the resource requests are processed. You do not need to check the current level of available resources to run the ksysrppmgr command. The ksysrppmgr command automatically determines whether a resource acquisition or a resource release is required to fulfill your resource request.

In both the modes, you must first explore the topology and resource levels by logically connecting all the entities. When you explore the topology, you can identify the Enterprise Pools that are associated with a managed host. During the topology exploration, the REST universally unique identifier (UUID) and information about the entities are also read. For example, you can identify whether the Elastic (On/Off) CoD is enabled for a specific managed host. After you explore the topology, you can use the results to optimize the requirements of the subsequent requests.

When you run the ksysrppmgr command in check mode, all the execution steps are performed except that all the HMC operations are simulated after the initial processing. The initial process contains the topology exploration. During the topology exploration, the HMC reads the status of resources for all entities (pools and managed hosts) that are involved in the operation, because the current values must be used as base values for all the simulation. The command execution in the check mode might show some differences as compared to the results in the execution mode when you use Elastic (On/Off) CoD facility because the HMC might contain some information about the current day activations that are available only in execution mode.

When you run the ksysrppmgr command that contains multiple resource requests, the requests are executed sequentially. If you want to execute the resource requests simultaneously, you can run the ksysrppmgr command separately for each managed host. In this case, the topology cost must be paid for each command execution.

If you are using the Power Enterprise Pools facility, the ksysrppmgr command handles the conflicts in resource requests. If the same managed host has contradictory requests, the available amount of resources cannot be guaranteed but will be at least at the lowest request value, and at most at the highest request value. For example, if one CPU is available in the host_1 host, and if you run three ksysrppmgr request simultaneously for the host_1 host each requesting two CPUs, three CPUs, and five CPUs. When all the three ksysrppmgr commands are run, the number of available CPUs cannot be predicted. However, the number of available CPUs will be between the lowest and the highest request, that is, in the range 2 - 5. Therefore, you might avail 2, 3, 4, or 5 CPUs depending on the priority of the threads indicated by the system.

If you are using the Elastic (On/Off) CoD facility, the conflicts are handled based on resource priority and therefore, the method is thread-safe. For example, a conflict of request during a resource acquisition is retried until success and a conflict of request during a resource release is dropped immediately. In this case, the amount of resource that is released might not be as expected, but this change is not treated as an error.

You must specify the correct Enterprise Pool to decrease the topology exploration cost of Enterprise Pools. If the Enterprise Pool is not specified in the ksysrppmgr command, the ksysrppmgr command checks all the Enterprise Pools that are identified by the HMCs, which are specified in the command, to find the correct pool for the specified managed hosts. If one or more Enterprise Pools are specified in the command, only those Enterprise Pools are checked to get the required information. Therefore, the time spent in topology exploration is reduced. However, if you are not sure of which Enterprise pools can be used, you can run the command to request the resource without specifying any Enterprise Pools.

When the ksysrppmgr command ends successfully, and if no other command was run for the same managed host with different resource levels, the requested resources are made available to the specified host. If you specify the -r flag in the command, you can open the log file to check whether the requested amount of resources match the existing amount of available resources at the end of command execution.

By default, the log files for the ksysrppmgr command are located in the /var/ksys/log/capmgr.log file. You can configure the log file settings to overwrite the existing logs or delete the old log files after the log files reach a specific limit. You can also set a log file prefix to analyze the log files if more than one execution information is available in the log files.

cat logfile | grep -e "##" -e "@@" | cut -d " " -f 2-

Flags

-o action

Specifies the action to be performed. The following action flags are available:

execute (alias: e)

Runs the resource requests.

check (alias: c)

Simulates whether the resource requests can be completed.

-h [hmc_name]:hmc_uri:hmc_user

Specifies the HMC details.

The Unique Resource Identifier (URI) and the user name of the HMC are mandatory parameters. The hmc_name parameter is optional and is used only if the HMC REST API page about HMC information returns information about other HMCs too, which might not occur.

All colons (:) in this flag are required, even if the optional parameters are not filled. This flag can be specified multiple times to add multiple HMCs.

-m ms_name:ms_action:[onoff_use(n|y[nb_days])]:[mem_amount]:[proc_amount]

Specifies the name of the managed host that must be configured for CoD resources.

The host name and action parameters are mandatory. Currently, the only allowed value for the ms_action parameter is s or set. This parameter matches the amount of requested resource to the amount of available resource. The unit to specify the memory resource is MB.

All colons (:) in this flag are required, even if the optional parameters are not filled. This flag can be specified multiple times to add multiple hosts.

-M ms_uuid:ms_action:[onoff_use(n|y[nb_days])]:[mem_amount]:[proc_amount]

Specifies the universally unique identifier (UUID) of the managed host that must be configured for CoD resources.

All other parameters are similar to the parameters of the -m flag.

-e enterprisepool_name

Specifies the name of the Enterprise Pool that must be monitored.

If the -e or -E flags are not specified, all the enterprise pools are monitored by default. This flag can be specified multiple times.

-E enterprisepool_uuid

Specifies the UUID of the Enterprise Pool that must be monitored.

If the -e or -E flags are not specified, all the enterprise pools are monitored by default. This flag can be specified multiple times.

-v

Specifies that you want to display detailed processing information on your screen.

This flag displays the information about the managed host and return codes, one per line, at the end of the execution.

-r

Specifies that you want detailed report.

This flag enables logging operation that includes the overall status of topology and resources before and after execution. It also includes a timing analysis on the overall execution.

If you specify this option, more REST operations might be triggered, which require more time to complete.

-l

Specifies the log file that must be used.

By default, the /var/ksys/log/capmgr.log file is used for the logging operation. You can use the none value to remove all the logging operations. The libhmc log files are stored in the LOGFILE.librpp_last_rest.log file or in the LOGFILE.LOGPREFIX.librpp_last_rest.log file if the log prefix is specified. The libhmc log files overwrite previous log files, if the same prefix or no prefix was used.

-p

Specifies the log prefix that must be used in the log files.

This flag specifies the prefix string that is determined at the beginning of each log string, along with other prefix information. This flag can also be used to avoid overwriting the libhmc log files.

Return values

Because you can run the ksysrppmgr command on multiple hosts simultaneously, you cannot get a complete error report in the return value. For a more detailed error report for each managed host, you must run the ksysrppmgr command with the -v flag. The following error codes can be returned:

0

The operation was successful.

1

An error occurred.

2

Indicates command line parsing error