lszdev(8)

📦 version 2.44.1, in opensuse-leap 16.0

💖 lszdev(8) 💖

okay so bestie, welcome to lszdev — that's the manual name, section 8, z Systems device tea ☕✨. Buckle up, because this page has a lot of options and we're getting through every single one of them. No skimming, no cap 🫶

✨ NAME ✨

lszdev — displays the configuration of z Systems specific devices 👑

🌸 SYNOPSIS 🌸

lszdev [ TYPE DEVICE SELECTION ACTIONS OPTIONS ]

💜 DESCRIPTION 💜

lszdev shows you the configuration of devices and device drivers that are specific to IBM z Systems. The device types it supports include storage devices (DASD and zFCP) and networking devices (QETH and CTC). Literally the whole z Systems device friend group 💅

lszdev can spit out output in either list format or detailed format. And if you don't specify any further options, it just defaults to list format. Low-effort queen behavior, we love her 🌈

🎀 Configurations 🎀

There are three sources for configuration information, bestie:

  • the active configuration of the currently running system
  • the persistent configuration stored in configuration files
  • the auto-configuration that some machine types provide to automatically enable I/O devices

Persistent configuration data comes in two different flavors: site-specific configuration and common-configuration. Common configuration means the persistent configuration that isn't bound to any site — and in many use cases, this configuration is being used as a fallback configuration. Check out the site section below to learn more about site-specific configuration 👀

By default, lszdev displays info from both the active and the persistent configuration, and — if it's available — from the auto-configuration too. She's thorough 💖

🦋 Output Format 🦋

In list format, lszdev uses values with the following meaning for the persistent columns (PERS):

  • yes — a persistent, non-site specific configuration exists; no site specific configurations available.
  • no — no persistent configurations is available.
  • auto — machine-provided auto-configuration is available.
  • s<n> — a site-specific configuration is available for site-id n.
  • s+ — site specific configurations are available for multiple sites.

💫 Example 💫

TYPE           ID                            ON   PERS NAMES
dasd-eckd      0.0.f001                      no   s+   dasda
dasd-eckd      0.0.f002                      no   s4   dasdb
dasd-eckd      0.0.f003                 no   no
qeth           0.0.1200:0.0.1201:0.0.1202    no   yes  encbdf0

🔥 TYPE 🔥

lszdev uses device type names to tell devices apart by their respective type. A device type usually corresponds to a device driver, though there are cases where multiple device types are provided for the same driver — for example, both device types "dasd-eckd" and "dasd-fba" are related to the DASD device driver. Siblings, basically 🙈

You can use the TYPE positional argument to restrict output to the specified device type:

  • Specify a device type and optionally a device ID to only display data for devices with matching type and ID
  • Specify a device type together with the --type option to display the configuration of the device type itself

To get a list of supported device types, use the --list-types action 👑

🌟 DEVICE 🌟

You can use the DEVICE positional argument to select a single device or a range of devices by device ID. To select a range, specify the ID of the first and the last device in the range separated by a hyphen (-). Multiple IDs or ranges? Just separate the ID specifications with a comma (,). Easy ✨

Example: lszdev dasd 1000,2000-2010

🧚 SELECTION 🧚

Besides picking devices by their ID, you can also select devices by their state or by the Linux functions they provide. So many ways to find your fave 💅

lszdev supports the following device states:

  • online — the device is enabled and set up to provide a Linux function such as a block device like /dev/dasda, or a networking interface like eth0.
  • offline — the device is not enabled.
  • existing — the device is present in the active configuration.
  • configured — there is a persistent configuration for this device.
  • failed — the driver of a device detected errors that may cause the device to not function properly.

Selection works in two stages, and yes, order matters 😭

  1. All devices specified by ID or by options --all, --by-interface, --by-node or --by-path are considered for selection.
  2. Of the considered devices, only those matching the specified state options --online, --offline, --existing, --configured and --failed are selected.

💅 Selection options 💅

  • --all — select all existing and configured devices. This is the default when no other options are specified. (Main character default energy 👑)
  • --by-attrib KEY=VALUE / --by-attrib KEY!=VALUE — select devices with the specified attribute value. When specified as KEY=VALUE, selects all devices that provide an attribute named KEY with a value of VALUE. When specified as KEY!=VALUE, selects all devices that don't provide an attribute named KEY with a value of VALUE. Equality check with extra steps, we stan 🎀
  • --by-interface NAME — select the device providing a network interface, e.g. eth0. The NAME parameter must be the name of an existing networking interface.
  • --by-node NODE — select the device providing a device node, e.g. /dev/sda. The NODE parameter must be the path to a block device or character device special file.
Note: if NODE is the device node for a logical device (such as a device mapper device), lszdev will try to resolve the corresponding physical device nodes. The lsblk(8) tool must be available for this resolution to work. 🫶
  • --by-path PATH — select the device providing a file system path, e.g. /usr. The PATH parameter can be the mount point of a mounted file system, or a path on that file system.
