3.1.5.11 networkInterfaces

  • Article

The networkInterfaces resource specifies the configuration of either a host virtual network interface card (host vNIC) or a virtual server NIC (VMNIC).

It is invoked through the following URI.

 https://<url>/networking/v1/networkInterfaces/{resourceId}

url: The address or name of the REST server of the Network Controller.

resourceId: The identifier for the specific resource within the resource type. See section 2.2.3.4 for more details.

Note  The server MAY support additional versions, v1 or later, in the URI.

The following HTTP methods can be performed on this resource.

HTTP method

Section

Description

PUT

3.1.5.11.1.1

Create a new networkInterfaces resource or update an existing networkInterfaces resource.

GET

3.1.5.11.1.2

Get one networkInterfaces resource.

GET ALL

3.1.5.11.1.3

List all networkInterfaces resources in the Network Controller.

DELETE

3.1.5.11.1.4

Delete a networkInterfaces resource.

The following property elements are valid.

Element name

Type

Description

etag

Read-only

Specified in Common JSON Elements, section 2.2.2.

provisioningState

Read-only

Specified in Common JSON Elements, section 2.2.2.

dnsSettings

Optional

Indicates the DNS settings of this network interface.

dnsSettings.dnsServers

Optional

Indicates an array of IP Addresses that this network interface resource will use for the DNS servers.

ipConfigurations

Read-only

Indicates an array of IP configurations that are contained in the network interface.  See section 3.1.5.11.2 for full details on this element.

isHostVirtualNetworkInterface

Optional

TRUE – this is a host virtual network interface card (host vNIC).

FALSE – this is a virtual server NIC (VMNIC) (default).

Cannot be changed after creation.

internalDnsNameLabel

Optional

Determines the name that will be registered in the internal Domain Name Service (iDNS) when the iDnsServer resource is configured. The host address record that contains the internalDnsNameLabel string is in addition to that which contains the virtual machine host name string. The names in the two records are the internalDnsNameLabel and the virtual machine hostname, respectively, followed by the virtual network resource ID, which is followed by the global zone name.

The internalDnsNameLabel can be set only for primary interfaces (meaning interfaces for which the isPrimary property is TRUE).

When the iDnsServer is configured and the internalDnsNameLabel is specified, it is guaranteed that the label will be registered.

The virtual machine guest operating system might not provide a host name part of the DHCP negotiation.

isPrimary

Optional

TRUE – this is the primary interface and the default value if the property is not set.

FALSE - this is a secondary interface.

The distinction is important if a virtual machine has more than one network interface.

This property cannot be changed after the resource is created.

configurationState

Optional

Read-only

The configurationState for network interfaces contains an id field that is set to the instanceId of the network interface. See specification in section 2.2.4.

More details are given in the section for the GET operation section 3.1.5.11.1.2.

isMultitenantStack

Optional

TRUE – Allows the NIC to be part of multiple virtual networks.

FALSE – the opposite (default).

server

Read-only

Indicates a reference to the servers resource for the machine that is currently hosting the virtual machine to which this network interface belongs.

portSettings

See following Port Settings table.

privateMacAddress

Optional

Indicates the private MAC address of this network interface. Only set if privateMacAllocationMethod is set to Static.

privateMacAllocationMethod

Required

Indicates the allocation scheme of the MAC for this network interface.  Valid values are Static or Dynamic.

serviceInsertionElements

Read-only

Optional

Indicates an array of serviceInsertions resources that this networkInterfaces resource is part of.

securityTags

Optional

An array of securityTags resources associated with this network interface.

This property is supported in URI version v5 or later.

counters

Read-only

Optional

Array of ResourceCounter structures (section 3.1.1.1). The supported properties are documented in the following counters properties table.

This property is supported with URI version v2 or later.

Port Settings

Element name

Type

Description

macSpoofing

Optional

Specifies whether virtual machines can change the source MAC address in outgoing packets to one not assigned to them.
Allowed values are
Enabled - allows the virtual machine to use a different MAC address, and
Disabled -  allows the virtual machine to use only the MAC address assigned to it.

arpGuard

Optional

Specifies whether ARP guard is enabled or not. ARP guard when enabled will allow only the IP assigned to the network interface and any addresses specified in arpFilter to pass through the port. Allowed values are Enabled or Disabled.

arpFilter

Optional

A string of comma separated IP addresses. This parameter is ignored and not used.

dhcpGuard

Optional

Specifies whether to drop DHCP messages from a virtual machine claiming to be a DHCP server. Allowed values are
Enabled -  drops DHCP messages because the virtualized DHCP server is considered untrusted, or
Disabled -  allows the message to be received because the virtualized DHCP server is considered trustworthy.

