chzdev - Configure IBM Z devices

LPAR mode z/VM guest KVM guest

Use the chzdev command to configure devices and device drivers on IBM Z®. Supported devices include storage devices (DASD and zFCP) and networking devices (QETH and LCS).

You can apply configuration changes to the active configuration of the currently running system, or to the persistent configuration stored in configuration files:

Changes to the active configuration are effective immediately. They are lost on reboot, when a device driver is unloaded, or when a device becomes unavailable.
Changes to the persistent configuration are applied when the system boots, when a device driver is loaded, or when a device becomes available.

By default, chzdev applies changes to both the active and the persistent configuration.

You can also temporarily remove existing auto-configuration data, see Managing auto-configuration data.

chzdev supports enabling and disabling devices, exporting and importing configuration data to and from a file, and displaying a list of available device types and attributes.

Figure 1. chzdev actions and options

Notes:

¹ This option is intended for utilities that run early in the boot process.

Device selection

Device type selection

Attribute settings

Notes:

¹ Specify at least one of the options

Figure 2. chzdev help functions

where:

<type>

restricts the scope of an action to the specified device type:

Specify a device type and optionally a device ID to work on devices with matching type and ID only.
Specify a device type together with the --type option to manage the configuration of the device type itself.

Note:

As a precaution, use the most specific device type when you configure a device by ID. Otherwise, the same device ID might accidentally match other devices of a different subtype. To get a list of supported device types, use the --list-types option.

<device>

selects a single device or a range of devices by device ID. Separate multiple IDs or ranges with a comma (,). To select a range of devices, specify the ID of the first and the last device in the range separated by a hyphen (-).

-t <device_type> or --type <device_type>

selects a device type as target for a configuration or query action. For example: dasd-eckd, zfcp, or qeth.

<attribute=value>

specifies a device attribute and its value. To specify multiple attributes, separate attribute-value pairs with a blank.

You can use the --list-attributes option to display a list of available attributes and the --help-attribute to get more detailed information about a specific attribute.

Tip: To specify an attribute that is not known to chzdev, use the --force option.

-r <attrib> or --remove <attrib>

removes the setting for attribute <attrib>.

Active configuration: For attributes that maintain a list of values, clears all values for that list.
Persistent configuration: Removes any setting for the specified attribute. When the device or device driver is configured again, the attribute is set to its default value.

Some attributes cannot be removed.

-R or --remove-all

removes the settings for all attributes of the selected device or device driver.

Active configuration: For attributes that maintain a list of values, clears all values for that list.
Persistent configuration: Removes all attribute settings that can be removed. When the device or device driver is configured again, the attribute is set to its default value.

Some attributes cannot be removed.

--by-attrib <attrib=value> | <attrib!=value>

selects devices with a specific attribute, <attrib> that has a value of <value>. When specified as <attrib>!=<value>, selects all devices that do not provide an attribute named <attrib> with a value of <value>.

Tip: You can use the --list-attributes option to display a list of available attributes and the --help-attribute to get more detailed information about a specific attribute.

--by-interface <interface>

selects devices by network interface, for example, encf500. <interface> must be the name of an existing networking interface.

--by-node <device_node>

selects devices by device node, for example, /dev/sda. <device_node> must be the path to the device node for a block device or character device.

Note: If <device_node> is the device node for a logical device (such as a device mapper device), lszdev tries to resolve the corresponding physical device nodes. The lsblk tool must be available for this resolution to work.

--by-path <path>

selects devices by file-system path, for example, /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 (such as supported by btrfs), lszdev tries to resolve the corresponding physical device nodes. The lsblk tool must be available and the file system must provide a valid UUID for this resolution to work.

--all

selects all existing and configured devices.

--configured

narrows the selection to those devices for which a persistent configuration exists.

--existing

narrows the selection to all devices that are present in the active configuration.

--configured --existing

specifying both --configured and --existing narrows the selection to devices that are present in both configurations, persistent and active.

--online

narrows the selection to devices that are enabled in the active configuration.

--offline

narrows the selection to devices that are disabled in the active configuration.

-a or --active

applies changes to the active configuration only. The persistent configuration is not changed unless you also specify --persistent.

Note: Changes to the active configuration are effective immediately. They are lost on reboot, when a device driver is unloaded, or when a device becomes unavailable.

-p or --persistent

applies changes to the persistent configuration only. The persistent configuration takes effect when the system boots, when a device driver is loaded, or when a device becomes available.

--auto-config

applies changes to the auto-configuration. Changes to the auto-configuration take effect when a device becomes available, but do not persist across reboots. This option is primarily intended for use by the boot process. For details about auto-configuration data, see Device auto-configuration for Linux in LPAR mode.

--export <filename>|-

writes configuration data to a text file called <filename>. If a single hyphen (-) is specified instead of a file name, data is written to the standard output stream. The output format of this option can be used with the --import option. To reduce the scope of exported configuration data, you can select specific devices, a device type, or define whether to export only data for the active or persistent configuration.

--import <filename>|-

