25.3. Adding a Network Device

Network device driver modules are loaded automatically by udev.

You can add a network interface on IBM System z dynamically or persistently.

Dynamically
1. Load the device driver
2. Remove the network devices from the list of ignored devices.
3. Create the group device.
4. Configure the device.
5. Set the device online.
Persistently
1. Create a configuration script.
2. Activate the interface.

The following sections provide basic information for each task of each IBM System z network device driver. Section 25.3.1, “Adding a qeth Device” describes how to add a qeth device to an existing instance of Red Hat Enterprise Linux. Section 25.3.2, “Adding an LCS Device” describes how to add an lcs device to an existing instance of Red Hat Enterprise Linux. Section 25.3.3, “Mapping subchannels and network device names” describes how persistent network device names work. Section 25.3.4, “Configuring a System z Network Device for Network Root File System” describes how to configure a network device to use with a root file system that is only accessible through the network.

25.3.1. Adding a qeth Device

The qeth network device driver supports System z OSA-Express features in QDIO mode, HiperSockets, z/VM guest LAN, and z/VM VSWITCH.

Based on the type of interface being added, the qeth device driver assigns one of the base interface names:

hsin for HiperSockets devices
ethn for Ethernet features

The value n is an integer that uniquely identifies the device. n is 0 for the first device of that type, 1 for the second, and so on.

25.3.1.1. Dynamically adding a qeth device

To add a qeth device dynamically, follow these steps:

Determine whether the qeth device driver modules are loaded. The following example shows loaded qeth modules:

# lsmod | grep qeth
qeth_l3                  127056  9
qeth_l2                   73008  3
ipv6                  492872  155ip6t_REJECT,nf_conntrack_ipv6,qeth_l3
qeth                  115808  2 qeth_l3,qeth_l2
qdio                   68240  1 qeth
ccwgroup               12112  2 qeth

If the output of the lsmod command shows that the qeth modules are not loaded, run the modprobe command to load them:

# modprobe qeth

Use the cio_ignore command to remove the network channels from the list of ignored devices and make them visible to Linux:
```
# cio_ignore -r read_device_bus_id,write_device_bus_id,data_device_bus_id
```
Replace read_device_bus_id,write_device_bus_id,data_device_bus_id with the three device bus IDs representing a network device. For example, if the read_device_bus_id is 0.0.f500, the write_device_bus_id is 0.0.f501, and the data_device_bus_id is 0.0.f502:
```
# cio_ignore -r 0.0.f500,0.0.f501,0.0.f502
```

Use the znetconf command to sense and list candidate configurations for network devices:

# znetconf -u
Scanning for network devices...
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 
0.0.0400,0.0.0401,0.0.0402 1731/05 HiperSockets      02 qeth

Select the configuration you want to work with and use znetconf to apply the configuration and to bring the configured group device online as network device.
```
# znetconf -a f500
Scanning for network devices...
Successfully configured device 0.0.f500 (eth1)
```
Optionally, you can also pass arguments that are configured on the group device before it is set online:
```
# znetconf -a f500 -o portname=myname
Scanning for network devices...
Successfully configured device 0.0.f500 (eth1)
```
Now you can continue to configure the network eth1 interface.

Alternatively, you can use sysfs attributes to set the device online as follows:

Create a qeth group device:

# echo read_device_bus_id,write_device_bus_id,data_device_bus_id > /sys/bus/ccwgroup/drivers/qeth/group

For example:

# echo 0.0.f500,0.0.f501,0.0.f502 > /sys/bus/ccwgroup/drivers/qeth/group

Next, verify that the qeth group device was created properly by looking for the read channel:
```
# ls /sys/bus/ccwgroup/drivers/qeth/0.0.f500
```
You may optionally set additional parameters and features, depending on the way you are setting up your system and the features you require, such as:
- portno
- layer2
- portname
For information on additional parameters, refer to the chapter on the qeth device driver in Linux on System z Device Drivers, Features, and Commands on Red Hat Enterprise Linux 6.
Bring the device online by writing 1 to the online sysfs attribute:
```
# echo 1 > /sys/bus/ccwgroup/drivers/qeth/0.0.f500/online
```
Then verify the state of the device:
```
# cat /sys/bus/ccwgroup/drivers/qeth/0.0.f500/online
1
```
A return value of 1 indicates that the device is online, while a return value 0 indicates that the device is offline.

Find the interface name that was assigned to the device:

# cat /sys/bus/ccwgroup/drivers/qeth/0.0.f500/if_name
eth1

Now you can continue to configure the network eth1 interface.

The following command from the s390utils package shows the most important settings of your qeth device:

# lsqeth eth1
Device name                     : eth1                
---------------------------------------------
        card_type               : OSD_1000
        cdev0                   : 0.0.f500
        cdev1                   : 0.0.f501
        cdev2                   : 0.0.f502
        chpid                   : 76
        online                  : 1
        portname                : OSAPORT
        portno                  : 0
        state                   : UP (LAN ONLINE)
        priority_queueing       : always queue 0
        buffer_count            : 16
        layer2                  : 1
        isolation               : none

25.3.1.2. Dynamically removing a qeth device

To remove a qeth device, use the znetconf tool. For example:

Use the znetconf command to show you all configured network devices:

znetconf -c
Device IDs                 Type    Card Type      CHPID Drv. Name        State  
--------------------------------------------------------------------------------
0.0.8036,0.0.8037,0.0.8038 1731/05 HiperSockets      FB qeth hsi1        online 
0.0.f5f0,0.0.f5f1,0.0.f5f2 1731/01 OSD_1000          76 qeth eth0        online 
0.0.f500,0.0.f501,0.0.f502 1731/01 GuestLAN QDIO     00 qeth eth1        online

