sncap - Manage CPU capacity

Use the simple network CPU capacity management (sncap) command to specify a temporary capacity record activation or deactivation and operation parameters for a CPC. This command can control the Capacity BackUp (CBU), Capacity for Planned Events, and On/Off Capacity On-Demand (OOCOD) temporary capacity records.

For command return codes, see the man page.

The sncap command is included in the snipl package that is provided with SUSE Linux Enterprise Server 12 SP4.

Before you begin:

sncap requires the Support Element (SE) and Hardware Management Console (HMC) software version 2.10.0 or later. The command can operate only with the records that are installed on the SE.
sncap uses the management application programming interfaces (APIs) provided by the SE or HMC (HWMCAAPI API servers). For information about the management APIs of the SE and the HMC, see System z® Application Programming Interfaces, SB10-7030, available from IBM® Resource Link® at www.ibm.com/servers/resourcelink.
To communicate with the server, sncap establishes a network connection and uses the SNMP protocol to send and retrieve data by using HWMCAAPI API calls. The server must be configured to allow the initiating host system to access the API.

Note:

A temporary capacity record activation or deactivation command might cancel due to a timeout. The timeout is indicated by return code 12 - "Timeout occurred, the command is canceled" or 18 - "An error was received from the HWMCAAPI API", with the short message about the timeout. If a timeout occurs, the requested operation can still continue to run on the CPC support element and potentially complete successfully. Use -q to investigate the state of the record before you issue the next command for that CPC.
The sncap command processes cannot be run in parallel for the same CPC for temporary capacity record activation or deactivation. Also, a sncap process that is started for a temporary capacity record activation or deactivation cannot run in parallel with a snipl process for the same CPC.
For CPCs with simultaneous multithreading, sncap acts on entire hardware cores, not at the level of individual threads.

sncap syntax

where:

<CPCID>

identifies the Central Processing Complex that is specified in the SE network settings configuration. This parameter also identifies the configuration file section where the server connection parameter can be specified (see access-data). Find the <CPCID> value either in the SE user interface in the Customize Network Settings window under the Identification tab, or by using sncap with the -x option. This parameter is mandatory for the activation, deactivation, and query operations. Specify it as a command-line argument.

<RECID>

identifies a temporary capacity record that is installed on the SE that you want to work with.

-a or --activate

activates the temporary capacity record with the record identifier <RECID> and processor parameters PROCINFO. The PROCINFO parameters must be specified for the record activation.

-t or --test

specifies the temporary capacity record activation in the test mode for up to 10 days. The test mode allows temporary record activation the number of times that are specified in the record definition. Real activation is possible only while no test is active. This option can be used only with the -a option.

-d or --deactivate

deactivates the temporary capacity record with the record identifier <RECID> and processor parameters PROCINFO on the CPC <CPCID>. If the PROCINFO data is specified, -d deactivates only the specified processors in the CPC configuration. If the PROCINFO parameters are not specified, -d deactivates the entire record.

-n or --no_record_changes

skips any actions that would change the records. This mode can be used for debugging purposes. When specified, sncap does not change the temporary capacity record state during the record activation or deactivation. It assumes that the activation or deactivation request is always successful. The querying functions run as in the regular mode.

-x or --list_cpcs

Sends the output of the list of CPCs that are defined on an SE or HMC to standard out. The list contains the CPC identifiers and its support element version numbers. When the -x option is specified, the -S specification of the server IP address or DNS name is required as part of the access data.

-q or --query

displays detailed information about the temporary capacity record <RECID>, installed on the specified CPC. The information includes the data for the available CPU capacity models that are defined in the record and the current CPC processor capacity parameters.

If the temporary capacity record activation parameters have a value of -1, the parameter value is unlimited.
The negative value of PU or CLI in the Available Model Capacity Identifiers table designates the number of PU or CLI to be deactivated to achieve the listed model capacity.
If the maximum quantity of CP type PUs shows an asterisk (*), all the PUs defined in the temporary capacity record can be activated as the CP type PUs.

-l or --list_records

displays the list of temporary capacity records that are installed on the specified CPC. A value of -1 in the Real Act. and Test Act. report fields means that there is an unlimited number of available record activation attempts.

-c or --pu_configuration

displays the information about the current CPC processing unit configuration, including the number of active processors, the processors available for temporary activation, model capacity identifier, and current MSUs available on the CPC. A minus sign (-) in the report fields means that the value is not applicable for temporary or permanent configuration.

