ZNETCONF(8)

NAME
znetconf - list and configure network devices for System z network adapters

SYNOPSIS
znetconf [-h|--help] [-v|--version]
znetconf -u | -c
znetconf -a <device_bus_id>[,...]{2} [-o <ATTR>=<VALUE>]+ [-d <DRIVER>]
znetconf -A [-o <ATTR>=<VALUE>]+ [-d <DRIVER>] [-e <device_bus_id>]+
znetconf -r <device_bus_id> [-n] | -R [-n] [-e <device_bus_id>]+

DESCRIPTION
The znetconf command lists and automatically configures network devices for System z network adapters. It senses and lists potential network devices that are not yet configured or already configured. Based on these lists, it automatically adds or removes network devices.

For automatic configuration, znetconf builds a channel command word (CCW) group device from sensed CCW devices, configures any specified option through the sensed network device driver and sets the new network device online.

During automatic removal, znetconf sets the device offline and removes it. Be aware that removing all network devices leads to the complete loss of network connectivity. So a terminal session (e.g. 3270) might be required to restore.

OPTIONS

-h|--help
    Print help text.

-v|--version
    Print the version of the s390-tools package and the znetconf command.

-u|--unconfigured
    List potential network devices that are not yet configured. For each device, the following data is provided:

    *   Device IDs (device bus-IDs) of the CCW devices constituting the network device

    *   Type of control unit (e.g. 1731/01)

    *   Network card type (e.g. OSA (QDIO))

    *   Channel path identifier (CHPID)

    *   Device driver (qeth, lcs, ctc, ctcm)

-c|--configured
    List configured network devices. For each device, the following data is provided:

    *   Device IDs (device bus-IDs) of the CCW devices constituting the network device

    *   Control unit type (e.g. 1731/01)

    *   Card type (e.g. GuestLAN QDIO)

    *   Channel path identifier (CHPID)

    *   Driver (qeth, lcs, ctc, ctcm)

    *   Network interface name (if available)

    *   State (online vs. offline)

-a|--add <device_bus_id>[,<device_bus_id>)][,<device_bus_id>]
    [-o | --option <ATTR>=<VALUE>]+ [-d | --driver <DRIVER>]
    Add the potential network device identified by device_bus_id. device_bus_id can be any of the device IDs listed as part of the potential network device list (argument -u). For example, if znetconf -u lists 0.0.f503,0.0.f504,0.0.f505 for a potential network device, device_bus_id may be 0.0.f503 or 0.0.f504 or 0.0.f505. If a device bus-ID begins with 0.0., you can abbreviate it to the final hexadecimal digits. For example, you can abbreviate 0.0.f503 to f503.
    If attribute value pairs are given with -o, these pairs are configured for the created network device. The device is then set online regardless of whether the given attribute value pairs were applied successfully.
    Finally, the corresponding network interface name (e.g. eth1) is displayed.
    If more then one device_bus_id is given, the given set of devices is configured as a network device. znetconf tries to sense the required device driver automatically. If the device driver cannot be sensed, you must specify it with -d. -d. With -d znetconf does NOT check the validity of the combination of device bus-IDs.

-A|--addall [-o | --option <ATTR>=<VALUE>]+ [-d | --driver DRIVER]
    [-e | --except <device_bus_id>]+
    Add all potential network devices. If one or more device_bus_id are specified with -e, the corresponding network devices are not added. Attribute value pairs given with -o are configured for the network devices before they are set online. If the configuration of one potential network device fails, znetconf continues with the next remaining potential network device.

-r|--remove <device_bus_id> [-n | --non-interactive]
    Remove the network device identified by device_bus_id. device_bus_id is one of the device IDs of the network device. They are listed as part of znetconf -c. znetconf sets the device offline and removes it. If -n is given, all confirmation questions are answered with 'yes'.

-R|--removall [-n | --non-interactive] [-e | --except <device_bus_id>]+
    Remove all network devices. If -n is given, all confirmation questions are answered with 'yes'. To exclude certain devices from the removal, their device bus-IDs have to be given with -e.

