SNCAP(8)

NAME¶

sncap - remote dynamic CPU capacity management

SYNOPSIS¶

sncap CPCID -a RECID [-t][-n][-V] PROCINFO [ACCESSDATA]

sncap CPCID -d RECID [-n][-V] [PROCINFO] [ACCESSDATA]

sncap CPCID -q RECID [-V] [ACCESSDATA]

sncap CPCID -l [-V] [ACCESSDATA]

scnap CPCID -c [-V] [ACCESSDATA]

sncap -x [-V] ACCESSDATA

sncap [-v|-h]

DESCRIPTION¶

Use the simple network System z 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 (CPE) and On/Off Capacity On-Demand (OOCOD) temporary capacity records. sncap requires the Support Element (SE) or Hardware Management Console (HMC) software version 2.10.0 or later. The command can operate only with the records that are installed on the support element (SE).

sncap uses the management application programming interfaces (APIs) provided by the SE or HMC (HWMCAAPI API servers). 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, the Linux system where sncap is run, to access the API.

GENERAL OPTIONS¶

CPCID: Central Processing Complex identifier specified in the SE network settings configuration. This parameter also identifies the configuration file section where the server connection parameters (see ACCESSDATA) can be specified. The CPCID value can be found in the SE user interface in the "Identification" tab of the "Customize Network Settings" window or using sncap with the -x option. This parameter is mandatory for the activation, deactivation and query operations, and should be specified as command line argument.
Example: CPC204
RECID: The identifier of a temporary capacity record that is installed on the SE you want to work with.
-a or --activate: Activates the temporary capacity record with the record identifier RECID and processor parameters PROCINFO. You must specify the PROCINFO parameters to activate the record.
-t or --test: Activates the temporary capacity record in test mode for up to 10 days. Use test mode to activate the record for a short period 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 together with the -a (--activate) 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 performed successfully. The querying functions run as in the regular execution mode.
-x or --list_cpcs: Sends the output of the list of CPCs that are defined on an SE or HMC to stdout. 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 ACCESSDATA.
-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 record activation attempts in the Real or Test mode.
-q or --query: Displays the detailed information about the temporary capacity record RECID, installed on the specified CPC, including the data for the available CPU capacity models defined in the record, and the current CPC processor capacity parameters. A value of -1 for the temporary capacity record activation parameters means that there is an unlimited value. 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. The asterisk '*' value of the maximum quantity of CP type PUs means that all the PUs defined in the temporary capacity record can be activated as the CP type PUs.
-c or --pu_configuration: Displays information about the current CPC processing unit configuration. The information includes the number of active processors, the processors available for temporary activation, model capacity identifier and current MSUs available on the CPC. A hypen, '-', in the report fields means that the value is not applicable for temporary or permanent configuration.
-h or --help: Displays a short usage description and exits. To view the man page, issue man sncap.
-v or --version: Displays the version of sncap and exits.
-V or --verbose: Specifies the verbose mode.

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 record, the command returns with return code 17. No processors are activated or deactivated.

--zaap <n>: Specifies the number (n) of ZAAP processors in the PROCINFO parameters to be activated or deactivated.
--ziip <n>: Specifies the number (n) of ZIIP processors in the PROCINFO parameters to be activated or deactivated.
--icf <n>: Specifies the number (n) of ICF processors in the PROCINFO parameters to be activated or deactivated.
--ifl <n>: Specifies the number (n) of IFL processors in the PROCINFO parameters to be activated or deactivated.
--sap <n>: Specifies the number (n) of SAP processors in the PROCINFO parameters to be activated or deactivated.
-m <id> 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 using the support element user interface, or the --query <RECID> function 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 parameter 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.

ACCESSDATA¶

-S <ip_address> --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 using the cpcid attribute.
-p <password> 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, and 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. When encryption is enabled, the password command line parameter specifies the password for the SNMPv3 username from the -u (--userid) 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 could be specified either in the command line or in the configuration file.
-e or --noencryption: Disables SE or HMC connection encryption. User name is not needed if encryption is disabled. By default, connection encryption is enabled.
-f <filename> 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 CPCID, 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 which contains the ACCESSDATA values. If the CPCID 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 ACCESSDATA are provided through the command line and the configuration file, the command line specification is used. If a configuration file is neither specified nor available at the default locations, all required parameters must be specified on the command line.
--timeout <timeout>: Specifies the timeout in milliseconds for general management API calls. The default is 60000 ms.

STRUCTURE OF THE CONFIGURATION FILE¶

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 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 because these sections define connections to z/VM systems in the snipl configuration file and sncap can only connect 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 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:

