Scroll to navigation

cpacfstats(1) General Commands Manual cpacfstats(1)

NAME

cpacfstats - enable, disable and display CPACF statistical data

SYNOPSIS

cpacfstats [-h|--help] [-v|--version] [-e|--enable counter ] [-d|--disable counter ] [-r|--reset counter ] [-p|--print counter [-n|--nonzero] ] [-j|--json]

DESCRIPTION

The cpacfstats client application interacts with the cpacfstatsd daemon and triggers actions. The application enables, disables, resets, and fetches one or all of the mainframe CPACF performance counters with the help of the daemon process.

All counters are initially disabled and must be switched on to measure CPACF activities of the system. There is a slight performance penalty with CPACF counters enabled.

CPACF activity counters come in two flavors: CPU-MF and PAI. CPU-MF counters are only available on LPARs and have to be authorized. If they are available, the counters des, aes, sha, rng, and ecc are made available. These counters can individually be activated, reset, printed, or deactivated. PAI counters are a lot more detailed. The user interface only offers the counters pai_user and pai_kernel to count CPACF usage in user-space or kernel-space. When printing these counters, detailed counters are shown.

A complete list of counters can be found at the end of this manpage.

Note that the counters starting with PCKMO and Reserved are only available in the pai_kernel set. Also note that the counters are designed to count successful operations. In the case of KMA this means only complete GCM operations including final hashing are counted.

Note: CPU-MF based CPACF performance counters are available on LPARs only. PAI counters are available on all hypervisors. For security reasons only members of the group cpacfstats are allowed to run the cpacfstats client application.

Example usage scenario:

1. Start the cpacfstatsd daemon with root privileges using 'systemctl start cpacfstatsd'.

2. Check for successful startup by using the 'systemctl status cpacfstatsd' command.

3. Enable the CPACF counters of interest. For example, enable all counters by issuing cpacfstats -e.

4. Run your applications.

5. Display counter values by using the cpacfstats command. Reset the cryptographic counters as required. To reset, use, for example, cpacfstats -r.

6. Disable all the CPACF measurements, for example, by using cpacfstats -d.

7. Shutdown the cpacfstatsd daemon by using 'systemctl stop cpacfstatsd'.

OPTIONS

Display help information for the command.
Display version and copyright information for the command.
Enable one or all CPACF performance counters. The optional counter argument can be one of: des, aes, sha, prng, ecc, or all. If the counter argument is omitted, all performance counters are enabled. Enabling a counter does not reset it. New events are added to the current counter value.
Disable one or all CPACF performance counters. The optional counter argument can be one of: des, aes, sha, prng, ecc, or all. If the counter argument is omitted, all performance counters are disabled. Disabling a counter does not reset it. The counter value is preserved when a counter is disabled, and counting will resume using the preserved value when the counter is re-enabled.
Reset one or all CPACF performance counters. The optional counter argument can be one of: des, aes, sha, prng, ecc, or all. If the counter argument is omitted, all performance counters are reset to 0.
Display the value of one or all CPACF performance counters. The optional counter argument can be one of: des, aes, sha, prng, ecc, pai_user, pai_kernel, or all. If the counter argument is omitted or if there is no argument, all performance counters are displayed. If the optional -n or --nonzero argument is given, then only PAI counters that have a non-zero value are printed.
Display all activated counters in JSON format. The JSON contains an array of counter objects. Each object contains the property counter specifying either a CPU-MF counter of one of the detailed PAI counter. Additional properties include error an error number if the counter could not be read, value the counter value if the counter could be read, space for PAI counters to specify user or kernel space counter set, and counterid for PAI counters to specify the PAI counter number as specified in the Principles of Operation.

FILES

/run/cpacfstatsd_socket

RETURN VALUE

0
Successful program execution.
1
An error occurred, reasons include: invalid argument, cpacfstatsd could not be reached (check that the daemon is running), insufficient access rights, version mismatch between client and daemon, or the application is out of memory. The application prints a message with the details of the error and the errno value.

NOTES

ECC counters are only available since z15. cpacfstats will show the counters as unsupported if the hardware does not support ECC counters.

APPENDIX

