NICDEF

Read syntax diagramSkip visual syntax diagramDIRMaintPrefix Keywords1 NICDEF vdev DELETETYPEHIPERsocketsQDIONICDEF Options
NICDEF Options
Read syntax diagramSkip visual syntax diagramDEVicesdevsLANownerid*SYSTEMlannameSYSTEMswitchnmPORTNUMberxxxxPORTTypeACCESSTRUNKPQUPLINKTXLOWNORMALHIGHNOPROmiscuousPROmiscuousVLANvidsetCHPIDhhMACIDmacaddress
Notes:
  • 1 For more information on prefix keywords, see the DIRMAINT EXEC.

Purpose

Use the NICDEF operand of the DIRMAINT command to create a virtual HiperSockets or QDIO adapter in the virtual machine, and to optionally connect it to a VM LAN or z/VM® Virtual Switch.

Operands

DELETE
will remove the statement or group of statements from the directory.
vdev
is the base (or first) device address in a series of virtual I/O devices that belong to the same unit.
TYPE
specifies the type of NIC adapter to be created, specifically the hardware and protocol that the adapter will emulate. Note that TYPE is a required keyword and it must be the first keyword specified. If LAN is also specified, an attempt will be made to couple the adapter to the specified ownerid lanname.

The values that may be specified for TYPE are as follows:

HIPERsockets
defines this adapter as a simulated HiperSockets NIC. This adapter will function like a HiperSockets internal adapter (model 1732-05). A HiperSockets NIC can function without a guest LAN connection, or it can be coupled to a HiperSockets guest LAN. An error will result if you attempt to connect a simulated HiperSockets adapter to a virtual switch.
QDIO
defines this adapter as a simulated QDIO NIC. This adapter will function like an OSA Direct Express® (QDIO) adapter (model 1731-01). A QDIO NIC is functional only when it is coupled to a QDIO guest LAN or to a QDIO, IEDN, or INMN virtual switch. A QDIO adapter can be coupled to an IEDN or INMN virtual switch only when the owning user ID is authorized by the system administrator, by specifying OSDSIM on the SET VSWITCH command.
DEVICES devs
is the number (decimal) of virtual I/O devices to be created for a simulated Network Interface Card (NIC). This number is evaluated during LOGON processing. For a simulated HiperSockets adapter, devs must be a decimal value between 3 and 3,072 (inclusive). For a simulated QDIO, IEDN, or INMN adapter, devs must be a decimal value between 3 and 240 (inclusive). If the devs value is omitted, the default for either HiperSockets, QDIO, IEDN, or INMN is three (3) devices.
LAN ownerid|*lanname
identifies a virtual LAN segment for an immediate connection to the Network Interface Card (NIC). When ownerid is specified as an asterisk (*), it is resolved as the user ID of the current virtual machine. When the LAN operand is omitted, the adapter is left in the default (uncoupled) state. When LAN ownerid lanname is identified in this statement or another with the same vdev, the adapter is connected to the designated virtual LAN segment automatically.

Ownerid may be specified as SYSTEM, indicating the virtual LAN segment is system-owned.

LAN SYSTEM switchnm
identifies a z/VM Virtual Switch for an immediate connection to the Network Interface Card (NIC). When the LAN operand is omitted, the adapter is left in the default (uncoupled) state. When LAN SYSTEM switchnm is identified in this statement or another with the same vdev, the adapter is connected to the designated z/VM Virtual Switch automatically.

LAN SYSTEM switchnm is only valid for QDIO adapters.

