Managed Object - DistributedVirtualSwitch

Property of: DistributedVirtualSwitchInfo, DistributedVirtualSwitchManagerDvsProductSpec, DistributedVirtualSwitchManagerHostDvsMembershipFilter, DVPortgroupConfigInfo, DvsEventArgument
Parameter to: MergeDvs_Task, QueryCompatibleHostForExistingDvs, QueryDvsConfigTarget
Returned by: CreateDVS_Task, QueryDvsByUuid
Extended by: VmwareDistributedVirtualSwitch
Extends: ManagedEntity
See also: DistributedVirtualPort, DistributedVirtualPortgroup, DistributedVirtualSwitchPortCriteria, DistributedVirtualSwitchProductSpec, DVPortConfigSpec, DVPortgroupConfigSpec, DVSCapability, DVSConfigInfo, DVSConfigSpec, DVSNetworkResourcePool, DVSNetworkResourcePoolConfigSpec, DVSSummary, HostSystem
Since: vSphere API 4.0

Managed Object Description

The interface to the distributed virtual switch objects.

Properties

Name	Type	Description
capability	DVSCapability	The capability of the switch. Queried against hosts, the property should always return configModificationSupported as false.
config	DVSConfigInfo	The configuration of the switch.
networkResourcePool*	DVSNetworkResourcePool[]	The network resource pool information for the switch. *Since* vSphere API 4.1
portgroup*	ManagedObjectReference[] to a DistributedVirtualPortgroup[]	The portgroups that are defined on the switch.
summary	DVSSummary	The summary of the switch.
uuid	xsd:string	The generated UUID of the switch. Unique across vCenter Server inventory and instances.
Properties inherited from ManagedEntity
alarmActionsEnabled, configIssue, configStatus, customValue, declaredAlarmState, disabledMethod, effectiveRole, name, overallStatus, parent, permission, recentTask, tag, triggeredAlarmState
Properties inherited from ExtensibleManagedObject
availableField, value

*May not be present

Methods

Methods defined in this Managed Object
AddDVPortgroup_Task, AddNetworkResourcePool, EnableNetworkResourceManagement, FetchDVPortKeys, FetchDVPorts, MergeDvs_Task, MoveDVPort_Task, PerformDvsProductSpecOperation_Task, QueryUsedVlanIdInDvs, ReconfigureDVPort_Task, ReconfigureDvs_Task, RectifyDvsHost_Task, RefreshDVPortState, RemoveNetworkResourcePool, UpdateDvsCapability, UpdateNetworkResourcePool
Methods inherited from ManagedEntity
Destroy_Task, Reload, Rename_Task
Methods inherited from ExtensibleManagedObject
setCustomValue

AddDVPortgroup_Task

Add a DistributedVirtualPortgroup to the switch.

Required Privileges: DVPortgroup.Create

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the DistributedVirtualSwitch used to make the method call.
spec	DVPortgroupConfigSpec[]	The specification for the portgroup.

Return Value

Type	Description
ManagedObjectReference to a Task

Faults

Type	Description
DuplicateName
DvsFault	Thrown if operation fails on any host or if there are other update failures.
DvsNotAuthorized	Thrown if login-session's extension key does not match the switch's configured extensionKey.
InvalidName
NotSupported	Thrown if called directly on a host.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

AddNetworkResourcePool

Add a network resource pool.

Required Privileges: DVSwitch.ResourceManagement
Since: vSphere API 5.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the DistributedVirtualSwitch used to make the method call.
configSpec	DVSNetworkResourcePoolConfigSpec[]	the network resource pool configuration specification.

Return Value

Type	Description
None

Faults

Type	Description
DvsFault	Thrown if operation fails on any host or if there are other update failures.
DvsNotAuthorized	Thrown if login-session's extension key does not match the switch's configured extensionKey.
InvalidName
NotSupported	Thrown if network I/O control is not supported on the vSphere Distributed Switch.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="AddNetworkResourcePool" type="vim25:AddNetworkResourcePoolRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="AddNetworkResourcePoolResponse">
            <complexType/>
         </element>

EnableNetworkResourceManagement

Enable/Disable network I/O control on the vSphere Distributed Switch.

