Chapter 4. Networking Overview
4.6 Guest LAN configuration
To create a Guest LAN, use the following required steps:
1. Create a z/VM Guest LAN segment in the z/VM host system.
2. Create a virtual Network Interface Card (NIC) in each guest machine that will be connected to the Guest LAN.
3. Connect the virtual NIC in each guest machine to the Guest LAN.
4. After the Linux guest has been booted, configure the appropriate device drivers in that guest to connect to the Guest LAN.
4.6.1 Create a z/VM Guest LAN
z/VM Guest LANs can be created in one of two ways: either by a DEFINE LAN statement in the z/VM CP SYSTEM CONFIG file or by using the DEFINE LAN CP command. Why choose one over the other? Guest LANs created with the DEFINE LAN command are only valid for the life of a z/VM system. In other words, if that system is shut down and then IPLed, the Guest LAN is no longer be defined. We
Important: Although the syntax in the following sections is valid, always refer to the relevant level of z/VM reference manual for a complete description of all command syntax.
For the following examples, we used z/VM Version 5 Release 1.0 CP Planning and Administration, SC24-6083, and z/VM Version 5 Release 1.0 CP
Commands and Utility Reference, SC24-6081.
Chapter 4. Networking Overview 97 CP SYSTEM CONFIG file. This is known as a persistent Guest LAN. For testing purposes, the DEFINE LAN command is perfectly valid because it provides the flexibility to dynamically create Guest LANs as required.
4.6.2 Persistent Guest LANs
In order to define a persistent Guest LAN, we need to add a DEFINE LAN statement to the CP SYSTEM CONFIG file. For a complete discussion of making changes to this file, refer to the relevant level of the z/VM reference manual.
The syntax of the DEFINE LAN statement is as follows:
DEFINE LAN lanname [ operands ] Where the following is true:
lanname Is a 1-8 alphanumeric name of the z/VM Guest LAN.
operands Defines the characteristics of the z/VM Guest LAN.
Table 4-5 summarizes the operands accepted by the DEFINE LAN statement.
Table 4-5 Operands of the DEFINE LAN statement
Operand Description
OWNERid ownerid Establishes the owner of the LAN. The OWNERid is either a user id or SYSTEM. In our examples, the ownerid will be SYSTEM.
TYPE lantype Specifies the type of LAN. Valid types are HIPERsockets for simulated HiperSockets adapters or QDIO for simulated QDIO adapters. HiperSockets is the default.
IP | ETHernet For QDIO Guest LANs, this indicates whether the transport for the LAN is Ethernet or IP. An Ethernet LAN operates at the Layer 2 level of the OSI model. An IP LAN operates at Layer 3 of the OSI model.
MAXCONN maxconn Sets the maximum number of simultaneous adapter connections permitted. When MAXCONN is specified as INFinite, there is no limit on the number of connections. Any other value limits the number of simultaneous connections to a decimal value in the range of 1-1024.
As an example, to create a QDIO type Guest LAN named TSTLAN owned by SYSTEM, use:
DEFINE LAN TSTLAN OWNERID SYSTEM TYPE QDIO
4.6.3 The VMLAN statement
In addition to the DEFINE LAN statement, we can also add VMLAN statements to the CP SYSTEM CONFIG file to establish system-wide attributes for all z/VM Guest LANs that have been defined to the z/VM operating system. This includes Virtual Switches, which is discussed later.
Each VMLAN statement specifies a different system wide attribute and operands. Each attribute and operands are described separately.
VMLAN LIMIT [ operands ] See Table 4-6 on page 99.
VMLAN ACCOUNTing [ operands ] See Table 4-7 on page 99 VMLAN MACPREFIX macprefix See Table 4-8 on page 99 VMLAN MACIDRange [ operands ] See Table 4-9 on page 100
MFS size Sets the Maximum Frame Size (MFS) for adapters on this network. When an adapter is connected to this LAN, it will adopt the network MFS. The MFS value determines the amount of storage to be allocated for internal structures and limits the effective Maximum Transfer Unit (MTU) size for the coupled adapters. The MFS operand is not valid for the QDIO Guest LAN; however, the effective MFS is 8 K for a QDIO adapter.
UNRESTricted Defines a LAN with no access control; therefore, any user can connect to the LAN. When neither UNRESTricted nor RESTricted are specified, UNRESTricted is the default value.
RESTricted Defines a LAN with an access list to restrict connections. The LAN owner will use the SET LAN command to grant or revoke access to specific VM users (by user ID). The COUPLE command will only allow authorized users (those on the access list) to connect a simulated adapter to a RESTRICTED network.
ACCOUNTING value Allows a Class B user to control whether accounting records are created for the LAN being defined.
GRANT userlist Defines the list of users to be included in the Initial Access List of a RESTRICTED LAN. If the GRANT operand is omitted, the default is to GRANT the LAN owner.
Operand Description
Chapter 4. Networking Overview 99 Table 4-6 Operands of the VMLAN LIMIT statement
Table 4-7 Operands of the VMLAN ACCOUNTing statement
Table 4-8 Operands of the VMLAN MACPREFIX statement
Operands Description
PERSistent INFinite | maxcount INFinite means that there will be an infinite number of PERSISTENT z/VM Guest LAN segments and Virtual Switches allowed on the system. INFinite is the default. Use the maxcount parameter to define a number of PERSISTENT Guest LANS (between 0 and 1024) permitted to run on the system.
TRANSient INFinite | maxcount INFinite means that there will be an infinite number of TRANSIENT z/VM Guest LAN segments allowed on the system. INFinite is the default. Use the maxcount parameter to define a number of TRANSIENT Guest LANS (between 0 and 1024) permitted to run on the system.
Operands Description
SYSTEM ON | OFF Set the default accounting state for z/VM Guest LAN segments and Virtual Switches owned by the SYSTEM user ID. The default state of this attribute is OFF.
USER ON | OFF Set the default accounting state for z/VM Guest LAN segments owned by individual users. The default state of this attribute is OFF.
Operands Description
macprefix Specifies the three-byte prefix (manufacturer ID) used when generating locally administered MAC addresses on the system. It must be six hexadecimal digits within the range of 020000 through 02FFFF (inclusive). In combination with the MAC ID used on the NICDEF directory statement, the MACPREFIX allows unique identification of virtual adapters within a network. If MACPREFIX is not specified, the default is 020000 02-00-00).
Table 4-9 Operands of the VMLAN MACIDRange statement
4.6.4 Create a virtual Network Interface Card
You must create a virtual Network Interface Card (NIC) for each guest machine.
After it is defined, this NIC can be connected to the Guest LAN. To the guest operating system, the NIC devices look like a range of OSA devices. The NIC can be defined permanently through a User Directory statement or temporarily (for the life of the Guest’s session) through a CP command.
4.6.5 NIC definition in the user directory
To create a virtual Network Interface Card that will remain permanently defined to a VM guest machine (that is, across guest sessions and across IPLs of the z/VM operating system), use the NICDEF statement in the z/VM User Directory.
The NICDEF statement defines virtual devices that are fully simulated by CP.
The NIC automatically joins the Guest LAN when the z/VM user ID is logged on.
The syntax of the NICDEF statement for Network Interface Cards is as follows:
NICDEF vdev [ operands ] Where the following is true:
vdev Specifies the base virtual device address for the adapter.
Operands Description
SYSTEM xxxxxx-xxxxxx The range of identifiers (up to six hexadecimal digits each) to be used by CP when generating the unique identifier part (last six hexadecimal digits) of a virtual adapter MAC address. If a SYSTEM MACIDRANGE is not specified, CP creates unique identifiers in any range (000001-FFFFFF).
This operand is required.
USER xxxxxx-xxxxxx USER xxxxxx-xxxxxx is the subset of the SYSTEM range of identifiers that are reserved for user definition of MACIDs in the NICDEF directory statement. When specified, CP does not assign MACIDs within this USER range during creation of virtual adapters defined dynamically (DEFINE NIC) or with the NICDEF (or SPECIAL) directory statement without the MACID operand. In these cases, CP generates a unique identifier for the adapter outside of the USER range. Any MACID values specified on a NICDEF directory statement must be within the USER range, or the virtual adapter is not defined during LOGON processing. If a USER MACIDRANGE is not specified, CP creates unique identifiers within the SYSTEM MACIDRANGE. This operand is optional.
Chapter 4. Networking Overview 101 operands Defines the characteristics of the virtual NIC.
Table 4-10 lists the operands accepted by the NICEF command.
Table 4-10 Operands for the NICDEF user directory statement
Operands Description
TYPE HIPERs or
TYPE QDIO
HIPERs indicates that a simulated HiperSockets adapter should be created. QDIO indicates that a simulated QDIO adapter should be created. If a LAN is identified in this statement or another with the same vdev, the NIC is automatically coupled to the specified ownerid lanname.
DEVices devs The number (decimal) of virtual I/O devices to be created for a simulated NIC. If devs is omitted, the default number of devices is three.
LAN ownerid lanname or
LAN SYSTEM lanname
Identifies a Guest LAN segment or Virtual Switch for an immediate connection to the NIC. If ownerid and lanname are omitted, the simulated adapter is left in the uncoupled state. When ownerid and lanname are specified, the adapter is automatically connected to the designated Guest LAN. Note that the ownerid can be specified as a name or using an asterisk (*) to represent the user ID of the current virtual machine. An ownerid of SYSTEM is used for a system owned Guest LAN or a Virtual Switch.
CHPID xx A two-digit hexadecimal number that represents the CHPID number to be allocated in the virtual machine I/O
configuration for this adapter. If CHPID is omitted, an available CHPID is automatically assigned to this adapter.
This option is required when a HiperSockets adapter is being created for a z/OS guest, because z/OS
configurations require a predictable CHPID number. During LOGON, CP attempts to use the specified CHPID number.
If the specified CHPID number is already in use, this adapter is not defined. To correct this situation, you must eliminate the conflicting device or select a different CHPID.
MACID xxxxxx Aunique identifier (up to six hexadecimal digits) used as part of the adapter MAC address. During LOGON, your MACID (3 bytes) is appended to the system MACPREFIX (3 bytes) to form a unique MAC address for this adapter. If MACID is omitted from this definition, CP generates a unique identifier for this adapter. If the specified MACID is already in use, this adapter is not defined. To correct this situation, you must eliminate the conflicting device or select a different MACID.
Figure 4-18 shows an example CP User Directory entry for a Linux guest that connects to a QDIO Guest LAN.
Figure 4-18 User directory entry for a Linux guest: Connecting to a QDIO Guest LAN
4.6.6 NIC definition using CP commands
To create a virtual Network Interface Card that will only last for the life of a guest (that is, it will need to be redefined when the guest next logs on to the system), use the following command syntax:
DEFINE NIC vdev [ operands ] Where the following is true:
vdev Specifies the base virtual device address for the adapter.
operands Define the characteristics of the virtual NIC.
Table 4-11 lists the operands accepted by the DEFINE NIC command.
Table 4-11 Operands for the DEFINE NIC command USER LNX23 LNX23 128M 1G G
INCLUDE IBMDFLT IPL CMSPARM AUTOCR MACHINE XA
CONSOLE 0009 3215
NICDEF 0700 TYPE QDIO DEV 3 SYSTEM TSTLAN MDISK 0191 3390 3274 025 LEVW01 MR
MDISK 0201 3390 3339 0200 LX3EA3 M MDISK 0202 3390 3539 3138 LX3EA3 M
Operands Description
TYPE HIPERsockets Defines this adapter as a simulated HiperSockets NIC. This adapter will function like the HiperSockets internal adapter. A HiperSockets NIC can function without a z/VM Guest LAN connection, or it can be coupled to a HiperSockets Guest LAN.
TYPE QDIO Defines this adapter as a simulated QDIO NIC. This adapter will function like the OSA-Express (QDIO) adapter. A QDIO NIC is only functional when it is coupled to a QDIO Guest LAN or a Virtual Switch.
Chapter 4. Networking Overview 103
4.6.7 Connect the virtual NIC to the Guest LAN
Now that we have defined the virtual NIC, just as in a real network we need to connect that device to the LAN. If we had used the NICDEF User Directory statement to define our NIC, the guest machine would automatically connect to the LAN whenever it logged on. However, if we chose to use the DEFINE NIC command, we have an additional step to perform before the device is connected to the Guest LAN.
Use the COUPLE CP command to attach the virtual NIC to a compatible Guest LAN. The syntax of the COUPLE command for this scenario is:
COUPLE vdev TO [ operands ] Where the following is true:
vdev Specifies the base virtual device address for the adapter.
operands Defines where to connect the NIC.
Table 4-12 lists the operands accepted by the COUPLE command for the purpose of connecting a virtual NIC to a Guest LAN.
Table 4-12 Operands for the COUPLE command
DEVices devs Determines the number of virtual devices associated with this adapter. For a simulated HiperSockets adapter, devs must be a decimal value between 3 and 3072 (inclusive). For a simulated QDIO adapter, devs must be a decimal value between 3 and 240 (inclusive). The DEFINE NIC command will create a range of virtual devices from vdev to vdev + devs -1 to represent this adapter in your virtual machine. The default value is 3.
CHPID nn A two-digit hexadecimal number that represents the CHPID number the invoker wants to allocate for this simulated adapter. If the requested CHPID number is available, all of the virtual devices belonging to this adapter will share the same CHPID number. This option is only useful if you need to configure a virtual environment with predictable CHPID numbers for your simulated devices.
Operands Description
Operands Description
vdev The base address of the network adapter.
Remember that a virtual NIC can only be coupled to a compatible Guest LAN.
For example, a QDIO NIC cannot be coupled to a Guest LAN of type
“HIPERsockets.”
4.6.8 Example of building a z/VM Guest LAN
We now demonstrate how to build a z/VM Guest LAN in Figure 4-19.
Figure 4-19 Steps to build a z/VM Guest LAN
To build a z/VM Guest LAN, follow these steps:
1. Define a QDIO Guest LAN owned by SYSTEM. This command was run from the MAINT user.
2. Define a Network Interface Card (NIC) of type QDIO. This command was run from Linux guest user LNX23.
3. Couple the NIC to the Guest LAN. This command was also run from LNX23.
Now that we have built a Guest LAN, we can use the CP QUERY LAN command to verify the status of the LAN, as shown in Figure 4-20 on page 105.
ownerid lanname The ownerid is the name of the owner of the Guest LAN (for example, SYSTEM). The lanname is the name of the Guest LAN or Virtual Switch.
Tip: If you choose to use the DEFINE NIC and COUPLE approach instead of the NICDEF User Directory statement, consider adding these two commands into your guest’s PROFILE EXEC file so that they are automatically executed whenever the guest logs on.
Operands Description
DEFINE LAN TSTLAN OWNERID SYSTEM TYPE QDIO 1 LAN SYSTEM TSTLAN is created Ready;
DEFINE NIC 0700 QDIO 2
NIC 0700 is created; devices 0700-0702 defined Ready;
COUPLE 0700 TO SYSTEM TSTLAN 3 NIC 0700 is connected to LAN SYSTEM TSTLAN Ready;
Chapter 4. Networking Overview 105 Figure 4-20 CP QUERY LAN command
In order to display information about the virtual NIC that we have defined, we can use the QUERY NIC CP command, as shown in Figure 4-21. If we use the DETAILS parameter of this command, we can get additional information about the IP addresses bound to this NIC and the amount of data that has been transmitted and received through this interface (TX packets/bytes and RX packets/bytes, respectively).
Notice that there is no IP addressing information and the number of bytes transmitted and received are both zero. Also, the port name value is set to UNASSIGNED. This tells us that the Linux guest has not started using this device for TCP/IP communications.
Figure 4-21 CP QUERY NIC commands
Finally, we said that the virtual NIC simulates an OSA-Express QDIO device.
This is confirmed by using the CP command QUERY VIRTUAL OSA from the guest machine, as shown in Figure 4-22 on page 106.
QUERY LAN TSTLAN ACTIVE
LAN SYSTEM TSTLAN Type: QDIO Active: 1 MAXCONN: INFINITE PERSISTENT UNRESTRICTED MFS: 8192 ACCOUNTING: OFF Ready;
QUERY NIC
Adapter 0700 Type: QDIO Name: UNASSIGNED Devices: 3
Port 0 MAC: 02-00-00-00-00-06 LAN: SYSTEM TSTLAN MFS: 8192 Q NIC DETAILS
Adapter 0700 Type: QDIO Name: UNASSIGNED Devices: 3
Port 0 MAC: 02-00-00-00-00-06 LAN: SYSTEM TSTLAN MFS: 8192 RX Packets: 0 Discarded: 0 Errors: 0
TX Packets: 0 Discarded: 0 Errors: 0 RX Bytes: 0 TX Bytes: 0
Unassigned Devices:
Device: 0700 Unit: 000 Role: Unassigned Device: 0701 Unit: 001 Role: Unassigned Device: 0702 Unit: 002 Role: Unassigned
Figure 4-22 CP QUERY VIRTUAL OSA command
4.6.9 Undoing the definitions
Before moving on to describe how to connect a Linux guest to the Guest LAN, we review how to undo the previous definitions in an orderly fashion. This is only for completeness, and you should not follow these steps unless you no longer want to use the z/VM Guest LAN that you created.
Disconnect from a Guest LAN
Use the CP UNCOUPLE command to disconnect a virtual NIC from a Guest LAN segment. Figure 4-23 illustrates this command.
Figure 4-23 UNCOUPLE command
Remove the virtual NIC from the guest machine
To remove a virtual NIC from a guest machine, use the CP DETACH NIC command. The command disconnects the virtual adapter from the Guest LAN (assuming the UNCOUPLE command has not been invoked) and removes each virtual device that has been created. Figure 4-24 illustrates the DETACH NIC command.
Figure 4-24 DETACH NIC command Q VIRTUAL OSA
OSA 0700 ON NIC 0700 UNIT 000 SUBCHANNEL = 0010 0700 QDIO-ELIGIBLE QIOASSIST NOT AVAILABLE OSA 0701 ON NIC 0700 UNIT 001 SUBCHANNEL = 0011 0701 QDIO-ELIGIBLE QIOASSIST NOT AVAILABLE OSA 0702 ON NIC 0700 UNIT 002 SUBCHANNEL = 0012 0702 QDIO-ELIGIBLE QIOASSIST NOT AVAILABLE
UNCOUPLE 700
NIC 0700 is disconnected from LAN SYSTEM TSTLAN Ready;
DETACH NIC 0700
NIC 0700 is destroyed; devices 0700-0702 detached Ready;
Chapter 4. Networking Overview 107
Remove the Guest LAN
To remove a Guest LAN from the system, use the CP DETACH LAN command. This command removes the LAN from the System LAN table, disconnects any virtual adapters that were using the LAN, and releases system resources associated with the LAN. Figure 4-25 illustrates the DETACH LAN command.
Figure 4-25 DETACH LAN command
4.6.10 Configuring Linux to connect to a Guest LAN
Now that we have created a z/VM Guest LAN and connected our guest’s virtual NIC to that LAN, it can now be used by Linux. Because z/VM creates a virtual network adapter (NIC) that simulates a real OSA-Express or HiperSockets adapter, the configuration Linux for a virtual adapter is the same as it is for a real one. Please refer back to the previous sections of this book that described the configuration of the real adapters:
For a type QDIO network adapter, see “Using OSA-Express with Linux” on page 71.
For a type HIPERSOCKETS network adapter, see “Using HiperSockets with Linux” on page 87.
Recommendations
Linux guests connected to a z/VM Guest LAN must communicate with the physical network through a z/VM TCP/IP or Linux router. This adds both latency
Linux guests connected to a z/VM Guest LAN must communicate with the physical network through a z/VM TCP/IP or Linux router. This adds both latency