-V or --verbose

displays information useful for debugging.

-v or --version

displays the version number of sncap, then exits.

-h or --help

displays a short usage description and exits. To view the man page, issue man sncap.

PROCINFO

Specifies the processor types and quantities to be activated or deactivated on the CPC <CPCID> to change the record activation level. The temporary capacity record activation operation requires the PROCINFO parameters. The PROCINFO parameters can be omitted for the record deactivation. If no specific processor type is specified, all the processors from the temporary capacity record are deactivated in the CPC. The model capacity identifier is set to the minimal available model capacity value. Each processor type can be specified only once. If more processors are specified for activation or deactivation than are defined in the record, the command returns with return code 17. No processors are activated or deactivated.

--zaap <number>: specifies the number of zAAP processors to be activated or deactivated.
--ziip <number>: specifies the number of zIIP processors to be activated or deactivated.
--icf <number>: specifies the number of ICF processors to be activated or deactivated.
--ifl <number>: specifies the number of IFL processors to be activated or deactivated.
--sap <number>: specifies the number of SAP processors in the PROCINFO parameters to be activated or deactivated.
-m or --model-capacity <ID>: specifies the model capacity identifier <ID> to be activated by the command. The model capacity identifiers are supplied in the temporary capacity record. They can be found either by using the support element user interface, or the --query <RECID> option of the sncap application. Use the model capacity identifier to control the number of CP processors and the Capacity Level Indicator value to be activated or deactivated to achieve the target CPU capacity model. Also, the model capacity identifier influenced the Target MSU Value and MSU Cost parameters. If the -m option is specified without the processor types and quantities, it activates or deactivates only the specified capacity model. It then leaves the active auxiliary processor quantities unchanged.

access-data

-S or --se <ip_address>

Specifies the IP address or DNS name for the SE or HMC that controls the CPC you want to work with. You can omit this parameter if the SE or HMC IP address or DNS name and community are specified in the sncap configuration file. The IP address of SE or HMC is identified in the configuration file with the cpcid attribute.

-p or --password <password>

Specifies the password (community) from the SNMP configuration settings on the SE or HMC that controls the CPC you want to work with. This parameter is required. It must be specified either in the command line or in the configuration file. Alternatively, use the -P option to prompt the user for the password.

The password depends on whether the connection is encrypted:

When encryption is disabled, the password specifies the password (community) from the SNMP configuration settings on the SE or HMC that controls the CPC you want to work with.
When encryption is enabled, the password parameter specifies the password for the SNMPv3 username from the -u command line parameter or user keyword value in the sncap configuration file.

-P or --promptpassword

Prompts for a password (community) in protected entry mode.

-u <username> or --userid <username>

Specifies the user name from the SNMP configuration settings of an SE or HMC that controls the CPC you want to work with. This parameter is required if encryption is active, and can be specified on the command line or in the sncap configuration file.

-e or --noencryption

Disables SE or HMC connection encryption. By default, connection encryption is enabled. A user name is not allowed if encryption is disabled.

-f or --configfilename <filename>

Specifies the name of the sncap configuration file that maps CPC identifiers to the corresponding specifications for the SE or HMC addresses and passwords. If no configuration file is specified, the user-specific default file ~/.snipl.conf is used. If this file does not exist, the system default file /etc/snipl.conf is used. A connection to server requires specification of the CPC ID, the SE or HMC IP address or DNS name, and the password (community). If only the <CPCID> parameter is specified on the command line, it identifies the section of the configuration file that contains the credentials values. If the CPC ID and the server IP address are specified, sncap looks for the password in the configuration file using the server IP address for the configuration file section identification. If your specification maps to multiple sections, the first match is processed. If conflicting specifications of credentials are provided through the command line and the configuration file, the command-line specification is used. If no configuration file is specified or available at the default locations, all required parameters must be specified on the command line.

--timeout <ms>

Specifies the timeout in milliseconds for general management API calls. The default is 60000 ms.

Configuration file structure

Any required connection parameters that are not provided on the command line must be specified through the configuration file. The command-line specifications override specifications in the configuration file. The sncap command uses the CPC identifier to select the configuration file sections to retrieve the relevant connection parameters. You must specify the CPC identifier on the command line for all sncap operations except the -x option. The -x option is used to retrieve the CPC identifier list that is defined on a server.