reads configuration data from <filename> and applies it. If a single hyphen (-) is specified instead of a file name, data is read from the standard input stream. The input format must be the same as the format produced by the --export option.

By default, all configuration data that is read is also applied. To reduce the scope of imported configuration data, you can select specific devices, a device type, or define whether to import only data for the active or persistent configuration.

-a or --apply

applies the persistent configuration of all selected devices and device types to the active configuration.

-e or --enable

enables the selected devices. Any steps necessary for the devices to function are taken, for example: create a CCW group device, remove a device from the CIO exclusion list, or set a CCW device online.

Active configuration: Performs all setup steps required for a device to become operational, for example, as a block device or as a network interface.
Persistent configuration: Creates configuration files and settings associated with the selected devices.

-d or --disable

disables the selected devices.

Active configuration: Disables the selected devices by reverting the configuration steps necessary to enable them.
Persistent configuration: Removes configuration files and settings associated with the selected devices.

--dry-run

processes the actions and displays command output without changing the configuration of any devices or device types. Combine with --verbose to display details about skipped configuration steps.

--base <path> | <key=value>

changes file system paths that are used to access files. If <path> is specified without an equal sign (=), it is used as base path for accessing files in the active and persistent configuration. If the specified parameter is in <key=value> format, only those paths that begin with <key> are modified. For these paths, the initial <key> portion is replaced with <value>.

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

-f or --force

overrides safety checks and confirmation questions, including:

More than 256 devices selected
Configuring unknown attributes
Combining apparently inconsistent settings

--no-root-update

skips any additional steps that are required to change the root device configuration persistently. Typically such steps include rebuilding the initial RAM disk, or modifying the kernel command line.

-y or --yes

answers all confirmation questions with yes.

-q or --quiet

prints only minimal run-time information.

-l or --list-attributes

lists all supported device or device type attributes, including a short description. Use the --help-attribute option to get more detailed information about an attribute.

-L or --list-types

lists the name and a short description for all device types supported by chzdev.

--no-settle

continue without waiting for udev processing to complete. This option is intended for utilities that run during the early initial RAM disc stage of the boot process, when udev is not fully functional.

-V or --verbose

prints additional run-time information.

-v or --version

displays the version number of chzdev, then exits.

-h or --help

displays help information for the command.

-H or --help-attribute

displays help information for the command.

Examples

To enable an FCP device with device number 0.0.198d, WWPN 0x50050763070bc5e3, and LUN 0x4006404600000000, and create a persistent configuration, issue:
```
# chzdev --enable zfcp-lun 0.0.198d:0x50050763070bc5e3:0x4006404600000000
```

To enable the same FCP device without creating a persistent configuration, issue:

# chzdev --enable --active zfcp-lun 0.0.198d:0x50050763070bc5e3:0x4006404600000000

To export configuration data for all FCP devices to a file called config.txt, issue:
```
# chzdev zfcp-lun --all --export config.txt
```
To enable a QETH device and create a persistent configuration, issue:
```
# chzdev --enable qeth 0.0.a000:0.0.a001:0.0.a002
```
To enable a QETH device without creating a persistent configuration, issue:
```
# chzdev --enable --active qeth 0.0.a000:0.0.a001:0.0.a002
```
To enable a device that provides networking interface encf500, issue:
```
# chzdev --by-interface encf500 --active
```
To get help for the QETH-device attribute layer2, issue:
```
# chzdev qeth --help-attribute layer2
```
To enable DASD 0.0.8000 and create a persistent configuration, issue:
```
# chzdev -e dasd 8000
```
To enable DASDs 0.0.1000 and 0.0.2000 through 0.0.2010, issue:
```
# chzdev dasd 1000,200-2010 -e 
```
To change the dasd device type parameter eer_pages to 14, issue:
```
# chzdev dasd --type eer_pages=14
```
To remove the persistent use_diag setting of DASD 0.0.8000, issue:
```
# chzdev dasd 8000 --remove use_diag --persistent
```
To persistently configure the root device, issue:
```
# chzdev --by-path / --persistent
```

See the man page for information about the command exit codes.

Activating a device early during the boot process

Use the zdev:early device attribute to activate a device early during the boot process and to override any existing auto-configuration with a persistent device configuration.

zdev:early=1: The device is activated during the initial RAM disc phase according to the persistent configuration.
zdev:early=0: The device is activated as usual during the boot process. This is the default. If auto-configuration data is present, the device is activated during the initial RAM disc phase according to the auto-configuration.

Example: To assure that the qeth device with bus-ID 0.0.f5f0 is enabled early in the boot process in layer 2 mode, issue:

# chzdev -e qeth 0.0.f5f0:0.0.f5f1:0.0.f5f2 layer2=1 zdev:early=1

Files used

The chzdev command uses these files:

/etc/udev/rules.d/: chzdev creates udev rules to store the persistent configuration of devices. File names start with 41-.
/etc/modprobe.d/: chzdev creates modprobe configuration files to store the persistent configuration of certain device types. File names start with s390x-.
/run: holds udev rules that represent auto-configuration data. chzdev can remove entries so the auto-configuration settings do not apply as devices appear on the running Linux instance.