Scroll to navigation

chzdev(8) chzdev 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.

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: chzdev dasd 1000,2000-2010 -e

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:

The device is enabled in the active configuation and set up to provide a Linux function such as a block device like /dev/dasda, or a networking interface like eth0.
The device is not enabled in the active configuration.
The device is present in the active configuration.
There is a persistent configuration for this device.
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 lsblk(8) 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 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.

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

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

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

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: chzdev dasd 1000 use_diag=1

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.

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: chzdev --import /sys/firmware/sclp_sd/config/data

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: chzdev -dasd-eckd 1000 -e -p --base /etc=/mnt/etc

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

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.

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:

chzdev -e dasd 8000

Enable zFCP LUN and create persistent configuration:

chzdev -e zfcp-lun 0.0.1724:0x50050763070ba5e2:0x4006404e00000000

Enable QETH device without creating a persistent configuration:

chzdev -e -a qeth 0.0.a000:0.0.a001:0.0.a002

Get help on QETH device attribute:

chzdev qeth --help-attribute layer2

Change dasd device type parameter:

chzdev dasd --type eer_pages=14

Remove persistent use_diag setting of dasd 0.0.8000:

chzdev dasd 8000 --remove use_diag --persistent

Export configuration data for all zFCP LUNs to file.

chzdev zfcp-lun --all --export config.txt

Persistently configure root device:

chzdev --by-path / --persistent --enable

Disable device that provides networking interface eth0:

chzdev --by-interface eth0 --active --disable

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

lszdev(8), lscss(8), lsdasd(8), lszfcp(8), lsqeth(8), lsblk(8).

Jan 2016 s390-tools