The detailed pai counter names are:

  • KM DES,
  • KM 2key TDES,
  • KM TDES,
  • KM DES protected key,
  • KM 2key TDES protected key,
  • KM TDES protected key,
  • KM AES 128bit,
  • KM AES 192bit,
  • KM AES 256bit,
  • KM AES 128bit protected key,
  • KM AES 192bit protected key,
  • KM AES 256bit protected key,
  • KM AES-XTS 128bit,
  • KM AES-XTS 256bit,
  • KM AES-XTS 128bit protected key,
  • KM AES-XTS 256bit protected key,
  • KMC DES,
  • KMC 2key TDES,
  • KMC TDES,
  • KMC DES protected key,
  • KMC 2key TDES protected key,
  • KMC TDES protected key,
  • KMC AES 128bit,
  • KMC AES 192bit,
  • KMC AES 256bit,
  • KMC AES 128bit protected key,
  • KMC AES 192bit protected key,
  • KMC AES 256bit protected key,
  • KMC PRNG,
  • KMA AES 128bit,
  • KMA AES 192bit,
  • KMA AES 256bit,
  • KMA AES 128bit protected key,
  • KMA AES 192bit protected key,
  • KMA AES 256bit protected key,
  • KMF DES,
  • KMF 2key TDES,
  • KMF TDES,
  • KMF DES protected key,
  • KMF 2key TDES protected key,
  • KMF TDES protected key,
  • KMF AES 128bit,
  • KMF AES 192bit,
  • KMF AES 256bit,
  • KMF AES 128bit protected key,
  • KMF AES 192bit protected key,
  • KMF AES 256bit protected key,
  • KMCTR DES,
  • KMCTR 2key TDES,
  • KMCTR TDES,
  • KMCTR DES protected key,
  • KMCTR 2key TDES protected key,
  • KMCTR TDES protected key,
  • KMCTR AES 128bit,
  • KMCTR AES 192bit,
  • KMCTR AES 256bit,
  • KMCTR AES 128bit protected key,
  • KMCTR AES 192bit protected key,
  • KMCTR AES 256bit protected key,
  • KMO DES,
  • KMO 2key TDES,
  • KMO TDES,
  • KMO DES protected key,
  • KMO 2key TDES protected key,
  • KMO TDES protected key,
  • KMO AES 128bit,
  • KMO AES 192bit,
  • KMO AES 256bit,
  • KMO AES 128bit protected key,
  • KMO AES 192bit protected key,
  • KMO AES 256bit protected key,
  • KIMD SHA1,
  • KIMD SHA256,
  • KIMD SHA512,
  • KIMD SHA3-224,
  • KIMD SHA3-256,
  • KIMD SHA3-384,
  • KIMD SHA3-512,
  • KIMD SHAKE 128,
  • KIMD SHAKE 256,
  • KIMD GHASH,
  • KLMD SHA1,
  • KLMD SHA256,
  • KLMD SHA512,
  • KLMD SHA3-224,
  • KLMD SHA3-256,
  • KLMD SHA3-384,
  • KLMD SHA3-512,
  • KLMD SHAKE 128,
  • KLMD SHAKE 256,
  • KMAC DES,
  • KMAC 2key TDES,
  • KMAC TDES,
  • KMAC DES protected key,
  • KMAC 2key TDES protected key,
  • KMAC TDES protected key,
  • KMAC AES 128bit,
  • KMAC AES 192bit,
  • KMAC AES 256bit,
  • KMAC AES 128bit protected key,
  • KMAC AES 192bit protected key,
  • KMAC AES 256bit protected key,
  • PCC Last Block CMAC DES,
  • PCC Last Block CMAC 2key TDES,
  • PCC Last Block CMAC TDES,
  • PCC Last Block CMAC DES protected key,
  • PCC Last Block CMAC 2key TDES protected key,
  • PCC Last Block CMAC TDES protected key,
  • PCC Last Block CMAC AES 128bit,
  • PCC Last Block CMAC AES 192bit,
  • PCC Last Block CMAC AES 256bit,
  • PCC Last Block CMAC AES 128bit protected key,
  • PCC Last Block CMAC AES 192bit protected key,
  • PCC Last Block CMAC AES 256bit protected key,
  • PCC XTS Parameter AES 128bit,
  • PCC XTS Parameter AES 256bit,
  • PCC XTS Parameter AES 128bit protected key,
  • PCC XTS Parameter AES 256bit protected key,
  • PCC Scalar Mult P256,
  • PCC Scalar Mult P384,
  • PCC Scalar Mult P521,
  • PCC Scalar Mult Ed25519,
  • PCC Scalar Mult Ed448,
  • PCC Scalar Mult X25519,
  • PCC Scalar Mult X448,
  • PRNO SHA512 DRNG,
  • PRNO TRNG Query Ratio,
  • PRNO TRNG,
  • KDSA ECDSA Verify P256,
  • KDSA ECDSA Verify P384,
  • KDSA ECDSA Verify P521,
  • KDSA ECDSA Sign P256,
  • KDSA ECDSA Sign P384,
  • KDSA ECDSA Sign P521,
  • KDSA ECDSA Sign P256 protected key,
  • KDSA ECDSA Sign P384 protected key,
  • KDSA ECDSA Sign P521 protected key,
  • KDSA EdDSA Verify Ed25519,
  • KDSA EdDSA Verify Ed448,
  • KDSA EdDSA Sign Ed25519,
  • KDSA EdDSA Sign Ed448,
  • KDSA EdDSA Sign Ed25519 protected key,
  • KDSA EdDSA Sign Ed448 protected key,
  • PCKMO DES,
  • PCKMO 2key TDES,
  • PCKMO TDES,
  • PCKMO AES 128bit,
  • PCKMO AES 192bit,
  • PCKMO AES 256bit,
  • PCKMO ECC P256,
  • PCKMO ECC P384,
  • PCKMO ECC P521,
  • PCKMO ECC Ed25519,
  • PCKMO ECC Ed448,
  • Reserved 1, and
  • Reserved 2.
  • KM AES-XTS (full) 128bit
  • KM AES-XTS (full) 256bit
  • KM AES-XTS (full) 128bit protected key
  • KM AES-XTS (full) 256bit protected key
  • KMAC HMAC SHA 224
  • KMAC HMAC SHA 256
  • KMAC HMAC SHA 384
  • KMAC HMAC SHA 512
  • KMAC HMAC SHA 224 protected key
  • KMAC HMAC SHA 256 protected key
  • KMAC HMAC SHA 384 protected key
  • KMAC HMAC SHA 512 protected key
  • PCKMO HMAC 512 protected key
  • PCKMO HMAC 1024 protected key
  • PCKMO AES-XTS 128bit double key protected key
  • PCKMO AES-XTS 256bit double key protected key

SEE ALSO

cpacfstatsd(8)

January 2015 s390-tools