Select the network device to be removed and trigger znetconf to set the device offline and ungroup the ccw group device.

# znetconf -r f500
Remove network device 0.0.f500 (0.0.f500,0.0.f501,0.0.f502)?
Warning: this may affect network connectivity!
Do you want to continue (y/n)?y
Successfully removed device 0.0.f500 (eth1)

Verify the success of the removal:

znetconf -c
Device IDs                 Type    Card Type      CHPID Drv. Name        State  
--------------------------------------------------------------------------------
0.0.8036,0.0.8037,0.0.8038 1731/05 HiperSockets      FB qeth hsi1        online 
0.0.f5f0,0.0.f5f1,0.0.f5f2 1731/01 OSD_1000          76 qeth eth0        online

25.3.1.3. Persistently adding a qeth device

To make your new qeth device persistent you need to create the configuration file for your new interface. The network interface configuration files are placed in /etc/sysconfig/network-scripts/.

The network configuration files use the naming convention ifcfg-device, where device is the value found in the if_name file in the qeth group device that was created earlier. In this example it is eth1. Cio_ignore is handled transparently for persistent device configurations and you do not need to free devices from the ignore list manually.

If a configuration file for another device of the same type already exists, the simplest solution is to copy it to the new name.

# cd /etc/sysconfig/network-scripts
# cp ifcfg-eth0 ifcfg-eth1

If you do not have a similar device defined you must create one. Use this example of ifcfg-eth0 as a template:

/etc/sysconfig/network-scripts/ifcfg-eth0

# IBM QETH
DEVICE=eth0
BOOTPROTO=static
IPADDR=10.12.20.136
NETMASK=255.255.255.0
ONBOOT=yes
NETTYPE=qeth
SUBCHANNELS=0.0.09a0,0.0.09a1,0.0.09a2
PORTNAME=OSAPORT
OPTIONS='layer2=1 portno=0'
MACADDR=02:00:00:23:65:1a
TYPE=Ethernet

Edit the new ifcfg-eth1 file as follows:

Modify the DEVICE statement to reflect the contents of the if_name file from your ccwgroup.
Modify the IPADDR statement to reflect the IP address of your new interface.
Modify the NETMASK statement as needed.
If the new interface is to be activated at boot time, then make sure ONBOOT is set to yes.
Make sure the SUBCHANNELS statement matches the hardware addresses for your qeth device.
Modify the PORTNAME statement or leave it out if it is not necessary in your environment.
You may add any valid sysfs atttribute and its value to the OPTIONS parameter. The Red Hat Enterprise Linux installer currently uses this to configure the layer mode (layer2) and the relative port number (portno) of qeth devices.
The qeth device driver default for OSA devices is now layer 2 mode. To continue using old ifcfg definitions that rely on the previous default of layer 3 mode, add layer2=0 to the OPTIONS parameter.

/etc/sysconfig/network-scripts/ifcfg-eth1

# IBM QETH
DEVICE=eth1
BOOTPROTO=static
IPADDR=192.168.70.87
NETMASK=255.255.255.0
ONBOOT=yes
NETTYPE=qeth
SUBCHANNELS=0.0.0600,0.0.0601,0.0.0602
PORTNAME=OSAPORT
OPTIONS='layer2=1 portno=0'
MACADDR=02:00:00:b3:84:ef
TYPE=Ethernet

Changes to an ifcfg file only become effective after rebooting the system or after the dynamic addition of new network device channels by changing the system's I/O configuration (for example, attaching under z/VM). Alternatively, you can trigger the activation of a ifcfg file for network channels which were previously not active yet, by executing the following commands:

Use the cio_ignore command to remove the network channels from the list of ignored devices and make them visible to Linux:
```
# cio_ignore -r read_device_bus_id,write_device_bus_id,data_device_bus_id
```
Replace read_device_bus_id,write_device_bus_id,data_device_bus_id with the three device bus IDs representing a network device. For example, if the read_device_bus_id is 0.0.0600, the write_device_bus_id is 0.0.0601, and the data_device_bus_id is 0.0.0602:
```
# cio_ignore -r 0.0.0600,0.0.0601,0.0.0602
```

To trigger the uevent that activates the change, issue:

echo add > /sys/bus/ccw/devices/read-channel/uevent

For example:

echo add > /sys/bus/ccw/devices/0.0.0600/uevent

Check the status of the network device:
```
# lsqeth
```
Now start the new interface:
```
# ifup eth1
```

Check the status of the interface:

# ifconfig eth1
eth1      Link encap:Ethernet  HWaddr 02:00:00:00:00:01
          inet addr:192.168.70.87  Bcast:192.168.70.255 Mask:255.255.255.0
          inet6 addr: fe80::ff:fe00:1/64 Scope:Link
          UP BROADCAST RUNNING NOARP MULTICAST  MTU:1492  Metric:1
          RX packets:23 errors:0 dropped:0 overruns:0 frame:0
          TX packets:3 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:644 (644.0 b)  TX bytes:264 (264.0 b)

Check the routing for the new interface:

# route
Kernel IP routing table
Destination     Gateway         Genmask        Flags Metric Ref  Use Iface
192.168.70.0    *               255.255.255.0  U     0      0      0 eth1
10.1.20.0       *               255.255.255.0  U     0      0      0 eth0
default         10.1.20.1       0.0.0.0        UG    0      0      0 eth0

Verify your changes by using the ping command to ping the gateway or another host on the subnet of the new device:

# ping -c 1 192.168.70.8
PING 192.168.70.8 (192.168.70.8) 56(84) bytes of data.
64 bytes from 192.168.70.8: icmp_seq=0 ttl=63 time=8.07 ms

If the default route information has changed, you must also update /etc/sysconfig/network accordingly.