chzdev(8)

NAME
chzdev - Configure z Systems specific devices

SYNOPSIS
chzdev TYPE DEVICE [ SELECTION SETTINGS ACTIONS OPTIONS ]

DESCRIPTION
chzdev is a tool for configuring devices and device drivers which are specific to the IBM z Systems platform. Supported device types include storage devices (DASD and zFCP) and networking devices (QETH, CTC and LCS).

  Configurations
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, or when a device becomes unavailable, or when a device driver is unloaded.

•   Changes to the persistent configuration are applied when the system boots, or when a device becomes available, or when a device driver is loaded.

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

  Site-specific configurations
In some high-availability setups, root and boot disks of a Linux installation are copied to remote sites that can take over execution of a Linux workload in case of an outage of the original site. A site in this context is an execution environment such as an LPAR or z/VM guest. Each site may provide a different set of devices, or require different parameters to be applied per device. chzdev supports site-specific device configuration for up to 10 sites. Each site is identified by a number in the range 0 to 9. You can provide a separate set of persistent device configuration for each site. The IPL Load Parameter value specified during boot determines the currently active site. Only the device configuration of the active site is applied during boot and when new devices become available. A common configuration can be provided that is applied when no site-specific configuration is available for a device in the active site. You can use the --site parameter to configure devices for a specific site only. Configuration actions without a site parameter apply to the common configuration. Linux supports the following IPL Load Parameter values for selecting the active site: S<n>
  Site with number <n> becomes the active site. Example: "S2" specifies site 2 as active site. SS
  The Subchannel-Set ID (SSID) of the IPL device specifies the number of the active site. If no site is specified in the Load Parameter, only the common configuration is applied.

  Tool actions
chzdev supports multiple tool actions such as

•   Enable a device.

•   Disable a device.

•   Export and import configuration data to and from a file.

•   Display a list of available device types and attributes.

You can trigger these actions by specifying one of the command line options listed in the ACTIONS section.

TYPE
chzdev uses device type names to distinguish devices by their respective type. A device type typically 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).

You can use the TYPE positional argument of the chzdev tool to restrict the scope of a tool action to the specified device type:

•   Specify a device type and optionally a device ID to only work on devices with matching type and ID

•   Specify a device type together with option --type to manage the configuration of the device type itself

Note: Specify the full device type when configuring a device by ID. Otherwise the same device ID might accidentally match other devices of a different type.

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

DEVICE
Use the DEVICE positional argument of chzdev to select a single device or a range of devices by device ID as target for a tool action. To select a range of devices, specify the ID of the first and the last device in the range separated by a hyphen (-). Separate multiple IDs or ranges with a comma (,).

Example:

SELECTION
In addition to specifying devices by their ID you can also select devices by their state or by the Linux functions they provide.

chzdev supports the following device states:

online
    The device is enabled in the active configuration 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 in the active configuration.

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:

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
Select all existing and configured devices.

Select devices with 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.

Select device providing network interface, e.g. eth0. The NAME parameter must be the name of an existing networking interface.

Select device providing 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), chzdev will try to resolve the corresponding physical device nodes. The tool must be available for this resolution to work.

Select device providing 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) chzdev will try to resolve the corresponding physical device nodes. The and 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.

Select all devices for which a persistent configuration exists.

Select all devices that are present in the active configuration.

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

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.

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:

SETTINGS
A setting is a positional argument of chzdev in the form KEY=VALUE. It can be used to configure a specific named attribute (KEY) of a device or device type with the provided VALUE.

Example:

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

  Special settings
The following special settings affect how devices are handled by chzdev:

zdev:early=0|1
    Control in which stage of the boot process a device is activated:

    0   Device is activated normally during boot (default).

    1   Device is activated early in the boot process, by the initial RAM-disk.

    Specify a value of 1 for this attribute in any of the following situations:

    •   To ensure that your settings override auto-configuration settings.

    •   To ensure that a device required to access the root file system is correctly enabled during boot. An example would be a networking device, or a device that is intended to extend a logical volume that provides the root file system.

ACTIONS
You can use one of the action options listed below to specify the main tool action that chzdev should perform. Alternatively you can specify a setting or one of --remove or --remove-all to modify device and device type settings.

  Action options
Apply persistent settings to active configuration. Applies the persistent configuration of all selected devices and device types to the active configuration.

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

Disable device in all configurations.

Enable device. The enable action instructs chzdev to perform any steps necessary for the selected devices to provide their corresponding Linux function (such as a block device or networking interface). Examples for such steps include setting a CCW device online, removing a CCW device from the CIO blacklist, and creating a CCW group device. Active configuration: Performs all initial setup steps required for a device to provide its Linux function. Persistent configuration: Creates configuration files and settings associated with the selected devices.

Export configuration data to a text file. Writes configuration data for all selected devices and device types to FILENAME. If a single hyphen ("-") is specified instead of an actual file name, data is written to the standard output stream. The output format of this action is suitable for use with the --import action of chzdev.

Print usage information, then exit.

Show detailed help on specified attribute. Displays detailed information about the attributes specified as positional command line arguments. Information displayed includes a description of the attribute function and optionally a list of accepted values and the default value.