Note: if the file system that provides PATH is stored on multiple physical devices or on a subvolume (such as supported by btrfs), lszdev will try to resolve the corresponding physical device nodes. The lsblk(8) and findmnt(8) tools must be available, and in the case of multiple physical devices the file system must provide a valid UUID for this resolution to work. 😭 So many requirements, but she delivers.
  • --configured — select all devices for which a persistent configuration exists.
  • --existing — select all devices that are present in the active configuration.
  • --online — select devices that are online. An online device is a device in the active configuration that is set up to provide its associated Linux function (such as a block device or networking interface). She's up, she's functioning, she's booked and busy ✨
  • --offline — select devices that are offline. An offline device is a device in the active configuration that is not set up to provide its associated Linux function. Resting, not cancelled 💤
  • --failed — select devices for which errors were detected. A failed device is a device for which its driver detected an error condition that may cause the device to not correctly perform its function. You can use the --info option of the lszdev tool to get more details on the detected errors. Example: lszdev --failed --info 💀
  • --ipldev — select IPL device. Selects the device used for the most recent IPL operation. The chosen one 👑

👑 ACTIONS 👑

  • -h, --help — print usage information, then exit.
  • -i, --info — display detailed information. Displays detailed information about the configuration of the selected device or device type. Specifying --info twice will display additional device information. Double it and give it to the next person 🙈
  • -l, --list-columns — list available output columns. Lists all available columns for use with option --columns.
  • -L, --list-types — list supported device types. Lists the name and a short description for all device types supported by lszdev.
  • -v, --version — print version information, then exit.

🐚 to be continued, bestie — part 2 is coming 🐚

✨ OPTIONS ✨

Okay bestie, this is the options menu — every flag is here, no skips, no “oops I forgot one” energy. 💅

  • -a, --active — List info from the active configuration only. This restricts output to stuff from the active configuration, meaning info from the running system. 🫶
  • --auto-conf — List info from the auto-configuration only. This restricts output to the auto-configuration, aka the collection of configuration data that some machine models grab automatically during boot. 🌈
Note: this data gets refreshed during each boot. Also, configuration directives in the auto-configuration only take effect if there’s no directive for the same device in the persistent configuration. ⭐
  • --base PATH|KEY=VALUE — Change the file system paths used to access files. If you give PATH without an equal sign (=), it becomes the base path for accessing files in both the active and persistent configuration. If the parameter is in KEY=VALUE format, only those paths that begin with KEY get modified — for those paths, the initial KEY portion is replaced with VALUE. 🎀

Example: lszdev --persistent --base /etc=/mnt/etc

  • -c COLUMNS, --columns COLUMNS — Specify a comma-separated list of columns to display. You can change the columns shown in list output format by giving column names as a comma-separated list via --columns. Note that --columns cannot be specified together with --info. 💖

Example: lszdev --columns TYPE,ID

To get a list of supported column names, use the --list-columns action.

  • -n, --no-headings — Do not print column headings. When displaying output in list format, this option suppresses the output of a heading row. 🙈
  • --pairs — Produce output in KEY="VALUE" format. Use this to generate output that’s more suitable for processing by other programs. In this format, column values are prefixed with the name of the corresponding column. Values are enclosed in double quotation marks. Any quotation marks or slashes in the value string are escaped by placing a slash in front of it. 🔥
  • --shell — Produces KEY="VALUE" format usable as shell variables. You can use this together with the --pairs option to generate output suitable to be sourced in a shell environment. It generates similar output to --pairs, but it takes care of replacing any character of a column name that wouldn’t be appropriate as part of a shell variable name with an underscore. 🐚
  • -p, --persistent — List info from the persistent configuration only. This restricts output to info obtained from configuration files. 🎀
  • -q, --quiet — Print only minimal run-time information. 🤫
  • -s SITE-ID, --site SITE-ID — List the persistent configuration from the specified site only. The resulting persistent configuration details get filtered based on the SITE-ID value. Site-specific info can be found in a basic lszdev output. For example, the PERS column may show "s+", which indicates that the device has multiple configurations for multiple sites, and "sn" where n is a number between 0 to 9, which indicates that the persistent configuration for the device is available only for site n. 🌸

Example:

lszdev --site 3
lszdev -i --site 2
lszdev f001 --site 9
  • -t, --type — List info about device type. Use this option to display configuration information of a device type instead of a device. 👑
  • -V, --verbose — Print additional run-time information. 🔊

🌸 EXAMPLES 🌸

  • Display a list of all devices:
lszdev
  • Return type and ID of root device in machine-readable format:
lszdev --columns TYPE,ID --by-path /
  • Display DASD driver settings:
lszdev --type dasd
  • Display cryptographic (AP) adapter and domain assignments:
lszdev --type ap

🎀 EXIT CODES 🎀

lszdev returns a subset of the exit codes returned by the chzdev tool. See chzdev(8) for the detailed list. 😭

🦋 FILES 🦋

  • /etc/udev/rules.d/ — lszdev reads udev rules representing the persistent configuration of devices from this directory. File names start with "41-". 💖
  • /etc/modprobe.d/ — chzdev reads modprobe configuration files representing the persistent configuration of certain device types from this directory. File names start with "s390x-". ✨

💜 SEE ALSO 💜

💖 That’s the whole page, bestie! This one comes from s390-tools, dated Jan 2016, and it’s the lszdev(8) manual. Periodt. 💅✨

📦 where this page comes from