VMware NSX for vSphere API documentation version 6.3
https://{nsxmanager}/api
Introduction
This manual, the NSX for vSphere API Guide, describes how to install, configure, monitor, and maintain the VMware® NSX system by using REST API requests.
Intended Audience
This manual is intended for anyone who wants to use REST API to programmatically control NSX in a VMware 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 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: docfeedback@vmware.com.
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 browser-based clients include the Chrome app, Postman, or the Firefox add-on, RESTClient. Curl is a command-line tool that can function as a REST client. 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 uses basic authentication.
You must configure your REST client to send the NSX Manager authentication credentials using basic authentication.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 an XML request body, you must include the
Content-Type: application/xmlheader.
Some requests require additional headers, for example, firewall configuration changes require theIf-Matchheader. This is noted on each method description.To ensure you always receive XML response bodies, set the
Accept: application/xmlheader.
Some API methods respond with JSON output, which is an experimental feature. Setting the Accept header ensures you always get XML output. 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 8
update-date
Modified MAY 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.
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. |
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
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.
logicalSwitchesGlobal
Working With Logical Switches in All Transport Zones
Retrieve information about all logical switches in all transport zones.
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.
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. |
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
Add controller syslog exporter on the controller.
Retrieve details about the syslog exporter on the controller.
Deletes syslog exporter on the specified controller node.
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 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.
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.
capacityUsage
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. |
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
Retrieve a user's role (possible roles are super_user, vshield_admin, enterprise_admin, security_admin, and audit).
Add role and resources for a user.
Change a user's 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
Working With Scoping Objects
Retrieve a list of objects that can be used to define a user's access scope.
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.
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 IPSets
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.
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. |
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 CPU Information
Retrieve NSX Manager CPU information.
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.
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 Servers
Retrieve syslog servers.
Configure syslog servers.
Delete syslog servers.
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 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.
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, and HTTPS.
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. |
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
Upload keystore file.
Input is PKCS#12 formatted NSX file along with password.
NSX Manager Certificate Manager
Retrieve certificate information from NSX Manager.
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. |
Retrieve generated certificate signing request (CSR).
Working With Certificate Chains
Upload certificate chain.
Input is certificate chain file which is a PEM encoded chain of certificates received from the CA after signing a CSR.
systemEvents
Working With NSX Manager System Events
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 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
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.
Working With a Specified Service
Retrieve all clusters on which the service is installed.
Uninstall specified service from specified clusters.
Working With Service Dependencies
Services installed through the security fabric may be dependent on other services. When an internal service is registered, a dependencyMap is maintained with the service-id and implementation type of the internal service.
When partner registers a new service, the security fabric looks up its implementation type in the dependencyMap to identify the service it depends on, if any. Accordingly, a new field in Service object called dependsOn-service-id is populated.
Retrieve service on which the specified service depends.
Working With Installed Services on a Cluster
Retrieve all services deployed along with their status.
Uninstall a service. Fails if you try to remove a service that another service depends on.
In order to uninstall services in any order, set parameter ignoreDependency to true.
Working With a Specific Service on a Cluster
Retrieve detailed information about the service.
eventControl
Working With Data Collection for Activity Monitoring
Activity Monitoring provides visibility into your virtual network to ensure that security policies at your organization are being enforced correctly.
A Security policy may mandate who is allowed access to what applications. The Cloud administrator can generate Activity Monitoring reports to see if the IP based firewall rule that they set is doing the intended work. By providing user and application level detail, Activity Monitoring translates high level security policies to low level IP address and network based implementation.
Once you enable data collection for Activity Monitoring, you can run reports to view inbound traffic (such as virtual machines being accessed by users) as well as outbound traffic (resource utilization, interaction between inventory containers, and AD groups that accessed a server).
You must enable data collection for one or more virtual machines on a vCenter Server before running an Activity Monitoring report. Before running a report, ensure that the enabled virtual machines are active and are generating network traffic.
You should also register NSX Manager with the AD Domain Controller. See "Working With Domains".
Note that only active connections are tracked by Activity Monitoring. Virtual machine traffic blocked by firewall rules at the vNIC level is not reflected in reports.
In case of an emergency such as a network overload, you can turn off data collection at a global level. This overrides all other data collection settings.
Some API calls may require the VMID, which is the MOID of the guest virtual machine. You can retrieve this by queuing the vCenter mob structure (https:VC-IP-Address/mob). The VMID is listed under host structure.
Working With Data Collection on a Specific Virtual Machine
You must enable data collection at least five minutes before running an Activity Monitoring report.
Enable or disable data collection on a virtual machine
Set value to enabled or disabled.
Override Data Collection
Turn data collection on or off at the global level.
In case of an emergency such as a network overload, you can turn off data collection at a global level (kill switch). This overrides all other data collection settings.
Set value to enabled or disabled.
Retrieve Data Collection Configuration for a Specific Virtual Machine
When reporting per virtual machine configuration, current kill switch status is also reported too. The effective configuration of a virtual machine is determined by both kill switch config and per virtual machine configuration. If kill switch is on, event collection is effectively disabled regardless of what its per virtual machine configuration is; if kill switch is off, per virtual machine configuration determines whether event collection should be performed for this virtual machine.
Retrieve per VM configuration for data collection.
activityMonitoring
Working With Activity Monitoring
Working With Aggregated User Activity
Get aggregated user activity (action records) using parameters. Requires that NSX Guest Introspection is configured, NSX Manager must be registered with Active Directory, and data collection is enabled on one or more VMs.
View Outbound Activity
You can view what applications are being run by a security group or desktop pool and then drill down into the report to find out which client applications are making outbound connections by a particular group of users. You can also discover all user groups and users who are accessing a particular application, which can help you determine if you need to adjust identity firewall in your environment.
- query=resource
- param=<param-name>:<param-type>:<comma-separated-values>:<operator>, where:
- <param-name> is one of:
- src (required)
- dest (required)
- app
- <param-type> is one of:
- for src: SECURITY_GROUP, DIRECTORY_GROUP, DESKTOP_POOL
- for dest: VIRTUAL_MACHINE
- for app: SRC_APP
- <comma-separated-values> is a comma-separated numbers (optional). If none specified then no filter is applied.
- <operator> is one of INCLUDE, EXCLUDE (default is INCLUDE).
- <param-name> is one of:
Example: View user activities to VM ID 1 originating from application ID 1GET /api/3.0/ai/records?query=resource&interval=60m¶m=src:DIRECTORY_GROUP¶m=dest:VIRTUAL_MACHINE:1¶m=app:SRC_APP:1
View Inbound Activity
You can view all inbound activity to a server by desktop pool, security group, or AD group.
- query=sam
- param=<param-name>:<param-type>:<comma-separated-values>:<operator>, where:
- <param-name> is one of:
- src (required)
- dest (required)
- app
- <param-type> is one of:
- for src: SECURITY_GROUP, DIRECTORY_GROUP, DESKTOP_POOL
- for dest: VIRTUAL_MACHINE
- for app: DEST_APP
- <comma-separated-values> is a comma-separated numbers (optional). If none specified then no filter is applied.
- <operator> is one of INCLUDE, EXCLUDE, NOT (default is INCLUDE).
- <param-name> is one of:
Example: View user activities to VM ID 1 originating from application ID 1GET /api/3.0/ai/records?query=containers&interval=60m¶m=dest:SECURITY_GROUP:1:EXCLUDE¶m=src:SECURITY_GROUP:1
View Interaction between Inventory Containers
You can view the traffic passing between defined containers such as AD groups, security groups and/or desktop pools. This can help you identify and configure access to shared services and to resolve misconfigured relationships between Inventory container definitions, desktop pools and AD groups.
- query=containers
- param=<param-name>:<param-type>:<comma-separated-values>:<operator>, where:
- <param-name> is one of:
- src (required)
- dest (required)
- <param-type> is one of:
- for src: SECURITY_GROUP, DIRECTORY_GROUP, DESKTOP_POOL
- for dest: SECURITY_GROUP, DESKTOP_POOL*
- <comma-separated-values> is a comma-separated numbers (optional). If none specified then no filter is applied.
- <operator> is one of INCLUDE, EXCLUDE, or NOT (default isINCLUDE*).
- <param-name> is one of:
Example: View interaction between inventory containersGET /api/3.0/ai/records?query=containers&interval=60m¶m=dest:SECURITY_GROUP:1:EXCLUDE¶m=src:SECURITY_GROUP:1
View Outbound AD Group Activity
You can view the traffic between members of defined Active Directory groups and can use this data to fine tune your firewall rules.
- query=adg
- param=<param-name>:<param-type>:<comma-separated-values>:<operator>, where:
- <param-name> is one of:
- src (required)
- adg
- <param-type> is one of:
- for src: SECURITY_GROUP, DESKTOP_POOL
- for adg: USER
- <comma-separated-values> is a comma-separated numbers (optional). If none specified then no filter is applied.
- <operator> is one of INCLUDE, EXCLUDE (default isINCLUDE*).
- <param-name> is one of:
Example: View outbound AD group activityGET https://NSX-Manager-IP-Address/api/3.0/ai/records?query=adg&interval=24h¶m=adg:USER:1:INCLUDE¶m=src:SECURITY_GROUP:1:EXCLUDE
Working With User Details
View Outbound Activity
You can view what applications are being run by a security group or desktop pool and then drill down into the report to find out which client applications are making outbound connections by a particular group of users. You can also discover all user groups and users who are accessing a particular application, which can help you determine if you need to adjust identity firewall in your environment.
- query=resource
- param=<param-name><param-type><comma-separated-values><operator>, where:
- <param-name> is one of:
- src (required)
- dest (required)
- app
- <param-type> is one of:
- for src: SECURITY_GROUP, DIRECTORY_GROUP, DESKTOP_POOL
- for dest: IP - a valid IP address in dot notation, xx.xx.xx.xx
- for app: SRC_APP
- <comma-separated-values> is a comma-separated numbers (optional). If none specified then no filter is applied.
- <operator> is one of INCLUDE, EXCLUDE (default is INCLUDE).
- <param-name> is one of:
Example: View user activities to VM ID 1 originating from application ID 1GET /api/3.0/ai/userdetails?query=resource&stime=2012-10-15T00:00:00&etime=2012-10-20T00:00:00¶m=src:DIRECTORY_GROUP:2¶m=app:SRC_APP:16¶m=dest:IP:172.16.4.52
View Inbound Activity
You can view all inbound activity to a server by desktop pool, security group, or AD group.
- query=sam
- param=<param-name><param-type><comma-separated-values><operator>, where:
- <param-name> is one of:
- src (required)
- dest (required)
- app (required)
- <param-type> is one of:
- for src: SECURITY_GROUP, DIRECTORY_GROUP, DESKTOP_POOL
- for dest: VIRTUAL_MACHINE
- for app: DEST_APP
- <comma-separated-values> is a comma-separated numbers (optional). If none specified then no filter is applied.
- <operator> is one of INCLUDE, EXCLUDE, NOT (default is INCLUDE).
- <param-name> is one of:
Example: View user activities to VM ID 1 originating from application ID 1GET /api/3.0/userdetails?query=sam&interval=60m¶m=app:DEST_APP:1:EXCLUDE¶m=dest:IP:1:EXCLUDE¶m=src:SECURITY_GROUP:1:EXCLUDE
View Interaction between Inventory Containers
You can view the traffic passing between defined containers such as AD groups, security groups and/or desktop pools. This can help you identify and configure access to shared services and to resolve misconfigured relationships between Inventory container definitions, desktop pools and AD groups.
- query=containers
- param=<param-name><param-type><comma-separated-values><operator>, where:
- <param-name> is one of:
- src (required)
- dest (required)
- <param-type> is one of:
- for src: SECURITY_GROUP, DIRECTORY_GROUP, DESKTOP_POOL
- for dest: SECURITY_GROUP, DESKTOP_POOL*
- <comma-separated-values> is a comma-separated numbers (optional). If none specified then no filter is applied.
- <operator> is one of INCLUDE, EXCLUDE, or NOT (default isINCLUDE*).
- <param-name> is one of:
Example: View interaction between inventory containersGET /api/3.0/ai/userdetails?query=containers&interval=60m¶m=dest:SECURITY_GROUP:1:EXCLUDE¶m=src:SECURITY_GROUP:1
View Outbound AD Group Activity
You can view the traffic between members of defined Active Directory groups and can use this data to fine tune your firewall rules.
- query=adg
- param=<param-name><param-type><comma-separated-values><operator>, where:
- <param-name> is one of:
- src (required)
- adg
- <param-type> is one of:
- for src: SECURITY_GROUP, DESKTOP_POOL
- for adg: USER
- <comma-separated-values> is a comma-separated numbers (optional). If none specified then no filter is applied.
- <operator> is one of INCLUDE, EXCLUDE (default is INCLUDE).
- <param-name> is one of:
Example: View outbound AD group activityGET /api/3.0/ai/userdetails?query=adg&interval=24h¶m=adg:USER:1:INCLUDE¶m=src:SECURITY_GROUP:1:EXCLUDE
View Virtual Machine Activity Report
- query=vma
- param=<param-name><param-type><comma-separated-values><operator>, where:
- <param-name> is one of:
- src
- dst
- app
- If no parameters are passed, then this would show all SAM activities
- <param-type> is one of:
- for src: SECURITY_GROUP, DESKTOP_POOL
- for dst: VIRTUAL_MACHINE, VM_UUID
- for app - SRC_APP or DEST_APP
- <comma-separated-values> is a comma-separated numbers (optional). If none specified then no filter is applied.
- <operator> is one of INCLUDE, EXCLUDE (default is INCLUDE).
- <param-name> is one of:
Example: View outbound AD group activityGET /api/3.0/ai/userdetails?query=vma&interval=60m¶m=dest:VIRTUAL_MACHINE:1
¶m=app:DEST_APP:16
Working With a Specific User
Retrieve details for a specific user.
Working With a Specific Application
Retrieve details for specific app.
Working With Discovered Hosts
Retrieve list of all discovered hosts (both by agent introspection and LDAP Sync) and their detail.
Working With Desktop Pools
Retrieve list of all discovered desktop pools by agent introspection.
Working With a Specific Desktop Pool
Retrieve specific desktop pool details.
Working With a Specific Virtual Machine
Retrieve details about a specific virtual machine.
Working With LDAP Directory Groups
Retrieve list of all discovered (and configured) LDAP directory groups.
Working With a Specific LDAP Directory Group
Retrieve details about a specific directory group.
Working With a Specific User's Active Directory Groups
Retrieve Active Directory groups that user belongs to.
Working With Security Groups
Retrieve list of all observed security groups.
Observed entities are the ones that are reported by the agents. For example, if a host activity is reported by an agent and if that host belongs to a security group then that security group would reported as observed in SAM database.
Working With a Specific Security Group
Retrieve details about specific security group.
domain
Working With Domains
After you create a domain, you can apply a security policy to it and run queries to view the applications and virtual machines being accessed by the users of a domain.
Registering Domains
You can a register one or more Windows domains with an NSX Manager and associated vCenter server. NSX Manager gets group and user information as well as the relationship between them from each domain that it is registered with. NSX Manager also retrieves Active Directory credentials. You can apply security policies on an Active Directory domain and run queries to get information on virtual machines and applications accessed by users within an Active Directory domain.
Parameter Values for Registering or Updating a Domain
| Parameter Name | Description | Required? |
|---|---|---|
| ID | Domain id. If you want to create a new domain, do not provide this value. Otherwise, the system will find an existing domain object by this ID and update it. | Required if updating existing domain |
| name | Domain name. This should be the domain's fully qualified name. If it's agent discovered, this will be the NetBIOS name, so you need to update it to FQN in order to support LDAP sync and event log reader. | Required if creating a new domain. |
| description | Domain description | Optional. |
| type | Domain type. Valid values include: AGENT_DISCOVERED, ACTIVE_DIRECTORY, SPECIAL (Do NOT modify SPECIAL domain). For LDAP sync and event log reader work, this need to be set to ACTIVE_DIRECTORY. | Optional. Default is ACTIVE_DIRECTORY. |
| netbiosName | NetBIOS name of domain. This is the domain's NetBIOS name. Normally Agent reported domain name is the NetBIOS name. Confirm from Windows domain settings. | Optional. |
| baseDn | Domain's Base DN (for LDAP sync). Base DN is required for LDAP Sync. If you have a domain like: w2k3.vshield.vmware.com, the base DN is very likely to be: DC=w2k3,DC=vshield,DC=vmware,DC=com. Another example is: domain name is: vs4.net, the base DN should be: DC=vs4,DC=net. You can use a LDAP client and connect to domain controller to find the domain's base DN. | Optional. Required for LDAP sync. |
| rootDn | LDAP Sync root DN. Specify where should LDAP sync start from LDAP tree. This could be an absolute path, for example: OU=Engineer,DC=vs4,DC=net, or a relative path (relative to Base DN), for example: OU=Engineer. | Optional. |
| securityId | Domain's Security ID (SID). This should be filled by LDAP sync process, and should not need to be modified. | Optional. |
| username | Domain's User name (Used for LDAP Sync and/or Event Log reader) | Optional. |
| password | User password | Optional. |
| eventLogUsername | Domain's event log reader username (will use above username if this is NULL) | Optional. |
| eventLogPassword | Domain's event log reader password | Optional. |
Register or update a domain with NSX Manager
Retrieve LDAP Domains
Retrieve all agent discovered (or configured) LDAP domains.
Query LDAP Servers for a Domain
Query LDAP servers for a domain.
Working With EventLog Servers for a Domain
Query EventLog servers for a domain.
Delete EventLog Server
Delete EventLog server.
mappingLists
Working With Mapping Lists
Working With User to IP Mappings
Query user-to-ip mapping list from database.
Working With Host to IP Mappings
Query host-to-ip mapping list from database.
Working With IP to User Mappings
Retrieve set of users associated with a given set of IP addresses during a specified time period. Since more than one user can be associated with a single IP address during the specified time period, each IP address can be associated with zero or more (i.e a SET of) users.
Working With User Domain Groups
Query set of Windows Domain Groups (AD Groups) to which the specified user belongs.
Working With a Specific Static User Mapping
Create static user IP mapping.
Working With Static User Mappings
Query static user IP mapping list.
Working With Static User IP Mappings for a Specific User
Query static user IP mapping for specified user.
Delete static user IP mapping for specified user.
Working With Static User IP Mappings for a Specific IP
Query static user IP mapping for specified IP.
Delete static user IP mapping for specified IP.
activityMonitoringSyslog
Working With Activity Monitoring Syslog Support
solutionIntegration
Working With Solution Integrations
Working With Agents on a Specific Host
Retrieves all agents on the specified host. The response body contains agent IDs for each agent, which you can use to retrieve details about that agent.
Working With a Specific Agent
Retrieve agent (host components and appliances) details.
Working With Agents on a Specific Deployment
Retrieve all agents for the specified deployment.
Working With Conflicting Agencies
When the NSX Manager database backup is restored to an older point in time, it is possible that deployment units for some EAM Agencies are missing. These methods help the administrator identify such EAM Agencies and take appropriate action.
Retrieve conflicting deployment units and EAM agencies, if any, and the allowed operations on them.
Create deployment units for conflicting EAM Agencies, delete conflicting EAM agencies, or delete deployment units for conflicting EAM agencies.
Create deployment units for conflicting EAM agencies
<conflictResolverInfo>
<agencyAction>RESTORE</agencyAction>
</conflictResolverInfo>
Delete conflicting EAM agencies
<conflictResolverInfo>
<agencyAction>DELETE</agencyAction>
</conflictResolverInfo>
Delete deployment units for conflicting EAM agencies
<conflictResolverInfo>
<deploymentUnitAction>DELETE</deploymentUnitAction>
</conflictResolverInfo>
macsets
Working With MAC Address Set Grouping Objects
You can create a MAC address set on the specified scope. On success, the API returns a string identifier for the new MAC address set.
Working With a Specific MAC Address Set
Retrieve details about a MAC address set.
Modify an existing MAC address set.
Delete a MAC address set.
Working With MAC Address Sets on a Specific Scope
Create a MAC address set on the specified scope.
The value parameter can include a single MAC identifier or a comma separated set of MAC identifiers. Universal MAC address sets are read-only from secondary managers.
List MAC address sets on the specified scope.
eam
Working With ESX Agent Manager
vSphere ESX Agent Manager (EAM) automates the process of deploying and managing NSX networking and security services.
Working With EAM Status
Retrieve EAM status from vCenter.
You can verify the status is UP before proceeding with an NSX install or upgrade.
Method history:
| Release | Modification |
|---|---|
| 6.3.5 | Method introduced. |
servicesSystemAlarms
Working With Alarms
Alarms are notifications that are activated in response to an event, a set of conditions, or the state of an object. Alarms, along with other alerts, are displayed on the NSX Dashboard and other screens on the vSphere Web Client UI.
See "Alarms" in the NSX Logging and System Events Guide for more information.
Generally, an alarm gets automatically deleted by the system when the error condition is rectified. Some alarms are not automatically cleared on a configuration update. Once the issue is resolved, you have to clear the alarms manually.
Alarm Parameters
| Paramter | Description | Comments |
|---|---|---|
| resolutionAttempted | Was resolution of the alarm was attempted? | true or false. |
| resolvable | Can the alarm be resolved? | true or false |
| alarmId | ID of the alarm. | For example, 79965. |
| alarmCode | Event code which uniquely identifies the system event. | For example, 130027. |
| alarmSource | The domain object identifier of the source where you can resolve the reported alarm. | For example, edge-3. |
| totalCount | The total number of unresolved alarms. |
Retrieve all unresolved alarms on NSX Manager.
Method history:
| Release | Modification |
|---|---|
| 6.3.3 | Method introduced. |
Working With a Specific System Alarm
You can view and resolve alarms by alarm ID.
Retrieve information about the specified alarm. Both resolved and unresolved alarms can be retrieved.
Method history:
| Release | Modification |
|---|---|
| 6.3.0 | Method introduced. |
Resolve the specified alarm.
System alarms resolve automatically when the cause of the alarm is resolved. For example, if an NSX Edge appliance is powered off, this triggers a alarm. If you power the NSX Edge appliance back on, the alarm resolves. If however, you delete the NSX Edge appliance, the alarm persists, because the alarm cause was never resolved. In this case, you might want to manually resolve the alarm. Resolving the alarm will clear it from the NSX Dashboard.
Method history:
| Release | Modification |
|---|---|
| 6.3.0 | Method introduced. |
servicesAlarmsSource
Working With Alarms from a Specific Source
You can view and resolve alarms from a specific source.
Retrive all alarms from the specified source.
Resolve all alarms for the specified source.
Alarms will resolve automatically when the cause of the alarm is resolved. For example, if an NSX Edge appliance is powered off, this will trigger an alarm. If you power the NSX Edge appliance back on, the alarm will resolve. If however, you delete the NSX Edge appliance, the alarm will persist, because the alarm cause was never resolved. In this case, you may want to manually resolve the alarm. Resolving the alarms will clear them from the NSX Dashboard.
Use GET /api/2.0/services/alarms/{sourceId} to retrieve the list of alarms for the source. Use this response as the request body for the POST call.
taskFramework
Working With the Task Framework
Working with filtering criteria and paging information for jobs on the task framework.
Working With a Specific Job Instance
Retrieve all job instances for the specified job ID.
guestIntrospection
Working With Guest Introspection and Third-party Endpoint Protection (Anti-virus) Solutions
About Guest Introspection and Endpoint Protection Solutions
VMware's Guest Introspection Service enables vendors to deliver an introspection-based, endpoint protection (anti-virus) solution that uses the hypervisor to scan guest virtual machines from the outside, with only a thin agent on each guest virtual machine.
Version Compatibility
Note: The management APIs listed in this section are to be used only with partner endpoint protection solutions that were developed with EPSec Partner Program 3.0 or earlier (for vShield 5.5 or earlier). These partner solutions are also supported on NSX 6.0 and need the APIs listed below. These APIs should not be used with partner solutions developed specifically for NSX 6.0 or later, as these newer solutions automate the registration and deployment process by using the new features introduced in NSX. Using these with newer NSX 6.0 based solutions could result in loss of features.
Register a Solution
To register a third-party solution with Guest Introspection, clients can use four REST calls to do the following:
- Register the vendor.
- Register one or more solutions.
- Set the solution IP address and port (for all hosts).
- Activate registered solutions per host.
Note: Steps 1 through 3 need to be performed once per solution. Step 4 needs to be performed for each host.
Unregister a Solution
To unregister a solution, clients perform these steps in reverse:
- Deactivate solutions per host.
- Unset a solution’s IP address and port.
- Unregister solutions.
- Unregister the vendor.
Updating Registration Information
To update registration information for a vendor or solution, clients must:
- Unregister the vendor or solution.
- Reregister the vendor or solution.
Register a Vendor and Solution with Guest Introspection
Register the vendor of an endpoint protection solution. Specify the following parameters in the request.
| Name | Comments |
|---|---|
| vendorId | VMware-assigned ID for the vendor. |
| vendorTitle | Vendor-specified title. |
| vendorDescription | Vendor-specified description. |
Working With Registered Guest Introspection Vendors
Retrieve the list of all registered Guest Introspection vendors.
Working With Guest Introspection Vendors and Endpoint Protection Solutions
Register an endpoint protection solution. Specify the following parameters in the request.
| Name | Comments |
|---|---|
| solutionAltitude | VMware-assigned altitude for the solution. Altitude is a number that VMware assigns to uniquely identify the solution. The altitude describes the type of solution and the order in which the solution receives events relative to other solutions on the same host. |
| solutionTitle | Vendor-specified title for the solution. |
| solutionDescription | Vendor-specified description of the solution. |
Retrieve registration information for a Guest Introspection vendor.
Unregister a Guest Introspection vendor.
Information About Registered Endpoint Protection Solutions
Get registration information for all endpoint protection solutions for a Guest Introspection vendor.
Endpoint Protection Solution Registration Information
Get registration information for an endpoint protection solution.
Unregister an endpoint protection solution.
IP Address and Port For an Endpoint Protection Solution
To change the location of an endpoint protection solution:
- Deactivate all security virtual machines.
- Change the location.
- Reactivate all security virtual machines.
Set the IP address and port on the vNIC host for an endpoint protection solution.
Get the IP address and port on the vNIC host for an endpoint protection solution.
Unset the IP address and port for an endpoint protection solution.
Activate an Endpoint Protection Solution
You can activate a solution that has been registered and located.
Retrieve activation information for all activated security VMs on the specified host.
Activated Security Virtual Machines
Retrieve a list of activated security VMs for an endpoint protection solution.
Activate a Registered Endpoint Protection Solution
Activate an endpoint protection solution that has been registered and located. Specify the following parameter in the request body.
| Name | Comments |
|---|---|
| svmMoid | Managed object ID of the virtual machine of the activated endpoint protection solution. |
Working With Solution Activation Status
Retrieve the endpoint protection solution activation status, either true (activated) or false (not activated).
Deactivate an endpoint protection solution on a host.
Working With Guest Introspection SVM Health Thresholds
System events are generated when the Guest Introspection service VM memory and CPU usage reach the defined thresholds.
Retrieve Guest Introspection service VM CPU and memory usage thresholds.
Method history:
| Release | Modification |
|---|---|
| 6.3.5 | Method introduced. |
Update Guest Introspection service VM CPU and memory usage thresholds.
Valid values are 0-100. The default value is 75.
Method history:
| Release | Modification |
|---|---|
| 6.3.5 | Method introduced. |
dfw
Working With Distributed Firewall
Default Firewall Configuration
Retrieve the default firewall configuration.
The output of this method can be used to restore the firewall config back to default. For example, to replace the layer 2 or layer 3 default section, use the relevant default section from the GET
/api/4.0/firewall/globalroot-0/defaultconfig response body to create the request body of PUT
/api/4.0/firewall/globalroot-0/config/layer2sections|layer3sections/{sectionId}.
Method history:
| Release | Modification |
|---|---|
| 6.3.0 | Method introduced. |
Distributed Firewall Rules Configuration
The following table lists the elements that can be used in firewall rules.
| Element | Keyword for API | Used in |
|---|---|---|
| All Edges | ALL_EDGES | appliedTo |
| application | Application | service |
| application group | ApplicationGroup | service |
| cluster | compute resource | ClusterComputeResource appliedTo |
| datacenter | Datacenter | source/destination appliedTo |
| distributed firewall | DISTRIBUTED_FIREWALL | appliedTo |
| distributed virtual port group | DistributedVirtualPortgroup | source/destination appliedTo |
| Edge ID | Edge | appliedTo |
| global root | GlobalRoot | source/destination |
| host | HostSystem | appliedTo |
| IP set | IPSet | source/destination |
| IPv4 addresses | Ipv4Address | source/destination |
| IPv6 addresses | Ipv6Address | source/destination |
| logical switch | VirtualWire | source/destination appliedTo |
| MAC address set | MACSet | source/destination |
| network | Network | for legacy portgroups, network can be used in source or destination instead of appliedTo |
| profile | ALL_PROFILE_BINDINGS | |
| resource pool | ResourcePool | source/destination |
| security group | SecurityGroup | source/destination |
| virtual app | VirtualApp | source/destination |
| virtual machine | VirtualMachine | source/destination appliedTo |
| vNIC | Vnic | source/destination appliedTo |
Retrieve distributed firewall rule configuration.
If no query parameters are used, all rule configuration is retrieved. Use the query parameters to filter the rule configuration information.
Update the complete firewall configuration in all sections.
- Retrieve the configuration with
GET /api/4.0/firewall/globalroot-0/config. - Retrieve the Etag value from the response headers.
- Extract and modify the configuration from the response body as needed.
- Set the If-Match header to the Etag value, and submit the request.
Not all fields are required while sending the request. All the optional fields are safe to be ignored while sending the configuration to server. For example, if an IP set is referenced in the rule only IPSet and Type is needed in the Source/Destination objects and not Name and isValid tags.
When updating the firewall configuration:
- IDs for new objects (rule/section) should be removed or set to zero.
- If new entities (sections/rules) have been sent in the request, the response will contain the system-generated IDs, which are assigned to these new entities.
- appliedTo can be any valid firewall rule element.
- action can be ALLOW, BLOCK, or REJECT. REJECT sends reject message for unaccepted packets; RST packets are sent for TCP connections and ICMP unreachable code packets are sent for UDP, ICMP, and other IP connections
- source and destination can have an exclude flag. For example, if you add an exclude tag for 1.1.1.1 in the source parameter, the rule looks for traffic originating from all IPs other than 1.1.1.1.
Restores default configuration, which means one defaultLayer3 section with three default allow rules and one defaultLayer2Section with one default allow rule.
Working With Layer 3 Sections in Distributed Firewall
You can use sections in the firewall table to group logical rules based on AppliedTo or for a tenant use case. A firewall section is the smallest unit of configuration which can be updated independently. Section types are as follows:
- Layer3Section contains layer3 rules
- Layer2Section contains layer2 rules
- Layer3RedirectSection contains traffic redirect rules.
When Distributed Firewall is used with Service Composer, firewall sections created by Service Composer contain an additional attribute in the XML called managedBy. You should not modify Service Composer firewall sections using Distributed Firewall REST APIs.
Retrieve rules from the layer 3 section specified by section name.
Create a layer 3 distributed firewall section.
By default, the section is created at the top of the firewall table. You can specify a location for the section with the operation and anchorId query parameters.
Working With a Specific Layer 3 Distributed Firewall Section
Retrieve information about the specified layer 3 section.
Move the specified layer 3 section.
Use the action, operation, and optionally achorId query parameters to specify the destination for the section.
POST /api/4.0/firewall/globalroot-0/config/layer3sections/1007
?action=revise&operation=insert_before&anchorId=1006
If-Match: 1477989118875
<section id="1007" name="Web Section" generationNumber="1477989118875" timestamp="1477989118875" type="LAYER3">
...
</section>
Update the specified layer 3 section in distributed firewall.
- Retrieve the configuration for the specified section.
- Retrieve the Etag value from the response headers.
- Extract and modify the configuration from the response body as needed.
- Set the If-Match header to the Etag value, and submit the request.
Not all fields are required while sending the request. All the optional fields are safe to be ignored while sending the configuration to server. For example, if an IP set is referenced in the rule only IPSet and Type is needed in the Source/Destination objects and not Name and isValid tags.
When updating the firewall configuration:
- IDs for new objects (rule/section) should be removed or set to zero.
- If new entities (sections/rules) have been sent in the request, the response will contain the system-generated IDs, which are assigned to these new entities.
- appliedTo can be any valid firewall rule element.
- action can be ALLOW, BLOCK, or REJECT. REJECT sends reject message for unaccepted packets; RST packets are sent for TCP connections and ICMP unreachable code packets are sent for UDP, ICMP, and other IP connections
- source and destination can have an exclude flag. For example, if you add an exclude tag for 1.1.1.1 in the source parameter, the rule looks for traffic originating from all IPs other than 1.1.1.1.
When Distributed Firewall is used with Service Composer, firewall sections created by Service Composer contain an additional attribute in the XML called managedBy. You should not modify Service Composer firewall sections using Distributed Firewall REST APIs. If you do, you must synchronize firewall rules from Service Composer using the GET
/api/2.0/services/policy/serviceprovider/firewall API.
Delete the specified layer 3 distributed firewall section.
If the default layer 3 firewall section is selected, the request is rejected. See GET /api/4.0/firewall/globalroot-0/defaultconfig for information on resetting the default firewall section.
Method history:
| Release | Modification |
|---|---|
| 6.3.0 | Method updated. When deleting the default firewall rule section, the method previously removed all rules except for the default rule. The method now returns status 400 and the message Cannot delete default section <sectionId>. |
Working With Distributed Firewall Rules in a Layer 3 Section
Add rules to the specified layer 2 section in distributed firewall.
You add firewall rules at the global scope. You can then narrow down the scope (datacenter, cluster, distributed virtual port group, network, virtual machine, vNIC, or logical switch) at which you want to apply the rule. Firewall allows you to add multiple objects at the source and destination levels for each rule, which helps reduce the total number of firewall rules to be added. To add a identity based firewall rule, first create a security group based on Directory Group objects. Then create a firewall rule with the security group as the source or destination. Rules that direct traffic to a third part service are referred to as layer3 redirect rules, and are displayed in the layer3 redirect tab.
When Distributed Firewall is used with Service Composer, firewall rules created by Service Composer contain an additional attribute in the XML called managedBy.
Follow this procedure to add a rule:
- Retrieve the configuration for the specified section.
- Retrieve the Etag value from the response headers. Note: Each section contains its own Etag, generationNumber, and timestamp. When adding a new rule, you must use the Etag value of the firewall section to which you wish to add the rule.
- Extract and modify the configuration from the response body as needed.
- Set the If-Match header to the section Etag value, and submit the request.
Not all fields are required while sending the request. All the optional fields are safe to be ignored while sending the configuration to server. For example, if an IP set is referenced in the rule only IPSet and Type is needed in the Source/Destination objects and not Name and isValid tags.
When updating the firewall configuration:
- IDs for new rules should be removed or set to zero.
- If new rules have been sent in the request, the response will contain the system-generated IDs, which are assigned to these new entities.
- appliedTo can be any valid firewall rule element.
- action can be ALLOW, BLOCK, or REJECT. REJECT sends reject message for unaccepted packets; RST packets are sent for TCP connections and ICMP unreachable code packets are sent for UDP, ICMP, and other IP connections
- source and destination can have an exclude flag. For example, if you add an exclude tag for 1.1.1.1 in the source parameter, the rule looks for traffic originating from all IPs other than 1.1.1.1.
Working With a Specific Rule in a Specific Layer 3 Section
Retrieve information about the specified distributed firewall rule.
Update a distributed firewall rule in a layer 3 section.
- Retrieve the configuration for the section that contains the rule you want to modify.
- Retrieve the Etag value from the response headers. Note: This is the Etag value of the firewall section to which you want to add the rule. If you are keeping this rule in the same section, you must keep the same Etag number.
- Extract and modify the rule configuration from the response body as needed.
- Set the If-Match header to the section Etag value, and submit the request.
Not all fields are required while sending the request. All the optional fields are safe to be ignored while sending the configuration to server. For example, if an IP set is referenced in the rule only IPSet and Type is needed in the Source/Destination objects and not Name and isValid tags.
Delete the specified distributed firewall rule.
Working With Layer 2 Sections in Distributed Firewall
You can use sections in the firewall table to group logical rules based on AppliedTo or for a tenant use case. A firewall section is the smallest unit of configuration which can be updated independently. Section types are as follows:
- Layer3Section contains layer3 rules
- Layer2Section contains layer2 rules
- Layer3RedirectSection contains traffic redirect rules.
When Distributed Firewall is used with Service Composer, firewall sections created by Service Composer contain an additional attribute in the XML called managedBy. You should not modify Service Composer firewall sections using Distributed Firewall REST APIs.
Retrieve rules from the layer 2 section specified by section name.
Create a layer 2 distributed firewall section.
By default, the section is created at the top of the firewall table. You can specify a location for the section with the operation and anchorId query parameters.
Working With a Specific Layer 2 Distributed Firewall Section
Retrieve information about the specified layer 2 section.
Move the specified layer 2 section.
Use the action, operation, and optionally anchorId query parameters to specify the destination for the section.
POST /api/4.0/firewall/globalroot-0/config/layer2sections/1009
?action=revise&operation=insert_before&anchorId=1008
If-Match: 1478307787160
<section id="1009" name="Test Section" generationNumber="1478307787160" timestamp="1478307787160" type="LAYER2">
...
</section>
Update the specified layer 2 section in distributed firewall.
- Retrieve the configuration for the specified section.
- Retrieve the Etag value from the response headers.
- Extract and modify the configuration from the response body as needed.
- Set the If-Match header to the Etag value, and submit the request.
Not all fields are required while sending the request. All the optional fields are safe to be ignored while sending the configuration to server. For example, if an IP set is referenced in the rule only IPSet and Type is needed in the Source/Destination objects and not Name and isValid tags.
When updating the firewall configuration:
- IDs for new objects (rule/section) should be removed or set to zero.
- If new entities (sections/rules) have been sent in the request, the response will contain the system-generated IDs, which are assigned to these new entities.
- appliedTo can be any valid firewall rule element.
- action can be ALLOW, BLOCK, or REJECT. REJECT sends reject message for unaccepted packets; RST packets are sent for TCP connections and ICMP unreachable code packets are sent for UDP, ICMP, and other IP connections
- source and destination can have an exclude flag. For example, if you add an exclude tag for 1.1.1.1 in the source parameter, the rule looks for traffic originating from all IPs other than 1.1.1.1.
When Distributed Firewall is used with Service Composer, firewall sections created by Service Composer contain an additional attribute in the XML called managedBy. You should not modify Service Composer firewall sections using Distributed Firewall REST APIs. If you do, you must synchronize firewall rules from Service Composer using the GET
/api/2.0/services/policy/serviceprovider/firewall API.
Delete the specified layer 2 section and its contents.
If the default layer 2 firewall section is selected, the request is rejected. See GET /api/4.0/firewall/globalroot-0/defaultconfig for information on resetting the default firewall section.
Method history:
| Release | Modification |
|---|---|
| 6.3.0 | Method updated. When deleting the default firewall rule section, the method previously removed all rules except for the default rule. The method now returns status 400 and the message Cannot delete default section <sectionId>. |
Working With Distributed Firewall Rules in a Layer 2 Section
Add rules to the specified layer 2 section in distributed firewall.
You add firewall rules at the global scope. You can then narrow down the scope (datacenter, cluster, distributed virtual port group, network, virtual machine, vNIC, or logical switch) at which you want to apply the rule. Firewall allows you to add multiple objects at the source and destination levels for each rule, which helps reduce the total number of firewall rules to be added. To add a identity based firewall rule, first create a security group based on Directory Group objects. Then create a firewall rule with the security group as the source or destination. Rules that direct traffic to a third part service are referred to as layer3 redirect rules, and are displayed in the layer3 redirect tab.
When Distributed Firewall is used with Service Composer, firewall rules created by Service Composer contain an additional attribute in the XML called managedBy.
Follow this procedure to add a rule:
- Retrieve the configuration for the specified section.
- Retrieve the Etag value from the response headers. Note: Each section contains its own Etag, generationNumber, and timestamp. When adding a new rule, you must use the Etag value of the firewall section to which you wish to add the rule.
- Extract and modify the configuration from the response body as needed.
- Set the If-Match header to the section Etag value, and submit the request.
Not all fields are required while sending the request. All the optional fields are safe to be ignored while sending the configuration to server. For example, if an IP set is referenced in the rule only IPSet and Type is needed in the Source/Destination objects and not Name and isValid tags.
When updating the firewall configuration:
- IDs for new rules should be removed or set to zero.
- If new rules have been sent in the request, the response will contain the system-generated IDs, which are assigned to these new entities.
- appliedTo can be any valid firewall rule element.
- action can be ALLOW, BLOCK, or REJECT. REJECT sends reject message for unaccepted packets; RST packets are sent for TCP connections and ICMP unreachable code packets are sent for UDP, ICMP, and other IP connections
- source and destination can have an exclude flag. For example, if you add an exclude tag for 1.1.1.1 in the source parameter, the rule looks for traffic originating from all IPs other than 1.1.1.1.
Working With a Specific Rule in a Specific Layer 2 Section
Retrieve the configuration of the specified rule.
Update a distributed firewall rule in a layer 2 section.
- Retrieve the configuration for the section that contains the rule you want to modify.
- Retrieve the Etag value from the response headers. Note: This is the Etag value of the firewall section to which you want to add the rule. If you are keeping this rule in the same section, you must keep the same Etag number.
- Extract and modify the rule configuration from the response body as needed.
- Set the If-Match header to the section Etag value, and submit the request.
Not all fields are required while sending the request. All the optional fields are safe to be ignored while sending the configuration to server. For example, if an IP set is referenced in the rule only IPSet and Type is needed in the Source/Destination objects and not Name and isValid tags.
Delete the specified distributed firewall rule.
Layer 3 Redirect Sections and Rules
Add L3 redirect section
Layer 3 Redirect Section
Get L3 redirect section configuration
Modify layer 3 redirect section. You will need to get the Etag value out of the GET first. Then pass the modified version of the whole redirect section configuration in the GET body.
Delete specified L3 redirect section
Working With Layer 3 Redirect Rules for a Specific Section
Add L3 redirect rule
Working With a Specific Layer 3 Redirect Rule for a Specific Section
Get L3 redirect rule
Modify L3 redirect rule. You will need Etag value from the response header of GET call. Then, pass Etag value as the if-match header in PUT call
Delete specified L3 redirect rule
Service Insertion Profiles and Layer 3 Redirect Rules
Retrieve the Service Insertion profiles that can be applied to layer3 redirect rules.
Enable Distributed Firewall After Upgrade
After upgrading NSX Manager, controllers, and network virtualization components, check the status of distributed firewall. If it is ready to enable, you can enable distributed firewall.
| State | Description |
|---|---|
| backwardCompatible | This is the default state after an upgrade from vCloud Networking and Security to NSX, which means that vShield App is being used for protection instead of distributed firewall. |
| backwardCompatibleReadyForSwitch | Once the clusters are prepared with NSX binaries, this state is enabled. You can enable distributed firewall only after firewall is in this state. |
| switchingToForward | This is an intermediate state when you change firewall to distributed firewall. |
| forward | This is the default state for green field deployments or after you have switched from vShield App to distributed firewall. |
| switchFailed | This state is unlikely, but may be present if NSX Manager failed to switch to distributed firewall. |
Retrieve current state of firewall functioning after NSX upgrade.
Enable distributed firewall.
Working With Distributed Firewall Status
Retrieve status of last publish action for each cluster in the NSX environment.
The status output displays a generation number (generationNumber) for each rule set, which can be used to verify whether a change in rule sets has propagated to a host. In 6.2.4, a generation number for objects (generationNumberObjects) has been added to the status API. This allows you to verify whether a change in objects consumed in firewall rules has propagated to a host. Note that the object generation number may change frequently and will always be equal to or greater than the ruleset generation number.
Starting in NSX 6.2.4, clusters (and hosts inside the cluster) are no longer included in the firewall status output if distributed firewall is disabled at the cluster level, or if the cluster is not prepared (NSX VIBs are not installed). In earlier versions of NSX these clusters and hosts are included in the output. However, because they are not configured for firewall, after a firewall rule publish their status is inprogress.
Get firewall configuration status
Method history:
| Release | Modification |
|---|---|
| 6.2.4 | Method updated. Parameter generationNumberObjects added. Clusters not configured for firewall are excluded from the status output. |
Working With a Specific Layer 3 Section Status
Retrieve status of the last publish action for the specified layer 3 section.
Method history:
| Release | Modification |
|---|---|
| 6.2.4 | Method updated. Parameter generationNumberObjects added. Clusters not configured for firewall are excluded from the status output. |
Working With a Specific Layer 2 Section Status
Retrieve status of the last publish action for the specified layer 2 section.
Method history:
| Release | Modification |
|---|---|
| 6.2.4 | Method updated. Parameter generationNumberObjects added. Clusters not configured for firewall are excluded from the status output. |
Import and Export Firewall Configurations
Save a firewall configuration.
Displays the draft IDs of all saved configurations.
Working With a Specific Saved Firewall Configuration
Get a saved firewall configuration.
Update a saved firewall configuration.
Delete a configuration.
Working With Distributed Firewall Session Timers
You can configure session timers (session timeouts) for TCP, UDP, and ICMP. There is a default configuration, which applies to all VMs protected by Distributed Firewall. You can modify the session timers values of the default configuration, but not the appliedTo values.
You can add additional session timer configurations with different appliedTo configurations.
| Parameter | Description | Comments |
|---|---|---|
| appliedTo > value | The ID of the object on which to apply the timeout settings. | Required. For example VM ID vm-216. |
| appliedTo > type | The type of object on which to apply the timeout settings. | Required. Can be VirtualMachine or Vnic |
| generationNumber | Generation number for the configuration. | When updating session timers, you must ensure the latest generation number is included in the request body. |
| tcpFirstPacket | The timeout value for the connection after the first packet has been sent. This will be the initial timeout for the connection once a SYN has been sent and the flow is created. | Valid timer values: 10-4320000 seconds. Default is 120. |
| tcpOpen | The timeout value for the connection after a second packet has been transferred. | Valid timer values: 10-4320000 seconds. Default is 30. |
| tcpEstablished | The timeout value for the connection once the connection has become fully established. | Valid timer values: 120-4320000 seconds. Default is 43200. |
| tcpClosing | The timeout value for the connection after the first FIN has been sent. | Valid timer values: 10-4320000 seconds. Default is 120. |
| tcpFinWait | The timeout value for the connection after both FINs have been exchanged and the connection is closed. | Valid timer values: 10-4320000 seconds. Default is 45. |
| tcpClosed | The timeout value for the connection after one endpoint sends an RST. | Valid timer values: 10-4320000 seconds. Default is 20. |
| udpFirstPacket | The timeout value for the connection after the first packet. This will be the initial timeout for the new UDP flow. | Valid timer values: 10-4320000 seconds. Default is 60. |
| udpSingle | The timeout value for the connection if the source host sends more than one packet but the destination host has never sent one back. | Valid timer values: 10-4320000 seconds. Default is 30. |
| udpMultiple | The timeout value for the connection if both hosts have sent packets. | Valid timer values: 10-4320000 seconds. Default is 60. |
| icmpFirstPacket | The timeout value for the connection after the first packet. This will be the initial timeout for the new ICMP flow. | Valid timer values: 10-4320000 seconds. Default is 20. |
| icmpErrorReply | The timeout value for the connection after an ICMP error came back in response to an ICMP packet. | Valid timer values: 10-4320000 seconds. Default is 10. |
Retrieve Distributed Firewall session timer configuration.
Method history:
| Release | Modification |
|---|---|
| 6.3.0 | Method introduced. |
Create a Distributed Firewall session timer configuration.
Method history:
| Release | Modification |
|---|---|
| 6.3.0 | Method introduced. |
Working With a Specific Distributed Firewall Session Timer Configuration
Retrieve the specified Distributed Firewall session timer configuration.
Method history:
| Release | Modification |
|---|---|
| 6.3.0 | Method introduced. |
Update the specified Distributed Firewall session timer configuration.
Method history:
| Release | Modification |
|---|---|
| 6.3.0 | Method introduced. |
Delete the specified Distributed Firewall session timer configuration.
Method history:
| Release | Modification |
|---|---|
| 6.3.0 | Method introduced. |
Working With Distributed Firewall Thresholds
Configure memory, CPU, and connections per second (CPS) thresholds for distributed firewall.
The firewall module generates system events when the memory and CPU usage crosses these thresholds.
Retrieve threshold configuration for distributed firewall.
Update threshold configuration for distributed firewall.
Working With the Distributed Firewall Global Configuration
You can use the following parameters to improve firewall performance:
- layer3RuleOptimize and layer2RuleOptimize to turn on/off rule optimization.
- tcpStrictOption determines whether or not to drop an established TCP connection when the firewall does not see the initial three-way handshake. If set to true, the connection will be dropped.
- autoDraftDisabled improves performances when making large numbers of changes to firewall rules.
You can disable the auto draft feature by setting autoDraftDisabled to true. Distributed Firewall saves up to 100 configurations, including manually saved drafts (preserve parameter can be set to true or false) and auto saved drafts (preserve parameter is set to false). Once 100 configurations are saved, older drafts with the preserve parameter set to false will be deleted in order to save new configurations. You might want to disable the auto drafts feature before making large numbers of changes to the firewall rules, to improve performance, and to prevent previously saved drafts from being overwritten.
Note: The autoDraftDisabled parameter does not appear in a GET of the global configuration.
Retrieve performance configuration for distributed firewall.
Update the distributed firewall performance configuration.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. autoDraftDisabled parameter added. |
Synchronize Firewall
Synchronize hosts and clusters with the last good configuration in NSX Manager database.
Force sync host or cluster.
Enable Firewall
Enable or disable firewall components on a cluster.
Enable or disable firewall components on a cluster
Working With IPFIX
Configuring IPFIX exports specific flows directly from Distributed Firewall to a flow collector.
| Parameter | Description | Comments |
|---|---|---|
| ipfixEnabled | Enabled status of IPFIX | Valid values: true or false. |
| observationDomainId | Observation domain ID for IPFIX | Required. Must be greater than 0. |
| flowTimeout | Flow timeout | Required. Valid values: 1-60. |
| collector | IPFIX collector configuration | Can define multiple. |
| collector > ip | IPFIX collector IP address | |
| collector > port | IPFIX collector port | Valid values: 0-65535. Default is 4739. |
Retrieve IPFIX configuration.
Update IPFIX configuration.
Method history:
| Release | Modification |
|---|---|
| 6.3.5 | Default value for collector port changed from 0 to 4739. |
Deleting IPFIX configuration resets the configuration to default values.
spoofGuard
Working With SpoofGuard
After synchronizing with the vCenter Server, NSX Manager collects the IP addresses of all vCenter guest virtual machines. If a virtual machine has been compromised, the IP address can be spoofed and malicious transmissions can bypass firewall policies.
You create a SpoofGuard policy for specific networks that allows you to authorize the reported IP addresses and alter them if necessary to prevent spoofing. SpoofGuard inherently trusts the MAC addresses of virtual machines collected from the VMX files and vSphere SDK. Operating separately from Firewall rules, you can use SpoofGuard to block traffic determined to be spoofed.
Working With SpoofGuard Policies
You can create a SpoofGuard policy to specify the operation mode for specific networks. The system generated policy applies to port groups and logical switches not covered by existing SpoofGuard policies.
The operationMode for a SpoofGuard policy can be set to one of the following:
- TOFU - Automatically trust IP assignments on their first use
- MANUAL - Manually inspect and approve all IP assignments before first use
- DISABLE - Disable the SpoofGuard policy
Create a SpoofGuard policy to specify the operation mode for networks.
Note: you must include the trailing slash for this URI: /api/4.0/services/spoofguard/policies/.
Retrieve information about all SpoofGuard policies.
Note: you must include the trailing slash for this URI: /api/4.0/services/spoofguard/policies/.
Working With a Specific SpoofGuard Policy
Retrieve information about the specified SpoofGuard policy.
Modify the specified SpoofGuard policy.
Delete the specified SpoofGuard policy.
Perform SpoofGuard Operations on IP Addresses in a Specific Policy
Approve or publish IP addresses.
Retrieve IP addresses for the specified state.
flowMonitoring
Working With Flow Monitoring
Working With Flow Monitoring Statistics
Retrieve flow statistics for a datacenter, port group, VM, or vNIC.
Response values for flow statistics:
- blocked - indicates whether traffic is blocked:
- 0 - flow allowed
- 1 - flow blocked
- 2 - flow blocked by SpoofGuard
- protocol - protocol in flow:
- 0 - TCP
- 1 - UDP
- 2 - ICMP
- direction - direction of flow:
- 1 - from virtual machine
- 2 - to virtual machine
- controlDirection - control direction for dynamic TCP traffic:
- 0 - source -> destination
- 1 - destination -> source
Working With Flow Monitoring Meta-Data
Retrieve flow statistics meta-data.
This method retrieves the following information for each flow type:
- minimum start time
- maximum end time
- total flow count
Working With Flow Monitoring Configuration
Flow records generated on all hosts are sent to NSX Manager, which consumes the records and displays aggregated information. Hosts can generate large numbers of flow records. You can configure flow monitoring to exclude certain records from collection. The flow configuration applies to all hosts.
- collectFlows - if true, flow collection is enabled.
- ignoreBlockedFlows - if true, ignore blocked flows.
- ignoreLayer2Flows - if true, ignore layer 2 flows.
- sourceIPs - source IPs to exclude. For example: 10.112.3.14, 10.112.3.15-10.112.3.18,192.168.1.1/24.
- sourceContainer - source containers to exclude. Containers can contain VM, vNic, IP Set, MAC Set.
- destinationIPs - destination IPs to exclude.
- destinationContainer - destination containers to exclude. Containers can contain VM, vNic, IP Set, MAC Set.
- destinationPorts - destination ports to exclude.
- serviceContainers - service containers to exclude. Container can contain application or application group.
Flow exclusion happens at the host. The following flows are discarded by default:
- Broadcast IP (255.255.255.255)
- Local multicast group (224.0.0.0/24)
- Broadcast MAC address (FF:FF:FF:FF:FF:FF)
Retrieve flow monitoring configuration.
Update flow monitoring configuration.
Working With Flow Configuration for a Specific Context
Delete flow records for the specified context.
dfwExclusion
Exclude Virtual Machines from Firewall Protection
Working With the Exclusion List
Add a vm to the exclusion list.
Delete a vm from exclusion list.
nsxEdges
Working With NSX Edge
There are two types of NSX Edge: Edge services gateway and logical (distributed) router.
Edge Services Gateway
The services gateway gives you access to all NSX Edge services such as firewall, NAT, DHCP, VPN, load balancing, and high availability. You can install multiple Edge services gateway virtual appliances in a datacenter. Each Edge service gateway virtual appliance can have a total of ten uplink and internal network interfaces.
The internal interfaces connect to secured port groups and act as the gateway for all protected virtual machines in the port group. The subnet assigned to the internal interface can be a publicly routed IP space or a NATed/routed RFC 1918 private space. Firewall rules and other NSX Edge services are enforced on traffic between network interfaces.
Uplink interfaces of NSX Edge connect to uplink port groups that have access to a shared corporate network or a service that provides access layer networking. Multiple external IP addresses can be configured for load balancer, site-to-site VPN, and NAT services.
Logical (Distributed) Router
The logical router provides East-West distributed routing with tenant IP address space and data path isolation. Virtual machines or workloads that reside on the same host on different subnets can communicate with one another without having to traverse a traditional routing interface.
A logical router can have up to 9 uplink interfaces and up to 990 internal interfaces.
You can install NSX Edge as a services gateway or as a logical router.
The type parameter determines which type of NSX Edge is deployed: distributedRouter or gatewayServices. If no type is specified, the type is gatewayServices.
Other parameters for this method will differ depending on which type of NSX Edge you are deploying. See the examples and parameter tables for more information.
NSX Edge: Service Gateway
The NSX Edge installation API copies the NSX Edge OVF from the Edge Manager to the specified datastore and deploys an NSX Edge on the given datacenter. After the NSX Edge is installed, the virtual machine powers on and initializes according to the given network configuration. If an appliance is added, it is deployed with the specified configuration.
Installing an NSX Edge instance adds a virtual machine to the vCenter Server inventory, you must specify an IP address for the management interface, and you may name the NSX Edge instance.
The configuration you specify when you install an NSX Edge is stored in the database. If an appliance is added, the configuration is applied to it and it is deployed.
NOTE: Do not use hidden/system resource pool IDs as they are not supported on the UI.
Request Body to Create Edge Services Gateway
<edge>
<datacenterMoid>datacenter-2</datacenterMoid>
<name>org1-edge</name>
<description>Description for the edge gateway</description>
<tenant>org1</tenant>
<fqdn>org1edge1</fqdn>
<vseLogLevel>info</vseLogLevel>
<enableAesni>false</enableAesni>
<enableFips>true</enableFips>
<appliances>
<applianceSize>compact</applianceSize>
<enableCoreDump>true</enableCoreDump>
<appliance>
<resourcePoolId>resgroup-53</resourcePoolId>
<datastoreId>datastore-29</datastoreId>
<hostId>host-28</hostId>
<vmFolderId>group-v38</vmFolderId>
<customField>
<key>system.service.vmware.vsla.main01</key>
<value>string</value>
</customField>
<cpuReservation>
<limit>2399</limit>
<reservation>500</reservation>
<shares>500</shares>
</cpuReservation>
<memoryReservation>
<limit>5000</limit>
<reservation>500</reservation>
<shares>20480</shares>
</memoryReservation>
</appliance>
</appliances>
<vnics>
<vnic>
<index>0</index>
<name>internal0</name>
<type>internal</type>
<portgroupId>dvportgroup-114</portgroupId>
<addressGroups>
<addressGroup>
<primaryAddress>192.168.3.1</primaryAddress>
<secondaryAddresses>
<ipAddress>192.168.3.2</ipAddress>
<ipAddress>192.168.3.3</ipAddress>
</secondaryAddresses>
<subnetMask>255.255.255.0</subnetMask>
</addressGroup>
<addressGroup>
<primaryAddress>192.168.4.1</primaryAddress>
<secondaryAddresses>
<ipAddress>192.168.4.2</ipAddress>
<ipAddress>192.168.4.3</ipAddress>
</secondaryAddresses>
<subnetPrefixLength>24</subnetPrefixLength>
</addressGroup>
<addressGroup>
<primaryAddress>ffff::1</primaryAddress>
<secondaryAddresses>
<ipAddress>ffff::2</ipAddress>
</secondaryAddresses>
<subnetPrefixLength>64</subnetPrefixLength>
</addressGroup>
</addressGroups>
<macAddress>
<edgeVmHaIndex>0</edgeVmHaIndex>
<value>00:50:56:01:03:23</value>
</macAddress>
<fenceParameter>
<key>ethernet0.filter1.param1</key>
<value>1</value>
</fenceParameter>
<mtu>1500</mtu>
<enableProxyArp>false</enableProxyArp>
<enableSendRedirects>true</enableSendRedirects>
<isConnected>true</isConnected>
<inShapingPolicy>
<averageBandwidth>200000000</averageBandwidth>
<peakBandwidth>200000000</peakBandwidth>
<burstSize>0</burstSize>
<enabled>true</enabled>
<inherited>false</inherited>
</inShapingPolicy>
<outShapingPolicy>
<averageBandwidth>400000000</averageBandwidth>
<peakBandwidth>400000000</peakBandwidth>
<burstSize>0</burstSize>
<enabled>true</enabled>
<inherited>false</inherited>
</outShapingPolicy>
</vnic>
</vnics>
<cliSettings>
<userName>test</userName>
<password>test123!</password>
<remoteAccess>false</remoteAccess>
</cliSettings>
<autoConfiguration>
<enabled>true</enabled>
<rulePriority>high</rulePriority>
</autoConfiguration>
<dnsClient>
<primaryDns>10.117.0.1</primaryDns>
<secondaryDns>10.117.0.2</secondaryDns>
<domainName>vmware.com</domainName>
<domainName>foo.com</domainName>
</dnsClient>
<queryDaemon>
<enabled>true</enabled>
<port>5666</port>
</queryDaemon>
</edge>
NSX Edge: Logical (Distributed) Router
Before installing a logical router, you must prepare the hosts on the appropriate clusters.
The user specified configuration is stored in the database and Edge identifier is returned to the user. This identifier must be used for future configurations on the given Edge. If any appliance(s) are specified and at least one connected interface/vnic is specified, then the appliance(s) are deployed and configuration is applied to them.
It is not possible to set the
DHCP relay settings are not able to be used when creating a distributed logical router Edge and a subsequent API call is required to configure DHCP relay properties.
Request Body to Create Logical (Distributed) Router
<edge>
<datacenterMoid>datacenter-2</datacenterMoid>
<type>distributedRouter</type>
<appliances>
<appliance>
<resourcePoolId>resgroup-20</resourcePoolId>
<datastoreId>datastore-23</datastoreId>
</appliance>
</appliances>
<mgmtInterface>
<connectedToId>dvportgroup-38</connectedToId>
<addressGroups>
<addressGroup>
<primaryAddress>10.112.196.165</primaryAddress>
<subnetMask>255.255.252.0</subnetMask>
</addressGroup>
</addressGroups>
</mgmtInterface>
<interfaces>
<interface>
<type>uplink</type>
<mtu>1500</mtu>
<isConnected>true</isConnected>
<addressGroups>
<addressGroup>
<primaryAddress>192.168.10.1</primaryAddress>
<subnetMask>255.255.255.0</subnetMask>
</addressGroup>
</addressGroups>
<connectedToId>dvportgroup-39</connectedToId>
</interface>
<interface>
<type>internal</type>
<mtu>1500</mtu>
<isConnected>true</isConnected>
<addressGroups>
<addressGroup>
<primaryAddress>192.168.20.1</primaryAddress>
<subnetMask>255.255.255.0</subnetMask>
</addressGroup>
</addressGroups>
<connectedToId>dvportgroup-40</connectedToId>
</interface>
</interfaces>
</edge>
Request and Response Body Parameters for NSX Edge
General Request Body Parameters: Edge Services Gateway and Logical (Distributed) Router
| Parameter | Description | Comments |
|---|---|---|
| datacenterMoid | Specify vCenter Managed Object Identifier of data center on which edge has to be deployed | Required. |
| type | Specify which kind of NSX Edge to deploy. Choice of distributedRouter or gatewayServices. | Optional. Default is gatewayServices. |
| name | Specify a name for the new NSX Edge. | Optional. Default is NSX-<edgeId>. Used as a VM name on vCenter appended by -<haIndex>. |
| description | NSX Edge description. | Optional. |
| tenant | Specify the tenant. Used for syslog messages. | Optional. |
| fqdn | Fully Qualified Domain Name for the edge. | Optional. Default is NSX-<edgeId> Used to set hostname on the VM. Appended by -<haIndex> |
| vseLogLevel | Defines the log level for log messages captured in the log files. | Optional. Choice of: emergency, alert, critical, error, warning, notice, debug. Default is info. |
| enableAesni | Enable support for Advanced Encryption Standard New Instructions on the Edge. | Optional. True/False. Default is true. |
| enableCoreDump | Deploys a new NSX Edge for debug/core-dump purpose. | Optional. Default is false. Enabling core-dump will deploy an extra disk for core-dump files. |
Appliances Configuration: Edge Services Gateway and Logical (Distributed) Router
| Parameter | Description | Comments |
|---|---|---|
| applianceSize | Edge form factor, it determines the NSX Edge size and capability. | Required. Choice of: compact, large, quadlarge, xlarge. Default is compact. |
| deployAppliances | Determine whether to deploy appliances. | Default is true. |
| appliance | Appliance configuration details. | Required. Can configure a maximum of two appliances. Until one appliance is configured and NSX Edge VM is deployed successfully, none of the configured features will serve the network. |
| resourcePoolId | Details of resource pool on which to deploy NSX Edge. | Required. Can be resource pool ID, e.g. resgroup-15 or cluster ID, e.g. domain-c41. |
| datastoreId | Details of datastore on which to deploy NSX Edge. | Required. |
| hostId | ID of the host on which to deploy the NSX Edge. | Optional. |
| vmFolderId | The folder in which to save the NSX Edge. | Optional. |
| customField | Custom key-value attributes. | Optional. Use custom attributes to associate user-specific meta-information with VMs and managed hosts, stored on vCenter Server. |
| customField > key | Meta information Key. | Required if customField is specified. |
| customField > value | Meta information Value. | Required if customField is specified. |
| cpuReservation > limit | Maximum CPU capacity the NSX Edge can use, specified in MHz. | Optional. -1 (unlimited), any positive integer |
| cpuReservation > reservation | CPU capacity reserved for NSX Edge in MHz. | Optional. |
| cpuReservation > shares | Higher value implies NSX Edge has priority when accessing resources. | Optional. |
| memoryReservation > limit | Maximum memory the NSX Edge can use, specified in MB. | Optional. -1 (unlimited), any positive integer |
| memoryReservation > reservation | Memory capacity reserved for NSX Edge in MB. | Optional. |
| memoryReservation > shares | Higher value implies NSX Edge has priority when accessing resources. | Optional. |
| cliSettings > userName | User name. | Required. length 1-33. |
| cliSettings > password | Password. | Required. The password must be at least 12 characters long. Must contain at-least 1 uppercase, 1 lowercase, 1 special character and 1 digit. In addition, a character cannot be repeated 3 or more times consectively. |
| cliSettings > remoteAccess | Enables or disables remote access through SSH. | Required. Relevant firewall rules to allow traffic on port 22 must be opened by user/client |
| autoConfiguration > enabled | Enable/Disable status of autoConfiguration | Optional. True/False. Default is true. If autoConfiguration is enabled, firewall rules are automatically created to allow control traffic. Rules to allow data traffic are not created. For example, if you are using IPsec VPN, and autoConfiguration is true, firewall rules will automatically be configured to allow IKE traffic. However, you will need to add additional rules to allow the data traffic for the IPsec tunnel. If HA is enabled, firewall rules are always created, even if autoConfiguration is false, otherwise both HA appliances will become active. |
| autoConfiguration > rulePriority | Defines the priority of system-defined rules over user-defined rules. | Optional. High, Low. Default is high. |
| queryDaemon > enabled | Configure the communication between server load balancer and NSX Edge VM. | Default is false. |
| queryDaemon > port | Defines the port through which the communication happens. | Integer 1-65535. Default is 5666. |
DNS Client: Edge Services Gateway and Logical (Distributed) Router
| Parameter | Description | Comments |
|---|---|---|
| dnsClient | Configures the DNS settings of the Edge Services Gateway. | Optional. If the primary/secondary are specified and the DNS service is not specified, the primary/secondary will be used as the default of the DNS service. |
| primaryDns | Primary DNS IP | |
| secondaryDns | Secondary DNS IP | |
| domainName | Domain Name of Edge | |
| domainName | Secondary Domain Name of Edge |
vNIC Parameters: Edge Services Gateway Only
| Parameter | Description | Comments |
|---|---|---|
| vnic | Configure interface (vNic). | Required. Until one connected vNic is configured, none of the configured features will serve the network. |
| index | Index of vNic to be configured. Value varies from 0-9. 4094 sub-interfaces can be configured in trunk mode. | Required. |
| name | Name of the vNic. | Optional. System provides default names: vnic0...vnic9. |
| label | Label for the vNic. | Optional. System provides default labels: vNic_0...vNic_9. |
| type | Type of interface connected to vNic. | Optional. Choice of: Uplink, Internal, TRUNK. Default is Internal. TRUNK should be specified when sub-interfaces are configured. |
| portgroupId | Connect NSX Edge to the network through this port group. | Required. Choice of: portgroupId or virtualWireId. portgroupId needs to be defined if isConnected=true |
| addressGroup | Address Group assigned to vNic. | Required. More than one addressGroup/subnets can be assigned to the vNic. |
| primaryAddress | Primary Address of Edge Interface. | Required. IPv4 and IPv6 addresses are supported. |
| secondaryAddresses > ipAddress | IP assigned to interface. | Optional. One or more ipAddress parameters are allowed, to enable assigning multiple IP addresses to a vNic, for example, for load balancing, NAT, VPN. At least one is required if secondaryAddresses is specified. |
| subnetMask or subnetPrefixLength | Subnet mask or prefix value. | Required. Either subnetMask or subnetPrefixLength should be provided. When both are provided then subnetprefixLength is ignored. |
| macAddress | Option to manually specify the MAC address. | Optional. Managed by vCenter if not provided. |
| macAddress > edgeVmHaIndex | HA index of the Edge VM. | Required. 0 or 1. |
| macAddress > value | Value of the MAC address. | Optional. Ensure that MAC addresses provided are unique within the given layer 2 domain. |
| vnic > mtu | The maximum transmission value for the data packets. | Optional. Default is 1500. |
| enableProxyArp | Enables proxy ARP. Do not use this flag unless you want NSX Edge to proxy ARP for all configured subnets. | Optional. True/False. Default is false. |
| enableSendRedirects | Enables ICMP redirect. | Optional. True/False. Default is true. |
| isConnected | Sets if the interface is connected to the port group network. | Optional. True/False. Default is false. portgroupId needs to be defined if isConnected=true. |
| inShapingPolicy | Configure Incoming Traffic. | Optional. |
| outShapingPolicy | Configure Outgoing Traffic. | Optional. |
| averageBandwidth (inShapingPolicy or outShapingPolicy) | Sets average bandwidth for traffic. | Optional. |
| peakBandwidth (inShapingPolicy or outShapingPolicy) | Sets peak bandwidth for traffic. | Required. |
| burstSize (inShapingPolicy or outShapingPolicy) | Sets the burst size of the interface. | Required. |
| enabled (inShapingPolicy or outShapingPolicy) | Enable/disable status of this traffic policy. | Required. |
| inherited (inShapingPolicy or outShapingPolicy) | Determine whether properties should be inherited to the vNic from the port group. | Required. |
HA (Management) Interfaces and Interfaces Configuration: Logical (Distributed) Router Only
| Parameter | Description | Comments |
|---|---|---|
| mgmtInterface | High availability interface configuration. Interface index 0 is assigned. | Required. |
| interface | Interface configuration. 1-9 are reserved for uplinks, 10-999 are used for internal interfaces. | Optional. Can be added after logical router creation. |
| connectedToId (mgmtInterface or interface) | Managed Object ID of logical switch or port group. | For example, virtualwire-1 or dvportgroup-50. Logical router interfaces do not support legacy port groups. |
| name (mgmtInterface or interface) | Name assigned to interface. | Optional. |
| addressGroup (mgmtInterface or interface) | Address Group assigned to interface. | Required. Only one addressGroup can be configured on each logical router mgmtInterface or interface. |
| primaryAddress (mgmtInterface or interface) | Primary Address of interface. | Required. Secondary Addresses are not supported on logical routers. Address must be IPv4. |
| subnetMask or subnetPrefixLength (mgmtInterface or interface) | Subnet mask or prefix value. | Required. Either subnetMask or subnetPrefixLength should be provided. When both are provided then subnetprefixLength is ignored. |
| mtu (mgmtInterface or interface) | The maximum transmission value for the data packets. | Optional. Default is 1500. |
| type | Type of interface. | Required. Choice of uplink or internal. |
Retrieve a list of all NSX Edges in your inventory. You can use the query parameters to filter results.
Working With a Specific NSX Edge
Manage NSX Edge.
Retrieve information about the specified NSX Edge.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. haAdminState, configuredResourcePool, configuredDataStore, configuredHost, configuredVmFolder parameters added. |
Update the NSX Edge configuration.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. haAdminState parameter added. |
| 6.3.0 | Method updated. dnatMatchSourceAddress, snatMatchDestinationAddress, dnatMatchSourcePort, snatMatchDestinationPort parameters added. protocol, originalPort, and translatedPort now supported in SNAT rules. |
Delete specified NSX Edge configuration. Associated appliances are also deleted.
Working With Core Dumps
Enabling core-dump feature results in deployment of built-in extra disk to save core-dump files. Disabling detaches the disk.
Modify core dump setting.
Working With NSX Edge Summary
Retrieve details about the specified NSX Edge.
Method history:
| Release | Modification |
|---|---|
| 6.3.0 | Method updated. enableFips parameter added to appliancesSummary. |
Working With NSX Edge Status
Retrieve the status of the specified Edge.
The edgeStatus has the following possible states:
- GREEN: Health checks are successful, status is good.
- YELLOW: Intermittent health check failure. If health check fails for five consecutive times for all appliances, status will turn RED.
- GREY: unknown status.
- RED: None of the appliances for this NSX Edge are in a serving state.
Working With NSX Edge Tech Support Logs
Retrieve the tech support logs for the specified NSX Edge.
The response status for the tech support logs API request is 303 See
Other, and the Location header contains the file location of the tech support logs on the NSX Manager web server.
If your REST client is configured to not follow redirects, see the Location header to find the location of the tech support logs on the NSX Manager web server. You can retrieve the logs from https://<nsxmgr-address>/<location>.
Example in curl:
$ curl -k -i -s -H 'Authorization: Basic YWRtaW46Vk13YXJlMSE=' -H "Content-Type: application/xml" -H "Accept: application/xml" -X GET https://192.168.110.42/api/4.0/edges/edge-4/techsupportlogs
HTTP/1.1 303 See Other
Cache-Control: private
Expires: Thu, 01 Jan 1970 00:00:00 GMT+00:00
Server:
Cache-Control: no-cache
Location: /tech_support_logs/vse/NSX_Edge_Support_edge-4_050217_155853GMT+00:00.log.gz
Date: Tue, 02 May 2017 15:59:02 GMT
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Frame-Options: SAMEORIGIN
Content-Length: 0
In this example, the log location is https://192.168.110.42/tech_support_logs/vse/NSX_Edge_Support_edge-4_050217_155853GMT+00:00.log.gz
If your REST client is configured to follow redirects, the request retrieves the tech support log file from the file location in the Location field. Consult your REST client documentation for information on saving binary file responses.
Example in curl:
curl -k -L -s -H 'Authorization: Basic YWRtaW46ZGXXXXXXXX==' -H "Content-Type: application/xml" -H "Accept: application/xml" -X GET https://192.168.110.42/api/4.0/edges/edge-4/techsupportlogs > NSX_Edge_Support_edge-4.log.gz
Working With NSX Edge CLI Settings
Modify CLI credentials and enable/disable SSH for Edge.
Working With NSX Edge System Control Configuration
Update the NSX Edge system control (sysctl) configuration.
Available System Control Properties
| Description | Properties |
|---|---|
| Determine the IP address to be sent in ARP | sysctl.net.ipv4.conf.all.arp_announce sysctl.net.ipv4.conf.default.arp_announce |
| TCP timeout values for conntrack to fine tune NAT performance | sysctl.net.netfilter.nf_conntrack_tcp_timeout_fin_wait sysctl.net.netfilter.nf_conntrack_tcp_timeout_close_wait sysctl.net.netfilter.nf_conntrack_tcp_timeout_max_retrans sysctl.net.netfilter.nf_conntrack_tcp_timeout_unacknowledged sysctl.net.netfilter.nf_conntrack_tcp_max_retrans |
| Disable uRPF check | sysctl.net.ipv4.conf.all.rp_filter sysctl.net.ipv4.conf.default.rp_filter sysctl.net.ipv4.conf.vNic_[0-4094].rp_filter |
| Modify ARP limits in cache | sysctl.net.ipv4.neigh.default.gc_thresh1 sysctl.net.ipv6.neigh.default.gc_thresh1 sysctl.net.ipv4.neigh.default.gc_thresh2 sysctl.net.ipv6.neigh.default.gc_thresh2 sysctl.net.ipv4.neigh.default.gc_thresh3 sysctl.net.ipv6.neigh.default.gc_thresh3 |
| TIME_WAIT socket connections configuration | sysctl.net.ipv4.tcp_tw_reuse sysctl.net.ipv4.tcp_tw_recycle |
| Load balancer tuning parameters | lb.global.tune.bufsize lb.global.tune.maxrewrite sysctl.net.ipv4.vs.expire_nodest_conn sysctl.net.ipv4.tcp_max_orphans sysctl.net.ipv4.tcp_mem |
| Bridge tuning parameters | sysctl.net.bridge.bridge-nf-call-iptables sysctl.net.bridge.bridge-nf-call-ip6tables |
Method history:
| Release | Modification |
|---|---|
| 6.3.2 | Properties added: sysctl.net.ipv4.tcp_max_orphans, sysctl.net.ipv4.tcp_mem |
| 6.3.7 | Properties added: sysctl.net.bridge.bridge-nf-call-iptables, sysctl.net.bridge.bridge-nf-call-ip6tables |
Retrieve all NSX Edge system control configuration.
If no system control parameters are configured, the response is empty.
Delete all NSX Edge system control configuration.
Deleting the system control configuration requires a reboot of the NSX Edge appliance.
Working With NSX Edge Firewall Configuration
Configures firewall for an Edge and stores the specified configuration in database. If any appliances are associated with this Edge, applies the configuration to them. While using this API, you should send the globalConfig, defaultPolicy and the rules. If either of them are not sent, the previous config if any on those fields will be removed and will be changed to the system defaults.
ruleId uniquely identifies a rule and should be specified only for rules that are being updated. If ruleTag is specified, the rules on Edge are configured using this user input. Otherwise, Edge is configured using ruleIds generated by NSX Manager.
| Parameter | Comments |
|---|---|
| tcpPickOngoingConnections | Boolean, optional, default: false. |
| tcpAllowOutOfWindowPackets | Boolean, optional, default: false. |
| tcpSendResetForClosedVsePorts | Boolean, optional, default: true. |
| dropInvalidTraffic | Boolean, optional, default: true. |
| logInvalidTraffic | Boolean, optional, default: false. |
| tcpTimeoutOpen | Integer, optional, default: 30. |
| tcpTimeoutEstablished | Integer, optional, default: 21600. |
| tcpTimeoutClose | Integer, optional, default: 30. |
| udpTimeout | Integer, optional, default: 60. |
| icmpTimeout | Integer, optional, default: 10. |
| icmp6Timeout | Integer, optional, default: 10. |
| ipGenericTimeout | Integer, optional, default: 120. |
| enableSynFloodProtection | Protect against SYN flood attacks by detecting bogus TCP connections and terminating them without consuming firewall state tracking resources. Boolean, optional, default: false. |
| logIcmpErrors | Boolean, optional, default false. |
| dropIcmpReplays | Boolean, optional, default false. |
| defaultPolicy | Optional. Default is deny. |
| action | String, values: accept, deny. |
| loggingEnabled | Boolean, optional, default: false. |
| firewallRules | Optional. |
| action | String. Valid values: accept, deny. |
| source | Optional. Default is any. |
| destination | Optional. Default is any. |
| exclude (source or destination) | Boolean. Exclude the specified source or destination. |
| ipAddress (source or destination) | List of string. Can specify single IP address, range of IP address, or in CIDR format. Can define multiple. |
| groupingObjectId (source or destination) | List of string, Id of cluster, datacenter, distributedPortGroup, legacyPortGroup, VirtualMachine, vApp, resourcePool, logicalSwitch, IPSet, securityGroup. Can defined multiple. |
| vnicGroupId (source or destination) | List of string. Possible values are vnic-index-[1-9], vse, external or internal. Can define multiple. |
| application | optional. When absent its treated as any. |
| applicationId | List of string. Id of service or serviceGroup groupingObject. |
| service | List. |
| protocol | String. |
| port | List of string. |
| sourcePort | List of string. |
| icmpType | String. |
| name | String. |
| description | String. |
| enabled | Boolean, optional. Default true. |
| loggingEnabled | Boolean, optional. Default false. |
| matchTranslated | Boolean. |
| direction | String, optional. Possible values in or out. When absent its treated as any. |
| ruleTag | Long, optional. This can be used to specify user controlled ruleId. If not specified, NSX Manager will generate ruleId. Valid values: 1-65536. |
Retrieve the NSX Edge firewall configuration.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. enableSynFloodProtection parameter added. |
| 6.3.0 | Method updated. logIcmpErrors and dropIcmpReplays parameters added. |
Configure NSX Edge firewall.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. enableSynFloodProtection parameter added. Default value of tcpTimeoutEstablished increased from 3600 to 21600 seconds (6 hours). |
| 6.3.0 | Method updated. logIcmpErrors and dropIcmpReplays parameters added. |
Delete NSX Edge firewall configuration.
Working With Firewall Rules
Add one or more rules. You can add a rule above a specific rule using the query parameter, indicating the desired ruleID.
Working With a Specific Firewall Rule
Retrieve specific rule.
Modify a specific firewall rule.
Delete firewall rule
Working With the NSX Edge Global Firewall Configuration
Retrieve the firewall default policy for an Edge.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. enableSynFloodProtection parameter added. |
| 6.3.0 | Method updated. logIcmpErrors and dropIcmpReplays parameters added. |
Configure firewall global config for an Edge.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. enableSynFloodProtection parameter added. Default value of tcpTimeoutEstablished increased from 3600 to 21600 seconds (6 hours). |
| 6.3.0 | Method updated. logIcmpErrors and dropIcmpReplays parameters added. |
Working With the Default Firewall Policy for an Edge
Retrieve default firewall policy
Configure default firewall policy
Working With Statistics for a Specific Firewall Rule
Retrieve stats for firewall rule.
Working With NAT Configuration
NSX Edge provides network address translation (NAT) service to protect the IP addresses of internal (private) networks from the public network.
You can configure NAT rules to provide access to services running on privately addressed virtual machines. There are two types of NAT rules that can be configured: SNAT and DNAT.
For the data path to work, you need to add firewall rules to allow the required traffic for IP addresses and port per the NAT rules.
NAT Parameter Table
| Parameter | Description | Other information |
|---|---|---|
| enabled | Enable rule. | Boolean. Optional. Default is true. |
| loggingEnabled | Enable logging. | Boolean. Optional. Default is false. |
| ruleTag | Rule tag. | This can be used to specify user-controlled ruleId. If not specified, NSX Manager will generate ruleId. Optional. Must be between 65537-131072. |
| ruleId | Identifier for the rule. | Read-only. Long. |
| ruleType | Rule type. | Read-only. Values: user, internal_high. |
| action | Type of NAT. | Valid values: snat or dnat. |
| vnic | Interface on which the translating is applied. | String. Optional. |
| originalAddress | Original address or address range. This is the source address for SNAT rules, and the destination address for DNAT rules. | String. Specify any, an IP address (e.g. 192.168.10.10), an IP range (e.g. 192.168.10.10-192.168.10.19), or a subnet in CIDR notation (e.g. 192.168.10.1/24). Default is any. |
| translatedAddress | Translated address or address range. | String. Specify any, an IP address (e.g. 192.168.10.10), an IP range (e.g. 192.168.10.10-192.168.10.19), or a subnet in CIDR notation (e.g. 192.168.10.1/24). Default is any. |
| dnatMatchSourceAddress | Source address to match in DNAT rules. | String. Specify any, an IP address (e.g. 192.168.10.10), an IP range (e.g. 192.168.10.10-192.168.10.19), or a subnet in CIDR notation (e.g. 192.168.10.1/24). Default is any. Not valid for SNAT rules. |
| snatMatchDestinationAddress | Destination address to match in SNAT rules. | String. Specify any, an IP address (e.g. 192.168.10.10), an IP range (e.g. 192.168.10.10-192.168.10.19), or a subnet in CIDR notation (e.g. 192.168.10.1/24). Default is any. Not valid for DNAT rules. |
| protocol | Protocol. | String. Optional. Default is any. |
| icmpType | ICMP type. | String. Only supported when protocol is icmp. Default is any. |
| originalPort | Original port. This is the source port for SNAT rules, and the destination port for DNAT rules. | String. Optional. Specify any, a port (e.g. 1234) or port range (1234-1239). Default is any. |
| translatedPort | Translated port. | String. Optional. Specify any, a port (e.g. 1234) or port range (1234-1239). Default is any. |
| dnatMatchSourcePort | Source port in DNAT rules. | String. Optional. Specify any, a port (e.g. 1234) or port range (1234-1239). Default is any. Not valid for SNAT rules. |
| snatMatchDestinationPort | Destination port in SNAT rules. | String. Optional. Specify any, a port (e.g. 1234) or port range (1234-1239). Default is any. Not valid for DNAT rules. |
Configure SNAT and DNAT rules for an Edge.
If you use this method to add new NAT rules, you must include all existing rules in the request body. Any rules that are omitted will be deleted.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. vnic parameter is now optional. The originalAddress for DNAT rules, and the translatedAddress for SNAT rules is no longer required to be a IP configured on one of the NSX Edge vNics. |
| 6.3.0 | Method updated. dnatMatchSourceAddress, snatMatchDestinationAddress, dnatMatchSourcePort, snatMatchDestinationPort parameters added. protocol, originalPort, and translatedPort now supported in SNAT rules. |
Retrieve SNAT and DNAT rules for the specified NSX Edge.
Method history:
| Release | Modification |
|---|---|
| 6.3.0 | Method updated. dnatMatchSourceAddress, snatMatchDestinationAddress, dnatMatchSourcePort, snatMatchDestinationPort parameters added. protocol, originalPort, and translatedPort now supported in SNAT rules. |
Delete all NAT rules for the specified NSX Edge. The auto plumbed rules continue to exist.
Working With NAT Rules
Add a NAT rule above a specific rule in the NAT rules table (using aboveRuleId query parameter) or append NAT rules to the bottom.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. vnic parameter is now optional. The originalAddress for DNAT rules, and the translatedAddress for SNAT rules is no longer required to be a IP configured on one of the NSX Edge vNics. |
| 6.3.0 | Method updated. dnatMatchSourceAddress, snatMatchDestinationAddress, dnatMatchSourcePort, snatMatchDestinationPort parameters added. protocol, originalPort, and translatedPort now supported in SNAT rules. |
Working With a Specific NAT Rule
Update the specified NAT rule.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. vnic parameter is now optional. The originalAddress for DNAT rules, and the translatedAddress for SNAT rules is no longer required to be a IP configured on one of the NSX Edge vNics. |
| 6.3.0 | Method updated. dnatMatchSourceAddress, snatMatchDestinationAddress, dnatMatchSourcePort, snatMatchDestinationPort parameters added. protocol, originalPort, and translatedPort now supported in SNAT rules. |
Delete the specified NAT rule.
Working With the NSX Edge Routing Configuration
You can specify static and dynamic routing for each NSX Edge.
Dynamic routing provides the necessary forwarding information between layer 2 broadcast domains, thereby allowing you to decrease layer 2 broadcast domains and improve network efficiency and scale. NSX extends this intelligence to where the workloads reside for doing East-West routing. This allows more direct virtual machine to virtual machine communication without the costly or timely need to extend hops. At the same time, NSX also provides North-South connectivity, thereby enabling tenants to access public networks.
Global Routing Configuration
| Parameter | Description | Comments |
|---|---|---|
| routerId | The first uplink IP address of the NSX Edge that pushes routes to the kernel for dynamic routing | Optional. RouterId is set only when configuring the dynamic routing protocols OSPF and BGP. |
| ecmp | Enables equal-cost multi-path routing (ECMP) | Optional. Boolean. By default, ecmp is set to false. |
| logging | Logging configuration. | Optional. |
| logging > enable | Enable/disable status of logging. | Optional. Default is false. |
| logging > logLevel | Sets the log level. | Default is info. Valid values: emergency, alert, critical, error, warning, notice, info, debug. |
| ipPrefix | Details for one IP prefix. | Optional. Required only if you define redistribution rules in dynamic routing protocols like ospf, bgp. |
| ipPrefix > name | The name of the IP prefix. | All defined IP prefixes must have unique names. |
| ipPrefix > ipAddress | IP addresses for the IP prefix. | Optional. String. |
Default Route Configuration
| Parameter | Description | Comments |
|---|---|---|
| description | A description for the default route. | |
| type | Specifies whether the static route was created by the system as an auto-generated route or the default route (internal); or whether it is a local (user) route. | |
| mtu | The maximum transmission value for the data packets | Default is 1500. The MTU value cannot be higher than the MTU value set on the NSX Edge interface. By default, mtu is the MTU value of the interface on which the route is configured. |
| vnic | Interface on which the default route is added. | |
| gatewayAddress | Default gateway IP used for routing. | |
| adminDistance | Admin distance. Used to determine which routing protocol to use if two protocols provide route information for the same destination. | Optional. Default value is 1. |
Static Route Configuration
| Parameter | Description | Comments |
|---|---|---|
| vnic | Interface on which the route is added. | |
| description | A description for the static route. | |
| mtu | The maximum transmission value for the data packet. | Default is 1500. By default, mtu is the MTU value of the interface on which the route is configured. |
| network | The network in CIDR notation. | |
| nextHop | Next hop IP address. | The router must be able to directly reach the next hop. When ECMP is enabled, multiple next hops can be displayed. |
| adminDistance | Admin distance. Used to determine which routing protocol to use if two protocols provide route information for the same destination. | Optional. Default value is 1. |
| type | Specifies whether the static route was created by the system as an auto-generated route or the default route (internal); or whether it is a local (user) route. |
OSPF Configuration
| Parameter | Description | Comments |
|---|---|---|
| enabled | OSPF enabled status. | When not specified, it will be treated as false, When false, it will delete the existing config. |
| gracefulRestart | For packet forwarding to be uninterrupted during restart of services. | Optional. |
| defaultOriginate | Allows the Edge Services Gateway to advertise itself as a default gateway to its peers. | Optional. Default is false. Not allowed on a logical distributed router. |
| forwardingAddress | The IP address of one of the uplink interfaces. | Logical (distributed) router only. |
| protocolAddress | An IP address on the same subnet as the forwarding address. | Logical (distributed) router only. |
| areaId | The area ID. The NSX Edge supports an area ID in the form of a decimal number. Valid values are 0-4294967295. | Required. The value for areaId must be a unique number. |
| translateType7ToType5 | Configure whether this NSX Edge should be used for translating Type 7 to Type 5 LSAs for this OSPF area. If not set, the router with highest router ID is used for translating. | Valid values: true or false. Optional, default is false. Only configurable for OSFP areas of type NSSA. |
| type | Gives whether the type is normal or nssa. | Optional. Default type is normal. NSSAs (the not-so-stubby areas feature described in RFC 3101) prevents the flooding of AS-external link-state advertisements (LSAs). They rely on default routing to external destinations. Therefore, NSSAs are placed at the edge of an OSPF routing domain. NSSA can import external routes into the OSPF routing domain, thereby providing transit service to small routing domains that are not part of the OSPF routing domain. |
| authentication > type | Authentication type. | Choice of none, password, or md5. If authentication information isn't provided, type is none. Type password: a password is included in the transmitted packet. Type md5: an MD5 checksum is included in the transmitted packet. |
| authentication > value | The password or MD5 key, respectively | |
| vnic | The interface that is mapped to OSPF Area | Required. The interface specifies the external network that both NSX Edges are connected to. |
| areaId | An area ID. Can be in the form of an IP address or decimal number. | Required. |
| helloInterval | The default interval between hello packets that are sent on the interface | Optional. By default, set to 10 seconds with valid values 1-255. |
| deadInterval | The default interval during which at least one hello packet must be received from a neighbor before the router declares that neighbor down. | Optional. By default, set to 40 seconds. Valid values are 1-65535. |
| priority | The default priority of the interface. The interface with the highest priority is the designated router. | Optional. By default, set to 128 with valid values 0-255. |
| cost | The default overhead required to send packets across that interface | Optional. Integer. The cost of an interface is inversely proportional to the bandwidth of that interface. The larger the bandwidth, the smaller the cost. Valid values are 1-65535. |
| mtuIgnore | Ignore interface MTU setting | true or false. |
BGP Configuration
| Parameter | Description | Comments |
|---|---|---|
| enabled | BGP routing enable/disable status. | Optional. By default, enabled is set to false. |
| gracefulRestart | For packet forwarding to be uninterrupted during restart of services. | Optional. |
| defaultOriginate | Allows the Edge Services Gateway to advertise itself as a default gateway to its peers. | Optional. Default is false. Not allowed on a logical distributed router. |
| localAS | The 2 byte local Autonomous System number that is assigned to the NSX Edge. The path of autonomous systems that a route traverses is used as one metric when selecting the best path to a destination. | Integer. A value (a globally unique number between 1-65535) for the local AS. This local AS is advertised when the NSX Edge peers with routers in other autonomous systems. Either localAS or localASNumber is required. |
| localASNumber | The 2 or 4 byte local Autonomous System number that is assigned to the NSX Edge. The path of autonomous systems that a route traverses is used as one metric when selecting the best path to a destination. | Integer. A value (a globally unique number between 1-4294967295) for the Local AS. This local AS is advertised when the NSX Edge peers with routers in other autonomous systems. Can be in plain or dotted format (e.g. 2 byte: 65001 or 0.65001, 4 byte: 65545 or 1.9). Either localAS or localASNumber is required. |
| bgpNeighbour > ipAddress | The IP address of the on-premises border device. | Required. String. IPv4 only. IPv6 is not supported. Should not be the same as any of the NSX Edge interfaces's IPs, forwardingAddress, protocolAddress. |
| bgpNeighbour > forwardingAddress | The IP address of one of the uplink interfaces. | Logical (distributed) router only. |
| bgpNeighbour > protocolAddress | An IP address on the same subnet as the forwarding address. | Logical (distributed) router only. |
| bgpNeighbour > remoteAS | The 2 byte remote Autonomous System number that is assigned to the the border device you are creating the connection for. | Integer. A value (a globally unique number between 1-65535) for the remote AS. Either remoteAS or remoteASNumber is required. |
| bgpNeighbour > remoteASNumber | The 2 or 4 byte remote Autonomous System number that is assigned to the border device you are creating the connection for. | Integer. A value (a globally unique number between 1-4294967295) for the remote AS. Can be in plain or dotted format (e.g. 2 byte: 65001 or 0.65001, 4 byte: 65545 or 1.9). Either remoteAS or remoteASNumber is required. |
| bgpNeighbour > removePrivateAS | Determines whether to remove private AS number while redistributing routes. | Boolean. You can set to true only when remote and local AS are different. |
| bgpNeighbour > weight | Weight for the neighbor connection | Optional. Integer. By default, weight is set to 60. |
| bgpNeighbour > holdDownTimer | Interval for the hold down timer | Optional. Integer. The NSX Edge uses the standard, default values for the keep alive timer (60 seconds) and the hold down timer. The default value for the hold down timer is 3x keepalive or 180 seconds. Once peering between two neighbors is achieved, the NSX Edge starts a hold down timer. Every keep alive message it receives from the neighbor resets the hold down timer to 0. When the NSX Edge fails to receive three consecutive keep alive messages, so that the hold down timer reaches 180 seconds, the NSX Edge considers the neighbor down and deletes the routes from this neighbor. |
| bgpNeighbour > keepAliveTimer | Interval for the keep alive timer. | Optional. Integer. Default is 60. Valid values are 1-65534. |
| bgpNeighbour > password | The authentication password. | Optional. String. Each segment sent on the connection between the neighbors is verified. MD5 authentication must be configured with the same password on both BGP neighbors, otherwise, the connection between them will not be made. |
| bgpFilter > direction | Indicate whether you are filtering traffic to or from the neighbor | Optional. Choice of in or out. |
| bgpFilter > action | Permit or deny traffic. | Optional. Choice of permit or deny. |
| bgpFilter > network | The network that you want to filter to or from the neighbor. | CIDR format. IPv4 only. IPv6 is not supported. |
| bgpFilter > ipPrefixGe | The IP prefixes that are to be filtered. Filter prefixes greater than or equal to this value. | Optional. Integer. Specify valid IPv4 prefixes. |
| bgpFilter > ipPrefixLe | The IP prefixes that are to be filtered. Filter prefixes less than or equal to this value. | Optional. Integer. Specify valid IPv4 prefixes. |
Note: New parameters localASNumber and remoteASNumber have been added in NSX 6.3.0 to allow configuration of 4 byte AS numbers. The previous parameters, localAS and remoteAS are still valid.
When you configure BGP, you must provide a local AS number parameter (localAS or localASNumber) and a remote AS number parameter (remoteAS or remoteASNumber). If you provide both forms of either local or remote AS number (for example, localAS and localASNumber), the values must be the same.
You can use any combination of remote and local AS parameters, as long as the values are valid. For example, localAS of 65501 and remoteASNumber of 70000.
If you configure a 2 byte number, both forms of the AS number parameters are returned with a GET request (for example, localAS and localASNumber). If you configure a 4 byte number, only the 4 byte parameter is returned (localASNumber).
If both parameters are present (for example localAS and localASNumber), and you update one parameter (localAS) subsequent GET requests will show both parameters updated.
Route Redistribution Configuration for OSPF or BGP
| Parameter | Description | Comments |
|---|---|---|
| enabled | Enabled status of route redistribution for the parent protocol (OSFP or BGP). | Optional. Default is false. |
| rule | Route redistribution rule. | |
| id | The ID for the rule. | Required. Number. |
| prefixName | The name for the IP prefix to add for route redistribution | Optional. String. Default is any. prefixName is set using routingGlobalConfig > ipPrefixes. By default, the value of prefixName is set to any. |
| from > ospf | Whether OSPF is a learner protocol (it learns routes from other protocols). | Optional. By default set to false for ospf. |
| from > bgp | Whether BGP is a learner protocol (it learns routes from other protocols). | Optional. By default set to false for bgp. |
| from > static | Whether routes can be learned from static networks. | Optional. By default set to false for static. |
| from > connected | Whether routes can be learned from connected networks. | Optional. By default set to false for connected. |
| action | Whether to permit or deny redistribution from the selected types of networks. | Required. Choice of deny or permit. |
Retrieve routes.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. isis configuration section removed. |
| 6.3.0 | Method updated. Parameter defaultOriginate removed for logical router NSX Edges. Parameter translateType7ToType5 added to OSPF section. Parameters localASNumber and remoteASNumber added to BGP section. |
| 6.3.6 | Method updated. Parameter removePrivateAS added. |
Configure NSX Edge global routing configuration, static routing, and dynamic routing (OSPF and BGP).
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. isis configuration section removed. |
| 6.3.0 | Method updated. Parameter defaultOriginate removed for logical router NSX Edges. Parameter translateType7ToType5 added to OSPF section. Parameters localASNumber and remoteASNumber added to BGP section. |
| 6.3.6 | Method updated. Parameter removePrivateAS added. |
Delete the routing config stored in the NSX Manager database and the default routes from the specified NSX Edge appliance.
Working With the NSX Edge Global Configuration
Configure global route.
Retrieve routing info from NSX Manager database (default route settings, static route configurations).
Working With Static and Default Routes
Read static and default routes.
Configure static and default routes.
Delete both static and default routing config stored in the NSX Manager database.
Working With OSPF Routing for NSX Edge
NSX Edge supports OSPF, an interior gateway protocol that routes IP packets only within a single routing domain. It gathers link state information from available routers and constructs a topology map of the network. The topology determines the routing table presented to the Internet Layer, which makes routing decisions based on the destination IP address found in IP packets.
OSPF routing policies provide a dynamic process of traffic load balancing between routes of equal cost. An OSPF network is divided into routing areas to optimize traffic. An area is a logical collection of OSPF networks, routers, and links that have the same area identification.
Areas are identified by an Area ID.
Retrieve OSPF configuration.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. isis configuration section removed. |
| 6.3.0 | Method updated. Parameter defaultOriginate removed for logical router NSX Edges. Parameter translateType7ToType5 added to OSPF section. |
Configure OSPF.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. isis configuration section removed. |
| 6.3.0 | Method updated. Parameter defaultOriginate removed for logical router NSX Edges. Parameter translateType7ToType5 added to OSPF section. |
Delete OSPF routing.
Working With BGP Routes for NSX Edge
Border Gateway Protocol (BGP) makes core routing decisions. It includes a table of IP networks or prefixes which designate network reachability among autonomous systems. An underlying connection between two BGP speakers is established before any routing information is exchanged. Keep alive messages are sent out by the BGP speakers in order to keep this relationship alive. Once the connection is established, the BGP speakers exchange routes and synchronize their tables.
Retrieve BGP configuration.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. isis configuration section removed. |
| 6.3.0 | Method updated. Parameter defaultOriginate removed for logical router NSX Edges. Parameters localASNumber and remoteASNumber added to BGP section. |
| 6.3.6 | Method updated. Parameter removePrivateAS added. |
Configure BGP.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. isis configuration section removed. |
| 6.3.0 | Method updated. Parameter defaultOriginate removed for logical router NSX Edges. Parameters localASNumber and remoteASNumber added to BGP section. |
Delete BGP Routing
Working With Layer 2 Bridging
Retrieve bridge configuration. The value of the enabled field is always true for a Distributed Logical Router.
Configure a bridge. Note that the bridging is always enabled for Distributed Logical Router and is unsupported for Edge Services Gateway. You cannot disable the bridging by setting the enable field to false. The value for the enable field is not honored.
Delete bridges.
Working With NSX Edge Load Balancer
The NSX Edge load balancer enables network traffic to follow multiple paths to a specific destination. It distributes incoming service requests evenly among multiple servers in such a way that the load distribution is transparent to users. Load balancing thus helps in achieving optimal resource utilization, maximizing throughput, minimizing response time, and avoiding overload. NSX Edge provides load balancing up to Layer 7.
You map an external, or public, IP address to a set of internal servers for load balancing. The load balancer accepts TCP, HTTP, or HTTPS requests on the external IP address and decides which internal server to use. Port 8090 is the default listening port for TCP, port 80 is the default port for HTTP, and port 443 is the default port for HTTPs.
Get load balancer configuration.
Configure load balancer.
The input contains five parts: application profile, virtual server, pool, monitor and application rule.
For the data path to work, you need to add firewall rules to allow required traffic as per the load balancer configuration.
General Load Balancer Parameters
| Parameter | Description | Comments |
|---|---|---|
| logging | Load balancer logging setting. | Optional. |
| enable | Whether logging is enabled. | Optional. Options are True or False. Default is False. |
| logLevel | Logging level. | Optional. Options are: EMERGENCY, ALERT, CRITICAL, ERROR, WARNING, NOTICE, INFO, and DEBUG. Default is INFO. |
| accelerationEnabled | Whether accelerationEnabled is enabled. | Optional. Options are True or False. Default is False. |
| enabled | Whether load balancer is enabled. | Optional. Options are True or False. Default is True. |
Parameter Table for Monitors
| Parameter | Description | Comments |
|---|---|---|
| monitor | Monitor list. | Optional. |
| monitorId | Generated monitor identifier. | Optional. Required if it is used in a pool. |
| name | Name of the monitor. | Required. |
| type | Monitor type. | Required. Options are : HTTP, HTTPS, TCP, ICMP, UDP. |
| interval | Interval in seconds in which a server is to be tested. | Optional. Default is 5. |
| timeout | Timeout value is the maximum time in seconds within which a response from the server must be received. | Optional. Default is 15. |
| maxRetries | Maximum number of times the server is tested before it is declared DOWN. | Optional. Default is 3. |
| method | Method to send the health check request to the server. | Optional. Options are: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT. Default is GET for HTTP monitor. |
| url | URL to GET or POST. | Optional. Default is "/" for HTTP monitor. |
| expected | Expected string. | Optional. Default is "HTTP/1" for HTTP/HTTPS protocol. |
| send | String to be sent to the backend server after a connection is established. | Optional. URL encoded HTTP POST data for HTTP/HTTPS protocol. |
| receive | String to be received from the backend server for HTTP/HTTPS protocol. | Optional. |
| extension | Advanced monitor configuration. | Optional. |
Parameter Table for Virtual Servers
| Parameter | Description | Comments |
|---|---|---|
| virtualServer | Virtual server list. | Optional. 0-64 virtualServer items can be added |
| name | Name of the virtual server. | Required. Unique virtualServer name per NSX Edge. |
| description | Description of the virtual server. | Optional. |
| enabled | Whether the virtual server is enabled. | Optional. Boolean. Options are True or False. Default is True. |
| ipAddress | IP address that the load balancer is listening on. | Required. A valid Edge vNic IP address (IPv4 or IPv6). |
| protocol | Virtual server protocol. | Required. Options are: HTTP, HTTPS, TCP, UDP. |
| port | Port number or port range. | Required. Port number such as 80, port range such as 80,443 or 1234-1238, or a combination such as 443,6000-7000. Valid range: 1-65535. |
| connectionLimit | Maximum concurrent connections. | Optional. Long. Default is 0. |
| connectionRateLimit | Maximum incoming new connection requests per second. | Optional. Long. Default is null. |
| defaultPoolId | Default pool ID. | Optional. |
| applicationProfileId | Application profile ID. | Optional. |
| accelerationEnabled | Use the faster L4 load balancer engine rather than L7 load balancer engine. | Optional. Boolean. Options are True or False. Default is False. If a virtual server configuration such as application rules, HTTP type, or cookie persistence, is using the L7 load balancer engine, then the L7 load balancer engine is used, even if accelerationEnabled is not set to true. |
| applicationRuleId | Application rule ID list. | Optional. |
Parameter Table for Pools
| Parameter | Description | Comments |
|---|---|---|
| pool | Pool list. | Optional. |
| poolId | Generated pool identifier. | Optional. Required if you specify pool object. |
| name | Name of the pool. | Required. |
| description | Description of the pool. | Optional. |
| algorithm | Pool member balancing algorithm. | Optional. Options are: round-robin, ip-hash, uri, leastconn, url, httpheader. Default is round-robin. |
| algorithmParameters | Algorithm parameters for httpheader, url. | Optional. Required for url,httpheader algorithm. |
| transparent | Whether client IP addresses are visible to the backend servers. | Optional. Options are True or False. Default is False. |
| monitorId | Monitor identifier list. | Optional. Only one monitor is supported. |
| member | Pool member list. | Optional. |
| memberId | Generated member identifier. | Optional. Required if you specify member object. |
| name | Member name. | Optional. Required when it is used in ACL rule. |
| ipAddress | Member IP address (IPv4/IPv6). | Optional. Required if groupingObjectId is null. |
| groupingObjectId | Member grouping object identifier. | Optional. Required if ipAddress is null. |
| groupingObjectName | Member grouping object name. | Optional. |
| weight | Member weight. | Optional. Default is 1. |
| monitorPort | Monitor port. | Optional. Long. Either monitorPort or port must be configured. |
| port | Member port. | Optional. Long. Either monitorPort or port must be configured. |
| maxConn | Maximum number of concurrent connections a member can handle. | Optional. Default is 0 which means unlimited. |
| minConn | Minimum number of concurrent connections a member can handle. | Optional. Default is 0 which means unlimited. |
| condition | Whether the member is enabled or disabled. | Optional. Options are: enabled or disabled. Default is enabled. |
Parameter Table for Application Profiles
| Parameter | Description | Comments |
|---|---|---|
| applicationProfile | Application profile list. | Optional. |
| applicationProfileId | Generated application profile identifier. | Optional. Required if it is used in virtual server. |
| name | Name of application profile. | Required. |
| persistence | Persistence setting. | Optional. |
| method | Persistent method. | Required. Options are: cookie, ssl_sessionid, sourceip, msrdp. |
| cookieName | Cookie name. | Optional. |
| cookieMode | Cookie mode. | Optional. Options are: insert, prefix, app. |
| expire | Expire time. | Optional. |
| insertXForwardedFor | Whether insertXForwardedFor is enabled. | Optional. Boolean. Options are True or False. Default is False. |
| sslPassthrough | Whether sslPassthrough is enabled. | Optional. Boolean. Options are True or False. Default is False. |
| httpRedirect | HTTP redirect setting. | Optional. |
| to | HTTP redirect to. | Required. Required if httpRedirect is specified. |
| serverSslEnabled | Whether serverSsl offloading is enabled. | Optional. Boolean. Options are True or False. |
| serverSsl | Server SSL setting. | Optional. |
| ciphers | Cipher suites. | Optional. Options are: DEFAULT ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES256-SHA, ECDHE-ECDSA-AES256-SHA, ECDH-ECDSA-AES256-SHA, ECDH-RSA-AES256-SHA, AES256-SHA AES128-SHA, DES-CBC3-SHA. Default is DEFAULT. |
| serviceCertificate | Service certificate identifier list. | Optional. Only one certificate is supported. |
| caCertificate | CA identifier list. | Optional. Required if serverAuth is required. |
| crlCertificate | CRL identifier list. | Optional. |
| serverAuth | Whether peer certificate should be verified. | Optional. Options are Required or Ignore. Default is Ignore. |
| clientSsl | Client SSL setting. | Optional. |
| ciphers | Cipher suites. | Optional. Options are: DEFAULT ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES256-SHA, ECDHE-ECDSA-AES256-SHA, ECDH-ECDSA-AES256-SHA, ECDH-RSA-AES256-SHA, AES256-SHA AES128-SHA, DES-CBC3-SHA. Default is DEFAULT. |
| serviceCertificate | Service certificate identifier list. | Required. Only one certificate is supported. |
| caCertificate | CA identifier list. | Optional. |
| crlCertificate | CRL identifier list. | Optional. |
| clientAuth | Whether peer certificate should be verified. | Optional. Options are Required or Ignore. Default is Ignore. |
Parameter Table for Application Rules
| Parameter | Description | Comments |
|---|---|---|
| applicationRule | Application rule list. | Optional. |
| applicationRuleId | Generated application rule identifier. | Optional. |
| name | Name of application rule. | Required. |
| script | Application rule script. | Required. |
For the data path to work, you need to add firewall rules to allow required traffic as per the load balancer configuration.
Delete load balancer configuration.
Working With Application Profiles
You create an application profile to define the behavior of a particular type of network traffic. After configuring a profile, you associate the profile with a virtual server. The virtual server then processes traffic according to the values specified in the profile. Using profiles enhances your control over managing network traffic, and makes traffic-management tasks easier and more efficient.
See Working With NSX Edge Load Balancer for applicationProfiles parameter information.
Add an application profile.
Retrieve all application profiles on the specified Edge.
Delete all application profiles on the specified Edge.
Working With a Specific Application Profile
Modify an application profile.
Retrieve an application profile.
Delete an application profile.
Working With Application Rules
You can write an application rule to directly manipulate and manage IP application traffic.
See Working With NSX Edge Load Balancer for applicationRule parameter information.
Add an application rule.
Retrieve all application rules.
Delete all application rules.
Working With a Specific Application Rule
Retrieve an application rule.
Modify an application rule.
Delete an application rule.
Working With Load Balancer Monitors
You create a service monitor to define health check parameters for a particular type of network traffic. When you associate a service monitor with a pool, the pool members are monitored according to the service monitor parameters.
See Working With NSX Edge Load Balancer for monitor parameter information.
Add a load balancer monitor.
Retrieve all load balancer monitors.
Delete all load balancer monitors.
Working With a Specific Load Balancer Monitor
Retrieve a load balancer monitor.
Modify a load balancer monitor.
Delete a load balancer monitor.
Working With Virtual Servers
Add a virtual server.
You can add an NSX Edge internal or uplink interface as a virtual server.
See Working With NSX Edge Load Balancer for virtualServer parameter information.
Retrieve all virtual servers.
Delete all virtual servers.
Working With a Specific Virtual Server
Retrieve details for the specified virtual server.
Delete the specified virtual server.
Working With Server Pools
You can add a server pool to manage and share backend servers flexibly and efficiently. A pool manages load balancer distribution methods and has a service monitor attached to it for health check parameters.
See Working With NSX Edge Load Balancer for pools parameter information.
Add a load balancer server pool to the Edge.
Method history:
| Release | Modification |
|---|---|
| 6.3.0 | Method updated. Member condition can be set to drain. |
Get all server pools on the specified NSX Edge.
Delete all server pools configured on the specified NSX Edge.
Working With a Specific Server Pool
Retrieve information about the specified server pool.
Update the specified server pool.
Method history:
| Release | Modification |
|---|---|
| 6.3.0 | Method updated. Member condition can be set to drain. |
Delete the specified server pool.
Working With a Specific Load Balancer Member
Update enabled status of the specified member.
Working With Load Balancer Statistics
Retrieves load balancer statistics.
Load Balancer Statistics Parameters
| Parameter | Description |
|---|---|
| virtualServer | Virtual server list. |
| virtualServerId | Virtual server identifier. |
| name | Name of the virtual server. |
| description | Description of virtual server. |
| ipAddress | IP address that the load balancer is listening on. |
| status | Virtual server status. |
| bytesIn | Number of bytes in. |
| bytesOut | Number of bytes out. |
| curSessions | Number of current sessions. |
| httpReqTotal | Total number of HTTP requests received. |
| httpReqRate | HTTP requests per second over last elapsed second. |
| httpReqRateMax | Maximum number of HTTP requests per second observed. |
| maxSession | Number of maximum sessions. |
| rate | Number of sessions per second over last elapsed second. |
| rateLimit | Configured limit on new sessions per second. |
| rateMax | Maximum number of new sessions per second. |
| totalSession | Total number of sessions. |
| pool | Pool list. |
| poolId | Generated pool identifier. |
| name | Name of the pool. |
| description | Description of the pool. |
| status | Pool status. |
| bytesIn | Number of bytes in. |
| bytesOut | Number of bytes out. |
| curSessions | Number of current sessions. |
| httpReqTotal | Total number of HTTP requests received. |
| httpReqRate | HTTP requests per second over last elapsed second. |
| httpReqRateMax | Maximum number of HTTP requests per second observed. |
| maxSession | Number of maximum sessions. |
| rate | Number of sessions per second over last elapsed second. |
| rateLimit | Configured limit on new sessions per second. |
| rateMax | Maximum number of new sessions per second. |
| totalSession | Total number of sessions. |
| member | Pool member list. |
| memberId | Generated member identifier. |
| name | Member name. |
| ipAddress | Member IP address. |
| groupingObjectId | Member grouping object identifier. |
| status | Member status. |
| bytesIn | Number of bytes in. |
| bytesOut | Number of bytes out. |
| curSessions | Number of current sessions. |
| httpReqTotal | Total number of HTTP requests received. |
| httpReqRate | HTTP requests per second over last elapsed second. |
| httpReqRateMax | Maximum number of HTTP requests per second observed. |
| maxSession | Number of maximum sessions. |
| rate | Number of sessions per second over last elapsed second. |
| rateLimit | Configured limit on new sessions per second. |
| rateMax | Maximum number of new sessions per second. |
| totalSession | Total number of sessions. |
| timestamp | Timestamp to fetch load balancer statistics. |
| serverStatus | Load balancer server status. |
Retrieve load balancer statistics.
Working With Load Balancer Acceleration
Configure load balancer acceleration mode.
Working With NSX Edge DNS Server Configuration
You can configure external DNS servers to which NSX Edge can relay name resolution requests from clients. NSX Edge will relay client application requests to the DNS servers to fully resolve a network name and cache the response from the servers.
The DNS server list allows two addresses – primary and secondary. The default cache size is 16 MB where the minimum can be 1 MB, and the maximum 8196 MB. The default listeners is any, which means listen on all NSX Edge interfaces. If provided, the listener’s IP address must be assigned to an internal interface. Logging is disabled by default.
Retrieve DNS configuration.
Configure DNS servers.
Delete DNS configuration
Get DNS server statistics
Get DNS server statistics
DNS Server Statistics Parameters
| Parameter Name | Parameter Information |
|---|---|
| requests > total | Indicates all of the incoming requests to the DNS server, including DNS query and other types of requests such as transfers, and updates. |
| requests > queries | Indicates all of the DNS queries the server received. |
| requests > total | Indicates all of the responses the server returned to requests. This might be different from the requests.total because some requests might be rejected. total = success + nxrrset + servFail + formErr + nxdomain + others. |
| responses > success | Indicates all of the successful DNS responses. |
| responses > nxrrset | Indicates the count of no existent resource record. |
| responses > servFail | Indicates the count of the SERVFAIL responses. |
| responses > formErr | Indicates the count of the format error responses. |
| responses > nxdomain | Indicates the count of no-such-domain answer |
| responses > others | Indicates the count of other types of responses. |
Configure DHCP for NSX Edge
NSX Edge provides DHCP service to bind assigned IP addresses to MAC addresses, helping to prevent MAC spoofing attacks. All virtual machines protected by a NSX Edge can obtain IP addresses dynamically from the NSX Edge DHCP service.
NSX Edge supports IP address pooling and one-to-one static IP address allocation based on the vCenter managed object ID (vmId) and interface ID (interfaceId) of the requesting client.
If either bindings or pools are not included in the PUT call, existing bindings or pools are deleted.
If the NSX Edge autoConfiguration flag and autoConfigureDNS is true, and the primaryNameServer or secondaryNameServer parameters are not specified, NSX Manager applies the DNS settings to the DHCP configuration.
NSX Edge DHCP service adheres to the following rules:
- Listens on the NSX Edge internal interface (non-uplink interface) for DHCP discovery.
- As stated above, vmId specifies the vc-moref-id of the virtual machine, and vnicId specifies the index of the vNic for the requesting client. The hostname is an identification of the binding being created. This hostName is not pushed as the specified host name of the virtual machine.
- By default, all clients use the IP address of the internal interface of the NSX Edge as the default gateway address. To override it, specify defaultGateway per binding or per pool. The client’s broadcast and subnetMask values are from the internal interface for the container network.
- leaseTime can be infinite, or a number of seconds. If not specified, the default lease time is 1 day.
- Logging is disabled by default.
- Setting the parameter enable to true starts the DHCP service while setting enable to false stops the service.
- Both staticBinding and ipPools must be part of the PUT request body. If either bindings or pools are not included in the PUT call, existing bindings or pools are deleted.
DHCP Configuration Parameters
| Parameter Name | Parameter Information |
|---|---|
| enabled | Default is true. |
| staticBinding | Assign an IP address via DHCP statically rather than dynamically. You can either specify macAddress directly, or specify vmId and vnicId. In case both are specified, only macAddress will be used; vmId and vnicId will be ignored. |
| staticBinding > macAddress | Optional. |
| staticBinding > vmId | Optional. The VM must be connected to the specified vnicId. |
| staticBinding > vnicId | Optional. Possible values 0 to 9. |
| staticBinding > hostname | Optional. Disallow duplicate. |
| staticBinding > ipAddress | The IP can either belong to a a subnet of one of Edge's vNics or it can be any valid IP address, but the IP must not overlap with any primary/secondary IP addresses associated with any of Edge's vNICs. If the IP does not belong to any Edge vNic subnets, you must ensure that the default gateway and subnetMask are configured via this API call. |
| ipPool > ipRange | Required. The IP range can either fall entirely within one of the Edge vNIC subnets, or it can be a valid IP range outside any Edge subnets. The IP range, however, cannot contain an IP that is defined as a vNic primary secondary IP. If the range does not fall entirely within one of the Edge vNIC subnets, you must provide correct subnetMask and defaultGateway. |
| defaultGateway (staticBinding and ipPool) | Optional. If the ipRange (for ipPool) or assigned IP (for staticBinding) falls entirely within one of the Edge vNIC subnets, defaultGateway is set to the primary IP of the vNIC configured with the matching subnet. Otherwise, you must provide the correct gateway IP. If an IP is not provided, the client host may not get default gateway IP from the DHCP server. |
| subnetMask (staticBinding and ipPool) | Optional. If not specified, and the the ipRange (for ipPool) or assigned IP (for staticBinding) belongs to an Edge vNic subnet, it is defaulted to the subnet mask of this vNic subnet. Otherwise, it is defaulted to a minimum subnet mask which is figured out with the IP range itself, e.g. the mask of range 192.168.5.2-192.168.5.20 is 255.255.255.224. You can edit this range, if required. Note: If you do not specify a subnet mask when configuring DHCP, subnetMask is not included in the output of GET /api/4.0/edges/{edgeId}/dhcp/config or GET /api/4.0/edges/{edgeId}/dhcp/config/bindings/{bindingID}. You can run show configuration dhcp on the Edge VM CLI to view the subnet mask. |
| domainName (staticBinding and ipPool) | Optional. |
| primaryNameServer secondaryNameServer (staticBinding and ipPool) | Optional. If autoConfigureDNS is true, the DNS primary/secondary IPs will be generated from DNS service (if configured). |
| leaseTime (staticBinding and ipPool) | Optional. In seconds, default is 86400. Valid leaseTime is a valid number or infinite. |
| autoConfigureDns (staticBinding and ipPool) | Optional. Default is true. |
| nextServer (staticBinding and ipPool) | Global TFTP server setting. If an IP pool or static binding has a TFTP server configured via option66 or option150, that server will be used instead. |
| dhcpOptions (staticBinding and ipPool) | Optional. |
| dhcpOptions > option121 (staticBinding and ipPool) | Add a static route. |
| dhcpOptions > option121 > destinationSubnet (staticBinding and ipPool) | Destination network, for example 1.1.1.4/30. |
| dhcpOptions > option121 > router (staticBinding and ipPool) | Router IP address. |
| dhcpOptions > option66 (staticBinding and ipPool) | Hostname or IP address of a single TFTP server for this IP pool. |
| dhcpOptions > option67 (staticBinding and ipPool) | Filename to be downloaded from TFTP server. |
| dhcpOptions > option150 (staticBinding and ipPool) | IP address of TFTP server. |
| dhcpOptions > option150 > server (staticBinding and ipPool) | Use to specify more than one TFTP server by IP address for this IP Pool. |
| dhcpOptions > option26 (staticBinding and ipPool) | MTU. |
| dhcpOptions > other (staticBinding and ipPool) | Add DHCP options other than 26, 66, 67, 121, 150. |
| dhcpOptions > other > code (staticBinding and ipPool) | Use the DHCP option number only. For example, to specify dhcp option 80, enter 80. |
| dhcpOptions > other > value (staticBinding and ipPool) | The DHCP option value, in hex. For example, 2F766172. |
| logging | Optional. Logging is disabled by default. |
| logging > enable | Optional, default is false. |
| logging > logLevel | Optional, default is info. |
Retrieve DHCP configuration.
Method History
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. DHCP options added. |
Configure DHCP service.
Method History
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. DHCP options added. |
Delete the DHCP configuration, restoring it to factory default.
Working With DHCP IP Pools
Add an IP pool to the DHCP configuration. Returns a pool ID within a Location HTTP header.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. DHCP options added. |
Working With a Specific DHCP IP Pool
Delete a pool specified by pool ID
Working With DHCP Static Bindings
Append a static-binding to DHCP config. A static-binding ID is returned within a Location HTTP header.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. DHCP options added. |
Working With a Specific DHCP Static Binding
Retrieve the specified static binding.
Method history:
| Release | Modification |
|---|---|
| 6.3.3 | Method introduced. |
Delete the specified static binding.
Working With DHCP Relays
Dynamic Host Configuration Protocol (DHCP) relay enables you to leverage your existing DHCP infrastructure from within NSX without any interruption to the IP address management in your environment. DHCP messages are relayed from virtual machine(s) to the designated DHCP server(s) in the physical world. This enables IP addresses within NSX to continue to be in synch with IP addresses in other environments.
DHCP configuration is applied on the logical router port and can list several DHCP servers. Requests are sent to all listed servers. While relaying the DHCP request from the client, the relay adds a Gateway IP Address to the request. The external DHCP server uses this gateway address to match a pool and allocate an IP address for the request. The gateway address must belong to a subnet of the NSX port on which the relay is running.
You can specify a different DHCP server for each logical switch and can configure multiple DHCP servers on each logical router to provide support for multiple IP domains.
NOTE DHCP relay does not support overlapping IP address space (option 82).
DHCP Relay and DHCP service cannot run on a port/vNic at the same time. If a relay agent is configured on a port, a DHCP pool cannot be configured on the subnet(s) of this port.
| Parameter | Comments |
|---|---|
| relay | You can configure ipPool, static-binding and relay at the same time if there is not any overlap on vnic. |
| relayServer | Required. There must be at least one external server. |
| groupingObjectId | A list of dhcp server IP addresses. There can be multiple sever group objects, the maximum groupObject is 4, the maximum number of server IP addresses is 16. |
| ipAddress | Supports both IP address and FQDN. |
| fqdn | Specify the IP of the fqdn, and add a Firewall rule to allow the response from the server represented by the fqdn such as: src - the IP; dest - any; service - udp:67:any. |
| relayAgents | Required. There must be at least one relay agent. |
| vnicIndex | Required. No default. Specify the vNic that proxy the dhcp request. |
| giAddress | Optional. Defaults to the vNic primary address. Only one giAddress allowed. |
Retrieve DHCP relay information.
Configure DHCP relay.
Delete DHCP relay configuration.
Working With NSX Edge High Availability
High Availability (HA) ensures that a NSX Edge appliance is always available on your virtualized network. You can enable HA either when installing NSX Edge or on an installed NSX Edge instance.
If a single appliance is associated with NSX Edge, the appliance configuration is cloned for the standby appliance. If two appliances are associated with NSX Edge and one of them is deployed, this REST call deploys the remaining appliance and push HA configuration to both.
HA relies on an internal interface. If an internal interface does not exist, this call will not deploy the secondary appliance, or push HA config to appliance. The enabling of HA will be done once an available internal interface is added. If the PUT call includes an empty <highAvailability /> or enabled=false, it acts as a DELETE call.
Get high availability configuration.
Configure high availability.
- ipAddress - Optional. A pair of ipAddresses with /30 subnet mandatory, one for each appliance. If provided, they must NOT overlap with any subnet defined on the Edge vNics. If not specified, a pair of IPs will be picked up from the reserved subnet, 169.254.0.0/16.
- declareDeadTime Optional. The default is 6 seconds.
- enabled - Optional. The default is set to true. The enabled flag will cause the HA appliance to be deployed or destroyed.
NSX Manager deletes the standby appliance and removes the HA config from the active appliance. You can also delete the HA configuration by using a PUT call with empty <highAvailability /> or with <highAvailability><enabled>false</enabled></highAvailability>.
Working With Remote Syslog Server on NSX Edge
You can configure one or two remote syslog servers. Edge events and logs related to firewall events that flow from Edge appliances are sent to the syslog servers
Retrieve syslog servers information.
Configure syslog servers.
Delete syslog servers.
Working With SSL VPN
With SSL VPN-Plus, remote users can connect securely to private networks behind a NSX Edge gateway. Remote users can access servers and applications in the private networks.
Enable or disable SSL VPN on the NSX Edge appliance.
Retrieve SSL VPN details.
Update the entire SSL VPN configuration to the specified NSX Edge in a single call.
Delete the SSL VPN configurations on the Edge.
Working With SSL VPN Server
Retrieve server settings.
Update server settings.
Working With Private Networks
You can use a private network to expose to remote users over SSL VPN tunnel.
Configure a private network.
Retrieve all private network profiles in the SSL VPN instance.
Update all private network configs of NSX Edge with the given list of private network configs. If the config is present, it is updated; otherwise, a new private network config is created. Existing configs not included in the call body are deleted.
Delete all private networks from the SSL VPN instance.
Working With a Specific Private Network
Retrieve the specified private network in the SSL VPN service.
Update the specified private network in the SSL VPN service.
Delete private network
Working With IP Pools for SSL VPN
Create an IP pool.
Retrieve all IP pools configured on SSL VPN.
Update all IP pools with the given list of pools. If the pool is present, it is updated; otherwise, a new pool is created. Existing pools not in the body are deleted.
Delete all IP pools configured on SSL VPN
Working With a Specific IP Pool for SSL VPN
Retrieve details of specified IP pool.
Update specified IP pool.
Delete the specified IP pool.
Working With Network Extension Client Parameters
Set advanced parameters for full access client configurations, such as whether client should auto-reconnect in case of network failures or network unavailability, or whether the client should be uninstalled after logout.
Retrieve client configuration.
Working With SSL VPN Client Installation Packages
Creates setup executables (installers) for full access network clients. These setup binaries are later downloaded by remote clients and installed on their systems. The primary parameters needed to configure this setup are hostname of the gateway, and its port and a profile name which is shown to the user to identify this connection. The Administrator can also set other parameters such as whether to automatically start the application on windows login, or hide the system tray icon.
Retrieve information about all installation packages.
Update all installation packages with the given list. If the package is present, it is updated; otherwise a new installation package is created. Existing packages not included in the body are deleted.
Delete all client installation packages.
Working With a Specific SSL VPN Client Installation Package
Get information about the specified installation package.
Modify the specified installation package.
Delete the specified installation package.
Working With Image Files for SSL VPN
Upload images for use with SSL VPN portal and client.
You can upload a logo to use in the SSL VPN portal, and a banner and icons to use in the SSL VPN client.
You must upload the image files 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. See the table below for the form-data key to use for each image type. The value is the path to the image file.
| Image Type | form-data key | Image format requirements |
|---|---|---|
| portallogo | layoutFile | n/a |
| phatbanner | banner | bmp |
| connecticon | icon | ico |
| disconnecticon | icon | ico |
| erroricon | icon | ico |
| desktopicon | icon | ico |
Example using curl
/usr/bin/curl -v -k -i -F layoutFile=@/tmp/portalLogo.jpg -H 'Authorization: Basic YWRtaW46ZGXXXXXXXX=='
https://192.168.110.42/api/4.0/edges/edge-3/sslvpn/config/layout/images/portallogo
Working With Portal Users
Add a new portal user.
Modify the portal user specified in the request body.
Delete all users on the specifed SSL VPN instance
Working With a Specific Portal User
Get information about the specified user.
Delete the specified user.
Working With Authentication Settings
Retrieve information about authentication settings.
Update authentication settings for remote users. Specify username/password authentication, active directory, ldap, radius, client certificate based authentication.
Working With the RSA Config File
Upload RSA config file (See "Generate the Authentication Manager Configuration File" section of the RSA Authentication Manager Administrator's guide for instructions on how to configure and download the RSA config file from RSA Authentication Manager).
SSL VPN Advanced Configuration
Retrieve SSL VPN advanced configuration.
Update SSL VPN advanced configuration.
Working With Logon and Logoff Scripts for SSL VPN
Configure parameters associated with the uploaded script file.
Retrieve all script configurations.
Update all script configurations with the given list of configurations. If the config is present, its is updated; otherwise, a new config is created. Existing configs not included in the body are deleted.
Delete all script configurations
Working With Uploaded Script Files
Retrieve parameters associated with the specified script file.
Update parameters associated with the specified script file.
Delete script parameters.
Uploading Script Files for SSL VPN
You can add multiple login or logoff scripts. For example, you can bind a login script for starting Internet Explorer with gmail.com. When the remote user logs in to the SSL client, Internet Explorer opens up gmail.com. This method returns a scriptFileId which can be used to update parameters associated with the script file.
You must upload the script files 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 script file.
Example using curl
/usr/bin/curl -v -k -i -F file=@/tmp/script.sh -H 'Authorization: Basic YWRtaW46ZGXXXXXXXX=='
https://192.168.110.42/api/4.0/edges/edge-3/sslvpn/config/script/file/
Working With SSL VPN Users
Update all users with the given list of users. If the user is present, it is updated. Otherwise, and new user is created. Existing users not included in the body are deleted.
Working With Active Client Sessions
Retrieve a list of active clients for the SSL VPN session.
Working With a Specific Active Client Session
Disconnect an active client.
Working With NSX Edge Firewall Dashboard Statistics
Retrieve number of ongoing connections for the firewall configuration.
Working With SSL VPN Dashboard Statistics
Retrieve SSL VPN statistics on the specified NSX Edge.
Working With Tunnel Traffic Dashboard Statistics
Retrieve tunnel traffic statistics for specified time interval.
Working With Interface Dashboard Statistics
Retrieves dashboard statistics between the specified start and end times. When start and end time are not specified, all statistics since the Edge deployed are displayed. When no end time is specified, the current Edge Manager time is set as endTime. Each record has the stats of 5 minutes granularity.
Working With Interface Statistics
Retrieve interface statistics.
Working With Uplink Interface Statistics
Retrieve uplink interface statistics.
Working With Internal Interface Statistics
Retrieve internal interface statistics.
Working With L2 VPN
L2 VPN allows you to configure a tunnel between two sites. VMs can move between the sites and stay on the same subnet, enabling you to extend your datacenter. An NSX Edge at one site can provide all services to VMs on the other site.
Enable or disable L2 VPN service.
Retrieve the current L2VPN configuration for NSX Edge.
Method history:
| Release | Modification |
|---|---|
| 6.3.5 | Method updated. showSensitiveData query parameter added. |
Configure L2VPN for server or client.
You first enable the L2 VPN service on the NSX Edge instance and then configure a server and a client.
L2 VPN Parameters
| Parameter | Description | Comments |
|---|---|---|
| enabled | Whether L2 VPN is enabled. | Optional. Boolean. Options are True or False. Default is True. |
| logging | L2 VPN logging setting. | Optional. Disable by default. |
| logging > enable | Whether logging is enabled. | Optional. Boolean. Options are True or False. Default is False. |
| logging > logLevel | Logging level. | Optional. Options are: EMERGENCY, ALERT, CRITICAL, ERROR, WARNING, NOTICE, INFO, and DEBUG. Default is INFO. |
| listenerIp | IP of external interface on which L2VPN service listens to. | Required. |
| listenerPort | Port on which L2VPN service listens to. | Optional. Default is 443. |
| encryptionAlgorithm | Encryption algorithm for communication between the server and the client. | Mandatory. Supported ciphers are RC4-MD5, AES128-SHA, AES256-SHA, DES-CBC3-SHA, AES128-GCM-SHA256, and NULL-MD5. |
| serverCertificate | Select the certificate to be bound to L2 VPN server. | Optional. If not specified server will use its default (self-signed) certificate. |
Peer Site Parameters
| Parameter | Description | Comments |
|---|---|---|
| peerSites | To connect multiple sites to the L2 VPN server. | Required. Minimum one peer site must be configured to enable L2 VPN server service. |
| name | Unique name for the site getting configured. | Required. |
| description | Description about the site. | Optional. |
| l2VpnUser | Every peer site must have a user configuration. | Required. |
| l2VpnUser > userId | L2 VPN user ID. | Required. |
| l2VpnUser > password | Password for L2 VPN user. | Required. |
| vnics | List of vNICs to be stretched over the tunnel. | Required. |
| vnics > index | Select the virtual machine NIC to bind to the IP address. | Required. |
| egressOptimization > gatewayIpAddress | The gateway IP addresses for which the traffic should be locally routed or for which traffic is to be blocked over the tunnel. | Optional. |
| enabled | Whether the peer site is enabled. | Optional. Boolean. Options are True or False. Default is True. |
Example to configure L2 VPN for Client
<l2Vpn>
<enabled>true</enabled>
<logging>
<enable>false</enable>
<logLevel>info</logLevel>
</logging>
<l2VpnSites>
<l2VpnSite>
<client>
<configuration>
<serverAddress>192.168.15.23</serverAddress>
<serverPort>443</serverPort>
<vnic>10</vnic>
<encryptionAlgorithm>AES128-SHA</encryptionAlgorithm>
<caCertificate>certificate-4</caCertificate>
<egressOptimization>
<gatewayIpAddress>192.168.15.1</gatewayIpAddress>
</egressOptimization>
</configuration>
<proxySetting>
<type>https</type>
<address>10.112.243.202</address>
<port>443</port>
<userName>root</userName>
<password>java123</password>
</proxySetting>
<l2VpnUser>
<userId>apple</userId>
<password>apple</password>
</l2VpnUser>
</client>
</l2VpnSite>
</l2VpnSites>
</l2Vpn>
Example to configure L2 VPN for Server
<l2Vpn>
<enabled>true</enabled>
<logging>
<enable>false</enable>
<logLevel>info</logLevel>
</logging>
<l2VpnSites>
<l2VpnSite>
<server>
<configuration>
<listenerIp>192.168.15.65</listenerIp>
<listenerPort>443</listenerPort>
<encryptionAlgorithm>RC4-MD5</encryptionAlgorithm>
<peerSites>
<peerSite>
<name>PeerSite1</name>
<description>description</description>
<l2VpnUser>
<userId>apple</userId>
<password>apple</password>
</l2VpnUser>
<vnics>
<index>10</index>
</vnics>
<egressOptimization>
<gatewayIpAddress>192.168.15.1</gatewayIpAddress>
</egressOptimization>
<enabled>true</enabled>
</peerSite>
</peerSites>
</configuration>
</server>
</l2VpnSite>
</l2VpnSites>
</l2Vpn>
Delete the L2 VPN configuration.
Working With L2 VPN Statistics
Retrieve L2 VPN statistics, which has information such as tunnel status, sent bytes, received bytes for the specified Edge.
Working With IPsec VPN
NSX Edge supports site-to-site IPsec VPN between an NSX Edge instance and remote sites. NSX Edge supports certificate authentication, preshared key mode, IP unicast traffic, and no dynamic routing protocol between the NSX Edge instance and remote VPN routers. Behind each remote VPN router, you can configure multiple subnets to connect to the internal network behind an NSX Edge through IPsec tunnels. These subnets and the internal network behind a NSX Edge must have address ranges that do not overlap.
You can deploy an NSX Edge agent behind a NAT device. In this deployment, the NAT device translates the VPN address of an NSX Edge instance to a publicly accessible address facing the Internet. Remote VPN routers use this public address to access the NSX Edge instance.
You can place remote VPN routers behind a NAT device as well. You must provide the VPN native address and the VPN Gateway ID to set up the tunnel. On both ends, static one-to-one NAT is required for the VPN address.
You can have a maximum of 64 tunnels across a maximum of 10 sites.
IPsec VPN Parameters
| Parameter | Description | Comments |
|---|---|---|
| logging | IPsec VPN logging setting. | Optional. Disable by default. |
| logging > logLevel | Logging level. | Optional. Options are: EMERGENCY, ALERT, CRITICAL, ERROR, WARNING, NOTICE, INFO, and DEBUG. Default is INFO. |
| logging > enable | Whether logging is enabled. | Optional. Boolean. Options are True or False. Default is False. |
| psk | Indicates that the secret key shared between NSX Edge and the peer site is to be used for authentication. | Optional. Required only when peerIp is specified as Any in site configuration. |
| site > encryptionAlgorithm | Encryption algorithm for communication. | Mandatory. Supported ciphers are AES, AES256, Triple DES, and AES-GCM. |
| serviceCertificate | Select the certificate to be bound to IPsec VPN server. | Optional. Required when x.509 certificate mode is selected. |
| caCertificate | List of CA certificates. | Optional. |
| crlCertificate | List of CRL certificates. | Optional. |
| site > enablePfs | Perfect Forward Secrecy (PFS) ensures that each new cryptographic key is unrelated to any previous key. | Optional. Boolean. Options are True or False. Default is True. |
| site > authenticationMode | Select authentication mode as psk or x.509. | Required. |
| site | To connect multiple sites to the IPsec VPN server. | Required. Minimum one site must be configured to enable IPsec VPN server service. |
| site > enabled | Whether site is enabled. | Optional. Boolean. Options are True or False. Default is True. |
| site > name | Unique name for the site getting configured. | Optional. |
| site > description | Description about the site. | Optional. |
| site > localId | Type the IP address of the NSX Edge instance. | Required. |
| site > localIp | Type the IP address of the local endpoint. | Required. |
| site > localSubnets | Type the subnets to share between the sites. | Required. |
| site > peerId | Enter the peer ID to uniquely identify the peer site. This should be a Distinguishing Name (DN) if authentication mode is x.509. | Required. |
| site > peerIp | Enter the IP address of the peer endpoint. | Required. |
| site > peerSubnets | Enter the subnets to share between the sites in CIDR format. | Required if ipsecSessionType parameter value is policybasedsession. For route-based IPSec site, the default and only valid subnet is 0.0.0.0/0 |
| site > dhGroup | In Diffie-Hellman (DH) Group, select the cryptography scheme that will allow the peer site and the NSX Edge to establish a shared secret over an insecure communications channel. | Optional. dh2 is selected by default. |
| extension | When add_spd is set to on, security policies are installed regardless of whether the tunnel is established. ike_fragment_size is used to avoid failure in the IKE negotiation when the link MTU size is small. For example, ike_frament_size=900. | Optional. Global extensions: add_spd and ike_frament_size. add_spd options are off or on. The default is on. |
| site > extension | To disable this value, replace with securelocaltrafficbyip=0. Users can explicitly set this value to one of the other local IP addresses configured in the local subnets of Edge. passthroughSubnets is used to exclude specific subnets from VPN policy enforcement if they overlap with the peerSubnets configured for the same site. | Optional. Configurable per site level: securelocaltrafficbyip |
Retrieve IPsec configuration.
Method history:
| Release | Modification |
|---|---|
| 6.3.5 | Method updated. showSensitiveData query parameter added. |
Update IPsec VPN configuration.
Delete the IPsec configuration.
Automatic Configuration of Firewall Rules
If autoConfiguration is enabled, firewall rules are automatically created to allow control traffic. Rules to allow data traffic are not created. For example, if you are using IPsec VPN, and autoConfiguration is true, firewall rules will automatically be configured to allow IKE traffic. However, you will need to add additional rules to allow the data traffic for the IPsec tunnel. If HA is enabled, firewall rules are always created, even if autoConfiguration is false, otherwise both HA appliances will become active.
Retrieve the auto configuration settings for the NSX Edge.
Update the auto configuration settings for the NSX Edge.
Working With NSX Edge Appliance Configuration
See Working With NSX Edge for additional parameters used to configure appliances.
When you create an NSX Edge, you define parameters that determine how the appliance is deployed, including resourcePoolId, dataStoreId, hostId, and vmFolderId. After the appliance is deployed, these deployment details may change, and the appliance parameters are updated to reflect the current, live location.
You can view the originally configured parameters by using the configuredResourcePool, configuredDataStore, configuredHost, and configuredVmFolder parameters.
You can trigger a high availability failover on the active NSX Edge appliance by changing the haAdminState value to down as part of appliance configuration for an NSX Edge. The haAdminState parameter determines whether or not an NSX Edge appliance is participating in high availability. Both appliances in an NSX Edge high availability configuration normally have an haAdminState of up. When you set the haAdminState of the active appliance to be down, it stops participating in high availability, and informs the standby appliance of its status. The standby appliance becomes active immediately.
| Parameter | Description | Comments |
|---|---|---|
| highAvailabilityIndex | Index number of the appliance | Read only. |
| haAdminState | Indicates whether appliance is participating in high availability. | If the active appliance haAdminState is set to down, it stops participating in HA, and informs the standby appliance of its status. The standby appliance becomes active immediately. |
| configuredResourcePool > id | ID of resource pool on which NSX Edge was originally deployed. | Read only. |
| configuredResourcePool > name | Name of resource pool on which NSX Edge was originally deployed. | Read only. |
| configuredResourcePool > isValid | True if resource pool on which NSX Edge was originally deployed currently exists. | Read only. true or false. |
| configuredDataStore > id | ID of data store on which NSX Edge was originally deployed. | Read only. |
| configuredDataStore > name | Name of data store on which NSX Edge was originally deployed. | Read only. |
| configuredDataStore > isValid | True if resource pool on which NSX Edge was originally deployed currently exists. | Read only. true or false. |
| configuredHost > id | ID of host on which NSX Edge was originally deployed. | Read only. |
| configuredHost > name | Name of host on which NSX Edge was originally deployed. | Read only. |
| configuredHost > isValid | True if resource pool on which NSX Edge was originally deployed currently exists. | Read only. true or false. |
| configuredVmFolder > id | ID of folder in which NSX Edge was originally deployed. | Read only. |
| configuredVmFolder > name | Name of folder in which NSX Edge was originally deployed. | Read only. |
| configuredVmFolder > isValid | True if resource pool on which NSX Edge was originally deployed currently exists. | Read only. true or false. |
Change the size of both appliances.
Retrieve appliance configuration.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. haAdminState, configuredResourcePool, configuredDataStore, configuredHost, configuredVmFolder parameters added. |
You can retrieve the configuration of both appliances by using the GET call and replace the size, resource pool, datastore, and custom parameters of the appliances by using a PUT call. If there were two appliances earlier and you PUT only one appliance, the other appliance is deleted.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. haAdminState parameter added. |
Working With NSX Edge Appliance Configuration by Index
Used to send CLI Commands to the Edge Gateway. To use CLI commands you also need to add an additional Accept Header with type text/plain, as well as the query parameter action=execute.
VMware recommends using the Central CLI instead of this method. See Working With the Central CLI
Retrieve the configuration of the specified appliance.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. haAdminState, configuredResourcePool, configuredDataStore, configuredHost, configuredVmFolder parameters added. |
Update the configuration of the specified appliance.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. haAdminState parameter added. |
Delete the appliance
Working With Edge Services Gateway Interfaces
See Working With NSX Edge for descriptions of parameters used to configure Edge Service Gateway interfaces.
Add an interface or sub interface.
Retrieve all interfaces for the specified Edge Services Gateway.
Working With a Specific Edge Services Gateway Interface
See Working With NSX Edge for descriptions of parameters used to configure Edge Service Gateway interfaces.
Retrieve the specified interface.
Update the specified interface.
Delete interface
Working With Logical Router HA (Management) Interface
Retrieve the management interface configuration for the logical router.
Configure high availability (management) interface for logical (distributed) router. See Working With NSX Edge for descriptions of parameters used to configure the logical router HA interface.
Working With Logical Router Interfaces
Configure interfaces for logical (distributed) router. See Working with NSX Edge for descriptions of parameters used to configure the logical router interfaces.
Add interfaces for a logical router.
Retrieve all interfaces on the logical router.
Delete all interfaces on the logical router.
Working With a Specific Logical Router Interface
Retrieve information about the specified logical router interface.
Delete interface configuration and reset to factory default.
Update interface configuration for the specified logical router interface.
Configuring Edge Services in Async Mode
You can configure NSX Edge to work in async mode. In the async mode, accepted commands return an Accepted status and a taskId. To know the status of the task, you can check the status of that taskId. The advantage of the async mode is that APIs are returned very fast and actions like vm deployment, reboots, publish to NSX Edge appliance, are done behind the scene under the taskId . To configure async mode, ?async=true at the end of any 4.0 service configuration URL for POST, PUT, and DELETE calls. Without async mode, the location header in HTTP response has the resource ID whereas in async mode, location header has the job ID.
The job status response includes the job status (SUCCESS, FAILED, QUEUED, RUNNING, ROLLBACK), URI of the resource, and ID of the resource.
Retrieve NSX Edge job status.
Working With a Specific Edge Job Status
Retrieve job status for the specified job.
nsxEdgePublish
Working With NSX Edge Configuration Publishing
Working With NSX Edge Tuning Configuration
Starting in 6.2.3 you can configure default values for NSX Edge configuration parameters, including publishing and health check timeouts, and CPU and memory reservation, which are applicable to all NSX Edges. The values for the tuning configuration parameters have been set to sensible defaults and may not require any changes. However, based on datacenter capacity and requirements, you can change the default CPU and memory resource reservation percentages using this API. This percentage is applied across all Edge VM Sizes {COMPACT, LARGE, QUADLARGE, XLARGE}. The default values are:
- 100% for CPU reservation
- 100% for Memory reservation
- 1000 MHz per CPU
| Name | Comments |
|---|---|
| lockUpdatesOnEdge | Default value is false. Serialize specific Edge operations related to DHCP and vnic configuration to avoid concurrency errors when too many configuration change requests arrive at the same time. |
| aggregatePublishing | Default value is true (enabled). Speed up configuration change publishing to the NSX Edge by aggregating over the configuration versions. |
| edgeVMHealthCheckIntervalInMin | Default value for time interval between NSX Edge VM's health check is 0, where NSX Manager manages the interval based on the number of NSX Edge VM's. A positive integer value overrides the default behavior. |
| healthCheckCommandTimeoutInMs | Default timeout value for health check command is 120000. |
| maxParallelVixCallsForHealthCheck | The maximum concurrent health check calls that can be made for NSX Edge VM's based on VIX communication channel is 25. |
| publishingTimeoutInMs | The timeout value to publish a configuration change on NSX Edge appliance. Default is 1200000 (20 minutes). |
| edgeVCpuReservationPercentage | Integer value [0-100], specifying the CPU reservation percentage which will be applied to the NSX Edge appliance. To disable this resource reservation, enter 0. |
| edgeMemoryReservationPercentage | integer value [0-100], specifying the memory reservation percentage which will be applied to the NSX Edge appliance. To disable this resource reservation, enter 0. |
| megaHertzPerVCpu | integer value specifying the megahertz per each vCPU (1000, 1500, 2000) |
Retrieve the NSX Edge tuning configuration.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Update the NSX Edge tuning configuration.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
truststore
Working With Certificates
NSX Edge supports self-signed certificates, certificates signed by a Certification Authority (CA), and certificates generated and signed by a CA.
Working With Certificates and Certificate Chains
Import a certificate or a certificate chain against a certificate signing request.
Working With Certificates on a Specific Scope
Retrieve all certificates on the specified scope.
Working With Self-Signed Certificates
Create a single certificate
You can create a certificate for a specific NSX Edge, or if you specify a scope of globalroot-0 you can create a global certificate in NSX Manager which is available to all NSX Edges.
Working With a Specific Certificate
Retrieve the certificate object specified by ID. If the ID specifies a chain, multiple certificate objects are retrieved.
Delete the specified certificate.
Working With Certificate Signing Requests
Create a certificate signing request (CSR).
Working With Self-Signed Certificate for CSR
Create a self-signed certificate for CSR.
Retrieve the specified certificate signing request (CSR).
Working With Certificate Signing Requests on a Specific Scope
Retrieve certificate signing requests (CSR) on the specified scope.
Working With Certificate Revocation Lists on a Specific Scope
Create a certificate revocation list (CRL) on the specified scope.
Working With CRL Certificates in a Specific Scope
Retrieve all certificates for the specified scope.
Working With a Specific CRL Certificate
Retrieve certificate object for the specified certificate revocation list (CRL).
Delete the specified certificate revocation list (CRL).
policy
Working With Service Composer
Service Composer helps you provision and assign network and security services to applications in a virtual infrastructure. You map these services to a security group, and the services are applied to the virtual machines in the security group.
Security Groups
You begin by creating a security group to define assets that you want to protect. Security groups may be static (including specific virtual machines) or dynamic where membership may be defined in one or more of the following ways:
- vCenter containers (clusters, port groups, or datacenters).
- Security tags, IPset, MACset, or even other security groups. For example, you may include a criteria to add all members tagged with the specified security tag (such as AntiVirus.virusFound) to the security group.
- Directory Groups (if NSX Manager is registered with Active Directory).
- Regular expressions such as virtual machines with name VM1.
Note that security group membership changes constantly. For example, a virtual machine tagged with the AntiVirus.virusFound tag is moved into the Quarantine security group. When the virus is cleaned and this tag is removed from the virtual machine, it again moves out of the Quarantine security group.
Security Policies
A security policy is a collection of the following service configurations.
| Service | Description | Applies to |
|---|---|---|
| Distributed Firewall rules category: firewall | Rules that define the traffic to be allowed to, from, or within the security group. | vNIC |
| Guest Introspection service category: endpoint | Third party solution provider services such as anti-virus or vulnerability management services. | virtual machines |
| Network Introspection services (NetX or Network Extensibility) category: traffic_steering | Services that monitor your network such as IPS. | virtual machines |
Applying Security Policies to Security Groups
You apply a security policy (say SP1) to a security group (say SG1). The services configured for SP1 are applied to all virtual machines that are members of SG1. If a virtual machine belongs to more than one security group, the services that are applied to the virtual machine depends on the precedence of the security policy mapped to the security groups. Service Composer profiles can be exported and imported as backups or for use in other environments. This approach to managing network and security services helps you with actionable and repeatable security policy management.
Service Composer Parameters
The following parameters are related to Service Composer, security policies, and security groups.
Common Parameters
- actionType - Defines the type of action belonging to a given executionOrderCategory
- executionOrderCategory - Category to which the action belongs to (endpoint, firewall or traffic_steering)
- isActive - In a security policy hierarchy, an action within a policy may or may not be active based on the precedence of the policy or usage of isActionEnforced flag in that hierarchy
- isActionEnforced - Enforces an action of a parent policy on its child policies for a given actionType and executionOrderCategory. Note that in a policy hierarchy, for a given actionType and executionOrderCategory, there can be only one action which can be marked as enforced.
- isEnabled - Indicates whether an action is enabled
- secondarySecurityGroup - Applicable for actions which need secondary security groups, say a source-destination firewall rule
- securityPolicy - Parent policy in an action
Output-only Parameters
- executionOrder - Defines the sequence in which actions belonging to an executionOrderCategory are executed. Note that this is not an input parameter and its value is implied by the index in the list.
Firewall Category Parameters
- action - Allow or block the traffic
- applications - Applications / application groups on which the rules are to be applied
- direction - Direction of traffic towards primary security group. Possible values: inbound, outbound, intra
- logged - Flag to enable logging of the traffic that is hit by this rule
- outsideSecondaryContainer - Flag to specify outside i.e. outside securitygroup-3
Endpoint Category Parameters
- serviceId - ID of the service (as registered with the service insertion module). If this tag is null, the functionality type (as defined in actionType tag) is not applied which will also result in blocking the actions (of given functionality type) that are inherited from the parent security policy. This is true if there is no action of enforce type.
- invalidServiceId - Flag to indicate that the service that was referenced in this rule is deleted, which make the rule ineffective (or deviate from the original intent that existed while configuring the rule). You must either modify this rule by adding correct Service or delete this rule.
- serviceName -Name of the service
- serviceProfile - Profile to be referenced in Endpoint rule.
- invalidServiceProfile - Flag to indicate that the service profile that was referenced in this rule is deleted, which makes the rule ineffective (or deviate from the original intent that existed while configuring the rule). You must either modify this rule by adding correct Service Profile or delete this rule.
The following parameters are deprecated:
- vendorTemplateId
- invalidVendorTemplateId
- vendorTemplateName
Traffic Steering/NetX Category Parameters
- redirect - Flag to indicate whether to redirect the traffic or not
- serviceProfile - Service profile for which redirection is being configured
- logged - Flag to enable logging of the traffic that is hit by this rule
Working With Security Policies
A security policy is a set of Endpoint, firewall, and network introspection services that can be applied to a security group.
See Working With Security Groups for more information about managing security groups.
Create a security policy.
When creating a security policy, a parent security policy can be specified if required. The security policy inherits services from the parent security policy. Security group bindings and actions can also be specified while creating the policy. Note that execution order of actions in a category is implied by their order in the list. The response of the call has Location header populated with the URI using which the created object can be fetched.
Ensure that:
- the required VMware built in services (such as Distributed Firewall and Endpoint) are installed. See NSX Installation Guide.
- the required partner services have been registered with NSX Manager.
- the required security groups have been created.
Working With a Specific Security Policy
Retrieve security policy information. To view all security policies, specify all as the security policy ID.
Edit a security policy.
To update a security policy, you must first fetch it. Then edit the received XML and pass it back as the input. The specified configuration replaces the current configuration.
Security group mappings provided in the PUT call replaces the security group mappings for the security policy. To remove all mappings, delete the securityGroupBindings parameter.
You can add or update actions for the security policy by editing the actionsByCategory parameter. To remove all actions (belonging to all categories), delete the actionsByCategory parameter. To remove actions belonging to a specific category, delete the block for that category.
Delete a security policy.
When you delete a security policy, its child security policies and all the actions in it are deleted as well.
Working With Security Group Bindings
Apply the specified security policy to the specified security group.
Working With Security Actions on a Security Policy
Retrieve all security actions applicable on a security policy.
This list includes security actions from associated parent security policies, if any. Security actions per Execution Order Category are sorted based on the weight of security actions in descending order.
Working with Service Composer Policy Precedence
Retrieve the highest precedence (or weight) of the Service Composer security policies.
The response body contains only the maximum precedence.
Example:
6300
Working With Service Composer Status
Retrieve the consolidated status of Service Composer.
The possible return of value for status are: in_sync, in_progress, out_of_sync, and pending.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Working With All Service Composer Alarms
Retrieve all system alarms that are raised at Service Composer level and policy level.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Working With Service Composer Firewall Applied To Setting
You can set the applied to setting for all firewall rules created though Service Composer to either Distributed Firewall or Policy's Security Groups. By default, the applied to is set to Distributed Firewall. When Service Composer firewall rules have an applied to setting of distributed firewall, the rules are applied to all clusters on which distributed firewall is installed. If the firewall rules are set to apply to the policy's security groups, you have more granular control over the firewall rules, but may need multiple security policies or firewall rules to get the desired result.
Applied To Values for Service Composer Firewall Rules
| Value | Description |
|---|---|
| dfw_only | Firewall rules are applied to all clusters on which Distributed Firewall is installed. |
| policy_security_group | Firewall rules are applied to security groups on which the security policy is applied. |
Retrieve the Service Composer firewall applied to setting.
Update the Service Composer firewall applied to setting.
Working With Service Composer Configuration Import and Export
Import a security policy configuration
You can create multiple security policies and parent-child hierarchies using the data fetched through export. All objects including security policies, security groups and security actions are created on a global scope.
The policy that is being imported needs to be included in the request body.
If a suffix is specified, it is added after the names of the security policy, security action, and security group objects in the exported XML. The suffix can thus be used to differentiate locally created objects from imported ones.
The location of the newly created security policy objects (multiple locations are separated by commas) is populated in the Location header of the response.
Export a Service Composer configuration (along with the security groups to which the security policies are mapped). You can save the response to a file. The saved configuration can be used as a backup for situations where you may accidentally delete a policy configuration, or it can be exported for use in another NSX Manager environment.
If a prefix is specified, it is added before the names of the security policy, security action, and security group objects in the exported XML. The prefix can thus be used to indicate the remote source from where the hierarchy was exported.
Working With Virtual Machines with Security Actions Applied
Retrieve all VirtualMachine objects on which security action of a given category and attribute has been applied.
Working With Security Actions Applicable on a Security Group
Retrieve all security actions applicable on a security group for all ExecutionOrderCategories. The list is sorted based on the weight of security actions in descending order. The isActive tag indicates if a securityaction will be applied (by the enforcement engine) on the security group.
Working With Security Actions Applicable on a Virtual Machine
You can retrieve the security actions applicable on a virtual machine for all ExecutionOrderCategories. The list of SecurityActions per ExecutionOrderCategory is sorted based on the weight of security actions in descending order. The isActive tag indicates whether a security action will be applied (by the enforcement engine) on the virtual machine.
Working With Service Composer Firewall
If Service Composer goes out of sync with Distributed Firewall, you must re-synchronize Service Composer rules with firewall rules. If Service Composer stays out of sync, firewall configuration may not stay enforced as expected.
This GET method can perform the following functions, depending on the request body provided. Note: Some REST clients do not allow you to specify a request body with a GET request.
Check if Service Composer firewall and Distributed Firewall are in sync
Note: Deprecated. Use GET /2.0/services/policy/securitypolicy/status instead.
- If they are in sync, the response body does not contain any data.
- If they are out of sync, the response body contains the unix timestamp representing the time since when Service Composer firewall is out of sync.
<keyValues>
<keyValue>
<key>getServiceComposerFirewallOutOfSyncTimestamp</key>
</keyValue>
</keyValues>
Synchronize Service Composer firewall with Distributed Firewall
<keyValues>
<keyValue>
<key>forceSync</key>
</keyValue>
</keyValues>
Retrieve the state of the auto save draft property in Service Composer
Retrieve the state of the auto save draft property in Service Composer. Response is true or false.
<keyValues>
<keyValue>
<key>getAutoSaveDraft</key>
</keyValue>
</keyValues>
Change the state of the auto save draft property in Service Composer
Note: Deprecated.
Change the state of the auto save draft property in Service Composer. Provide request body value of true or false.
<keyValues>
<keyValue>
<key>autoSaveDraft</key>
<value>false</value>
</keyValue>
</keyValues>
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated and some functions deprecated. Changing auto save draft with the autoSaveDraft parameter is deprecated, and will be removed in a future release. The default setting of autoSaveDraft is changed from true to false. Method to check if Service Composer and Distributed Firewall are in sync is deprecated, and will be removed in a future release. Use GET /2.0/services/policy/securitypolicy/status instead. |
Working With Security Policies Mapped to a Security Group
Retrieve security policies mapped to a security group.
The list is sorted based on the precedence of security policy precedence in descending order. The security policy with the highest precedence (highest numeric value) is the first entry (index = 0) in the list.
snmp
Working With SNMP
NSX Manager receives events from other NSX components, including NSX Edge, network fabric, and hypervisors.
You can configure NSX Manager to forward SNMP traps to an SNMP Manager.
Working With SNMP Status Settings
You can configure settings for SNMP on the NSX Manager.
| Parameter | Description |
|---|---|
| serviceStatus | Boolean. Set to true to enable SNMP. There must be at least one SNMP manager configured to enable SNMP. |
| groupNotification | Boolean. Set to true to group similar SNMP notifications. This reduces the number of notifications being sent out, which can improve SNMP manager performance when there is a high volume of SNMP notifications. |
Retrieve SNMP status settings.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Update SNMP status settings.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Working With SNMP Managers
Retrieve information about SNMP managers.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Add an SNMP manager.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Working With a Specific SNMP Manager
Retrieve information about the specified SNMP manager.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Update an SNMP manager configuration.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Delete an SNMP manager configuration.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Working With SNMP Traps
Retrieve information about SNMP traps.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Working With a Specific SNMP Trap
Retrieve information about the specified SNMP trap.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Update the specified SNMP trap.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
nsxCli
Working With the Central CLI
The central command-line interface (central CLI) commands are run from the NSX Manager command line, and retrieve information from the NSX Manager and other devices. These commands can also be executed in the API.
You can insert any valid central CLI command as the command parameter. For a complete list of the central CLI commands executable through the API, please see the central CLI chapter of the NSX Command Line Interface Reference.
You must set the Accept header to text/plain.
inventoryStatus
Working with Logical Inventory Details
Communication Status of a Specific Host
This feature allows the user to check the connection status between the NSX Manager and hosts. A hash map is used to hold all hosts' connection status. It keeps track of the latest heartbeat from each host. When querying a host’s connection status, NSX Manager will get the latest heartbeat information to compare the last heartbeat time and current time. If the duration is longer than a threshold, it returns DOWN, otherwise it returns UP. If no last heartbeat information is found and this host has not been prepared or the netcpa version on this host is lower than 6.2.0, it will return NOT_AVAILABLE. But if no last heartbeat information is found and the host has been prepared with netcpa version no less than 6.2.0, it will return DOWN. When a host has been unprepared, its heartbeat information will be removed from the NSX Manager memory.
Retrieve the status of the specified host.
History:
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. Introduced hostToControllerConnectionErrors array. Deprecated fullSyncCount parameter. Parameter is still present, but always has value of -1. |
Communication Status of a List of Hosts
Retrieve the status of a list of hosts.
| Release | Modification |
|---|---|
| 6.2.3 | Method updated. Introduced hostToControllerConnectionErrors array. Deprecated fullSyncCount parameter. Parameter is still present, but always has value of -1. |
Detailed Information about Logical Switches
Retrieve detailed information about logical switches shown in the UI. This includes hosts and VM information for the logical switches.
Detailed Information about Logical Switches in a Specific Transport Zone
Retrieve detailed information about logical switches shown in the UI for the specified transport zone. This includes hosts and VM information for the logical switches.
hardwareGateways
Working With Hardware Gateways
Install a hardware gateway.
bfdEnabled is true by default.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Retrieve information about all hardware gateways.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Working With a Specific Hardware Gateway
Retrieve information about the specified hardware gateway.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Update the specified hardware gateway.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Delete the specified hardware gateway.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Working With Switches on a Specific Hardware Gateway
Retrieve information about switches on the specified hardware gateway.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Working With a Specific Switch on a Specific Hardware Gateway
Working With Ports on a Specific Switch on a Specific Hardware Gateway
Retrieve information about the hardware gateway switch ports for the specified switch and hardware gateway.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Working With the Hardware Gateway Replication Cluster
Update the hardware gateway replication cluster.
Add or remove hosts on a replication cluster.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Retrieve information about the hardware gateway replication cluster.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
hardwareGateway
Working With Hardware Gateway Bindings and BFD
Working With Hardware Gateway Bindings
Create a hardware gateway binding.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Retrieve information about hardware gateway bindings.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Working With a Specific Hardware Gateway Binding
Retrieve information about the specified hardware gateway binding.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Update the specified hardware gateway binding.
You can update the binding parameters. This API will fail if:
- the specified hardwareGatewayId does not exist.
- the specified logical switch (virtualWire) is not present or there is a software gateway on the binding.
- the new binding value is a duplicate of an existing binding.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Delete the specified hardware gateway binding.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Working With Hardware Gateway Binding Statistics
Retrieve statistics for the specified hardware gateway binding.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Working With Hardware Gateway Binding Objects
Manage hardware gateway binding objects.
Use this API to attach, detach, and update multiple bindings in a single API call. This API accepts three lists for add, update, and delete. Each list accepts a hardwareGatewayManageBindingsItem with a full description of the new binding with its objectID. This API handles a maximum of 100 HardwareGatewayManageBindingsItem objects for each of the Add/Update/Delete lists.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Working With Hardware Gateway BFD (Bidirectional Forwarding Detection)
Working With Hardware Gateway BFD Configuration
Update global hardware gateway BFD configuration.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Retrieve global hardware gateway BFD configuration.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |
Working With Hardware Gateway BFD Tunnel Status
Retrieve hardware gateway BFD tunnel status for all tunnel endpoints, including hosts and hardware gateways.
Method history:
| Release | Modification |
|---|---|
| 6.2.3 | Method introduced. |