stormLimit

Optional

Specifies the number of broadcast, multicast, and unknown unicast packets per second a virtual machine is allowed to send through the specified virtual network adapter. Broadcast, multicast, and unknown unicast packets beyond the limit during that one second interval are dropped. A value of zero means there is no limit.

portFlowLimit

Optional

Specifies the maximum number of flows that can be executed for the port.  A value of blank or zero means there is no limit.

vmqWeight

Optional

Specifies whether virtual machine queue (VMQ) is to be enabled on the virtual network adapter. The relative weight describes the affinity of the virtual network adapter to use VMQ. The range of value is typically from 0 through 100. Specify 0 to disable VMQ on the virtual network adapter.

iovWeight

Optional

Specifies whether single-root I/O virtualization (SR-IOV) is to be enabled on this virtual network adapter. The relative weight sets the affinity of the virtual network adapter to the assigned SR-IOV virtual function. The range of the value is typically from 0 through 100. Specify 0 to disable SR-IOV on the virtual network adapter.

iovInterruptModeration

Optional

Specifies the interrupt moderation value for a single-root I/O virtualization (SR-IOV) virtual function assigned to a virtual network adapter. Allowed values are Default, Adaptive, Off, Low, Medium, and High.

Default - the value is determined by the physical network adapter vendor's setting.

Adaptive - the interrupt moderation rate will be based on the runtime traffic pattern.

iovQueuePairsRequested

Optional

Specifies the number of hardware queue pairs to be allocated to an SR-IOV virtual function. If receive-side scaling (RSS) is required, and if the physical network adapter that binds to the virtual switch supports RSS on SR-IOV virtual functions, then more than one queue pair is required. Allowed values range from 1 to 4294967295.

QosSettings

Optional

The following QOS Settings can be configured; all are optional:

outboundReservedValue:
If outboundReservedMode is Absolute then the value indicates the bandwidth, in Mbps, guaranteed to the virtual port for transmission (egress).
If outboundReservedMode is Weight then the value indicates the weighted portion of the bandwidth guaranteed.

outboundMaximumMbps:
Indicates the maximum permitted send-side bandwidth, in Mbps, for the virtual port (egress).

InboundMaximumMbps:
Indicates the maximum permitted receive-side bandwidth for the virtual port (ingress) in Mbps.

enableHardwareLimits:
If this is set to TRUE, hardware QOS limits is enabled. When this property is TRUE, QOS is done in hardware if it supports it. Otherwise, QOS is done in software.
This property is supported with URI version v4 or later.

configurationState

Optional

Read-only

See specification in section 2.2.4.

More details are given in the section for the GET operation section 3.1.5.11.1.2.

Properties supported in the counters for the networkInterfaces resource. The following property elements are valid where source is VirtualNetworkManager and category is Performance.

Name

Unit

Meaning

TotalPacketsOut

Decimal

Total Packets outgoing from Network Interface.

TotalPacketsIn

Decimal

Total Packets incoming to Network Interface.

DropPacketsOut

Decimal

Total Packets outgoing that are dropped by Network Interface.

DropPacketsIn

Decimal

Total Packets incoming that are dropped by Network Interface.

DropNoRuleMatchPacketsOut

Decimal

Total outgoing packets dropped by virtual filtering platform on the Network Interface which does not match any configured rules.

DropNoRuleMatchPacketsIn

Decimal

Total incoming packets dropped by virtual filtering platform on the Network Interface which does not match any configured rules.

DropAclPacketsOut

Decimal

Total outgoing packets dropped by virtual filtering platform on the network interface due to Access Control Lists configuration.

DropAclPacketsIn

Decimal

Total incoming packets dropped by virtual filtering platform on the network interface due to Access Control Lists configuration.

DropForwardingPacketsOut

Decimal

Total outgoing forwarding packets dropped by virtual filtering platform.

DropForwardingPacketsIn

Decimal

Total incoming forwarding packets dropped by virtual filtering platform.

TcpSynPacketsOut

Decimal

Total outgoing TCP SYN packets processed by virtual filtering platform on the network interface.

TcpSynPacketsIn

Decimal

Total incoming TCP SYN packets processed by virtual filtering platform on the network interface.

TcpFinPacketsOut

Decimal

Total outgoing TCP FIN packets processed by virtual filtering platform on the network interface.

TcpFinPacketsIn

Decimal

Total incoming TCP FIN packets processed by virtual filtering platform on the network interface.

TcpResetPacketsOut

Decimal

Total outgoing TCP RESET packets processed by virtual filtering platform on the network interface.

TcpResetPacketsIn

Decimal

Total incoming TCP RESET packets processed by virtual filtering platform on the network interface.