Import configuration data from a text or machine-provided file. Reads configuration data from FILENAME and applies it. If a single hyphen ("-") is specified as FILENAME data is read from the standard input stream. The input format must be either in the format as produced by the chzdev --export action, or in the format of a machine-provided I/O configuration data file. Machine-provided data: Some machine models provide I/O configuration data which is made available by the Linux kernel via a sysfs interface. While this data is intended for automatic consumption during the boot phase, you can also apply it manually using the --import action like in the following example Example: Note: 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 only data for the active, persistent or auto-configuration should be imported.

List attributes. Lists all supported device or device type attributes, including a short description. You can use the --help-attribute action to get more detailed information about an attribute.

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

Print version information, then exit.

OPTIONS
Apply changes to the active configuration only. Restricts configuration changes to the active configuration. As a result, the persistent configuration is not changed unless --persistent was also specified. Note: Changes to the active configuration are effective immediately. They are lost on reboot, or when a device becomes unavailable, or when a device driver is unloaded.

Apply changes to the auto-configuration only. This option is used internally to apply machine-provided I/O configuration data to a Linux system. Note: There is typically no need for users to specify this option directly. In particular, user-initiated changes to this configuration will be lost the next time that machine-provided data is obtained (i.e. during boot).

Change file system paths 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:

Print output without performing configuration actions. Performs action processing and displays tool output without changing the configuration of any devices or device types. When combined with --verbose, details about skipped configuration steps are displayed.

Override safety checks. Overrides safety checks and confirmation questions. These checks include:

    •   Selection of more than 256 devices

    •   Configuring unknown attributes

    •   Combining apparently inconsistent settings

Detect if the file mentioned is generated by zdev tools. Return 0 if the FILENAME is generated by zdev tools and 33 otherwise. Example:

Skip root device update. Skips any additional steps that are required to make changes to the root device configuration persistent. Typically such steps include rebuilding the initial RAM disk, or modifying the kernel command line.

Do not wait for udev processing to complete. Skips all calls to the udevadm tool that are intended to wait for udev to finish processing before continuing. There is typically no need to use this option unless chzdev is run in an environment where udev is not fully functional (such as in the early phase of an initial RAM disk).

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

Print only minimal run-time information.

Remove setting for attribute ATTRIB. Persistent configuration: Removes any setting for the specified attribute. As a result, the attribute will keep its initial value when the device or device type is configured. Active configuration: For attributes that maintain a list of values written to them, clears all values for that list. Note: Some attributes are mandatory and cannot be removed.

Remove settings for all attributes. Persistent configuration: Removes all non-mandatory attribute settings. As a result, these attributes will keep their initial value when the device or device type is configured. Active configuration: For all attributes that maintain a list of values written to them, clears all values for that list. Note: Some attributes are mandatory and cannot be removed.

Apply the persistent configuration to the specified site only. This option can be used to configure the device in such a way that, the same configuration can be used on multiple different sites with different device hardwares, without any modification. With the site information, we can add different configurations which are specific to different sites. Where each site represents different systems or different hardware devices which are even located in different locations. For example, having the configuration of main-site or failover-site in the same place, but these configurations used only on the respective sites. Currently a user can define 10 different configurations for 10 different sites with SITE-ID 0 to 9. The configuration settings is put into effect only on the system with the site number which is mentioned in SITE-ID. This parameter is only effective only for persistent configurations and for dasd device-types. Example:

Select device type as target for actions. Selects a device type as target for a configuration or query action.

Print additional run-time information.

Answer all confirmation questions with 'yes'.

EXAMPLES
Enable DASD 0.0.8000 and create persistent configuration:

Enable zFCP LUN and create persistent configuration:

Enable QETH device without creating a persistent configuration:

Get help on QETH device attribute:

Change dasd device type parameter:

Remove persistent use_diag setting of dasd 0.0.8000:

Export configuration data for all zFCP LUNs to file.

Persistently configure root device:

Disable device that provides networking interface eth0:

If you intend to assign a cryptographic (AP) adapter or domain to a KVM guest you must first release its usage by the zcrypt driver in the host operating system using chzdev commands similar to the following examples:

Remove AP adapters 1 and 20 through 22 from host usage:

Return AP domains 5 and 8 through 10 to host usage:

Specify the list of AP adapters and domains available for host usage:

EXIT CODES

0   Program finished successfully

1   Usage error

2   Unknown device type specified

3   Device not found

4   Unknown attribute specified

5   Invalid device type specified

6   Invalid attribute value specified

7   Setting not found

8   Empty selection

9   Invalid configuration

10  Invalid device ID specified

11  Incomplete device ID specified

12  Configuration data not found

13  Unknown column specified

14  None or incomplete type specified

15  A run-time error occurred

16  Operation aborted on user request

17  Error while applying setting

18  File format error

19  Kernel module is in use

20  Kernel module could not be unloaded

21  Kernel module could not be loaded

22  Not enough available memory

23  FCP device not found

24  Invalid WWPN specified

25  WWPN not found

26  Invalid LUN specified

27  SCSI device not found

28  CCW group device: CCW device not found

29  CCW group device: CCW devices are not a valid group

30  CCW group device: CCW device already grouped

31  CCW group device: Grouping failed

32  CCW group device: Ungrouping failed

33  The file specified by --is-owner is not generated by zdev

99  An internal error occurred

FILES

/etc/udev/rules.d/
    chzdev creates udev rules to store the persistent configuration of devices in this directory. File names start with "41-".

/etc/modprobe.d/
    chzdev creates modprobe configuration files to store the persistent configuration of certain device types in this directory. File names start with "s390x-".

SEE ALSO