cpacfstats - Monitor CPACF cryptographic activity

6.10 LPAR mode

Use the cpacfstats command to display the number of cryptographic operations that are performed by the Central Processor Assist for Cryptographic Function (CPACF). CPACF counters are available for the CPU Measurement Facility (CPU-MF) and, as of IBM z16, Processor Activity Instrumentation (PAI).

CPU-MF

Available on LPARs only. The cpacfstats command shows CPU-MF counters as "unavailable" on z/VM® or KVM.

CPU-MF distinguishes functional grouping of counters. You can display and enable, disable, or reset specific hardware counters for AES, DES, ECC, SHA, and pseudo-random functions.

All counters are initially disabled and must be enabled in the LPAR activation profile on the SE or HMC to measure CPACF activities. The cpacfstats command prints a message: CPU-MF counters not authorized into the system log if the counters are not authorized on the HMC or SE.

There is a slight performance penalty with CPACF counters enabled.

PAI

Available on LPARs, z/VM and KVM as of IBM® z16™ and IBM LinuxONE Emperor 4.

PAI distinguishes kernel and user space counters. You can activate user space counters, kernel space counters, or both. The names of the counters is shown in the command output. There is a performance penalty with PAI counters enabled.

The cpacfstats command detects CPU hotplug events and displays a warning if an event is detected.

Prerequisites

The kernel must be built with the kernel configuration option CONFIG_PERF_EVENTS.
To activate CPU-MF counters: On the HMC or SE, authorize the LPAR for each counter set you want to use. Customize the LPAR activation profile and modify the Counter Facility Security Options. You need to activate the "Crypto activity counter set authorization control" checkbox
The cpacfstatsd daemon must be running. Check the syslog for the message:cpacfstatsd: Running. To start the daemon, issue:
```
# cpacfstatsd
```
The daemon requires root privileges to open and work with the perf kernel API functions. Issue man cpacfstatsd for more information about the daemon.

Note: The counter value is increased once per API call and also for every additional 4096 bytes of data.

Setting up the cpacfstats group

Only root and members of the group cpacfstats are allowed to communicate with the daemon process. You must create the group and add users to it.

Create the group cpacfstats:
```
# groupadd cpacfstats
```
Add all users who are allowed to run the cpacfstats client application to the group:
```
# usermod -a -G cpacfstats <user>
```

All users in the cpacfstats group are also able to modify the CPACF counter states (enable, disable, reset).

cpacfstats syntax

Where:

-e or --enable <counter>

enables one or all CPACF performance counters. You can enable CPU-MF, PAI, or all counters.

CPU-MF counter can be one of:

des: counts all DES- and 3DES-related cipher message CPACF instructions.
aes: counts all AES-related cipher message CPACF instructions.
sha: counts all message digest (that is, SHA-1 through SHA-512) related CPACF instructions.
rng: counts all pseudo-random related CPACF instructions.

PAI counters can be one of:

pai_kernel: counts all cryptographic PAI counters in kernel space. For a full list of counters, see the man page.
pai_user: counts all cryptographic PAI counters in user space. For a full list of counters, see the man page.

If you omit the counter, all performance counters are enabled. Enabling a counter does not reset it. New events are added to the current counter value.

-n or --non-zero

prints only PAI counters with non-zero values.

-d or --disable <counter>

disables one or all CPACF performance counters. If you omit the counter, all performance counters are disabled. Disabling a counter does not reset it. The counter value is preserved when a counter is disabled, and counting resumes with the preserved value when the counter is re-enabled.

-r or --reset <counter>

resets one or all CPACF performance counters. If you omit the counter, all performance counters are reset to 0.

-p or --print <counter>

displays the value of one or all CPACF performance counters. If you omit the counter, all performance counters are displayed.

-j or --json

displays all activated counters in JSON format. The JSON contains an array of counter objects. Each object contains the property counter that specifies either a CPU-MF counter or a 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: specifies whether the user or kernel space counter set is used
counterid: specifies the PAI counter number as given in the Principles of Operation.

Tip: Pipe the JSON output through jq -r . to obtain a human-readable version.

-h or --help

displays help information for the command. To view the command man page, enter man cpacfstats.

-v or --version

displays version information for cpacfstats.

The default command is --print all.

Examples

To print status and values of all CPACF performance counters:

# cpacfstats 
 des counter: disabled
 aes counter: disabled
 sha counter: disabled
 rng counter: disabled
 ecc counter: disabled
 pai user   : disabled
 pai kernel : disabled

To enable the AES CPACF performance counter:
```
# cpacfstats --enable aes
 aes counter: 0
```
To enable all performance counters and pipe the output to /dev/null to suppress a long list of counters:
```
# cpacfstats -e > /dev/null
```
For the already enabled AES counter, the value is not reset.

To enable all performance counters and suppress all PAI counters with the value zero:

# cpacfstats -e -n
 des counter: 0
 aes counter: 382
 sha counter: 0
 rng counter: 0
 ecc counter: 0
 pai_user   : enabled
  KMA AES 256bit                               : 618
 pai_kernel : enabled
  PRNO TRNG                                    : 6

To display all performance counters, but suppressing the zero value PAI counters:

# cpacfstats -n
 des counter: 0
 aes counter: 1
 sha counter: 0
 rng counter: 0
 ecc counter: 0
 pai user  : enabled
  KM AES 128bit                               : 1
 pai kernel: disabled

The example shows that only the KM AES 128-bit counter is used in user space.

If a hotplug event is detected, cpacfstats displays a message:

# cpacfstats -n pai_user
 pai_user   : enabled
  KMA AES 256bit                              : 170
 hotplug detected

As a new CPU came online and cpacfstats needs some time to activate counters on the new CPU, the counters might now show the wrong values. To ensure that you have the correct counter values, reset all counters and start over:

# cpacfstats -d 
  des counter: disabled
  aes counter: disabled
  sha counter: disabled
  rng counter: disabled
  ecc counter: disabled
  pai_user   : disabled
  pai_kernel : disabled
# cpacfstats -e pai_user -n
  pai_user   : enabled
   KMA AES 256bit                             : 215