The structure of the sncap configuration file is similar to the snipl configuration file structure. You can use the snipl configuration file with sncap if you add the CPC identifiers to the snipl server definition sections by using the cpcid keyword. The cpcid keywords can be added only to the support element HWMCAAPI API server definitions (LPAR type sections). They cannot be added to the configuration file sections of the VM type. VM type sections define connections to z/VM® systems in the snipl configuration file and sncap can connect only to SEs or HMCs.

An sncap configuration file contains one or more sections. Each section consists of multiple lines with specifications of the form <keyword>=<value> for an SE or HMC. The sncap command identifies the sections by using the CPC identifier. To retrieve the connection parameters from the configuration file, at least the CPC identifier must be specified on the command line. If both the server IP address (or DNS name) and the CPC identifier are specified on the command line, the password is selected in the configuration file by using the server IP address (or DNS name). When you use the -x command-line option to get the list of defined CPCs on a server, specify only the server IP address (or DNS name) on the command line.

The following rules apply to the configuration file:

Lines that begin with a number sign (#) are comment lines.
A number sign in the middle of a line makes the remaining line a comment.
Empty lines are allowed.
The specifications are not case-sensitive.
In a <keyword>=<value> pair, one or more blanks are allowed before or after the equal sign (=).

The following list maps the configuration file keywords to command line equivalents:

server: (required, once per section) starts a configuration file section by specifying the IP address or DNS name of an SE or HMC. This attribute is equivalent to the --se command-line argument.
user: (optional, at most once per section) specifies the username from the SNMP settings of the HMC or SE. When omitted, you must specify the user name in the sncap command line arguments. The user parameter applies to encrypted connections only, and is not allowed for unencrypted connections.
password: (optional, at most once per section) specifies the password (community) from the SNMP settings of the SE or HMC. If omitted, you must specify the password in the sncap command-line arguments. Alternatively, use -P option to prompt the user for the password. This attribute specifies the --password command-line argument.
encryption: (optional, at most once per section) specifies whether the server connection is encrypted. Valid values are: yes or no. If not specified, encryption is enabled by default. Specifying "encryption = no" is equivalent to the -e command-line argument.
cpcid: (required, at least once per section) specifies the Central Processing Complex name that is defined in the hardware. This server attribute is used to map the CPC identifier to the server IP address (DNS name) and password. There can be more than one cpcid entry in a section if the server is an HMC.
type: (optional, at most once per section) specifies the server type. This parameter is used to provide compatibility with the snipl configuration file. If it is specified, it must have the value "LPAR".

Sample configuration file

-----------------------------------------------------
# Comment line (ignored).
#
# A section that defines a support element connection.
#
Server = 192.0.2.4
type = LPAR

encryption = yes
user = hugo
cpcid = SZ01CP00
password = pw42play
#
# A section that defines a hardware management console
# connection.
#
Server = 192.0.2.2
type = LPAR
encryption = no
cpcid = SZ02CP00
cpcid = SZ02CP01
cpcid = SZ02CP03
cpcid = SZ02CP04
password= pw42play
<EOF>
----------------------------------------------------------

Examples

To activate a CBU temporary capacity record CB7KHB38 on CPC SCZP201 to temporarily upgrade it to model capacity identifier 741:
```
sncap SCZP201 -S 192.0.2.4 -e -P -a CB7KHB38 -m 741
```
To activate only a subset of processors defined in temporary capacity record CB7KHB38 on the CPC SCZP201:
```
sncap SCZP201 -S 192.0.2.4 -e -P -a CB7KHB38 --zaap 2 --ziip 2
```
To deactivate a CBU temporary capacity record CB7KH38 on the CPC SCZP201:
```
sncap SCZP201 -S 192.0.2.4 -e -P -d CB7KHB38
```
To deactivate only a subset of processors defined in temporary capacity record CB7KHB38 on the CPC SCZP201:
```
sncap SCZP201 -S 192.0.2.4 -e -P -d CB7KHB38 --zaap 2 --ziip 2
```
With a suitable configuration file at /etc/xcfg the previous command can be shortened to:
```
sncap SCZP201 -f /etc/xcfg -d CB7KHB38 --zaap 2 --ziip 2
```
With a suitable default configuration file the command can be further shortened to:
```
sncap SCZP201 -d CB7KHB38 --zaap 2 --ziip 2
```

For information about the sncap report fields and sample workflows for the temporary capacity record installation, activation and deactivation, see the Redbooks® publication z Systems Capacity on Demand User's Guide, SC28-6943 or any updates of this publication that applies to your mainframe system.