ZCRYPTSTATS(1)

NAME
zcryptstats - Display usage statistics of IBM Crypto Express adapters

SYNOPSIS
zcryptstats [OPTIONS] [DEVICE_ID [...] ]

zcryptstats --help|-h
zcryptstats --version|-v

DESCRIPTION
Use zcryptstats to display usage statistics of IBM Crypto Express adapters.

zcryptstats obtains cryptographic performance measurement data periodically and displays the data for each cryptographic device for each interval. A cryptographic device can be either a card device or a queue device (APQN). zcryptstats runs forever unless you limit the number of intervals with the --count option. The default interval time is 10 seconds. Use the --interval option to specify a different interval time.

By default, all available cryptographic devices are monitored. You can optionally specify the device IDs of the devices to be monitored. The card device representation and the queue device are both in hexadecimal notation.

Use the --no-apqn option to omit the performance measurement data of the queues. If the system does not support obtaining cryptographic performance measurement data on the queue devices, only the card devices are monitored.

For each device, a set of counters is displayed. The amount and meaning of the counters are dependent on the device type and mode, see the COUNTERS section. For each counter and interval, the following values are displayed:

    •   Number of measured operations.

    •   Rate of the measured operation in operations per second.

    •   Utilization of the device in percent.

    •   Average duration of the operations.

The sum of all operations is displayed in a separate totals line. Use the --only-totals option to omit the individual counters and display the totals only. Use the --no-totals option to omit the totals.

Note: The utilization value of a counter can exceed 100%. This value is caused by the parallel execution of cryptographic operations.

Cryptographic performance measurement data might not be available when Linux is running as guest under z/VM or under KVM. zcryptstats then displays an error message and exits.

Note: zcryptstats utilizes the device node /dev/chsc. When this device node is not available, you might have to load kernel module chsc_sch using modprobe chsc_sch to make it available.

OPTIONS

DEVICE_ID
    Specifies a cryptographic device for which statistics are displayed. A device ID can either be a card device ID (<card-id>) or a queue device (APQN) ID (<card-id>.<domain-id>). To filter all devices by domain, provide .<domain-id>. If no IDs are given, statistics are displayed for all available devices.

-i, --interval INTERVAL
    Specifies the interval time in seconds. If this option is omitted, then the default interval time of 10 seconds is used.

-c, --count COUNT
    Specifies the number of reports that are generated at INTERVAL seconds apart. If this option is omitted, the zcryptstats command generates reports continuously, until it is stopped with control-C.

-o, --output JSON|TABLE|CSV
    Displays the statistics in the specified format. If this option is omitted, a comprehensive report is displayed. Supported output formats are:

    •   JSON: Displays the statistics in Javascript Object Notation (JSON) format. JSON output field order is undefined, and new fields might be added in the future.

    •   TABLE: Displays the statistics in a human readable simple table format. The individual counters are omitted, and only the totals are displayed. This output format implies option --only-totals.

    •   CSV: Displays the statistics in comma-separated values format. The values are separated with a semicolon. The individual counters are omitted, and only the totals are displayed. This output format implies option --only-totals.

-t, --no-totals
    Excludes the totals of all counters of a card device or queue device (APQN). This option cannot be specified together with option --only-totals or option --output TABLE|CSV.

-T, --only-totals
    Displays only the totals of all counters of a card device or a queue device (APQN), but not the individual counters. This option is implied with option --output TABLE|CSV.

-a, --no-apqn
    Displays only the counters of the card device, but omits the counters of the queue device (APQN). If the system does not support obtaining cryptographic performance measurement data on the queue devices, this option is implied.

-M, --map-type MAPPING
    Maps unknown cryptographic device types and modes to known types and modes. This option should only be used when new, so far unknown cryptographic devices are found. You can then map them to known devices and modes, provided that the new cryptographic devices report the same counters as the known cryptographic device to which it is mapped. The mapping specification consists of a comma-separated list of FROM-TYPE:FROM-MODE=TO-TYPE:TO-MODE specifications. The type and mode values must be specified in decimal notation.

-A, --all
    Displays all cards devices and queue devices (APQNs), not only those that are available to the Linux instance. Using this option additional cryptographic devices that are available in the CEC, but not available to the Linux system are also monitored. This option cannot be specified together with option --only-online.

-O, --only-online
    Displays only online cards devices and queue devices (APQNs). This option cannot be specified together with option --all.

-V, --verbose
    Displays additional information messages during processing.

-h, --help
    Displays help text and exits.

-v, --version
    Displays version information and exits.

COUNTERS

IBM Crypto Express adapter in accelerator mode:

    All All operations on the adapter

    RSA Key-gen
        RSA-key-generation operations (also included in All).

IBM Crypto Express adapter in CCA co-processor mode:

    RSA 1024 ME
        1024-bit ME-format RSA operations.

    RSA 2048 ME
        2048-bit ME-format RSA operations.

    RSA 1024 CRT
        1024-bit CRT-format RSA operations.

    RSA 2048 CRT
        2048-bit CRT-format RSA operations.

    RSA 4096 ME
        4096-bit ME-format RSA operations.

    RSA 4096 CTR
        4096-bit CRT-format RSA operations.

IBM Crypto Express adapter in EP11 co-processor mode:

    Asym. Slow
        Slow asymmetric-key functions.

    Asym. Fast
        Fast asymmetric-key functions.

    Symm. Partial
        Symmetric-key functions that return partial or incremental results.

    Symm. Complete
        Symmetric-key functions that return a complete or final result.

    Asym. Key-gen
        asymmetric-key generation function.

EXAMPLES

zcryptstats 02
    Display statistics for all cryptographic devices with card ID 02.

zcryptstats 02.0005 --interval 5
    Display statistics for cryptographic devices with card ID 02 and domain ID 0005 in a 5 second interval.

zcryptstats .0005 --count 10
    Display statistics for cryptographic devices with domain ID 0005 with the default interval time of 10 seconds, for 10 intervals.

zcryptstats 02 --output JSON
    Display statistics for all cryptographic devices with card ID 02 in JSON output format.