Required Privileges: DVSwitch.ResourceManagement
Since: vSphere API 4.1

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the DistributedVirtualSwitch used to make the method call.
enable	xsd:boolean	If true, enables I/O control. If false, disables network I/O control.

Return Value

Type	Description
None

Faults

Type	Description
DvsFault	Thrown if the enabling/disabling fails.
DvsNotAuthorized	Thrown if login-session's extension key does not match the switch's configured extensionKey.
NotSupported	Thrown if network I/O control is not supported on the vSphere Distributed Switch.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="EnableNetworkResourceManagement" type="vim25:EnableNetworkResourceManagementRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="EnableNetworkResourceManagementResponse">
            <complexType/>
         </element>

FetchDVPortKeys

Return the keys of ports that meet the criteria. Queried against host, the property reports only the connected ports currently on the host.

Required Privileges: System.Read

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the DistributedVirtualSwitch used to make the method call.
criteria*	DistributedVirtualSwitchPortCriteria	The port selection criteria. If unset, the operation returns the keys of all the ports in the switch.

*Need not be set

Return Value

Type	Description
xsd:string[]

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FetchDVPortKeys" type="vim25:FetchDVPortKeysRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FetchDVPortKeysResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>

FetchDVPorts

Return the ports that meet the criteria.

Required Privileges: System.Read

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the DistributedVirtualSwitch used to make the method call.
criteria*	DistributedVirtualSwitchPortCriteria	The port selection criteria. If unset, the operation returns the keys of all the ports in the portgroup.

*Need not be set

Return Value

Type	Description
DistributedVirtualPort[]

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FetchDVPorts" type="vim25:FetchDVPortsRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FetchDVPortsResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:DistributedVirtualPort" minOccurs="0" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>

MergeDvs_Task

Merge an existing DistributedVirtualSwitch (source) to this switch (destination). The host members and the connected entity of the source switch will be transferred to the destination switch. This operation disconnects the entities from the source switch, tears down its host proxy VirtualSwitches, creates new ones for the destination switch, and reconnects the entities to the destination switch.

In summary, this operation does the following:

Adds the maxPorts of the source switch to the maxPorts of the destination switch.
The host members of the source switch leave the source switch and join the destination switch with the same Physical NIC and VirtualSwitch (if applicable). A set of new uplink ports, compliant with the uplinkPortPolicy, is created as the hosts join the destination switch.
The portgroups on the source switch are copied over to destination switch, by calculating the effective default port config and creating a portgroup of the same name in the destination switch. If the name already exists, the copied portgroup uses names like "Copy of switch-portgroup-name" scheme to avoid conflict. The same number of ports are created inside each copied portgroup.
The standalone DVPorts are not copied, unless there is a Virtual Machine or host Virtual NIC connecting to it. In that case, the operation calculates the effective port config and creates a port in the designation DVS with the same name. Name conflict is resolved by numbers like "original-port-name(1)". The uplink ports are not copied over.
The Virtual Machine host Virtual NICs are disconnected from the source switch and reconnected with the destination switch, either to the copied standalone port or portgroup.
(Applicable to VmwareDistributedVirtualSwitch object only) Unless the PVLAN map contains exactly the same entries between the source and destination switches, the operation raises a fault if pvlanId is set in any port, portgroup, or switch that will be copied.

Required Privileges: DVSwitch.Modify

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the DistributedVirtualSwitch used to make the method call.
dvs P	ManagedObjectReference to a DistributedVirtualSwitch	The switch (source) to be merged

P Required privilege: DVSwitch.Delete

Return Value

Type	Description
ManagedObjectReference to a Task

Faults

Type	Description
DvsFault	Thrown if operation fails on any host or if there are other update failures.
DvsNotAuthorized	Thrown if login-session's extension key does not match the switch's configured extensionKey.
InvalidHostState
NotFound
NotSupported	Thrown if called directly on a host.
ResourceInUse	Thrown if failed to delete the source switch
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

MoveDVPort_Task

Move the ports out of their current portgroup into the specified portgroup. If the moving of any of the ports results in a violation of the portgroup policy, or type of the source or destination portgroup, the operation raises a fault. A conflict port cannot be moved.

