s390-tools/qeth_configure.8

.TH qeth_configure "8" "July 2013" "s390-tools"
.SH NAME
qeth_configure \- Configures or deconfigures a HiperSocket adapter or an IBM Open Systems Adapter (OSA) in QDIO mode
.SH SYNOPSIS
.B qeth_configure [options] read_channel write_channel data_channel online
.SH DESCRIPTION
.B qeth_configure
is intended to make it easy to persistently add and remove HiperSocket Adapters and Open System Adapters (OSAs) that are in QDIO mode. In addition to bringing the adapter online or offline, it will also create or delete the necessary udev rules for the adapter.
.SH PARAMETERS
.IP read_channel
The device number of the read channel of the adapter. Takes the form x.y.ssss.
.IP write_channel
The device number of the write channel of the adapter.Takes the form x.y.ssss.
.IP data_channel
The device number of the data channel of the adapter.Takes the form x.y.ssss.
.RS

where
.RS
.B x
is always 0 until IBM creates something that uses that number.
.RE
.RS
.B y
is the logical channel subsystem (lcss) number. Most often this is 0, but it could be non-zero.
.RE
.RS
.B ssss
is the four digit subchannel address of the device, in hexidecimal, with leading zeros. If entered in upper/mixed case, this is automatically converted to lower case.
.RE
.RE
.RS
.RE
.RE
.IP online
Either a literal 1 to bring the adapter online or a literal 0 to take it offline
.SH OPTIONAL PARAMETERS
.IP -i
Configure IP takeover
.IP -l
Configure Layer 2 support
.IP -f
Force creation of udev rules, do not check values in /sys. Requires -t to be specfied.
.IP "-t CARDTYPE"
The type of card being configured. Valid values are: qeth, hsi, or osn.
.IP "-o ""Values"""
General/arbitrary QETH options, separated by spaces
.IP "-n portnumber"
QETH port number to use, 0 or 1. Only needed for real, not virtual devices.
.IP "-p portname"
QETH Portname to use. Only needed if sharing a real OSA with z/OS.
.SH FILES
.I /etc/udev/rules.d/51-hsi-<ccwid>.rules
.RE
.I /etc/udev/rules.d/51-osn-<ccwid>.rules
.RE
.I /etc/udev/rules.d/51-qeth-<ccwid>.rules
.RS
These files provide the udev rules necessary to activate a specific adapter.
.RE
.SH ENVIRONMENT
.IP DEBUG
If set to "yes" some minimal debugging information is output during execution.
.SH DIAGNOSTICS
The following messages may be issued on stdout:
.IP
.B /sysfs not present
.RS
The sysfs file system could not be found in /proc/mounts, so there's nothing the script can 
do. Return code 1 is set.
.RE
.IP
.B Invalid device status ${ONLINE}
.RS
A value other than 0 or 1 was specified for the third parameter, online. Return code 2 is set.
.RE
.IP
.B No device ${QETH_READ_CHAN}
.RS
A non-existent <ccwid> was specified for the read_channel parameter. Remember the x.y.ssss format is necessary. Return code 3 is set.
.RE
.IP
.B No device ${QETH_WRITE_CHAN}
.RS
A non-existent <ccwid> was specified for the write_channel parameter. Remember the x.y.ssss format is necessary. Return code 4 is set.
.RE
.IP
.B No device ${QETH_DATA_CHAN}
.RS
A non-existent <ccwid> was specified for the data_channel parameter. Remember the x.y.ssss format is necessary. Return code 4 is set.. Return code 5 is st.
.RE
.IP
.B Only qeth, hsi and osn are supported.
.RS
The device type specified by the -t option is not one of the supported types. Return code 6 is set.
.RE
.IP
.B Not a valid QETH device (cu $_cutype, dev $_devtype)
.RS
The device number specified does not correspond to a valid QETH device type. Return code 6 is set.
.RE
.IP
.B Could not load module ${CCW_DRV}
.RS
The kernel module for the device type failed to load. Try "dmesg" to see if there is any indication why. Return code 7 is set.
.RE
.IP
.B CCW devices grouped to different devices
.RS
Two or more of the read, write and channels are already grouped, but not within the same interface. Try again with different devices. Return code 8 is set.
.RE
.IP
.B Could not group $CCW_DRV devices $QETH_READ_CHAN/$QETH_WRITE_CHAN/$QETH_DATA_CHAN
.RS
The attempt to group the read, write and data channels into an interface failed. Try "dmesg" to see if there is any indication why. Return code 9 is set.
.RE
.IP
.B Could not set device ${CCW_CHAN_ID} online
.RS
The attempt to bring the grouped devices online failed. Try "dmesg" to see if there is any indication why. Return code 10 is set.
.RE
.IP
.B Could not set device ${CCW_CHAN_ID} offline
.RS
The attempt to take the grouped devices offline failed. Try "dmesg" to see if there is any indication why. Return code 11 is set.
.RE

If environment variable DEBUG is set to "yes," the following messages may be issued on stdout:
.IP
.B 
Configuring QETH device ${QETH_READ_CHAN}/${QETH_WRITE_CHAN}/${QETH_DATA_CHAN}
.RS
Just a little bit of verbosity, since it just indicates that we got past certain error checks and will now try to do something useful.
.RE
.IP
.B No portname required for $QETH_CARD adapters
.RS
If a QETH_CARD type other than "qeth" is specified or detected, a portname is not used, so using the -p option is unnecessary.
.RE
.IP
.B Invalid option $opt_name
.RS
Either portname, ipa_takeover, layer2, or a completely unknown QETH parameter was specified via the -o parameter. For portname, ipa_takeover, and layer2, use the -p, -i, or -l options, respectively.
.RE
.IP
.B Device ${CCW_CHAN_ID} is already online
.RS
An attempt was made to bring the adapter online when it was already online.
.RE
.IP
.B Setting device offline
.RS
Just a little bit of verbosity.
.RE
.IP
.B Device ${CCW_CHAN_ID} is already offline
.RS
An attempt was made to take the adapter offline when it was already offline.
.RE
.SH BUGS
Gotta be some, I'm sure. If you find one, please open a bug report.