o: 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.
o: Empty lines are permitted.
o: The specifications are not case sensitive.
o: 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, once per section): specifies the user name from the SNMP settings of the HMC. When omitted, you must specify the user name in the sncap command line arguments. The user name is not needed for unencrypted connections.
password (optional, 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. When encryption is enabled, the password is the SNMPv3 user name password from the SNMPv3 settings of the SE or HMC.
encryption (optional, once per section): specifies whether the server connection is encrypted. Allowed values: yes or no. If not specified, encryption is enabled by default.
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. Note that 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".

The other snipl configuration file keywords are ignored by sncap.

Sample configuration file:
-----------------------------------------------------------
# Comment line (ignored).
#
# A section that defines a support element connection.
#
Server = 192.0.2.4
type = LPAR
cpcid = SZ01CP00
encryption = yes
user = hugo
password = pw42play
encryption = yes
#
# A section which defines a hardware management console
# connection.
#
Server = 192.0.2.2
encryption = no
type = LPAR
cpcid = SZ02CP00
cpcid = SZ02CP01
cpcid = SZ02CP03
cpcid = SZ02CP04
password= pw42play
<EOF>
-----------------------------------------------------------

RETURN CODES AND CONNECTION ERRORS¶

Successful sncap commands return 0 and write the message "Execution completed successfully" to stderr. If an error occurs, sncap writes a short message to stderr and completes with a return code other than 0.

1: An unknown command option was specified.
2: A command option with an invalid value was specified.
3: A command option was specified more than once.
4: Conflicting command options were specified.
5: No command option was specified.
6: No request server was specified on the command line, nor in a configuration file.
7: Temporary capacity record <RECID> is not installed on CPC <CPCID>.
8: Server version is not supported.
9: No password was specified on the command line, nor through a configuration file.
10: The specified CPC does not exist.
11: Insufficient hardware resources to complete the request.
12: The timeout occurred, the command is cancelled.
13: An invalid password was specified.
14: An invalid model capacity identifier was specified.
15: No operation option was specified.
16: Invalid server IP address or DNS name was specified.
17: Too many processors were specified for the operation. No processors were activated.
18: An error was received from HWMCAAPI API.
19: Missing mandatory argument.
20: An error occurred when processing the configuration file.
21: One of the specified processor types is not defined in the temporary capacity record.
22: Cannot deactivate the inactive temporary capacity record.
23: The number of activations was exhausted.
24: No user name was specified in the command line or configuration file. User name is required when encryption is selected.
25: User name must not be specified when encryption is disabled.
26: The wrong encryption value was specified in the configuration file. Use "yes" or "no".

The following return codes indicate setup errors or program errors:

50: A response from the SE or HMC could not be interpreted.
90: A storage allocation failure occurred.
99: A program error occurred.

If a connection error occurs (such as a timeout), sncap sends a message to stderr.

To recover connection errors, try to issue the command again. If the problem persists, a networking failure is most likely. In this case, increase the timeout value. When sncap receives an error code from SE or HMC, it returns application return code 18.

Error messages from the SE have this format:

<server address>: <message> - rc is <rc>

where <rc> is a return code from the HWMCAAPI on the SE or HMC.

Example: 192.168.1.15: not acknowledged - command was not successful - rc is 135921664.

To interpret these return codes, see System z Application Programming Interfaces, SB10-7030. You can obtain this publication from IBM Resource Link at www.ibm.com/servers/resourcelink.

NOTES¶

When a temporary capacity record activation or deactivation command cancels due to a timeout (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 occurred, the requested operation can still continue to run on the CPC support element and potentially complete successfully. Use -q / --query to investigate the record's state before issuing the next command for that CPC.

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.

EXAMPLES¶

To activate a CBU temporary capacity record CB7KHB38 on CPC SZ02CP03 to temporarily upgrade it to model capacity identifier 741:
sncap SZ02CP03 -S 192.0.2.2 -e -P -a CB7KHB38 -m 741

To activate only a subset of processors defined in temporary capacity record CB7KHB38 on the CPC SZ02CP03:
sncap SZ02CP03 -S 192.0.2.2 -e -P -a CB7KHB38 --zaap 2 --ziip 2

To deactivate a CBU temporary capacity record CB7KHB38 on the CPC SZ01CP00:
sncap SZ01CP00 -S 192.0.2.4 -u hugo -P -d CB7KHB38

To deactivate only a subset of processors defined in temporary capacity record CB7KHB38 on the CPC SZ01CP00:
sncap SZ01CP00 -S 192.0.2.4 -u hugo -P -d CB7KHB38 --zaap 2 --ziip 2

With a suitable configuration file at /etc/xcfg the previous command can be shortened to:
sncap SZ01CP00 -f /etc/xcfg -d CB7KHB38 --zaap 2 --ziip 2

With a suitable default configuration file the command can be further shortened to:
sncap SZ01CP00 -d CB7KHB38 --zaap 2 --ziip 2

AUTHOR¶

Copyright IBM Corp. 2012, 2013
Published under the terms and conditions of the CPL
(common public license).

Source file:	sncap.8.en.gz (from snipl 0.3.0.0-150600.17.3)
Source last updated:	2024-05-09T10:43:19Z
Converted to HTML:	2025-04-28T10:11:06Z