Required Privileges: DVSwitch.Modify

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the DistributedVirtualSwitch used to make the method call.
portKey	xsd:string[]	The keys of the ports to be moved into the portgroup.
destinationPortgroupKey*	xsd:string	The key of the portgroup to be moved into. If unset, the port will be moved under the switch.

*Need not be set

Return Value

Type	Description
ManagedObjectReference to a Task

Faults

Type	Description
ConcurrentAccess
DvsFault	Thrown if operation fails on any host or if there are other update failures.
DvsNotAuthorized	Thrown if login-session's extension key does not match the switch's configured extensionKey.
NotFound
NotSupported	Thrown if called directly on a host.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

PerformDvsProductSpecOperation_Task

This method updates the DistributedVirtualSwitch product specifications.

Required Privileges: DVSwitch.Modify

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the DistributedVirtualSwitch used to make the method call.
operation	xsd:string	The operation. See DistributedVirtualSwitchProductSpecOperationType for valid values. For VmwareDistributedVirtualSwitch, only upgrade is valid.
productSpec*	DistributedVirtualSwitchProductSpec	The product info of the implementation.

*Need not be set

Return Value

Type	Description
ManagedObjectReference to a Task

Faults

Type	Description
DvsFault	Thrown if operation fails on any host or if there are other update failures.
DvsNotAuthorized	Thrown if login-session's extension key does not match the switch's configured extensionKey.
InvalidState
NotSupported	Thrown if called directly on a host.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress

QueryUsedVlanIdInDvs

Return the used VLAN ID (PVLAN excluded) in the switch.

Required Privileges: System.Read

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the DistributedVirtualSwitch used to make the method call.

Return Value

Type	Description
xsd:int[]

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryUsedVlanIdInDvs" type="vim25:QueryUsedVlanIdInDvsRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryUsedVlanIdInDvsResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="xsd:int" minOccurs="0" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>

ReconfigureDVPort_Task

Reconfigure individual ports.

Required Privileges: DVSwitch.PortConfig

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the DistributedVirtualSwitch used to make the method call.
port	DVPortConfigSpec[]	The specification of the ports.

Return Value

Type	Description
ManagedObjectReference to a Task

Faults

Type	Description
ConcurrentAccess
DvsFault	Thrown if operation fails on any host or if there are other update failures.
DvsNotAuthorized	Thrown if login-session's extension key does not match the switch's configured extensionKey.
InvalidArgument	Thrown if the array have different elements for the same port.
NotFound
NotSupported	Thrown if called directly on a host or if the switch implementation doesn't support this API or if the spec includes settings for any vSphere Distributed Switch feature that is not supported on this switch.
ResourceInUse
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

ReconfigureDvs_Task

Reconfigure the switch.

Reconfiguring the switch may require any of the following privileges, depending on what is being changed:

DVSwitch.PolicyOp if policy is set.
DVSwitch.PortSetting if defaultPortConfig is set.
DVSwitch.HostOp if policy is set. The user will also need the Host.Config.Network privilege on the host.
DVSwitch.Vspan if vspanConfigSpec is set.
DVSwitch.Modify for anything else.

Required Privileges: Dynamic - See discussion above

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the DistributedVirtualSwitch used to make the method call.
spec	DVSConfigSpec	The configuration of the switch

Return Value

Type	Description
ManagedObjectReference to a Task

Faults

Type	Description
AlreadyExists
ConcurrentAccess
DuplicateName
DvsFault	Thrown if operation fails on any host or if there are other update failures.
DvsNotAuthorized	Thrown if login-session's extension key does not match the switch's configured extensionKey.
InvalidArgument	Thrown if any of the hosts being added lack support for any of the overlay classes of the switch's overlay instances.
InvalidName
InvalidState
LimitExceeded
NotFound
NotSupported	Thrown if called directly on a host or if the spec includes settings for any vNetwork Distributed Switch feature that is not supported on this switch.
ResourceInUse
ResourceNotAvailable	Thrown if there is no port available in the portgroup
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
VspanDestPortConflict	Thrown if a dvPort is used as desination ports in multiple Distributed Port Mirroring sessions.
VspanPortConflict	Thrown if dvPort is used as both the transmitted source and destination ports in Distributed Port Mirroring sessions.
VspanPromiscuousPortNotSupported	Thrown if a promiscuous port is used as transmitted source or destination in the Distributed Port Mirroring sessions.
VspanSameSessionPortConflict	Thrown if a dvPort is used as both the source and destination in the same Distributed Port Mirroring session.

