SET NIC

Read syntax diagramSkip visual syntax diagram SET NIC Privilege Class BPrivilege Class G
Privilege Class B
Read syntax diagramSkip visual syntax diagram 1 USERid*USERiduserid vdev NOPROmiscuousPROmiscuousMACIDSYStemUSErmacidMACProtectUNSPECifiedOFFON
Privilege Class G
Read syntax diagramSkip visual syntax diagram vdev NOPROmiscuousPROmiscuous
Notes:
  • 1 If SET NIC is executed with the AT command, the USERID userid operands are required.

Authorization

Privilege Class: B, G

Purpose

Use SET NIC to perform various settings for a specific network device.

A class B user can:
  • Toggle promiscuous mode ON or OFF for a specified user ID's virtual network data device. In order for the guest to participate in promiscuous mode, the NIC must be authorized for promiscuous mode and coupled to a guest LAN or virtual switch.
  • Specify the mechanism to be used when assigning a MAC address to a real or simulated network data device.
  • Enable or disable MAC address protection for a specific network data device. Enabling MAC address protection ensures only the MAC address assigned by z/VM® or the system administrator is used when a guest establishes a layer 2 (ETHERNET) network connection.

A class G user can only toggle promiscuous mode ON and OFF for a particular virtual network data device.

Operands

USERid userid
USERid *
is the user ID of the virtual machine for which you want to set NIC settings. If omitted or specified as an asterisk (*), CP uses the user ID of the virtual machine issuing the command. The userid specified must be logged on.
vdev
is the virtual device number to be modified. Typically, this is required to be the device number of what is the data device (or what will be the data device) for the NIC.
NOPROmiscuous
PROmiscuous
specifies if promiscuous mode is to be toggled ON or OFF. Current Linux® distributions enable or disable Promiscuous mode as part of the device driver alleviating the need for this SET command. Authorization to enable Promiscuous mode is still required using SET VSWITCH.
MACID SYStem
MACID [USEr] macid
specifies the mechanism to be used when assigning a MAC address to a real or simulated network data device.

Specify SYSTEM to have a locally administered MAC address automatically assigned to this device number. The first 3 bytes (6 hexadecimal digits) of the MAC address will be the MACPREFIX value set on the VMLAN system configuration statement and the last 3 bytes will be the next available number in the MACIDRANGE SYSTEM range specified on the VMLAN statement.

Specify USER macid to have a static MAC address assigned. The macid value must be a unique 3-byte (6 hexadecimal digits) identifier. It will be appended to the system MACPREFIX or USERPREFIX value set on the VMLAN system configuration statement to form a unique user-defined locally administered MAC address for this device.

When MACPREFIX and USERPREFIX are set to the identical value, the value specified for macid must be in the USER subset of the MACIDRANGE SYSTEM range.

When MACPREFIX and USERPREFIX are set to different values, the MACIDRANGE settings are ignored. This allows the entire range of MACIDs (000001 - FFFFFF) to be used by either the system or the user when making MAC address assignments.

Use SET NIC with the SYSTEM operand to remove a previously assigned USER MACID.

MACProtect UNSPECified|ON|OFF
turns MAC address protection on or off for the specified network device number. Turning MAC address protection on prevents a guest from using a MAC address that is not assigned to the user's network device. MAC address protection is valid only for simulated network devices when coupled to an ETHERNET virtual switch or guest LAN. MAC address protection is not supported for HiperSockets Bridge Capable guest ports that are being bridged by this virtual switch.

There are three levels of inheritance used when determining the MAC address protection level for a MAC address assigned to a network device. The highest is the system level, followed by the virtual switch or guest LAN level. The lowest level is the protection set for a specific network data device.

The MAC address protection level assigned is determined first by the device, then virtual switch or guest LAN and lastly the system level. If MAC address protection is set at the device level using the SET NIC CP command, then its current setting is used. When the device is set to UNSPECIFIED, it will inherit the MACPROTECT setting of the virtual switch. When the virtual switch MACPROTECT setting is set to UNSPECIFIED, the SYSTEM's MAC address protection specified by the SET VMLAN CP command or VMLAN configuration statement is assigned.

UNSPECified
allows the MAC address protection to be determined by the next higher level. UNSPECIFIED is the default setting for a network device.
OFF
will set the device MAC address protection level to unrestricted or off. The MAC address assigned to this device is not protected. A guest can override the assigned MAC address when establishing a network connection.
ON
will set the device MAC address protection level to restricted or on. The MAC address assigned to this device is protected and cannot be overridden by the guest when establishing a network connection.

Usage Notes

  1. The virtual device number (vdev) does not have to exist to set a MACID or the MACPROTECT option. In this case, the option will be preassigned and will be inherited when the virtual NIC is created comprising the device number.
  2. A SET NIC vdev MACID command has no effect when a real device is attached as vdev, unless the device driver uses VM MAC address support. That is, the device driver must make a call to subcode X'30' of Diagnose X'26C' to retrieve a MAC address from CP and use that MAC address on link initialization.

    The z/VM TCP/IP stack's OSD device driver provides this support for a link defined to use the ETHERNET transport type. The link must be restarted in order to use the new MAC address. Until the link is restarted, a QUERY VIRTUAL OSA or QUERY VIRTUAL NIC command issued for the device shows a status of Pending for the newly assigned MAC address.

  3. A SET NIC vdev MACID command sets the MAC ID for a virtual device. For the z/VM OSD device driver, the link must be restarted in order to use the newly assigned MAC address, unless it is SET before the link is first initialized..
  4. For the z/VM TCP/IP stack, the network data device number is the first device number in a network adapter triplet. That is, a DEFINE NIC 501 creates an adapter with devices 501, 502, and 503. 501 is the data device number and should be used in the SET NIC command. (This information applies to z/VM stacks with code from release z/VM 5.4.0 and later.)

Responses

Response 1:

Promiscuous Mode has been enabled for device vdev

Response 2:

Promiscuous Mode has been disabled for device vdev

Response 3:

MAC address macaddr has been assigned to device vdev

Response 4:

A MAC address is automatically assigned to device vdev

are the normal responses from this command.

Messages

  • HCP006E Invalid device type - vdev.
  • HCP0045E userid not logged on
  • HCP022E A virtual device number was not supplied or it was invalid
  • HCP026E Operand missing or invalid
  • HCP040E Device vdev does not exist.
  • HCP2795E Promiscuous Mode can not be used with a HiperSockets device.
  • HCP2795E Promiscuous Mode must be used on a data device
  • HCP2850E MACID is not set for vdev. MAC address macaddr is already in use [by user ID]
  • HCP2850E MACID is not set for vdev. Suffix for MAC address macaddr is not within USER MACIDRANGE.
  • HCP2850E MACID is not set for vdev. SSI cluster mode not stable.
  • HCP2850E MACID is not set for vdev. Guest relocation active.
  • HCP3022E SET NIC not performed; MACPROTECT is not valid for the IP transport type.
  • HCP6704E Missing token at end of line