mirror of
https://github.com/ibm-s390-linux/s390-tools.git
synced 2026-08-05 02:14:52 +00:00
5b909a40cb
Introduce the new state 'unauthorized' to the three already existing states disabled, enabled, and unsupported to CPU-MF counters. CPU-MF counters are only available on LPARs. The intent is to differentiate whether a system simply does not support the CPU-MF counters like a z/VM guest or if they are supported like on LPAR but have to be authorized via HMC/SE. Signed-off-by: Finn Callies <fcallies@linux.ibm.com> Reviewed-by: Harald Freudenberger <freude@linux.ibm.com> [hoeppner@linux.ibm.com: Adapt commit message] Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>
540 lines
12 KiB
Groff
540 lines
12 KiB
Groff
.\" cpacfstats.1
|
|
.\"
|
|
.\" Copyright IBM Corp. 2015, 2022
|
|
.\" s390-tools is free software; you can redistribute it and/or modify
|
|
.\" it under the terms of the MIT license. See LICENSE for details.
|
|
.\"
|
|
.\" use
|
|
.\" groff -man -Tutf8 cpacfstats.1
|
|
.\" or
|
|
.\" nroff -man cpacfstats.1
|
|
.\" to process this source
|
|
.\"
|
|
.TH cpacfstats "1" "January 2015" "s390-tools"
|
|
.
|
|
.ds c \fcpacfstats\fP
|
|
.
|
|
.SH NAME
|
|
cpacfstats \- enable, disable and display CPACF statistical data
|
|
.
|
|
.SH SYNOPSIS
|
|
.B cpacfstats
|
|
.RB [ \-h | \-\-help ]
|
|
.RB [ \-v | \-\-version ]
|
|
.RB [ \-e | \-\-enable
|
|
.I counter
|
|
.RB ]
|
|
.RB [ \-d | \-\-disable
|
|
.I counter
|
|
.RB ]
|
|
.RB [ \-r | \-\-reset
|
|
.I counter
|
|
.RB ]
|
|
.RB [ \-p | \-\-print
|
|
.I counter
|
|
.RB [ \-n | \-\-nonzero]
|
|
.RB ]
|
|
.RB [ \-j | \-\-json ]
|
|
.
|
|
.SH 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
|
|
.B des,
|
|
.B aes,
|
|
.B sha,
|
|
.B rng,
|
|
and
|
|
.B 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
|
|
.B pai_user
|
|
and
|
|
.B 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 \fIcpacfstats\fR are allowed to run
|
|
the cpacfstats client application.
|
|
|
|
Example usage scenario:
|
|
.P
|
|
1. Start the cpacfstatsd daemon with root privileges using 'systemctl start
|
|
cpacfstatsd'.
|
|
.P
|
|
2. Check for successful startup by using the 'systemctl status cpacfstatsd'
|
|
command.
|
|
.P
|
|
3. Enable the CPACF counters of interest. For example, enable all counters
|
|
by issuing cpacfstats -e.
|
|
.P
|
|
4. Run your applications.
|
|
.P
|
|
5. Display counter values by using the cpacfstats command. Reset the
|
|
cryptographic counters as required. To reset, use, for example, cpacfstats
|
|
-r.
|
|
.P
|
|
6. Disable all the CPACF measurements, for example, by using cpacfstats
|
|
-d.
|
|
.P
|
|
7. Shutdown the cpacfstatsd daemon by using 'systemctl stop cpacfstatsd'.
|
|
|
|
.SH OPTIONS
|
|
.TP
|
|
\fB\-h\fR or \fB\-\-help\fR
|
|
Display help information for the command.
|
|
.TP
|
|
\fB\-v\fR or \fB\-\-version\fR
|
|
Display version and copyright information for the command.
|
|
.TP
|
|
\fB\-e\fR or \fB\-\-enable\fR [counter]
|
|
Enable one or all CPACF performance counters. The optional counter
|
|
argument can be one of: \fBdes\fR, \fBaes\fR, \fBsha\fR, \fBprng\fR,
|
|
\fBecc\fR, or \fBall\fR. 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.
|
|
.TP
|
|
\fB\-d\fR or \fB\-\-disable\fR [counter]
|
|
Disable one or all CPACF performance counters. The optional counter
|
|
argument can be one of: \fBdes\fR, \fBaes\fR, \fBsha\fR, \fBprng\fR,
|
|
\fBecc\fR, or \fBall\fR. 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.
|
|
.TP
|
|
\fB\-r\fR or \fB\-\-reset\fR [counter]
|
|
Reset one or all CPACF performance counters. The optional counter
|
|
argument can be one of: \fBdes\fR, \fBaes\fR, \fBsha\fR, \fBprng\fR,
|
|
\fBecc\fR, or \fBall\fR. If the counter argument is omitted, all
|
|
performance counters are reset to 0.
|
|
.TP
|
|
\fB\-p\fR or \fB\-\-print\fR [\fB\-n\fR or \fB\-\-nonzero\fR] [counter]
|
|
Display the value of one or all CPACF performance counters. The
|
|
optional counter argument can be one of: \fBdes\fR, \fBaes\fR,
|
|
\fBsha\fR, \fBprng\fR, \fBecc\fR, \fBpai_user\fR, \fBpai_kernel\fR, or
|
|
\fBall\fR. If the counter argument is omitted or if there is no
|
|
argument, all performance counters are displayed. If the optional
|
|
\fB\-n\fR or \fB\-\-nonzero\fR argument is given, then only PAI
|
|
counters that have a non-zero value are printed.
|
|
.TP
|
|
\fB\-j\fR or \fB\-\-json\fR
|
|
Display all activated counters in JSON format. The JSON contains an
|
|
array of counter objects. Each object contains the property
|
|
.B counter
|
|
specifying either a CPU-MF counter of one of the detailed PAI counter.
|
|
Additional properties include
|
|
.B error
|
|
an error number if the counter could not be read,
|
|
.B value
|
|
the counter value if the counter could be read,
|
|
.B space
|
|
for PAI counters to specify
|
|
.B user
|
|
or
|
|
.B kernel
|
|
space counter set, and
|
|
.B counterid
|
|
for PAI counters to specify the PAI counter number as specified in the
|
|
Principles of Operation.
|
|
.TP
|
|
The default command is --print all.
|
|
.
|
|
.SH FILES
|
|
.nf
|
|
/run/cpacfstatsd_socket
|
|
.fi
|
|
.
|
|
.SH RETURN VALUE
|
|
.IP 0
|
|
Successful program execution.
|
|
.IP 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.
|
|
.
|
|
.SH NOTES
|
|
ECC counters are only available since z15. cpacfstats will show the
|
|
counters as \fIunsupported\fR if the hardware does not support ECC
|
|
counters.
|
|
|
|
CPU-MF counters have to be authorized on HMC or SE to be available and are
|
|
otherwise shown as \fIunauthorized\fR. 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
|
|
\fICrypto activity counter set authorization control\fR checkbox.
|
|
.
|
|
.SH APPENDIX
|
|
The detailed pai counter names are:
|
|
.RS
|
|
.IP \(bu
|
|
KM DES,
|
|
.IP \(bu
|
|
KM 2key TDES,
|
|
.IP \(bu
|
|
KM TDES,
|
|
.IP \(bu
|
|
KM DES protected key,
|
|
.IP \(bu
|
|
KM 2key TDES protected key,
|
|
.IP \(bu
|
|
KM TDES protected key,
|
|
.IP \(bu
|
|
KM AES 128bit,
|
|
.IP \(bu
|
|
KM AES 192bit,
|
|
.IP \(bu
|
|
KM AES 256bit,
|
|
.IP \(bu
|
|
KM AES 128bit protected key,
|
|
.IP \(bu
|
|
KM AES 192bit protected key,
|
|
.IP \(bu
|
|
KM AES 256bit protected key,
|
|
.IP \(bu
|
|
KM AES-XTS 128bit,
|
|
.IP \(bu
|
|
KM AES-XTS 256bit,
|
|
.IP \(bu
|
|
KM AES-XTS 128bit protected key,
|
|
.IP \(bu
|
|
KM AES-XTS 256bit protected key,
|
|
.IP \(bu
|
|
KMC DES,
|
|
.IP \(bu
|
|
KMC 2key TDES,
|
|
.IP \(bu
|
|
KMC TDES,
|
|
.IP \(bu
|
|
KMC DES protected key,
|
|
.IP \(bu
|
|
KMC 2key TDES protected key,
|
|
.IP \(bu
|
|
KMC TDES protected key,
|
|
.IP \(bu
|
|
KMC AES 128bit,
|
|
.IP \(bu
|
|
KMC AES 192bit,
|
|
.IP \(bu
|
|
KMC AES 256bit,
|
|
.IP \(bu
|
|
KMC AES 128bit protected key,
|
|
.IP \(bu
|
|
KMC AES 192bit protected key,
|
|
.IP \(bu
|
|
KMC AES 256bit protected key,
|
|
.IP \(bu
|
|
KMC PRNG,
|
|
.IP \(bu
|
|
KMA AES 128bit,
|
|
.IP \(bu
|
|
KMA AES 192bit,
|
|
.IP \(bu
|
|
KMA AES 256bit,
|
|
.IP \(bu
|
|
KMA AES 128bit protected key,
|
|
.IP \(bu
|
|
KMA AES 192bit protected key,
|
|
.IP \(bu
|
|
KMA AES 256bit protected key,
|
|
.IP \(bu
|
|
KMF DES,
|
|
.IP \(bu
|
|
KMF 2key TDES,
|
|
.IP \(bu
|
|
KMF TDES,
|
|
.IP \(bu
|
|
KMF DES protected key,
|
|
.IP \(bu
|
|
KMF 2key TDES protected key,
|
|
.IP \(bu
|
|
KMF TDES protected key,
|
|
.IP \(bu
|
|
KMF AES 128bit,
|
|
.IP \(bu
|
|
KMF AES 192bit,
|
|
.IP \(bu
|
|
KMF AES 256bit,
|
|
.IP \(bu
|
|
KMF AES 128bit protected key,
|
|
.IP \(bu
|
|
KMF AES 192bit protected key,
|
|
.IP \(bu
|
|
KMF AES 256bit protected key,
|
|
.IP \(bu
|
|
KMCTR DES,
|
|
.IP \(bu
|
|
KMCTR 2key TDES,
|
|
.IP \(bu
|
|
KMCTR TDES,
|
|
.IP \(bu
|
|
KMCTR DES protected key,
|
|
.IP \(bu
|
|
KMCTR 2key TDES protected key,
|
|
.IP \(bu
|
|
KMCTR TDES protected key,
|
|
.IP \(bu
|
|
KMCTR AES 128bit,
|
|
.IP \(bu
|
|
KMCTR AES 192bit,
|
|
.IP \(bu
|
|
KMCTR AES 256bit,
|
|
.IP \(bu
|
|
KMCTR AES 128bit protected key,
|
|
.IP \(bu
|
|
KMCTR AES 192bit protected key,
|
|
.IP \(bu
|
|
KMCTR AES 256bit protected key,
|
|
.IP \(bu
|
|
KMO DES,
|
|
.IP \(bu
|
|
KMO 2key TDES,
|
|
.IP \(bu
|
|
KMO TDES,
|
|
.IP \(bu
|
|
KMO DES protected key,
|
|
.IP \(bu
|
|
KMO 2key TDES protected key,
|
|
.IP \(bu
|
|
KMO TDES protected key,
|
|
.IP \(bu
|
|
KMO AES 128bit,
|
|
.IP \(bu
|
|
KMO AES 192bit,
|
|
.IP \(bu
|
|
KMO AES 256bit,
|
|
.IP \(bu
|
|
KMO AES 128bit protected key,
|
|
.IP \(bu
|
|
KMO AES 192bit protected key,
|
|
.IP \(bu
|
|
KMO AES 256bit protected key,
|
|
.IP \(bu
|
|
KIMD SHA1,
|
|
.IP \(bu
|
|
KIMD SHA256,
|
|
.IP \(bu
|
|
KIMD SHA512,
|
|
.IP \(bu
|
|
KIMD SHA3-224,
|
|
.IP \(bu
|
|
KIMD SHA3-256,
|
|
.IP \(bu
|
|
KIMD SHA3-384,
|
|
.IP \(bu
|
|
KIMD SHA3-512,
|
|
.IP \(bu
|
|
KIMD SHAKE 128,
|
|
.IP \(bu
|
|
KIMD SHAKE 256,
|
|
.IP \(bu
|
|
KIMD GHASH,
|
|
.IP \(bu
|
|
KLMD SHA1,
|
|
.IP \(bu
|
|
KLMD SHA256,
|
|
.IP \(bu
|
|
KLMD SHA512,
|
|
.IP \(bu
|
|
KLMD SHA3-224,
|
|
.IP \(bu
|
|
KLMD SHA3-256,
|
|
.IP \(bu
|
|
KLMD SHA3-384,
|
|
.IP \(bu
|
|
KLMD SHA3-512,
|
|
.IP \(bu
|
|
KLMD SHAKE 128,
|
|
.IP \(bu
|
|
KLMD SHAKE 256,
|
|
.IP \(bu
|
|
KMAC DES,
|
|
.IP \(bu
|
|
KMAC 2key TDES,
|
|
.IP \(bu
|
|
KMAC TDES,
|
|
.IP \(bu
|
|
KMAC DES protected key,
|
|
.IP \(bu
|
|
KMAC 2key TDES protected key,
|
|
.IP \(bu
|
|
KMAC TDES protected key,
|
|
.IP \(bu
|
|
KMAC AES 128bit,
|
|
.IP \(bu
|
|
KMAC AES 192bit,
|
|
.IP \(bu
|
|
KMAC AES 256bit,
|
|
.IP \(bu
|
|
KMAC AES 128bit protected key,
|
|
.IP \(bu
|
|
KMAC AES 192bit protected key,
|
|
.IP \(bu
|
|
KMAC AES 256bit protected key,
|
|
.IP \(bu
|
|
PCC Last Block CMAC DES,
|
|
.IP \(bu
|
|
PCC Last Block CMAC 2key TDES,
|
|
.IP \(bu
|
|
PCC Last Block CMAC TDES,
|
|
.IP \(bu
|
|
PCC Last Block CMAC DES protected key,
|
|
.IP \(bu
|
|
PCC Last Block CMAC 2key TDES protected key,
|
|
.IP \(bu
|
|
PCC Last Block CMAC TDES protected key,
|
|
.IP \(bu
|
|
PCC Last Block CMAC AES 128bit,
|
|
.IP \(bu
|
|
PCC Last Block CMAC AES 192bit,
|
|
.IP \(bu
|
|
PCC Last Block CMAC AES 256bit,
|
|
.IP \(bu
|
|
PCC Last Block CMAC AES 128bit protected key,
|
|
.IP \(bu
|
|
PCC Last Block CMAC AES 192bit protected key,
|
|
.IP \(bu
|
|
PCC Last Block CMAC AES 256bit protected key,
|
|
.IP \(bu
|
|
PCC XTS Parameter AES 128bit,
|
|
.IP \(bu
|
|
PCC XTS Parameter AES 256bit,
|
|
.IP \(bu
|
|
PCC XTS Parameter AES 128bit protected key,
|
|
.IP \(bu
|
|
PCC XTS Parameter AES 256bit protected key,
|
|
.IP \(bu
|
|
PCC Scalar Mult P256,
|
|
.IP \(bu
|
|
PCC Scalar Mult P384,
|
|
.IP \(bu
|
|
PCC Scalar Mult P521,
|
|
.IP \(bu
|
|
PCC Scalar Mult Ed25519,
|
|
.IP \(bu
|
|
PCC Scalar Mult Ed448,
|
|
.IP \(bu
|
|
PCC Scalar Mult X25519,
|
|
.IP \(bu
|
|
PCC Scalar Mult X448,
|
|
.IP \(bu
|
|
PRNO SHA512 DRNG,
|
|
.IP \(bu
|
|
PRNO TRNG Query Ratio,
|
|
.IP \(bu
|
|
PRNO TRNG,
|
|
.IP \(bu
|
|
KDSA ECDSA Verify P256,
|
|
.IP \(bu
|
|
KDSA ECDSA Verify P384,
|
|
.IP \(bu
|
|
KDSA ECDSA Verify P521,
|
|
.IP \(bu
|
|
KDSA ECDSA Sign P256,
|
|
.IP \(bu
|
|
KDSA ECDSA Sign P384,
|
|
.IP \(bu
|
|
KDSA ECDSA Sign P521,
|
|
.IP \(bu
|
|
KDSA ECDSA Sign P256 protected key,
|
|
.IP \(bu
|
|
KDSA ECDSA Sign P384 protected key,
|
|
.IP \(bu
|
|
KDSA ECDSA Sign P521 protected key,
|
|
.IP \(bu
|
|
KDSA EdDSA Verify Ed25519,
|
|
.IP \(bu
|
|
KDSA EdDSA Verify Ed448,
|
|
.IP \(bu
|
|
KDSA EdDSA Sign Ed25519,
|
|
.IP \(bu
|
|
KDSA EdDSA Sign Ed448,
|
|
.IP \(bu
|
|
KDSA EdDSA Sign Ed25519 protected key,
|
|
.IP \(bu
|
|
KDSA EdDSA Sign Ed448 protected key,
|
|
.IP \(bu
|
|
PCKMO DES,
|
|
.IP \(bu
|
|
PCKMO 2key TDES,
|
|
.IP \(bu
|
|
PCKMO TDES,
|
|
.IP \(bu
|
|
PCKMO AES 128bit,
|
|
.IP \(bu
|
|
PCKMO AES 192bit,
|
|
.IP \(bu
|
|
PCKMO AES 256bit,
|
|
.IP \(bu
|
|
PCKMO ECC P256,
|
|
.IP \(bu
|
|
PCKMO ECC P384,
|
|
.IP \(bu
|
|
PCKMO ECC P521,
|
|
.IP \(bu
|
|
PCKMO ECC Ed25519,
|
|
.IP \(bu
|
|
PCKMO ECC Ed448,
|
|
.IP \(bu
|
|
Reserved 1, and
|
|
.IP \(bu
|
|
Reserved 2.
|
|
.IP \(bu
|
|
KM AES-XTS (full) 128bit
|
|
.IP \(bu
|
|
KM AES-XTS (full) 256bit
|
|
.IP \(bu
|
|
KM AES-XTS (full) 128bit protected key
|
|
.IP \(bu
|
|
KM AES-XTS (full) 256bit protected key
|
|
.IP \(bu
|
|
KMAC HMAC SHA 224
|
|
.IP \(bu
|
|
KMAC HMAC SHA 256
|
|
.IP \(bu
|
|
KMAC HMAC SHA 384
|
|
.IP \(bu
|
|
KMAC HMAC SHA 512
|
|
.IP \(bu
|
|
KMAC HMAC SHA 224 protected key
|
|
.IP \(bu
|
|
KMAC HMAC SHA 256 protected key
|
|
.IP \(bu
|
|
KMAC HMAC SHA 384 protected key
|
|
.IP \(bu
|
|
KMAC HMAC SHA 512 protected key
|
|
.IP \(bu
|
|
PCKMO HMAC 512 protected key
|
|
.IP \(bu
|
|
PCKMO HMAC 1024 protected key
|
|
.IP \(bu
|
|
PCKMO AES-XTS 128bit double key protected key
|
|
.IP \(bu
|
|
PCKMO AES-XTS 256bit double key protected key
|
|
.RE
|
|
.
|
|
.SH SEE ALSO
|
|
.BR cpacfstatsd (8)
|