cpacfstats(1)

📦 version 2.44.1, in opensuse-leap 16.0

💅 cpacfstats — the cpacfstats(1) page, but make it make sense ✨

okay bestie, buckle up — this is the cpacfstats command from the General Commands Manual, and it's lowkey one of those tools that sounds scary but is actually just a little messenger girl running errands for a daemon. let's get into it 🫶

✨ NAME ✨

cpacfstats — enable, disable and display CPACF statistical data. that's the whole job. she enables, she disables, she displays. iconic behavior only 👑

🌸 SYNOPSIS 🌸

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

like, yes, the bracket nesting is giving slightly unhinged, but she's valid 💅

🦋 DESCRIPTION 🦋

so the cpacfstats client application is basically the bestie who talks to the cpacfstatsd daemon and makes things happen. that's the whole dynamic — client asks, daemon does. together they enable, disable, reset, and fetch one or all of the mainframe CPACF performance counters. teamwork, fr fr 🤝

here's the thing though: all counters are initially disabled and you literally have to switch them on yourself to measure CPACF activities of the system. nothing is happening until you say so, no cap. also be aware there's a slight performance penalty with CPACF counters enabled — so, like, she's not free, but she's worth it 🌈

CPACF activity counters come in two flavors, and yes this is the moment to pay attention:

  • CPU-MF — these 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. very much giving independent women 💅
  • PAI — a lot more detailed, like so much more detailed. the user interface only offers the counters pai_user and pai_kernel to count CPACF usage in user-space or kernel-space. but when you print these counters, the detailed counters are shown. surprise! there's lore 😭

a complete list of counters can be found at the end of this manpage — so if you're looking for the full roster, keep reading bestie, it's coming 📜

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. so if something failed, she's not counting it — she's not messy like that 🙈

Note: CPU-MF based CPACF performance counters are available on LPARs only. PAI counters are available on all hypervisors. and for security reasons only members of the group cpacfstats are allowed to run the cpacfstats client application. so, like, permissions check before you vibe check 🔐

💖 example usage scenario 💖

this is the part where I hold your hand through the whole thing. follow along:

  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.

see? not scary. it's literally start, check, enable, run, print, reset, disable, stop. a whole little routine, main character energy from start to finish ⭐

💅 OPTIONS 💅

okay this is the part everyone scrolls to. here's every single flag, no skips, no cuts 🎀

  • -h or --help — Display help information for the command. like a lil "what does this do again" button 🫶
  • -v or --version — Display version and copyright information for the command. proof she's real and legally distinct ✨
  • -e or --enable [counter] — 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. so she picks up where she left off, no dramatic restart 💖
  • -d or --disable [counter] — 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. she remembers everything, she's not the type to forget 🔥
  • -r or --reset [counter] — 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. clean slate, fresh start, new era 🧚
  • -p or --print [-n or --nonzero] [counter] — 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. filtering out the zeros because we simply don't have time for empty results 💀
  • -j or --json — 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. machine-readable, structured, immaculate 🌸
and the default command? it's --print all. so if you just type the command with nothing else, that's what you get. she's generous like that 👑

🍓 FILES 🍓

  • /run/cpacfstatsd_socket

that's the one and only file she cares about. the socket. the connection. the link between client and daemon 🦋

🔥 RETURN VALUE 🔥

  • 0 — Successful program execution. we love a win 💖
  • 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. so if you see this, she'll tell you exactly what went wrong, she's not leaving you guessing 😭

🌈 NOTES 🌈

okay little PSA section, listen up:

ECC counters are only available since z15. cpacfstats will show the counters as unsupported if the hardware does not support ECC counters. so like, don't come for her, it's a hardware thing 💀

CPU-MF counters have to be authorized on HMC or SE to be available and are otherwise shown as unauthorized. 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. yes, that's a lot of checkboxes. yes, you have to do all of them. administrative slay, unfortunately 🎀

and that's part 1 bestie — the full counter list is still up next 👀

💅 APPENDIX 💅

ok so this is the part everyone scrolls past and then immediately scrolls back to, because — bestie — the detailed pai counter names are a whole journey. it's giving phone book. it's giving "the group chat has 172 members and you know three of them." but we do not skip entries on this page, so here is every single one, in order, no cap. 🫶

  • 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.

and then — because the list literally said "hold my iced coffee" — it keeps going. yes there's more, and yes you're gonna read all of it, because we don't gatekeep counters here 😭✨

  • 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

like... the way that last stretch is basically all PCKMO and protected key — she's consistent, she's committed, she ate and left no crumbs 💅

🌈 SEE ALSO 🌈

  • cpacfstatsd(8) — your next stop, bestie. go read it, you're gonna want the whole picture 🦋

and that's a wrap on cpacfstats(1), babes 💖 this little beauty comes to you from s390-tools, dated January 2015 — vintage, but absolutely still serving 👑 now go check your counters, you icon. 🎀✨

📦 where this page comes from