RectifyDvsHost_Task

Deprecated. as of vSphere API 5.0. Use RectifyDvsOnHost_Task instead. Update the switch configuration on the host to bring them in sync with the current configuration in vCenter Server.

deprecated as of vSphere API 5.0. Use RectifyDvsOnHost_Task instead. Update the switch configuration on the host to bring them in sync with the current configuration in vCenter Server.

Required Privileges: System.Read

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the DistributedVirtualSwitch used to make the method call.
hosts*	ManagedObjectReference[] to a HostSystem[]	The hosts to be rectified.

*Need not be set

Return Value

Type	Description
ManagedObjectReference to a Task

Faults

Type	Description
DvsFault	Thrown if operation fails on any host or if there are other update failures.
NotFound
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

RefreshDVPortState

Refresh port states.

Required Privileges: System.Read

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the DistributedVirtualSwitch used to make the method call.
portKeys*	xsd:string[]	The keys of the ports to be refreshed. If not set, all port states are refreshed.

*Need not be set

Return Value

Type	Description
None

Faults

Type	Description
DvsFault	Thrown if operation fails on any host or if there are other update failures.
NotFound
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RefreshDVPortState" type="vim25:RefreshDVPortStateRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RefreshDVPortStateResponse">
            <complexType/>
         </element>

RemoveNetworkResourcePool

Remove a network resource pool.

Required Privileges: DVSwitch.ResourceManagement
Since: vSphere API 5.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the DistributedVirtualSwitch used to make the method call.
key	xsd:string[]	the network resource pool key

Return Value

Type	Description
None

Faults

Type	Description
DvsFault	Thrown if operation fails on any host or if there are other update failures.
DvsNotAuthorized	Thrown if login-session's extension key does not match the switch's configured extensionKey.
InvalidName	Thrown if the name of the resource pool is invalid.
NotFound	Thrown if the resource pool does not exist on the dvs.
NotSupported	Thrown if network I/O control is not supported on the vSphere Distributed Switch.
ResourceInUse	Thrown if network resource pool is associated with a network entity
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RemoveNetworkResourcePool" type="vim25:RemoveNetworkResourcePoolRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RemoveNetworkResourcePoolResponse">
            <complexType/>
         </element>

UpdateDvsCapability

Set the capability of the switch.

Required Privileges: DVSwitch.Modify

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the DistributedVirtualSwitch used to make the method call.
capability	DVSCapability	The capability of the switch.

Return Value

Type	Description
None

Faults

Type	Description
DvsFault	Thrown if operation fails on any host or if there are other update failures.
DvsNotAuthorized	Thrown if login-session's extension key does not match the switch's configured extensionKey.
NotSupported	Thrown if called directly on a host or if the switch implementation doesn't support this API.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateDvsCapability" type="vim25:UpdateDvsCapabilityRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateDvsCapabilityResponse">
            <complexType/>
         </element>

UpdateNetworkResourcePool

Update the network resource pool configuration.

Required Privileges: DVSwitch.ResourceManagement
Since: vSphere API 4.1

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the DistributedVirtualSwitch used to make the method call.
configSpec	DVSNetworkResourcePoolConfigSpec[]	the network resource pool configuration specification.

Return Value

Type	Description
None

Faults

Type	Description
ConcurrentAccess	Thrown if a network resource pool is modified by two or more clients at the same time.
DvsFault	Thrown if operation fails on any host or if there are other update failures.
DvsNotAuthorized	Thrown if login-session's extension key does not match the switch's configured extensionKey.
InvalidName	Thrown if the name of the resource pool is invalid.
NotFound	Thrown if the resource pool does not exist on the dvs.
NotSupported	Thrown if network I/O control is not supported on the vSphere Distributed Switch.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateNetworkResourcePool" type="vim25:UpdateNetworkResourcePoolRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateNetworkResourcePoolResponse">
            <complexType/>
         </element>