VMware NSX Data Center for vSphere API documentation version 6.4
https://{nsxmanager}/api
Introduction
This manual, the NSX API Guide, describes how to install, configure, monitor, and maintain the VMware NSX® Data Center for vSphere® system by using REST API requests.
Important: NSX for vSphere is now known as NSX Data Center for vSphere.
Intended Audience
This manual is intended for anyone who wants to use the REST API to programmatically control an NSX Data Center for vSphere environment. The information in this manual is written for experienced developers who are familiar with virtual machine technology, virtualized datacenter operations, and REST APIs. This manual also assumes familiarity with NSX Data Center for vSphere.
VMware Technical Publications Glossary
VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For definitions of terms as they are used in VMware technical documentation go to http://www.vmware.com/support/pubs.
Technical Documentation and Product Updates
You can find the most up-to-date technical documentation on the VMware Web site at: http://www.vmware.com/support/.
The VMware Web site also provides the latest product updates.
If you have comments about this documentation, submit your feedback to: <[email protected]>.
Using the NSX REST API
To use the NSX REST API, you must configure a REST client, verify the required ports are open between your REST client and the NSX Manager, and understand the general RESTful workflow.
Ports Required for the NSX REST API
The NSX Manager requires port 443/TCP for REST API requests.
Configuring REST Clients for the NSX REST API
Some common REST clients include Postman, RESTClient (a Firefox add-on), and curl (a command-line tool). The details of REST client configuration will vary from client to client, but this general information should help you configure your REST client correctly.
The NSX REST API can use basic authentication or JSON Web Token authentication.
You can authenticate using basic authentication or JSON Web Tokens. See "Working with API Tokens" for information on creating and using JSON Web Tokens. You must configure your REST client to send the NSX Manager authentication credentials. See the documentation for your REST client for details.You must use https to send API requests to the NSX Manager.
You might need to import the certificate from the NSX Manager to your REST client to allow it to connect to the NSX Manager.When you submit an API request with a request body, you must include the appropriate
Content-Typeheader.
Starting in NSX 6.4, both XML and JSON are supported. This guide documents XML examples. Set the Content-Type header to application/xml or application/json as needed.
Some requests require additional headers, for example, firewall configuration changes require the If-Match header. This is noted on each method description.- To ensure you always receive the correct response bodies, set the
Acceptheader
Starting in NSX 6.4, both XML and JSON are supported. This guide documents XML examples. Set the Accept header to application/xml or application/json as needed.
Note: Some methods, for example, the central CLI method,POST /1.0/nsx/cli, might require a different Accept header.
The following API method will return a response on a newly deployed NSX Manager appliance, even if you have not made any configuration changes. You can use this as a test to verify that your REST client is configured correctly to communicate with the NSX Manager API.
GET /api/2.0/services/usermgmt/user/admin
URI and Query Parameters
Some methods have URI or query parameters. URI parameters are values that you include in the request URL. You use a question mark (?) to join the request URL and the query parameters. Multiple query parameters can be combined by using ampersands (&).
For example, you can use this method to get a list of logical switches on a transport zone:
GET /api/2.0/vdn/scopes/{scopeId}/virtualwires
scopeId is a URI parameter that represents a transport zone.
The startindex and pagesize query parameters control how this information is displayed. startindex determines which logical switch to begin the list with, and pagesize determines how many logical switches to list.
To view the first 20 logical switches on transport zone vdnscope-1, use the following parameters:
- scopeId URI parameter set to vdnscope-1.
- startindex query parameter set to 0.
- pagesize query parameter set to 20.
These parameters are combined to create this request:
GET https://192.168.110.42/api/2.0/vdn/scopes/vdnscope-1/virtualwires?
startindex=0&pagesize=20
RESTful Workflow Patterns
All RESTful workflows fall into a pattern that includes only two fundamental operations, which you repeat in this order for as long as necessary.
- Make an HTTP request (GET, PUT, POST, or DELETE).
The target of this request is either a well-known URL (such as NSX Manager) or a link obtained from the response to a previous request. For example, a GET request to an Org URL returns links to vDC objects contained by the Org. - Examine the response, which can be an XML document or an HTTP response code.
If the response is an XML document, it might contain links or other information about the state of an object. If the response is an HTTP response code, it indicates whether the request succeeded or failed, and might be accompanied by a URL that points to a location from which additional information can be retrieved.
Revision Numbers
Some API objects include a configuration version number. In some cases, this revision number is used to prevent concurrent changes to an object. As a best practice, before you change the configuration of an object, retrieve the latest configuration using GET. Modify the response body as needed and use it as your PUT request body. If the object has been modified since your GET operation, you might see an error message.
Finding vCenter Object IDs
Many API methods reference vCenter object IDs in URI parameters, query parameters, request bodies, and response bodies. You can find vCenter object IDs via the vCenter Managed Object Browser.
Find Datacenter MOID
- In a web browser, enter the vCenter Managed Object Browser URL:
http://vCenter-IP-Address/mob. - Click content.
- Find rootFolder in the Name column, and click the corresponding link in the Value column. For example, group-d1.
- Find the childEntity in the Name column, and the corresponding Value column entry is the datacenter MOID. For example, datacenter-21.
Find Cluster or Host MOID
- In a web browser, enter the vCenter Managed Object Browser URL:
http://vCenter-IP-Address/mob. - Click content.
- Find rootFolder in the Name column, and click the corresponding link in the Value column. For example, group-d1.
- Find childEntity in the Name column, and click the corresponding link in the Value column. For example, datacenter-21.
- Find hostFolder in the Name column, and click the corresponding link in the Value column. For example, group-h23.
- Find childEntity in the Name column. The corresponding Value column lists the host clusters. For example, domain-c33.
- To find the MOID of a host in a cluster, click the appropriate host cluster link located in the previous step.
- Find host in the Name column. The corresponding Value column lists the hosts in that cluster by vCenter MOID and hostname. For example, host-32 (esx-02a.corp.local).
Find Portgroup MOID
- In a web browser, enter the vCenter Managed Object Browser URL:
http://vCenter-IP-Address/mob. - Click content.
- Find rootFolder in the Name column, and click the corresponding link in the Value column. For example, group-d1.
- Find childEntity in the Name column, and click the corresponding link in the Value column. For example, datacenter-21.
- Find hostFolder in the Name column, and click the corresponding link in the Value column. For example, group-h23.
- Find childEntity in the Name column. The corresponding Value column contains links to host clusters. Click the appropriate host cluster link. For example, domain-c33.
- Find host in the Name column. The corresponding Value column lists the hosts in that cluster by vCenter MOID and hostname. Click the appropriate host link, For example, host-32.
- Find network in the Name column. The corresponding Value column lists the port groups on that host, For example, dvportgroup-388.
Find VM MOID or VM Instance UUID
- In a web browser, enter the vCenter Managed Object Browser URL:
http://vCenter-IP-Address/mob. - Click content.
- Find rootFolder in the Name column, and click the corresponding link in the Value column. For example, group-d1.
- Find childEntity in the Name column, and click the corresponding link in the Value column. For example, datacenter-21.
- Find hostFolder in the Name column, and click the corresponding link in the Value column. For example, group-h23.
- Find childEntity in the Name column. The corresponding Value column contains links to host clusters. Click the appropriate host cluster link. For example, domain-c33.
- Find host in the Name column. The corresponding Value column lists the hosts in that cluster by vCenter MOID and hostname. Click the appropriate host link, For example, host-32.
- Find vm in the Name column. The corresponding Value column lists the virtual machines by vCenter MOID and hostname. For example, vm-216 (web-01a).
- To find the instance UUID of a VM, click the VM MOID link located in the previous step. Click the config link in the Value column.
- Find instanceUuid in the Name column. The corresponding Value column lists the VM instance UUID. For example, 502e71fa-1a00-759b-e40f-ce778e915f16.
update-number
Update 13
update-date
Modified JULY 2020
vdsManage
Working With vSphere Distributed Switches
Prepare a vSphere Distributed Switch.
The MTU is the maximum amount of data that can be transmitted in one packet before it is divided into smaller packets. VXLAN frames are slightly larger in size because of the traffic encapsulation, so the MTU required is higher than the standard MTU. You must set the MTU for each switch to 1602 or higher.
Retrieve information about all vSphere Distributed Switches.
Working With vSphere Distributed Switches in a Datacenter
Retrieve information about all vSphere Distributed Switches in the specified datacenter.
Working With a Specific vSphere Distributed Switch
Retrieve information about the specified vSphere Distributed Switch.
Delete the specified vSphere Distributed Switch.
Working With Latency Configuration of a Specific vSphere Distributed Switch
Starting in NSX 6.4.5, you can use APIs to monitor the end-to-end network latency of a data path as traffic moves between VMs that are either on the same ESXi host or on different ESXi hosts. However, both the VMs must be attached to the same logical switch (subnet).
Note: NSX cannot calculate the end-to-end latency information when data traffic is routed between VMs through a distributed logical router. That is, when VMs are attached to different logical switches or subnets.
To calculate the end-to-end latency of the data path, NSX uses the timestamp attribute of a data path packet inside the hypervisor.
Retrieve the latency configuration of the specified vSphere Distributed Switch.
Method history:
| Release | Modification |
|---|---|
| 6.4.5 | Method introduced. |
Update the latency configuration of the specified vSphere Distributed Switch.
Method history:
| Release | Modification |
|---|---|
| 6.4.5 | Method introduced. |
Latency Configuration Parameters
| Parameter | Description | Comments |
|---|---|---|
| enabled | When set to true, the dvSwitch collects latency data. When set to false, the dvSwitch stops collecting latency data and releases all the reserved resources. | Optional. Boolean. Options are True or False. Default is False. |
| latencySamplingRateForHost | Packet sampling rate of the dvSwitch in integer. For example, 100 means that one packet in every 100 packets is timestamped. 1 means that all packets are timestamped. | Optional. Default value is 100. Maximum value is 10000, and minimum value is 1. |
| latencyDurationMillSecondsForHost | Packet sampling duration of the dvSwitch in milliseconds. Denotes the frequency at which latency data is generated. | Optional. Default value is 1000 ms. Maximum value is 10000 ms, and minimum value is 1 ms. |
Working With Latency Configuration of a Specific Host
Retrieve the latency configuration of the specified vSphere Distributed Switch on the specified host.
Method history:
| Release | Modification |
|---|---|
| 6.4.5 | Method introduced. |
Update the latency configuration of the specified vSphere Distributed Switch on the specfied host.
Method history:
| Release | Modification |
|---|---|
| 6.4.5 | Method introduced. |
vdnConfig
Working With Segment ID Pools and Multicast Ranges
Working With Segment ID Pools
Segment ID pools (also called segment ID ranges) provide virtual network identifiers (VNIs) to logical switches.
You must configure a segment ID pool for each NSX Manager. You can have more than one segment ID pool. The segment ID pool includes the beginning and ending IDs.
You should not configure more than 10,000 VNIs in a single vCenter server because vCenter limits the number of dvPortgroups to 10,000.
If any of your transport zones will use multicast or hybrid replication mode, you must also configure a multicast address range.
Add a segment ID pool.
- name - Required property.
- desc - Optional property.
- begin - Required property. Minimum value is 5000
- end - Required property. Maximum value is 16777216
Retrieve information about all segment ID pools.
Working With a Specific Segment ID Pool
Retrieve information about the specified segment ID pool.
Update the specified segment ID pool.
If the segment ID pool is universal you must send the API request to the primary NSX Manager.
Delete the specified segment ID pool.
If the segment ID pool is universal you must send the API request to the primary NSX Manager.
Working With Multicast Address Ranges
If any of your transport zones will use multicast or hybrid replication mode, you must add a multicast address range (also called a multicast address pool). Specifying a multicast address range helps in spreading traffic across your network to avoid overloading a single multicast address.
Add a multicast address range for logical switches.
The address range includes the beginning and ending addresses.
Retrieve information about all configured multicast address ranges.
Universal multicast address ranges have the property isUniversal set to true.
Working With a Specific Multicast Address Range
Retrieve information about the specified multicast address range.
Update the specified multicast address range.
If the multicast address range is universal you must send the API request to the primary NSX Manager.
Delete the specified multicast address range.
If the multicast address range is universal you must send the API request to the primary NSX Manager.
Working With the VXLAN Port Configuration
Retrieve the UDP port configured for VXLAN traffic.
Update the VXLAN Port Configuration
Update the VXLAN port configuration to use port portNumber.
This method changes the VXLAN port in a three phrase process, avoiding disruption of VXLAN traffic. In a cross-vCenter NSX environment, change the VXLAN port on the primary NSX Manager to propagate this change on all NSX Managers and hosts in the cross-vCenter NSX environment.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. Port change is now non-disruptive, and propagates to secondary NSX Managers if performed on the primary NSX Manager. Force parameter added. |
VXLAN Port Configuration Update Status
Retrieve the status of the VXLAN port configuration update.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Resume VXLAN Port Configuration Update
If you update the VXLAN port using the Change button on the Installation > Logical Network Preparation page in the vSphere Web Client, or using PUT
/api/2.0/vdn/config/vxlan/udp/port/{portNumber} without the force parameter, and the port update does not complete, you can try resuming the port config change.
You can check the progress of the VXLAN port update with GET /api/2.0/vdn/config/vxlan/udp/port/taskStatus.
Only try resuming the port update if it has failed to complete. You should not need to resume the port update under normal circumstances.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Working With Allocated Resources
Retrieve information about allocated segment IDs or multicast addresses.
Resolving Missing VXLAN VMKernel Adapters
Resolve missing VXLAN VMKernel adapters.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
CdoMode
Working With Controller Disconnected Operation (CDO) Mode
You can enable CDO mode on secondary NSX Manager to avoid connectivity issues with the primary site.
CDO mode state has the following values:
- ENABLED: CDO mode has been successfully enabled on NSX Manager.
- DISABLED: CDO mode has been successfully disabled on NSX Manager.
- UNKNOWN: CDO mode has not been set on NSX Manager.
CDO mode operation status has the following values:
- FAILED: NSX Manager failed to set CDO state.
- SUCCESSFUL: NSX Manager is successful to set CDO state.
- IN_PROGRESS: Setting of CDO state in-progress.
- UNKNOWN: Unknown state.
Retrieves the status of CDO mode.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
Modify the status of CDO mode. This method can be used to perform the following tasks:
- Update the CDO mode: POST /api/2.0/vdn/cdo?action=update
- Resync the CDO mode: POST /api/2.0/vdn/cdo?action=resync
- Enable the CDO mode: POST /api/2.0/vdn/cdo?action=enable
- Disable the CDO mode: POST /api/2.0/vdn/cdo?action=disable
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
vdnScopes
Working With Transport Zones
Retrieve information about all transport zones (also known as network scopes).
CDO mode state parameters (read-only)
The CDO mode state shows the most recent CDO operation, and the status of that operation. The status can be: UNKNOWN, PENDING, IN_PROGRESS, COMPLETED, or FAILED.
| Operation Type | Description |
|---|---|
| ENABLE | Enable CDO mode on all distributed switches in the transport zone. |
| DISABLE | Disable CDO mode on all distributed switches in the transport zone. |
| EXPAND | Enable CDO mode on newly joined distributed swithes. |
| SHRINK | Disable CDO mode on removed distributed switches. |
| CLEAN_UP | Transport zone removed, clean up the CDO mode configuration from all distributed switches in the transport zone. |
| SYNC_ENABLE | Repush CDO mode configuration data to all distributed switches in the scope |
| SYNC_DISABLE | Remove CDO mode configuration from all distributed switches in the transport zone. |
Method history:
| Release | Modification |
|---|---|
| 6.3.0 | Method updated. Output includes information about CDO mode. See Working With Transport Zone CDO Mode for more information. |
Create a transport zone.
Request body parameters:
- name - Required. The name of the transport zone.
- description - Optional. Description of the transport zone.
- objectId - Required. The cluster object ID from vSphere. One or more are required.
- controlPlaneMode - Optional. The control plane mode. It can be one of the following:
- UNICAST_MODE
- HYBRID_MODE
- MULTICAST_MODE
Working With a Specific Transport Zone
Retrieve information about the specified transport zone.
Method history:
| Release | Modification |
|---|---|
| 6.3.0 | Method updated. Output includes information about CDO mode. See Working With Transport Zone CDO Mode for more information. |
Update the specified transport zone.
You can add a cluster to or delete a cluster from a transport zone.
You can also repair missing port groups. For every logical switch created, NSX creates a corresponding port group in vCenter. If the port group is lost for any reason, the logical switch will stop functioning. The repair action recreates any missing port groups.
Delete the specified transport zone.
Working With Transport Zone Attributes
Update the attributes of a transport zone.
For example, you can update the name, description, or control plane mode. You must include the cluster object IDs for the transport zone in the request body.
Working With Transport Zone CDO Mode
Note: From 6.4.0, CDO feature is supported at NSX Manager level and not at Transport Zone level. For more details, refer to Working with Controller Disconnected Operation (CDO) Mode section.
Enable or disable CDO mode for the specified transport zone.
Controller Disconnected Operation (CDO) mode ensures that the data plane connectivity is unaffected when host lose connectivity with the controller.
If you want to enable CDO mode on the universal transport zone in a cross-vCenter NSX environment, you must do this from the primary NSX Manager. The universal synchronization service will propagate the CDO configuration to the secondary NSX Managers.
Method history:
| Release | Modification |
|---|---|
| 6.3.2 | Method introduced. (Tech preview in 6.3.0). |
Testing Multicast Group Connectivity
Test multicast group connectivity.
Test multicast group connectivity between two hosts connected to the specified transport zone.
Parameter packetSizeMode has one of the following values:
- 0 - VXLAN standard packet size
- 1 - minimum packet size
- 2 - customized packet size. If you set packetSizeMode to 2, you must specify the size using the packetSize parameter.
logicalSwitches
Working With Logical Switches in a Specific Transport Zone
Retrieve information about all logical switches in the specified transport zone (network scope).
Create a logical switch.
To create a universal logical switch use universalvdnscope as the scopeId in the URI and send the request to the primary NSX Manager. Request body parameters:
- name - Optional. The name of the logical switch.
- description - Optional. Description of the logical switch.
- tenantId - Required.
- controlPlaneMode - Optional. The control plane mode. If not specified, the controlPlaneMode of the transport zone is used. It can be one of the following:
- UNICAST_MODE
- HYBRID_MODE
- MULTICAST_MODE
- guestVlanAllowed - Optional. Default is false.
traceflows
Working With Traceflow
For Traceflow to work as expected, make sure that the controller cluster is connected and in healthy state. The Traceflow operation requires active communication between vCenter, NSX Manager, controller cluster, and netcpa User World Agents (UWA) on the host. Traceflow observes marked packet as it traverses overlay network. Each packet is delivered to host VM and monitored as it crosses overlay network until it reaches the destination VM. The packet is never delivered to the destination guest VM. This means that Traceflow packet delivery is successful even when the guest VM is powered down. Unknown L2 Packets are always be sent to the bridge. Typically, the bridge forwards these packets to a VLAN and reports the Traceflow packet as delivered. The packet which is reported as delivered need not necessarily mean that the trace packet was delivered to the destination specified. You should conclude only after validating the observations.vdl2 serves ARP proxy for ARP packets coming from VMs. However, Traceflow bypasses this process, hence vdl2 may broadcast the Traceflow packet out.
Working With a Specific Traceflow
Query a specific Traceflow by tracflowId which is the value returned after executing the create Traceflow API call.
Traceflow Observations
Retrieve traceflow observations.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method updated. New parameter replicateType added. |
logicalSwitchesGlobal
Working With Logical Switches in All Transport Zones
Retrieve information about all logical switches in all transport zones.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method updated. Added name query parameter. |
Working Virtual Machine Connections to Logical Switches
Attach a VM vNIC to, or detach a VM vNIC from a logical switch.
Specify the logical switch ID in the portgroupId parameter. To detach a VM vNIC from a logical switch, leave the portgroupId parameter empty.
To find the ID of a VM vNIC, do the following:
- In the vSphere MOB, navigate to the VM you want to connect or disconnect.
- Click config and take note of the instanceUuid.
- Click hardware and take note of the last three digits of the appropriate network interface device.
Use these two values to form the VM vNIC ID. For example, if the instanceUuid is 502e71fa-1a00-759b-e40f-ce778e915f16 and the appropriate device value is device[4000], the objectId and vnicUuid are both 502e71fa-1a00-759b-e40f-ce778e915f16.000.
Working With a Specific Logical Switch
Retrieve information about the specified logical switch.
If the switch is a universal logical switch the isUniversal parameter is set to true in the response body.
Update the specified logical switch.
For example, you can update the name, description, or control plane mode.
Delete the specified logical switch.
Resolving Missing Port Groups for a Logical Switch
For every logical switch created, NSX creates a corresponding port group in vCenter. If the port group is missing, the logical switch will stop functioning.
If the port group backing a logical switch is deleted, you can recreate a new backing port group for the logical switch.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Testing Host Connectivity
Test multicast group connectivity.
Test multicast group connectivity between two hosts connected to the specified logical switch.
Parameter packetSizeMode has one of the following values:
- 0 - VXLAN standard packet size
- 1 - minimum packet size
- 2 - customized packet size. If you set packetSizeMode to 2, you must specify the size using the packetSize parameter.
Testing Point-to-Point Connectivity
Test point-to-point connectivity.
Test point-to-point connectivity between two hosts connected to the specified logical switch.
Parameter packetSizeMode has one of the following values:
- 0 - VXLAN standard packet size
- 1 - minimum packet size
- 2 - customized packet size. If you set packetSizeMode to 2, you must specify the size using the packetSize parameter.
Working With Hardware Gateway Bindings for a Specific Logical Switch
Retrieve hardware gateway bindings for the specified logical switch.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Working With Connections Between Hardware Gateways and Logical Switches
Manage the connection between a hardware gateway and a logical switch.
Attach a hardware gateway to a logical switch and create a new binding with the information provided
POST /api/2.0/vdn/virtualwires/{virtualwireid}/hardwaregateways
<hardwareGatewayBinding>
<hardwareGatewayId>hardwarewgateway1</hardwareGatewayId>
<vlan>v1</vlan>
<switchName>s1</switchName>
<portName>s1</portName>
</hardwareGatewayBinding>
Attach a hardware gateway to a logical switch, specifying an existing binding by ID
POST /api/2.0/vdn/virtualwires/<virtualwireId>/hardwaregateways/{bindingId}?action=attach
<virtualWire>
...
<hardwareGatewayBindings>
<hardwareGatewayBinding>
<id>binding id</id>
</hardwareGatewayBinding>
</hardwareGatewayBindings>
</virtualWire>
Detach a hardware gateway from a logical switch
POST /api/2.0/vdn/virtualwires/<virtualwireId>/hardwaregateways/{bindingId}?action=detach
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
arpMAC
Working With IP Discovery and MAC Learning for Logical Switches
You can enable IP discovery (ARP suppression) and MAC learning for logical switches or dvPortGroup. Enabling MAC learning builds a VLAN - MAC pair learning table on each vNic.
This table is stored as part of the dvfilter data. During vMotion, dvfilter saves/restores the table at the new location. The switch then issues RARPs for all the VLAN - MAC entries in the table.
Enabling this feature avoids possible traffic loss during vMotion in the following cases:
- the vNic is in VLAN trunk mode
- the VM is using more than one unicast MAC address. Since Etherswitch supports only one unicast MAC per vNic, RARP is not processed.
When a logical switch is created using the API, IP discovery is enabled, and MAC learning is disabled.
In cross-vCenter NSX, the following applies:
- The MAC learning setting for a universal logical switch is managed on the primary NSX Manager. Any changes are synchronized to all secondary NSX Managers.
- The IP discovery setting for a universal logical switch is managed separately on each NSX Manager.
Note: In NSX 6.2.2 and earlier you cannot disable IP discovery for universal logical switches on secondary NSX Managers.
Retrieve IP discovery and MAC learning information.
Enable or disable IP discovery and MAC learning.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. IP discovery can be disabled on secondary NSX Managers. |
nsxControllers
Working With NSX Controllers
For the unicast or hybrid control plane mode, you must add an NSX controller to manage overlay transport and provide East-West routing. The controller optimizes virtual machine broadcast (ARP only) traffic, and the learning is stored on the host and the controller.
Add a new NSX Controller on the specified cluster. The hostId parameter is optional. The resourcePoolId can be either the clusterId or resourcePoolId.
The IP address of the controller node will be allocated from the specified IP pool.
Note: Controller nodes are deployed with 4 GB of memory regardless of which deployType value is provided.
Method history:
| Release | Modification |
|---|---|
| 6.3.3 | Method updated. deployType is no longer required. |
Retrieves details and runtime status for all controllers. Runtime status can be one of the following:
- Deploying - Controller is being deployed and the procedure has not completed yet.
- Removing - Controller is being removed and the procedure has not completed yet.
- Running - Controller has been deployed and can respond to API invocation.
- Unknown - Controller has been deployed but fails to respond to API invocation.
When a controller is in Running status, the diskLatencyAlertDetected parameter in the API response shows whether disk latency alert is detected in the controller. This parameter can take one of the following values:
- True - Disk latency alert is detected in the controller.
- False - Disk latency is not detected in the controller.
- Unknown - After the controller connects with the NSX Manager, the NSX Manager receives the disk latency report of the controller after a delay of 30 seconds.
Working With Controller Upgrade Availability
Retrieve controller upgrade availability.
Working With of Controller Job Status
Retrieves status of controller creation or removal, or controller cluster upgrade.
Working With a Specific Controller
Delete the NSX controller.
If you power off or delete a controller from vCenter, NSX Manager detects the change in controller status. You can remediate the controller, which will power on a powered off controller, or remove the controller from the NSX Manager database if the controller is deleted.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Update the name of the controller. The name must not contain spaces or underscores.
When you update the controller name, the following changes are made:
- the name displayed in the Networking & Security UI is changed to newName
- the VM name is vSphere is changed to newName-NSX-<controller_id>
- the VM's hostname is changed to newName-NSX-<controller_id>
Note: The VM hostname is used in controller log entries. If you change the controller hostname, the log entries display the new hostname.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
Working With NSX Controller System Statistics
Retrieve NSX Controller system statistics.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Working With Controller Tech Support Logs
Retrieve controller logs. Response content type is application/octet-stream and response header is filename. This streams a fairly large bundle back (possibly hundreds of MB).
Working With Controller Syslog Configuration
Add controller syslog exporter on the controller.
Deprecated: Starting in 6.4.2, POST/DELETE
/api/2.0/vdn/controller/{controllerId}/syslog are deprecated.
Use GET/PUT /api/2.0/vdn/controller/cluster/syslog instead.
Using both these methods is not supported and might result in an inconsistent state on the controller nodes.
Retrieve details about the syslog exporter on the controller.
Deprecated: Starting in 6.4.2, POST/DELETE
/api/2.0/vdn/controller/{controllerId}/syslog are deprecated.
Use GET/PUT /api/2.0/vdn/controller/cluster/syslog instead.
Using both these methods is not supported and might result in an inconsistent state on the controller nodes.
Deletes syslog exporter on the specified controller node.
Deprecated: Starting in 6.4.2, POST/DELETE
/api/2.0/vdn/controller/{controllerId}/syslog are deprecated.
Use GET/PUT /api/2.0/vdn/controller/cluster/syslog instead.
Using both these methods is not supported and might result in an inconsistent state on the controller nodes.
Working With Controller Cluster Snapshots
Take a snapshot of the control cluster from the specified controller node.
Working With the NSX Controller Cluster Configuration
Retrieve cluster wide configuration information for controller.
Modify cluster wide configuration information for controller.
Working With Controller Cluster NTP Settings
You can configure up to five NTP servers on the NSX Controller cluster. You can specify NTP servers by IPv4 address or FQDN. If an FQDN is used, DNS settings must also be configured. The same NTP settings are applied to all controller nodes in the cluster.
Retrieve NTP configuration for the NSX Controller cluster.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
Update NTP configuration for the NSX Controller cluster.
If the settings fail to apply to one or more controller nodes, an error message is returned. Check the controller node status, and retry the request.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
Working With Controller Cluster DNS Settings
When you configure DNS on the NSX Controller cluster, the same settings are applied to all nodes in the cluster.
Controller cluster DNS settings override any DNS settings configured on the controller IP pool.
DNS Parameters
| Parameter | Description | Comments |
|---|---|---|
| dnsServer | DNS server IP address | Required. Specify up to 3. Valid input: IPv4 addresses. |
| dnsSuffix | DNS suffix for search order | Optional. Specify up to 3. Valid input: domain name suffix. At least one dnsServer must be configured. |
Retrieve DNS settings for the NSX Controller cluster.
Method history:
| Release | Modification |
|---|---|
| 6.4.2 | Method introduced. |
Update DNS settings for all nodes in the NSX Controller cluster.
Note: If the settings fail to apply to one or more controller nodes, an error message is returned. Check the controller node status, and retry the request.
Method history:
| Release | Modification |
|---|---|
| 6.4.2 | Method introduced. |
Working With Controller Cluster Syslog Configuration
When you configure syslog on the NSX Controller cluster, the same settings are applied to all nodes in the cluster.
Syslog Parameters
| Parameter | Description | Comments |
|---|---|---|
| syslogServer | Syslog server address | Required. Specify up to 10. Valid input: IPv4 addresses or FQDN. If FQDN is used, DNS must also be configured. |
| port | Syslog exporter port | Optional. Default is 6514. Valid ports: 1-65535. |
| level | Syslog logging level | Optional. Default is INFO. Valid values: INFO, ERROR, WARN. |
| protocol | Syslog protocol | Optional. Default is TLS. Valid values: TLS, UDP, TCP. |
| certificate | Certificate | Required if protocol is set to TLS. Valid value: X.509 PEM encoded certificate. |
Retrieve syslog settings for the NSX Controller cluster.
Method history:
| Release | Modification |
|---|---|
| 6.4.2 | Method introduced. |
Update syslog settings for all nodes in the NSX Controller cluster.
If the settings fail to apply to one or more controller nodes, an error message is returned. Check the controller node status, and retry the request.
Important: You can also configure syslog on an individual controller node with the deprecated API POST/DELETE
/api/2.0/vdn/controller/{controllerId}/syslog. Using both these methods is not supported and might result in an inconsistent state on the controller nodes.
Method history:
| Release | Modification |
|---|---|
| 6.4.2 | Method introduced. |
Working With Controller Cluster Upgrade
Start the upgrade of the NSX Controller cluster. The upgrade is performed on one controller node at a time.
Before you start the controller upgrade, use GET
/api/2.0/vdn/controller to ensure that all three controllers have status of RUNNING. It can take about 10 minutes after the NSX Manager upgrade and reboot for the controllers to reestablish connectivity to the NSX Manager.
This request returns a jobId, for example, jobdata-22307. You can use GET /api/2.0/vdn/controller/progress/{jobId} to get the status of the NSX Controller cluster upgrade.
Working With the NSX Controller Password
Change the NSX controller password.
Working With Controller Synchronization
You can resynchronize the NSX Controller cluster with NSX Manager. You might want to do this if you notice that the controller cluster has extra, stale, or missing configuration items.
Synchronize the controller cluster with the NSX Manager database.
Working with Controller Synchronization Status
Retrieve the status of the controller synchronization.
Get the status of the controller synchronization.
If the sync is in progress, the response includes the status JOB_IN_PROGRESS, and the jobId. If the sync has finished, the response includes the status NOT_RUNNING.
hostsHealth
Working With Host Health Status Using BFD
Provides overall information about the host health status. Tunnel, pNIC, control plane, and management plane statuses are displayed.
Working with overall information about host health status
Retrieve the host health status.
The status API endpoint has a known limitation in a multi-site Cross-vCenter NSX deployment where the vCenter Server and the NSX Manager know only the hosts that they manage.
The NSX Manager can query status of only those hosts that its vCenter Server manages. For example, when you run this API on the primary NSX Manager, the API cannot return the status of hosts, which are managed by the vCenter Servers that are paired with the secondary NSX Managers.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
Working with health status for a specific host
Retrieve health status for a specific host.
NSX Manager obtains host status from the host periodically and updates the cache. When the source is specified as realtime, the current status of the host is retrieved. In the meantime, NSX Manager updates the host status in the cache. When the source is specified as cached, the host status is retrieved directly from the cache.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
Working with tunnel connections for a specific host
Retrieve tunnel connections for a specific host.
In NSX 6.4.6 or earlier, tunnel details are retrieved for a maximum of 1560 tunnels on the host. Starting in NSX 6.4.7, tunnel details are retrieved for a maximum of 4096 tunnels on the host.
The tunnel API endpoint has a known limitation in a multi-site Cross-vCenter NSX deployment. In the API response, the remoteNodeId will be Unknown if the remote host is not managed by the NSX Manager on which the API is run.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
Working with remote host status
Retrieve status of all remote hosts with tunnel connections to the given host.
The remote host status API endpoint has a known limitation in a multi-site Cross-vCenter NSX deployment. This API returns the status of remote hosts that are managed by the NSX Manager on which the API is run. However, the status of the remote hosts managed by other NSX Managers is not returned.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
bfdConfig
Working With BFD Global Configuration
NSX Data Center uses Bidrectional Forwarding Detection (BFD) network protocol to obtain the tunnel health status and the tunnel latency. By default, BFD is disabled.
In NSX 6.4.6 or earlier, when you enable BFD, monitoring of both tunnel latency and tunnel health is enabled. You cannot separately turn on or turn off the monitoring of tunnel health and tunnel latency.
Starting in NSX 6.4.7, BFD global configuration includes two additional parameters to help you enable or disable the monitoring of tunnel health and tunnel latency separately. These two parameters are tunnelReportEnabled and tunnelLatencyEnabled.
BFD Parameters
| Parameter | Description | Comments |
|---|---|---|
| enabled | Enable or disable BFD. In NSX 6.4.6 or earlier, this parameter enables global BFD and monitoring of tunnel health and tunnel latency. Starting in NSX 6.4.7, this parameter enables only global BFD. | Required. Options are True or False. Default is False. |
| tunnelReportEnabled | Enable or disable monitoring of tunnel health. This parameter is available starting in NSX 6.4.7. | Optional. Options are True or False. Default is False. |
| tunnelLatencyEnabled | Enable or disable monitoring of tunnel latency. This parameter is available starting in NSX 6.4.7. | Optional. Options are True or False. Default is False. |
| pollingIntervalSecondsForHost | Configure the BFD polling interval. | Optional. Value should be greater than 30. Default value is 180. |
| bfdIntervalMillSecondsForHost | Configure the interval of BFD session in milliseconds. | Optional. Value should be greater than 300. Default value is 120000. |
Valid Combinations of BFD Configuration Parameters
| BFD | Tunnel Report | Tunnel Latency | Result |
|---|---|---|---|
| False | False | False | When BFD is disabled, monitoring of tunnel health and tunnel latency must be disabled. Turning on tunnel health and tunnel latency monitoring is not permitted. |
| True | True | False | Only tunnel health is monitored. Tunnel latency is not monitored. |
| True | True | True | Both tunnel health and tunnel latency are monitored. |
| True | False | True | Only tunnel latency is monitored. Tunnel health is not monitored. |
| True | False | False | Both tunnel health and tunnel latency are not monitored. |
Retrieve the BFD global configuration.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
| 6.4.7 | Method updated. Added tunnelReportEnabled and tunnelLatencyEnabled parameters. |
Update the BFD global configuration.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
| 6.4.7 | Method updated. Added tunnelReportEnabled and tunnelLatencyEnabled parameters. |
pnicCheckConfig
Working With pNIC Configuration Information
Provides the status information about physical NIC (pNIC) global configuration. You can enable or disable pNIC to monitor health of a host. By default, pNIC is disabled.
pNIC Parameters
| Parameter | Description | Comments |
|---|---|---|
| enabled | Enable or disable pNIC to monitor health of a host. | Required. Options are True or False. Default is False. |
| pollingIntervalSecondsForHost | Configure the pNIC polling interval for the host. | Required. Value should be greater than 30. Default value is 180. |
Get pNIC status information.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
Update the global configuration for pNIC status check.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
servicesApps
Working With Services Grouping Objects
Retrieve Services from a Specific Scope
Retrieve services that have been created on the specified scope.
Create a Service on a Specific Scope
Create a new service on the specified scope.
Working With a Specified Service
Retrieve details about the specified service.
Modify the name, description, applicationProtocol, or port value of a service.
Delete the specified service.
applicationgroup
Working With Service Groups Grouping Objects
Creating Service Groups on a Specific Scope
Create a new service group on the specified scope.
Working With Service Groups on a Specific Scope
Retrieve a list of service groups that have been created on the scope.
Working With a Specific Service Group
Retrieve details about the specified service group.
Modify the name, description, applicationProtocol, or port value of the specified service group.
Delete the specified service group (application group) from a scope.
Working With a Specific Service Group Member
Add a member to the service group.
Delete a member from the service group.
Working With Service Group Members on a Specific Scope
Get a list of member elements that can be added to the service groups created on a particular scope.
ipPoolsObjects
Working With IP Pool Grouping Objects
Working With IP Pools on a Specific Scope
Retrieves all IP pools on the specified scope where the scopeId is the reference to the desired scope. An example of the scopeID is globalroot-0.
Create a pool of IP addresses. For scopeId use globalroot-0 or the datacenterId in upgrade use cases.
Working With a Specific IP Pool
Retrieve details about a specific IP pool.
To modify an IP pool, query the IP pool first. Then modify the output and send it back as the request body.
Delete an IP pool.
Working With IP Pool Address Allocations
Retrieves all allocated IP addresses from the specified pool.
Allocate an IP address from the pool.
To allocate the next available IP, set allocationMode to ALLOCATE
<ipAddressRequest>
<allocationMode>ALLOCATE</allocationMode>
</ipAddressRequest>
To allocate a specific IP, set allocationMode to RESERVE and pass the IP to reserve in the ipAddress parameter.
<ipAddressRequest>
<allocationMode>RESERVE</allocationMode>
<ipAddress>192.168.1.2</ipAddress>
</ipAddressRequest>
Working With Specific IPs Allocated to an IP Pool
Release an IP address allocation in the pool.
nsxLicensing
Working With Licensing
The licensing capacity usage API command reports usage of CPUs, VMs and concurrent users for the distributed firewall and VXLAN. The licensing status API command displays details about the assigned license.
Working With Licensing Capacity
The licensing capacity usage API command reports usage of CPUs, VMs and concurrent users for the distributed firewall and VXLAN.
Retrieve capacity usage information on the usage of CPUs, VMs and concurrent users for the distributed firewall and VXLAN.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Working With Licensing Status
The licensing status API command displays details about the assigned license.
Retrieve details about the assigned license.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
securitytags
Working With Security Tags
You can manage security tags and their virtual machine assignments. For example, you can create a user defined security tag, assign tags to a virtual machine, view tags assigned to virtual machines, and view virtual machines that have a specific tag assigned.
ssoConfig
Working With NSX Manager SSO Registration
Retrieve SSO Configuration.
Register NSX Manager to SSO Services.
Deletes the NSX Manager SSO Configuration.
Working With SSO Configuration Status
Retrieve the SSO configuration status of NSX Manager.
userMgmt
Working With User Management
Manage Users on NSX Manager
Get information about a user.
Remove the NSX role for a vCenter user.
Working With User Account State
You can disable or enable a user account, either local user or vCenter user. When a user account is created, the account is enabled by default.
Manage NSX Roles for Users
Possible roles are:
- super_user - built-in admin user
- vshield_admin - NSX Administrator
- enterprise_admin - Enterprise Administrator
- security_admin - Security Administrator
- auditor - Auditor
- security_engineer - Security Engineer (introduced in NSX 6.4.2)
- network_engineer - Network Engineer (introduced in NSX 6.4.2)
- security_role_admin - Security & Role Administrator (introduced in NSX 6.4.5)
Retrieve a user's role.
Add role and resources for a user.
Method history:
| Release | Modification |
|---|---|
| 6.4.2 | Method updated. Added security_engineer and network_engineer roles. |
| 6.4.5 | Method updated. Added security_role_admin role. |
Change a user's role.
Method history:
| Release | Modification |
|---|---|
| 6.4.2 | Method updated. Added security_engineer and network_engineer roles. |
| 6.4.5 | Method updated. Added security_role_admin role. |
Delete the role assignment for specified vCenter user. Once this role is deleted, the user is removed from NSX Manager. You cannot delete the role for a local user.
Working With NSX Manager Role Assignment
Get information about users who have been assigned a NSX Manager role (local users as well as vCenter users with NSX Manager role).
Working With Available NSX Manager Roles
Read all possible roles in NSX Manager.
Method history:
| Release | Modification |
|---|---|
| 6.4.2 | Method updated. Added security_engineer and network_engineer roles. |
| 6.4.5 | Method updated. Added security_role_admin role. |
Working With Scoping Objects
Retrieve a list of objects that can be used to define a user's access scope.
servicesAuth
Working with API Authentication
Working with Basic Authentication
Update whether basic authentication is enabled.
Authentication headers are ignored, and the credentials used in the request body are used instead. This request works whether or not basic authenication is enabled.
All NSX Manager systems in a cross-vCenter NSX environment must have the same enabled/disabled status for basic authentication. If you disable basic authentication on one NSX Manager in a cross-vCenter NSX environment, you must disable it on all NSX Manager systems in the environment.
Method history:
| Release | Modification |
|---|---|
| 6.4.2 | Method introduced. |
Retrieve basic authentication configuration.
Method history:
| Release | Modification |
|---|---|
| 6.4.2 | Method introduced. |
Working with API Tokens
You can create a JSON Web Token and use it to authenticate with the NSX Manager appliance in subsequent API requests.
Create a new authentication token.
You can use this token in your REST client to access the API. Send the token in the Authorization header with the AUTHTOKEN keyword. See the documentation for your REST client for more information.
Example Authorization header:
Authorization: AUTHTOKEN eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTUyMDU1NTU0NH0.bXPVyHp6uR4HmCmyIMcgJQIS-E1xeb6MLz_3BDk7Lzw
By default, this token is created with the default expiry value. You can also set a custom expiration using the expiresInMinutes query parameter.
If a user authenticates with a token, and the user is deleted or their NSX access is disabled, their token will remain valid until the token expires.
To create a token when basic authentication is disabled, see POST /api/3.0/services/auth/token.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
Working With API Token Expiration
You can configure the default expiry time of API tokens. New tokens are created with this expiry time.
Update the default token expiry time.
The default expiry time is 90 minutes. The maximum expiry time is 24 hours.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
Retrieve the default token expiry time.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
Working With Token Invalidation
Invalidate tokens created by the specified user.
Method history:
| Release | Modification |
|---|---|
| 6.4.1 | Method introduced. |
3AuthToken
Working with API Authentication
Create a new authentication token.
Authentication headers are ignored, and the credentials used in the request body are used instead. This request works whether or not Basic Authenication is enabled.
You can use this token in your REST client to access the API. Send the token in the Authorization header with the AUTHTOKEN keyword. See the documentation for your REST client for more information.
Example Authorization header:
Authorization: AUTHTOKEN eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTUyMDU1NTU0NH0.bXPVyHp6uR4HmCmyIMcgJQIS-E1xeb6MLz_3BDk7Lzw
By default, this token is created with the default expiry value (see GET/PUT /api/2.0/services/auth/tokenexpiration). You can also set a custom expiration using the expiresInMinutes query parameter.
If a user authenticates with a token, and the user is deleted or their NSX access is disabled, their token will remain valid until the token expires.
Method history:
| Release | Modification |
|---|---|
| 6.4.2 | Method introduced. |
secGroup
Working With Security Group Grouping Objects
A security group is a collection of assets or grouping objects from your vSphere inventory.
Creating New Security Groups With Members
Create a new security group on a global scope or universal scope with membership information.
Universal security groups are read-only when querying a secondary NSX manager.
When you create a universal security group (on scope universalroot-0) by default localMembersOnly is set to false which indicates that the universal security group will contain members across the cross-vCenter NSX environment. This is the case in an active active environment. You can add the following objects to a universal security group with localMembersOnly=false (active active):
- IP Address Set
- MAC Address Set
- Universal Security Groups with localMembersOnly=false
When you create a universal security group (on scope universalroot-0) you can set the extendedAttribute localMembersOnly to true to indicate that the universal security group will contain members local to that NSX Manager only. This is the case in an active standby environment, because only one NSX environment is active at a time, and the same VMs are present in each NSX environment. You can add the following objects to a universal security group with localMembersOnly=true (active standby):
- Universal Security Tag
- IP Address Set
- MAC Address Set
- Universal Security Groups with localMembersOnly=true
- Dynamic criteria using VM name
You can set the localMembersOnly attribute only when the universal security group is created, it cannot be modified afterwards.
Method history:
| Release | Modification |
|---|---|
| 6.3.0 | Extended attribute localMembersOnly introduced. |
Creating New Security Groups Without Members
Create a new security group, with no membership information specified. You can add members later with PUT
/2.0/services/securitygroup/bulk/{objectId}
When you create a universal security group (on scope universalroot-0) by default localMembersOnly is set to false which indicates that the universal security group will contain members across the cross-vCenter NSX environment. This is the case in an active active environment. You can add the following objects to a universal security group with localMembersOnly=false (active active):
- IP Address Set
- MAC Address Set
- Universal Security Groups with localMembersOnly=false
When you create a universal security group (on scope universalroot-0) you can set the extendedAttribute localMembersOnly to true to indicate that the universal security group will contain members local to that NSX Manager only. This is the case in an active standby environment, because only one NSX environment is active at a time, and the same VMs are present in each NSX environment. You can add the following objects to a universal security group with localMembersOnly=true (active standby):
- Universal Security Tag
- IP Address Set
- MAC Address Set
- Universal Security Groups with localMembersOnly=true
- Dynamic criteria using VM name
You can set the localMembersOnly attribute only when the universal security group is created, it cannot be modified afterwards.
Method history:
| Release | Modification |
|---|---|
| 6.3.0 | Extended attribute localMembersOnly introduced. |
Updating a Specific Security Group Including Membership
Update configuration for the specified security group, including membership information.
Working With a Specific Security Group
Retrieve all members of the specified security group.
Update configuration for the specified security group. Members are not updated. You must use PUT
/2.0/services/securitygroup/bulk/{objectId} to update a security group membership.
Delete an existing security group.
If force=true is specified, the object is deleted even if used in other configurations, such as firewall rules. If force=true is not specified, the object is deleted only if it is not used by other configuration; otherwise the delete fails.
Working With Members of a Specific Security Group
Add a new member to the specified security group.
Delete member from the specified security group.
Working With Virtual Machines in a Security Group
Retrieve effective membership of a security group in terms of virtual machines. The effective membership is calculated using all the three membership components of a security group - static include, static exclude, and dynamic using the following formula:
Effective membership virtual machines = [ (VMs resulting from static include component + VMs resulting from dynamic component) - (VMs resulting from static exclude component) ]
Working With IP Addresses in a Security Group
Retrieve list of IP addresses that belong to a specific security group.
Working With MAC Addresses in a Security Group
Retrieve list of MAC addresses that belong to a specific security group.
Working With vNICs in a Security Group
Retrieve list of vNICs that belong to a specific security group.
Working With Virtual Machine Security Group Membership
Retrieves the collection of security groups to which a virtual machine is a direct or indirect member. Indirect membership involves nesting of security groups.
Working With IP Address in a Security Group
Retrieve all the security groups that contain the specified IP address.
Working With Internal Security Groups
Retrieve all internal security groups on the NSX Manager. These are used internally by the system and should not be created or modified by end users.
Working With Security Groups on a Specific Scope
List all the security groups created on a specific scope.
Method history:
| Release | Modification |
|---|---|
| 6.4.7 | Method updated. Added two new query parameters populateMembers and populateExtendedAttributes. |
Working With Security Group Member Types
Retrieve a list of valid elements that can be added to a security group.
Working With a Specific Security Group Member Type
Retrieve members of a specific type in the specified scope.
ipsets
Working With IP Set Grouping Objects
Working With IP Sets on a Specific Scope
Retrieve all configured IP sets.
Method history:
| Release | Modification |
|---|---|
| 6.4.7 | Method updated. Added populateExtendedAttributes query parameter. |
Working With a Specific IP Set
Retrieve an individual IP set.
Modify an existing IP set.
Delete an IP set.
vCenterConfig
Configuring NSX Manager with vCenter Server
You can synchronize NSX Manager with a vCenter Server, which enables the Networking and Security tab in the vCenter Web Client to display your VMware Infrastructure inventory.
vCenter Config Parameters
| Parameter | Comments |
|---|---|
| ipAddress | FQDN or IP address of vCenter server. |
| userName | Required. |
| password | Required. |
| certificateThumbprint | Required. Must be colon (:) delimited hexadecimal. |
| assignRoleToUser | Optional. true or false. |
| pluginDownloadServer | Optional. |
| pluginDownloadPort | Optional. |
Get vCenter Server configuration details on NSX Manager.
Synchronize NSX Manager with vCenter server.
Connection Status for vCenter Server
Get default vCenter Server connection status.
Working with vCenter Server Connection
Validates the vCenter connection by actually trying connection to vCenter Server with the available credentials instead of the cached state. Returns true if vCenter connectivity is successful and false if fails. If the vCenter connectivity has issues, then it disconnects the default connection.
Note: If previously connected, this API tries to re-connect to the vCenter Server which may take time to respond. If vCenter Server is non-responsive, then the API may result in timeout error.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
Update the vCenter Server connection status.
IndexMaintenanceConfig
Configuring Index Maintainance
If you have few tables in the database that is taking up most of the space, you can configure your index maintenance activities. You can reindex the tables, and tables with index bloat size greater than 75% are reindexed.
Retrieve the default settings for the index maintenance activities.
Method history:
| Release | Modification |
|---|---|
| 6.3.3 | Method introduced. |
Update the index maintenance default settings. You can enable or disable the settings and change the CRON configuration. To make the changes effective, you must restart the NSX Manager. To change the CRON expression, make sure the new CRON expression is correct using any CRON evaluators. Note that incorrect CRON expression will not run the reindexing task at the expected frequency.
CRON expression guidelines:
CRON expression pattern is a list of six single space-separated fields,representing second, minute, hour, day, month, weekday. Month and weekday can be given as first three letters of the English names. You can refer to the following Web sites for details:
- https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/scheduling/support/CronSequenceGenerator.html
- http://www.manpagez.com/man/5/crontab/
Method history:
| Release | Modification |
|---|---|
| 6.3.3 | Method introduced. |
Trigger the reindexing task on demand. Tables with index bloat size greater than 75% are reindexed.
Method history:
| Release | Modification |
|---|---|
| 6.3.3 | Method introduced. |
CPUConfiguration
Configuring the High CPU Usage Reporting Tool
You can configure the monitoring of high CPU usage for a defined time period using the High CPU Usage Reporting tool. The CPU Usage Monitoring Tool uses this configuration to monitor CPU utilization of the NSX Manager. You can configure the parameter values to monitor the CPU utilization.
CPU Configuration Parameters
| Parameter | Comments |
|---|---|
| delay | Time between two monitoring sessions in milliseconds. |
| intervals | The number of monitoring sessions. This is a positive integer value. |
| highcputhreshold | Enter threshold value for high CPU usage. Threshold value is a percentage value ranging from 1 to 100. |
| mediumcputhreshold | Enter threshold value for medium CPU usage. Threshold value is a percentage value ranging from 1 to 100. |
| monitoringfeatureenabled | Enter true to enable CPU usage monitoring feature. Enter false to disable CPU usage monitoring feature. |
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
Get the configuration details for the High CPU Usage Reporting Tool.
Update the configuration for the High CPU Usage Reporting Tool.
CPUUsage
Working with the CPU Usage Monitoring Tool
Monitoring tool monitors CPU usage of the NSX Manager. The configurations for the CPU usage are defined in the High CPU Usage Reporting Tool. Monitoring tool displays values for CPU utilization as High, Medium, and Low.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
Working With CPU Usage Indicator
Retrieve the CPU utilization status and the CPU usage percentage.
Working With CPU Usage Details
Retrieve the details of the module which is causing high CPU utilization for the NSX Manager.
universalSync
Working With Universal Sync Configuration in Cross-vCenter NSX
Working With Universal Sync Configuration Roles
You can set the role of an NSX Manager to primary, secondary, or standalone. If you set an NSX Manager’s role to primary, then use it to create universal objects, and then set the role to standalone, the role will be set as transit. In the transit role, the universal objects will still exist, but cannot be modified, other than being deleted.
Set the universal sync configuration role.
Retrieve the universal sync configuration role.
Working With Universal Sync Configuration of NSX Managers
Add a secondary NSX manager.
Run this method on the primary NSX Manager, providing details of the secondary NSX Manager.
Retrieve the certificate thumbprint of the secondary NSX Manager using the GET
/api/1.0/appliance-management/certificatemanager/certificates/nsx method. The sha1Hash parameter contains the thumbprint.
If run on a primary NSX Manager, it will list secondary NSX Managers configured on the primary NSX Manager.
If run on a secondary NSX Manager, it will list information about the secondary NSX Manager and the primary NSX Manager it is associated with.
Delete secondary NSX manager configuration.
Universal Sync Configuration of a Specific NSX Manager
Retrieve information about the specified secondary NSX Manager.
Delete the specified secondary NSX Manager.
Update the the specified secondary NSX manager IP or thumbprint in the universal sync configuration.
Working With Universal Sync Entities
Retrieve the status of a universal sync entity.
Working With Universal Sync Status
Retrieve the universal sync status.
applianceManager
Working With the Appliance Manager
With the appliance management tool, you can manage:
- System configurations like network configuration, syslog, time settings, and certificate management etc.
- Components of appliance such as NSX Manager, Postgres, SSH component, RabbitMQ service.
- Overall support related features such as tech support logs, backup restore, status, and summary reports of appliance health.
Global Information for NSX Manager
Retrieve global information containing version information as well as current logged in user.
Summary Information for NSX Manager
Retrieve system summary info such as address, DNS name, version, CPU, memory and storage.
Component Information for NSX Manager
Retrieve summary of all available components and their status info.
NSX Manager Appliance CPU Information
Retrieve NSX Manager Appliance CPU information.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method updated. Added cpuUsageIndicator parameter. |
NSX Manager Appliance CPU Details
Retrieve details about CPU utilization for the NSX Manager Appliance.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
NSX Manager Appliance Uptime Information
Retrieve NSX Manager uptime information.
Example response:
25 days, 22 hours, 11 minutes
NSX Manager Appliance Memory Information
Retrieve NSX Manager memory information.
NSX Manager Appliance Storage Information
Retrieve NSX Manager storage information.
NSX Manager Appliance Network Settings
Retrieve network information for the NSX Manager appliance. i.e. host name, IP address, DNS settings.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method updated. New parameter dynamicIPAddress added. The parameter tells whether the IP address of the NSX Appliance Manager is dynamically allocated or not. If dynamicIPAddress parameter is true, then the Unconfigure ipv4/ipv6 button on the UI is disabled. |
Update network information for the NSX Manager appliance.
Working With DNS Configuration
Configure DNS.
Delete DNS server configuration.
Working With Security Settings
Retrieve the NSX Manager FIPS and TLS settings.
Method history:
| Release | Modification |
|---|---|
| 6.3.0 | Method introduced. |
Update the NSX Manager security settings, including FIPS and TLS.
Do not enable FIPS until you have upgraded all NSX components to NSX 6.3.0 or later. Enable FIPS on NSX Edges before enabling it on the NSX Manager.
Changing the FIPS mode will reboot the NSX Manager appliance.
Method history:
| Release | Modification |
|---|---|
| 6.3.0 | Method introduced. |
Working With TLS Settings
Retrieve TLS settings.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Update TLS settings.
Include a comma separated list of the TLS versions you want to enable, for both server and client.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Working With Time Settings
You can either configure time or specify the NTP server to be used for time synchronization.
Retrieve time settings, like timezone or current date and time with NTP server, if configured.
Configure time or specify the NTP server to use for time synchronization.
Configure System Locale
Retrieve locale info.
Configure locale.
Working With Syslog Server
Retrieves only the first syslog server among the servers configured.
Configures one syslog server. If there are syslog server(s) already configured, this API replaces the first one in the list.
Deletes all the syslog servers.
Working With Multiple Syslog Servers
Retrieves all syslog servers configured on the NSX Manager.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
Configure one or more syslog servers. Unconfigures all servers that were previously configured, and configures the one provided in the request body for this API.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
Deletes all the syslog servers. Same as DELETE /system/syslogserver API.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method introduced. |
Working With Components
The NSX Manager appliance has the following components.
| Component | Description |
|---|---|
| NSX | NSX Manager |
| NSXREPLICATOR | Universal Synchronization Service |
| RABBITMQ | RabbitMQ - Messaging service |
| SSH | SSH Service |
| VPOSTGRES | vPostgres - Database service |
Retrieve all appliance manager components.
Working With a Specific Component
Retrieve details for the specified component.
Working With Component Dependencies
Retrieve dependency details for the specified component.
Working With Component Dependents
Retrieve dependents for the specified component.
Working With Component Status
Retrieve current status for the specified component.
Toggle Component Status
Start or stop a component.
Working With the Appliance Management Web Application
Restart the appliance management web application.
NSX Manager Appliance Backup Settings
You can back up and restore your NSX Manager data, which can include system configuration, events, and audit log tables. Configuration tables are included in every backup. Backups are saved to a remote location that must be accessible by the NSX Manager.
FTP parameters for backup and restore
| Parameter | Description | Comments |
|---|---|---|
| transferProtocol | Transfer protocol. | Required. SFTP or FTP. |
| hostNameIPAddress | Backup server hostname or IP address. | Required. |
| port | Transfer protocol port. | Required. Determined by backup server configuration, standard ports are 22 for SFTP, 21 for FTP. |
| userName | User name to log in to backup server. | Required. |
| password | Password for user on backup server. | Required. |
| backupDirectory | Directory location to save backup files on backup server. | Required. |
| fileNamePrefix | Prefix for backup files. | Required. |
| passPhrase | Passphrase to encrypt and decrypt backups. | Required. |
| passiveMode | Use passive mode. | Optional. Default is true. |
| useEPRT | Use EPRT. | Optional. Default is false. |
| useEPSV | Use EPSV. | Optional. Default is true. |
Backup frequency parameters
| Parameter | Description | Comments |
|---|---|---|
| frequency | Frequency to run backups | WEEKLY, DAILY, or HOURLY. |
| dayOfWeek | Day of week to run backups. | Required for WEEKLY backups. SUNDAY, MONDAY, ..., SATURDAY. |
| hourOfDay | Hour of day to run backups. | Required for WEEKLY and DAILY backups. [0-23]. |
| minuteOfHour | Minute of hour to run backups. | Required for WEEKLY, DAILY, and HOURLY backups. [0-59]. |
| excludeTable | Table to exclude from backups. | Optional if excludeTables section is omitted. Specify AUDIT_LOG, SYSTEM_EVENTS, or FLOW_RECORDS. You can provide multiple excludeTable parameters. |
Retrieve backup settings.
Configure backups on the appliance manager.
You must set a passPhrase for the backups. The passphrase is used to encrypt and decrypt backup files. If you do not set a passphrase, backups will fail. If you forget the passphrase set on a backup file, you cannot restore that backup file.
Method history:
| Release | Modification |
|---|---|
| 6.3.3 | Method updated. Parameters passiveMode and useEPSV previously defaulted to false, now default to true. |
Delete appliance manager backup configuration.
NSX Manager Appliance Backup FTP Settings
See NSX Manager Appliance Backup Settings for details.
Configure FTP settings.
Method history:
| Release | Modification |
|---|---|
| 6.3.3 | Method updated. Parameters passiveMode and useEPSV previously defaulted to false, now default to true. |
NSX Manager Appliance Backup Exclusion Settings
See NSX Manager Appliance Backup Settings for details.
Specify tables that need not be backed up.
NSX Manager Appliance Backup Schedule Settings
See NSX Manager Appliance Backup Settings for details.
Set backup schedule.
Delete backup schedule.
NSX Manager Appliance On-Demand Backup
Start an on-demand NSX Manager backup.
You must set the Content-Type header to application/xml for the backup to run successfully.
Working With NSX Manager Appliance Backup Files
Retrieve list of all backups available at configured backup location.
Restoring Data from an NSX Manager Appliance Backup File
Restore data from a backup file.
Retrieve a list of restore files using GET /api/1.0/appliance-management/backuprestore/backups.
Restore the backup to a newly deployed, unconfigured NSX Manager appliance. Restoring to an NSX Manager which is in use might result in inconsistent behavior.
Method history:
| Release | Modification |
|---|---|
| 6.4.1 | Method updated. Query parameter forceRestore added. |
Working With Tech Support Logs by Component
Generate tech support logs. The location response header contains the location of the created tech support file.
Working With Tech Support Log Files
Download tech support logs.
Working With Support Notifications
Retrieve all system generated notifications.
Delete all notifications.
Acknowledge Notifications
Acknowledge a notification. The notification is then deleted from the system.
Upgrading NSX Manager Appliance
To upgrade NSX Manager, you must do the following:
- upload an upgrade bundle
POST /api/1.0/appliance-management/upgrade/uploadbundle/{componentID} - retrieve the upgrade information
GET /api/1.0/appliance-management/upgrade/information/{componentID} - edit the preUpgradeQuestionsAnswers section of the upgrade information response to include answers
- start the upgrade, providing the edited preUpgradeQuestionsAnswers section as the request body
POST /api/1.0/appliance-management/upgrade/start/{componentID}
Upload an NSX Manager Upgrade Bundle
You must upload the upgrade bundle using the form-data content-type. Consult the documentation for your REST client for instructions.
Do not set other Content-type headers in your request, for example, Content-type: application/xml.
When you upload a file as form-data, you must provide a key and a value for the file. The key is file, and the value is the location of the upgrade bundle file.
Example using curl
/usr/bin/curl -v -k -i -F file=@/tmp/VMware-NSX-Manager-upgrade-bundle-6.2.7-5343628.tar.gz -H 'Authorization: Basic YWRtaW46ZGXXXXXXXX=='
https://192.168.110.42/api/1.0/appliance-management/upgrade/uploadbundle/NSX
Upload upgrade bundle.
Upload an NSX Manager Upgrade Bundle from URL
You can upload the upgrade bundle using the URL. Supported protocols are HTTP, HTTPS, and FTP.
You must provide the URL of the upgrade bundle file. For example:
Upload upgrade bundle from URL.
Method history:
| Release | Modification |
|---|---|
| 6.3.3 | Method introduced. |
| 6.4.0 | Method updated. FTP protocol support added. |
Prepare for NSX Manager Upgrade
Once you have uploaded an upgrade bundle, you must retrieve information about the upgrade. This request contains pre-upgrade validation warnings and error messages, along with pre-upgrade questions.
You use the preUpgradeQuestionsAnswers section with the addition of your answers to create the request body for the POST
/api/1.0/appliance-management/upgrade/start/{componentID} request to start the backup. See Start the NSX Manager Upgrade for more information.
Start the NSX Manager Upgrade
Start upgrade process.
If you want to enable SSH or join the VMware CEIP program, you must specify Yes (not YES) for the answer parameter.
Working With Certificates on the NSX Manager Appliance
Working With Keystore Files
You must upload a key store file by using the form-data content-type in the request body. See the documentation of your REST client for instructions.
To upload a file with form-data as the content-type, specify a key and a value for the file. The key is file with type as File, and the value is the keystore file that you want to upload.
Example using curl
/usr/bin/curl -v -k -i -F file=@/tmp/cert.p12 -H 'Authorization: Basic YWRtaW46ZGXXXXXXXX=='
https://192.168.110.42/api/1.0/appliance-management/certificatemanager/pkcs12keystore/nsx?password=password
Upload keystore file.
Input is PKCS#12 formatted NSX file with form-data.
NSX Manager Certificate Manager
Retrieve certificate information from the NSX Manager.
Method history:
| Release | Modification |
|---|---|
| 6.4.4 | Method updated. PEM encoding of the certificate is added in the response body. |
Working With Certificate Signing Requests
Create a certificate signing request (CSR) for NSX Manager.
The response header contains the created file location.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. Replaces PUT /api/1.0/appliance-management/certificatemanager/csr/nsx. Added two query parameters action and expires_after. |
Retrieve generated certificate signing request (CSR).
Working With Certificate Chains
You must upload a certificate chain file by using the form-data content-type in the request body. See the documentation of your REST client for instructions.
To upload a file with form-data as the content-type, specify a key and a value for the file. The key is file with type as File, and the value is the certificate chain file that you want to upload.
Example using curl
/usr/bin/curl -v -k -i -F file=@/tmp/cert.pem -H 'Authorization: Basic YWRtaW46ZGXXXXXXXX=='
https://192.168.110.42/api/1.0/appliance-management/certificatemanager/uploadchain/nsx
Upload certificate chain.
Input is certificate chain file which is a PEM encoded chain of certificates received from the certification authority after signing a CSR.
threaddump
Working with NSX Manager Debug APIs
You can use the NSX Manager debug APIs to troubleshoot problems on the NSX Manager.
Generates the thread dump of the NSX Manager and captures the output of the top command. The top output helps you to monitor the processes and the usage of the system resources on the NSX Manager. The combined output (top output + thread dump) is saved in a separate threaddump_top log file. To view the files, download the NSX Manager tech support bundle. The files are available in Bundle_Name\logs\threaddump.
Note: Starting in NSX 6.4.5, the name of the log file is changed to threaddump.top. After you upgrade to NSX 6.4.5 and generate the thread dump, the old threaddump_top file that existed before the upgrade is preserved in Bundle_Name\preupgradeslot\logs\threaddump. The new thread dump (threaddump.top) is created and saved in Bundle_Name\logs\threaddump.
systemEvents
Working With NSX Manager System Events
Get NSX Manager system events
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method updated. New parameters eventSourceId, eventSourceType, eventSourceIP added under eventSourceInfo. |
hostevents
Working with Host Event Notifications
You can enable host event notifications on the NSX Manager as a security feature to detect potential denial-of-service (DoS) attack on hosts. By default, host event notifications are enabled. To view host event notifications in the vSphere Web Client, navigate to Networking & Security > System > Events > Monitor > System Events. These notifications are also displayed as alarms in the vSphere Web Client.
Retrieve configuration of host event notifications.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method added. |
Add configuration of host event notifications on the NSX Manager and host.
Method history:
| Release | Modification |
|---|---|
| 6.4.0 | Method added. |
Request body parameters:
- enabled - Required. Enable or disable host event notifications. Options are True or False.
- notificationInterval - Required. Time interval in seconds at which the NSX Manager receives host event notifications from each host. Valid range is 300 to 3600.
dhcpStarvWhitelist
Working With DHCP Starv WhiteList
Hosts use vCenter alerts and dashboard alerts to notify users about DoS attacks on the hosts. In NSX 6.4.4 and earlier, you can enable and disable DHCP DoS attack notifications on the hosts only at the global level. Starting with NSX Data Center 6.4.5, you can use APIs to enable or disable DHCP DoS attack notifications on a per port basis (dvPort).
By default, DHCP DoS attack notifications are enabled on all the ports. However, you can disable these notifications on the ports that are expected to route DHCP packets. NSX 6.4.5 introduces APIs to create and modify a DHCP Starv Whitelist, which you can use to exclude selected ports from checking DHCP DoS attack notifications. For example, you can identify the third-party router VMs and disable notifications for the ports on those VMs by using the APIs. On the ESG VMs, the APIs are automatically executed to whitelist all the vNICs of the ESG VMs, and no user intervention is required.
Note: With NSX, you cannot whitelist ports when a VM or an Edge is connected to a VLAN-based port group.
DHCP Starv Whitelist Parameters
| Parameter | Description | Comments |
|---|---|---|
| vmId | Object ID of the virtual machine. | Required. |
| virtualWire | Object ID of the virtualwire (logical switch). | Required. For example, virtualwire-1. |
| vnicUuid | Index of the vNIC for a VM. | Optional. Use the VMInstanceUuid.deviceId format to specify the vNIC of a VM (vnicId). For example, 564d05d4-29f3-94ad-7fa5-47ca2be93796.000. If you omit the vnicUuid, all vNICs for that VM and virtualwire combination are added to the whitelist. |
Create a new DHCP starv whitelist to exclude selected distributed virtual ports (dvPorts) from checking DoS attacks on hosts. In the whitelist, specify combinations of vmId, virtualwire, and vnicId to identify ports on the dvSwitch that you want to exclude.
In a multi-vCenter environment, you must create a separate whitelist that is local to the NSX Manager and vCenter combination. For universal virtualwires, unique dvPortGroups are created on the dvSwitches that participate in the logical network. NSX Manager associated with the vCenter Server manages the ports created on the dvPortGroups in that vCenter.
Note: It is recommended to remove the whitelist entries before the following situations occur, else the whitelist might grow unrestricted:
- Third-party router VMs are deleted.
- vNICs on the third-party router VMs are deleted or reconfigured to another logical switch (virtualwire).
For example, imagine that you have a third-party router VM connected to dvPort1 and dvPort1 is added to the whitelist. Now, you want to move the VM from dvPort1 to dvPort2. Before moving the VM, first remove dvPort1 from the whitelist, and then add dvPort2 to the whitelist. To summarize, use the following workflow:
- Run the DELETE API request (without force option) to remove dvPort1 from the whitelist.
- Move the VM from dvPort1 to dvPort2.
- Run the POST API request to add dvPort2 to the whitelist.
Method history:
| Release | Modification |
|---|---|
| 6.4.5 | Method introduced. |
Retrieve information about all the entries in the DHCP starv whitelist.
Method history:
| Release | Modification |
|---|---|
| 6.4.5 | Method introduced. |
Working With a Specific DHCP Starv Whitelist Entry
Retrieve information about the specified DHCP starv whitelist entry.
Method history:
| Release | Modification |
|---|---|
| 6.4.5 | Method introduced. |
Delete the specified DHCP starv whitelist entry.
Method history:
| Release | Modification |
|---|---|
| 6.4.5 | Method introduced. |
Working With DHCP Starv Whitelist Entries of a Specific VM
Retrieve information about all the DHCP starv whitelist entries of the specified VM.
Method history:
| Release | Modification |
|---|---|
| 6.4.5 | Method introduced. |
Delete all the DHCP starv whitelist entries of the specified VM.
Method history:
| Release | Modification |
|---|---|
| 6.4.5 | Method introduced. |
auditLogs
Working With NSX Manager Audit Logs
You can retrieve NSX Manager audit logs. The following table translates the names used for modules in the API and the vSphere Web Client UI.
Navigate to Networking & Security > NSX Managers > NSX Manager > Monitor > Audit Logs to view the logs in the vSphere Web Client UI.
Module Names for Audit Logs in API and UI
| API Names for Audit Log Modules | UI Names for Audit Log Modules |
|---|---|
| UNKNOWN | Unknown |
| ZONES_FIREWALL | App Firewall |
| EDGE_FIREWALL | Edge Firewall |
| EDGE | Edge |
| EDGE_NAT | Edge NAT |
| EDGE_SNAT | Edge SNAT |
| EDGE_DNAT | Edge DNAT |
| EDGE_DHCP | Edge DHCP |
| EDGE_VPN | Edge VPN |
| EDGE_LB | Edge Load Balancer |
| EDGE_SYSLOG | Edge Syslog |
| EDGE_STATIC_ROUTING | Edge Static Routing |
| EDGE_TRAFFICSTATS | Edge Traffic Stats |
| EDGE_SUPPORT | Edge Support |
| EDGE_CERTIFICATE | Edge Certificate |
| EPSEC | Guest Introspection |
| NETWORK_ISOLATION | Port Group Isolation |
| INVENTORY | Inventory |
| SDD | Data Security |
| SHIELD | vShield |
| SYSTEM | System |
| UPGRADE | Upgrade |
| ACCESS_CONTROL | Access Control |
| DLP | Data Recovery |
| APPLICATION | Application |
| IP_SET | IP Addresses |
| MAC_SET | MAC Addresses |
| SECURITY_GROUP | Security Group |
| SPOOFGUARD | SpoofGuard |
| APP_FAIL_SAFE | App Fail Safe Config |
| APP_EXCLUDE_LIST | App Exclude List |
| SYSLOG_SERVER_CONFIG | Syslog Server Config |
| TRUST_STORE | Trust Store |
| PASSWORD_CHANGE | Password Change |
| SSO_CONFIG | SSO Config |
| BACKUP_RESTORE | Backup Restore |
| SSL_CERTIFICATE | SSL Certificate |
| APPLICATION_GROUP | Application Group |
| NAMESPACE | Namespace |
| DYNAMIC_SET | Dynamic set |
| DYNAMIC_CRITERIA | Dynamic criteria |
| NamespaceService | Namespace Service |
| SECURITY_POLICY | Security Policy |
| SECURITY_TAG | Security Tag |
telemetry
Working With the VMware Customer Experience Improvement Program
NSX Data Center for vSphere participates in VMware’s Customer Experience Improvement Program (CEIP).
See "Customer Experience Improvement Program" in the NSX Administration Guide for more information.
Working With the VMware CEIP Configuration
You can join or leave the CEIP at any time. You can also define the frequency and the days the information is collected.
CEIP Parameters
| Parameter | Description | Comments |
|---|---|---|
| enabled | Enable status of data collection | true or false. |
| frequency | Frequency of data collection | daily, weekly, or monthly. |
| dayOfWeek | Day to collect data | SUNDAY, MONDAY, ... SATURDAY. |
| hourOfDay | Hour to collect data | 0-23. |
| minutes | Minute to collect data | 0-59. |
| lastCollectionTime | Time of last collection. | Timestamp in milliseconds. Read only. |
Retrieve the CEIP configuration.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Update the CEIP configuration.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
| 6.3.3 | Method updated. minutes parameter is configurable. |
Working With Proxy Setting for VMware CEIP
If your NSX Manager appliance does not have a direct connection to the internet, you can configure a proxy server for the purpose of sending information collected by CEIP to VMware.
CEIP Proxy Parameters
| Parameter | Description | Comments |
|---|---|---|
| enabled | Enabled status of proxy | Required. Default is AUTO. OFF: use direct connection MANUAL: use settings defined here AUTO: use proxy auto-discovery. |
| scheme | Proxy scheme. | Required if enabled is set to MANUAL. Valid value: http. Default is http. |
| hostname | Hostname of proxy server | Required if enabled is set to MANUAL. |
| port | Port used for proxy server | Required if enabled is set to MANUAL. Default is 0. |
| username | Proxy server username | Optional. |
| password | Proxy server password | Optional. Not included in GET response. |
Retrieve the NSX Manager proxy settings for CEIP.
Method history:
| Release | Modification |
|---|---|
| 6.3.3 | Method introduced. |
Retrieve the NSX Manager proxy settings for CEIP.
Method history:
| Release | Modification |
|---|---|
| 6.3.3 | Method introduced. |
nwfabric
Working With Network Fabric Configuration
Working With Network Virtualization Components and VXLAN
Cluster preparation can be broken down into the following:
- Install VIB and non-VIB related action: Before any per-host config a VIB must be installed on the host. The feature can use this time to perform other bootstrapping tasks which do not depend on VIB-installation. e.g. VXLAN creates the vmknic-pg and sets up some opaque data.
- Post-VIB install: Prepare each host for the feature. In the case of VXLAN, create vmknics.
Install network fabric or VXLAN.
This method can be used to perform the following tasks:
- Install Network Virtualization Components
- Configure VXLAN
- Configure VXLAN with LACPv2
- Reset Communication Between NSX Manager and a Host or Cluster
Starting in NSX 6.4.7, before installing the network virtualization components on clusters that are managed by vCenter 7.0 or later, the API checks whether vSphere Lifecycle Management (vLCM) image is used on the clusters. If any vCenter cluster uses a vLCM image, the API throws an error.
Host preparation is not allowed on vCenter clusters that use a vLCM image.
Parameter Information
| Name | Comments |
|---|---|
| resourceId | vCenter MOB ID of cluster. For example, domain-c7. A host can be specified when resetting communication. For example, host-24. |
| featureId | Feature to act upon. Omit for network virtualization components operations. Use com.vmware.vshield.vsm.vxlan for VXLAN operations, com.vmware.vshield.vsm.messagingInfra for message bus operations. |
| ipPoolId | Used for VXLAN installation. If not specified, DHCP is used for VTEP address assignment. |
| teaming | Used for VXLAN installation. Options are FAILOVER_ORDER, ETHER_CHANNEL, LACP_ACTIVE, LACP_PASSIVE, LOADBALANCE_LOADBASED, LOADBALANCE_SRCID, LOADBALANCE_SRCMAC, LACP_V2 |
| uplinkPortName | The uplinkPortName as specified in vCenter. |
Install Network Virtualization Components
POST /api/2.0/nwfabric/configure
<nwFabricFeatureConfig>
<resourceConfig>
<resourceId>CLUSTER MOID</resourceId>
</resourceConfig>
</nwFabricFeatureConfig>
Configure VXLAN
POST /api/2.0/nwfabric/configure
<nwFabricFeatureConfig>
<featureId>com.vmware.vshield.vsm.vxlan</featureId>
<resourceConfig>
<resourceId>CLUSTER MOID</resourceId>
<configSpec class="clusterMappingSpec">
<switch>
<objectId>DVS MOID</objectId></switch>
<vlanId>0</vlanId>
<vmknicCount>1</vmknicCount>
<ipPoolId>IPADDRESSPOOL ID</ipPoolId>
</configSpec>
</resourceConfig>
<resourceConfig>
<resourceId>DVS MOID</resourceId>
<configSpec class="vdsContext">
<switch>
<objectId>DVS MOID</objectId>
</switch>
<mtu>1600</mtu>
<teaming>ETHER_CHANNEL</teaming>
</configSpec>
</resourceConfig>
</nwFabricFeatureConfig>
Configure VXLAN with LACPv2
POST /api/2.0/nwfabric/configure
<nwFabricFeatureConfig>
<featureId>com.vmware.vshield.nsxmgr.vxlan</featureId>
<resourceConfig>
<resourceId>CLUSTER MOID</resourceId>
<configSpec class="clusterMappingSpec">
<switch>
<objectId>DVS MOID</objectId>
</switch>
<vlanId>0</vlanId>
<vmknicCount>1</vmknicCount>
</configSpec>
</resourceConfig>
<resourceConfig>
<resourceId>DVS MOID</resourceId>
<configSpec class="vdsContext">
<switch>
<objectId>DVS MOID</objectId>
</switch>
<mtu>1600</mtu>
<teaming>LACP_V2</teaming>
<uplinkPortName>LAG NAME</uplinkPortName>
</configSpec>
</resourceConfig>
</nwFabricFeatureConfig>
Reset Communication Between NSX Manager and a Host or Cluster
POST /api/2.0/nwfabric/configure?action=synchronize
<nwFabricFeatureConfig>
<featureId>com.vmware.vshield.vsm.messagingInfra</featureId>
<resourceConfig>
<resourceId>resourceId</resourceId>
</resourceConfig>
</nwFabricFeatureConfig>
Upgrade Network virtualization components.
This API call can be used to upgrade network virtualization components. After NSX Manager is upgraded, previously prepared clusters must have the 6.x network virtualization components installed.
Remove VXLAN or network virtualization components.
Removing network virtualization components removes previously installed VIBs, tears down NSX Manager to ESXi messaging, and removes any other network fabric dependent features such as logical switches. If a feature such as logical switches is being used in your environment, this call fails.
Removing VXLAN does not remove the network virtualization components from the cluster.
| Name | Comments |
|---|---|
| resourceId | vCenter MOB ID of cluster. For example, domain-c7. |
| featureId | Feature to act upon. Omit for network virtualization components operations. Use com.vmware.vshield.vsm.vxlan for VXLAN operations. |
Remove Network Virtualization Components
<nwFabricFeatureConfig>
<resourceConfig>
<resourceId>CLUSTER MOID</resourceId>
</resourceConfig>
</nwFabricFeatureConfig>
Remove VXLAN
<nwFabricFeatureConfig>
<featureId>com.vmware.vshield.vsm.vxlan</featureId>
<resourceConfig>
<resourceId>CLUSTER MOID</resourceId>
</resourceConfig>
</nwFabricFeatureConfig>
Remove VXLAN with vDS context
<nwFabricFeatureConfig>
<featureId>com.vmware.vshield.vsm.vxlan</featureId>
<resourceConfig>
<resourceId>CLUSTER MOID</resourceId>
<configSpec class="map">
<entry>
<keyclass="java.lang.String">vxlan</key>
<valueclass="java.lang.String">cascadeDeleteVdsContext</value>
</entry>
</configSpec>
</resourceConfig>
</nwFabricFeatureConfig>
Resolving Host Preparation Issues
Resolve all issues associated with host preparation (VIB installation). You can resolve issues only at the cluster level.
Working With Network Fabric Features
Retrieves all network fabric features available on the cluster. Multiple featureInfo sections may be returned.
Working With Network Fabric Status
Retrieve the network fabric status of the specified resource.
Working With Network Fabric Status of Child Resources
Retrieve the network fabric status of child resources of the specified resource.
Working With Status of Resources by Criterion
Retrieve status of resources by criterion.
Working With Locale ID Configuration For Clusters
Retrieve the locale ID for the specified cluster.
Update the locale ID for the specified cluster.
Delete locale ID for the specified cluster.
Working With Locale ID Configuration for Hosts
Retrieve the locale ID for the specified host.
Update the locale ID for the specified host.
Delete the locale ID for the specified host.
securityFabric
Working With Security Fabric and Security Services
The security fabric simplifies and automates deployment of security services and provide a platform for configuration of the elements that are required to provide security to workloads. These elements include:
Internal components:
- Guest Introspection Universal Service Virtual Machine
- Guest Introspection Mux
- Logical Firewall
External components:
- Partner OVFs / VIBs
- Partner vendor policy templates
For partner services, the overall workflow begins with registration of services by partner consoles, followed by deployment of the services by the administrator.
Subsequent workflow is as follows:
- Select the clusters on which to deploy the security fabric (Mux, Traffic filter, USVM).
- Specify an IP pool to be used with the SVMs (available only if the partner registration indicates requirement of static IPs)
- Select portgroup (DVPG) to be used for each cluster (a default is pre-populated for the user).
- Select datastore to be used for each cluster (a default is pre-populated for the user).
- NSX Manager deploys the components on all hosts of the selected clusters.
Once you deploy the security fabric, an agency defines the configuration needed to deploy agents (host components and appliances). An agency is created per cluster per deployment spec associated with services. Agents are deployed on the selected clusters, and events / hooks for all the relevant actions are generated.
Request parameters
| Parameter | Description |
|---|---|
| dataStore | Needs to be specified only in POST call. In PUT call, it should be left empty. |
| dvPortGroup | Optional. If not specified, then user will set the Agent using vCenter Server. |
| ipPool | Optional. If not specified, IP address is assigned through DHCP. |
Deploy security fabric.
Upgrade service to recent version.
The datastore, dvPortGroup, and ipPool variables should either not be specified or have same value as provided at time of deployment.