CHPID hh
is a two digit hexadecimal number that represents the Channel Path ID (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 macaddress
is a unique identifier (up to six hexadecimal digits) used as part of the adapter MAC address for a QDIO or HiperSockets type NIC adapter. A MAC address for a device on an IEDN or INMN network can be assigned only by the Unified Resource Manager. Therefore, a user-defined MAC address is not allowed on these networks. Specifying a MACID for a type IEDN or INMN adapter would prevent the adapter from being added to the virtual I/O configuration of a guest.

During LOGON, your MACID (three bytes) is appended to the system MACPREFIX or USERPREFIX (three bytes) to form a unique MAC address for this adapter. If MACID is omitted from this definition, CP will generate a unique identifier for this adapter. If the specified MACID is already in use, this adapter will not be defined. To correct this situation, you must eliminate the conflicting device or select a different MACID.

PORTNUMber portnum
is the network-specific port number (a decimal number in the range 1-2048) to be used when this virtual NIC is connected to the NICDEF LAN.
PORTType ACCESS|TRUNK
is the network-specific port type to determine whether VLAN tags should be visible to the guest.
ACCESS
defines a connection that exchanges untagged frames with the guest. PORTTYPE ACCESS is only valid when the interface is configured for a single VLAN.

CP adds (or removes) VLAN tags as necessary.

TRUNK
defines a connection that exchanges tagged frames with the guest. PORTTYPE TRUNK is the only valid option when the interface is configured for multiple VLAN groups.
PQUPLINKTX LOW | NORMAL | HIGH
For a virtual switch with priority queuing enabled, PQUPLINKTX sets the priority for all packets sent from a NIC's network connection to an external network. If PQUPLINKTX is not specified, all outbound traffic to the external network is sent at a NORMAL priority on the virtual switch uplink port. If PQUPLINKTX is configured for a virtual switch without priority queuing enabled, the setting is saved and used if priority queuing is enabled at a later time.

For a HiperSockets type NIC, the PQUPLINKTX operand is ignored.

LOW
specifies that outbound traffic to the external network is sent at a low priority. This traffic uses the low priority queue, which is serviced less frequently than the normal and high priority queues.
NORMAL
specifies that outbound traffic to the external network is sent at a normal priority. This traffic uses the normal priority queue, which is serviced less frequently than the high priority queue but more frequently than the low priority queue.
HIGH
specifies that outbound traffic to the external network is sent at a high priority. This traffic uses the high priority queue, which is serviced more frequently than the normal or low priority queues.
PROMISCUOUS | NOPROMISCUOUS
when PROMISCUOUS is specified, the guest is authorized to enable promiscuous mode (allowing this interface to receive a copy of every network packet on the simulated LAN segment).
VLAN vidset
defines the VLAN ID set. The vidset may be a simple VLAN ID (for example, "VLAN 1"), a VLAN range (for example, "VLAN 10-19"), or a complex set (for example, "VLAN 1 10-19 100-109").

Usage Notes

  1. You may use one or more of the prefix keywords (REQuest, TOsys, ASuser, BYuser, PRESET, FORuser, ATnode, NODIRectxa) with this command. These prefix keywords may be specified in any order, but each keyword may only be specified once. The FOR and AT prefix keywords do not apply to this command. They are accepted without error, but otherwise ignored.
  2. If all of the parameters are needed for a given device definition, then the resulting directory statement will not fit within a single directory record. The statement must be completely specified, however, within a single DirMaint request. DirMaint will therefore split the statement and continue it onto subsequent records by repeating the statement name and device address, followed by the additional parameters, as needed. Such continuation records will be consecutive. Intervening comments and blank lines are not supported.
  3. When adding a new directory entry containing NICDEF statements, or when using a DIRM REPLACE command to add a NICDEF statement to a directory entry, note that the NICDEF statements for a given device address must be consecutive records with no intervening comment lines or blank records.
  4. The LAN operand is required when a virtual switch-specific operand (PORTNUMBER, PORTTYPE, VLAN, PQUPLINKTX, PROMISCUOUS or NOPROMISCUOUS) is specified. Furthermore, the use of a virtual switch-specific operand restricts the virtual NIC to the designated network. When the virtual NIC is configured for a specific network, the CP COUPLE command does not allow a connection to any other network.
  5. With Directory Network Authorization (DNA), a system administrator can configure and consolidate a virtual NIC device and its network properties in a secure, centralized location in z/VM's user directory.
    The following NICDEF operands support DNA:
    • PORTNUMBER portnum
    • PORTTYPE ACCESS | TRUNK
    • VLAN vidset
    • PROMISCUOUS | NO PROMISCUOUS
    • PQUPLINKTX priority

    By default, Directory Network Authorization (DNA) is enabled for use on z/VM but can be turned off dynamically by the system administrator with the SET VMLAN DNA CP command, or during IPL with the VMLAN DNA system configuration statement. When DNA is disabled, all DNA operands are ignored on the NICDEF statement. For more information on DNA, see z/VM: Connectivity.