<ATTR>
    Specify a device option. The option must match a sysfs attribute for the device to be configured. For a detailed description of the semantics of sysfs attributes please refer to the Device Drivers, Features, and Commands book for Linux on System z. The attributes are:
    qeth
    broadcast_mode
    buffer_count
    canonical_macaddr
    checksumming
    fake_broadcast
    ipa_takeover/add4
    ipa_takeover/add6
    ipa_takeover/del4
    ipa_takeover/del6
    ipa_takeover/enable
    ipa_takeover/invert4
    ipa_takeover/invert6
    isolation
    large_send
    layer2
    performance_stats
    portname
    portno
    priority_queueing
    route4
    route6
    rxip/add4
    rxip/add6
    rxip/del4
    rxip/del6
    vipa/add4
    vipa/add6
    vipa/del4
    vipa/del
    sniffer
    ctc(m)
    buffer
    loglevel
    protocol
    stats
    lcs
    portno
    lancmd_timeout
    NOTE: for qeth, some attributes are specific to layer 2 or layer 3 mode of operation. The option "layer2=[0|1]" must be specified before such attributes in the command line, thus it is recommended to always specify it first.

<device_bus_id>
    Specify the device bus-ID of a CCW device. Device bus-IDs have the form ([A-Fa-f0-9].[A-Fa-f0-9].)[A-Fa-f0-9]{4}. If a device bus-ID begins with 0.0., you can abbreviate it to the final hexadecimal digits. For example, you can abbreviate 0.0.f503 to f503.

<DRIVER>
    Specify the device driver for the device. Valid values are qeth, lcs, ctc, or ctcm.

EXAMPLES
znetconf -A
    Configures all potential network devices. To display a list of all potential network devices enter znetconf -u. After running znetconf -A enter znetconf -c to see which devices have been configured successfully. You can also enter znetconf -u to display devices that have not been configured successfully. Successfully configured devices are no longer listed with znetconf -u.

znetconf -A -e f500
    Configures all potential network devices except the one with the device bus-ID 0.0.f500. To display a list of all potential network devices enter znetconf -u. After running znetconf -A -e f500 enter znetconf -c to see which devices have been configured successfully. You can also enter znetconf -u to display devices that have not been configured successfully. Successfully configured devices are no longer listed with znetconf -u.

znetconf -R
    Removes all configured network devices. After successfully running this command, all devices listed by znetconf -c become potential devices listed by -u.

znetconf -R -e f501
    Removes all configured network devices except the one having the device bus-ID 0.0.f501. After successfully running this command, all devices listed by znetconf -c except the one having the device bus-ID 0.0.f501 become potential devices listed by -u.

znetconf -u
    Shows the list of potential network devices. Example output:
    Device IDs Type Card Type CHPID Drv.
    --------------------------------------------------------
    0.0.f500,0.0.f501,0.0.f502 1731/01 OSA (QDIO) 00 qeth
    0.0.f503,0.0.f504,0.0.f505 1731/01 OSA (QDIO) 01 qeth

znetconf -a 0.0.f503
    Adds the potential network device with 0.0.f503 as one of its device bus-IDs. After successfully running this command, znetconf -c lists the new network device.

znetconf -a f503
    This command is equivalent to znetconf -a 0.0.f503.

znetconf -a f503 -o layer2=0 -o portname=myname
    Adds the potential network device with 0.0.f503 as one of its device bus-IDs and configures the options layer2 with value 0 and portname with myname.

znetconf -c
    Shows a list of configured network devices. Example output:
    Device IDs Type Card Type CHPID Drv. Name State
    -----------------------------------------------------------------------
    0.0.f503,0.0.f504,0.0.f505 1731/01 GuestLAN QDIO 01 qeth eth1 online
    0.0.f5f0,0.0.f5f1,0.0.f5f2 1731/01 OSD_1000 76 qeth eth0 online

znetconf -r 0.0.f503
    Removes the network device with 0.0.f503 as one of its device bus-IDs. You can only remove configured devices as listed by znetconf -c. After successfully running this command the corresponding device appears in the list of potential network devices as listed by znetconf -u.

znetconf -r f503
    This command is equivalent to znetconf -r 0.0.f503.

DIAGNOSTICS
If znetconf runs successfully, the exit status is 0. In case of errors, the following codes are returned:

0   success

9   could not group devices

10  could not set device online

11  could not set device offline

12  invalid attribute value pair

13  missing component (broken installation)

15  invalid device ID format

17  unknown driver

19  invalid argument

20  too much arguments

21  no configuration found for device ID

22  device is not configured

23  could not ungroup device

24  at least one option could not be configured

25  missing value for attribute

26  device does not exist

27  device already in use

28  net device did not come online

29  some devices could not be added or failed

30  syntax error on command line

31  ccwgroup devices do not exist

99  internal znetconf bug

AUTHOR
This man-page was written by Einar Lueck <elelueck@de.ibm.com>.