NSX API Guide 6.4

NSX API Guide

Update 13

Modified JULY 2020

VMware NSX Data Center for vSphere 6.4

Page 1

NSX API Guide Version: 6.4 Page 2

Table of Contents

14Introduction

18Endpoints

18Working With vSphere Distributed Switches

. . . . . . . . . . . . . . . . . . . . . . . . . . . 19Working With vSphere Distributed Switches in a Datacenter

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Working With a Specific vSphere Distributed Switch

. . . . . . . . . . . . . . . . . 21Working With Latency Configuration of a Specific vSphere Distributed Switch

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Working With Latency Configuration of a Specific Host

25Working With Segment ID Pools and Multicast Ranges

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Working With Segment ID Pools

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Working With a Specific Segment ID Pool

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Working With Multicast Address Ranges

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Working With a Specific Multicast Address Range

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Working With the VXLAN Port Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Update the VXLAN Port Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30VXLAN Port Configuration Update Status

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Resume VXLAN Port Configuration Update

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Working With Allocated Resources

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Resolving Missing VXLAN VMKernel Adapters

33Working With Controller Disconnected Operation (CDO) Mode

35Working With Transport Zones

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Working With a Specific Transport Zone

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Working With Transport Zone Attributes

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Working With Transport Zone CDO Mode

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Testing Multicast Group Connectivity

44Working With Logical Switches in a Specific Transport Zone

45Working With Traceflow

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Working With a Specific Traceflow

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Traceflow Observations

50Working With Logical Switches in All Transport Zones

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Working Virtual Machine Connections to Logical Switches

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Working With a Specific Logical Switch

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Resolving Missing Port Groups for a Logical Switch

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Testing Host Connectivity

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Testing Point-to-Point Connectivity

. . . . . . . . . . . . . . . . . . . . 56Working With Hardware Gateway Bindings for a Specific Logical Switch

. . . . . . . . . . . . . . . 57Working With Connections Between Hardware Gateways and Logical Switches

59Working With IP Discovery and MAC Learning for Logical Switches

61Working With NSX Controllers

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Working With Controller Upgrade Availability

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Working With of Controller Job Status

NSX API Guide Version: 6.4 Page 3

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Working With a Specific Controller

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Working With NSX Controller System Statistics

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Working With Controller Tech Support Logs

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Working With Controller Syslog Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Working With Controller Cluster Snapshots

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Working With the NSX Controller Cluster Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Working With Controller Cluster NTP Settings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Working With Controller Cluster DNS Settings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Working With Controller Cluster Syslog Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Working With Controller Cluster Upgrade

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Working With the NSX Controller Password

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Working With Controller Synchronization

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Working with Controller Synchronization Status

75Working With Host Health Status Using BFD

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Working with overall information about host health status

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Working with health status for a specific host

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Working with tunnel connections for a specific host

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Working with remote host status

81Working With BFD Global Configuration

83Working With pNIC Configuration Information

85Working With Services Grouping Objects

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Retrieve Services from a Specific Scope

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Create a Service on a Specific Scope

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Working With a Specified Service

88Working With Service Groups Grouping Objects

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Creating Service Groups on a Specific Scope

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Working With Service Groups on a Specific Scope

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Working With a Specific Service Group

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Working With a Specific Service Group Member

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Working With Service Group Members on a Specific Scope

91Working With IP Pool Grouping Objects

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Working With IP Pools on a Specific Scope

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Working With a Specific IP Pool

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Working With IP Pool Address Allocations

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Working With Specific IPs Allocated to an IP Pool

96Working With Licensing

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Working With Licensing Capacity

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Working With Licensing Status

98Working With Security Tags

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Managing Security Tags

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Delete a Security Tag

. . . . . . . . . . . . . . . . . . . . . . . . . . 100Working With Virtual Machines on a Specific Security Tag

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Manage a Security Tag on a Virtual Machine

. . . . . . . . . . . . . . . . . . . . . . 102Working With Virtual Machine Details for a Specific Security Tag

NSX API Guide Version: 6.4 Page 4

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Working With Security Tags on a Specific Virtual Machine

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Working With Security Tags Unique ID Selection Criteria

106Working With NSX Manager SSO Registration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Working With SSO Configuration Status

107Working With User Management

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Manage Users on NSX Manager

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Working With User Account State

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Manage NSX Roles for Users

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Working With NSX Manager Role Assignment

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Working With Available NSX Manager Roles

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Working With Scoping Objects

111Working with API Authentication

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Working with Basic Authentication

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Working with API Tokens

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Working With API Token Expiration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Working With Token Invalidation

115Working with API Authentication

116Working With Security Group Grouping Objects

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Creating New Security Groups With Members

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Creating New Security Groups Without Members

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Updating a Specific Security Group Including Membership

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Working With a Specific Security Group

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Working With Members of a Specific Security Group

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Working With Virtual Machines in a Security Group

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Working With IP Addresses in a Security Group

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Working With MAC Addresses in a Security Group

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Working With vNICs in a Security Group

. . . . . . . . . . . . . . . . . . . . . . . . . . . 123Working With Virtual Machine Security Group Membership

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Working With IP Address in a Security Group

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Working With Internal Security Groups

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Working With Security Groups on a Specific Scope

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Working With Security Group Member Types

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Working With a Specific Security Group Member Type

128Working With IP Set Grouping Objects

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128Working With IP Sets on a Specific Scope

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Creating New IP Sets

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Working With a Specific IP Set

131Configuring NSX Manager with vCenter Server

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Connection Status for vCenter Server

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Working with vCenter Server Connection

133Configuring Index Maintainance

135Configuring the High CPU Usage Reporting Tool

137Working with the CPU Usage Monitoring Tool

NSX API Guide Version: 6.4 Page 5

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Working With CPU Usage Indicator

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Working With CPU Usage Details

139Working With Universal Sync Configuration in Cross-vCenter NSX

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Working With Universal Sync Configuration Roles

. . . . . . . . . . . . . . . . . . . . . . . . . . 139Working With Universal Sync Configuration of NSX Managers

. . . . . . . . . . . . . . . . . . . . . . . . . . . 140Universal Sync Configuration of a Specific NSX Manager

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141NSX Manager Synchronization

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Working With Universal Sync Entities

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Working With Universal Sync Status

142Working With the Appliance Manager

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142Global Information for NSX Manager

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142Summary Information for NSX Manager

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143Component Information for NSX Manager

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Reboot NSX Manager

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145NSX Manager Appliance CPU Information

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146NSX Manager Appliance CPU Details

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146NSX Manager Appliance Uptime Information

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147NSX Manager Appliance Memory Information

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147NSX Manager Appliance Storage Information

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147NSX Manager Appliance Network Settings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149Working With DNS Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149Working With Security Settings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150Working With TLS Settings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151Working With Time Settings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152Working With NTP Settings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152Configure System Locale

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Working With Syslog Server

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154Working With Multiple Syslog Servers

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155Working With Components

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Working With a Specific Component

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Working With Component Dependencies

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158Working With Component Dependents

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158Working With Component Status

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Toggle Component Status

. . . . . . . . . . . . . . . . . . . . . . . . . . 159Working With the Appliance Management Web Application

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159NSX Manager Appliance Backup Settings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162NSX Manager Appliance Backup FTP Settings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162NSX Manager Appliance Backup Exclusion Settings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163NSX Manager Appliance Backup Schedule Settings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163NSX Manager Appliance On-Demand Backup

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Working With NSX Manager Appliance Backup Files

. . . . . . . . . . . . . . . . . . . . . . . . . . 164Restoring Data from an NSX Manager Appliance Backup File

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165Working With Tech Support Logs by Component

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165Working With Tech Support Log Files

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165Working With Support Notifications

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165Acknowledge Notifications

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Upgrading NSX Manager Appliance

NSX API Guide Version: 6.4 Page 6

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Upload an NSX Manager Upgrade Bundle

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Upload an NSX Manager Upgrade Bundle from URL

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167Prepare for NSX Manager Upgrade

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168Start the NSX Manager Upgrade

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169NSX Manager Upgrade Status

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Working With Certificates on the NSX Manager Appliance

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Working With Keystore Files

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170NSX Manager Certificate Manager

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Working With Certificate Signing Requests

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Working With Certificate Chains

173Working with NSX Manager Debug APIs

174Working With NSX Manager System Events

176Working with Host Event Notifications

177Working With DHCP Starv WhiteList

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Working With a Specific DHCP Starv Whitelist Entry

. . . . . . . . . . . . . . . . . . . . . . . . . . 179Working With DHCP Starv Whitelist Entries of a Specific VM

181Working With NSX Manager Audit Logs

183Working With the VMware Customer Experience Improvement Program

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Working With the VMware CEIP Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Working With Proxy Setting for VMware CEIP

186Working With Network Fabric Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . 186Working With Network Virtualization Components and VXLAN

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Resolving Host Preparation Issues

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Working With Network Fabric Features

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Working With Network Fabric Status

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Working With Network Fabric Status of Child Resources

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Working With Status of Resources by Criterion

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195Working With Locale ID Configuration For Clusters

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196Working With Locale ID Configuration for Hosts

197Working With Security Fabric and Security Services

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198Working With a Specified Service

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199Working With Service Dependencies

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199Working With Installed Services on a Cluster

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201Working With a Specific Service on a Cluster

202Working With Data Collection for Activity Monitoring

. . . . . . . . . . . . . . . . . . . . . . . . . . . 202Working With Data Collection on a Specific Virtual Machine

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202Override Data Collection

. . . . . . . . . . . . . . . . . . . . . . 203Retrieve Data Collection Configuration for a Specific Virtual Machine

205Working With Activity Monitoring

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Working With Aggregated User Activity

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207Working With User Details

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209Working With a Specific User

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209Working With Applications

NSX API Guide Version: 6.4 Page 7

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210Working With a Specific Application

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210Working With Discovered Hosts

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210Working With a Specific Discovered Host

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210Working With Desktop Pools

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Working With a Specific Desktop Pool

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Working With Virtual Machines

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Working With a Specific Virtual Machine

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Working With LDAP Directory Groups

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Working With a Specific LDAP Directory Group

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Working With a Specific User's Active Directory Groups

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Working With Security Groups

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Working With a Specific Security Group

214Working With Domains

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214Registering Domains

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216Retrieve LDAP Domains

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216Retrieve Security Groups of a Specific Domain

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217Delete a Specific Domain

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217Working with Root Distinguished Names

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Delete DomainRootDN

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Create LDAP Server

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Query LDAP Servers for a Domain

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219Update AD Sync Settings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220Start LDAP Full Sync

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220Start LDAP Delta Sync

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220Delete LDAP Server

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220EventLog Server

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221Working With EventLog Servers for a Domain

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221Delete EventLog Server

222Working With Mapping Lists

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222Working With User to IP Mappings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222Working With Host to IP Mappings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222Working With IP to User Mappings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223Working With User Domain Groups

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224Working With a Specific Static User Mapping

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224Working With Static User Mappings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 224Working With Static User IP Mappings for a Specific User

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225Working With Static User IP Mappings for a Specific IP

226Working With Activity Monitoring Syslog Support

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226Enable Syslog Support

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226Disable Syslog Support

227Working With Solution Integrations

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227Working With Agents on a Specific Host

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228Working With a Specific Agent

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229Working With Agents on a Specific Deployment

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230Working With Conflicting Agencies

NSX API Guide Version: 6.4 Page 8

232Working With MAC Address Set Grouping Objects

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232Working With a Specific MAC Address Set

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233Working With MAC Address Sets on a Specific Scope

236Working With ESX Agent Manager

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236Working With EAM Status

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236Working With a Specific EAM Agent

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237Working With EAM Agent Runtime Information

238Working With Alarms

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241Working With a Specific System Alarm

243Working With Alarms from a Specific Source

246Working With System Scale (Capacity Parameter) Dashboard

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246System Scale (Capacity Parameter) Dashboard Report

. . . . . . . . . . . . . . . . . . . . . . . . . . . 247System Scale (Capacity Parameter) Dashboard Threshold

249Working With Custom Dashboard Widget

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259Working With a Specific Widget

263Working With the Task Framework

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263Working With a Specific Job Instance

264

Working With Guest Introspection and Third-party Endpoint Protection (Anti-virus)

Solutions

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 264Register a Vendor and Solution with Guest Introspection

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 265Working With Registered Guest Introspection Vendors

. . . . . . . . . . . . . . . . 265Working With Guest Introspection Vendors and Endpoint Protection Solutions

. . . . . . . . . . . . . . . . . . . . . . . . . 266Information About Registered Endpoint Protection Solutions

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 266Endpoint Protection Solution Registration Information

. . . . . . . . . . . . . . . . . . . . . . . . . . 267IP Address and Port For an Endpoint Protection Solution

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268Activate an Endpoint Protection Solution

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269Activated Security Virtual Machines

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269Activate a Registered Endpoint Protection Solution

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270Working With Solution Activation Status

. . . . . . . . . . . . . . . . . . . . . . . . . . . 271Working With Guest Introspection SVM Health Thresholds

273Working With Distributed Firewall

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273Default Firewall Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273Working with Distributed Firewall Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278Working With Layer 3 Sections in Distributed Firewall

. . . . . . . . . . . . . . . . . . . . . . . . . 282Working With a Specific Layer 3 Distributed Firewall Section

. . . . . . . . . . . . . . . . . . . . . . . . 288Working With Distributed Firewall Rules in a Layer 3 Section

. . . . . . . . . . . . . . . . . . . . . . . . 289Working With a Specific Rule in a Specific Layer 3 Section

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291Working With Layer 2 Sections in Distributed Firewall

. . . . . . . . . . . . . . . . . . . . . . . . . 293Working With a Specific Layer 2 Distributed Firewall Section

. . . . . . . . . . . . . . . . . . . . . . . . 296Working With Distributed Firewall Rules in a Layer 2 Section

. . . . . . . . . . . . . . . . . . . . . . . . 298Working With a Specific Rule in a Specific Layer 2 Section

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299Layer 3 Redirect Sections and Rules

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300Layer 3 Redirect Section

. . . . . . . . . . . . . . . . . . . . . . . . 301Working With Layer 3 Redirect Rules for a Specific Section

NSX API Guide Version: 6.4 Page 9

. . . . . . . . . . . . . . . . . . . 302Working With a Specific Layer 3 Redirect Rule for a Specific Section

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303Service Insertion Profiles and Layer 3 Redirect Rules

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303Enable Distributed Firewall After Upgrade

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304Working With Distributed Firewall Status

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306Working With a Specific Layer 3 Section Status

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306Working With a Specific Layer 2 Section Status

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306Import and Export Firewall Configurations

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307Working With a Specific Saved Firewall Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309Export a Firewall Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309Import a Firewall Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310Working With Distributed Firewall Session Timers

. . . . . . . . . . . . . . . . . . . 312Working With a Specific Distributed Firewall Session Timer Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314Working With Distributed Firewall Event Thresholds

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315Working With Distributed Firewall Thresholds

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317Working With Distributed Firewall Rule Hit Counts

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318Working with Rule Hit Counts for a Specific Rule

. . . . . . . . . . . . . . . . . . . . . . . . . . . 318Working With the Distributed Firewall Global Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . 320Working With the Distributed Firewall Universal Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320Synchronize Firewall

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320Enable Firewall

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321Working With IPFIX

. . . . . . . . . . . . . . . . . . . . . . . . . . . 322Distributed Firewall State Realization for Grouping Objects

324Working With SpoofGuard

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324Working With SpoofGuard Policies

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324Working With a Specific SpoofGuard Policy

. . . . . . . . . . . . . . . . . . . . . . 325Perform SpoofGuard Operations on IP Addresses in a Specific Policy

327Working With Flow Monitoring

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327Working With Flow Monitoring Statistics

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328Working With Flow Monitoring Meta-Data

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329Working With Flow Monitoring Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331Working With Flow Configuration for a Specific Context

332Exclude Virtual Machines from Firewall Protection

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333Working With the Exclusion List

335Working With NSX Edge

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346Working With a Specific NSX Edge

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352Working With DNS Client Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352Working With AESNI

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352Working With Core Dumps

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353Working With FIPS on NSX Edge

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353Working With NSX Edge Logs

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353Working With NSX Edge Summary

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360Working With NSX Edge Status

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362Working With NSX Edge Health Summary

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365Working With NSX Edge Tech Support Logs

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366Working With NSX Edge CLI Settings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366Working With NSX Edge Remote Access

NSX API Guide Version: 6.4 Page 10

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 367Working With NSX Edge System Control Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370Working With NSX Edge Firewall Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373Working With Firewall Rules

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374Working With a Specific Firewall Rule

. . . . . . . . . . . . . . . . . . . . . . . . . . 376Working With the NSX Edge Global Firewall Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377Working With the Default Firewall Policy for an Edge

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377Working With Statistics for a Specific Firewall Rule

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378Working With NAT Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382Working With NAT Rules

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383Working With a Specific NAT Rule

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384Working With the NSX Edge Routing Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394Working With the NSX Edge Global Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395Working With Static and Default Routes

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396Working with Static Routes for a Specific Network

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399Working With OSPF Routing for NSX Edge

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402Working With BGP Routes for NSX Edge

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405Working With Multicast Routing

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409Working With GRE Tunnels

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414Working With a Specific GRE Tunnel

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416Working With Layer 2 Bridging

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417Working With NSX Edge Load Balancer

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426Working With Application Profiles

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427Working With a Specific Application Profile

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429Working With Application Rules

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430Working With a Specific Application Rule

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431Working With Load Balancer Monitors

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432Working With a Specific Load Balancer Monitor

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433Working With Virtual Servers

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434Working With a Specific Virtual Server

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435Working With Server Pools

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439Working With a Specific Server Pool

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440Working With a Specific Load Balancer Member

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441Working With Load Balancer Statistics

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445Working With Load Balancer Acceleration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445Working With NSX Edge DNS Server Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446Get DNS server statistics

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447Configure DHCP for NSX Edge

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451Working With DHCP IP Pools

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452Working With a Specific DHCP IP Pool

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453Working With DHCP Static Bindings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455Working With a Specific DHCP Static Binding

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456Working With DHCP Relays

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458Working With DHCP Leases

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458Working With NSX Edge High Availability

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459Working With Remote Syslog Server on NSX Edge

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460Working With SSL VPN

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462Working With SSL VPN Server

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463Working With Private Networks

NSX API Guide Version: 6.4 Page 11

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464Working With a Specific Private Network

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465Working With IP Pools for SSL VPN

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466Working With a Specific IP Pool for SSL VPN

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467Working With Network Extension Client Parameters

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468Working With SSL VPN Client Installation Packages

. . . . . . . . . . . . . . . . . . . . . . . 469Working With a Specific SSL VPN Client Installation Package

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471Working With Image Files for SSL VPN

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471Working With Portal Users

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473Working With a Specific Portal User

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473Working With Authentication Settings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475Working With the RSA Config File

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475SSL VPN Advanced Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476Working With Logon and Logoff Scripts for SSL VPN

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477Working With Uploaded Script Files

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478Uploading Script Files for SSL VPN

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478Working With SSL VPN Users

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479Working With Active Client Sessions

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479Working With a Specific Active Client Session

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 480Working With NSX Edge Firewall Dashboard Statistics

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480Working With SSL VPN Dashboard Statistics

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481Working With Tunnel Traffic Dashboard Statistics

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481Working With Interface Dashboard Statistics

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482Working With Interface Statistics

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482Working With Uplink Interface Statistics

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483Working With Internal Interface Statistics

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484Working With L2 VPN Over SSL

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489Working With L2 VPN Over SSL Statistics

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490Working with L2 VPN Over IPSec

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492Working With L2 VPN Tunnels

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493Working With a Specific L2 VPN Tunnel

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495Working With Peer Codes for L2 VPN over IPSec

. . . . . . . . . . . . . . . . . . . . . . . . . 496Working With Global Configuration for L2 VPN Over IPSec

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497Working With IPSec VPN

. . . . . . . . . . . . . . . . . . . . . . . . . . 505Downloading IPSec VPN and BGP Neighbor Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507Working With IPSec VPN Statistics

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510Automatic Configuration of Firewall Rules

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511Working With NSX Edge Appliance Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . 515Working With NSX Edge Appliance Configuration by Index

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516Working With Edge Services Gateway Interfaces

. . . . . . . . . . . . . . . . . . . . . . . . . . 518Working With a Specific Edge Services Gateway Interface

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519Creating a Sub-Interface of a Backing Type

. . . . . . . . . . . . . . . . . . . . . . . . . . 520Working With a Specific Sub-Interface of a Backing Type

. . . . . . . . . . . . . . . . . . . . . . . . . . . 522Working With Logical Router HA (Management) Interface

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523Working With Logical Router Interfaces

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524Working With a Specific Logical Router Interface

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525Configuring Edge Services in Async Mode

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525Working With a Specific Edge Job Status

527Working With NSX Edge Configuration Publishing

NSX API Guide Version: 6.4 Page 12

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527Working With NSX Edge Tuning Configuration

529Working With Certificates

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529Working With Certificates and Certificate Chains

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529Working With Certificate Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530Working With Certificates on a Specific Scope

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530Working With Self-Signed Certificates

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531Working With a Specific Certificate

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531Working With Certificate Signing Requests

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532Working With Self-Signed Certificate for CSR

. . . . . . . . . . . . . . . . . . . . . . . . . 533Working With Certificate Signing Requests on a Specific Scope

. . . . . . . . . . . . . . . . . . . . . . . . . 533Working With Certificate Revocation Lists on a Specific Scope

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533Working With CRL Certificates in a Specific Scope

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534Working With a Specific CRL Certificate

535Working With Service Composer

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536Working With Security Policies

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538Working With all Security Policies

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542Working With a Specific Security Policy

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546Working With Security Group Bindings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546Working With Security Actions on a Security Policy

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547Working with Service Composer Policy Precedence

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547Working With Service Composer Status

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547Working With All Service Composer Alarms

. . . . . . . . . . . . . . . . . . . . . . . . . 549Working With Service Composer Firewall Applied To Setting

. . . . . . . . . . . . . . . . . . . . . . . 549Working With Service Composer Configuration Import and Export

. . . . . . . . . . . . . . . . . . . . . . . . . . 550Working With Virtual Machines with Security Actions Applied

. . . . . . . . . . . . . . . . . . . . . . . . . 551Working With Security Actions Applicable on a Security Group

. . . . . . . . . . . . . . . . . . . . . . . . . 556Working With Security Actions Applicable on a Virtual Machine

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556Working With Service Composer Firewall

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557Working With Service Composer Firewall Information

. . . . . . . . . . . . . . . . . . . . . . . . . . . 558Working With Security Policies Mapped to a Security Group

561Working With SNMP

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561Working With SNMP Status Settings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562Working With SNMP Managers

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563Working With a Specific SNMP Manager

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564Working With SNMP Traps

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565Working With a Specific SNMP Trap

567Working With Translation of Virtual Machines to IP Addresses

568Working With Support Bundle

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569Status of the Technical Support Bundle

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571Download Support Bundle

572Working With the Central CLI

573Working with Logical Inventory Details

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573Communication Status of a Specific Host

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573Communication Status of a List of Hosts

NSX API Guide Version: 6.4 Page 13

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574Detailed Information about Logical Switches

. . . . . . . . . . . . . . . . . . . . 577Detailed Information about Logical Switches in a Specific Transport Zone

580Working With Hardware Gateways

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581Working With a Specific Hardware Gateway

. . . . . . . . . . . . . . . . . . . . . . . . . . . 583Working With Switches on a Specific Hardware Gateway

. . . . . . . . . . . . . . . . . . . . . . 583Working With a Specific Switch on a Specific Hardware Gateway

. . . . . . . . . . . . . . . . . 583Working With Ports on a Specific Switch on a Specific Hardware Gateway

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 584Working With All Hardware Gateway Replication Clusters

. . . . . . . . . . . . . . . . . . . . . . . . . 585Working With a Specific Hardware Gateway Replication Cluster

589Working With Hardware Gateway Bindings and BFD

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589Working With Hardware Gateway Bindings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590Working With a Specific Hardware Gateway Binding

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591Working With Hardware Gateway Binding Statistics

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591Working With Hardware Gateway Binding Objects

. . . . . . . . . . . . . . . . . . 592Working With Hardware Gateway BFD (Bidirectional Forwarding Detection)

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593Working With Hardware Gateway BFD Configuration

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593Working With Hardware Gateway BFD Tunnel Status

596Appendix

NSX API Guide Version: 6.4 Page 14

Introduction

This manual, the NSX API Guide, describes how to install, configure, monitor, and maintain the VMware NSX® Data

Center for vSphere® system by using REST API requests.

Important: NSX for vSphere is now known as NSX Data Center for vSphere.

Intended Audience

This manual is intended for anyone who wants to use the REST API to programmatically control an NSX Data Center

for vSphere environment. The information in this manual is written for experienced developers who are familiar with

virtual machine technology, virtualized datacenter operations, and REST APIs. This manual also assumes familiarity

with NSX Data Center for vSphere.

VMware Technical Publications Glossary

VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For definitions of terms as

they are used in VMware technical documentation go to http://www.vmware.com/support/pubs.

Technical Documentation and Product Updates

You can find the most up-to-date technical documentation on the VMware Web site at:

http://www.vmware.com/support/.

The VMware Web site also provides the latest product updates.

If you have comments about this documentation, submit your feedback to: <[email protected]>.

Using the NSX REST API

To use the NSX REST API, you must configure a REST client, verify the required ports are open between your REST

client and the NSX Manager, and understand the general RESTful workflow.

Ports Required for the NSX REST API

The NSX Manager requires port 443/TCP for REST API requests.

Configuring REST Clients for the NSX REST API

Some common REST clients include Postman, RESTClient (a Firefox add-on), and curl (a command-line tool). The

details of REST client configuration will vary from client to client, but this general information should help you configure

your REST client correctly.

• The NSX REST API can use basic authentication or JSON Web Token authentication.

You can authenticate using basic authentication or JSON Web Tokens. See "Working with API Tokens" for

information on creating and using JSON Web Tokens. You must configure your REST client to send the NSX

Manager authentication credentials. See the documentation for your REST client for details.

• You must use https to send API requests to the NSX Manager.

You might need to import the certificate from the NSX Manager to your REST client to allow it to connect to the NSX

Manager.

• When you submit an API request with a request body, you must include the appropriate Content-Type

header.

Starting in NSX 6.4, both XML and JSON are supported. This guide documents XML examples. Set the

Content-Type header to application/xml or application/json as needed.

Some requests require additional headers, for example, firewall configuration changes require the If-Match header.

This is noted on each method description.

• To ensure you always receive the correct response bodies, set the Accept header

Starting in NSX 6.4, both XML and JSON are supported. This guide documents XML examples. Set the Accept

header to application/xml or application/json as needed.

NSX API Guide Version: 6.4 Page 15

• 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.

NSX API Guide Version: 6.4 Page 16

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.

NSX API Guide Version: 6.4 Page 17

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.

NSX API Guide Version: 6.4 Page 18

Endpoints

https://{nsxmanager}/api

Base URI Parameters:

nsxmanager€€(required) Hostname or IP address of the NSX Manager.

Working With vSphere Distributed Switches

GET /api/2.0/vdn/switches

Description:

Retrieve information about all vSphere Distributed Switches.

Responses:

Status Code: 200

Body: application/xml

€<vdsContext>

€€€<switch>

€€€€€<objectId>dvs-35</objectId>

€€€€€<objectTypeName>VmwareDistributedVirtualSwitch</objectTypeName>

€€€€€<vsmUuid>423A993F-BEE6-1285-58F1-54E48D508D90</vsmUuid>

€€€€€<nodeId>916287b3-761d-430b-8ab2-83878dfe3e7f</nodeId>

€€€€€<revision>10</revision>

€€€€€<type>

€€€€€€€<typeName>VmwareDistributedVirtualSwitch</typeName>

€€€€€</type>

€€€€€<name>vds-site-a</name>

€€€€€<scope>

€€€€€€€<id>datacenter-21</id>

€€€€€€€<objectTypeName>Datacenter</objectTypeName>

€€€€€€€<name>Datacenter Site A</name>

€€€€€</scope>

€€€€€<clientHandle></clientHandle>

€€€€€<extendedAttributes></extendedAttributes>

€€€€€<isUniversal>false</isUniversal>

€€€€€<universalRevision>0</universalRevision>

€€€</switch>

€€€<mtu>1600</mtu>

€€€<teaming>FAILOVER_ORDER</teaming>

€€€<uplinkPortName>Uplink 4</uplinkPortName>

€€€<promiscuousMode>false</promiscuousMode>

€</vdsContext>

€<vdsContext>

€€€<switch>

€€€€€<objectId>dvs-47</objectId>

€€€€€<objectTypeName>VmwareDistributedVirtualSwitch</objectTypeName>

€€€€€***

€€€</switch>

€€€***

€</vdsContext>

</vdsContexts>

NSX API Guide Version: 6.4 Page 19

POST /api/2.0/vdn/switches

Description:

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.

Request:

Body: application/xml

€<switch>

€€€<objectId>dvs-26</objectId>

€€€<type>

€€€€€<typeName>DistributedVirtualSwitch</typeName>

€€€</type>

€€€<name></name>

€€€<revision>0</revision>

€€€<objectTypeName>DistributedVirtualSwitch</objectTypeName>

€</switch>

€<teaming>ETHER_CHANNEL</teaming>

€<mtu>mtu-value</mtu>

</vdsContext>

Working With vSphere Distributed Switches in a Datacenter

GET /api/2.0/vdn/switches/datacenter/{datacenterID}

URI Parameters:

datacenterID€€(required) A valid datacenter ID (e.g. datacenter-21)

Description:

Retrieve information about all vSphere Distributed Switches in the specified datacenter.

Responses:

Status Code: 200

Body: application/xml

€<vdsContext>

€€€<switch>

€€€€€<objectId>dvs-35</objectId>

€€€€€<objectTypeName>VmwareDistributedVirtualSwitch</objectTypeName>

€€€€€<vsmUuid>423A993F-BEE6-1285-58F1-54E48D508D90</vsmUuid>

€€€€€<nodeId>916287b3-761d-430b-8ab2-83878dfe3e7f</nodeId>

€€€€€<revision>10</revision>

€€€€€<type>

NSX API Guide Version: 6.4 Page 20

€€€€€€€<typeName>VmwareDistributedVirtualSwitch</typeName>

€€€€€</type>

€€€€€<name>vds-site-a</name>

€€€€€<scope>

€€€€€€€<id>datacenter-21</id>

€€€€€€€<objectTypeName>Datacenter</objectTypeName>

€€€€€€€<name>Datacenter Site A</name>

€€€€€</scope>

€€€€€<clientHandle></clientHandle>

€€€€€<extendedAttributes></extendedAttributes>

€€€€€<isUniversal>false</isUniversal>

€€€€€<universalRevision>0</universalRevision>

€€€</switch>

€€€<mtu>1600</mtu>

€€€<teaming>FAILOVER_ORDER</teaming>

€€€<uplinkPortName>Uplink 4</uplinkPortName>

€€€<promiscuousMode>false</promiscuousMode>

€</vdsContext>

€<vdsContext>

€€€<switch>

€€€€€<objectId>dvs-47</objectId>

€€€€€<objectTypeName>VmwareDistributedVirtualSwitch</objectTypeName>

€€€€€***

€€€</switch>

€€€***

€</vdsContext>

</vdsContexts>

Working With a Specific vSphere Distributed Switch

GET /api/2.0/vdn/switches/{vdsId}

URI Parameters:

vdsId€€(required) A valid vSphere Distributed Switch ID (e.g. dvs-35)

Description:

Retrieve information about the specified vSphere Distributed Switch.

Responses:

Status Code: 200

Body: application/xml

€<switch>

€€€<objectId>dvs-35</objectId>

€€€<objectTypeName>VmwareDistributedVirtualSwitch</objectTypeName>

€€€<vsmUuid>423A993F-BEE6-1285-58F1-54E48D508D90</vsmUuid>

€€€<nodeId>916287b3-761d-430b-8ab2-83878dfe3e7f</nodeId>

€€€<revision>10</revision>

€€€<type>

€€€€€<typeName>VmwareDistributedVirtualSwitch</typeName>

€€€</type>

NSX API Guide Version: 6.4 Page 21

€€€<name>vds-site-a</name>

€€€<scope>

€€€€€<id>datacenter-21</id>

€€€€€<objectTypeName>Datacenter</objectTypeName>

€€€€€<name>Datacenter Site A</name>

€€€</scope>

€€€<clientHandle></clientHandle>

€€€<extendedAttributes></extendedAttributes>

€€€<isUniversal>false</isUniversal>

€€€<universalRevision>0</universalRevision>

€</switch>

€<mtu>1600</mtu>

€<teaming>FAILOVER_ORDER</teaming>

€<uplinkPortName>Uplink 4</uplinkPortName>

€<promiscuousMode>false</promiscuousMode>

</vdsContext>

DELETE /api/2.0/vdn/switches/{vdsId}

URI Parameters:

vdsId€€(required) A valid vSphere Distributed Switch ID (e.g. dvs-35)

Description:

Delete the specified vSphere Distributed Switch.

Working With Latency Configuration of a Specific vSphere Distributed Switch

Starting in NSX 6.4.5, you can use APIs to monitor the end-to-end network latency of a data path as traffic moves

between VMs that are either on the same ESXi host or on different ESXi hosts. However, both the VMs must be

attached to the same logical switch (subnet).

Note: NSX cannot calculate the end-to-end latency information when data traffic is routed between VMs through a

distributed logical router. That is, when VMs are attached to different logical switches or subnets.

To calculate the end-to-end latency of the data path, NSX uses the timestamp attribute of a data path packet inside

the hypervisor.

GET /api/2.0/vdn/switches/{vdsId}/latency/configuration

URI Parameters:

vdsId€€(required) A valid vSphere Distributed Switch ID (e.g. dvs-35)

Description:

Retrieve the latency configuration of the specified vSphere Distributed Switch.

Method history:

Release Modification

6.4.5 Method introduced.

Responses:

Status Code: 200

NSX API Guide Version: 6.4 Page 22

Body: application/xml

€<enabled>true</enabled>

€<latencySamplingRateForHost>100</latencySamplingRateForHost>

€<latencyDurationMillSecondsForHost>100</latencyDurationMillSecondsForHost>

</latencyHostConfiguration>

PUT /api/2.0/vdn/switches/{vdsId}/latency/configuration

URI Parameters:

vdsId€€(required) A valid vSphere Distributed Switch ID (e.g. dvs-35)

Description:

Update the latency configuration of the specified vSphere Distributed Switch.

Method history:

Release Modification

6.4.5 Method introduced.

Latency Configuration Parameters

Parameter Description Comments

enabled

When set to true, the dvSwitch

collects latency data. When set to

false, the dvSwitch stops

collecting latency data and

releases all the reserved

resources.

Optional. Boolean. Options are

True or False. Default is False.

latencySamplingRateForHost

Packet sampling rate of the

dvSwitch in integer. For example,

100 means that one packet in

every 100 packets is

timestamped. 1 means that all

packets are timestamped.

Optional. Default value is 100.

Maximum value is 10000, and

minimum value is 1.

latencyDurationMillSecondsForHost

Packet sampling duration of the

dvSwitch in milliseconds. Denotes

the frequency at which latency

data is generated.

Optional. Default value is 1000

ms. Maximum value is 10000 ms,

and minimum value is 1 ms.

Request:

Body: application/xml

€<enabled>true</enabled>

€<latencySamplingRateForHost>100</latencySamplingRateForHost>

€<latencyDurationMillSecondsForHost>100</latencyDurationMillSecondsForHost>

</latencyHostConfiguration>

NSX API Guide Version: 6.4 Page 23

Working With Latency Configuration of a Specific Host

GET /api/2.0/vdn/switches/{vdsId}/host/{hostId}/latency/configuration

URI Parameters:

hostId€€(required) ID of the host.

vdsId€€(required) A valid vSphere Distributed Switch ID (e.g. dvs-35)

Description:

Retrieve the latency configuration of the specified vSphere Distributed Switch on the specified host.

Method history:

Release Modification

6.4.5 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<enabled>true</enabled>

€<latencySamplingRateForHost>100</latencySamplingRateForHost>

€<latencyDurationMillSecondsForHost>100</latencyDurationMillSecondsForHost>

</latencyHostConfiguration>

PUT /api/2.0/vdn/switches/{vdsId}/host/{hostId}/latency/configuration

URI Parameters:

hostId€€(required) ID of the host.

vdsId€€(required) A valid vSphere Distributed Switch ID (e.g. dvs-35)

Description:

Update the latency configuration of the specified vSphere Distributed Switch on the specfied host.

Method history:

Release Modification

6.4.5 Method introduced.

Request:

Body: application/xml

€<enabled>true</enabled>

NSX API Guide Version: 6.4 Page 24

€<latencySamplingRateForHost>100</latencySamplingRateForHost>

€<latencyDurationMillSecondsForHost>100</latencyDurationMillSecondsForHost>

</latencyHostConfiguration>

NSX API Guide Version: 6.4 Page 25

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.

GET /api/2.0/vdn/config/segments

Description:

Retrieve information about all segment ID pools.

Responses:

Status Code: 200

Body: application/xml

€<segmentRange>

€€€<id>1</id>

€€€<name>Local Segments</name>

€€€<desc>Local Segment ID pool</desc>

€€€<begin>5000</begin>

€€€<end>5999</end>

€€€<isUniversal>false</isUniversal>

€€€<universalRevision>0</universalRevision>

€</segmentRange>

€<segmentRange>

€€€<id>3</id>

€€€<name>Universal-Segments</name>

€€€<desc>Universal segment ID pool</desc>

€€€<begin>200000</begin>

€€€<end>201000</end>

€€€<isUniversal>true</isUniversal>

€€€<universalRevision>2</universalRevision>

€</segmentRange>

</segmentRanges>

POST /api/2.0/vdn/config/segments

Query Parameters:

isUniversal€€(optional) Set to true when creating a universal segment ID pool.

Description:

Add a segment ID pool.

NSX API Guide Version: 6.4 Page 26

• name - Required property.

• desc - Optional property.

• begin - Required property. Minimum value is 5000

• end - Required property. Maximum value is 16777216

Request:

Body: application/xml

€<name>Segment 1</name>

€<desc>Segment Range 1</desc>

€<begin>5000</begin>

€<end>12999</end>

</segmentRange>

Working With a Specific Segment ID Pool

GET /api/2.0/vdn/config/segments/{segmentPoolId}

URI Parameters:

segmentPoolId€€(required) A valid segmentPoolId

Description:

Retrieve information about the specified segment ID pool.

Responses:

Status Code: 200

Body: application/xml

€<id>1</id>

€<name>Local Segments</name>

€<desc>Local Segment ID pool</desc>

€<begin>5000</begin>

€<end>5999</end>

€<isUniversal>false</isUniversal>

€<universalRevision>0</universalRevision>

</segmentRange>

PUT /api/2.0/vdn/config/segments/{segmentPoolId}

URI Parameters:

segmentPoolId€€(required) A valid segmentPoolId

Description:

Update the specified segment ID pool.

NSX API Guide Version: 6.4 Page 27

If the segment ID pool is universal you must send the API request to the primary NSX Manager.

Request:

Body: application/xml

€<desc>Local Segment ID pool expanded</desc>

€<end>6999</end>

</segmentRange>

DELETE /api/2.0/vdn/config/segments/{segmentPoolId}

URI Parameters:

segmentPoolId€€(required) A valid segmentPoolId

Description:

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.

GET /api/2.0/vdn/config/multicasts

Description:

Retrieve information about all configured multicast address ranges.

Universal multicast address ranges have the property isUniversal set to true.

Responses:

Status Code: 200

Body: application/xml

€<multicastRange>

€€€<id>5</id>

€€€<name>239.0.0.0-239.255.255.255</name>

€€€<begin>239.0.0.0</begin>

€€€<end>239.255.255.255</end>

€€€<isUniversal>false</isUniversal>

€€€<universalRevision>0</universalRevision>

€</multicastRange>

€<multicastRange>

€€€<id>10</id>

€€€<name>Range 2</name>

€€€<begin>237.0.0.0</begin>

NSX API Guide Version: 6.4 Page 28

€€€<end>237.255.255.255</end>

€€€<isUniversal>false</isUniversal>

€€€<universalRevision>0</universalRevision>

€</multicastRange>

</multicastRanges>

POST /api/2.0/vdn/config/multicasts

Query Parameters:

isUniversal€€(optional) Set to true when creating a universal multicast address

range.

Description:

Add a multicast address range for logical switches.

The address range includes the beginning and ending addresses.

Request:

Body: application/xml

€<name>Range 2</name>

€<begin>237.0.0.0</begin>

€<end>237.255.255.255</end>

</multicastRange>

Working With a Specific Multicast Address Range

GET /api/2.0/vdn/config/multicasts/{multicastAddresssRangeId}

URI Parameters:

multicastAddresssRangeId€€(required) A valid multicast address range ID

Description:

Retrieve information about the specified multicast address range.

Responses:

Status Code: 200

Body: application/xml

€<id>5</id>

€<name>239.0.0.0-239.255.255.255</name>

€<begin>239.0.0.0</begin>

€<end>239.255.255.255</end>

€<isUniversal>false</isUniversal>

€<universalRevision>0</universalRevision>

NSX API Guide Version: 6.4 Page 29

</multicastRange>

PUT /api/2.0/vdn/config/multicasts/{multicastAddresssRangeId}

URI Parameters:

multicastAddresssRangeId€€(required) A valid multicast address range ID

Description:

Update the specified multicast address range.

If the multicast address range is universal you must send the API request to the primary NSX Manager.

Request:

Body: application/xml

€<name>Extended range 2</name>

€<desc>Extended range 2</desc>

€<end>238.255.255.255</end>

</multicastRange>

DELETE /api/2.0/vdn/config/multicasts/{multicastAddresssRangeId}

URI Parameters:

multicastAddresssRangeId€€(required) A valid multicast address range ID

Description:

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

GET /api/2.0/vdn/config/vxlan/udp/port

Description:

Retrieve the UDP port configured for VXLAN traffic.

Responses:

Status Code: 200

Body: application/xml

NSX API Guide Version: 6.4 Page 30

Update the VXLAN Port Configuration

PUT /api/2.0/vdn/config/vxlan/udp/port/{portNumber}

URI Parameters:

portNumber€€(required) A valid UDP port for VXLAN

Query Parameters:

force€€(optional) Set to true to force the change in VXLAN port.

This updates the port configuration on the hosts directly,

and might cause a disruption in VXLAN traffic. In a

cross-vCenter NSX environment, this does not change

the port on all NSX Managers.

Description:

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

GET /api/2.0/vdn/config/vxlan/udp/port/taskStatus

Description:

Retrieve the status of the VXLAN port configuration update.

Method history:

Release Modification

6.2.3 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<prevPort>8472</prevPort>

NSX API Guide Version: 6.4 Page 31

€<targetPort>4789</targetPort>

€<taskPhase>PHASE_TWO</taskPhase>

€<taskStatus>PAUSED</taskStatus>

</vxlanPortUpdatingStatus>

Resume VXLAN Port Configuration Update

POST /api/2.0/vdn/config/vxlan/udp/port/resume

Description:

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

GET /api/2.0/vdn/config/resources/allocated

Query Parameters:

type€€ set to segmentId or multicastAddress

pagesize€€ The number of results to return. Range is 1-1024.

startindex€€ The starting point for returning results.

Description:

Retrieve information about allocated segment IDs or multicast addresses.

Resolving Missing VXLAN VMKernel Adapters

POST /api/2.0/vdn/config/host/{hostId}/vxlan/vteps

Query Parameters:

NSX API Guide Version: 6.4 Page 32

action€€(required) • remediate: Use the remediate action to recreate the

missing VXLAN VMKernel adapter on the host. This

action removes the adapter using the resync action,

then recreates the adapter.

• resync: If the VXLAN VMKernel adapter is no longer

needed, you can use the resync action to remove the

missing VXLAN VMKernel adapter from the NSX

Manager configuration database.

Description:

Resolve missing VXLAN VMKernel adapters.

Method history:

Release Modification

6.2.3 Method introduced.

NSX API Guide Version: 6.4 Page 33

Working With Controller Disconnected Operation (CDO)

Mode

You can enable CDO mode on secondary NSX Manager to avoid connectivity issues with the primary site.

CDO mode state has the following values:

• ENABLED: CDO mode has been successfully enabled on NSX Manager.

• DISABLED: CDO mode has been successfully disabled on NSX Manager.

• UNKNOWN: CDO mode has not been set on NSX Manager.

CDO mode operation status has the following values:

• FAILED: NSX Manager failed to set CDO state.

• SUCCESSFUL: NSX Manager is successful to set CDO state.

• IN_PROGRESS: Setting of CDO state in-progress.

• UNKNOWN: Unknown state.

GET /api/2.0/vdn/cdo

Description:

Retrieves the status of CDO mode.

Method history:

Release Modification

6.4.0 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<vdnCdoModeState>DISABLED</vdnCdoModeState>

€<vdnCdoModeOperationStatus>UNKNOWN</vdnCdoModeOperationStatus>

</vdnCdo>

POST /api/2.0/vdn/cdo

Query Parameters:

action€€ • Use action=enable to enable the CDO mode. Return

value is job ID.

• Use action=disable to disable the CDO mode. Return

value is job ID.

• Use action=resync to resync the CDO mode. Return

value is job ID.

• Use action=update to update the CDO mode detect

time. CDO detect time indicates how much time the

NSX Manager waits to detect the CDO mode. CDO

mode detect time value should be between 2 minutes

to 120 minutes. Return value is job ID.

Description:

Modify the status of CDO mode. This method can be used to perform the following tasks:

• Update the CDO mode: POST /api/2.0/vdn/cdo?action=update

NSX API Guide Version: 6.4 Page 34

• Resync the CDO mode: POST /api/2.0/vdn/cdo?action=resync

• Enable the CDO mode: POST /api/2.0/vdn/cdo?action=enable

• Disable the CDO mode: POST /api/2.0/vdn/cdo?action=disable

Method history:

Release Modification

6.4.0 Method introduced.

Request:

Body: application/xml

€<cdoDetectTime>12</cdoDetectTime>

</vdnCdoConfig>

NSX API Guide Version: 6.4 Page 35

Working With Transport Zones

GET /api/2.0/vdn/scopes

Description:

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.

Responses:

Status Code: 200

Body: application/xml

€<vdnScope>

€€€<objectId>universalvdnscope</objectId>

€€€<objectTypeName>VdnScope</objectTypeName>

€€€<vsmUuid>423A993F-BEE6-1285-58F1-54E48D508D90</vsmUuid>

€€€<nodeId>916287b3-761d-430b-8ab2-83878dfe3e7f</nodeId>

€€€<revision>5</revision>

€€€<type>

€€€€€<typeName>VdnScope</typeName>

€€€</type>

€€€<name>Universal-Transport-Zone</name>

€€€<clientHandle></clientHandle>

€€€<extendedAttributes></extendedAttributes>

€€€<isUniversal>true</isUniversal>

€€€<universalRevision>0</universalRevision>

NSX API Guide Version: 6.4 Page 36

€€€<id>universalvdnscope</id>

€€€<clusters>

€€€€€<cluster>

€€€€€€€<cluster>

€€€€€€€€€<objectId>domain-c33</objectId>

€€€€€€€€€<objectTypeName>ClusterComputeResource</objectTypeName>

€€€€€€€€€<vsmUuid>423A993F-BEE6-1285-58F1-54E48D508D90</vsmUuid>

€€€€€€€€€<nodeId>916287b3-761d-430b-8ab2-83878dfe3e7f</nodeId>

€€€€€€€€€<revision>20</revision>

€€€€€€€€€<type>

€€€€€€€€€€€<typeName>ClusterComputeResource</typeName>

€€€€€€€€€</type>

€€€€€€€€€<name>Compute Cluster A</name>

€€€€€€€€€<scope>

€€€€€€€€€€€<id>datacenter-21</id>

€€€€€€€€€€€<objectTypeName>Datacenter</objectTypeName>

€€€€€€€€€€€<name>Datacenter Site A</name>

€€€€€€€€€</scope>

€€€€€€€€€<clientHandle></clientHandle>

€€€€€€€€€<extendedAttributes></extendedAttributes>

€€€€€€€€€<isUniversal>false</isUniversal>

€€€€€€€€€<universalRevision>0</universalRevision>

€€€€€€€</cluster>

€€€€€</cluster>

€€€€€<cluster>

€€€€€€€<cluster>

€€€€€€€€€<objectId>domain-c41</objectId>

€€€€€€€€€<objectTypeName>ClusterComputeResource</objectTypeName>

€€€€€€€€€<vsmUuid>423A993F-BEE6-1285-58F1-54E48D508D90</vsmUuid>

€€€€€€€€€<nodeId>916287b3-761d-430b-8ab2-83878dfe3e7f</nodeId>

€€€€€€€€€<revision>16</revision>

€€€€€€€€€<type>

€€€€€€€€€€€<typeName>ClusterComputeResource</typeName>

€€€€€€€€€</type>

€€€€€€€€€<name>Management & Edge Cluster</name>

€€€€€€€€€<scope>

€€€€€€€€€€€<id>datacenter-21</id>

€€€€€€€€€€€<objectTypeName>Datacenter</objectTypeName>

€€€€€€€€€€€<name>Datacenter Site A</name>

€€€€€€€€€</scope>

€€€€€€€€€<clientHandle></clientHandle>

€€€€€€€€€<extendedAttributes></extendedAttributes>

€€€€€€€€€<isUniversal>false</isUniversal>

€€€€€€€€€<universalRevision>0</universalRevision>

€€€€€€€</cluster>

€€€€€</cluster>

€€€</clusters>

€€€<virtualWireCount>5</virtualWireCount>

€€€<controlPlaneMode>UNICAST_MODE</controlPlaneMode>

€€€<cdoModeEnabled>false</cdoModeEnabled>

€€€<cdoModeState>

€€€€€<jobId>jobdata-23061</jobId>

€€€€€<operationType>SYNC_DISABLE</operationType>

€€€€€<status>COMPLETED</status>

€€€€€<errorCode>0</errorCode>

€€€</cdoModeState>

€</vdnScope>

€<vdnScope>

€€€<objectId>vdnscope-1</objectId>

€€€<objectTypeName>VdnScope</objectTypeName>

€€€<vsmUuid>423A993F-BEE6-1285-58F1-54E48D508D90</vsmUuid>

€€€<nodeId>916287b3-761d-430b-8ab2-83878dfe3e7f</nodeId>

NSX API Guide Version: 6.4 Page 37

€€€<revision>1</revision>

€€€<type>

€€€€€<typeName>VdnScope</typeName>

€€€</type>

€€€<name>Local-Transport-Zone-A test</name>

€€€<description></description>

€€€<clientHandle></clientHandle>

€€€<extendedAttributes></extendedAttributes>

€€€<isUniversal>false</isUniversal>

€€€<universalRevision>0</universalRevision>

€€€<id>vdnscope-1</id>

€€€<clusters>

€€€€€<cluster>

€€€€€€€<cluster>

€€€€€€€€€<objectId>domain-c33</objectId>

€€€€€€€€€<objectTypeName>ClusterComputeResource</objectTypeName>

€€€€€€€€€<vsmUuid>423A993F-BEE6-1285-58F1-54E48D508D90</vsmUuid>

€€€€€€€€€<nodeId>916287b3-761d-430b-8ab2-83878dfe3e7f</nodeId>

€€€€€€€€€<revision>20</revision>

€€€€€€€€€<type>

€€€€€€€€€€€<typeName>ClusterComputeResource</typeName>

€€€€€€€€€</type>

€€€€€€€€€<name>Compute Cluster A</name>

€€€€€€€€€<scope>

€€€€€€€€€€€<id>datacenter-21</id>

€€€€€€€€€€€<objectTypeName>Datacenter</objectTypeName>

€€€€€€€€€€€<name>Datacenter Site A</name>

€€€€€€€€€</scope>

€€€€€€€€€<clientHandle></clientHandle>

€€€€€€€€€<extendedAttributes></extendedAttributes>

€€€€€€€€€<isUniversal>false</isUniversal>

€€€€€€€€€<universalRevision>0</universalRevision>

€€€€€€€</cluster>

€€€€€</cluster>

€€€€€<cluster>

€€€€€€€<cluster>

€€€€€€€€€<objectId>domain-c41</objectId>

€€€€€€€€€<objectTypeName>ClusterComputeResource</objectTypeName>

€€€€€€€€€<vsmUuid>423A993F-BEE6-1285-58F1-54E48D508D90</vsmUuid>

€€€€€€€€€<nodeId>916287b3-761d-430b-8ab2-83878dfe3e7f</nodeId>

€€€€€€€€€<revision>16</revision>

€€€€€€€€€<type>

€€€€€€€€€€€<typeName>ClusterComputeResource</typeName>

€€€€€€€€€</type>

€€€€€€€€€<name>Management & Edge Cluster</name>

€€€€€€€€€<scope>

€€€€€€€€€€€<id>datacenter-21</id>

€€€€€€€€€€€<objectTypeName>Datacenter</objectTypeName>

€€€€€€€€€€€<name>Datacenter Site A</name>

€€€€€€€€€</scope>

€€€€€€€€€<clientHandle></clientHandle>

€€€€€€€€€<extendedAttributes></extendedAttributes>

€€€€€€€€€<isUniversal>false</isUniversal>

€€€€€€€€€<universalRevision>0</universalRevision>

€€€€€€€</cluster>

€€€€€</cluster>

€€€</clusters>

€€€<virtualWireCount>4</virtualWireCount>

€€€<controlPlaneMode>UNICAST_MODE</controlPlaneMode>

€€€<cdoModeEnabled>false</cdoModeEnabled>

€</vdnScope>

</vdnScopes>

NSX API Guide Version: 6.4 Page 38

POST /api/2.0/vdn/scopes

Query Parameters:

isUniversal€€(optional) Set the isUniversal property to true when creating a

universal transport zone.

Description:

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

Request:

Body: application/xml

€<name>Local-Transport-Zone-B</name>

€<clusters>

€€€<cluster>

€€€€€<cluster>

€€€€€€€<objectId>domain-c7</objectId>

€€€€€</cluster>

€€€</cluster>

€</clusters>

€<controlPlaneMode>UNICAST_MODE</controlPlaneMode>

</vdnScope>

Working With a Specific Transport Zone

GET /api/2.0/vdn/scopes/{scopeId}

URI Parameters:

scopeId€€(required) A valid transport zone ID (vdnScope objectId)

Description:

Retrieve information about the specified transport zone.

Method history:

Release Modification

NSX API Guide Version: 6.4 Page 39

6.3.0

Method updated. Output includes information about

CDO mode. See Working With Transport Zone CDO

Mode for more information.

Responses:

Status Code: 200

Body: application/xml

€<objectId>universalvdnscope</objectId>

€<objectTypeName>VdnScope</objectTypeName>

€<vsmUuid>423A993F-BEE6-1285-58F1-54E48D508D90</vsmUuid>

€<nodeId>916287b3-761d-430b-8ab2-83878dfe3e7f</nodeId>

€<revision>4</revision>

€<type>

€€€<typeName>VdnScope</typeName>

€</type>

€<name>Universal-Transport-Zone</name>

€<clientHandle></clientHandle>

€<extendedAttributes></extendedAttributes>

€<isUniversal>true</isUniversal>

€<universalRevision>0</universalRevision>

€<id>universalvdnscope</id>

€<clusters>

€€€<cluster>

€€€€€<cluster>

€€€€€€€<objectId>domain-c33</objectId>

€€€€€€€<objectTypeName>ClusterComputeResource</objectTypeName>

€€€€€€€<vsmUuid>423A993F-BEE6-1285-58F1-54E48D508D90</vsmUuid>

€€€€€€€<nodeId>916287b3-761d-430b-8ab2-83878dfe3e7f</nodeId>

€€€€€€€<revision>20</revision>

€€€€€€€<type>

€€€€€€€€€<typeName>ClusterComputeResource</typeName>

€€€€€€€</type>

€€€€€€€<name>Compute Cluster A</name>

€€€€€€€<scope>

€€€€€€€€€<id>datacenter-21</id>

€€€€€€€€€<objectTypeName>Datacenter</objectTypeName>

€€€€€€€€€<name>Datacenter Site A</name>

€€€€€€€</scope>

€€€€€€€<clientHandle></clientHandle>

€€€€€€€<extendedAttributes></extendedAttributes>

€€€€€€€<isUniversal>false</isUniversal>

€€€€€€€<universalRevision>0</universalRevision>

€€€€€</cluster>

€€€</cluster>

€€€<cluster>

€€€€€<cluster>

€€€€€€€<objectId>domain-c41</objectId>

€€€€€€€<objectTypeName>ClusterComputeResource</objectTypeName>

€€€€€€€<vsmUuid>423A993F-BEE6-1285-58F1-54E48D508D90</vsmUuid>

€€€€€€€<nodeId>916287b3-761d-430b-8ab2-83878dfe3e7f</nodeId>

€€€€€€€<revision>16</revision>

€€€€€€€<type>

€€€€€€€€€<typeName>ClusterComputeResource</typeName>

€€€€€€€</type>

€€€€€€€<name>Management & Edge Cluster</name>

€€€€€€€<scope>

€€€€€€€€€<id>datacenter-21</id>

NSX API Guide Version: 6.4 Page 40

€€€€€€€€€<objectTypeName>Datacenter</objectTypeName>

€€€€€€€€€<name>Datacenter Site A</name>

€€€€€€€</scope>

€€€€€€€<clientHandle></clientHandle>

€€€€€€€<extendedAttributes></extendedAttributes>

€€€€€€€<isUniversal>false</isUniversal>

€€€€€€€<universalRevision>0</universalRevision>

€€€€€</cluster>

€€€</cluster>

€</clusters>

€<virtualWireCount>5</virtualWireCount>

€<controlPlaneMode>UNICAST_MODE</controlPlaneMode>

€<cdoModeEnabled>true</cdoModeEnabled>

€<cdoModeState>

€€€<jobId>jobdata-23057</jobId>

€€€<operationType>ENABLE</operationType>

€€€<status>COMPLETED</status>

€€€<errorCode>0</errorCode>

€€€<cdoLogicalSwitch>

€€€€€<objectId>universalcdologicalswitch-2</objectId>

€€€€€<objectTypeName>CdoLogicalSwitch</objectTypeName>

€€€€€<vsmUuid>423A993F-BEE6-1285-58F1-54E48D508D90</vsmUuid>

€€€€€<nodeId>916287b3-761d-430b-8ab2-83878dfe3e7f</nodeId>

€€€€€<revision>0</revision>

€€€€€<type>

€€€€€€€<typeName>CdoLogicalSwitch</typeName>

€€€€€</type>

€€€€€<name>universalvdnscope-cdo-logical-switch</name>

€€€€€<description>The backing logical switch to support the cdo mode on universalvdnscope.</description>

€€€€€<clientHandle></clientHandle>

€€€€€<extendedAttributes></extendedAttributes>

€€€€€<isUniversal>true</isUniversal>

€€€€€<universalRevision>0</universalRevision>

€€€€€<vdnId>200005</vdnId>

€€€€€<tenantId>cdo logical switch tenant</tenantId>

€€€€€<status>OK</status>

€€€€€<lSwitchUuid>30059c1e-8d79-4f20-99a3-3d49852835e4</lSwitchUuid>

€€€</cdoLogicalSwitch>

€</cdoModeState>

</vdnScope>

POST /api/2.0/vdn/scopes/{scopeId}

URI Parameters:

scopeId€€(required) A valid transport zone ID (vdnScope objectId)

Query Parameters:

action€€(required) The action parameter values are:

• expand - add a cluster to a transport zone.

• shrink - remove a cluster from a transport zone.

• repair - recreate missing distributed port groups.

Description:

Update the specified transport zone.

You can add a cluster to or delete a cluster from a transport zone.

NSX API Guide Version: 6.4 Page 41

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.

Request:

Body: application/xml

<objectId>universalvdnscope</objectId>

€<clusters>

€€<cluster>

€€€<cluster>

€€€€<objectId>domain-c7</objectId>

€€€€</cluster>

€€</cluster>

€</clusters>

</vdnScope>

DELETE /api/2.0/vdn/scopes/{scopeId}

URI Parameters:

scopeId€€(required) A valid transport zone ID (vdnScope objectId)

Description:

Delete the specified transport zone.

Working With Transport Zone Attributes

PUT /api/2.0/vdn/scopes/{scopeId}/attributes

URI Parameters:

scopeId€€(required) A valid transport zone ID (vdnScope objectId)

Description:

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.

Request:

Body: application/xml

€<objectId>vdnscope-1</objectId>

€<name>Local-Transport-Zone Site-B</name>

€<clusters>

€€€<cluster>

€€€€€<cluster>

NSX API Guide Version: 6.4 Page 42

€€€€€€€<objectId>domain-c7</objectId>

€€€€€</cluster>

€€€</cluster>

€</clusters>

</vdnScope>

Working With Transport Zone CDO Mode

POST /api/2.0/vdn/scopes/{scopeId}/cdo

URI Parameters:

scopeId€€(required) A valid transport zone ID (vdnScope objectId)

Query Parameters:

action€€(required) • enable to enable CDO mode configuration.

• disable to disable CDO mode configuration.

• force_sync to manually push the CDO configuration to

all distributed switches in the transport zone.

Description:

Note: From 6.4.0, CDO feature is supported at NSX Manager level and not at Transport Zone level. For more details,

refer to Working with Controller Disconnected Operation (CDO) Mode section.

Enable or disable CDO mode for the specified transport zone.

Controller Disconnected Operation (CDO) mode ensures that the data plane connectivity is unaffected when host lose

connectivity with the controller.

If you want to enable CDO mode on the universal transport zone in a cross-vCenter NSX environment, you must do

this from the primary NSX Manager. The universal synchronization service will propagate the CDO configuration to the

secondary NSX Managers.

Method history:

Release Modification

6.3.2 Method introduced. (Tech preview in 6.3.0).

Testing Multicast Group Connectivity

POST /api/2.0/vdn/scopes/{scopeId}/conn-check/multicast

URI Parameters:

scopeId€€(required) A valid transport zone ID (vdnScope objectId)

Description:

Test multicast group connectivity.

Test multicast group connectivity between two hosts connected to the specified transport zone.

NSX API Guide Version: 6.4 Page 43

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.

Request:

Body: application/xml

€<gateway>172.23.233.1</gateway>

€<packetSizeMode>0</packetSizeMode>

€<packetSize>1600</packetSize>

€<sourceHost>

€€€<hostId>host-9</hostId>

€€€<switchId>dvs-22</switchId>

€€€<vlanId>54</vlanId>

€</sourceHost>

€<destinationHost>

€€€<hostId>host-92</hostId>

€€€<switchId>dvs-22</switchId>

€€€<vlanId>54</vlanId>

€</destinationHost>

</testParameters>

NSX API Guide Version: 6.4 Page 44

Working With Logical Switches in a Specific Transport Zone

GET /api/2.0/vdn/scopes/{scopeId}/virtualwires

URI Parameters:

scopeId€€(required) A valid transport zone ID (vdnScope objectId). For

example, vdnscope-1 or universalvdnscope.

Query Parameters:

startindex€€ The starting point for returning results.

pagesize€€ The number of results to return. Range is 1-1024.

Description:

Retrieve information about all logical switches in the specified transport zone (network scope).

POST /api/2.0/vdn/scopes/{scopeId}/virtualwires

URI Parameters:

scopeId€€(required) A valid transport zone ID (vdnScope objectId). For

example, vdnscope-1 or universalvdnscope.

Description:

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.

Request:

Body: application/xml

€<name>Web-Tier-01</name>

€<description>Web tier network</description>

€<tenantId>virtual wire tenant</tenantId>

€<controlPlaneMode>UNICAST_MODE</controlPlaneMode>

€<guestVlanAllowed>false</guestVlanAllowed>

</virtualWireCreateSpec>

NSX API Guide Version: 6.4 Page 45

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.

POST /api/2.0/vdn/traceflow

Description:

Create a traceflow.

Request:

Body: application/xml

€<vnicId>74eb1145-d40b-4061-8e64-1caddf2dbf81.001</vnicId>

€<timeout>10000</timeout>

€<routed>true</routed>

€<packet class="fieldsPacketData">

€€€<resourceType>FieldsPacketData</resourceType>

€€€<ethHeader>

€€€€€<srcMac>00:50:56:83:7e:87</srcMac>

€€€€€<dstMac>00:50:56:83:fa:6c</dstMac>

€€€€€<ethType>2048</ethType>

€€€</ethHeader>

€€€<ipHeader>

€€€€€<ttl>64</ttl>

€€€€€<srcIp>172.32.1.5</srcIp>

€€€€€<dstIp>172.34.1.5</dstIp>

€€€</ipHeader>

€</packet>

</traceflowRequest>

Working With a Specific Traceflow

GET /api/2.0/vdn/traceflow/{traceflowId}

URI Parameters:

traceflowId€€(required) Traceflow ID.

Description:

Query a specific Traceflow by tracflowId which is the value returned after executing the create Traceflow API call.

Responses:

NSX API Guide Version: 6.4 Page 46

Status Code: 200

Body: application/xml

€<operState>COMPLETE</operState>

€<vnicId>74eb1145-d40b-4061-8e64-1caddf2dbf81.001</vnicId>

€<id>00000000-0000-0000-0000-000056b5dec3</id>

€<receivedCount>2</receivedCount>

€<forwardedCount>1</forwardedCount>

€<deliveredCount>1</deliveredCount>

€<logicalReceivedCount>4</logicalReceivedCount>

€<logicalDroppedCount>0</logicalDroppedCount>

€<logicalForwardedCount>4</logicalForwardedCount>

€<timeout>10000</timeout>

€<completeAvailable>true</completeAvailable>

€<result>SUCCESS</result>

€<resultSummary>Traceflow delivered observation(s) reported</resultSummary>

€<srcIp>172.32.1.5</srcIp>

€<srcMac>00:50:56:83:7e:87</srcMac>

€<dstMac>172.34.1.5</dstMac>

€<lifMac>00:50:56:83:fa:6c</lifMac>

</traceflowDto>

Traceflow Observations

GET /api/2.0/vdn/traceflow/{traceflowId}/observations

URI Parameters:

traceflowId€€(required) Traceflow ID.

Description:

Retrieve traceflow observations.

Method history:

Release Modification

6.4.0 Method updated. New parameter replicateType added.

Responses:

Status Code: 200

Body: application/xml

€<traceflowObservationsDataPage>

€€€<pagingInfo>

€€€€€<pageSize>100</pageSize>

€€€€€<startIndex>0</startIndex>

€€€€€<totalCount>12</totalCount>

€€€€€<sortOrderAscending>true</sortOrderAscending>

€€€€€<sortBy></sortBy>

NSX API Guide Version: 6.4 Page 47

€€€</pagingInfo>

€€€<traceflowObservationReceived>

€€€€€<roundId>00000000-0000-0000-0000-000056b5dec3</roundId>

€€€€€<transportNodeId>a02fe610-5358-4a3d-8fef-7be60b7d4ea5</transportNodeId>

€€€€€<hostName>10.146.104.42</hostName>

€€€€€<hostId>host-22</hostId>

€€€€€<component>PHYS</component>

€€€€€<compDisplayName>vNIC</compDisplayName>

€€€€€<hopCount>0</hopCount>

€€€</traceflowObservationReceived>

€€€<traceflowObservationLogicalReceived>

€€€€€<roundId>00000000-0000-0000-0000-000056b5dec3</roundId>

€€€€€<transportNodeId>a02fe610-5358-4a3d-8fef-7be60b7d4ea5</transportNodeId>

€€€€€<hostName>10.146.104.42</hostName>

€€€€€<hostId>host-22</hostId>

€€€€€<component>FW</component>

€€€€€<compDisplayName>Firewall</compDisplayName>

€€€€€<hopCount>1</hopCount>

€€€</traceflowObservationLogicalReceived>

€€€<traceflowObservationLogicalForwarded>

€€€€€<roundId>00000000-0000-0000-0000-000056b5dec3</roundId>

€€€€€<transportNodeId>a02fe610-5358-4a3d-8fef-7be60b7d4ea5</transportNodeId>

€€€€€<hostName>10.146.104.42</hostName>

€€€€€<hostId>host-22</hostId>

€€€€€<component>FW</component>

€€€€€<compDisplayName>Firewall</compDisplayName>

€€€€€<hopCount>2</hopCount>

€€€€€<ruleId>1001</ruleId>

€€€</traceflowObservationLogicalForwarded>

€€€<traceflowObservationLogicalForwarded>

€€€€€<roundId>00000000-0000-0000-0000-000056b5dec3</roundId>

€€€€€<transportNodeId>a02fe610-5358-4a3d-8fef-7be60b7d4ea5</transportNodeId>

€€€€€<hostName>10.146.104.42</hostName>

€€€€€<hostId>host-22</hostId>

€€€€€<component>LS</component>

€€€€€<compDisplayName>1-switch-3</compDisplayName>

€€€€€<hopCount>3</hopCount>

€€€€€<vni>10000</vni>

€€€€€<logicalCompId>universalwire-1</logicalCompId>

€€€€€<logicalCompName>1-switch-3</logicalCompName>

€€€</traceflowObservationLogicalForwarded>

€€€<traceflowObservationLogicalReceived>

€€€€€<roundId>00000000-0000-0000-0000-000056b5dec3</roundId>

€€€€€<transportNodeId>a02fe610-5358-4a3d-8fef-7be60b7d4ea5</transportNodeId>

€€€€€<hostName>10.146.104.42</hostName>

€€€€€<hostId>host-22</hostId>

€€€€€<component>LR</component>

€€€€€<compDisplayName>1-vm-3</compDisplayName>

€€€€€<hopCount>4</hopCount>

€€€€€<vni>10000</vni>

€€€€€<lifName>27100000000a</lifName>

€€€€€<compId>10000</compId>

€€€€€<srcNsxManager>4204ad55-71ec-927b-ca1b-aabfa36863ad</srcNsxManager>

€€€€€<srcGlobal>true</srcGlobal>

€€€€€<compName>default+edge-bbe379a7-e7b9-4ece-b97c-466cf746c93e</compName>

€€€€€<logicalCompId>edge-bbe379a7-e7b9-4ece-b97c-466cf746c93e</logicalCompId>

€€€€€<logicalCompName>1-vm-3</logicalCompName>

€€€€€<otherLogicalCompId>universalwire-1</otherLogicalCompId>

€€€€€<otherLogicalCompName>1-switch-3</otherLogicalCompName>

€€€</traceflowObservationLogicalReceived>

€€€<traceflowObservationLogicalForwarded>

€€€€€<roundId>00000000-0000-0000-0000-000056b5dec3</roundId>

NSX API Guide Version: 6.4 Page 48

€€€€€<transportNodeId>a02fe610-5358-4a3d-8fef-7be60b7d4ea5</transportNodeId>

€€€€€<hostName>10.146.104.42</hostName>

€€€€€<hostId>host-22</hostId>

€€€€€<component>LR</component>

€€€€€<compDisplayName>1-vm-3</compDisplayName>

€€€€€<hopCount>5</hopCount>

€€€€€<vni>10002</vni>

€€€€€<lifName>27100000000c</lifName>

€€€€€<compId>10000</compId>

€€€€€<compName>default+edge-bbe379a7-e7b9-4ece-b97c-466cf746c93e</compName>

€€€€€<srcNsxManager>4204ad55-71ec-927b-ca1b-aabfa36863ad</srcNsxManager>

€€€€€<srcGlobal>true</srcGlobal>

€€€€€<logicalCompId>edge-bbe379a7-e7b9-4ece-b97c-466cf746c93e</logicalCompId>

€€€€€<logicalCompName>1-vm-3</logicalCompName>

€€€€€<otherLogicalCompId>universalwire-3</otherLogicalCompId>

€€€€€<otherLogicalCompName>3-switch-98</otherLogicalCompName>

€€€</traceflowObservationLogicalForwarded>

€€€<traceflowObservationLogicalReceived>

€€€€€<roundId>00000000-0000-0000-0000-000056b5dec3</roundId>

€€€€€<transportNodeId>a02fe610-5358-4a3d-8fef-7be60b7d4ea5</transportNodeId>

€€€€€<hostName>10.146.104.42</hostName>

€€€€€<hostId>host-22</hostId>

€€€€€<component>LS</component>

€€€€€<compDisplayName>3-switch-98</compDisplayName>

€€€€€<hopCount>6</hopCount>

€€€€€<vni>10002</vni>

€€€€€<logicalCompId>universalwire-3</logicalCompId>

€€€€€<logicalCompName>3-switch-98</logicalCompName>

€€€</traceflowObservationLogicalReceived>

€€€<traceflowObservationForwarded>

€€€€€<roundId>00000000-0000-0000-0000-000056b5dec3</roundId>

€€€€€<transportNodeId>a02fe610-5358-4a3d-8fef-7be60b7d4ea5</transportNodeId>

€€€€€<hostName>10.146.104.42</hostName>

€€€€€<hostId>host-22</hostId>

€€€€€<component>PHYS</component>

€€€€€<compDisplayName>10.146.104.42</compDisplayName>

€€€€€<hopCount>7</hopCount>

€€€€€<remoteIpAddress>172.19.172.142</remoteIpAddress>

€€€€€<context>5109430534275084</context>

€€€€€<replicateType>TraceflowEgressBUMReplication</replicateType>

€€€</traceflowObservationForwarded>

€€€<traceflowObservationReceived>

€€€€€<roundId>00000000-0000-0000-0000-000056b5dec3</roundId>

€€€€€<transportNodeId>d2fd4b26-a664-423f-b0aa-8ba760cd967f</transportNodeId>

€€€€€<hostName>10.146.103.3</hostName>

€€€€€<hostId>host-20</hostId>

€€€€€<component>PHYS</component>

€€€€€<compDisplayName>10.146.103.3</compDisplayName>

€€€€€<hopCount>8</hopCount>

€€€</traceflowObservationReceived>

€€€<traceflowObservationLogicalReceived>

€€€€€<roundId>00000000-0000-0000-0000-000056b5dec3</roundId>

€€€€€<transportNodeId>d2fd4b26-a664-423f-b0aa-8ba760cd967f</transportNodeId>

€€€€€<hostName>10.146.103.3</hostName>

€€€€€<hostId>host-20</hostId>

€€€€€<component>FW</component>

€€€€€<compDisplayName>Firewall</compDisplayName>

€€€€€<hopCount>9</hopCount>

€€€</traceflowObservationLogicalReceived>

€€€<traceflowObservationLogicalForwarded>

€€€€€<roundId>00000000-0000-0000-0000-000056b5dec3</roundId>

€€€€€<transportNodeId>d2fd4b26-a664-423f-b0aa-8ba760cd967f</transportNodeId>

NSX API Guide Version: 6.4 Page 49

€€€€€<hostName>10.146.103.3</hostName>

€€€€€<hostId>host-20</hostId>

€€€€€<component>FW</component>

€€€€€<compDisplayName>Firewall</compDisplayName>

€€€€€<hopCount>10</hopCount>

€€€€€<ruleId>1001</ruleId>

€€€</traceflowObservationLogicalForwarded>

€€€<traceflowObservationDelivered>

€€€€€<roundId>00000000-0000-0000-0000-000056b5dec3</roundId>

€€€€€<transportNodeId>d2fd4b26-a664-423f-b0aa-8ba760cd967f</transportNodeId>

€€€€€<hostName>10.146.103.3</hostName>

€€€€€<hostId>host-20</hostId>

€€€€€<component>PHYS</component>

€€€€€<compDisplayName>vNIC</compDisplayName>

€€€€€<hopCount>11</hopCount>

€€€€€<vlanId>0</vlanId>

€€€</traceflowObservationDelivered>

€</traceflowObservationsDataPage>

</traceflowObservations>

NSX API Guide Version: 6.4 Page 50

Working With Logical Switches in All Transport Zones

GET /api/2.0/vdn/virtualwires

Query Parameters:

startindex€€ The starting point for returning results.

pagesize€€ The number of results to return. Range is 1-1024.

name€€ Sort using the virtual wire name. For example

/virtualwires?name=virtual wire name.

Description:

Retrieve information about all logical switches in all transport zones.

Method history:

Release Modification

6.4.0 Method updated. Added name query parameter.

Responses:

Status Code: 200

Body: application/xml

€<dataPage>

€€€<pagingInfo>

€€€€€<pageSize>20</pageSize>

€€€€€<startIndex>0</startIndex>

€€€€€<totalCount>13</totalCount>

€€€€€<sortOrderAscending>true</sortOrderAscending>

€€€</pagingInfo>

€€€<virtualWire>

€€€€€<objectId>virtualwire-1</objectId>

€€€€€<objectTypeName>VirtualWire</objectTypeName>

€€€€€<vsmUuid>423A993F-BEE6-1285-58F1-54E48D508D90</vsmUuid>

€€€€€<nodeId>916287b3-761d-430b-8ab2-83878dfe3e7f</nodeId>

€€€€€<revision>3</revision>

€€€€€<type>

€€€€€€€<typeName>VirtualWire</typeName>

€€€€€</type>

€€€€€<name>Transit-Network-01</name>

€€€€€<description></description>

€€€€€<clientHandle></clientHandle>

€€€€€<extendedAttributes></extendedAttributes>

€€€€€<isUniversal>false</isUniversal>

€€€€€<universalRevision>0</universalRevision>

€€€€€<tenantId>virtual wire tenant</tenantId>

€€€€€<vdnScopeId>vdnscope-1</vdnScopeId>

€€€€€<vdsContextWithBacking>

€€€€€€€<switch>

€€€€€€€€€<objectId>dvs-47</objectId>

€€€€€€€€€<objectTypeName>VmwareDistributedVirtualSwitch</objectTypeName>

€€€€€€€€€<vsmUuid>423A993F-BEE6-1285-58F1-54E48D508D90</vsmUuid>

€€€€€€€€€<nodeId>916287b3-761d-430b-8ab2-83878dfe3e7f</nodeId>

€€€€€€€€€<revision>29</revision>

NSX API Guide Version: 6.4 Page 51

€€€€€€€€€<type>

€€€€€€€€€€€<typeName>VmwareDistributedVirtualSwitch</typeName>

€€€€€€€€€</type>

€€€€€€€€€<name>vds-mgt-edge</name>

€€€€€€€€€<scope>

€€€€€€€€€€€<id>datacenter-21</id>

€€€€€€€€€€€<objectTypeName>Datacenter</objectTypeName>

€€€€€€€€€€€<name>Datacenter Site A</name>

€€€€€€€€€</scope>

€€€€€€€€€<clientHandle></clientHandle>

€€€€€€€€€<extendedAttributes></extendedAttributes>

€€€€€€€€€<isUniversal>false</isUniversal>

€€€€€€€€€<universalRevision>0</universalRevision>

€€€€€€€</switch>

€€€€€€€<mtu>1600</mtu>

€€€€€€€<promiscuousMode>false</promiscuousMode>

€€€€€€€<backingType>portgroup</backingType>

€€€€€€€<backingValue>dvportgroup-355</backingValue>

€€€€€€€<missingOnVc>false</missingOnVc>

€€€€€</vdsContextWithBacking>

€€€€€<vdsContextWithBacking>

€€€€€€€<switch>

€€€€€€€€€<objectId>dvs-35</objectId>

€€€€€€€€€<objectTypeName>VmwareDistributedVirtualSwitch</objectTypeName>

€€€€€€€€€***

€€€€€€€</switch>

€€€€€€€<mtu>1600</mtu>

€€€€€€€<promiscuousMode>false</promiscuousMode>

€€€€€€€<backingType>portgroup</backingType>

€€€€€€€<backingValue>dvportgroup-354</backingValue>

€€€€€€€<missingOnVc>false</missingOnVc>

€€€€€</vdsContextWithBacking>

€€€€€<vdnId>5000</vdnId>

€€€€€<guestVlanAllowed>false</guestVlanAllowed>

€€€€€<controlPlaneMode>UNICAST_MODE</controlPlaneMode>

€€€€€<ctrlLsUuid>7ad8bc71-5857-475c-af2a-a9e5337b0944</ctrlLsUuid>

€€€€€<macLearningEnabled>false</macLearningEnabled>

€€€</virtualWire>

€€€<virtualWire>

€€€€€<objectId>virtualwire-2</objectId>

€€€€€***

€€€</virtualWire>

€€€<virtualWire>

€€€€€<objectId>virtualwire-3</objectId>

€€€€€***

€€€</virtualWire>

€€€<virtualWire>

€€€€€<objectId>virtualwire-4</objectId>

€€€€€***

€€€</virtualWire>

€€€<virtualWire>

€€€€€<objectId>universalwire-1</objectId>

€€€€€***

€€€</virtualWire>

€€€***

€€€<virtualWire>

€€€€€<objectId>virtualwire-9</objectId>

€€€€€***

€€€</virtualWire>

€</dataPage>

</virtualWires>

NSX API Guide Version: 6.4 Page 52

Working Virtual Machine Connections to Logical Switches

POST /api/2.0/vdn/virtualwires/vm/vnic

Description:

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.

Request:

Body: application/xml

<com.vmware.vshield.vsm.inventory.dto.VnicDto>

€<objectId>502e71fa-1a00-759b-e40f-ce778e915f16.000</objectId>

€<vnicUuid>502e71fa-1a00-759b-e40f-ce778e915f16.000</vnicUuid>

€<portgroupId>virtualwire-2</portgroupId>

</com.vmware.vshield.vsm.inventory.dto.VnicDto>

Working With a Specific Logical Switch

GET /api/2.0/vdn/virtualwires/{virtualWireID}

URI Parameters:

virtualWireID€€(required) A logical switch id, e.g. virtualwire-1002

Description:

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.

Responses:

Status Code: 200

Body: application/xml

NSX API Guide Version: 6.4 Page 53

€<objectId>universalwire-2</objectId>

€<objectTypeName>VirtualWire</objectTypeName>

€<vsmUuid>423A993F-BEE6-1285-58F1-54E48D508D90</vsmUuid>

€<nodeId>916287b3-761d-430b-8ab2-83878dfe3e7f</nodeId>

€<revision>3</revision>

€<type>

€€€<typeName>VirtualWire</typeName>

€</type>

€<name>ULS-Web-Tier-02</name>

€<clientHandle></clientHandle>

€<extendedAttributes></extendedAttributes>

€<isUniversal>true</isUniversal>

€<universalRevision>2</universalRevision>

€<tenantId>ULS-Tenant</tenantId>

€<vdnScopeId>universalvdnscope</vdnScopeId>

€<vdsContextWithBacking>

€€€<switch>

€€€€€<objectId>dvs-35</objectId>

€€€€€<objectTypeName>VmwareDistributedVirtualSwitch</objectTypeName>

€€€€€<vsmUuid>423A993F-BEE6-1285-58F1-54E48D508D90</vsmUuid>

€€€€€<nodeId>916287b3-761d-430b-8ab2-83878dfe3e7f</nodeId>

€€€€€<revision>29</revision>

€€€€€<type>

€€€€€€€<typeName>VmwareDistributedVirtualSwitch</typeName>

€€€€€</type>

€€€€€<name>vds-site-a</name>

€€€€€<scope>

€€€€€€€<id>datacenter-21</id>

€€€€€€€<objectTypeName>Datacenter</objectTypeName>

€€€€€€€<name>Datacenter Site A</name>

€€€€€</scope>

€€€€€<clientHandle></clientHandle>

€€€€€<extendedAttributes></extendedAttributes>

€€€€€<isUniversal>false</isUniversal>

€€€€€<universalRevision>0</universalRevision>

€€€</switch>

€€€<mtu>1600</mtu>

€€€<promiscuousMode>false</promiscuousMode>

€€€<backingType>portgroup</backingType>

€€€<backingValue>dvportgroup-397</backingValue>

€€€<missingOnVc>false</missingOnVc>

€</vdsContextWithBacking>

€<vdsContextWithBacking>

€€€***

€</vdsContextWithBacking>

€<vdnId>200001</vdnId>

€<guestVlanAllowed>false</guestVlanAllowed>

€<controlPlaneMode>UNICAST_MODE</controlPlaneMode>

€<ctrlLsUuid>f360d6e5-c709-4aca-b8d1-37de500a867a</ctrlLsUuid>

€<macLearningEnabled>false</macLearningEnabled>

</virtualWire>

PUT /api/2.0/vdn/virtualwires/{virtualWireID}

URI Parameters:

virtualWireID€€(required) A logical switch id, e.g. virtualwire-1002

Description:

NSX API Guide Version: 6.4 Page 54

Update the specified logical switch.

For example, you can update the name, description, or control plane mode.

Request:

Body: application/xml

€<name>ULS-Web-Tier-02 </name>

€<description>Universal Web Logical Switch</description>

€<tenantId>virtual wire tenant</tenantId>

€<controlPlaneMode>UNICAST_MODE</controlPlaneMode>

</virtualWire>

DELETE /api/2.0/vdn/virtualwires/{virtualWireID}

URI Parameters:

virtualWireID€€(required) A logical switch id, e.g. virtualwire-1002

Description:

Delete the specified logical switch.

Resolving Missing Port Groups for a Logical Switch

POST /api/2.0/vdn/virtualwires/{virtualWireID}/backing

URI Parameters:

virtualWireID€€(required) A logical switch id, e.g. virtualwire-1002

Query Parameters:

action€€(required) • remediate: The remediate action performs the resync

action and then creates a new backing port group for

the logical switch. Under normal operations, you

should need the remediate action only.

• resync: The resync action removes the association

between the backing port group and the logical switch

in the NSX Manager configuration.

Description:

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.

NSX API Guide Version: 6.4 Page 55

Testing Host Connectivity

POST /api/2.0/vdn/virtualwires/{virtualWireID}/conn-check/multicast

URI Parameters:

virtualWireID€€(required) A logical switch id, e.g. virtualwire-1002

Description:

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.

Request:

Body: application/xml

€<gateway></gateway>

€<packetSizeMode></packetSizeMode>

€<packetSize></packetSize>

€<sourceHost>

€€€<hostId></hostId>

€€€<switchId></switchId>

€€€<vlanId></vlanId>

€</sourceHost>

€<destinationHost>

€€€<hostId></hostId>

€€€<switchId></switchId>

€€€<vlanId></vlanId>

€</destinationHost>

</testParameters>

Testing Point-to-Point Connectivity

POST /api/2.0/vdn/virtualwires/{virtualWireID}/conn-check/p2p

URI Parameters:

virtualWireID€€(required) A logical switch id, e.g. virtualwire-1002

Description:

Test point-to-point connectivity.

Test point-to-point connectivity between two hosts connected to the specified logical switch.

NSX API Guide Version: 6.4 Page 56

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.

Request:

Body: application/xml

€<gateway></gateway>

€<packetSizeMode></packetSizeMode>

€<packetSize></packetSize>

€<sourceHost>

€€€<hostId></hostId>

€€€<switchId></switchId>

€€€<vlanId></vlanId>

€</sourceHost>

€<destinationHost>

€€€<hostId></hostId>

€€€<switchId></switchId>

€€€<vlanId></vlanId>

€</destinationHost>

</testParameters>

Working With Hardware Gateway Bindings for a Specific Logical Switch

GET /api/2.0/vdn/virtualwires/{virtualWireID}/hardwaregateways

URI Parameters:

virtualWireID€€(required) A logical switch id, e.g. virtualwire-1002

Description:

Retrieve hardware gateway bindings for the specified logical switch.

Method history:

Release Modification

6.2.3 Method introduced.

Responses:

Status Code: 200

Body: application/xml

<list>

€<hardwareGatewayBinding>

€€€<id>torbinding-2</id>

€€€<hardwareGatewayId>torgateway-1</hardwareGatewayId>

€€€<switchName>1-switch-579</switchName>

€€€<portname>p1</portname>

NSX API Guide Version: 6.4 Page 57

€€€<vlan>0</vlan>

€€€<virtualWire>virtualwire-1</virtualWire>

€€€<vni>5342</vni>

€</hardwareGatewayBinding>

€<hardwareGatewayBinding>

€€€<id>torbinding-1</id>

€€€<hardwareGatewayId>torgateway-2</hardwareGatewayId>

€€€<switchName>1-switch-104</switchName>

€€€<portname>p1</portname>

€€€<vlan>0</vlan>

€€€<virtualWire>virtualwire-1</virtualWire>

€€€<vni>5342</vni>

€</hardwareGatewayBinding>

</list>

Working With Connections Between Hardware Gateways and Logical Switches

POST /api/2.0/vdn/virtualwires/{virtualWireID}/hardwaregateways/{hardwareGatewa

yBindingId}

URI Parameters:

hardwareGatewayBindingId€€ Hardware Gateway Binding ID.

virtualWireID€€(required) A logical switch id, e.g. virtualwire-1002

Query Parameters:

action€€(optional) Specify attach to attach a hardware gateway to a logical

switch.

Specify detach to detach a hardware gateway from a

logical switch.

Description:

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

€<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

NSX API Guide Version: 6.4 Page 58

€***

€<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.

Request:

Body: application/xml

€<hardwareGatewayId>hardwarewgateway1</hardwareGatewayId>

€<vlan>v1</vlan>

€<switchName>s1</switchName>

€<portName>s1</portName>

</hardwareGatewayBinding>

NSX API Guide Version: 6.4 Page 59

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.

GET /api/2.0/xvs/networks/{ID}/features

URI Parameters:

ID€€(required) dvPortGroup MOID or logical switch (virtual wire) ID.

Description:

Retrieve IP discovery and MAC learning information.

PUT /api/2.0/xvs/networks/{ID}/features

URI Parameters:

ID€€(required) dvPortGroup MOID or logical switch (virtual wire) ID.

Description:

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.

Request:

Body: application/xml

€<ipDiscoveryConfig>

€€€<enabled></enabled>

€</ipDiscoveryConfig>

€<macLearningConfig>

€€€<enabled></enabled>

NSX API Guide Version: 6.4 Page 60

€</macLearningConfig>

</networkFeatureConfig>

NSX API Guide Version: 6.4 Page 61

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.

GET /api/2.0/vdn/controller

Description:

Retrieves details and runtime status for all controllers. Runtime status can be one of the following:

• Deploying - Controller is being deployed and the procedure has not completed yet.

• Removing - Controller is being removed and the procedure has not completed yet.

• Running - Controller has been deployed and can respond to API invocation.

• Unknown - Controller has been deployed but fails to respond to API invocation.

When a controller is in Running status, the diskLatencyAlertDetected parameter in the API response shows whether

disk latency alert is detected in the controller. This parameter can take one of the following values:

• True - Disk latency alert is detected in the controller.

• False - Disk latency is not detected in the controller.

• Unknown - After the controller connects with the NSX Manager, the NSX Manager receives the disk latency report

of the controller after a delay of 30 seconds.

Responses:

Status Code: 200

Body: application/xml

€<controller>

€€€<id></id>

€€€<name></name>

€€€<description></description>

€€€<ipAddress></ipAddress>

€€€<status></status>

€€€<diskLatencyAlertDetected></diskLatencyAlertDetected>

€</controller>

</controllers>

POST /api/2.0/vdn/controller

Description:

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.

Request:

NSX API Guide Version: 6.4 Page 62

Body: application/xml

€<name>nsx-controller-node1</name>

€<description>nsx-controller</description>

€<ipPoolId>ipPool-1</ipPoolId>

€<resourcePoolId>domain-c1</resourcePoolId>

€<hostId>host-1</hostId>

€<datastoreId>datastore-1</datastoreId>

€<deployType>medium</deployType>

€<networkId>dvportgroup-1</networkId>

€<password>MyTestPassword</password>

</controllerSpec>

Working With Controller Upgrade Availability

GET /api/2.0/vdn/controller/upgrade-available

Description:

Retrieve controller upgrade availability.

Working With of Controller Job Status

GET /api/2.0/vdn/controller/progress/{jobId}

URI Parameters:

jobId€€(required) Specified job Id

Description:

Retrieves status of controller creation or removal, or controller cluster upgrade.

Responses:

Status Code: 200

Body: application/xml

€<vmId></vmId>

€<progress></progress>

€<status></status>

€<exceptionMessage></exceptionMessage>

</controllerDeploymentInfo>

NSX API Guide Version: 6.4 Page 63

Working With a Specific Controller

PUT /api/2.0/vdn/controller/{controllerId}

URI Parameters:

controllerId€€(required) Specified controller ID.

Retrieve available controller IDs with GET

/api/2.0/vdn/controller.

In a cross-vCenter NSX environment, retrieve the

controller IDs from the primary NSX Manager.

Description:

Update the name of the controller. The name must not contain spaces or underscores.

When you update the controller name, the following changes are made:

• the name displayed in the Networking & Security UI is changed to newName

• the VM name is vSphere is changed to newName-NSX-<controller_id>

• the VM's hostname is changed to newName-NSX-<controller_id>

Note: The VM hostname is used in controller log entries. If you change the controller hostname, the log entries display

the new hostname.

Method history:

Release Modification

6.4.0 Method introduced.

Request:

Body: application/xml

€<name>newName</name>

</controller>

POST /api/2.0/vdn/controller/{controllerId}

URI Parameters:

controllerId€€(required) Specified controller ID.

Retrieve available controller IDs with GET

/api/2.0/vdn/controller.

In a cross-vCenter NSX environment, retrieve the

controller IDs from the primary NSX Manager.

Query Parameters:

action€€(required) Specify remediate to recover from controller shutdown or

deletion.

Description:

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.

NSX API Guide Version: 6.4 Page 64

Method history:

Release Modification

6.2.3 Method introduced.

DELETE /api/2.0/vdn/controller/{controllerId}

URI Parameters:

controllerId€€(required) Specified controller ID.

Retrieve available controller IDs with GET

/api/2.0/vdn/controller.

In a cross-vCenter NSX environment, retrieve the

controller IDs from the primary NSX Manager.

Query Parameters:

forceRemoval€€(required) Specify whether to force removal of controller. Must be

set to true to remove last controller of the controller

cluster.

Description:

Delete the NSX controller.

Working With NSX Controller System Statistics

GET /api/2.0/vdn/controller/{controllerId}/systemStats

URI Parameters:

controllerId€€(required) Specified controller ID.

Retrieve available controller IDs with GET

/api/2.0/vdn/controller.

In a cross-vCenter NSX environment, retrieve the

controller IDs from the primary NSX Manager.

Description:

Retrieve NSX Controller system statistics.

Method history:

Release Modification

6.2.3 Method introduced.

Responses:

Status Code: 200

Body: application/xml

NSX API Guide Version: 6.4 Page 65

€<id>controller-2</id>

€<ipAddress>192.168.110.32</ipAddress>

€<syncTime>1490991545530</syncTime>

€<cpuCoreCount>2</cpuCoreCount>

€<cpuLoadInfo>

€€€<interval>1</interval>

€€€<averageLoad>0.17</averageLoad>

€</cpuLoadInfo>

€<cpuLoadInfo>

€€€<interval>5</interval>

€€€<averageLoad>0.6</averageLoad>

€</cpuLoadInfo>

€<cpuLoadInfo>

€€€<interval>15</interval>

€€€<averageLoad>0.4</averageLoad>

€</cpuLoadInfo>

€<totalMemory>1924280</totalMemory>

€<usedMemory>1542524</usedMemory>

€<cachedMemory>589196</cachedMemory>

€<totalSwap>4190204</totalSwap>

€<usedSwap>0</usedSwap>

€<systemTime>1490991545521</systemTime>

€<upTime>433880</upTime>

€<nodeFailoverReady>false</nodeFailoverReady>

€<nodeDiskLatencyStatus>

€€€<deviceName>sda</deviceName>

€€€<refreshTime>1490991404000</refreshTime>

€€€<latencyType>w_await</latencyType>

€€€<lastLatency>97.0</lastLatency>

€€€<avgLatency>28.572</avgLatency>

€€€<alertEnabled>false</alertEnabled>

€</nodeDiskLatencyStatus>

€<nodeDiskLatencyStatus>

€€€<deviceName>sda</deviceName>

€€€<refreshTime>1490991186000</refreshTime>

€€€<latencyType>r_await</latencyType>

€€€<lastLatency>9.18</lastLatency>

€€€<avgLatency>0.0</avgLatency>

€€€<alertEnabled>false</alertEnabled>

€</nodeDiskLatencyStatus>

€<nodeDiskLatencyStatus>

€€€<deviceName>dm-1</deviceName>

€€€<refreshTime>1490991185000</refreshTime>

€€€<latencyType>w_await</latencyType>

€€€<lastLatency>0.0</lastLatency>

€€€<avgLatency>0.0</avgLatency>

€€€<alertEnabled>false</alertEnabled>

€</nodeDiskLatencyStatus>

€<nodeDiskLatencyStatus>

€€€<deviceName>dm-1</deviceName>

€€€<refreshTime>1490991185000</refreshTime>

€€€<latencyType>r_await</latencyType>

€€€<lastLatency>51.51</lastLatency>

€€€<avgLatency>0.0</avgLatency>

€€€<alertEnabled>false</alertEnabled>

€</nodeDiskLatencyStatus>

€<nodeDiskLatencyStatus>

€€€<deviceName>dm-0</deviceName>

€€€<refreshTime>1490991404000</refreshTime>

€€€<latencyType>w_await</latencyType>

€€€<lastLatency>129.33</lastLatency>

NSX API Guide Version: 6.4 Page 66

€€€<avgLatency>34.16</avgLatency>

€€€<alertEnabled>false</alertEnabled>

€</nodeDiskLatencyStatus>

€<nodeDiskLatencyStatus>

€€€<deviceName>dm-0</deviceName>

€€€<refreshTime>1490991225000</refreshTime>

€€€<latencyType>r_await</latencyType>

€€€<lastLatency>0.0</lastLatency>

€€€<avgLatency>12.678</avgLatency>

€€€<alertEnabled>false</alertEnabled>

€</nodeDiskLatencyStatus>

</controllerNodeStatus>

Working With Controller Tech Support Logs

GET /api/2.0/vdn/controller/{controllerId}/techsupportlogs

URI Parameters:

controllerId€€(required) Specified controller ID.

Retrieve available controller IDs with GET

/api/2.0/vdn/controller.

In a cross-vCenter NSX environment, retrieve the

controller IDs from the primary NSX Manager.

Headers:

Content-type€€(required) application/octet-stream

Description:

Retrieve controller logs. Response content type is application/octet-stream and response header is filename. This

streams a fairly large bundle back (possibly hundreds of MB).

Working With Controller Syslog Configuration

GET /api/2.0/vdn/controller/{controllerId}/syslog

URI Parameters:

controllerId€€(required) Specified controller ID.

Retrieve available controller IDs with GET

/api/2.0/vdn/controller.

In a cross-vCenter NSX environment, retrieve the

controller IDs from the primary NSX Manager.

Description:

Retrieve details about the syslog exporter on the controller.

NSX API Guide Version: 6.4 Page 67

Deprecated: Starting in 6.4.2, POST/DELETE /api/2.0/vdn/controller/{controllerId}/syslog are

deprecated.

Use GET/PUT /api/2.0/vdn/controller/cluster/syslog instead.

Using both these methods is not supported and might result in an inconsistent state on the controller nodes.

Responses:

Status Code: 200

Body: application/xml

€<syslogServer></syslogServer>

€<port></port>

€<protocol></protocol>

€<level></level>

</controllerSyslogServer>

POST /api/2.0/vdn/controller/{controllerId}/syslog

URI Parameters:

controllerId€€(required) Specified controller ID.

Retrieve available controller IDs with GET

/api/2.0/vdn/controller.

In a cross-vCenter NSX environment, retrieve the

controller IDs from the primary NSX Manager.

Description:

Add controller syslog exporter on the controller.

Deprecated: Starting in 6.4.2, POST/DELETE /api/2.0/vdn/controller/{controllerId}/syslog are

deprecated.

Use GET/PUT /api/2.0/vdn/controller/cluster/syslog instead.

Using both these methods is not supported and might result in an inconsistent state on the controller nodes.

Request:

Body: application/xml

€<syslogServer></syslogServer>

€<port></port>

€<protocol></protocol>

€<level></level>

</controllerSyslogServer>

DELETE /api/2.0/vdn/controller/{controllerId}/syslog

URI Parameters:

NSX API Guide Version: 6.4 Page 68

controllerId€€(required) Specified controller ID.

Retrieve available controller IDs with GET

/api/2.0/vdn/controller.

In a cross-vCenter NSX environment, retrieve the

controller IDs from the primary NSX Manager.

Description:

Deletes syslog exporter on the specified controller node.

Deprecated: Starting in 6.4.2, POST/DELETE /api/2.0/vdn/controller/{controllerId}/syslog are

deprecated.

Use GET/PUT /api/2.0/vdn/controller/cluster/syslog instead.

Using both these methods is not supported and might result in an inconsistent state on the controller nodes.

Working With Controller Cluster Snapshots

GET /api/2.0/vdn/controller/{controllerId}/snapshot

URI Parameters:

controllerId€€(required) Specified controller ID.

Retrieve available controller IDs with GET

/api/2.0/vdn/controller.

In a cross-vCenter NSX environment, retrieve the

controller IDs from the primary NSX Manager.

Description:

Take a snapshot of the control cluster from the specified controller node.

Working With the NSX Controller Cluster Configuration

GET /api/2.0/vdn/controller/cluster

Description:

Retrieve cluster wide configuration information for controller.

Responses:

Status Code: 200

Body: application/xml

€<sslEnabled></sslEnabled>

</controllerConfig>

NSX API Guide Version: 6.4 Page 69

PUT /api/2.0/vdn/controller/cluster

Description:

Modify cluster wide configuration information for controller.

Request:

Body: application/xml

€<sslEnabled></sslEnabled>

</controllerConfig>

Working With Controller Cluster NTP Settings

You can configure up to five NTP servers on the NSX Controller cluster. You can specify NTP servers by IPv4 address

or FQDN. If an FQDN is used, DNS settings must also be configured. The same NTP settings are applied to all

controller nodes in the cluster.

GET /api/2.0/vdn/controller/cluster/ntp

Description:

Retrieve NTP configuration for the NSX Controller cluster.

Method history:

Release Modification

6.4.0 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<ntpServers>

€€€<string>192.168.110.10</string>

€€€<string>192.168.110.11</string>

€</ntpServers>

</ControllerClusterNtpServers>

PUT /api/2.0/vdn/controller/cluster/ntp

Description:

Update NTP configuration for the NSX Controller cluster.

If the settings fail to apply to one or more controller nodes, an error message is returned. Check the controller node

status, and retry the request.

Method history:

NSX API Guide Version: 6.4 Page 70

Release Modification

6.4.0 Method introduced.

Request:

Body: application/xml

€<ntpServers>

€€€<string>192.168.110.10</string>

€€€<string>192.168.110.11</string>

€€€<string>ntp-1.example.com</string>

€</ntpServers>

</ControllerClusterNtpServers>

Working With Controller Cluster DNS Settings

When you configure DNS on the NSX Controller cluster, the same settings are applied to all nodes in the cluster.

Controller cluster DNS settings override any DNS settings configured on the controller IP pool.

DNS Parameters

Parameter Description Comments

dnsServer DNS server IP address

Required. Specify up to 3. Valid

input: IPv4 addresses.

dnsSuffix DNS suffix for search order

Optional. Specify up to 3. Valid

input: domain name suffix. At least

one dnsServer must be configured.

GET /api/2.0/vdn/controller/cluster/dns

Description:

Retrieve DNS settings for the NSX Controller cluster.

Method history:

Release Modification

6.4.2 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<dnsServer>10.1.140.1</dnsServer>

€<dnsServer>10.1.150.1</dnsServer>

€<dnsSuffix>example.com</dnsSuffix>

€<dnsSuffix>dns1.example.com</dnsSuffix>

</ControllerClusterDns>

NSX API Guide Version: 6.4 Page 71

PUT /api/2.0/vdn/controller/cluster/dns

Description:

Update DNS settings for all nodes in the NSX Controller cluster.

Note: If the settings fail to apply to one or more controller nodes, an error message is returned. Check the controller

node status, and retry the request.

Method history:

Release Modification

6.4.2 Method introduced.

Request:

Body: application/xml

€<dnsServer>10.1.140.1</dnsServer>

€<dnsServer>10.1.150.1</dnsServer>

€<dnsServer>10.1.160.1</dnsServer>

€<dnsSuffix>example.com</dnsSuffix>

€<dnsSuffix>dns1.example.com</dnsSuffix>

€<dnsSuffix>dns2.example.com</dnsSuffix>

</ControllerClusterDns>

Working With Controller Cluster Syslog Configuration

When you configure syslog on the NSX Controller cluster, the same settings are applied to all nodes in the cluster.

Syslog Parameters

Parameter Description Comments

syslogServer Syslog server address

Required. Specify up to 10. Valid

input: IPv4 addresses or FQDN. If

FQDN is used, DNS must also be

configured.

port Syslog exporter port

Optional. Default is 6514. Valid

ports: 1-65535.

level Syslog logging level

Optional. Default is INFO. Valid

values: INFO, ERROR, WARN.

protocol Syslog protocol

Optional. Default is TLS. Valid

values: TLS, UDP, TCP.

certificate Certificate

Required if protocol is set to TLS.

Valid value: X.509 PEM encoded

certificate.

GET /api/2.0/vdn/controller/cluster/syslog

Description:

NSX API Guide Version: 6.4 Page 72

Retrieve syslog settings for the NSX Controller cluster.

Method history:

Release Modification

6.4.2 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<controllerSyslogServer>

€€€<syslogServer>syslog1.com</syslogServer>

€€€<port>6514</port>

€€€<protocol>TLS</protocol>

€€€<level>ERROR</level>

€€€<certificate>-----BEGIN CERTIFICATE-----

MIICWjCCAcMCAgGlMA0GCSqGSIb3DQEBBAUAMHUxCzAJBgNVBAYTAlVTMRgwFgYDVQQKEw ***

-----END CERTIFICATE-----</certificate>

€</controllerSyslogServer>

€<controllerSyslogServer>

€€€<syslogServer>syslog5.com</syslogServer>

€€€<port>514</port>

€€€<protocol>UDP</protocol>

€€€<level>INFO</level>

€</controllerSyslogServer>

</ControllerSyslogServerList>

PUT /api/2.0/vdn/controller/cluster/syslog

Description:

Update syslog settings for all nodes in the NSX Controller cluster.

If the settings fail to apply to one or more controller nodes, an error message is returned. Check the controller node

status, and retry the request.

Important: You can also configure syslog on an individual controller node with the deprecated API POST/DELETE

/api/2.0/vdn/controller/{controllerId}/syslog. Using both these methods is not supported and might

result in an inconsistent state on the controller nodes.

Method history:

Release Modification

6.4.2 Method introduced.

Request:

Body: application/xml

€<controllerSyslogServer>

€€€<syslogServer>syslog1.com</syslogServer>

€€€<port>6514</port>

€€€<protocol>TLS</protocol>

NSX API Guide Version: 6.4 Page 73

€€€<level>ERROR</level>

€€€<certificate>-----BEGIN CERTIFICATE-----

MIICWjCCAcMCAgGlMA0GCSqGSIb3DQEBBAUAMHUxCzAJBgNVBAYTAlVTMRgwFgYDVQQKEw ***

-----END CERTIFICATE-----</certificate>

€</controllerSyslogServer>

€<controllerSyslogServer>

€€€<syslogServer>syslog5.com</syslogServer>

€€€<port>514</port>

€€€<protocol>UDP</protocol>

€€€<level>INFO</level>

€</controllerSyslogServer>

</ControllerSyslogServerList>

Working With Controller Cluster Upgrade

POST /api/2.0/vdn/controller/cluster/upgrade

Description:

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

PUT /api/2.0/vdn/controller/credential

Description:

Change the NSX controller password.

Request:

Body: application/xml

€<apiPassword></apiPassword>

</controllerCredential>

Working With Controller Synchronization

NSX API Guide Version: 6.4 Page 74

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.

PUT /api/2.0/vdn/controller/synchronize

Description:

Synchronize the controller cluster with the NSX Manager database.

Working with Controller Synchronization Status

Retrieve the status of the controller synchronization.

GET /api/2.0/vdn/controller/synchronize/status

Description:

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.

Responses:

Status Code: 200

Body: application/xml

€<status>JOB_IN_PROGRESS</status>

€<jobId>jobdata-201</jobId>

</controllerSyncStatus>

NSX API Guide Version: 6.4 Page 75

Working With Host Health Status Using BFD

Provides overall information about the host health status. Tunnel, pNIC, control plane, and management plane

statuses are displayed.

Working with overall information about host health status

GET /api/2.0/vdn/host/status

Query Parameters:

source€€(optional) Specify source as REALTIME, or CACHED. Default

value is CACHED. Use status?source=REALTIME to get

current status. Use status?source=CACHED to get

cached status.

status€€(optional) Specify UP, DOWN, DEGRADED to filter by status.

Default value is NONE.

host_id€€(optional) Specify host ID.

Description:

Retrieve the host health status.

The status API endpoint has a known limitation in a multi-site Cross-vCenter NSX deployment where the vCenter

Server and the NSX Manager know only the hosts that they manage.

The NSX Manager can query status of only those hosts that its vCenter Server manages. For example, when you run

this API on the primary NSX Manager, the API cannot return the status of hosts, which are managed by the vCenter

Servers that are paired with the secondary NSX Managers.

Method history:

Release Modification

6.4.0 Method introduced.

Request:

Body: application/xml

€<hostId>host-23</hostId>

€<status>UP</status>

€<controlConnectionStatus>UP</controlConnectionStatus>

€<mgmtConnectionStatus>UP</mgmtConnectionStatus>

€<pnicStatus>

€€€<status>UP</status>

€€€<upCount>1</upCount>

€€€<downCount>0</downCount>

€€€<degradedCount>0</degradedCount>

€</pnicStatus>

€<tunnelStatus>

€€€<status>UP</status>

€€€<upCount>1</upCount>

€€€<downCount>0</downCount>

€€€<degradedCount>0</degradedCount>

NSX API Guide Version: 6.4 Page 76

€€€<bfdStatusCount>

€€€€€<bfdAdminDownCount>0</bfdAdminDownCount>

€€€€€<bfdUpCount>3</bfdUpCount>

€€€€€<bfdDownCount>0</bfdDownCount>

€€€€€<bfdInitCount>3</bfdInitCount>

€€€</bfdStatusCount>

€€€<bfdDiagnostic>

€€€€€<echoFunctionFailedCount>0</echoFunctionFailedCount>

€€€€€<noDiagnosticCount>1</noDiagnosticCount>

€€€€€<pathDownCount>0</pathDownCount>

€€€€€<administrativelyDownCount>0</administrativelyDownCount>

€€€€€<controlDetectionTimeExpiredCount>0</controlDetectionTimeExpiredCount>

€€€€€<forwardingPlaneResetCount>0</forwardingPlaneResetCount>

€€€€€<reverseConcatenatedPathDownCount>0</reverseConcatenatedPathDownCount>

€€€€€<neighborSignaledSessionDownCount>0</neighborSignaledSessionDownCount>

€€€€€<concatenatedPathDownCount>0</concatenatedPathDownCount>

€€€</bfdDiagnostic>

€</tunnelStatus>

</hostStatus>

Working with health status for a specific host

GET /api/2.0/vdn/host/{hostId}/status

URI Parameters:

hostId€€(required) ID of the host.

Query Parameters:

source€€(optional) Specify source as REALTIME, or CACHED. Default

value is CACHED. Use status?source=REALTIME to get

current status. Use status?source=CACHED to get

cached status.

status€€(optional) Specify UP, DOWN, DEGRADED to filter by status.

Default value is NONE.

host_id€€(optional) Specify host ID.

Description:

Retrieve health status for a specific host.

NSX Manager obtains host status from the host periodically and updates the cache. When the source is specified as

realtime, the current status of the host is retrieved. In the meantime, NSX Manager updates the host status in the

cache. When the source is specified as cached, the host status is retrieved directly from the cache.

Method history:

Release Modification

6.4.0 Method introduced.

Request:

Body: application/xml

NSX API Guide Version: 6.4 Page 77

€<hostId>host-23</hostId>

€<status>UP</status>

€<controlConnectionStatus>UP</controlConnectionStatus>

€<mgmtConnectionStatus>UP</mgmtConnectionStatus>

€<pnicStatus>

€€€<status>UP</status>

€€€<upCount>1</upCount>

€€€<downCount>0</downCount>

€€€<degradedCount>0</degradedCount>

€</pnicStatus>

€<tunnelStatus>

€€€<status>UP</status>

€€€<upCount>1</upCount>

€€€<downCount>0</downCount>

€€€<degradedCount>0</degradedCount>

€€€<bfdStatusCount>

€€€€€<bfdAdminDownCount>0</bfdAdminDownCount>

€€€€€<bfdUpCount>3</bfdUpCount>

€€€€€<bfdDownCount>0</bfdDownCount>

€€€€€<bfdInitCount>3</bfdInitCount>

€€€</bfdStatusCount>

€€€<bfdDiagnostic>

€€€€€<echoFunctionFailedCount>0</echoFunctionFailedCount>

€€€€€<noDiagnosticCount>1</noDiagnosticCount>

€€€€€<pathDownCount>0</pathDownCount>

€€€€€<administrativelyDownCount>0</administrativelyDownCount>

€€€€€<controlDetectionTimeExpiredCount>0</controlDetectionTimeExpiredCount>

€€€€€<forwardingPlaneResetCount>0</forwardingPlaneResetCount>

€€€€€<reverseConcatenatedPathDownCount>0</reverseConcatenatedPathDownCount>

€€€€€<neighborSignaledSessionDownCount>0</neighborSignaledSessionDownCount>

€€€€€<concatenatedPathDownCount>0</concatenatedPathDownCount>

€€€</bfdDiagnostic>

€</tunnelStatus>

</hostStatus>

Working with tunnel connections for a specific host

GET /api/2.0/vdn/host/{hostId}/tunnel

URI Parameters:

hostId€€(required) ID of the host.

Description:

Retrieve tunnel connections for a specific host.

In NSX 6.4.6 or earlier, tunnel details are retrieved for a maximum of 1560 tunnels on the host. Starting in NSX 6.4.7,

tunnel details are retrieved for a maximum of 4096 tunnels on the host.

The tunnel API endpoint has a known limitation in a multi-site Cross-vCenter NSX deployment. In the API response,

the remoteNodeId will be Unknown if the remote host is not managed by the NSX Manager on which the API is run.

Method history:

Release Modification

NSX API Guide Version: 6.4 Page 78

6.4.0 Method introduced.

Request:

Body: application/xml

€<tunnel>

€€€<name>vxlan3232138659</name>

€€€<localIp>192.166.133.164</localIp>

€€€<remoteIp>192.166.133.163</remoteIp>

€€€<egressInterface>vmk1</egressInterface>

€€€<encap>vxlan</encap>

€€€<status>UP</status>

€€€<remoteNodeId>host-21</remoteNodeId>

€€€<latency>240</latency>

€€€<bfd>

€€€€€<remoteState>UP</remoteState>

€€€€€<remoteDiagnostic>NO_DIAGNOSTIC</remoteDiagnostic>

€€€€€<active>true</active>

€€€€€<state>UP</state>

€€€€€<forwarding>true</forwarding>

€€€€€<diagnostic>NO_DIAGNOSTIC</diagnostic>

€€€</bfd>

€</tunnel>

</bfdTunnels>

Working with remote host status

GET /api/2.0/vdn/host/{hostId}/remote-host-status

URI Parameters:

hostId€€(required) ID of the host.

Query Parameters:

source€€(optional) Specify source as REALTIME, or CACHED. Default

value is CACHED. Use status?source=REALTIME to get

current status. Use status?source=CACHED to get

cached status.

tunnel_status€€(optional) Specify UP, DOWN, or DEGRADED to filter by tunnel

status. Default value is NONE.

NSX API Guide Version: 6.4 Page 79

bfd_diagnostic_code€€(optional) This field is used to filter the remote hosts in current

host’s tunnel status detail list by the remoteDiagnostic

field, for the tunnel status detail list. BFD diagnostic code

of tunnel is as defined in RFC 5880. Allowed values are:

NO_DIAGNOSTIC,

CONTROL_DETECTION_TIME_EXPIRED,

ECHO_FUNCTION_FAILED,

NEIGHBOR_SIGNALED_SESSION_DOWN,

FORWARDING_PLANE_RESET, PATH_DOWN,

CONCATENATED_PATH_DOWN,

ADMINISTRATIVELY_DOWN,

REVERSE_CONCATENATED_PATH_DOWN.

Description:

Retrieve status of all remote hosts with tunnel connections to the given host.

The remote host status API endpoint has a known limitation in a multi-site Cross-vCenter NSX deployment. This API

returns the status of remote hosts that are managed by the NSX Manager on which the API is run. However, the status

of the remote hosts managed by other NSX Managers is not returned.

Method history:

Release Modification

6.4.0 Method introduced.

Request:

Body: application/xml

€<hostStatus>

€€€<hostId>host-12</hostId>

€€€<status>UP</status>

€€€<mgmtConnectionStatus>UP</mgmtConnectionStatus>

€€€<controlConnectionStatus>UP</controlConnectionStatus>

€€€<pnicStatus>

€€€€€<status>DISABLED</status>

€€€</pnicStatus>

€€€<tunnelStatus>

€€€€€<status>UP</status>

€€€€€<upCount>3</upCount>

€€€€€<downCount>0</downCount>

€€€€€<degradedCount>0</degradedCount>

€€€€€<bfdStatusCount>

€€€€€€€<bfdAdminDownCount>0</bfdAdminDownCount>

€€€€€€€<bfdUpCount>3</bfdUpCount>

€€€€€€€<bfdDownCount>0</bfdDownCount>

€€€€€€€<bfdInitCount>0</bfdInitCount>

€€€€€</bfdStatusCount>

€€€€€<bfdDiagnostic>

€€€€€€€<echoFunctionFailedCount>0</echoFunctionFailedCount>

€€€€€€€<noDiagnosticCount>3</noDiagnosticCount>

€€€€€€€<pathDownCount>0</pathDownCount>

€€€€€€€<administrativelyDownCount>0</administrativelyDownCount>

€€€€€€€<controlDetectionTimeExpiredCount>0</controlDetectionTimeExpiredCount>

€€€€€€€<forwardingPlaneResetCount>0</forwardingPlaneResetCount>

€€€€€€€<reverseConcatenatedPathDownCount>0</reverseConcatenatedPathDownCount>

€€€€€€€<neighborSignaledSessionDownCount>0</neighborSignaledSessionDownCount>

€€€€€€€<concatenatedPathDownCount>0</concatenatedPathDownCount>

NSX API Guide Version: 6.4 Page 80

€€€€€</bfdDiagnostic>

€€€</tunnelStatus>

€</hostStatus>

</hostStatusList>

NSX API Guide Version: 6.4 Page 81

Working With BFD Global Configuration

NSX Data Center uses Bidrectional Forwarding Detection (BFD) network protocol to obtain the tunnel health status and

the tunnel latency. By default, BFD is disabled.

In NSX 6.4.6 or earlier, when you enable BFD, monitoring of both tunnel latency and tunnel health is enabled. You

cannot separately turn on or turn off the monitoring of tunnel health and tunnel latency.

Starting in NSX 6.4.7, BFD global configuration includes two additional parameters to help you enable or disable the

monitoring of tunnel health and tunnel latency separately. These two parameters are tunnelReportEnabled and

tunnelLatencyEnabled.

BFD Parameters

Parameter Description Comments

enabled

Enable or disable BFD. In NSX 6.4.6

or earlier, this parameter enables

global BFD and monitoring of tunnel

health and tunnel latency. Starting in

NSX 6.4.7, this parameter enables

only global BFD.

Required. Options are True or False.

Default is False.

tunnelReportEnabled

Enable or disable monitoring of

tunnel health. This parameter is

available starting in NSX 6.4.7.

Optional. Options are True or False.

Default is False.

tunnelLatencyEnabled

Enable or disable monitoring of

tunnel latency. This parameter is

available starting in NSX 6.4.7.

Optional. Options are True or False.

Default is False.

pollingIntervalSecondsForHost Configure the BFD polling interval.

Optional. Value should be greater

than 30. Default value is 180.

bfdIntervalMillSecondsForHost

Configure the interval of BFD

session in milliseconds.

Optional. Value should be greater

than 300. Default value is 120000.

Valid Combinations of BFD Configuration Parameters

BFD Tunnel Report Tunnel Latency Result

False False False

When BFD is disabled,

monitoring of tunnel health

and tunnel latency must be

disabled. Turning on

tunnel health and tunnel

latency monitoring is not

permitted.

True True False

Only tunnel health is

monitored. Tunnel latency

is not monitored.

True True True

Both tunnel health and

tunnel latency are

monitored.

True False True

Only tunnel latency is

monitored. Tunnel health

is not monitored.

True False False

Both tunnel health and

tunnel latency are not

monitored.

NSX API Guide Version: 6.4 Page 82

GET /api/2.0/vdn/bfd/configuration/global

Description:

Retrieve the BFD global configuration.

Method history:

Release Modification

6.4.0 Method introduced.

6.4.7

Method updated. Added tunnelReportEnabled and

tunnelLatencyEnabled parameters.

Request:

Body: application/xml

€<enabled>false</enabled>

€<tunnelReportEnabled>true</tunnelReportEnabled>

€<tunnelLatencyEnabled>true</tunnelLatencyEnabled>

€<pollingIntervalSecondsForHost>180</pollingIntervalSecondsForHost>

€<bfdIntervalMillSecondsForHost>120000</bfdIntervalMillSecondsForHost>

</bfdGlobalConfiguration>

PUT /api/2.0/vdn/bfd/configuration/global

Description:

Update the BFD global configuration.

Method history:

Release Modification

6.4.0 Method introduced.

6.4.7

Method updated. Added tunnelReportEnabled and

tunnelLatencyEnabled parameters.

Responses:

Status Code: 200

Body: application/xml

€<enabled>true</enabled>

€<tunnelReportEnabled>true</tunnelReportEnabled>

€<tunnelLatencyEnabled>true</tunnelLatencyEnabled>

€<pollingIntervalSecondsForHost>190</pollingIntervalSecondsForHost>

€<bfdIntervalMillSecondsForHost>300</bfdIntervalMillSecondsForHost>

</bfdGlobalConfiguration>

NSX API Guide Version: 6.4 Page 83

Working With pNIC Configuration Information

Provides the status information about physical NIC (pNIC) global configuration. You can enable or disable pNIC to

monitor health of a host. By default, pNIC is disabled.

pNIC Parameters

Parameter Description Comments

enabled

Enable or disable pNIC to monitor

health of a host.

Required. Options are True or False.

Default is False.

pollingIntervalSecondsForHost

Configure the pNIC polling interval

for the host.

Required. Value should be greater

than 30. Default value is 180.

GET /api/2.0/vdn/pnic-check/configuration/global

Description:

Get pNIC status information.

Method history:

Release Modification

6.4.0 Method introduced.

Request:

Body: application/xml

€<enabled>false</enabled>

€<pollingIntervalSecondsForHost>180</pollingIntervalSecondsForHost>

</pnicStatusCheckGlobalConfiguration>

PUT /api/2.0/vdn/pnic-check/configuration/global

Description:

Update the global configuration for pNIC status check.

Method history:

Release Modification

6.4.0 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<enabled>true</enabled>

€<pollingIntervalSecondsForHost>120</pollingIntervalSecondsForHost>

</pnicStatusCheckGlobalConfiguration>

NSX API Guide Version: 6.4 Page 84

NSX API Guide Version: 6.4 Page 85

Working With Services Grouping Objects

Retrieve Services from a Specific Scope

GET /api/2.0/services/application/scope/{scopeId}

URI Parameters:

scopeId€€(required) Can be globalroot-0, universalroot-0 or datacenterId in

upgrade use cases.

Description:

Retrieve services that have been created on the specified scope.

Create a Service on a Specific Scope

POST /api/2.0/services/application/{scopeId}

Description:

Create a new service on the specified scope.

Request:

Body: application/xml

€<revision>0</revision>

€<name>TestService</name>

€<clientHandle></clientHandle>

€<isUniversal>false</isUniversal>

€<universalRevision>0</universalRevision>

€<inheritanceAllowed>true</inheritanceAllowed>

€<element>

€€€<applicationProtocol>MS_RPC_TCP</applicationProtocol>

€€€<value>420</value>

€</element>

</application>

Working With a Specified Service

GET /api/2.0/services/application/{applicationId}

URI Parameters:

NSX API Guide Version: 6.4 Page 86

applicationId€€(required) Application ID. You can get a list of application IDs from GET

/api/2.0/services/application/scope/{scopeId}.

Description:

Retrieve details about the specified service.

PUT /api/2.0/services/application/{applicationId}

URI Parameters:

applicationId€€(required) Application ID. You can get a list of application IDs from GET

/api/2.0/services/application/scope/{scopeId}.

Description:

Modify the name, description, applicationProtocol, or port value of a service.

Request:

Body: application/xml

€<objectId>application-371</objectId>

€<objectTypeName>Application</objectTypeName>

€<vsmUuid>422A532F-41FA-4388-AC80-12F967B51339</vsmUuid>

€<nodeId>8fd64272-b735-44b8-8b93-525a00a82d5d</nodeId>

€<revision>2</revision>

€<type>

€€€€€<typeName>Application</typeName>

€</type>

€<name>TestService-Renamed</name>

€<scope>

€€€€€<id>globalroot-0</id>

€€€€€<objectTypeName>GlobalRoot</objectTypeName>

€€€€€<name>Global</name>

€</scope>

€<clientHandle></clientHandle>

€<extendedAttributes></extendedAttributes>

€<isUniversal>false</isUniversal>

€<universalRevision>0</universalRevision>

€<inheritanceAllowed>true</inheritanceAllowed>

€<element>

€€€€€<applicationProtocol>MS_RPC_UDP</applicationProtocol>

€€€€€<value>500</value>

€</element>

</application>

DELETE /api/2.0/services/application/{applicationId}

URI Parameters:

applicationId€€(required) Application ID. You can get a list of application IDs from GET

/api/2.0/services/application/scope/{scopeId}.

Query Parameters:

NSX API Guide Version: 6.4 Page 87

force€€(optional) Determines if the delete should be forced or unforced.

Default is false.

If true, the object is deleted even if it is in use in other

places such as firewall rules, which invalidates other

configurations referring to the deleted object.

If false, the object is deleted only if it is not being used

by any other configuration.

Description:

Delete the specified service.

NSX API Guide Version: 6.4 Page 88

Working With Service Groups Grouping Objects

Creating Service Groups on a Specific Scope

POST /api/2.0/services/applicationgroup/{scopeId}

URI Parameters:

scopeId€€(required) The scopeId can be globalroot-0, universalroot-0 or

datacenterId in upgrade use cases.

Description:

Create a new service group on the specified scope.

Request:

Body: application/xml

€<description></description>

€<name></name>

€<revision></revision>

€<inheritanceAllowed></inheritanceAllowed>

</applicationGroup>

Working With Service Groups on a Specific Scope

GET /api/2.0/services/applicationgroup/scope/{scopeId}

URI Parameters:

scopeId€€(required) The scopeId can be globalroot-0, universalroot-0 or

datacenterId in upgrade use cases.

Description:

Retrieve a list of service groups that have been created on the scope.

Working With a Specific Service Group

GET /api/2.0/services/applicationgroup/{applicationgroupId}

URI Parameters:

NSX API Guide Version: 6.4 Page 89

applicationgroupId€€(required) Application group ID

Description:

Retrieve details about the specified service group.

PUT /api/2.0/services/applicationgroup/{applicationgroupId}

URI Parameters:

applicationgroupId€€(required) Application group ID

Description:

Modify the name, description, applicationProtocol, or port value of the specified service group.

Request:

Body: application/xml

€<objectId></objectId>

€<type>

€€€<typeName></typeName>

€</type>

€<name></name>

€<description></description>

€<revision></revision>

€<objectTypeName></objectTypeName>

€<scope>

€€€<id></id>

€€€<objectTypeName></objectTypeName>

€€€<name></name>

€</scope>

€<extendedAttributes></extendedAttributes>

€<inheritanceAllowed></inheritanceAllowed>

€<member>

€€€<objectId></objectId>

€€€<type>

€€€€€<typeName></typeName>

€€€</type>

€€€<name></name>

€€€<revision></revision>

€€€<objectTypeName></objectTypeName>

€€€<scope>

€€€€€<id></id>

€€€€€<objectTypeName></objectTypeName>

€€€€€<name></name>

€€€</scope>

€</member>

</applicationGroup>

DELETE /api/2.0/services/applicationgroup/{applicationgroupId}

URI Parameters:

applicationgroupId€€(required) Application group ID

Query Parameters:

NSX API Guide Version: 6.4 Page 90

force€€(optional) Determines if the delete should be forced or unforced.

Default is false.

If true, the object is deleted even if it is in use in other

places such as firewall rules, which invalidates other

configurations referring to the deleted object.

If false, the object is deleted only if it is not being used

by any other configuration.

Description:

Delete the specified service group (application group) from a scope.

Working With a Specific Service Group Member

PUT /api/2.0/services/applicationgroup/{applicationgroupId}/members/{moref}

URI Parameters:

moref€€(required) Managed object reference to the member.

applicationgroupId€€(required) Application group ID

Description:

Add a member to the service group.

DELETE /api/2.0/services/applicationgroup/{applicationgroupId}/members/{moref}

URI Parameters:

moref€€(required) Managed object reference to the member.

applicationgroupId€€(required) Application group ID

Description:

Delete a member from the service group.

Working With Service Group Members on a Specific Scope

GET /api/2.0/services/applicationgroup/scope/{scopeId}/members

URI Parameters:

scopeId€€(required) globalroot-0 or datacenterId in upgrade use cases

Description:

Get a list of member elements that can be added to the service groups created on a particular scope.

NSX API Guide Version: 6.4 Page 91

Working With IP Pool Grouping Objects

Working With IP Pools on a Specific Scope

GET /api/2.0/services/ipam/pools/scope/{scopeId}

URI Parameters:

scopeId€€(required) For scopeId use globalroot-0 or datacenterId in upgrade

use cases.

Description:

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.

Responses:

Status Code: 200

Body: application/xml

€<objectId>ipaddresspool-1</objectId>

€<objectTypeName>IpAddressPool</objectTypeName>

€<vsmUuid>4237BA90-C373-A71A-9827-1673BFA29498</vsmUuid>

€<revision>1</revision>

€<type>

€€€<typeName>IpAddressPool</typeName>

€</type>

€<name>rest-ip-pool-1</name>

€<extendedAttributes></extendedAttributes>

€<prefixLength>23</prefixLength>

€<gateway>192.168.1.1</gateway>

€<dnsSuffix>example.com</dnsSuffix>

€<dnsServer1>10.11.0.1</dnsServer1>

€<dnsServer2>10.11.0.2</dnsServer2>

€<ipRanges>

€€€<ipRangeDto>

€€€€€<id>iprange-1</id>

€€€€€<startAddress>192.168.1.2</startAddress>

€€€€€<endAddress>192.168.1.3</endAddress>

€€€</ipRangeDto>

€</ipRanges>

€<totalAddressCount>2</totalAddressCount>

€<usedAddressCount>0</usedAddressCount>

€<usedPercentage>0</usedPercentage>

</ipamAddressPool>

POST /api/2.0/services/ipam/pools/scope/{scopeId}

URI Parameters:

NSX API Guide Version: 6.4 Page 92

scopeId€€(required) For scopeId use globalroot-0 or datacenterId in upgrade

use cases.

Description:

Create a pool of IP addresses. For scopeId use globalroot-0 or the datacenterId in upgrade use cases.

Request:

Body: application/xml

€<name></name>

€<prefixLength></prefixLength>

€<gateway></gateway>

€<dnsSuffix></dnsSuffix>

€<dnsServer1></dnsServer1>

€<dnsServer2></dnsServer2>

€<ipRanges>

€€€<ipRangeDto>

€€€€€<startAddress></startAddress>

€€€€€<endAddress></endAddress>

€€€</ipRangeDto>

€</ipRanges>

</ipamAddressPool>

Working With a Specific IP Pool

GET /api/2.0/services/ipam/pools/{poolId}

URI Parameters:

poolId€€(required) Specify the pool ID as poolId in the URI.

Description:

Retrieve details about a specific IP pool.

Responses:

Status Code: 200

Body: application/xml

€<objectId>ipaddresspool-1</objectId>

€<objectTypeName>IpAddressPool</objectTypeName>

€<vsmUuid>4237BA90-C373-A71A-9827-1673BFA29498</vsmUuid>

€<revision>1</revision>

€<type>

€€€<typeName>IpAddressPool</typeName>

€</type>

€<name>rest-ip-pool-1</name>

€<extendedAttributes></extendedAttributes>

€<prefixLength>23</prefixLength>

€<gateway>192.168.1.1</gateway>

NSX API Guide Version: 6.4 Page 93

€<dnsSuffix>example.com</dnsSuffix>

€<dnsServer1>10.11.0.1</dnsServer1>

€<dnsServer2>10.11.0.2</dnsServer2>

€<ipRanges>

€€€<ipRangeDto>

€€€€€<id>iprange-1</id>

€€€€€<startAddress>192.168.1.2</startAddress>

€€€€€<endAddress>192.168.1.3</endAddress>

€€€</ipRangeDto>

€</ipRanges>

€<totalAddressCount>2</totalAddressCount>

€<usedAddressCount>0</usedAddressCount>

€<usedPercentage>0</usedPercentage>

</ipamAddressPool>

PUT /api/2.0/services/ipam/pools/{poolId}

URI Parameters:

poolId€€(required) Specify the pool ID as poolId in the URI.

Description:

To modify an IP pool, query the IP pool first. Then modify the output and send it back as the request body.

Request:

Body: application/xml

€<objectId></objectId>

€<objectTypeName></objectTypeName>

€<vsmUuid></vsmUuid>

€<revision></revision>

€<type>

€€€<typeName></typeName>

€</type>

€<name></name>

€<extendedAttributes></extendedAttributes>

€<prefixLength></prefixLength>

€<gateway></gateway>

€<dnsSuffix></dnsSuffix>

€<dnsServer1></dnsServer1>

€<dnsServer2></dnsServer2>

€<ipRanges>

€€€<ipRangeDto>

€€€€€<id></id>

€€€€€<startAddress></startAddress>

€€€€€<endAddress></endAddress>

€€€</ipRangeDto>

€</ipRanges>

</ipamAddressPool>

DELETE /api/2.0/services/ipam/pools/{poolId}

URI Parameters:

NSX API Guide Version: 6.4 Page 94

poolId€€(required) Specify the pool ID as poolId in the URI.

Description:

Delete an IP pool.

Working With IP Pool Address Allocations

GET /api/2.0/services/ipam/pools/{poolId}/ipaddresses

URI Parameters:

poolId€€(required) Specify the pool ID as poolId in the URI.

Description:

Retrieves all allocated IP addresses from the specified pool.

Responses:

Status Code: 200

Body: application/xml

€<allocatedIpAddress>

€€€<id>allocatedipaddress-4</id>

€€€<ipAddress>192.168.1.2</ipAddress>

€€€<gateway>192.168.1.1</gateway>

€€€<prefixLength>23</prefixLength>

€€€<dnsServer1>10.112.0.1</dnsServer1>

€€€<dnsServer2>10.112.0.2</dnsServer2>

€€€<dnsSuffix>eng.vmware.com</dnsSuffix>

€€€<allocationNote>sample note</allocationNote>

€</allocatedIpAddress>

</allocatedIpAddresses>

POST /api/2.0/services/ipam/pools/{poolId}/ipaddresses

URI Parameters:

poolId€€(required) Specify the pool ID as poolId in the URI.

Description:

Allocate an IP address from the pool.

To allocate the next available IP, set allocationMode to ALLOCATE

€<allocationMode>ALLOCATE</allocationMode>

</ipAddressRequest>

To allocate a specific IP, set allocationMode to RESERVE and pass the IP to reserve in the ipAddress parameter.

NSX API Guide Version: 6.4 Page 95

€<allocationMode>RESERVE</allocationMode>

€<ipAddress>192.168.1.2</ipAddress>

</ipAddressRequest>

Request:

Body: application/xml

€<allocationMode>RESERVE</allocationMode>

€<ipAddress>192.168.1.2</ipAddress>

</ipAddressRequest>

Responses:

Status Code: 200

Body: application/xml

€<id>allocatedipaddress-1</id>

€<ipAddress>192.168.1.2</ipAddress>

€<gateway>192.168.1.1</gateway>

€<prefixLength>23</prefixLength>

€<dnsServer1>10.112.0.1</dnsServer1>

€<dnsServer2>10.112.0.2</dnsServer2>

€<dnsSuffix>eng.vmware.com</dnsSuffix>

€<allocationNote>sample note</allocationNote>

</allocatedIpAddress>

Working With Specific IPs Allocated to an IP Pool

DELETE /api/2.0/services/ipam/pools/{poolId}/ipaddresses/{ipAddress}

URI Parameters:

ipAddress€€(required) The IP address to release, e.g. 192.168.10.10.

poolId€€(required) Specify the pool ID as poolId in the URI.

Description:

Release an IP address allocation in the pool.

NSX API Guide Version: 6.4 Page 96

Working With Licensing

The licensing capacity usage API command reports usage of CPUs, VMs and concurrent users for the distributed

firewall and VXLAN. The licensing status API command displays details about the assigned license.

Working With Licensing Capacity

The licensing capacity usage API command reports usage of CPUs, VMs and concurrent users for the distributed

firewall and VXLAN.

GET /api/2.0/services/licensing/capacityusage

Description:

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.

Responses:

Status Code: 200

Body: application/xml

€<featureCapacityUsageInfo>

€€€<capacityUsageInfo>

€€€€€<capacityType>CPU_CAPACITY_TYPE</capacityType>

€€€€€<usageCount>16</usageCount>

€€€</capacityUsageInfo>

€€€<capacityUsageInfo>

€€€€€<capacityType>VM_CAPACITY_TYPE</capacityType>

€€€€€<usageCount>3</usageCount>

€€€</capacityUsageInfo>

€€€<capacityUsageInfo>

€€€€€<capacityType>CONCURRENT_USER_CAPACITY_TYPE</capacityType>

€€€€€<usageCount>3</usageCount>

€€€</capacityUsageInfo>

€€€<feature>dfw</feature>

€</featureCapacityUsageInfo>

€<featureCapacityUsageInfo>

€€€<capacityUsageInfo>

€€€€€<capacityType>CPU_CAPACITY_TYPE</capacityType>

€€€€€<usageCount>16</usageCount>

€€€</capacityUsageInfo>

€€€<capacityUsageInfo>

€€€€€<capacityType>VM_CAPACITY_TYPE</capacityType>

€€€€€<usageCount>3</usageCount>

€€€</capacityUsageInfo>

€€€<capacityUsageInfo>

€€€€€<capacityType>CONCURRENT_USER_CAPACITY_TYPE</capacityType>

€€€€€<usageCount>3</usageCount>

€€€</capacityUsageInfo>

NSX API Guide Version: 6.4 Page 97

€€€<feature>vxlan</feature>

€</featureCapacityUsageInfo>

</featureCapacityUsageList>

Working With Licensing Status

The licensing status API command displays details about the assigned license.

GET /api/2.0/services/licensing/status

Description:

Retrieve details about the assigned license.

Method history:

Release Modification

6.4.0 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<key>00000-00000-00000-00000-00000</key>

€<edition>NSX for vSphere - Enterprise (CPUs)</edition>

€<eval>false</eval>

€<expiry>1546214400000</expiry>

€<currentTime>1510035564506</currentTime>

</licenseStatus>

NSX API Guide Version: 6.4 Page 98

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.

Managing Security Tags

GET /api/2.0/services/securitytags/tag

Query Parameters:

isUniversal€€(optional) Set to true to view universal security tags only. Set to

false to view security tags local to that NSX Manager

only. To view all tags (tags local to that NSX Manager

plus universal tags), omit the action parameter.

startIndex€€(optional) The starting point for returning results.

pageSize€€(optional) The number of results to return. Default is 1024.

sortOrderAscending€€(optional) Sort in ascending order of start time (true or false).

sortBy€€(optional) Parameter to sort by. Default is objectId.

filterBy€€(optional) Parameter type to filter by. Options are objectId or

name.

filterValue€€(optional) Value for filterBy. For example, securitytag-1 if filterBy

is objectId, or IDS_IPS.threat=medium if filterBy is

name.

Description:

Retrieve all security tags.

Method history:

Release Modification

6.3.0

Method updated. Added isUniversal query parameter to

filter universal security tags.

6.3.3

Method updated. Output is now paginated. startIndex,

pageSize, sortOrderAscending, sortBy, filterBy, and

filterValue query parameters added.

Responses:

Status Code: 200

Body: application/xml

€<pagingInfo>

€€€<pageSize>1024</pageSize>

€€€<startIndex>0</startIndex>

€€€<totalCount>2</totalCount>

€€€<sortOrderAscending>true</sortOrderAscending>

€€€<sortBy>objectId</sortBy>

€</pagingInfo>

NSX API Guide Version: 6.4 Page 99

€<securityTag>

€€€<objectId>securitytag-1</objectId>

€€€<objectTypeName>SecurityTag</objectTypeName>

€€€<vsmUuid>42030D04-DA84-841C-B02B-3D0F845AF88A</vsmUuid>

€€€<nodeId>6438f0c2-593c-4237-b116-7c958fffa15b</nodeId>

€€€<revision>0</revision>

€€€<type>

€€€€€<typeName>SecurityTag</typeName>

€€€</type>

€€€<name>VULNERABILITY_MGMT.VulnerabilityFound.threat=high</name>

€€€<description>Tag indicates that the vulnerability found has a high threat level</description>

€€€<clientHandle></clientHandle>

€€€<extendedAttributes></extendedAttributes>

€€€<isUniversal>false</isUniversal>

€€€<universalRevision>0</universalRevision>

€€€<systemResource>true</systemResource>

€€€<vmCount>0</vmCount>

€</securityTag>

€<securityTag>

€€€<objectId>securitytag-10</objectId>

€€€<objectTypeName>SecurityTag</objectTypeName>

€€€<vsmUuid>42030D04-DA84-841C-B02B-3D0F845AF88A</vsmUuid>

€€€<nodeId>6438f0c2-593c-4237-b116-7c958fffa15b</nodeId>

€€€<revision>0</revision>

€€€<type>

€€€€€<typeName>SecurityTag</typeName>

€€€</type>

€€€<name>IDS_IPS.threat=medium</name>

€€€<description>Tag indicates that the data violation detected has a medium threat level</description>

€€€<clientHandle></clientHandle>

€€€<extendedAttributes></extendedAttributes>

€€€<isUniversal>false</isUniversal>

€€€<universalRevision>0</universalRevision>

€€€<systemResource>true</systemResource>

€€€<vmCount>0</vmCount>

€</securityTag>

</securityTags>

POST /api/2.0/services/securitytags/tag

Description:

Create a new security tag.

Method history:

Release Modification

6.3.0

Method updated. isUniversal parameter can be set to

create a universal security tag.

Request:

Body: application/xml

€<objectTypeName>SecurityTag</objectTypeName>

€<type>

NSX API Guide Version: 6.4 Page 100

€€€<typeName>SecurityTag</typeName>

€</type>

€<name>TAG_NAME</name>

€<isUniversal>true</isUniversal>

€<description>description of the tag</description>

€<extendedAttributes></extendedAttributes>

</securityTag>

Delete a Security Tag

DELETE /api/2.0/services/securitytags/tag/{tagId}

URI Parameters:

tagId€€(required) Specified security tag.

Query Parameters:

force€€(optional) When the tag is in use and you want to delete the tag,

provide ?force=true in the API.

Description:

Delete the specified security tag.

Working With Virtual Machines on a Specific Security Tag

GET /api/2.0/services/securitytags/tag/{tagId}/vm

URI Parameters:

tagId€€(required) Specified security tag.

Description:

Retrieve the list of VMs that have the specified tag attached to them.

POST /api/2.0/services/securitytags/tag/{tagId}/vm

URI Parameters:

tagId€€(required) Specified security tag.

Query Parameters:

action€€(required) Action to perform: attach or detach specified security tag

from the VMs listed in the request body.

Description:

Attach or detach a security tag to a virtual machine.

NSX API Guide Version: 6.4 Page 101

This operation does not check that the virtual machine exists in the local inventory. This allows you to attach a

universal security tag to a virtual machine that is connected to a secondary NSX Manager (and therefore is not

connected to the primary NSX Manager where the call is sent).

Possible keys for the tagParameter are:

• instance_uuid

• bios_uuid

• vmname

Method history:

Release Modification

6.3.0 Method introduced.

Request:

Body: application/xml

€<tagParameter>

€€<key>instance_uuid</key>

€€<value>123e4567-e89b-12d3-a456-426655440000</value>

€</tagParameter>

</securityTagAssignment>

Manage a Security Tag on a Virtual Machine

PUT /api/2.0/services/securitytags/tag/{tagId}/vm/{vmId}

URI Parameters:

vmId€€(required) Specify VM using VM managed object ID or VM instance

UUID.

tagId€€(required) Specified security tag.

Description:

Apply a security tag to the specified virtual machine.

Note: this method can attach a universal security tag to a virtual machine. However, this method checks that the VM

exists on the NSX Manager to which the API call is sent. In a cross-vCenter active active environment, the VM might

exist on a secondary NSX Manager, and so the call would fail.

You can instead use the POST /api/2.0/services/securitytags/tag/{tagId}/vm?action=attach

method to attach universal security tags to a VM that is not local to the primary NSX Manager. This method does not

check that the VM is local to the NSX Manager.

DELETE /api/2.0/services/securitytags/tag/{tagId}/vm/{vmId}

URI Parameters:

vmId€€(required) Specify VM using VM managed object ID or VM instance

UUID.

tagId€€(required) Specified security tag.

NSX API Guide Version: 6.4 Page 102

Description:

Detach a security tag from the specified virtual machine.

Working With Virtual Machine Details for a Specific Security Tag

GET /api/2.0/services/securitytags/tag/{tagId}/vmDetail

URI Parameters:

tagId€€(required) Specified security tag.

Description:

Retrieve details about the VMs that are attached to the specified security tag.

Method history:

Release Modification

6.3.0 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<attachedVM>

€€€<objectId>vm-17</objectId>

€€€<objectTypeName>VirtualMachine</objectTypeName>

€€€<vsmUuid>564D5E43-1A21-9061-CE62-16E4E64FBC52</vsmUuid>

€€€<revision>1</revision>

€€€<type>

€€€€€<typeName>VirtualMachine</typeName>

€€€</type>

€€€<name>Ubuntu2</name>

€€€<scope>

€€€€€<id>domain-c7</id>

€€€€€<objectTypeName>ClusterComputeResource</objectTypeName>

€€€€€<name>sp cluster</name>

€€€</scope>

€€€<clientHandle></clientHandle>

€€€<isUniversal>false</isUniversal>

€€€<universalRevision>0</universalRevision>

€€€<instanceUUID>520932b3-b531-7b4a-d3fe-76f0fdd82736</instanceUUID>

€€€<biosUUID>423f7c14-6463-8ebc-d06d-2a284b24cabb</biosUUID>

€</attachedVM>

€<attachedVM>

€€€<objectId>vm-59</objectId>

€€€<objectTypeName>VirtualMachine</objectTypeName>

€€€<vsmUuid>564D5E43-1A21-9061-CE62-16E4E64FBC52</vsmUuid>

€€€<revision>1</revision>

€€€<type>

€€€€€<typeName>VirtualMachine</typeName>

€€€</type>

NSX API Guide Version: 6.4 Page 103

€€€<name>vShield-FW (1)</name>

€€€<scope>

€€€€€<id>domain-c7</id>

€€€€€<objectTypeName>ClusterComputeResource</objectTypeName>

€€€€€<name>sp cluster</name>

€€€</scope>

€€€<clientHandle></clientHandle>

€€€<isUniversal>false</isUniversal>

€€€<universalRevision>0</universalRevision>

€€€<instanceUUID>502777a8-a4b0-6b1e-1af1-6ab43f3417a0</instanceUUID>

€€€<biosUUID>42278ffc-021c-cd1f-1413-978f34079593</biosUUID>

€</attachedVM>

</attachedVMList>

Working With Security Tags on a Specific Virtual Machine

GET /api/2.0/services/securitytags/vm/{vmId}

URI Parameters:

vmId€€(required) Specify VM using VM managed object ID or VM instance

UUID.

Description:

Retrieve all security tags associated with the specified virtual machine.

POST /api/2.0/services/securitytags/vm/{vmId}

URI Parameters:

vmId€€(required) Specify VM using VM managed object ID or VM instance

UUID.

Query Parameters:

action€€(required) Action to perform. ASSIGN_TAGS or

CLEAR_ALL_TAGS.

Description:

Update security tags associated with the specified virtual machine.

You can assign multiple tags at a time to the specified VM, or clear all assigned tags from the specified VM.

Method history:

Release Modification

6.3.0 Method introduced.

Request:

NSX API Guide Version: 6.4 Page 104

Body: application/xml

€<securityTag>

€€€<objectId>securitytag-12</objectId>

€</securityTag>

€<securityTag>

€€€<objectId>securitytag-13</objectId>

€</securityTag>

€<securityTag>

€€€<objectId>securitytag-14</objectId>

€</securityTag>

</securityTags>

Working With Security Tags Unique ID Selection Criteria

In NSX versions before 6.3.0, security tags are local to a NSX Manager, and are mapped to VMs using the VM's

managed object ID.

In NSX 6.3.0 and later, you can create universal security tags to use in all NSX Managers in a cross-vCenter NSX

environment.

In an active standby environment, the managed object ID for a given VM might not be the same in the active and

standby datacenters. NSX 6.3.x introduces a Unique ID Selection Criteria on the primary NSX Manager to use to

identify VMs when attaching them to universal security tags only. You can use them singly or in combination. The VM

instance UUID is the recommended selection criteria. See the descriptions for more information.

The default value for the selection criteria is null and must be set before assigning a universal security tag to a VM. The

selection criteria can be set only on the primary NSX manager and is read-only on secondary NSX Managers.

Security Tag Assignment

Metadata Parameter Description

instance_uuid

The VM instance UUID is generally unique within a

vCenter domain, however there are exceptions such as

when deployments are made through snapshots. If the

VM instance UUID is not unique, you can use the VM

BIOS UUID in combination with the VM name.

bios_uuid

The BIOS UUID is not guaranteed to be unique within a

vCenter domain, but it is always preserved in case of

disaster. Use BIOS UUID in combination with VM name

to reduce the chance of a duplicate ID.

vmname

If all of the VM names in an environment are unique,

then VM name can be used to identify a VM across

vCenters. Use VM name in combination with VM BIOS

UUID to reduce the chance of a duplicate ID.

GET /api/2.0/services/securitytags/selection-criteria

Description:

Retrieve unique ID section criteria configuration.

Method history:

Release Modification

NSX API Guide Version: 6.4 Page 105

6.3.0 Method introduced.

PUT /api/2.0/services/securitytags/selection-criteria

Description:

Configure the unique ID section criteria configuration.

If you set the selection criteria and assign security tags to VMs, you must remove all security tags from VMs before you

can change the selection criteria.

Method history:

Release Modification

6.3.0 Method introduced.

Request:

Body: application/xml

€<metadata>instance_uuid</metadata>

</securityTagAssignmentMetadata>

NSX API Guide Version: 6.4 Page 106

Working With NSX Manager SSO Registration

GET /api/2.0/services/ssoconfig

Description:

Retrieve SSO Configuration.

Responses:

Status Code: 200

Body: application/xml

€<ssoLookupServiceUrl>https://vc-l-01a.corp.local:443/lookservice/sdk</ssoLookupServiceUrl>

€<ssoAdminUsername>[email protected]</ssoAdminUsername>

</ssoConfig>

POST /api/2.0/services/ssoconfig

Description:

Request:

Body: application/xml

€<ssoLookupServiceUrl></ssoLookupServiceUrl>

€<ssoAdminUsername></ssoAdminUsername>

€<ssoAdminUserpassword></ssoAdminUserpassword>

€<certificateThumbprint></certificateThumbprint>

</ssoConfig>

DELETE /api/2.0/services/ssoconfig

Description:

Deletes the NSX Manager SSO Configuration.

Working With SSO Configuration Status

GET /api/2.0/services/ssoconfig/status

Description:

Retrieve the SSO configuration status of NSX Manager.

NSX API Guide Version: 6.4 Page 107

Working With User Management

Manage Users on NSX Manager

GET /api/2.0/services/usermgmt/user/{userId}

URI Parameters:

userId€€(required) User ID. To specify a domain user, use user@domain

not domain\user.

Description:

Get information about a user.

DELETE /api/2.0/services/usermgmt/user/{userId}

URI Parameters:

userId€€(required) User ID. To specify a domain user, use user@domain

not domain\user.

Description:

Remove the NSX role for a vCenter user.

Working With User Account State

PUT /api/2.0/services/usermgmt/user/{userId}/enablestate/{value}

URI Parameters:

value€€(required) value can be 0 to disable, or 1 to enable.

userId€€(required) User ID. To specify a domain user, use user@domain

not domain\user.

Description:

You can disable or enable a user account, either local user or vCenter user. When a user account is created, the

account is enabled by default.

Manage NSX Roles for Users

Possible roles are:

• super_user - built-in admin user

• vshield_admin - NSX Administrator

• enterprise_admin - Enterprise Administrator

NSX API Guide Version: 6.4 Page 108

• security_admin - Security Administrator

• auditor - Auditor

• security_engineer - Security Engineer (introduced in NSX 6.4.2)

• network_engineer - Network Engineer (introduced in NSX 6.4.2)

• security_role_admin - Security & Role Administrator (introduced in NSX 6.4.5)

GET /api/2.0/services/usermgmt/role/{userId}

URI Parameters:

userId€€(required) User ID. To specify a domain user, use user@domain

not domain\user.

Description:

Retrieve a user's role.

PUT /api/2.0/services/usermgmt/role/{userId}

URI Parameters:

userId€€(required) User ID. To specify a domain user, use user@domain

not domain\user.

Description:

Change a user's role.

Method history:

Release Modification

6.4.2

Method updated. Added security_engineer and

network_engineer roles.

6.4.5 Method updated. Added security_role_admin role.

Request:

Body: application/xml

€<role></role>

€<resource>

€€€<resourceId></resourceId>

€</resource>

</accessControlEntry>

POST /api/2.0/services/usermgmt/role/{userId}

URI Parameters:

userId€€(required) User ID. To specify a domain user, use user@domain

not domain\user.

Query Parameters:

isGroup€€(required) Set to true to apply to a group; set to false to apply to an

individual user.

NSX API Guide Version: 6.4 Page 109

Description:

Add role and resources for a user.

Method history:

Release Modification

6.4.2

Method updated. Added security_engineer and

network_engineer roles.

6.4.5 Method updated. Added security_role_admin role.

Request:

Body: application/xml

€<role></role>

€<resource>

€€€<resourceId></resourceId>

€</resource>

</accessControlEntry>

DELETE /api/2.0/services/usermgmt/role/{userId}

URI Parameters:

userId€€(required) User ID. To specify a domain user, use user@domain

not domain\user.

Description:

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 /api/2.0/services/usermgmt/users/vsm

Description:

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

GET /api/2.0/services/usermgmt/roles

Description:

Read all possible roles in NSX Manager.

NSX API Guide Version: 6.4 Page 110

Method history:

Release Modification

6.4.2

Method updated. Added security_engineer and

network_engineer roles.

6.4.5 Method updated. Added security_role_admin role.

Responses:

Status Code: 200

Body: application/xml

<list>

€<string>super_user</string>

€<string>vshield_admin</string>

€<string>security_admin</string>

€<string>auditor</string>

€<string>enterprise_admin</string>

€<string>security_engineer</string>

€<string>network_engineer</string>

€<string>security_role_admin</string>

</list>

Working With Scoping Objects

GET /api/2.0/services/usermgmt/scopingobjects

Description:

Retrieve a list of objects that can be used to define a user's access scope.

NSX API Guide Version: 6.4 Page 111

Working with API Authentication

Working with Basic Authentication

GET /api/2.0/services/auth/basic

Description:

Retrieve basic authentication configuration.

Method history:

Release Modification

6.4.2 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<disableBasicAuth>false</disableBasicAuth>

</basicAuthStatus>

PUT /api/2.0/services/auth/basic

Description:

Update whether basic authentication is enabled.

Authentication headers are ignored, and the credentials used in the request body are used instead. This request works

whether or not basic authenication is enabled.

All NSX Manager systems in a cross-vCenter NSX environment must have the same enabled/disabled status for basic

authentication. If you disable basic authentication on one NSX Manager in a cross-vCenter NSX environment, you

must disable it on all NSX Manager systems in the environment.

Method history:

Release Modification

6.4.2 Method introduced.

Request:

Body: application/xml

<auth>

€<username>username</username>

€<password>password</password>

€<disableBasicAuth>false</disableBasicAuth>

</auth>

NSX API Guide Version: 6.4 Page 112

Working with API Tokens

You can create a JSON Web Token and use it to authenticate with the NSX Manager appliance in subsequent API

requests.

POST /api/2.0/services/auth/token

Query Parameters:

expiresInMinutes€€ Specify number of minutes for the token expiration. Valid

values are 1-1440.

Description:

Create a new authentication token.

You can use this token in your REST client to access the API. Send the token in the Authorization header with the

AUTHTOKEN keyword. See the documentation for your REST client for more information.

Example Authorization header:

Authorization: AUTHTOKEN eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTUyMDU1NTU0NH0.bX

PVyHp6uR4HmCmyIMcgJQIS-E1xeb6MLz_3BDk7Lzw

By default, this token is created with the default expiry value. You can also set a custom expiration using the

expiresInMinutes query parameter.

If a user authenticates with a token, and the user is deleted or their NSX access is disabled, their token will remain

valid until the token expires.

To create a token when basic authentication is disabled, see POST /api/3.0/services/auth/token.

Method history:

Release Modification

6.4.0 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<value>eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTUyMDU1NTU0NH0

€€€€€€€€.bXPVyHp6uR4HmCmyIMcgJQIS-E1xeb6MLz_3BDk7Lzw</value>

</authToken>

Working With API Token Expiration

You can configure the default expiry time of API tokens. New tokens are created with this expiry time.

GET /api/2.0/services/auth/tokenexpiration

NSX API Guide Version: 6.4 Page 113

Description:

Retrieve the default token expiry time.

Method history:

Release Modification

6.4.0 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<defaultExpiryInMinutes>180</defaultExpiryInMinutes>

</authTokenExpiry>

PUT /api/2.0/services/auth/tokenexpiration

Description:

Update the default token expiry time.

The default expiry time is 90 minutes. The maximum expiry time is 24 hours.

Method history:

Release Modification

6.4.0 Method introduced.

Request:

Body: application/xml

€<defaultExpiryInMinutes>90</defaultExpiryInMinutes>

</authTokenExpiry>

Working With Token Invalidation

POST /api/2.0/services/auth/tokeninvalidation

Query Parameters:

userId€€ Specify which user the token was created by. Specify

username (e.g. admin). Domain users can be specified

as either user@domain or domain\user.

Description:

Invalidate tokens created by the specified user.

NSX API Guide Version: 6.4 Page 114

Method history:

Release Modification

6.4.1 Method introduced.

NSX API Guide Version: 6.4 Page 115

Working with API Authentication

POST /api/3.0/services/auth/token

Query Parameters:

expiresInMinutes€€ Specify number of minutes for the token expiration. Valid

values are 1-1440.

Description:

Create a new authentication token.

Authentication headers are ignored, and the credentials used in the request body are used instead. This request works

whether or not Basic Authenication is enabled.

You can use this token in your REST client to access the API. Send the token in the Authorization header with the

AUTHTOKEN keyword. See the documentation for your REST client for more information.

Example Authorization header:

Authorization: AUTHTOKEN eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTUyMDU1NTU0NH0.bX

PVyHp6uR4HmCmyIMcgJQIS-E1xeb6MLz_3BDk7Lzw

By default, this token is created with the default expiry value (see GET/PUT

/api/2.0/services/auth/tokenexpiration). You can also set a custom expiration using the expiresInMinutes

query parameter.

If a user authenticates with a token, and the user is deleted or their NSX access is disabled, their token will remain

valid until the token expires.

Method history:

Release Modification

6.4.2 Method introduced.

Request:

Body: application/xml

€<username>test</username>

€<password>testing123!</password>

</credentials>

NSX API Guide Version: 6.4 Page 116

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

POST /api/2.0/services/securitygroup/bulk/{scopeId}

URI Parameters:

scopeId€€(required) For the scopeId use globalroot-0 for non-universal

security groups and universalroot-0 for universal security

groups.

Description:

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.

Request:

Body: application/xml

€<objectId></objectId>

€<objectTypeName></objectTypeName>

€<vsmUuid></vsmUuid>

€<revision></revision>

€<type>

NSX API Guide Version: 6.4 Page 117

€€€<typeName></typeName>

€</type>

€<name></name>

€<scope>

€€€<id></id>

€€€<objectTypeName></objectTypeName>

€€€<vsmUuid></vsmUuid>

€€€<name></name>

€€€<revision></revision>

€</scope>

€<clientHandle></clientHandle>

€<extendedAttributes>

€€€<extendedAttribute>

€€€€€<name>localMembersOnly</name>

€€€€€<value>true</value>

€€€</extendedAttribute>

€</extendedAttributes>

€<member>

€€€<objectId></objectId>

€€€<objectTypeName></objectTypeName>

€€€<vsmUuid></vsmUuid>

€€€<revision></revision>

€€€<type>

€€€€€<typeName></typeName>

€€€</type>

€€€<name></name>

€€€<scope>

€€€€€<id></id>

€€€€€<objectTypeName></objectTypeName>

€€€€€<name></name>

€€€</scope>

€€€<clientHandle></clientHandle>

€€€<extendedAttributes></extendedAttributes>

€</member>

€<excludeMember>

€€€<objectId></objectId>

€€€<objectTypeName></objectTypeName>

€€€<vsmUuid></vsmUuid>

€€€<revision></revision>

€€€<type>

€€€€€<typeName></typeName>

€€€</type>

€€€<name></name>

€€€<scope>

€€€€€<id></id>

€€€€€<objectTypeName></objectTypeName>

€€€€€<name></name>

€€€</scope>

€€€<clientHandle></clientHandle>

€€€<extendedAttributes></extendedAttributes>

€</excludeMember>

€<dynamicMemberDefinition>

€€€<dynamicSet>

€€€€€<operator></operator>

€€€€€<dynamicCriteria>

€€€€€€€<operator></operator>

€€€€€€€<key></key>

€€€€€€€<criteria></criteria>

€€€€€€€<value></value>

€€€€€</dynamicCriteria>

€€€</dynamicSet>

€</dynamicMemberDefinition>

NSX API Guide Version: 6.4 Page 118

</securitygroup>

Creating New Security Groups Without Members

POST /api/2.0/services/securitygroup/{scopeId}

URI Parameters:

scopeId€€(required) For the scopeId use globalroot-0 for non-universal

security groups and universalroot-0 for universal security

groups.

Description:

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.

Request:

Body: application/xml

€<name></name>

€<extendedAttributes>

€€€<extendedAttribute>

€€€€€<name>localMembersOnly</name>

€€€€€<value>true</value>

€€€</extendedAttribute>

€</extendedAttributes>

NSX API Guide Version: 6.4 Page 119

</securitygroup>

Updating a Specific Security Group Including Membership

PUT /api/2.0/services/securitygroup/bulk/{objectId}

URI Parameters:

objectId€€(required) Security group ID.

Description:

Update configuration for the specified security group, including membership information.

Request:

Body: application/xml

€<objectId></objectId>

€<objectTypeName></objectTypeName>

€<vsmUuid></vsmUuid>

€<revision></revision>

€<type>

€€€<typeName></typeName>

€</type>

€<name></name>

€<scope>

€€€<id></id>

€€€<objectTypeName></objectTypeName>

€€€<vsmUuid></vsmUuid>

€€€<name></name>

€€€<revision></revision>

€</scope>

€<clientHandle></clientHandle>

€<extendedAttributes></extendedAttributes>

€<member>

€€€<objectId></objectId>

€€€<objectTypeName></objectTypeName>

€€€<vsmUuid></vsmUuid>

€€€<revision></revision>

€€€<type>

€€€€€<typeName></typeName>

€€€</type>

€€€<name></name>

€€€<scope>

€€€€€<id></id>

€€€€€<objectTypeName></objectTypeName>

€€€€€<name></name>

€€€</scope>

€€€<clientHandle></clientHandle>

€€€<extendedAttributes></extendedAttributes>

€</member>

€<excludeMember>

€€€<objectId></objectId>

NSX API Guide Version: 6.4 Page 120

€€€<objectTypeName></objectTypeName>

€€€<vsmUuid></vsmUuid>

€€€<revision></revision>

€€€<type>

€€€€€<typeName></typeName>

€€€</type>

€€€<name></name>

€€€<scope>

€€€€€<id></id>

€€€€€<objectTypeName></objectTypeName>

€€€€€<name></name>

€€€</scope>

€€€<clientHandle></clientHandle>

€€€<extendedAttributes></extendedAttributes>

€</excludeMember>

€<dynamicMemberDefinition>

€€€<dynamicSet>

€€€€€<operator></operator>

€€€€€<dynamicCriteria>

€€€€€€€<operator></operator>

€€€€€€€<key></key>

€€€€€€€<criteria></criteria>

€€€€€€€<value></value>

€€€€€</dynamicCriteria>

€€€</dynamicSet>

€</dynamicMemberDefinition>

</securitygroup>

Working With a Specific Security Group

GET /api/2.0/services/securitygroup/{objectId}

URI Parameters:

objectId€€(required) Security group ID.

Description:

Retrieve all members of the specified security group.

PUT /api/2.0/services/securitygroup/{objectId}

URI Parameters:

objectId€€(required) Security group ID.

Description:

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.

Request:

Body: application/xml

NSX API Guide Version: 6.4 Page 121

€<objectId></objectId>

€<objectTypeName></objectTypeName>

€<revision></revision>

€<type>

€€€<typeName></typeName>

€</type>

€<name></name>

€<scope>

€€€<id></id>

€€€<objectTypeName></objectTypeName>

€€€<name></name>

€</scope>

€<clientHandle></clientHandle>

€<extendedAttributes></extendedAttributes>

€<isUniversal></isUniversal>

€<inheritanceAllowed></inheritanceAllowed>

</securitygroup>

DELETE /api/2.0/services/securitygroup/{objectId}

URI Parameters:

objectId€€(required) Security group ID.

Query Parameters:

force€€(optional) Use force=true to force removal of security group that is

in use in other configurations.

Description:

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

PUT /api/2.0/services/securitygroup/{objectId}/members/{memberId}

URI Parameters:

memberId€€(required) Security group member, can be a vSphere managed

object ID or NSX object ID.

objectId€€(required) Security group ID.

Query Parameters:

NSX API Guide Version: 6.4 Page 122

failIfExists€€(optional) Default is true.

If failIfExists=false:

• If the member is not already present in the

SecurityGroup, the API adds the member to the

SecurityGroup.

• If the member is already present in the SecurityGroup,

the API will be a no-op and will return silently.

If failIfExists=true:

• If the member is not already present in the

SecurityGroup, the API adds the member to the

SecurityGroup.

• If the member is already present in the SecurityGroup,

the API call fails.

Description:

Add a new member to the specified security group.

DELETE /api/2.0/services/securitygroup/{objectId}/members/{memberId}

URI Parameters:

memberId€€(required) Security group member, can be a vSphere managed

object ID or NSX object ID.

objectId€€(required) Security group ID.

Query Parameters:

failIfAbsent€€(optional) Default is true.

If failIfAbsent=false:

• If the member is present in the SecurityGroup, the API

removes the member from the SecurityGroup.

• If the member is not present in the SecurityGroup, the

API call will be a no-op and will return silently.

If failIfExists=true:

• If the member is present in the SecurityGroup, the API

removes the member from the SecurityGroup.

• If the member is not present in the SecurityGroup, the

API call fails.

Description:

Delete member from the specified security group.

Working With Virtual Machines in a Security Group

GET /api/2.0/services/securitygroup/{objectId}/translation/virtualmachines

URI Parameters:

objectId€€(required) Security group ID.

Description:

NSX API Guide Version: 6.4 Page 123

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

GET /api/2.0/services/securitygroup/{objectId}/translation/ipaddresses

URI Parameters:

objectId€€(required) Security group ID.

Description:

Retrieve list of IP addresses that belong to a specific security group.

Working With MAC Addresses in a Security Group

GET /api/2.0/services/securitygroup/{objectId}/translation/macaddresses

URI Parameters:

objectId€€(required) Security group ID.

Description:

Retrieve list of MAC addresses that belong to a specific security group.

Working With vNICs in a Security Group

GET /api/2.0/services/securitygroup/{objectId}/translation/vnics

URI Parameters:

objectId€€(required) Security group ID.

Description:

Retrieve list of vNICs that belong to a specific security group.

Working With Virtual Machine Security Group Membership

NSX API Guide Version: 6.4 Page 124

GET /api/2.0/services/securitygroup/lookup/virtualmachine/{virtualMachineId}

URI Parameters:

virtualMachineId€€(required) Specified virtual machine

Description:

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

GET /api/2.0/services/securitygroup/lookup/ipaddress/{ipAddress}

URI Parameters:

ipAddress€€(required) Specified IP address

Description:

Retrieve all the security groups that contain the specified IP address.

Request:

Body: application/xml

€<securityGroups>

€€€<securitygroup>

€€€€€<objectId>securitygroup-654</objectId>

€€€€€<objectTypeName>SecurityGroup</objectTypeName>

€€€€€<vsmUuid>42013FC7-556D-36E8-EB79-DF359AE8AC70</vsmUuid>

€€€€€<nodeId>a51981cd-18e1-4f55-abeb-079d61ca72fb</nodeId>

€€€€€<revision>5</revision>

€€€€€<type>

€€€€€€€<typeName>SecurityGroup</typeName>

€€€€€</type>

€€€€€<name>NSBU1-SG-AC-WORKDAY-DEV-XX-STATE-SMB</name>

€€€€€<description></description>

€€€€€<scope>

€€€€€€€<id>globalroot-0</id>

€€€€€€€<objectTypeName>GlobalRoot</objectTypeName>

€€€€€€€<name>Global</name>

€€€€€</scope>

€€€€€<clientHandle></clientHandle>

€€€€€<extendedAttributes></extendedAttributes>

€€€€€<isUniversal>false</isUniversal>

€€€€€<universalRevision>0</universalRevision>

€€€€€<inheritanceAllowed>false</inheritanceAllowed>

€€€€€<member>

€€€€€€€<objectId>vm-156</objectId>

€€€€€€€<objectTypeName>VirtualMachine</objectTypeName>

€€€€€€€<vsmUuid>42013FC7-556D-36E8-EB79-DF359AE8AC70</vsmUuid>

€€€€€€€<nodeId>a51981cd-18e1-4f55-abeb-079d61ca72fb</nodeId>

€€€€€€€<revision>7</revision>

€€€€€€€<type>

NSX API Guide Version: 6.4 Page 125

€€€€€€€€€<typeName>VirtualMachine</typeName>

€€€€€€€</type>

€€€€€€€<name>Web01</name>

€€€€€€€<scope>

€€€€€€€€€<id>resgroup-v151</id>

€€€€€€€€€<objectTypeName>VirtualApp</objectTypeName>

€€€€€€€€€<name>3 Tier App</name>

€€€€€€€</scope>

€€€€€€€<clientHandle></clientHandle>

€€€€€€€<extendedAttributes></extendedAttributes>

€€€€€€€<isUniversal>false</isUniversal>

€€€€€€€<universalRevision>0</universalRevision>

€€€€€</member>

€€€€€<member>

€€€€€€€<objectId>ipset-152</objectId>

€€€€€€€<objectTypeName>IPSet</objectTypeName>

€€€€€€€<vsmUuid>42013FC7-556D-36E8-EB79-DF359AE8AC70</vsmUuid>

€€€€€€€<nodeId>a51981cd-18e1-4f55-abeb-079d61ca72fb</nodeId>

€€€€€€€<revision>3</revision>

€€€€€€€<type>

€€€€€€€€€<typeName>IPSet</typeName>

€€€€€€€</type>

€€€€€€€<name>IPSET-INTERNAL-TRUST-ZGF-003</name>

€€€€€€€<description></description>

€€€€€€€<scope>

€€€€€€€€€<id>globalroot-0</id>

€€€€€€€€€<objectTypeName>GlobalRoot</objectTypeName>

€€€€€€€€€<name>Global</name>

€€€€€€€</scope>

€€€€€€€<clientHandle></clientHandle>

€€€€€€€<extendedAttributes></extendedAttributes>

€€€€€€€<isUniversal>false</isUniversal>

€€€€€€€<universalRevision>0</universalRevision>

€€€€€</member>

€€€</securitygroup>

€</securityGroups>

</securityGroups>

Working With Internal Security Groups

GET /api/2.0/services/securitygroup/internal/scope/{scopeId}

URI Parameters:

scopeId€€(required) Specified transport zone (scope)

Description:

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

NSX API Guide Version: 6.4 Page 126

GET /api/2.0/services/securitygroup/scope/{scopeId}

URI Parameters:

scopeId€€(required) scopeId can be globalroot-0, universalroot-0 or

datacenterID / portgroupID in upgrade use cases

Query Parameters:

populateMembers€€(optional) Display members of the security group. Default is true.

populateExtendedAttributes€€(optional) Display extended attributes of the security group. Default

is true.

Description:

List all the security groups created on a specific scope.

Method history:

Release Modification

6.4.7

Method updated. Added two new query parameters

populateMembers and populateExtendedAttributes.

Request:

Body: application/xml

€<securitygroup>

€€€<objectId>securitygroup-1</objectId>

€€€<objectTypeName>SecurityGroup</objectTypeName>

€€€<vsmUuid>42013FC7-556D-36E8-EB79-DF359AE8AC70</vsmUuid>

€€€<nodeId>a51981cd-18e1-4f55-abeb-079d61ca72fb</nodeId>

€€€<revision>5</revision>

€€€<type>

€€€€€<typeName>SecurityGroup</typeName>

€€€</type>

€€€<name></name>

€€€<description></description>

€€€<scope>

€€€€€<id>globalroot-0</id>

€€€€€<objectTypeName>GlobalRoot</objectTypeName>

€€€€€<name>Global</name>

€€€</scope>

€€€<clientHandle></clientHandle>

€€€<extendedAttributes></extendedAttributes>

€€€<isUniversal>false</isUniversal>

€€€<universalRevision>0</universalRevision>

€€€<inheritanceAllowed>false</inheritanceAllowed>

€€€<member>

€€€€€<objectId>vm-1</objectId>

€€€€€<objectTypeName>VirtualMachine</objectTypeName>

€€€€€<vsmUuid>42013FC7-556D-36E8-EB79-DF359AE8AC70</vsmUuid>

€€€€€<nodeId>a51981cd-18e1-4f55-abeb-079d61ca72fb</nodeId>

€€€€€<revision>7</revision>

€€€€€<type>

€€€€€€€<typeName>VirtualMachine</typeName>

€€€€€</type>

NSX API Guide Version: 6.4 Page 127

€€€€€<name>Web01</name>

€€€€€<scope>

€€€€€€€<id></id>

€€€€€€€<objectTypeName>VirtualApp</objectTypeName>

€€€€€€€<name>Three-Tier-App</name>

€€€€€</scope>

€€€€€<clientHandle></clientHandle>

€€€€€<extendedAttributes></extendedAttributes>

€€€€€<isUniversal>false</isUniversal>

€€€€€<universalRevision>0</universalRevision>

€€€</member>

€</securitygroup>

</securityGroups>

Working With Security Group Member Types

GET /api/2.0/services/securitygroup/scope/{scopeId}/memberTypes

URI Parameters:

scopeId€€(required) scopeId can be globalroot-0, universalroot-0 or

datacenterID / portgroupID in upgrade use cases

Description:

Retrieve a list of valid elements that can be added to a security group.

Working With a Specific Security Group Member Type

GET /api/2.0/services/securitygroup/scope/{scopeId}/members/{memberType}

URI Parameters:

memberType€€(required) Specific member type

scopeId€€(required) scopeId can be globalroot-0, universalroot-0 or

datacenterID / portgroupID in upgrade use cases

Description:

Retrieve members of a specific type in the specified scope.

NSX API Guide Version: 6.4 Page 128

Working With IP Set Grouping Objects

Working With IP Sets on a Specific Scope

GET /api/2.0/services/ipset/scope/{scopeMoref}

URI Parameters:

scopeMoref€€(required) For scopeMoref use globalroot-0 for non-universal IP

sets and use universalroot-0 for universal IP sets.

Query Parameters:

populateExtendedAttributes€€(optional) Display extended attributes of the IP set. Default is true.

Description:

Retrieve all configured IP sets.

Method history:

Release Modification

6.4.7

Method updated. Added populateExtendedAttributes

query parameter.

Request:

Body: application/xml

<ipset>

€<objectId>ipset-1</objectId>

€<objectTypeName>IPSet</objectTypeName>

€<vsmUuid>42271168-863F-EAA7-C3FD-BCFED40B77BB</vsmUuid>

€<nodeId>a8dfee54-210f-47f0-a9e3-401a350eb6d8</nodeId>

€<revision>2</revision>

€<type>

€€€<typeName>IPSet</typeName>

€</type>

€<name>sys-gen-empty-ipset-edge-fw</name>

€<scope>

€€€<id>globalroot-0</id>

€€€<objectTypeName>GlobalRoot</objectTypeName>

€€€<name>Global</name>

€</scope>

€<clientHandle></clientHandle>

€<extendedAttributes>

€€€<extendedAttribute>

€€€€€<name>isReadOnly</name>

€€€€€<value>true</value>

€€€</extendedAttribute>

€</extendedAttributes>

€<isUniversal>false</isUniversal>

€<universalRevision>0</universalRevision>

€<isTemporal>false</isTemporal>

NSX API Guide Version: 6.4 Page 129

€<inheritanceAllowed>true</inheritanceAllowed>

</ipset>

Creating New IP Sets

POST /api/2.0/services/ipset/{scopeMoref}

URI Parameters:

scopeMoref€€(required) For scopeMoref use globalroot-0 for non-universal IP

sets and use universalroot-0 for universal IP sets.

Description:

Create a new IP set.

Request:

Body: application/xml

<ipset>

€<objectId></objectId>

€<type>

€€€<typeName></typeName>

€</type>

€<description></description>

€<name></name>

€<objectTypeName></objectTypeName>

€<value></value>

€<inheritanceAllowed></inheritanceAllowed>

</ipset>

Working With a Specific IP Set

GET /api/2.0/services/ipset/{ipsetId}

URI Parameters:

ipsetId€€(required) The IP set to be queried or changed.

Description:

Retrieve an individual IP set.

Responses:

Status Code: 200

Body: application/xml

NSX API Guide Version: 6.4 Page 130

<ipset>

€<objectId>ipset-3</objectId>

€<type>

€€€<typeName>IPSet</typeName>

€</type>

€<description></description>

€<name>IPSET-2</name>

€<revision>1</revision>

€<objectTypeName>IPSet</objectTypeName>

€<value></value>

</ipset>

PUT /api/2.0/services/ipset/{ipsetId}

URI Parameters:

ipsetId€€(required) The IP set to be queried or changed.

Description:

Modify an existing IP set.

Request:

Body: application/xml

<ipset>

€€€<objectId>ipset-3</objectId>

€€€<type>

€€€€€<typeName>IPSet</typeName>

€€€</type>

€€€<description></description>

€€€<name>IPSET-2</name>

€€€<revision>1</revision>

€€€<objectTypeName>IPSet</objectTypeName>

€€€<value></value>

</ipset>

DELETE /api/2.0/services/ipset/{ipsetId}

URI Parameters:

ipsetId€€(required) The IP set to be queried or changed.

Query Parameters:

force€€(optional) Set to true when forcing the removal of an IP set.

Description:

Delete an IP set.

NSX API Guide Version: 6.4 Page 131

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 /api/2.0/services/vcconfig

Description:

Get vCenter Server configuration details on NSX Manager.

Responses:

Status Code: 200

Body: application/xml

€<ipAddress>vcsa-01a.corp.local</ipAddress>

€<userName>[email protected]</userName>

€<certificateThumbprint>D2:75:61:24:52:CA:B2:8D:D3:25:3F:78:11:2A:8F:94:5A:30:57:0D</certificateThumbprint>

€<assignRoleToUser>true</assignRoleToUser>

€<vcInventoryLastUpdateTime>1492567224920</vcInventoryLastUpdateTime>

</vcInfo>

PUT /api/2.0/services/vcconfig

Description:

Synchronize NSX Manager with vCenter server.

Request:

Body: application/xml

€<ipAddress>vc-l-01a.corp.local</ipAddress>

€<userName>[email protected]</userName>

€<password>VMware123</password>

€<certificateThumbprint>D2:75:61:24:52:CA:B2:8D:D3:25:3F:78:11:2A:8F:94:5A:30:57:0D</certificateThumbprint>

€<assignRoleToUser>true</assignRoleToUser>

€<pluginDownloadServer></pluginDownloadServer>

€<pluginDownloadPort></pluginDownloadPort>

NSX API Guide Version: 6.4 Page 132

</vcInfo>

Connection Status for vCenter Server

GET /api/2.0/services/vcconfig/status

Description:

Get default vCenter Server connection status.

Responses:

Status Code: 200

Body: application/xml

€<connected>true</connected>

€<lastInventorySyncTime>1492568145678</lastInventorySyncTime>

</vcConfigStatus>

Working with vCenter Server Connection

Validates the vCenter connection by actually trying connection to vCenter Server with the available credentials instead

of the cached state. Returns true if vCenter connectivity is successful and false if fails. If the vCenter connectivity has

issues, then it disconnects the default connection.

Note: If previously connected, this API tries to re-connect to the vCenter Server which may take time to respond. If

vCenter Server is non-responsive, then the API may result in timeout error.

Method history:

Release Modification

6.4.0 Method introduced.

POST /api/2.0/services/vcconfig/connectionstatus

Query Parameters:

action€€(optional) Use action=update to update the vCenter connection. If

the action is not specified then the default value is

update.

Description:

Update the vCenter Server connection status.

NSX API Guide Version: 6.4 Page 133

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.

GET /api/2.0/services/housekeeping/management/index_maintenance

Description:

Retrieve the default settings for the index maintenance activities.

Method history:

Release Modification

6.3.3 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<moduleName>index_maintenance</moduleName>

€<housekeepingEnabled>true</housekeepingEnabled>

€<scheduleType>cron</scheduleType>

€<scheduleTimeMillis>0</scheduleTimeMillis>

€<cronExpression>0 0 0 1-7 * SAT</cronExpression>

</housekeepingModule>

PUT /api/2.0/services/housekeeping/management/index_maintenance

Description:

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/CronSequenceGener

ator.html

• http://www.manpagez.com/man/5/crontab/

Method history:

Release Modification

6.3.3 Method introduced.

Request:

Body: application/xml

NSX API Guide Version: 6.4 Page 134

€<moduleName>index_maintenance</moduleName>

€<housekeepingEnabled>true</housekeepingEnabled>

€<scheduleTimeMillis>0</scheduleTimeMillis>

€<cronExpression>0 0 0 1-5 * SAT</cronExpression>

</housekeepingModule>

POST /api/2.0/services/housekeeping/management/index_maintenance

Query Parameters:

action€€(required) Use action=invokenow to trigger the reindexing task.

Description:

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.

NSX API Guide Version: 6.4 Page 135

Configuring the High CPU Usage Reporting Tool

You can configure the monitoring of high CPU usage for a defined time period using the High CPU Usage Reporting

tool. The CPU Usage Monitoring Tool uses this configuration to monitor CPU utilization of the NSX Manager. You can

configure the parameter values to monitor the CPU utilization.

CPU Configuration Parameters

Parameter Comments

delay Time between two monitoring sessions in milliseconds.

intervals

The number of monitoring sessions. This is a positive

integer value.

highcputhreshold

Enter threshold value for high CPU usage. Threshold

value is a percentage value ranging from 1 to 100.

mediumcputhreshold

Enter threshold value for medium CPU usage. Threshold

value is a percentage value ranging from 1 to 100.

monitoringfeatureenabled

Enter true to enable CPU usage monitoring feature.

Enter false to disable CPU usage monitoring feature.

Method history:

Release Modification

6.4.0 Method introduced.

GET /api/2.0/services/configuration

Description:

Get the configuration details for the High CPU Usage Reporting Tool.

Responses:

Status Code: 200

Body: application/xml

€<configuration>

€€€<context>HighCPUReportingTool</context>

€€€<name>delay</name>

€€€<value>10000</value>

€</configuration>

€<configuration>

€€€<context>HighCPUReportingTool</context>

€€€<name>intervals</name>

€€€<value>3</value>

€</configuration>

€<configuration>

€€€<context>HighCPUReportingTool</context>

€€€<name>highcputhreshold</name>

€€€<value>10</value>

€</configuration>

€<configuration>

€€€<context>HighCPUReportingTool</context>

€€€<name>mediumcputhreshold</name>

€€€<value>5</value>

€</configuration>

NSX API Guide Version: 6.4 Page 136

€<configuration>

€€€<context>HighCPUReportingTool</context>

€€€<name>monitoringfeatureenabled</name>

€€€<value>true</value>

€</configuration>

</configurations>

PUT /api/2.0/services/configuration

Description:

Update the configuration for the High CPU Usage Reporting Tool.

Request:

Body: application/xml

€<configuration>

€€€<context>HighCPUReportingTool</context>

€€€<name>delay</name>

€€€<value>10000</value>

€</configuration>

€<configuration>

€€€<context>HighCPUReportingTool</context>

€€€<name>intervals</name>

€€€<value>3</value>

€</configuration>

€<configuration>

€€€<context>HighCPUReportingTool</context>

€€€<name>highcputhreshold</name>

€€€<value>10</value>

€</configuration>

€<configuration>

€€€<context>HighCPUReportingTool</context>

€€€<name>mediumcputhreshold</name>

€€€<value>5</value>

€</configuration>

€<configuration>

€€€<context>HighCPUReportingTool</context>

€€€<name>monitoringfeatureenabled</name>

€€€<value>true</value>

€</configuration>

</configurations>

NSX API Guide Version: 6.4 Page 137

Working with the CPU Usage Monitoring Tool

Monitoring tool monitors CPU usage of the NSX Manager. The configurations for the CPU usage are defined in the

High CPU Usage Reporting Tool. Monitoring tool displays values for CPU utilization as High, Medium, and Low.

Method history:

Release Modification

6.4.0 Method introduced.

Working With CPU Usage Indicator

GET /api/2.0/system-monitor/cpuusage/indicator

Description:

Retrieve the CPU utilization status and the CPU usage percentage.

Responses:

Status Code: 200

Body: application/xml

€<cpuUsageIndicator>HIGH</cpuUsageIndicator>

€<cpuUsagePercent>89</cpuUsagePercent>

</cpuUsageSummary>

Working With CPU Usage Details

GET /api/2.0/system-monitor/cpuusage/details

Description:

Retrieve the details of the module which is causing high CPU utilization for the NSX Manager.

Responses:

Status Code: 200

Body: application/xml

€<highCPUPeriodInSeconds>30</highCPUPeriodInSeconds>

€<cpuConsumedTasks>

€€€<taskCPUDetails>

€€€€€<moduleName>DynamicCriteriaEvaluation</moduleName>

€€€€€<taskType>com.vmware.vshield.vsm.task.utils.SimpleTaskManager$1</taskType>

€€€€€<totalTasks>66</totalTasks>

€€€€€<displayName>DynamicCriteriaEvaluation</displayName>

NSX API Guide Version: 6.4 Page 138

€€€€€<totalCPU>17274</totalCPU>

€€€</taskCPUDetails>

€</cpuConsumedTasks>

€<queuedTasks></queuedTasks>

</cpuUsageDetails>

NSX API Guide Version: 6.4 Page 139

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.

GET /api/2.0/universalsync/configuration/role

Description:

Retrieve the universal sync configuration role.

POST /api/2.0/universalsync/configuration/role

Query Parameters:

action€€(required) Set the role of the NSX manager. Possible values are

set-as-standalone, or set-as-primary. To set an NSX Manager as

secondary, use the POST

/api/2.0/universalsync/configuration/nsxmanagers

method on the primary NSX Manager.

Description:

Set the universal sync configuration role.

Working With Universal Sync Configuration of NSX Managers

GET /api/2.0/universalsync/configuration/nsxmanagers

Description:

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.

POST /api/2.0/universalsync/configuration/nsxmanagers

Description:

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.

NSX API Guide Version: 6.4 Page 140

Request:

Body: application/xml

€<nsxManagerIp></nsxManagerIp>

€<nsxManagerUsername></nsxManagerUsername>

€<nsxManagerPassword></nsxManagerPassword>

€<certificateThumbprint></certificateThumbprint>

€<isPrimary></isPrimary>

</nsxManagerInfo>

DELETE /api/2.0/universalsync/configuration/nsxmanagers

Description:

Delete secondary NSX manager configuration.

Universal Sync Configuration of a Specific NSX Manager

GET /api/2.0/universalsync/configuration/nsxmanagers/{nsxManagerID}

URI Parameters:

nsxManagerID€€(required) NSX Manager UUID.

Description:

Retrieve information about the specified secondary NSX Manager.

PUT /api/2.0/universalsync/configuration/nsxmanagers/{nsxManagerID}

URI Parameters:

nsxManagerID€€(required) NSX Manager UUID.

Description:

Update the the specified secondary NSX manager IP or thumbprint in the universal sync configuration.

Request:

Body: application/xml

€<uuid></uuid>

€<nsxManagerIp></nsxManagerIp>

€<certificateThumbprint></certificateThumbprint>

</nsxManagerInfo>

DELETE /api/2.0/universalsync/configuration/nsxmanagers/{nsxManagerID}

URI Parameters:

NSX API Guide Version: 6.4 Page 141

nsxManagerID€€(required) NSX Manager UUID.

Query Parameters:

force€€(optional) Force removal of a secondary NSX Manager. Options

are true and false.

Description:

Delete the specified secondary NSX Manager.

NSX Manager Synchronization

POST /api/2.0/universalsync/sync

Query Parameters:

action€€(required) Use invoke to sync all objects on the NSX Manager.

Description:

Sync all objects on the NSX Manager.

Working With Universal Sync Entities

GET /api/2.0/universalsync/entitystatus

Query Parameters:

objectType€€(required) Specify the object type. For example VdnScope.

objectId€€(required) Specify the objectID. For example globalvdnscope.

Description:

Retrieve the status of a universal sync entity.

Working With Universal Sync Status

GET /api/2.0/universalsync/status

Description:

Retrieve the universal sync status.

NSX API Guide Version: 6.4 Page 142

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

GET /api/1.0/appliance-management/global/info

Description:

Retrieve global information containing version information as well as current logged in user.

Responses:

Status Code: 200

Body: application/xml

€<currentLoggedInUser>admin</currentLoggedInUser>

€<versionInfo>

€€€<majorVersion>6</majorVersion>

€€€<minorVersion>2</minorVersion>

€€€<patchVersion>5</patchVersion>

€€€<buildNumber>4818372</buildNumber>

€</versionInfo>

</globalInfo>

Summary Information for NSX Manager

GET /api/1.0/appliance-management/summary/system

Description:

Retrieve system summary info such as address, DNS name, version, CPU, memory and storage.

Responses:

Status Code: 200

Body: application/xml

€<ipv4Address>192.168.110.15</ipv4Address>

€<dnsName>nsxmgr-01a</dnsName>

€<hostName>nsxmgr-01a</hostName>

€<applianceName>vShield Virtual Appliance Management</applianceName>

€<versionInfo>

NSX API Guide Version: 6.4 Page 143

€€€<majorVersion>6</majorVersion>

€€€<minorVersion>2</minorVersion>

€€€<patchVersion>5</patchVersion>

€€€<buildNumber>4818372</buildNumber>

€</versionInfo>

€<uptime>25 days, 21 hours, 51 minutes</uptime>

€<cpuInfoDto>

€€€<totalNoOfCPUs>4</totalNoOfCPUs>

€€€<capacity>2799 MHZ</capacity>

€€€<usedCapacity>49 MHZ</usedCapacity>

€€€<freeCapacity>2750 MHZ</freeCapacity>

€€€<usedPercentage>2</usedPercentage>

€</cpuInfoDto>

€<memInfoDto>

€€€<totalMemory>16025 MB</totalMemory>

€€€<usedMemory>5633 MB</usedMemory>

€€€<freeMemory>10392 MB</freeMemory>

€€€<usedPercentage>35</usedPercentage>

€</memInfoDto>

€<storageInfoDto>

€€€<totalStorage>86G</totalStorage>

€€€<usedStorage>22G</usedStorage>

€€€<freeStorage>64G</freeStorage>

€€€<usedPercentage>25</usedPercentage>

€</storageInfoDto>

€<currentSystemDate>Wednesday, 19 April 2017 06:02:32 AM UTC</currentSystemDate>

</systemSummary>

Component Information for NSX Manager

GET /api/1.0/appliance-management/summary/components

Description:

Retrieve summary of all available components and their status info.

Responses:

Status Code: 200

Body: application/xml

€<componentsByGroup class="tree-map">

€€€<entry>

€€€€€<string>COMMON</string>

€€€€€<components>

€€€€€€€<component>

€€€€€€€€€<componentId>VPOSTGRES</componentId>

€€€€€€€€€<name>vPostgres</name>

€€€€€€€€€<description>vPostgres - Database service</description>

€€€€€€€€€<status>RUNNING</status>

€€€€€€€€€<enabled>true</enabled>

€€€€€€€€€<showTechSupportLogs>false</showTechSupportLogs>

€€€€€€€€€<usedBy>

€€€€€€€€€€€<string>NSX</string>

NSX API Guide Version: 6.4 Page 144

€€€€€€€€€</usedBy>

€€€€€€€€€<componentGroup>COMMON</componentGroup>

€€€€€€€</component>

€€€€€€€<component>

€€€€€€€€€<componentId>RABBITMQ</componentId>

€€€€€€€€€<name>RabbitMQ</name>

€€€€€€€€€<description>RabbitMQ - Messaging service</description>

€€€€€€€€€<status>RUNNING</status>

€€€€€€€€€<enabled>true</enabled>

€€€€€€€€€<showTechSupportLogs>false</showTechSupportLogs>

€€€€€€€€€<usedBy>

€€€€€€€€€€€<string>NSX</string>

€€€€€€€€€</usedBy>

€€€€€€€€€<componentGroup>COMMON</componentGroup>

€€€€€€€</component>

€€€€€</components>

€€€</entry>

€€€<entry>

€€€€€<string>NSXGRP</string>

€€€€€<components>

€€€€€€€<component>

€€€€€€€€€<componentId>NSXREPLICATOR</componentId>

€€€€€€€€€<name>NSX Replicator</name>

€€€€€€€€€<description>NSX Replicator</description>

€€€€€€€€€<status>RUNNING</status>

€€€€€€€€€<enabled>true</enabled>

€€€€€€€€€<showTechSupportLogs>false</showTechSupportLogs>

€€€€€€€€€<uses>

€€€€€€€€€€€<string>NSX</string>

€€€€€€€€€</uses>

€€€€€€€€€<usedBy></usedBy>

€€€€€€€€€<componentGroup>NSXGRP</componentGroup>

€€€€€€€€€<versionInfo>

€€€€€€€€€€€<majorVersion>6</majorVersion>

€€€€€€€€€€€<minorVersion>2</minorVersion>

€€€€€€€€€€€<patchVersion>5</patchVersion>

€€€€€€€€€€€<buildNumber>4818383</buildNumber>

€€€€€€€€€</versionInfo>

€€€€€€€</component>

€€€€€€€<component>

€€€€€€€€€<componentId>NSX</componentId>

€€€€€€€€€<name>NSX Manager</name>

€€€€€€€€€<description>NSX Manager</description>

€€€€€€€€€<status>RUNNING</status>

€€€€€€€€€<enabled>true</enabled>

€€€€€€€€€<showTechSupportLogs>true</showTechSupportLogs>

€€€€€€€€€<uses>

€€€€€€€€€€€<string>VPOSTGRES</string>

€€€€€€€€€€€<string>RABBITMQ</string>

€€€€€€€€€</uses>

€€€€€€€€€<usedBy>

€€€€€€€€€€€<string>NSXREPLICATOR</string>

€€€€€€€€€</usedBy>

€€€€€€€€€<componentGroup>NSXGRP</componentGroup>

€€€€€€€€€<versionInfo>

€€€€€€€€€€€<majorVersion>6</majorVersion>

€€€€€€€€€€€<minorVersion>2</minorVersion>

€€€€€€€€€€€<patchVersion>5</patchVersion>

€€€€€€€€€€€<buildNumber>4818372</buildNumber>

€€€€€€€€€</versionInfo>

€€€€€€€</component>

€€€€€</components>

NSX API Guide Version: 6.4 Page 145

€€€</entry>

€€€<entry>

€€€€€<string>SYSTEM</string>

€€€€€<components>

€€€€€€€<component>

€€€€€€€€€<componentId>SSH</componentId>

€€€€€€€€€<name>SSH Service</name>

€€€€€€€€€<description>Secure Shell</description>

€€€€€€€€€<status>RUNNING</status>

€€€€€€€€€<enabled>true</enabled>

€€€€€€€€€<showTechSupportLogs>false</showTechSupportLogs>

€€€€€€€€€<usedBy></usedBy>

€€€€€€€€€<componentGroup>SYSTEM</componentGroup>

€€€€€€€</component>

€€€€€</components>

€€€</entry>

€</componentsByGroup>

</componentsSummary>

Reboot NSX Manager

POST /api/1.0/appliance-management/system/restart

Description:

Reboot the NSX Manager appliance.

NSX Manager Appliance CPU Information

GET /api/1.0/appliance-management/system/cpuinfo

Description:

Retrieve NSX Manager Appliance CPU information.

Method history:

Release Modification

6.4.0 Method updated. Added cpuUsageIndicator parameter.

Responses:

Status Code: 200

Body: application/xml

€<totalNoOfCPUs>4</totalNoOfCPUs>

€<capacity>2799 MHZ</capacity>

€<usedCapacity>47 MHZ</usedCapacity>

€<freeCapacity>2752 MHZ</freeCapacity>

NSX API Guide Version: 6.4 Page 146

€<usedPercentage>2</usedPercentage>

€<cpuUsageIndicator>LOW</cpuUsageIndicator>

</cpuInfo>

NSX Manager Appliance CPU Details

GET /api/1.0/appliance-management/system/cpuinfo/details

Description:

Retrieve details about CPU utilization for the NSX Manager Appliance.

Method history:

Release Modification

6.4.0 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<highCPUPeriodInSeconds>30</highCPUPeriodInSeconds>

€<cpuConsumedTasks>

€€€<taskCPUDetails>

€€€€€<moduleName>DynamicCriteriaEvaluation</moduleName>

€€€€€<taskType>com.vmware.vshield.vsm.task.utils.SimpleTaskManager$1</taskType>

€€€€€<totalTasks>66</totalTasks>

€€€€€<displayName>DynamicCriteriaEvaluation</displayName>

€€€€€<totalCPU>17274</totalCPU>

€€€</taskCPUDetails>

€</cpuConsumedTasks>

€<queuedTasks></queuedTasks>

</cpuUsageDetails>

NSX Manager Appliance Uptime Information

GET /api/1.0/appliance-management/system/uptime

Description:

Retrieve NSX Manager uptime information.

Example response:

25 days, 22 hours, 11 minutes

NSX API Guide Version: 6.4 Page 147

NSX Manager Appliance Memory Information

GET /api/1.0/appliance-management/system/meminfo

Description:

Retrieve NSX Manager memory information.

Responses:

Status Code: 200

Body: application/xml

€<totalMemory>16025 MB</totalMemory>

€<usedMemory>5633 MB</usedMemory>

€<freeMemory>10392 MB</freeMemory>

€<usedPercentage>35</usedPercentage>

</memInfo>

NSX Manager Appliance Storage Information

GET /api/1.0/appliance-management/system/storageinfo

Description:

Retrieve NSX Manager storage information.

Responses:

Status Code: 200

Body: application/xml

€<totalStorage>86G</totalStorage>

€<usedStorage>22G</usedStorage>

€<freeStorage>64G</freeStorage>

€<usedPercentage>25</usedPercentage>

</storageInfo>

NSX Manager Appliance Network Settings

GET /api/1.0/appliance-management/system/network

NSX API Guide Version: 6.4 Page 148

Description:

Retrieve network information for the NSX Manager appliance. i.e. host name, IP address, DNS settings.

Method history:

Release Modification

6.4.0

Method updated. New parameter dynamicIPAddress

added. The parameter tells whether the IP address of

the NSX Appliance Manager is dynamically allocated or

not. If dynamicIPAddress parameter is true, then the

Unconfigure ipv4/ipv6 button on the UI is disabled.

Responses:

Status Code: 200

Body: application/xml

€<hostName>nsxmgr-01a</hostName>

€<networkIPv4AddressDto>

€€€<ipv4Address>192.168.110.15</ipv4Address>

€€€<ipv4NetMask>255.255.255.0</ipv4NetMask>

€€€<ipv4Gateway>192.168.110.1</ipv4Gateway>

€</networkIPv4AddressDto>

€<dns>

€€€<ipv4Address>192.168.110.10</ipv4Address>

€€€<domainList>corp.local</domainList>

€€€<isDynamicIPAddress>true</isDynamicIPAddress>

€</dns>

</network>

PUT /api/1.0/appliance-management/system/network

Description:

Update network information for the NSX Manager appliance.

Request:

Body: application/xml

€<hostName>nsxmgr-01a</hostName>

€<networkIPv4AddressDto>

€€€<ipv4Address>192.168.110.15</ipv4Address>

€€€<ipv4NetMask>255.255.255.0</ipv4NetMask>

€€€<ipv4Gateway>192.168.110.1</ipv4Gateway>

€</networkIPv4AddressDto>

€<networkIPv6AddressDto>

€€€<ipv6Address>fdd1:0ebc:b724:d2f1:0000:8a7e:0360:5332</ipv6Address>

€€€<ipv6PrefixLength>64</ipv6PrefixLength>

€€€<ipv6Gateway>fdd1:0ebc:b724:d2f1:0000:8a7e:0360:0002</ipv6Gateway>

€</networkIPv6AddressDto>

€<dns>

€€€<ipv4Address>192.168.110.10</ipv4Address>

NSX API Guide Version: 6.4 Page 149

€€€<ipv6Address>fdd1:0ebc:b724:d2f1:0000:8a7e:0360:0010</ipv6Address>

€€€<domainList>corp.local</domainList>

€</dns>

</network>

Working With DNS Configuration

PUT /api/1.0/appliance-management/system/network/dns

Description:

Configure DNS.

Request:

Body: application/xml

<dns>

€<ipv4Address></ipv4Address>

€<ipv6Address></ipv6Address>

€<domainList></domainList>

</dns>

DELETE /api/1.0/appliance-management/system/network/dns

Description:

Delete DNS server configuration.

Working With Security Settings

GET /api/1.0/appliance-management/system/securitysettings

Description:

Retrieve the NSX Manager FIPS and TLS settings.

Method history:

Release Modification

6.3.0 Method introduced.

Responses:

Status Code: 200

Body: application/xml

NSX API Guide Version: 6.4 Page 150

€<fipsEnabled>false</fipsEnabled>

€<tlsSettings>

€€€<serverEnabledProtocols>TLSv1,TLSv1.1,TLSv1.2</serverEnabledProtocols>

€€€<clientEnabledProtocols>TLSv1,TLSv1.1,TLSv1.2</clientEnabledProtocols>

€</tlsSettings>

</securitySettings>

POST /api/1.0/appliance-management/system/securitysettings

Description:

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.

Request:

Body: application/xml

€<fipsEnabled>true</fipsEnabled>

€<tlsSettings>

€€€<serverEnabledProtocols>TLSv1.1,TLSv1.2</serverEnabledProtocols>

€€€<clientEnabledProtocols>TLSv1.1,TLSv1.2</clientEnabledProtocols>

€</tlsSettings>

</securitySettings>

Working With TLS Settings

GET /api/1.0/appliance-management/system/tlssettings

Description:

Retrieve TLS settings.

Method history:

Release Modification

6.2.3 Method introduced.

Responses:

Status Code: 200

NSX API Guide Version: 6.4 Page 151

Body: application/xml

€<serverEnabledProtocols>TLSv1,TLSv1.1,TLSv1.2</serverEnabledProtocols>

€<clientEnabledProtocols>TLSv1,TLSv1.1,TLSv1.2</clientEnabledProtocols>

</tlsSettings>

POST /api/1.0/appliance-management/system/tlssettings

Description:

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.

Request:

Body: application/xml

€<serverEnabledProtocols>TLSv1.1,TLSv1.2</serverEnabledProtocols>

€<clientEnabledProtocols>TLSv1.1,TLSv1.2</clientEnabledProtocols>

</tlsSettings>

Working With Time Settings

You can either configure time or specify the NTP server to be used for time synchronization.

GET /api/1.0/appliance-management/system/timesettings

Description:

Retrieve time settings, like timezone or current date and time with NTP server, if configured.

Responses:

Status Code: 200

Body: application/xml

€<ntpServer>

€€€<string>192.168.110.1</string>

€</ntpServer>

€<datetime>04/19/2017 06:53:57</datetime>

€<timezone>UTC</timezone>

</timeSettings>

NSX API Guide Version: 6.4 Page 152

PUT /api/1.0/appliance-management/system/timesettings

Description:

Configure time or specify the NTP server to use for time synchronization.

Request:

Body: application/xml

€<ntpServer>

€€€<string>192.168.110.1</string>

€</ntpServer>

€<datetime>04/19/2017 06:53:57</datetime>

€<timezone>UTC</timezone>

</timeSettings>

Working With NTP Settings

DELETE /api/1.0/appliance-management/system/timesettings/ntp

Description:

Delete NTP server.

Configure System Locale

GET /api/1.0/appliance-management/system/locale

Description:

Retrieve locale info.

Responses:

Status Code: 200

Body: application/xml

€<language>en</language>

€<country>US</country>

</locale>

PUT /api/1.0/appliance-management/system/locale

NSX API Guide Version: 6.4 Page 153

Description:

Configure locale.

Request:

Body: application/xml

€<language>ja</language>

€<country>JP</country>

</locale>

Working With Syslog Server

GET /api/1.0/appliance-management/system/syslogserver

Description:

Retrieves only the first syslog server among the servers configured.

Responses:

Status Code: 200

Body: application/xml

€<syslogServer>192.168.110.20</syslogServer>

€<port>514</port>

€<protocol>UDP</protocol>

</syslogserver>

PUT /api/1.0/appliance-management/system/syslogserver

Description:

Configures one syslog server. If there are syslog server(s) already configured, this API replaces the first one in the list.

Request:

Body: application/xml

€€€<port>port-2</port>

€€€<protocol>protocol-2</protocol>

</syslogserver>

DELETE /api/1.0/appliance-management/system/syslogserver

Description:

NSX API Guide Version: 6.4 Page 154

Deletes all the syslog servers.

Working With Multiple Syslog Servers

GET /api/1.0/appliance-management/system/syslogservers

Description:

Retrieves all syslog servers configured on the NSX Manager.

Method history:

Release Modification

6.4.0 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€€€<syslogServer>name-1</syslogServer>

€€€<port>port-1</port>

€€€<protocol>protocol-1</protocol>

</syslogserver>

€€€<port>port-2</port>

€€€<protocol>protocol-2</protocol>

</syslogserver>

</syslogservers>

PUT /api/1.0/appliance-management/system/syslogservers

Description:

Configure one or more syslog servers. Unconfigures all servers that were previously configured, and configures the

one provided in the request body for this API.

Method history:

Release Modification

6.4.0 Method introduced.

Request:

Body: application/xml

€€€<syslogServer>name-1</syslogServer>

NSX API Guide Version: 6.4 Page 155

€€€<port>port-1</port>

€€€<protocol>protocol-1</protocol>

</syslogserver>

€€€<port>port-2</port>

€€€<protocol>protocol-2</protocol>

</syslogserver>

</syslogservers>

DELETE /api/1.0/appliance-management/system/syslogservers

Description:

Deletes all the syslog servers. Same as DELETE /system/syslogserver API.

Method history:

Release Modification

6.4.0 Method introduced.

Working With Components

The NSX Manager appliance has the following components.

Component Description

NSX NSX Manager

NSXREPLICATOR Universal Synchronization Service

RABBITMQ RabbitMQ - Messaging service

SSH SSH Service

VPOSTGRES vPostgres - Database service

GET /api/1.0/appliance-management/components

Description:

Retrieve all appliance manager components.

Responses:

Status Code: 200

Body: application/xml

€<component>

€€€<componentId>SSH</componentId>

€€€<name>SSH Service</name>

€€€<description>Secure Shell</description>

€€€<status>RUNNING</status>

€€€<enabled>true</enabled>

€€€<showTechSupportLogs>false</showTechSupportLogs>

€€€<usedBy></usedBy>

NSX API Guide Version: 6.4 Page 156

€€€<componentGroup>SYSTEM</componentGroup>

€</component>

€<component>

€€€<componentId>VPOSTGRES</componentId>

€€€<name>vPostgres</name>

€€€<description>vPostgres - Database service</description>

€€€<status>RUNNING</status>

€€€<enabled>true</enabled>

€€€<showTechSupportLogs>false</showTechSupportLogs>

€€€<usedBy>

€€€€€<string>NSX</string>

€€€</usedBy>

€€€<componentGroup>COMMON</componentGroup>

€</component>

€<component>

€€€<componentId>NSXREPLICATOR</componentId>

€€€<name>NSX Replicator</name>

€€€<description>NSX Replicator</description>

€€€<status>RUNNING</status>

€€€<enabled>true</enabled>

€€€<showTechSupportLogs>false</showTechSupportLogs>

€€€<uses>

€€€€€<string>NSX</string>

€€€</uses>

€€€<usedBy></usedBy>

€€€<componentGroup>NSXGRP</componentGroup>

€€€<versionInfo>

€€€€€<majorVersion>6</majorVersion>

€€€€€<minorVersion>2</minorVersion>

€€€€€<patchVersion>5</patchVersion>

€€€€€<buildNumber>4818383</buildNumber>

€€€</versionInfo>

€</component>

€<component>

€€€<componentId>RABBITMQ</componentId>

€€€<name>RabbitMQ</name>

€€€<description>RabbitMQ - Messaging service</description>

€€€<status>RUNNING</status>

€€€<enabled>true</enabled>

€€€<showTechSupportLogs>false</showTechSupportLogs>

€€€<usedBy>

€€€€€<string>NSX</string>

€€€</usedBy>

€€€<componentGroup>COMMON</componentGroup>

€</component>

€<component>

€€€<componentId>NSX</componentId>

€€€<name>NSX Manager</name>

€€€<description>NSX Manager</description>

€€€<status>RUNNING</status>

€€€<enabled>true</enabled>

€€€<showTechSupportLogs>true</showTechSupportLogs>

€€€<uses>

€€€€€<string>VPOSTGRES</string>

€€€€€<string>RABBITMQ</string>

€€€</uses>

€€€<usedBy>

€€€€€<string>NSXREPLICATOR</string>

€€€</usedBy>

€€€<componentGroup>NSXGRP</componentGroup>

€€€<versionInfo>

€€€€€<majorVersion>6</majorVersion>

NSX API Guide Version: 6.4 Page 157

€€€€€<minorVersion>2</minorVersion>

€€€€€<patchVersion>5</patchVersion>

€€€€€<buildNumber>4818372</buildNumber>

€€€</versionInfo>

€</component>

</components>

Working With a Specific Component

GET /api/1.0/appliance-management/components/component/{componentID}

URI Parameters:

componentID€€(required) Specified component ID.

Description:

Retrieve details for the specified component.

Responses:

Status Code: 200

Body: application/xml

€<componentId>NSX</componentId>

€<name>NSX Manager</name>

€<description>NSX Manager</description>

€<status>RUNNING</status>

€<enabled>true</enabled>

€<showTechSupportLogs>true</showTechSupportLogs>

€<uses>

€€€<string>VPOSTGRES</string>

€€€<string>RABBITMQ</string>

€</uses>

€<usedBy>

€€€<string>NSXREPLICATOR</string>

€</usedBy>

€<componentGroup>NSXGRP</componentGroup>

€<versionInfo>

€€€<majorVersion>6</majorVersion>

€€€<minorVersion>2</minorVersion>

€€€<patchVersion>5</patchVersion>

€€€<buildNumber>4818372</buildNumber>

€</versionInfo>

</component>

Working With Component Dependencies

NSX API Guide Version: 6.4 Page 158

GET

/api/1.0/appliance-management/components/component/{componentID}/dependencies

URI Parameters:

componentID€€(required) Specified component ID.

Description:

Retrieve dependency details for the specified component.

Responses:

Status Code: 200

Body: application/xml

<list>

€<string>VPOSTGRES</string>

€<string>RABBITMQ</string>

</list>

Working With Component Dependents

GET /api/1.0/appliance-management/components/component/{componentID}/dependents

URI Parameters:

componentID€€(required) Specified component ID.

Description:

Retrieve dependents for the specified component.

Responses:

Status Code: 200

Body: application/xml

<list>

€<string>NSXREPLICATOR</string>

</list>

Working With Component Status

GET /api/1.0/appliance-management/components/component/{componentID}/status

URI Parameters:

componentID€€(required) Specified component ID.

NSX API Guide Version: 6.4 Page 159

Description:

Retrieve current status for the specified component.

Responses:

Status Code: 200

Body: application/xml

€<result class="status">RUNNING</result>

€<operationStatus>SUCCESS</operationStatus>

</result>

Toggle Component Status

POST /api/1.0/appliance-management/components/component/{componentID}/toggleSta

tus/{command}

URI Parameters:

command€€(required) Use command parameter start or stop.

componentID€€(required) Specified component ID.

Description:

Start or stop a component.

Working With the Appliance Management Web Application

POST /api/1.0/appliance-management/components/component/APPMGMT/restart

Description:

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

NSX API Guide Version: 6.4 Page 160

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.

GET /api/1.0/appliance-management/backuprestore/backupsettings

Description:

Retrieve backup settings.

Responses:

Status Code: 200

Body: application/xml

€<ftpSettings>

€€€<transferProtocol>SFTP</transferProtocol>

€€€<hostNameIPAddress>10.2.56.199</hostNameIPAddress>

€€€<port>22</port>

NSX API Guide Version: 6.4 Page 161

€€€<userName>backup-user</userName>

€€€<backupDirectory>backups</backupDirectory>

€€€<filenamePrefix>SiteA_</filenamePrefix>

€€€<passiveMode>true</passiveMode>

€€€<useEPRT>false</useEPRT>

€€€<useEPSV>true</useEPSV>

€</ftpSettings>

€<backupFrequency>

€€€<frequency>WEEKLY</frequency>

€€€<dayOfWeek>SUNDAY</dayOfWeek>

€€€<hourOfDay>2</hourOfDay>

€€€<minuteOfHour>15</minuteOfHour>

€</backupFrequency>

€<excludeTables>

€€€<excludeTable>AUDIT_LOGS</excludeTable>

€</excludeTables>

</backupRestoreSettings>

PUT /api/1.0/appliance-management/backuprestore/backupsettings

Description:

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.

Request:

Body: application/xml

€<ftpSettings>

€€€<transferProtocol>SFTP</transferProtocol>

€€€<hostNameIPAddress>10.2.56.199</hostNameIPAddress>

€€€<port>22</port>

€€€<userName>backup-user</userName>

€€€<password>testing123</password>

€€€<backupDirectory>backups</backupDirectory>

€€€<filenamePrefix>SiteA_</filenamePrefix>

€€€<passPhrase>testing456</passPhrase>

€€€<passiveMode>true</passiveMode>

€€€<useEPRT>false</useEPRT>

€€€<useEPSV>true</useEPSV>

€</ftpSettings>

€<backupFrequency>

€€€<frequency>WEEKLY</frequency>

€€€<dayOfWeek>SUNDAY</dayOfWeek>

€€€<hourOfDay>2</hourOfDay>

€€€<minuteOfHour>15</minuteOfHour>

NSX API Guide Version: 6.4 Page 162

€</backupFrequency>

€<excludeTables>

€€€<excludeTable>AUDIT_LOGS</excludeTable>

€</excludeTables>

</backupRestoreSettings>

DELETE /api/1.0/appliance-management/backuprestore/backupsettings

Description:

Delete appliance manager backup configuration.

NSX Manager Appliance Backup FTP Settings

See NSX Manager Appliance Backup Settings for details.

PUT /api/1.0/appliance-management/backuprestore/backupsettings/ftpsettings

Description:

Configure FTP settings.

Method history:

Release Modification

6.3.3

Method updated. Parameters passiveMode

and useEPSV previously defaulted to false, now default

to true.

Request:

Body: application/xml

€<transferProtocol>SFTP</transferProtocol>

€<hostNameIPAddress>10.2.56.199</hostNameIPAddress>

€<port>22</port>

€<userName>backup-user</userName>

€<password>testing123</password>

€<backupDirectory>backups</backupDirectory>

€<filenamePrefix>SiteA_</filenamePrefix>

€<passPhrase>testing456</passPhrase>

€<passiveMode>true</passiveMode>

€<useEPRT>false</useEPRT>

€<useEPSV>true</useEPSV>

</ftpSettings>

NSX Manager Appliance Backup Exclusion Settings

See NSX Manager Appliance Backup Settings for details.

NSX API Guide Version: 6.4 Page 163

PUT /api/1.0/appliance-management/backuprestore/backupsettings/excludedata

Description:

Specify tables that need not be backed up.

Request:

Body: application/xml

€<excludeTable>AUDIT_LOGS</excludeTable>

</excludeTables>

NSX Manager Appliance Backup Schedule Settings

See NSX Manager Appliance Backup Settings for details.

PUT /api/1.0/appliance-management/backuprestore/backupsettings/schedule

Description:

Set backup schedule.

Request:

Body: application/xml

€<frequency>WEEKLY</frequency>

€<dayOfWeek>SUNDAY</dayOfWeek>

€<hourOfDay>2</hourOfDay>

€<minuteOfHour>15</minuteOfHour>

</backupFrequency>

DELETE /api/1.0/appliance-management/backuprestore/backupsettings/schedule

Description:

Delete backup schedule.

NSX Manager Appliance On-Demand Backup

POST /api/1.0/appliance-management/backuprestore/backup

Headers:

Content-Type€€(required) Specify application/xml.

NSX API Guide Version: 6.4 Page 164

Description:

Start an on-demand NSX Manager backup.

You must set the Content-Type header to application/xml for the backup to run successfully.

Working With NSX Manager Appliance Backup Files

GET /api/1.0/appliance-management/backuprestore/backups

Description:

Retrieve list of all backups available at configured backup location.

Responses:

Status Code: 200

Body: application/xml

<list>

€<backupFileProperties>

€€€<fileName>SiteA_00_27_58_Thu08Jun2017</fileName>

€€€<fileSize>3645472</fileSize>

€€€<creationTime>1496881678000</creationTime>

€</backupFileProperties>

€<backupFileProperties>

€€€<fileName>SiteA_01_06_16_Wed07Jun2017</fileName>

€€€<fileSize>3604512</fileSize>

€€€<creationTime>1496797576000</creationTime>

€</backupFileProperties>

</list>

Restoring Data from an NSX Manager Appliance Backup File

POST /api/1.0/appliance-management/backuprestore/restore

Query Parameters:

restoreFile€€(required) File name of restore file.

forceRestore€€(optional) With forceRestore=true you can restore a backup to an

NSX Manager that is in use. This might result in

inconsistent behavior.

Description:

Restore data from a backup file.

Retrieve a list of restore files using GET /api/1.0/appliance-management/backuprestore/backups.

Restore the backup to a newly deployed, unconfigured NSX Manager appliance. Restoring to an NSX Manager which

is in use might result in inconsistent behavior.

Method history:

NSX API Guide Version: 6.4 Page 165

Release Modification

6.4.1 Method updated. Query parameter forceRestore added.

Working With Tech Support Logs by Component

POST /api/1.0/appliance-management/techsupportlogs/{componentID}

URI Parameters:

componentID€€(required) Specified component to generate tech support logs. For

example, NSX.

Description:

Generate tech support logs. The location response header contains the location of the created tech support file.

Working With Tech Support Log Files

GET /api/1.0/appliance-management/techsupportlogs/{filename}

URI Parameters:

filename€€(required) Name of log file to download.

Description:

Download tech support logs.

Working With Support Notifications

GET /api/1.0/appliance-management/notifications

Description:

Retrieve all system generated notifications.

DELETE /api/1.0/appliance-management/notifications

Description:

Delete all notifications.

NSX API Guide Version: 6.4 Page 166

Acknowledge Notifications

POST /api/1.0/appliance-management/notifications/{ID}/acknowledge

URI Parameters:

ID€€(required) Notification ID.

Description:

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

POST /api/1.0/appliance-management/upgrade/uploadbundle/{componentID}

URI Parameters:

componentID€€(required) Component ID. Specify NSX.

Description:

Upload upgrade bundle.

Upload an NSX Manager Upgrade Bundle from URL

NSX API Guide Version: 6.4 Page 167

You can upload the upgrade bundle using the URL. Supported protocols are HTTP, HTTPS, and FTP.

You must provide the URL of the upgrade bundle file. For example:

• NSX?fileurl=http://www.vmware.com/build/mts/release/final-5934867/publish/VMware-NSX-Manager-upgrade-bundl

e-6.4.0-5934867.tar.gz

• NSX?fileurl=ftp://10.112.11.53/backup/VMware-NSX-Manager-upgrade-bundle-6.4.0-6864920.tar.gz

POST /api/1.0/appliance-management/upgrade/uploadbundlefromurl

Description:

Upload upgrade bundle from URL.

Method history:

Release Modification

6.3.3 Method introduced.

6.4.0 Method updated. FTP protocol support added.

Prepare for NSX Manager Upgrade

GET /api/1.0/appliance-management/upgrade/information/{componentID}

URI Parameters:

componentID€€(required) Component ID. Specify NSX.

Description:

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.

Responses:

Status Code: 200

Body: application/xml

€<fromVersion>6.2.5</fromVersion>

€<toVersion>6.2.7.5343628</toVersion>

€<upgradeBundleDescription>Upgrade to 6.2.7 5343628</upgradeBundleDescription>

€<preUpgradeQuestionsAnswers>

€€€<preUpgradeQuestionAnswer>

€€€€€<questionId>preUpgradeChecks1:Q1</questionId>

€€€€€<question>Do you want to enable SSH ?</question>

€€€€€<questionAnserType>YESNO</questionAnserType>

€€€</preUpgradeQuestionAnswer>

€€€<preUpgradeQuestionAnswer>

€€€€€<questionId>preUpgradeChecks1:Q2</questionId>

€€€€€<question>This product participates in VMware's Customer Experience Improvement Program ("CEIP"). The

CEIP provides VMware with information that enables VMware to improve its products and services, to fix

problems, and to advise you on

€€€€€€€how best to deploy and use our products. As part of the CEIP, VMware collects technical information

NSX API Guide Version: 6.4 Page 168

about your organization's use of VMware products and services on a regular basis in association with your

organization's VMware license

€€€€€€€key(s). This information does not personally identify any individual. For additional information

regarding the CEIP, please see the Trust and Assurance Center at

http://www.vmware.com/trustvmware/ceip.html. You can select your participation

€€€€€€€preferences below. Do you want to join the VMware Customer Experience Improvement Program

?</question>

€€€€€<questionAnserType>YESNO</questionAnserType>

€€€</preUpgradeQuestionAnswer>

€</preUpgradeQuestionsAnswers>

€<upgradeStepsDto>

€€€<step>

€€€€€<stepId>ValidationStep</stepId>

€€€€€<stepLabel>Upgrade Bundle Validation</stepLabel>

€€€€€<description>Upgrade bundle will be validated before the actual upgrade process.</description>

€€€</step>

€€€<step>

€€€€€<stepId>UpgradeStep</stepId>

€€€€€<stepLabel>Upgrade NSX manager</stepLabel>

€€€€€<description>Upgrade process for NSX Manager will begin.</description>

€€€</step>

€</upgradeStepsDto>

</upgradeInformation>

Start the NSX Manager Upgrade

POST /api/1.0/appliance-management/upgrade/start/{componentID}

URI Parameters:

componentID€€(required) Component ID. Specify NSX.

Description:

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.

Request:

Body: application/xml

€<preUpgradeQuestionAnswer>

€€€<questionId>preUpgradeChecks1:Q1</questionId>

€€€<question>Do you want to enable SSH ?</question>

€€€<questionAnserType>YESNO</questionAnserType>

€€€<answer>Yes</answer>

€</preUpgradeQuestionAnswer>

€<preUpgradeQuestionAnswer>

€€€<questionId>preUpgradeChecks1:Q2</questionId>

€€€<question>This product participates in VMware's Customer Experience Improvement Program ("CEIP"). The

CEIP provides VMware with information that enables VMware to improve its products and services, to fix

problems, and to advise you on

NSX API Guide Version: 6.4 Page 169

€€€€€how best to deploy and use our products. As part of the CEIP, VMware collects technical information

about your organization's use of VMware products and services on a regular basis in association with your

organization's VMware license

€€€€€key(s). This information does not personally identify any individual. For additional information

regarding the CEIP, please see the Trust and Assurance Center at

http://www.vmware.com/trustvmware/ceip.html. You can select your participation

€€€€€preferences below. Do you want to join the VMware Customer Experience Improvement Program ?</question>

€€€<questionAnserType>YESNO</questionAnserType>

€€€<answer>Yes</answer>

€</preUpgradeQuestionAnswer>

</preUpgradeQuestionsAnswers>

NSX Manager Upgrade Status

GET /api/1.0/appliance-management/upgrade/status/{componentID}

URI Parameters:

componentID€€(required) Component ID. Specify NSX.

Description:

Query upgrade status.

Working With Certificates on the NSX Manager Appliance

Working With Keystore Files

You must upload a key store file by using the form-data content-type in the request body. See the documentation of

your REST client for instructions.

To upload a file with form-data as the content-type, specify a key and a value for the file. The key is file with type as

File, and the value is the keystore file that you want to upload.

Example using curl

/usr/bin/curl -v -k -i -F file=@/tmp/cert.p12 -H 'Authorization: Basic YWRtaW46ZGXXXXXXXX=='

https://192.168.110.42/api/1.0/appliance-management/certificatemanager/pkcs12keystore/nsx?password=password

POST /api/1.0/appliance-management/certificatemanager/pkcs12keystore/nsx

Query Parameters:

password€€ Password.

Description:

Upload keystore file.

NSX API Guide Version: 6.4 Page 170

Input is PKCS#12 formatted NSX file with form-data.

NSX Manager Certificate Manager

GET /api/1.0/appliance-management/certificatemanager/certificates/nsx

Description:

Retrieve certificate information from the NSX Manager.

Method history:

Release Modification

6.4.4

Method updated. PEM encoding of the certificate is

added in the response body.

Responses:

Status Code: 200

Body: application/xml

€<x509certificate>

€€€<subjectCn></subjectCn>

€€€<issuerCn></issuerCn>

€€€<version></version>

€€€<serialNumber></serialNumber>

€€€<signatureAlgo></signatureAlgo>

€€€<signature></signature>

€€€<notBefore></notBefore>

€€€<notAfter></notAfter>

€€€<issuer></issuer>

€€€<subject></subject>

€€€<publicKeyAlgo></publicKeyAlgo>

€€€<publicKeyLength></publicKeyLength>

€€€<rsaPublicKeyModulus></rsaPublicKeyModulus>

€€€<rsaPublicKeyExponent></rsaPublicKeyExponent>

€€€<sha1Hash></sha1Hash>

€€€<md5Hash></md5Hash>

€€€<isCa></isCa>

€€€<isValid></isValid>

€</x509certificate>

€<pemEncoding>----BEGIN CERTIFICATE-----

€€€***

€€€-----END CERTIFICATE-----

€</pemEncoding>

</x509Certificates>

Working With Certificate Signing Requests

NSX API Guide Version: 6.4 Page 171

GET /api/1.0/appliance-management/certificatemanager/csr/nsx

Description:

Retrieve generated certificate signing request (CSR).

POST /api/1.0/appliance-management/certificatemanager/csr/nsx

Query Parameters:

action€€(optional) Specify self_sign to self sign the CSR and apply the

self-signed certificate.

expires_after€€(optional) Specify the validity of the certificate in number of days.

Default is 3650.

Description:

Create a certificate signing request (CSR) for NSX Manager.

The response header contains the created file location.

Method history:

Release Modification

6.2.3

Method introduced. Replaces PUT

/api/1.0/appliance-management/certificatemanager/csr/nsx.

Added two query parameters action and expires_after.

Request:

Body: application/xml

<csr>

€<algorithm></algorithm>

€<keySize></keySize>

€<subjectDto>

€€€<commonName></commonName>

€€€<organizationUnit></organizationUnit>

€€€<organizationName></organizationName>

€€€<localityName></localityName>

€€€<stateName></stateName>

€€€<countryCode></countryCode>

€</subjectDto>

</csr>

Working With Certificate Chains

You must upload a certificate chain file by using the form-data content-type in the request body. See the

documentation of your REST client for instructions.

To upload a file with form-data as the content-type, specify a key and a value for the file. The key is file with type as

File, and the value is the certificate chain file that you want to upload.

Example using curl

NSX API Guide Version: 6.4 Page 172

/usr/bin/curl -v -k -i -F file=@/tmp/cert.pem -H 'Authorization: Basic YWRtaW46ZGXXXXXXXX=='

https://192.168.110.42/api/1.0/appliance-management/certificatemanager/uploadchain/nsx

POST /api/1.0/appliance-management/certificatemanager/uploadchain/nsx

Description:

Upload certificate chain.

Input is certificate chain file which is a PEM encoded chain of certificates received from the certification authority after

signing a CSR.

NSX API Guide Version: 6.4 Page 173

Working with NSX Manager Debug APIs

You can use the NSX Manager debug APIs to troubleshoot problems on the NSX Manager.

GET /api/1.0/services/debug/threaddump

Description:

Generates the thread dump of the NSX Manager and captures the output of the top command. The top output helps

you to monitor the processes and the usage of the system resources on the NSX Manager. The combined output (top

output + thread dump) is saved in a separate threaddump_top log file. To view the files, download the NSX Manager

tech support bundle. The files are available in Bundle_Name\logs\threaddump.

Note: Starting in NSX 6.4.5, the name of the log file is changed to threaddump.top. After you upgrade to NSX 6.4.5

and generate the thread dump, the old threaddump_top file that existed before the upgrade is preserved in

Bundle_Name\preupgradeslot\logs\threaddump. The new thread dump (threaddump.top) is created and saved in

Bundle_Name\logs\threaddump.

Request:

Body: application/xml

€<status>Success</status>

</processoutput>

NSX API Guide Version: 6.4 Page 174

Working With NSX Manager System Events

GET /api/2.0/systemevent

Query Parameters:

startIndex€€(optional) The starting point for returning results.

pageSize€€(optional) The number of results to return. Range is 1-1024.

Description:

Get NSX Manager system events

Method history:

Release Modification

6.4.0

Method updated. New parameters eventSourceId,

eventSourceType, eventSourceIP added under

eventSourceInfo.

Request:

Body: application/xml

€<pagingInfo>

€€€<pageSize>256</pageSize>

€€€<startIndex>0</startIndex>

€€€<totalCount>8</totalCount>

€€€<sortOrderAscending>true</sortOrderAscending>

€€€<sortBy>eventId</sortBy>

€</pagingInfo>

€€€<eventId>1</eventId>

€€€<timestamp>1509946963236</timestamp>

€€€<severity>High</severity>

€€€<eventSource>NSX Manager</eventSource>

€€€<eventCode>340004</eventCode>

€€€<message>The scale for the parameter Controllers is not equal to recommended value 3.</message>

€€€<module>NSX Manager</module>

€€€<objectId></objectId>

€€€<reporterName>vShield Manager</reporterName>

€€€<reporterType>1</reporterType>

€€€<sourceType>1</sourceType>

€€€<displayName>NSX Manager UUID</displayName>

€€€<isResourceUniversal>false</isResourceUniversal>

€€€<eventSourceInfo>

€€€€€€€<eventSourceId></eventSourceId>

€€€€€€€<eventSourceType>NSX Manager</eventSourceType>

€€€€€€€<eventSourceIP>10.161.163.231</eventSourceIP>

€€€</eventSourceInfo>

€€€<eventMetadata></eventMetadata>

</systemEvent>

</dataPage>

</pagedSystemEventList>

NSX API Guide Version: 6.4 Page 175

NSX API Guide Version: 6.4 Page 176

Working with Host Event Notifications

You can enable host event notifications on the NSX Manager as a security feature to detect potential denial-of-service

(DoS) attack on hosts. By default, host event notifications are enabled. To view host event notifications in the vSphere

Web Client, navigate to Networking & Security > System > Events > Monitor > System Events. These notifications

are also displayed as alarms in the vSphere Web Client.

GET /api/2.0/hostevents

Description:

Retrieve configuration of host event notifications.

Method history:

Release Modification

6.4.0 Method added.

Responses:

Status Code: 200

Body: application/xml

€<enabled>true</enabled>

€<notificationInterval>300</notificationInterval>

</hostEventsDto>

POST /api/2.0/hostevents

Description:

Add configuration of host event notifications on the NSX Manager and host.

Method history:

Release Modification

6.4.0 Method added.

Request body parameters:

• enabled - Required. Enable or disable host event notifications. Options are True or False.

• notificationInterval - Required. Time interval in seconds at which the NSX Manager receives host event

notifications from each host. Valid range is 300 to 3600.

Request:

Body: application/xml

€<enabled>true</enabled>

€<notificationInterval>300</notificationInterval>

</hostEventsDto>

NSX API Guide Version: 6.4 Page 177

Working With DHCP Starv WhiteList

Hosts use vCenter alerts and dashboard alerts to notify users about DoS attacks on the hosts. In NSX 6.4.4 and

earlier, you can enable and disable DHCP DoS attack notifications on the hosts only at the global level. Starting with

NSX Data Center 6.4.5, you can use APIs to enable or disable DHCP DoS attack notifications on a per port basis

(dvPort).

By default, DHCP DoS attack notifications are enabled on all the ports. However, you can disable these notifications on

the ports that are expected to route DHCP packets. NSX 6.4.5 introduces APIs to create and modify a DHCP Starv

Whitelist, which you can use to exclude selected ports from checking DHCP DoS attack notifications. For example,

you can identify the third-party router VMs and disable notifications for the ports on those VMs by using the APIs. On

the ESG VMs, the APIs are automatically executed to whitelist all the vNICs of the ESG VMs, and no user intervention

is required.

Note: With NSX, you cannot whitelist ports when a VM or an Edge is connected to a VLAN-based port group.

DHCP Starv Whitelist Parameters

Parameter Description Comments

vmId

Object ID of the virtual

machine. Required.

virtualWire

Object ID of the virtualwire

(logical switch). Required. For example, virtualwire-1.

vnicUuid Index of the vNIC for a VM.

Optional. Use the VMInstanceUuid.deviceId

format to specify the vNIC of a VM (vnicId). For

example,

564d05d4-29f3-94ad-7fa5-47ca2be93796.000. If

you omit the vnicUuid, all vNICs for that VM and

virtualwire combination are added to the whitelist.

GET /api/2.0/vdn/hostevents/dhcp-starv-whitelist

Description:

Retrieve information about all the entries in the DHCP starv whitelist.

Method history:

Release Modification

6.4.5 Method introduced.

Request:

Body: application/xml

€<dhcpStarvWhitelistEntry>

€€€<id>dhcpstarvwhitelistentry-30</id>

€€€<vmId>vm-27</vmId>

€€€<virtualWire>virtualwire-3</virtualWire>

€€€<vnicUuid>500202d1-e85d-3584-5b11-149ba55dec62.000</vnicUuid>

€</dhcpStarvWhitelistEntry>

€<dhcpStarvWhitelistEntry>

€€€<id>dhcpstarvwhitelistentry-31</id>

€€€<vmId>vm-27</vmId>

€€€<virtualWire>virtualwire-3</virtualWire>

€€€<vnicUuid>500202d1-e85d-3584-5b11-149ba55dec62.001</vnicUuid>

€</dhcpStarvWhitelistEntry>

NSX API Guide Version: 6.4 Page 178

</dhcpStarvWhitelist>

POST /api/2.0/vdn/hostevents/dhcp-starv-whitelist

Description:

Create a new DHCP starv whitelist to exclude selected distributed virtual ports (dvPorts) from checking DoS attacks on

hosts. In the whitelist, specify combinations of vmId, virtualwire, and vnicId to identify ports on the dvSwitch that you

want to exclude.

In a multi-vCenter environment, you must create a separate whitelist that is local to the NSX Manager and vCenter

combination. For universal virtualwires, unique dvPortGroups are created on the dvSwitches that participate in the

logical network. NSX Manager associated with the vCenter Server manages the ports created on the dvPortGroups in

that vCenter.

Note: It is recommended to remove the whitelist entries before the following situations occur, else the whitelist might

grow unrestricted:

• Third-party router VMs are deleted.

• vNICs on the third-party router VMs are deleted or reconfigured to another logical switch (virtualwire).

For example, imagine that you have a third-party router VM connected to dvPort1 and dvPort1 is added to the whitelist.

Now, you want to move the VM from dvPort1 to dvPort2. Before moving the VM, first remove dvPort1 from the

whitelist, and then add dvPort2 to the whitelist. To summarize, use the following workflow:

• Run the DELETE API request (without force option) to remove dvPort1 from the whitelist.

• Move the VM from dvPort1 to dvPort2.

• Run the POST API request to add dvPort2 to the whitelist.

Method history:

Release Modification

6.4.5 Method introduced.

Request:

Body: application/xml

€<dhcpStarvWhitelistEntry>

€€€<id>dhcpstarvwhitelistentry-30</id>

€€€<vmId>vm-27</vmId>

€€€<virtualWire>virtualwire-3</virtualWire>

€€€<vnicUuid>500202d1-e85d-3584-5b11-149ba55dec62.002</vnicUuid>

€</dhcpStarvWhitelistEntry>

</dhcpStarvWhitelist>

Working With a Specific DHCP Starv Whitelist Entry

GET /api/2.0/vdn/hostevents/dhcp-starv-whitelist/{id}

URI Parameters:

id€€(required) ID of the DHCP starv whitelist entry.

Description:

NSX API Guide Version: 6.4 Page 179

Retrieve information about the specified DHCP starv whitelist entry.

Method history:

Release Modification

6.4.5 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<dhcpStarvWhitelistEntry>

€€€<id>dhcpstarvwhitelistentry-30</id>

€€€<vmId>vm-27</vmId>

€€€<virtualWire>virtualwire-3</virtualWire>

€€€<vnicUuid>500202d1-e85d-3584-5b11-149ba55dec62.002</vnicUuid>

€</dhcpStarvWhitelistEntry>

</dhcpStarvWhitelist>

DELETE /api/2.0/vdn/hostevents/dhcp-starv-whitelist/{id}

URI Parameters:

id€€(required) ID of the DHCP starv whitelist entry.

Query Parameters:

force€€(optional) Set to true to forcefully delete a whitelist entry.

If a vNIC that was whitelisted earlier is disconnected or

deleted after whitelisting, you must forcefully delete the

whitelist entry.

Description:

Delete the specified DHCP starv whitelist entry.

Method history:

Release Modification

6.4.5 Method introduced.

Working With DHCP Starv Whitelist Entries of a Specific VM

GET /api/2.0/vdn/hostevents/dhcp-starv-whitelist/vm/{vmId}

URI Parameters:

vmId€€(required) Object ID of the specified VM.

Description:

NSX API Guide Version: 6.4 Page 180

Retrieve information about all the DHCP starv whitelist entries of the specified VM.

Method history:

Release Modification

6.4.5 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<dhcpStarvWhitelistEntry>

€€€<id>dhcpstarvwhitelistentry-30</id>

€€€<vmId>vm-27</vmId>

€€€<virtualWire>virtualwire-3</virtualWire>

€€€<vnicUuid>500202d1-e85d-3584-5b11-149ba55dec62.002</vnicUuid>

€</dhcpStarvWhitelistEntry>

</dhcpStarvWhitelist>

DELETE /api/2.0/vdn/hostevents/dhcp-starv-whitelist/vm/{vmId}

URI Parameters:

vmId€€(required) Object ID of the specified VM.

Query Parameters:

force€€(optional) Set to true to forcefully delete a whitelist entry.

If a vNIC that was whitelisted earlier is disconnected or

deleted after whitelisting, you must forcefully delete the

whitelist entry.

Description:

Delete all the DHCP starv whitelist entries of the specified VM.

Method history:

Release Modification

6.4.5 Method introduced.

NSX API Guide Version: 6.4 Page 181

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

NSX API Guide Version: 6.4 Page 182

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

GET /api/2.0/auditlog

Query Parameters:

startIndex€€(optional) The starting point for returning results.

pageSize€€(optional) The number of results to return. Range is 1-1024.

sortOrderAscending€€(optional) Sort audit logs in ascending order. Use true for ascending order, and

false for descending order.

sortBy€€(optional) Sort audit logs by timestamp. Example

auditlog?sortOrderAscending=false&sortBy=timestamp.

Description:

Get NSX Manager audit logs.

NSX API Guide Version: 6.4 Page 183

Working With the VMware Customer Experience

Improvement Program

NSX Data Center for vSphere participates in VMware’s Customer Experience Improvement Program (CEIP).

See "Customer Experience Improvement Program" in the NSX Administration Guide for more information.

Working With the VMware CEIP Configuration

You can join or leave the CEIP at any time. You can also define the frequency and the days the information is

collected.

CEIP Parameters

Parameter Description Comments

enabled Enable status of data collection true or false.

frequency Frequency of data collection daily, weekly, or monthly.

dayOfWeek Day to collect data

SUNDAY, MONDAY, ...

SATURDAY.

hourOfDay Hour to collect data 0-23.

minutes Minute to collect data 0-59.

lastCollectionTime Time of last collection.

Timestamp in milliseconds. Read

only.

GET /api/1.0/telemetry/config

Description:

Retrieve the CEIP configuration.

Method history:

Release Modification

6.2.3 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<enabled>true</enabled>

€<frequency>weekly</frequency>

€<dayOfWeek>MONDAY</dayOfWeek>

€<hourOfDay>2</hourOfDay>

€<minutes>0</minutes>

€<lastCollectionTime>1499369743000</lastCollectionTime>

</telemetryConfiguration>

PUT /api/1.0/telemetry/config

NSX API Guide Version: 6.4 Page 184

Description:

Update the CEIP configuration.

Method history:

Release Modification

6.2.3 Method introduced.

6.3.3 Method updated. minutes parameter is configurable.

Request:

Body: application/xml

€<enabled>true</enabled>

€<frequency>daily</frequency>

€<hourOfDay>2</hourOfDay>

€<minutes>0</minutes>

</telemetryConfiguration>

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.

GET /api/1.0/telemetry/proxy

Description:

Retrieve the NSX Manager proxy settings for CEIP.

Method history:

NSX API Guide Version: 6.4 Page 185

Release Modification

6.3.3 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<enabled>manual</enabled>

€<scheme>http</scheme>

€<hostname>proxy.example.com</hostname>

€<port>3128</port>

€<username>nsxadmin</username>

</telemetryProxy>

PUT /api/1.0/telemetry/proxy

Description:

Retrieve the NSX Manager proxy settings for CEIP.

Method history:

Release Modification

6.3.3 Method introduced.

Request:

Body: application/xml

€<enabled>manual</enabled>

€<scheme>http</scheme>

€<hostname>proxy.example.com</hostname>

€<port>3128</port>

€<username>nsxadmin</username>

€<password>testing123</password>

</telemetryProxy>

NSX API Guide Version: 6.4 Page 186

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.

PUT /api/2.0/nwfabric/configure

Description:

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.

Request:

Body: application/xml

€<resourceConfig>

€€€<resourceId>CLUSTER MOID</resourceId>

€</resourceConfig>

</nwFabricFeatureConfig>

POST /api/2.0/nwfabric/configure

Query Parameters:

action€€(optional) Specify synchronize to reset communication between

NSX Manager and a host or cluster.

Description:

Install network fabric or VXLAN.

This method can be used to perform the following tasks:

• Install Network Virtualization Components

• Configure VXLAN

• Configure VXLAN with LACPv2

• Reset Communication Between NSX Manager and a Host or Cluster

Starting in NSX 6.4.7, before installing the network virtualization components on clusters that are managed by vCenter

7.0 or later, the API checks whether vSphere Lifecycle Management (vLCM) image is used on the clusters. If any

vCenter cluster uses a vLCM image, the API throws an error.

Host preparation is not allowed on vCenter clusters that use a vLCM image.

Parameter Information

Name Comments

NSX API Guide Version: 6.4 Page 187

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

€<resourceConfig>

€€€<resourceId>CLUSTER MOID</resourceId>

€</resourceConfig>

</nwFabricFeatureConfig>

Configure VXLAN

POST /api/2.0/nwfabric/configure

€<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>

NSX API Guide Version: 6.4 Page 188

Configure VXLAN with LACPv2

POST /api/2.0/nwfabric/configure

€<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

€<featureId>com.vmware.vshield.vsm.messagingInfra</featureId>

€<resourceConfig>

€€€<resourceId>resourceId</resourceId>

€</resourceConfig>

</nwFabricFeatureConfig>

Request:

Body: application/xml

€<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>

NSX API Guide Version: 6.4 Page 189

€€€</configSpec>

€</resourceConfig>

</nwFabricFeatureConfig>

DELETE /api/2.0/nwfabric/configure

Description:

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

€<resourceConfig>

€€€<resourceId>CLUSTER MOID</resourceId>

€</resourceConfig>

</nwFabricFeatureConfig>

Remove VXLAN

€<featureId>com.vmware.vshield.vsm.vxlan</featureId>

€<resourceConfig>

€€€<resourceId>CLUSTER MOID</resourceId>

€€</resourceConfig>

</nwFabricFeatureConfig>

Remove VXLAN with vDS context

€<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>

NSX API Guide Version: 6.4 Page 190

</nwFabricFeatureConfig>

Request:

Body: application/xml

€<featureId>com.vmware.vshield.vsm.vxlan</featureId>

€<resourceConfig>

€€€<resourceId>CLUSTER MOID</resourceId>

€€</resourceConfig>

</nwFabricFeatureConfig>

Resolving Host Preparation Issues

POST /api/2.0/nwfabric/resolveIssues/{clusterID}

URI Parameters:

clusterID€€ MOID of the cluster to resolve. For example,

domain-c27.

Description:

Resolve all issues associated with host preparation (VIB installation). You can resolve issues only at the cluster level.

Working With Network Fabric Features

GET /api/2.0/nwfabric/features

Description:

Retrieves all network fabric features available on the cluster. Multiple featureInfo sections may be returned.

Responses:

Status Code: 200

Body: application/xml

€<featureInfo>

€€€<name>FEATURE NAME</name>

€€€<featureId>FEATURE ID</featureId>

€€€<version>FEATURE VERSION</version>

€</featureInfo>

</featureInfos>

NSX API Guide Version: 6.4 Page 191

Working With Network Fabric Status

GET /api/2.0/nwfabric/status

Query Parameters:

resource€€(required) Set resource to the correct resourceId which is a valid

vCenter MOID (e.g. domain-c34 for a cluster).

Description:

Retrieve the network fabric status of the specified resource.

Responses:

Status Code: 200

Body: application/xml

€<resourceStatus>

€€€<resource>

€€€€€<objectId>resource-id</objectId>

€€€€€<objectTypeName>ClusterComputeResource</objectTypeName>

€€€€€<nsxmgrUuid>jfldj</nsxmgrUuid>

€€€€€<revision>2</revision>

€€€€€<type>

€€€€€€€<typeName>ClusterComputeResource</typeName>

€€€€€</type>

€€€€€<name>c-1</name>

€€€€€<scope>

€€€€€€€<id>datacenter-2</id>

€€€€€€€<objectTypeName>Datacenter</objectTypeName>

€€€€€€€<name>dc-1</name>

€€€€€</scope>

€€€€€<clientHandle></clientHandle>

€€€€€<extendedAttributes></extendedAttributes>

€€€</resource>

€€€<nwFabricFeatureStatus>

€€€€€<featureId>com.vmware.vshield.nsxmgr.nwfabric.hostPrep</featureId>

€€€€€<featureVersion>5.5</featureVersion>

€€€€€<updateAvailable>false</updateAvailable>

€€€€€<status>RED</status>

€€€€€<message></message>

€€€€€<installed>true</installed>

€€€</nwFabricFeatureStatus>

€€€<nwFabricFeatureStatus>

€€€€€<featureId>com.vmware.vshield.nsxmgr.vxlan</featureId>

€€€€€<featureVersion>5.5</featureVersion>

€€€€€<updateAvailable>false</updateAvailable>

€€€€€<status>UNKNOWN</status>

€€€€€<installed>false</installed>

€€€</nwFabricFeatureStatus>

€€€<nwFabricFeatureStatus>

€€€€€<featureId>com.vmware.vshield.nsxmgr.messagingInfra</featureId>

€€€€€<featureVersion>5.5</featureVersion>

€€€€€<updateAvailable>false</updateAvailable>

€€€€€<status>UNKNOWN</status>

NSX API Guide Version: 6.4 Page 192

€€€€€<installed>false</installed>

€€€</nwFabricFeatureStatus>

€€€<nwFabricFeatureStatus>

€€€€€<featureId>com.vmware.vshield.firewall</featureId>

€€€€€<featureVersion>5.5</featureVersion>

€€€€€<updateAvailable>false</updateAvailable>

€€€€€<status>UNKNOWN</status>

€€€€€<installed>false</installed>

€€€</nwFabricFeatureStatus>

€</resourceStatus>

</resourceStatuses>

Working With Network Fabric Status of Child Resources

GET /api/2.0/nwfabric/status/child/{parentResourceID}

URI Parameters:

parentResourceID€€(required) Parent resource ID

Description:

Retrieve the network fabric status of child resources of the specified resource.

Responses:

Status Code: 200

Body: application/xml

€<resourceStatus>

€€€<resource>

€€€€€<objectId>host-9</objectId>

€€€€€<objectTypeName>HostSystem</objectTypeName>

€€€€€<nsxmgrUuid>jfldj</nsxmgrUuid>

€€€€€<revision>4</revision>

€€€€€<type>

€€€€€€€<typeName>HostSystem</typeName>

€€€€€</type>

€€€€€<name>10.135.14.186</name>

€€€€€<scope>

€€€€€€€<id>domain-c34</id>

€€€€€€€<objectTypeName>ClusterComputeResource</objectTypeName>

€€€€€€€<name>c-1</name>

€€€€€</scope>

€€€€€<clientHandle></clientHandle>

€€€€€<extendedAttributes></extendedAttributes>

€€€</resource>

€€€<nwFabricFeatureStatus>

€€€€€<featureId>com.vmware.vshield.nsxmgr.nwfabric.hostPrep</featureId>

€€€€€<featureVersion>5.5</featureVersion>

€€€€€<updateAvailable>false</updateAvailable>

€€€€€<status>RED</status>

€€€€€<message></message>

€€€€€<installed>true</installed>

NSX API Guide Version: 6.4 Page 193

€€€</nwFabricFeatureStatus>

€€€<nwFabricFeatureStatus>

€€€€€<featureId>com.vmware.vshield.nsxmgr.vxlan</featureId>

€€€€€<featureVersion>5.5</featureVersion>

€€€€€<updateAvailable>false</updateAvailable>

€€€€€<status>UNKNOWN</status>

€€€€€<installed>false</installed>

€€€</nwFabricFeatureStatus>

€€€<nwFabricFeatureStatus>

€€€€€<featureId>com.vmware.vshield.nsxmgr.messagingInfra</featureId>

€€€€€<featureVersion>5.5</featureVersion>

€€€€€<updateAvailable>false</updateAvailable>

€€€€€<status>UNKNOWN</status>

€€€€€<installed>false</installed>

€€€</nwFabricFeatureStatus>

€€€<nwFabricFeatureStatus>

€€€€€<featureId>com.vmware.vshield.firewall</featureId>

€€€€€<featureVersion>5.5</featureVersion>

€€€€€<updateAvailable>false</updateAvailable>

€€€€€<status>UNKNOWN</status>

€€€€€<installed>false</installed>

€€€</nwFabricFeatureStatus>

€</resourceStatus>

</resourceStatuses>

Working With Status of Resources by Criterion

GET /api/2.0/nwfabric/status/alleligible/{resourceType}

URI Parameters:

resourceType€€(required) Valid resource type. Valid resourceType is clusters. You

can also use ClusterComputeResource, if required.

Description:

Retrieve status of resources by criterion.

Responses:

Status Code: 200

Body: application/xml

€<resourceStatus>

€€€<resource>

€€€€€<objectId>domain-c34</objectId>

€€€€€<objectTypeName>ClusterComputeResource</objectTypeName>

€€€€€<nsxmgrUuid>jfldj</nsxmgrUuid>

€€€€€<revision>2</revision>

€€€€€<type>

€€€€€€€<typeName>ClusterComputeResource</typeName>

€€€€€</type>

€€€€€<name>c-1</name>

€€€€€<scope>

NSX API Guide Version: 6.4 Page 194

€€€€€€€<id>datacenter-2</id>

€€€€€€€<objectTypeName>Datacenter</objectTypeName>

€€€€€€€<name>dc-1</name>

€€€€€</scope>

€€€€€<clientHandle></clientHandle>

€€€€€<extendedAttributes></extendedAttributes>

€€€</resource>

€€€<nwFabricFeatureStatus>

€€€€€<featureId>com.vmware.vshield.nsxmgr.nwfabric.hostPrep</featureId>

€€€€€<featureVersion>5.5</featureVersion>

€€€€€<updateAvailable>false</updateAvailable>

€€€€€<status>RED</status>

€€€€€<message></message>

€€€€€<installed>true</installed>

€€€</nwFabricFeatureStatus>

€€€<nwFabricFeatureStatus>

€€€€€<featureId>com.vmware.vshield.nsxmgr.vxlan</featureId>

€€€€€<featureVersion>5.5</featureVersion>

€€€€€<updateAvailable>false</updateAvailable>

€€€€€<status>UNKNOWN</status>

€€€€€<installed>false</installed>

€€€</nwFabricFeatureStatus>

€€€<nwFabricFeatureStatus>

€€€€€<featureId>com.vmware.vshield.nsxmgr.messagingInfra</featureId>

€€€€€<featureVersion>5.5</featureVersion>

€€€€€<updateAvailable>false</updateAvailable>

€€€€€<status>UNKNOWN</status>

€€€€€<installed>false</installed>

€€€</nwFabricFeatureStatus>

€€€<nwFabricFeatureStatus>

€€€€€<featureId>com.vmware.vshield.firewall</featureId>

€€€€€<featureVersion>5.5</featureVersion>

€€€€€<updateAvailable>false</updateAvailable>

€€€€€<status>UNKNOWN</status>

€€€€€<installed>false</installed>

€€€</nwFabricFeatureStatus>

€</resourceStatus>

€<resourceStatus>

€€€<resource>

€€€€€<objectId>domain-c32</objectId>

€€€€€<objectTypeName>ClusterComputeResource</objectTypeName>

€€€€€<nsxmgrUuid>jfldj</nsxmgrUuid>

€€€€€<revision>1</revision>

€€€€€<type>

€€€€€€€<typeName>ClusterComputeResource</typeName>

€€€€€</type>

€€€€€<name>c-2</name>

€€€€€<scope>

€€€€€€€<id>datacenter-12</id>

€€€€€€€<objectTypeName>Datacenter</objectTypeName>

€€€€€€€<name>dc-2</name>

€€€€€</scope>

€€€€€<clientHandle></clientHandle>

€€€€€<extendedAttributes></extendedAttributes>

€€€</resource>

€€€<nwFabricFeatureStatus>

€€€€€<featureId>com.vmware.vshield.nsxmgr.nwfabric.hostPrep</featureId>

€€€€€<updateAvailable>false</updateAvailable>

€€€€€<status>UNKNOWN</status>

€€€€€<installed>false</installed>

€€€</nwFabricFeatureStatus>

€€€<nwFabricFeatureStatus>

NSX API Guide Version: 6.4 Page 195

€€€€€<featureId>com.vmware.vshield.nsxmgr.vxlan</featureId>

€€€€€<featureVersion>5.5</featureVersion>

€€€€€<updateAvailable>false</updateAvailable>

€€€€€<status>UNKNOWN</status>

€€€€€<installed>false</installed>

€€€</nwFabricFeatureStatus>

€€€<nwFabricFeatureStatus>

€€€€€<featureId>com.vmware.vshield.nsxmgr.messagingInfra</featureId>

€€€€€<featureVersion>5.5</featureVersion>

€€€€€<updateAvailable>false</updateAvailable>

€€€€€<status>UNKNOWN</status>

€€€€€<installed>false</installed>

€€€</nwFabricFeatureStatus>

€€€<nwFabricFeatureStatus>

€€€€€<featureId>com.vmware.vshield.firewall</featureId>

€€€€€<featureVersion>5.5</featureVersion>

€€€€€<updateAvailable>false</updateAvailable>

€€€€€<status>UNKNOWN</status>

€€€€€<installed>false</installed>

€€€</nwFabricFeatureStatus>

€</resourceStatus>

</resourceStatuses>

Working With Locale ID Configuration For Clusters

GET /api/2.0/nwfabric/clusters/{clusterID}

URI Parameters:

clusterID€€(required) Cluster ID.

Description:

Retrieve the locale ID for the specified cluster.

PUT /api/2.0/nwfabric/clusters/{clusterID}

URI Parameters:

clusterID€€(required) Cluster ID.

Description:

Update the locale ID for the specified cluster.

Request:

Body: application/xml

€<localeId></localeId>

</nwFabricClusterConfig>

NSX API Guide Version: 6.4 Page 196

DELETE /api/2.0/nwfabric/clusters/{clusterID}

URI Parameters:

clusterID€€(required) Cluster ID.

Description:

Delete locale ID for the specified cluster.

Working With Locale ID Configuration for Hosts

GET /api/2.0/nwfabric/hosts/{hostID}

URI Parameters:

hostID€€(required) Host ID.

Description:

Retrieve the locale ID for the specified host.

PUT /api/2.0/nwfabric/hosts/{hostID}

URI Parameters:

hostID€€(required) Host ID.

Description:

Update the locale ID for the specified host.

Request:

Body: application/xml

€<localeId></localeId>

</nwFabricHostConfig>

DELETE /api/2.0/nwfabric/hosts/{hostID}

URI Parameters:

hostID€€(required) Host ID.

Description:

Delete the locale ID for the specified host.

NSX API Guide Version: 6.4 Page 197

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.

PUT /api/2.0/si/deploy

Query Parameters:

startTime€€(optional) Specify time to start upgrade.

Description:

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.

Request:

Body: application/xml

€<clusterDeploymentConfig>

NSX API Guide Version: 6.4 Page 198

€€€<clusterId></clusterId>

€€€<datastore></datastore>

€€€<services>

€€€€€<serviceDeploymentConfig>

€€€€€€€<serviceId></serviceId>

€€€€€€€<serviceInstanceId></serviceInstanceId>

€€€€€€€<dvPortGroup></dvPortGroup>

€€€€€€€<ipPool></ipPool>

€€€€€</serviceDeploymentConfig>

€€€</services>

€</clusterDeploymentConfig>

</clusterDeploymentConfigs>

POST /api/2.0/si/deploy

Query Parameters:

startTime€€(optional) Time to start deployment task. If not specified, deploy

immediately.

Description:

Deploy security fabric.

Request:

Body: application/xml

€<clusterDeploymentConfig>

€€€<clusterId></clusterId>

€€€<datastore></datastore>

€€€<services>

€€€€€<serviceDeploymentConfig>

€€€€€€€<serviceId></serviceId>

€€€€€€€<dvPortGroup></dvPortGroup>

€€€€€€€<ipPool></ipPool>

€€€€€</serviceDeploymentConfig>

€€€</services>

€</clusterDeploymentConfig>

</clusterDeploymentConfigs>

Working With a Specified Service

GET /api/2.0/si/deploy/service/{serviceID}

URI Parameters:

serviceID€€(required) Specified service.

Description:

Retrieve all clusters on which the service is installed.

NSX API Guide Version: 6.4 Page 199

DELETE /api/2.0/si/deploy/service/{serviceID}

URI Parameters:

serviceID€€(required) Specified service.

Query Parameters:

clusters€€ Comma-separated list of cluster IDs from which to

uninstall the service.

startTime€€ Time for uninstall to be scheduled. If not specified,

uninstall immediately.

Description:

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.

GET /api/2.0/si/deploy/service/{serviceID}/dependsOn

URI Parameters:

serviceID€€(required) Specified service.

Description:

Retrieve service on which the specified service depends.

Working With Installed Services on a Cluster

GET /api/2.0/si/deploy/cluster/{clusterID}

URI Parameters:

clusterID€€(required) Cluster ID

Description:

Retrieve all services deployed along with their status.

Responses:

Status Code: 200

Body: application/xml

NSX API Guide Version: 6.4 Page 200

€<deployedService>

€€€<deploymentUnitId>deploymentunit-1</deploymentUnitId>

€€€<serviceId>service-3</serviceId>

€€€<cluster>

€€€€€<objectId>domain-c41</objectId>

€€€€€<objectTypeName>ClusterComputeResource</objectTypeName>

€€€€€<nsxmgrUuid>42036483-6CF3-4F0F-B356-2EB1E6369C6F</nsxmgrUuid>

€€€€€<revision>2</revision>

€€€€€<type>

€€€€€€€<typeName>ClusterComputeResource</typeName>

€€€€€</type>

€€€€€<name>Cluster-1</name>

€€€€€<scope>

€€€€€€€<id>datacenter-21</id>

€€€€€€€<objectTypeName>Datacenter</objectTypeName>

€€€€€€€<name>nasingh-dc</name>

€€€€€</scope>

€€€€€€<extendedAttributes></extendedAttributes>

€€€</cluster>

€€€<serviceName>domain-c41_service-3</serviceName>

€€€<datastore>

€€€€€<objectId>datastore-29</objectId>

€€€€€<objectTypeName>Datastore</objectTypeName>

€€€€€<nsxmgrUuid>42036483-6CF3-4F0F-B356-2EB1E6369C6F</nsxmgrUuid>

€€€€€<revision>1</revision>

€€€€€<type>

€€€€€€€<typeName>Datastore</typeName>

€€€€€</type>

€€€€€<name>datastore1</name>

€€€€€€<extendedAttributes></extendedAttributes>

€€€</datastore>

€€€<dvPortGroup>

€€€€€<objectId>dvportgroup-45</objectId>

€€€€€<objectTypeName>DistributedVirtualPortgroup</objectTypeName>

€€€€€<nsxmgrUuid>42036483-6CF3-4F0F-B356-2EB1E6369C6F</nsxmgrUuid>

€€€€€<revision>2</revision>

€€€€€<type>

€€€€€€€<typeName>DistributedVirtualPortgroup</typeName>

€€€€€</type>

€€€€€<name>dvPortGroup</name>

€€€€€<scope>

€€€€€€€<id>datacenter-21</id>

€€€€€€€<objectTypeName>Datacenter</objectTypeName>

€€€€€€€<name>nasingh-dc</name>

€€€€€</scope>

€€€€€€<extendedAttributes></extendedAttributes>

€€€</dvPortGroup>

€€€<serviceStatus>SUCCEEDED</serviceStatus>

€</deployedService>

</deployedServices>

DELETE /api/2.0/si/deploy/cluster/{clusterID}

URI Parameters:

clusterID€€(required) Cluster ID

Query Parameters:

NSX API Guide Version: 6.4 Page 201

services€€(optional) Comma-separated list of service IDs to specify which

services to uninstall. If this is not specified then all the

services are uninstalled.

startTime€€ Time for uninstall to be scheduled. If not specified, do

immediately.

Description:

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

GET /api/2.0/si/deploy/cluster/{clusterID}/service/{serviceID}

URI Parameters:

serviceID€€ Service ID on cluster

clusterID€€(required) Cluster ID

Description:

Retrieve detailed information about the service.

NSX API Guide Version: 6.4 Page 202

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.

POST /api/1.0/eventcontrol/vm/{vmID}/request

URI Parameters:

vmID€€(required) MOID of the guest vm

Description:

Enable or disable data collection on a virtual machine

Set value to enabled or disabled.

Request:

Body: application/xml

€<actions>

€€€<action>

€€€€€<type>per_vm_config</type>

€€€€€<value>enabled</value>

€€€</action>

€</actions>

</perVmConfig>

NSX API Guide Version: 6.4 Page 203

Override Data Collection

POST /api/1.0/eventcontrol/eventcontrol-root/request

Description:

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.

Request:

Body: application/xml

€<actions>

€€€<action>

€€€€€<type>global_switch</type>

€€€€€<value>disabled</value>

€€€</action>

€</actions>

</request>

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.

GET /api/1.0/eventcontrol/config/vm/{vmID}

URI Parameters:

vmID€€(required) MOID of the guest vm

Description:

Retrieve per VM configuration for data collection.

Responses:

Status Code: 200

Body: application/xml

€<actions>

€€€<action>

€€€€€<type>global_switch</type>

€€€€€<value>disabled</value>

NSX API Guide Version: 6.4 Page 204

€€€</action>

€€€<action>

€€€€€<type>per_vm_config</type>

€€€€€<value>enabled</value>

€€€</action>

€</actions>

</perVmConfig>

NSX API Guide Version: 6.4 Page 205

Working With Activity Monitoring

Working With Aggregated User Activity

Get aggregated user activity (action records) using parameters. Requires that Guest Introspection is configured, NSX

Manager must be registered with Active Directory, and data collection is enabled on one or more VMs.

GET /api/3.0/ai/records

Query Parameters:

query€€(required) Name of report (resource,adg,containers,sam,vma).

interval€€(required) Relative time to current time (number followed by either m,h,d,s).

stime€€(optional) Start time for query. interval is used if stime and etime are not

specified.

etime€€(optional) End time for query. interval is used if stime and etime are not specified.

example: 2012-02-29T21:00

param€€ Parameter to be applied to query

<param-name>:<param-type>:<comma-separated-values>:<operator>

pagesize€€ The number of results to return. Recommended range is 100-2000.

startindex€€ The starting point for returning results.

Description:

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).

Example: View user activities to VM ID 1 originating from application ID 1

GET /api/3.0/ai/records?query=resource&interval=60m&

param=src:DIRECTORY_GROUP&param=dest:VIRTUAL_MACHINE:1&param=app:SRC_APP:1

NSX API Guide Version: 6.4 Page 206

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).

Example: View user activities to VM ID 1 originating from application ID 1

GET /api/3.0/ai/records?query=containers&interval=60m&

param=dest:SECURITY_GROUP:1:EXCLUDE &param=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 is INCLUDE*).

Example: View interaction between inventory containers

GET /api/3.0/ai/records?query=containers&interval=60m&

param=dest:SECURITY_GROUP:1:EXCLUDE&param=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:

NSX API Guide Version: 6.4 Page 207

⋅ 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*).

Example: View outbound AD group activity

GET /api/3.0/ai/records?query=adg&interval=24h&

param=adg:USER:1:INCLUDE&param=src:SECURITY_GROUP:1:EXCLUDE

Working With User Details

GET /api/3.0/ai/userdetails

Query Parameters:

query€€(required) Name of report (resource,adg,containers,sam,vma)

interval€€(required) Relative time to current time (number followed by either m,h,d,s)

stime€€ Start time for query

etime€€ End time for query

param€€ Parameter to be applied to query

<param-name>:<param-type>:<comma-separated-values>:<operator>

pagesize€€ The number of results to return. Recommended range is 100-2000.

startindex€€ The starting point for returning results.

Description:

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).

Example: View user activities to VM ID 1 originating from application ID 1

NSX API Guide Version: 6.4 Page 208

GET /api/3.0/ai/userdetails?query=resource&stime=2012-10-15T00:00:00&etime=2012-10-20T00:00:00&

param=src:DIRECTORY_GROUP:2&param=app:SRC_APP:16&param=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).

Example: View user activities to VM ID 1 originating from application ID 1

GET /api/3.0/userdetails?query=sam&interval=60m&param=app:DEST_APP:1:EXCLUDE

&param=dest:IP:1:EXCLUDE&param=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 is INCLUDE*).

Example: View interaction between inventory containers

GET /api/3.0/ai/userdetails?query=containers&interval=60m&

param=dest:SECURITY_GROUP:1:EXCLUDE&param=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:

NSX API Guide Version: 6.4 Page 209

- <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).

Example: View outbound AD group activity

GET /api/3.0/ai/userdetails?query=adg&interval=24h&param=adg:USER:1:INCLUDE

&param=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).

Example: View outbound AD group activity

GET /api/3.0/ai/userdetails?query=vma&interval=60m&param=dest:VIRTUAL_MACHINE:1&

param=app:DEST_APP:16

Working With a Specific User

GET /api/3.0/ai/user/{userID}

URI Parameters:

userID€€(required) User ID

Description:

Retrieve details for a specific user.

NSX API Guide Version: 6.4 Page 210

Working With Applications

GET /api/3.0/ai/app

Description:

Retrieve app details.

Working With a Specific Application

GET /api/3.0/ai/app/{appID}

URI Parameters:

appID€€(required) Specified app ID.

Description:

Retrieve details for specific app.

Working With Discovered Hosts

GET /api/3.0/ai/host

Description:

Retrieve list of all discovered hosts (both by agent introspection and LDAP Sync) and their detail.

Working With a Specific Discovered Host

GET /api/3.0/ai/host/{hostID}

URI Parameters:

hostID€€(required) Specified host ID.

Description:

Get host details.

Working With Desktop Pools

NSX API Guide Version: 6.4 Page 211

GET /api/3.0/ai/desktoppool

Description:

Retrieve list of all discovered desktop pools by agent introspection.

Working With a Specific Desktop Pool

GET /api/3.0/ai/desktoppool/{desktoppoolID}

URI Parameters:

desktoppoolID€€(required) Specified desktop pool.

Description:

Retrieve specific desktop pool details.

Working With Virtual Machines

GET /api/3.0/ai/vm

Description:

Retrieve list of all discovered VMs.

Working With a Specific Virtual Machine

GET /api/3.0/ai/vm/{vmID}

URI Parameters:

vmID€€(required) VM ID

Description:

Retrieve details about a specific virtual machine.

Working With LDAP Directory Groups

GET /api/3.0/ai/directorygroup

Description:

NSX API Guide Version: 6.4 Page 212

Retrieve list of all discovered (and configured) LDAP directory groups.

Working With a Specific LDAP Directory Group

GET /api/3.0/ai/directorygroup/{directorygroupID}

URI Parameters:

directorygroupID€€(required) Specified directory group.

Description:

Retrieve details about a specific directory group.

Working With a Specific User's Active Directory Groups

GET /api/3.0/ai/directorygroup/user/{userID}

URI Parameters:

userID€€(required) User ID.

Description:

Retrieve Active Directory groups that user belongs to.

Working With Security Groups

GET /api/3.0/ai/securitygroup

Description:

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

GET /api/3.0/ai/securitygroup/{secgroupID}

URI Parameters:

secgroupID€€(required) Specified security group.

NSX API Guide Version: 6.4 Page 213

Description:

Retrieve details about specific security group.

NSX API Guide Version: 6.4 Page 214

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?

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.

rootDnItem

Root DN item. Use instead of rootDn if the

domain has multiple rootDn values. Optional.

NSX API Guide Version: 6.4 Page 215

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.

POST /api/1.0/directory/updateDomain

Description:

Example: Domain with one root DN

€<name>example.com</name>

€<netbiosName>Example</netbiosName>

€<baseDn>DC=example,DC=com</baseDn>

€<rootDn>OU=prod,DC=example,DC=com</rootDn>

€<username>Administrator</username>

€<password>xxx</password>

</DirectoryDomain>

Example: Domain with multiple root DN

€<name>example.com</name>

€<netbiosName>Example</netbiosName>

€<baseDn>DC=example,DC=com</baseDn>

€<rootDnItem>OU=prod,DC=example,DC=com</rootDnItem>

€<rootDnItem>OU=test,DC=example,DC=com</rootDnItem>

€<username>Administrator</username>

€<password>xxx</password>

</DirectoryDomain>

Method history:

Release Modification

6.4.0 Method updated. rootDnItem parameter added.

Request:

Body: application/xml

€<name>example.com</name>

€<netbiosName>Example</netbiosName>

€<username>Administrator</username>

€<password>xxx</password>

</DirectoryDomain>

NSX API Guide Version: 6.4 Page 216

Retrieve LDAP Domains

GET /api/1.0/directory/listDomains

Description:

Retrieve all agent discovered (or configured) LDAP domains.

Responses:

Status Code: 200

Body: application/xml

€<DirectoryDomain>

€€€<id>2</id>

€€€<name>vs4.net</name>

€€€<type>ActiveDirectory</type>

€€€<netbiosName>VS4</netbiosName>

€€€<username>Administrator</username>

€€€<baseDn>DC=vs4,DC=net</baseDn>

€</DirectoryDomain>

</DirectoryDomains>

Retrieve Security Groups of a Specific Domain

GET /api/1.0/directory/domainSgMapping/{domainId}

URI Parameters:

domainId€€(required) Domain ID.

Description:

List all the security groups of the specified domain.

Responses:

Status Code: 200

Body: application/xml

€<DirectoryDomainRelatedSG>

€€€<sgId>2</sgId>

€€€<sgName>group1</sgName>

€</DirectoryDomainRelatedSG>

</DirectoryDomainRelatedSGs>

NSX API Guide Version: 6.4 Page 217

Delete a Specific Domain

DELETE /api/1.0/directory/deleteDomain/{ID}

URI Parameters:

ID€€(required) Domain ID.

Description:

Delete domain.

Working with Root Distinguished Names

Retrieve the list of individual root distinguished names under which each domain sub-tree synchronization is executed.

POST /api/1.0/directory/verifyRootDn

Query Parameters:

domainName€€(required) Parent domain name this root distinguished name

belongs to. It is a string type.

baseDN€€(required) Domain's base distinguished name. It is a string type.

rootDnlists€€(required) The list of individual root distinguished name. It is a list

of string type.

hostName€€(required) Domain LDAP server host name or IP address. It is a list

of string type.

port€€(optional) Domain LDAP server port. It is an integer type.

username€€(required) Account credential of user name to access LDAP server.

It is a string type.

password€€(required) Account credential of password to access ldap server. It

is a string type.

protocol€€(optional) Domain LDAP server protocol used. It is a string type.

Description:

Verify that the rootDNs in the rootDNList are independent to each other. Verify that the rootDNs in the rootDNList exist

in Active Director server.

Method history:

Release Modification

6.4.0 Method introduced.

Request:

Body: application/xml

NSX API Guide Version: 6.4 Page 218

€<domainName>nimbustest.com</domainName>

€<baseDn>Example</baseDn>

€<rootDnItem>CN=nimbustest,DC=com</rootDnItem>

€<hostName>10.142.72.70</hostName>

€<username>Administrator</username>

€<password>xxx</password>

</RootDnVerify>

Delete DomainRootDN

DELETE /api/1.0/directory/deleteDomainRootDN/{domainID}

URI Parameters:

domainID€€(required) Domain ID.

Description:

Delete individual root distinguished name under which each domain sub-tree synchronization is not to be executed.

Method history:

Release Modification

6.4.0 Method introduced.

Create LDAP Server

POST /api/1.0/directory/updateLdapServer

Description:

Create LDAP server.

Request:

Body: application/xml

€<domainId>4</domainId>

€<hostName>10.142.72.70</hostName>

€<enabled>true</enabled>

</LDAPServer>

NSX API Guide Version: 6.4 Page 219

Query LDAP Servers for a Domain

GET /api/1.0/directory/listLdapServersForDomain/{domainID}

URI Parameters:

domainID€€(required) Specified domain.

Description:

Query LDAP servers for a domain.

Update AD Sync Settings

Update AD sync settings (both delta sync and full sync). Change delta sync interval, and enable or disable full sync, as

well as full sync frequency.

POST /api/1.0/directory/ldapSyncSettings

Query Parameters:

deltaSyncIntervalInMin€€(optional) AD delta sync interval (in minutes).

fullSyncCronExpr€€(optional) AD full sync frequency (as cron expression), not used if

enableFullSync is false. The cron expresssion has 6

fields (second, minute, hour, day of month, month,

day(s) of week). An asterisk means match any.

enableFullSync€€(optional) Whether to enable/disable AD full sync.

restartSync€€(optional) Restart LDAP sync at the end of request. To see an

immediate change in the domain sync schedule, this

parameter must be set to true. If this paramter is not

included in the post body it is false. When false, even if

the delta sync interval is changed, the current domain

sync schedule is not impacted because it only saves the

configuration in the datbase and run time behavior is not

changed.

Description:

LDAP full sync settings

Method history:

Release Modification

6.4.0 Method introduced.

Request:

Body: application/xml

€<deltaSyncIntervalInMin>1</deltaSyncIntervalInMin>

€<fullSyncCronExpr>0 */5 * ? * *</fullSyncCronExpr>

€<enableFullSync>true</enableFullSync>

€<restartSync>true</restartSync>

NSX API Guide Version: 6.4 Page 220

</LdapSyncSettings>

Start LDAP Full Sync

PUT /api/1.0/directory/fullSync/{domainID}

URI Parameters:

domainID€€(required) Specified domain.

Description:

Start LDAP full sync.

Start LDAP Delta Sync

PUT /api/1.0/directory/deltaSync/{domainID}

URI Parameters:

domainID€€(required) Specified domain.

Description:

Start LDAP delta sync.

Delete LDAP Server

DELETE /api/1.0/directory/deleteLdapServer/{serverID}

URI Parameters:

serverID€€(required) Specified LDAP server.

Description:

Delete LDAP server.

EventLog Server

POST /api/1.0/directory/updateEventLogServer

Description:

NSX API Guide Version: 6.4 Page 221

Create EventLog server.

Request:

Body: application/xml

€<id>1</id>

€<domainId>4</domainId>

€<hostName>10.142.72.70</hostName>

€<enabled>false</enabled>

</EventlogServer>

Working With EventLog Servers for a Domain

GET /api/1.0/directory/listEventLogServersForDomain/{domainID}

URI Parameters:

domainID€€(required) Specified domain.

Description:

Query EventLog servers for a domain.

Delete EventLog Server

DELETE /api/1.0/directory/deleteEventLogServer/{serverID}

URI Parameters:

serverID€€(required) Specified EventLog server ID.

Description:

Delete EventLog server.

NSX API Guide Version: 6.4 Page 222

Working With Mapping Lists

Working With User to IP Mappings

GET /api/1.0/identity/userIpMapping

Query Parameters:

domainId€€(optional) Filter results on specified domain ID. Use GET

/api/1.0/directory/listDomains to retrieve all

domain IDs.

userId€€(optional) Filter results on specified user ID. Use GET

/api/3.0/ai/user to retrieve all user IDs.

ip€€(optional) Filter results on specified IP address.

time€€(optional) Filter results on specified time. Specify time in format

yyyy-MM-dd'T'HH:mm:ss. For example,

2018-12-08T11:26:21.

Description:

Query user-to-ip mapping list from database.

Working With Host to IP Mappings

GET /api/1.0/identity/hostIpMapping

Query Parameters:

domainId€€(optional) Filter results on specified domain ID. Use GET

/api/1.0/directory/listDomains to retrieve all

domain IDs.

userId€€(optional) Filter results on specified user ID. Use GET

/api/3.0/ai/user to retrieve all user IDs.

ip€€(optional) Filter results on specified IP address.

time€€(optional) Filter results on specified time. Specify time in format

yyyy-MM-dd'T'HH:mm:ss. For example,

2018-12-08T11:26:21.

Description:

Query host-to-ip mapping list from database.

Working With IP to User Mappings

NSX API Guide Version: 6.4 Page 223

GET /api/1.0/identity/ipToUserMapping

Query Parameters:

ipStringCsv€€(optional) Filter on one or more IP addresses. Specify IPv4 IP

addresses in a comma separated list.

startTime€€(optional) Start of the time period of interest. Specify time in format

yyyy-MM-dd'T'HH:mm:ss. For example,

2018-12-08T11:26:21.

endTime€€(optional) End of the time period of interest. Specify time in format

yyyy-MM-dd'T'HH:mm:ss. For example,

2018-12-08T11:26:21.

Description:

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

GET /api/1.0/identity/directoryGroupsForUser

Query Parameters:

loginName€€(optional) Specify the Active Directory username.

domainName€€(optional) Specify the full domain name (not the NetBIOS name).

Description:

Query set of Windows Domain Groups (AD Groups) to which the specified user belongs.

Request:

Body: application/xml

€<basicinfo>

€€€<objectId>directory_group-36</objectId>

€€€<objectTypeName>DirectoryGroup</objectTypeName>

€€€<vsmUuid>42337BA1-12CA-32EB-7616-98503466FE1B</vsmUuid>

€€€<nodeId>522b6528-be75-46c2-8ab5-8b9bbb9c7712</nodeId>

€€€<revision>0</revision>

€€€<type>

€€€€€<typeName>DirectoryGroup</typeName>

€€€</type>

€€€<name>AD-NSBU-Solution-Architects</name>

€€€<clientHandle></clientHandle>

€€€<extendedAttributes></extendedAttributes>

€€€<isUniversal>false</isUniversal>

€€€<universalRevision>0</universalRevision>

€</basicinfo>

€<basicinfo>

€€€<objectId>directory_group-6</objectId>

€€€<objectTypeName>DirectoryGroup</objectTypeName>

NSX API Guide Version: 6.4 Page 224

€€€<vsmUuid>42337BA1-12CA-32EB-7616-98503466FE1B</vsmUuid>

€€€<nodeId>522b6528-be75-46c2-8ab5-8b9bbb9c7712</nodeId>

€€€<revision>0</revision>

€€€<type>

€€€€€<typeName>DirectoryGroup</typeName>

€€€</type>

€€€<name>Users</name>

€€€<clientHandle></clientHandle>

€€€<extendedAttributes></extendedAttributes>

€€€<isUniversal>false</isUniversal>

€€€<universalRevision>0</universalRevision>

€</basicinfo>

€<basicinfo>

€€€<objectId>directory_group-23</objectId>

€€€<objectTypeName>DirectoryGroup</objectTypeName>

€€€<vsmUuid>42337BA1-12CA-32EB-7616-98503466FE1B</vsmUuid>

€€€<nodeId>522b6528-be75-46c2-8ab5-8b9bbb9c7712</nodeId>

€€€<revision>0</revision>

€€€<type>

€€€€€<typeName>DirectoryGroup</typeName>

€€€</type>

€€€<name>Domain Users</name>

€€€<clientHandle></clientHandle>

€€€<extendedAttributes></extendedAttributes>

€€€<isUniversal>false</isUniversal>

€€€<universalRevision>0</universalRevision>

€</basicinfo>

</basicinfolist>

Working With a Specific Static User Mapping

POST /api/1.0/identity/staticUserMapping/{userID}/{IP}

URI Parameters:

userID€€(required) User ID

IP€€(required) IP address

Description:

Create static user IP mapping.

Working With Static User Mappings

GET /api/1.0/identity/staticUserMappings

Description:

Query static user IP mapping list.

NSX API Guide Version: 6.4 Page 225

Working With Static User IP Mappings for a Specific User

GET /api/1.0/identity/staticUserMappingByUser/{userID}

URI Parameters:

userID€€(required) User ID

Description:

Query static user IP mapping for specified user.

DELETE /api/1.0/identity/staticUserMappingByUser/{userID}

URI Parameters:

userID€€(required) User ID

Description:

Delete static user IP mapping for specified user.

Working With Static User IP Mappings for a Specific IP

GET /api/1.0/identity/staticUserMappingByIP/{IP}

URI Parameters:

IP€€(required) IP address

Description:

Query static user IP mapping for specified IP.

DELETE /api/1.0/identity/staticUserMappingByIP/{IP}

URI Parameters:

IP€€(required) IP address

Description:

Delete static user IP mapping for specified IP.

NSX API Guide Version: 6.4 Page 226

Working With Activity Monitoring Syslog Support

Enable Syslog Support

POST /api/1.0/sam/syslog/enable

Description:

Enable syslog support.

Disable Syslog Support

POST /api/1.0/sam/syslog/disable

Description:

Disable syslog support.

NSX API Guide Version: 6.4 Page 227

Working With Solution Integrations

Working With Agents on a Specific Host

GET /api/2.0/si/host/{hostID}/agents

URI Parameters:

hostID€€(required) Specified host

Description:

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.

Responses:

Status Code: 200

Body: application/xml

€<agent>

€€€<agentId>nsxmgragent-1</agentId>

€€€<agentName>agent name</agentName>

€€€<serviceId>service-6</serviceId>

€€€<serviceName>EndpointService</serviceName>

€€€<operationalStatus>ENABLED</operationalStatus>

€€€<progressStatus>IN_PROGRESS</progressStatus>

€€€<vmId>vm-92</vmId>

€€€<host>host-10</host>

€€€<allocatedIpAddress>

€€€€€<id>2</id>

€€€€€<ipAddress>10.112.5.182</ipAddress>

€€€€€<gateway>10.112.5.253</gateway>

€€€€€<prefixLength>23</prefixLength>

€€€€€<dnsServer1>10.112.0.1</dnsServer1>

€€€€€<dnsServer2>10.112.0.2</dnsServer2>

€€€€€<dnsSuffix></dnsSuffix>

€€€€€<subnetId>subnet-1</subnetId>

€€€</allocatedIpAddress>

€€€<serviceStatus>

€€€€€<status>WARNING</status>

€€€€€<errorId>partner_error</errorId>

€€€€€<errorDescription>partner_error</errorDescription>

€€€</serviceStatus>

€€€<hostInfo>

€€€€€<objectId>host-10</objectId>

€€€€€<objectTypeName>HostSystem</objectTypeName>

€€€€€<nsxmgrUuid>420369CD-2311-F1F7-D4AA-1158EA688E54</nsxmgrUuid>

€€€€€<revision>1</revision>

€€€€€<type>

€€€€€€€<typeName>HostSystem</typeName>

€€€€€</type>

€€€€€<name>10.112.5.173</name>

€€€€€<scope>

NSX API Guide Version: 6.4 Page 228

€€€€€€€<id>domain-c7</id>

€€€€€€€<objectTypeName>ClusterComputeResource</objectTypeName>

€€€€€€€<name>Kaustubh-CL</name>

€€€€€</scope>

€€€€€<clientHandle></clientHandle>

€€€€€€<extendedAttributes></extendedAttributes>

€€€</hostInfo>

€€€<initialData>partner data if present</initialData>

€</agent>

</fabricAgents>

Working With a Specific Agent

GET /api/2.0/si/agent/{agentID}

URI Parameters:

agentID€€(required) Specified agent

Description:

Retrieve agent (host components and appliances) details.

Responses:

Status Code: 200

Body: application/xml

<agent>

€<agentId>nsxmgragent-1</agentId>

€<agentName>agent name</agentName>

€<serviceId>service-6</serviceId>

€<serviceName>EndpointService</serviceName>

€<operationalStatus>ENABLED</operationalStatus>

€<progressStatus>IN_PROGRESS</progressStatus>

€<vmId>vm-92</vmId>

€<host>host-10</host>

€<allocatedIpAddress>

€€€<id>2</id>

€€€<ipAddress>10.112.5.182</ipAddress>

€€€<gateway>10.112.5.253</gateway>

€€€<prefixLength>23</prefixLength>

€€€<dnsServer1>10.112.0.1</dnsServer1>

€€€<dnsServer2>10.112.0.2</dnsServer2>

€€€<dnsSuffix></dnsSuffix>

€€€<subnetId>subnet-1</subnetId>

€</allocatedIpAddress>

€<serviceStatus>

€€€<status>WARNING</status>

€€€<errorId>partner_error</errorId>

€€€<errorDescription>partner_error</errorDescription>

€</serviceStatus>

€<hostInfo>

€€€<objectId>host-10</objectId>

€€€<objectTypeName>HostSystem</objectTypeName>

NSX API Guide Version: 6.4 Page 229

€€€<nsxmgrUuid>420369CD-2311-F1F7-D4AA-1158EA688E54</nsxmgrUuid>

€€€<revision>1</revision>

€€€<type>

€€€€€<typeName>HostSystem</typeName>

€€€</type>

€€€<name>10.112.5.173</name>

€€€<scope>

€€€€€<id>domain-c7</id>

€€€€€<objectTypeName>ClusterComputeResource</objectTypeName>

€€€€€<name>Kaustubh-CL</name>

€€€</scope>

€€€<clientHandle></clientHandle>

€€€€<extendedAttributes></extendedAttributes>

€</hostInfo>

€<initialData>partner data if present</initialData>

</agent>

Working With Agents on a Specific Deployment

GET /api/2.0/si/deployment/{deploymentunitID}/agents

URI Parameters:

deploymentunitID€€(required) Specified deployment.

Description:

Retrieve all agents for the specified deployment.

Responses:

Status Code: 200

Body: application/xml

€<agent>

€€€<agentId>nsxmgragent-1</agentId>

€€€<agentName>agent name</agentName>

€€€<serviceId>service-6</serviceId>

€€€<serviceName>EndpointService</serviceName>

€€€<operationalStatus>ENABLED</operationalStatus>

€€€<progressStatus>IN_PROGRESS</progressStatus>

€€€<vmId>vm-92</vmId>

€€€<host>host-10</host>

€€€<allocatedIpAddress>

€€€€€<id>2</id>

€€€€€<ipAddress>10.112.5.182</ipAddress>

€€€€€<gateway>10.112.5.253</gateway>

€€€€€<prefixLength>23</prefixLength>

€€€€€<dnsServer1>10.112.0.1</dnsServer1>

€€€€€<dnsServer2>10.112.0.2</dnsServer2>

€€€€€<dnsSuffix></dnsSuffix>

€€€€€<subnetId>subnet-1</subnetId>

€€€</allocatedIpAddress>

€€€<serviceStatus>

NSX API Guide Version: 6.4 Page 230

€€€€€<status>WARNING</status>

€€€€€<errorId>partner_error</errorId>

€€€€€<errorDescription>partner_error</errorDescription>

€€€</serviceStatus>

€€€<hostInfo>

€€€€€<objectId>host-10</objectId>

€€€€€<objectTypeName>HostSystem</objectTypeName>

€€€€€<nsxmgrUuid>420369CD-2311-F1F7-D4AA-1158EA688E54</nsxmgrUuid>

€€€€€<revision>1</revision>

€€€€€<type>

€€€€€€€<typeName>HostSystem</typeName>

€€€€€</type>

€€€€€<name>10.112.5.173</name>

€€€€€<scope>

€€€€€€€<id>domain-c7</id>

€€€€€€€<objectTypeName>ClusterComputeResource</objectTypeName>

€€€€€€€<name>Kaustubh-CL</name>

€€€€€</scope>

€€€€€<clientHandle></clientHandle>

€€€€€<extendedAttributes></extendedAttributes>

€€€</hostInfo>

€€€<initialData>partner data</initialData>

€</agent>

</fabricAgents>

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.

GET /api/2.0/si/fabric/sync/conflicts

Description:

Retrieve conflicting deployment units and EAM agencies, if any, and the allowed operations on them.

Responses:

Status Code: 200

Body: application/xml

€<conflictExist>true</conflictExist>

€<agencies>

€€€<agenciesInfo>

€€€€€<agencyConflictInfo>

€€€€€€€<agencyId>agency-150</agencyId>

€€€€€€€<agencyName>_VCNS_264_nasingh-cluster1_VMware Endpoint</agencyName>

€€€€€</agencyConflictInfo>

€€€</agenciesInfo>

€€€<allowedOperations>

€€€€€<conflictResolverOperation>DELETE</conflictResolverOperation>

€€€€€<conflictResolverOperation>RESTORE</conflictResolverOperation>

€€€</allowedOperations>

€</agencies>

NSX API Guide Version: 6.4 Page 231

</fabricSyncConflictInfo>

PUT /api/2.0/si/fabric/sync/conflicts

Description:

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

€<agencyAction>RESTORE</agencyAction>

</conflictResolverInfo>

Delete conflicting EAM agencies

€<agencyAction>DELETE</agencyAction>

</conflictResolverInfo>

Delete deployment units for conflicting EAM agencies

€<deploymentUnitAction>DELETE</deploymentUnitAction>

</conflictResolverInfo>

Request:

Body: application/xml

€<agencyAction></agencyAction>

</conflictResolverInfo>

NSX API Guide Version: 6.4 Page 232

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

GET /api/2.0/services/macset/{macsetId}

URI Parameters:

macsetId€€(required) Specified MAC address set ID (can be retrieved by

listing the MAC address set on a scope).

Description:

Retrieve details about a MAC address set.

Responses:

Status Code: 200

Body: application/xml

€<objectId>macset-1</objectId>

€<objectTypeName>MACSet</objectTypeName>

€<vsmUuid>4226CACF-0558-AFF3-5D92-279B201C40E2</vsmUuid>

€<nodeId>72eee9ab-bb75-49ba-a782-d7dffedd180a</nodeId>

€<revision>4</revision>

€<type>

€<typeName>MACSet</typeName>

€</type>

€<name>system-generated-broadcast-macset</name>

€<scope>

€€€<id>globalroot-0</id>

€€€<objectTypeName>GlobalRoot</objectTypeName>

€€€<name>Global</name>

€</scope>

€<clientHandle></clientHandle>

€<extendedAttributes>

€€€<extendedAttribute>

€€€€€<name>isReadOnly</name>

€€€€€<value>true</value>

€€€</extendedAttribute>

€€€<extendedAttribute>

€€€€€<name>isHidden</name>

€€€€€<value>true</value>

€€€</extendedAttribute>

€€€<extendedAttribute>

€€€€€<name>facadeHidden</name>

€€€€€<value>true</value>

€€€</extendedAttribute>

€</extendedAttributes>

€<isUniversal>false</isUniversal>

€<universalRevision>0</universalRevision>

€<inheritanceAllowed>false</inheritanceAllowed>

NSX API Guide Version: 6.4 Page 233

€<value>FF:FF:FF:FF:FF:FF</value>

</macset>

PUT /api/2.0/services/macset/{macsetId}

URI Parameters:

macsetId€€(required) Specified MAC address set ID (can be retrieved by

listing the MAC address set on a scope).

Description:

Modify an existing MAC address set.

Request:

Body: application/xml

€<objectId></objectId>

€<type>

€€€<typeName></typeName>

€</type>

€<description></description>

€<name></name>

€<revision></revision>

€<objectTypeName></objectTypeName>

€<value></value>

</macset>

DELETE /api/2.0/services/macset/{macsetId}

URI Parameters:

macsetId€€(required) Specified MAC address set ID (can be retrieved by

listing the MAC address set on a scope).

Query Parameters:

force€€(optional) Indicates forced or unforced delete. With forced delete,

the object is deleted even if used in other places such as

firewall rules, causing invalid referrals. For unforced

delete, the object is deleted only if it is no used by other

configurations; otherwise the delete fails.

Description:

Delete a MAC address set.

Working With MAC Address Sets on a Specific Scope

GET /api/2.0/services/macset/scope/{scopeId}

NSX API Guide Version: 6.4 Page 234

URI Parameters:

scopeId€€(required) Can be globalroot-0, universalroot-0 or datacenterId in

upgrade use cases.

Description:

List MAC address sets on the specified scope.

Responses:

Status Code: 200

Body: application/xml

<list>

€<macset>

€€€<objectId>macset-1</objectId>

€€€<objectTypeName>MACSet</objectTypeName>

€€€<vsmUuid>4226CACF-0558-AFF3-5D92-279B201C40E2</vsmUuid>

€€€<nodeId>72eee9ab-bb75-49ba-a782-d7dffedd180a</nodeId>

€€€<revision>4</revision>

€€€<type>

€€€€€<typeName>MACSet</typeName>

€€€</type>

€€€<name>system-generated-broadcast-macset</name>

€€€<scope>

€€€€€<id>globalroot-0</id>

€€€€€<objectTypeName>GlobalRoot</objectTypeName>

€€€€€<name>Global</name>

€€€</scope>

€€€<clientHandle></clientHandle>

€€€<extendedAttributes>

€€€€€<extendedAttribute>

€€€€€€€<name>isReadOnly</name>

€€€€€€€<value>true</value>

€€€€€</extendedAttribute>

€€€€€<extendedAttribute>

€€€€€€€<name>isHidden</name>

€€€€€€€<value>true</value>

€€€€€</extendedAttribute>

€€€€€<extendedAttribute>

€€€€€€€<name>facadeHidden</name>

€€€€€€€<value>true</value>

€€€€€</extendedAttribute>

€€€</extendedAttributes>

€€€<isUniversal>false</isUniversal>

€€€<universalRevision>0</universalRevision>

€€€<inheritanceAllowed>false</inheritanceAllowed>

€€€<value>FF:FF:FF:FF:FF:FF</value>

€</macset>

</list>

POST /api/2.0/services/macset/scope/{scopeId}

URI Parameters:

scopeId€€(required) Can be globalroot-0, universalroot-0 or datacenterId in

upgrade use cases.

Description:

NSX API Guide Version: 6.4 Page 235

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.

Request:

Body: application/xml

€<objectId></objectId>

€<type>

€€€<typeName></typeName>

€</type>

€<description></description>

€<name></name>

€<objectTypeName></objectTypeName>

€<value></value>

</macset>

NSX API Guide Version: 6.4 Page 236

Working With ESX Agent Manager

vSphere ESX Agent Manager (EAM) automates the process of deploying and managing NSX Data Center for vSphere

networking and security services.

Working With EAM Status

GET /api/2.0/eam/status

Description:

Retrieve EAM status from vCenter.

You can verify the status is UP before proceeding with an NSX Data Center for vSphere install or upgrade.

Method history:

Release Modification

6.3.5 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<status>UP</status>

€<vcName>vcsa-01a.corp.local</vcName>

€<eamServiceName>VMware ESX Agent Manager</eamServiceName>

</eamStatusInfo>

Working With a Specific EAM Agent

GET /api/2.0/eam/agency/{agencyId}

URI Parameters:

agencyId€€(required) Managed object ID of the EAM agent.

Description:

Retrieve the status of a specific EAM agent.

Responses:

Status Code: 200

Body: application/xml

NSX API Guide Version: 6.4 Page 237

€<agencyId>3d02f5ac-4bb0-45a3-930c-33f280313424</agencyId>

€<status>red</status>

€<goalState>enabled</goalState>

</agencyInfo>

Working With EAM Agent Runtime Information

GET /api/2.0/eam/agency/{agencyId}/agentruntimeinfos

URI Parameters:

agencyId€€(required) Managed object ID of the EAM agent.

Description:

Retrieve the runtime information of a specific EAM agent.

Responses:

Status Code: 200

Body: application/xml

€<agentRuntimeInfo>

€€€<host>host-21</host>

€€€<receivingHearBeat>false</receivingHearBeat>

€€€<vmName></vmName>

€€€<vmPowerState>poweredOff</vmPowerState>

€€€<status>red</status>

€</agentRuntimeInfo>

€<agentRuntimeInfo>

€€€<host>host-27</host>

€€€<receivingHearBeat>false</receivingHearBeat>

€€€<vmName></vmName>

€€€<vmPowerState>poweredOff</vmPowerState>

€€€<status>red</status>

€</agentRuntimeInfo>

€<agentRuntimeInfo>

€€€<host>host-15</host>

€€€<receivingHearBeat>false</receivingHearBeat>

€€€<vmName></vmName>

€€€<vmPowerState>poweredOff</vmPowerState>

€€€<status>red</status>

€</agentRuntimeInfo>

</agentRuntimeInfos>

NSX API Guide Version: 6.4 Page 238

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 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.

GET /api/2.0/services/systemalarms

Query Parameters:

sortBy€€(optional) Parameter to sort by. Default is eventId.

pageSize€€(optional) The number of results to return.

sortOrderAscending€€(optional) Set to true to sort ascending or false to sort descending.

Default is false.

startIndex€€(optional) The starting point for returning results.

Description:

Retrieve all unresolved alarms on NSX Manager.

Method history:

Release Modification

6.3.3 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<dataPage>

€€€<pagingInfo>

€€€€€<pageSize>256</pageSize>

€€€€€<startIndex>0</startIndex>

€€€€€<totalCount>2</totalCount>

NSX API Guide Version: 6.4 Page 239

€€€€€<sortOrderAscending>false</sortOrderAscending>

€€€€€<sortBy>id</sortBy>

€€€</pagingInfo>

€€€<systemAlarm>

€€€€€<eventId>1390</eventId>

€€€€€<timestamp>1501114563913</timestamp>

€€€€€<severity>High</severity>

€€€€€<eventSource>edge-5</eventSource>

€€€€€<eventCode>130033</eventCode>

€€€€€<message>NSX Edge VM (vmId : vm-435) is not responding to NSX manager health check. Please check NSX

manager logs for details.</message>

€€€€€<module>NSX Edge Health Check</module>

€€€€€<objectId>edge-5</objectId>

€€€€€<reporterName>vShield Manager</reporterName>

€€€€€<reporterType>4</reporterType>

€€€€€<sourceType>4</sourceType>

€€€€€<isResourceUniversal>false</isResourceUniversal>

€€€€€<eventMetadata>

€€€€€€€<data>

€€€€€€€€€<key>edgeId</key>

€€€€€€€€€<value>edge-5</value>

€€€€€€€</data>

€€€€€€€<data>

€€€€€€€€€<key>edgeVmVcUUId</key>

€€€€€€€€€<value>502ecb37-306e-8cf9-4919-16bdf053bd06</value>

€€€€€€€</data>

€€€€€€€<data>

€€€€€€€€€<key>edgeVmName</key>

€€€€€€€€€<value>Perimeter-Gateway-02-0</value>

€€€€€€€</data>

€€€€€€€<data>

€€€€€€€€€<key>edgeVmId</key>

€€€€€€€€€<value>vm-435</value>

€€€€€€€</data>

€€€€€</eventMetadata>

€€€€€<resolutionAttempted>false</resolutionAttempted>

€€€€€<resolvable>true</resolvable>

€€€€€<alarmId>1390</alarmId>

€€€€€<alarmCode>130033</alarmCode>

€€€€€<alarmSource>edge-5</alarmSource>

€€€€€<target>

€€€€€€€<objectId>vm-435</objectId>

€€€€€€€<objectTypeName>VirtualMachine</objectTypeName>

€€€€€€€<vsmUuid>423A993F-BEE6-1285-58F1-54E48D508D90</vsmUuid>

€€€€€€€<nodeId>916287b3-761d-430b-8ab2-83878dfe3e7f</nodeId>

€€€€€€€<revision>13</revision>

€€€€€€€<type>

€€€€€€€€€<typeName>VirtualMachine</typeName>

€€€€€€€</type>

€€€€€€€<name>Perimeter-Gateway-02-0</name>

€€€€€€€<scope>

€€€€€€€€€<id>domain-c41</id>

€€€€€€€€€<objectTypeName>ClusterComputeResource</objectTypeName>

€€€€€€€€€<name>Management & Edge Cluster</name>

€€€€€€€</scope>

€€€€€€€<clientHandle></clientHandle>

€€€€€€€<extendedAttributes></extendedAttributes>

€€€€€€€<isUniversal>false</isUniversal>

€€€€€€€<universalRevision>0</universalRevision>

€€€€€</target>

€€€€€<alarmBeingResolved>false</alarmBeingResolved>

€€€€€<alarmMetadata>

NSX API Guide Version: 6.4 Page 240

€€€€€€€<data>

€€€€€€€€€<key>edgeId</key>

€€€€€€€€€<value>edge-5</value>

€€€€€€€</data>

€€€€€€€<data>

€€€€€€€€€<key>edgeVmVcUUId</key>

€€€€€€€€€<value>502ecb37-306e-8cf9-4919-16bdf053bd06</value>

€€€€€€€</data>

€€€€€€€<data>

€€€€€€€€€<key>edgeVmName</key>

€€€€€€€€€<value>Perimeter-Gateway-02-0</value>

€€€€€€€</data>

€€€€€€€<data>

€€€€€€€€€<key>edgeVmId</key>

€€€€€€€€€<value>vm-435</value>

€€€€€€€</data>

€€€€€</alarmMetadata>

€€€</systemAlarm>

€€€<systemAlarm>

€€€€€<eventId>1388</eventId>

€€€€€<timestamp>1501114563865</timestamp>

€€€€€<severity>High</severity>

€€€€€<eventSource>edge-5</eventSource>

€€€€€<eventCode>130027</eventCode>

€€€€€<message>NSX Edge VM (vmId : vm-435) is powered off. Please use vsphere client to power on Edge

VM</message>

€€€€€<module>NSX Edge Communication Agent</module>

€€€€€<objectId>edge-5</objectId>

€€€€€<reporterName>vShield Manager</reporterName>

€€€€€<reporterType>4</reporterType>

€€€€€<sourceType>4</sourceType>

€€€€€<isResourceUniversal>false</isResourceUniversal>

€€€€€<eventMetadata>

€€€€€€€<data>

€€€€€€€€€<key>edgeVmVcUUId</key>

€€€€€€€€€<value>502ecb37-306e-8cf9-4919-16bdf053bd06</value>

€€€€€€€</data>

€€€€€</eventMetadata>

€€€€€<resolutionAttempted>false</resolutionAttempted>

€€€€€<resolvable>true</resolvable>

€€€€€<alarmId>1388</alarmId>

€€€€€<alarmCode>130027</alarmCode>

€€€€€<alarmSource>edge-5</alarmSource>

€€€€€<target>

€€€€€€€<objectId>vm-435</objectId>

€€€€€€€<objectTypeName>VirtualMachine</objectTypeName>

€€€€€€€<vsmUuid>423A993F-BEE6-1285-58F1-54E48D508D90</vsmUuid>

€€€€€€€<nodeId>916287b3-761d-430b-8ab2-83878dfe3e7f</nodeId>

€€€€€€€<revision>13</revision>

€€€€€€€<type>

€€€€€€€€€<typeName>VirtualMachine</typeName>

€€€€€€€</type>

€€€€€€€<name>Perimeter-Gateway-02-0</name>

€€€€€€€<scope>

€€€€€€€€€<id>domain-c41</id>

€€€€€€€€€<objectTypeName>ClusterComputeResource</objectTypeName>

€€€€€€€€€<name>Management & Edge Cluster</name>

€€€€€€€</scope>

€€€€€€€<clientHandle></clientHandle>

€€€€€€€<extendedAttributes></extendedAttributes>

€€€€€€€<isUniversal>false</isUniversal>

€€€€€€€<universalRevision>0</universalRevision>

NSX API Guide Version: 6.4 Page 241

€€€€€</target>

€€€€€<alarmBeingResolved>false</alarmBeingResolved>

€€€€€<alarmMetadata>

€€€€€€€<data>

€€€€€€€€€<key>edgeVmVcUUId</key>

€€€€€€€€€<value>502ecb37-306e-8cf9-4919-16bdf053bd06</value>

€€€€€€€</data>

€€€€€</alarmMetadata>

€€€</systemAlarm>

€</dataPage>

</pagedSystemAlarmList>

Working With a Specific System Alarm

You can view and resolve alarms by alarm ID.

GET /api/2.0/services/systemalarms/{alarmId}

URI Parameters:

alarmId€€ Alarm ID.

Description:

Retrieve information about the specified alarm. Both resolved and unresolved alarms can be retrieved.

Method history:

Release Modification

6.3.0 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<eventId>262</eventId>

€<timestamp>1479121141922</timestamp>

€<severity>High</severity>

€<eventSource>Policy</eventSource>

€<eventCode>300006</eventCode>

€<message>Service Composer is out of sync due to failure on sync on reboot operation</message>

€<module>Policy</module>

€<objectId>servicecomposer</objectId>

€<reporterName>NSX Manager</reporterName>

€<reporterType>1</reporterType>

€<sourceType>1</sourceType>

€<displayName>Service Composer</displayName>

€<isResourceUniversal>false</isResourceUniversal>

€<eventMetadata></eventMetadata>

€<resolutionAttempted>true</resolutionAttempted>

€<resolvable>true</resolvable>

€<alarmId>262</alarmId>

€<alarmCode>300006</alarmCode>

NSX API Guide Version: 6.4 Page 242

€<alarmSource>Policy</alarmSource>

€<alarmBeingResolved>false</alarmBeingResolved>

€<alarmMetadata></alarmMetadata>

</systemAlarm>

POST /api/2.0/services/systemalarms/{alarmId}

URI Parameters:

alarmId€€ Alarm ID.

Query Parameters:

action€€ Use action=resolve to resolve the specified alarm.

Description:

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.

NSX API Guide Version: 6.4 Page 243

Working With Alarms from a Specific Source

You can view and resolve alarms from a specific source.

GET /api/2.0/services/alarms/{sourceId}

URI Parameters:

sourceId€€ ID of the object for which you want to manage alarms.

sourceId can be the ID of a cluster, host, resource pool,

security group, or edge.

Description:

Retrive all alarms from the specified source.

POST /api/2.0/services/alarms/{sourceId}

URI Parameters:

sourceId€€ ID of the object for which you want to manage alarms.

sourceId can be the ID of a cluster, host, resource pool,

security group, or edge.

Query Parameters:

action€€ Use action=resolve to resolve alarms.

Description:

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 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.

Request:

Body: application/xml

€€€<systemAlarm>

€€€€€€€<eventId>79965</eventId>

€€€€€€€<timestamp>1485556529744</timestamp>

€€€€€€€<severity>High</severity>

€€€€€€€<eventSource>edge-3</eventSource>

€€€€€€€<eventCode>130027</eventCode>

€€€€€€€<message>NSX Edge VM (vmId : vm-430) is powered off. Please use vsphere client to power on Edge

VM</message>

€€€€€€€<module>NSX Edge Communication Agent</module>

€€€€€€€<objectId>edge-3</objectId>

€€€€€€€<reporterName>vShield Manager</reporterName>

€€€€€€€<reporterType>4</reporterType>

€€€€€€€<sourceType>4</sourceType>

€€€€€€€<isResourceUniversal>false</isResourceUniversal>

€€€€€€€<eventMetadata>

NSX API Guide Version: 6.4 Page 244

€€€€€€€€€€€<data>

€€€€€€€€€€€€€€€<key>edgeVmVcUUId</key>

€€€€€€€€€€€€€€€<value>502e05c2-380f-998c-35ec-1f48991fe7e0</value>

€€€€€€€€€€€</data>

€€€€€€€</eventMetadata>

€€€€€€€<resolutionAttempted>false</resolutionAttempted>

€€€€€€€<resolvable>true</resolvable>

€€€€€€€<alarmId>79965</alarmId>

€€€€€€€<alarmCode>130027</alarmCode>

€€€€€€€<alarmSource>edge-3</alarmSource>

€€€€€€€<target>

€€€€€€€€€€€<objectId>vm-430</objectId>

€€€€€€€€€€€<objectTypeName>VirtualMachine</objectTypeName>

€€€€€€€€€€€<vsmUuid>423A993F-BEE6-1285-58F1-54E48D508D90</vsmUuid>

€€€€€€€€€€€<nodeId>916287b3-761d-430b-8ab2-83878dfe3e7f</nodeId>

€€€€€€€€€€€<revision>18</revision>

€€€€€€€€€€€<type>

€€€€€€€€€€€€€€€<typeName>VirtualMachine</typeName>

€€€€€€€€€€€</type>

€€€€€€€€€€€<name>Perimeter-Gateway-01-0</name>

€€€€€€€€€€€<scope>

€€€€€€€€€€€€€€€<id>domain-c41</id>

€€€€€€€€€€€€€€€<objectTypeName>ClusterComputeResource</objectTypeName>

€€€€€€€€€€€€€€€<name>Management & Edge Cluster</name>

€€€€€€€€€€€</scope>

€€€€€€€€€€€<clientHandle></clientHandle>

€€€€€€€€€€€<extendedAttributes></extendedAttributes>

€€€€€€€€€€€<isUniversal>false</isUniversal>

€€€€€€€€€€€<universalRevision>0</universalRevision>

€€€€€€€</target>

€€€€€€€<alarmBeingResolved>false</alarmBeingResolved>

€€€€€€€<alarmMetadata>

€€€€€€€€€€€<data>

€€€€€€€€€€€€€€€<key>edgeVmVcUUId</key>

€€€€€€€€€€€€€€€<value>502e05c2-380f-998c-35ec-1f48991fe7e0</value>

€€€€€€€€€€€</data>

€€€€€€€</alarmMetadata>

€€€</systemAlarm>

€€€<systemAlarm>

€€€€€€€<eventId>79967</eventId>

€€€€€€€<timestamp>1485556529774</timestamp>

€€€€€€€<severity>High</severity>

€€€€€€€<eventSource>edge-3</eventSource>

€€€€€€€<eventCode>130033</eventCode>

€€€€€€€<message>NSX Edge VM (vmId : vm-430) is not responding to NSX manager health check. Please check NSX

manager logs for details.</message>

€€€€€€€<module>NSX Edge Health Check</module>

€€€€€€€<objectId>edge-3</objectId>

€€€€€€€<reporterName>vShield Manager</reporterName>

€€€€€€€<reporterType>4</reporterType>

€€€€€€€<sourceType>4</sourceType>

€€€€€€€<isResourceUniversal>false</isResourceUniversal>

€€€€€€€<eventMetadata>

€€€€€€€€€€€<data>

€€€€€€€€€€€€€€€<key>edgeVmVcUUId</key>

€€€€€€€€€€€€€€€<value>502e05c2-380f-998c-35ec-1f48991fe7e0</value>

€€€€€€€€€€€</data>

€€€€€€€€€€€<data>

€€€€€€€€€€€€€€€<key>edgeId</key>

€€€€€€€€€€€€€€€<value>edge-3</value>

€€€€€€€€€€€</data>

€€€€€€€€€€€<data>

NSX API Guide Version: 6.4 Page 245

€€€€€€€€€€€€€€€<key>edgeVmName</key>

€€€€€€€€€€€€€€€<value>Perimeter-Gateway-01-0</value>

€€€€€€€€€€€</data>

€€€€€€€€€€€<data>

€€€€€€€€€€€€€€€<key>edgeVmId</key>

€€€€€€€€€€€€€€€<value>vm-430</value>

€€€€€€€€€€€</data>

€€€€€€€</eventMetadata>

€€€€€€€<resolutionAttempted>false</resolutionAttempted>

€€€€€€€<resolvable>true</resolvable>

€€€€€€€<alarmId>79967</alarmId>

€€€€€€€<alarmCode>130033</alarmCode>

€€€€€€€<alarmSource>edge-3</alarmSource>

€€€€€€€<target>

€€€€€€€€€€€<objectId>vm-430</objectId>

€€€€€€€€€€€<objectTypeName>VirtualMachine</objectTypeName>

€€€€€€€€€€€<vsmUuid>423A993F-BEE6-1285-58F1-54E48D508D90</vsmUuid>

€€€€€€€€€€€<nodeId>916287b3-761d-430b-8ab2-83878dfe3e7f</nodeId>

€€€€€€€€€€€<revision>18</revision>

€€€€€€€€€€€<type>

€€€€€€€€€€€€€€€<typeName>VirtualMachine</typeName>

€€€€€€€€€€€</type>

€€€€€€€€€€€<name>Perimeter-Gateway-01-0</name>

€€€€€€€€€€€<scope>

€€€€€€€€€€€€€€€<id>domain-c41</id>

€€€€€€€€€€€€€€€<objectTypeName>ClusterComputeResource</objectTypeName>

€€€€€€€€€€€€€€€<name>Management & Edge Cluster</name>

€€€€€€€€€€€</scope>

€€€€€€€€€€€<clientHandle></clientHandle>

€€€€€€€€€€€<extendedAttributes></extendedAttributes>

€€€€€€€€€€€<isUniversal>false</isUniversal>

€€€€€€€€€€€<universalRevision>0</universalRevision>

€€€€€€€</target>

€€€€€€€<alarmBeingResolved>false</alarmBeingResolved>

€€€€€€€<alarmMetadata>

€€€€€€€€€€€<data>

€€€€€€€€€€€€€€€<key>edgeVmVcUUId</key>

€€€€€€€€€€€€€€€<value>502e05c2-380f-998c-35ec-1f48991fe7e0</value>

€€€€€€€€€€€</data>

€€€€€€€€€€€<data>

€€€€€€€€€€€€€€€<key>edgeId</key>

€€€€€€€€€€€€€€€<value>edge-3</value>

€€€€€€€€€€€</data>

€€€€€€€€€€€<data>

€€€€€€€€€€€€€€€<key>edgeVmName</key>

€€€€€€€€€€€€€€€<value>Perimeter-Gateway-01-0</value>

€€€€€€€€€€€</data>

€€€€€€€€€€€<data>

€€€€€€€€€€€€€€€<key>edgeVmId</key>

€€€€€€€€€€€€€€€<value>vm-430</value>

€€€€€€€€€€€</data>

€€€€€€€</alarmMetadata>

€€€</systemAlarm>

</systemAlarms>

NSX API Guide Version: 6.4 Page 246

Working With System Scale (Capacity Parameter) Dashboard

The System Scale (Capacity Parameter) dashboard displays information about the current object count, maximum

object supported by the system, and percentage usage for each parameter. The capacity parameter report collects

information about the current system scale and the supported scale parameters. It also allows you to view a warning

threshold value and percentage usage for each the parameter. It also allows you to view and configure a warning

threshold value at the system level. If the current global threshold values exceeds a specified threshold value, a

warning indicator is displayed on the UI to alert that the maximum supported scale is approaching. This information is

also logged and included in the support bundle.

System Scale (Capacity Parameter) Dashboard Report

Retrieves the current and supported scale configuration of the system.

GET /api/2.0/capacity-parameters/report

Description:

The output displays scale summary, current scale value, supported system scale value, threshold value, and the

percentage usage for each parameter.

Method history:

Release Modification

6.4.0 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<timeStamp>2017-11-06 09:53:50.057</timeStamp>

€<ScaleSummary>

€€€€€<parametersAboveSupportedValue>0</parametersAboveSupportedValue>

€€€€€<parametersAboveThreshold>0</parametersAboveThreshold>

€€€€€<parametersBelowThreshold>18</parametersBelowThreshold>

€</ScaleSummary>

€<CapacityParameter>

€€€€€<name>Security Policies</name>

€€€€€<currValue>0</currValue>

€€€€€<supportedValue>10000</supportedValue>

€€€€€<threshold>80</threshold>

€€€€€<percentageUsed>0.0</percentageUsed>

€</CapacityParameter>

€<CapacityParameter>

€€€€€<name>IP Pools</name>

€€€€€<currValue>0</currValue>

€€€€€<supportedValue>10000</supportedValue>

€€€€€<threshold>80</threshold>

€€€€€<percentageUsed>0.0</percentageUsed>

€</CapacityParameter>

€<CapacityParameter>

€€€€€<name>AD Domains</name>

€€€€€<currValue>0</currValue>

€€€€€<supportedValue>15</supportedValue>

NSX API Guide Version: 6.4 Page 247

€€€€€<threshold>80</threshold>

€€€€€<percentageUsed>0.0</percentageUsed>

€</CapacityParameter>

</CapacityParameters>

System Scale (Capacity Parameter) Dashboard Threshold

You can find out and change the global threshold for the system, if required. The default global threshold value for the

system is set to 80.

GET /api/2.0/capacity-parameters/thresholds

Description:

Retrieves the global threshold for the system. The System Scale dashboard on UI displays warning when the threshold

value is reached.

Method history:

Release Modification

6.4.0 Method introduced.

Responses:

Status Code: 200

Body: application/xml

€<globalThresholdPercentage>80</globalThresholdPercentage>

</CapacityThresholds>

PUT /api/2.0/capacity-parameters/thresholds

Description:

You can configure the scale threshold of the system. If you change the global threshold from 80 to 70, it means the

System Scale dashboard displays warning when the system threshold reaches at 70%.

Method history:

Release Modification

6.4.0 Method introduced.

Request:

Body: application/xml

€<globalThresholdPercentage>70</globalThresholdPercentage>

</CapacityThresholds>

NSX API Guide Version: 6.4 Page 248

NSX API Guide Version: 6.4 Page 249

Working With Custom Dashboard Widget

You can add up to five custom widgets to the dashboard. You can also share widgets with other users by setting the

shared parameter to true in the widget configuration. It is recommended to have total of maximum 10 widgets on your

dashboard. The following two types of widgets are supported:

• Label Value, and

• Grid (or Table)

Data Types

Following data types are supported:

• Datasource

• GridConfiguration

• LabelValueConfiguration

• UrlAlias

• Label

• Icon

• WidgetConfigurationList

• WidgetQueryParameters

Datasource

Parameter Description Type Comments

display_name

Datasource Instance

Name. Only NSX-API is

supported as ‘default’

datasource. String Required

urls

Array of relative urls and

their aliases. Array of UrlAlias Required

GridConfiguration

Parameter Description Type Comments

resource_type

Must be set to the value

GridConfiguration. String

Required

Read only

Enum: GridConfiguration,

LabelValueConfiguration

datasources

Array of Datasource Instances

with their relative urls.

The 'datasources' represent

the sources from which data is

fetched.Currently, only

NSX-API is supported as a

'default' datasource. An

example of specifying 'default'

datasource along with the urls

to fetch data from is given at

'example_request' section of

'CreateWidgetConfiguration'

API. Array of Datasource Minimum items: 1

description

Description of this widget

configuration. String Maximum length: 1024

category_id

Category of this widget

configuration. If category_id is

not provided, system

generates a category ID. String

NSX API Guide Version: 6.4 Page 250

category_display_name

Display name of the category.

If category display name is not

provided, then category_id is

used as its display name. String

columns

Columns describes the

information about individual

columns such as column

heading or label, data type of

the column and so on. Array of ColumnItem Required

shared

Share widget configuration

with other users. Boolean Default is False

GridConfiguration: Grid Column - Represents column of the Grid

ColumnItem

Parameter Description Type Comments

field

Column Field.

Field from which values of

the column are derived. String Required

label Label of the column. Label Required

render_configuration

Render configuration to be

applied, if any.

Array of

RenderConfiguration

type Data type of the field. String

Required

Options are String,

Number, Date. Default is

String

Label Value Configuration

Parameter Description Type Comments

resource_type

Label Value Configuration.

Must be set to the value

LabelValueConfiguration. String Required. Read only

sub_type

[Optional] Sub-type of the

resource type. When the

sub-type is omitted, then

the parent type

LabelValueConfiguration

will be considered.

For

LabelValueConfiguration

the available sub-type is

aggregate_count. String Read only

object_type

[Optional] User defined type

for identifying the widget’s

data. Example:

HostConnStatuses. String

datasources

Array of Datasource

Instances with their relative

URLs. Array of Datasource Required. Read only

description

Description of this widget

configuration. String Maximum length:1024

display_name Widget Title. String Required

NSX API Guide Version: 6.4 Page 251

category_id

Category of this widget

configuration.

If category_id is not

provided, system generates

an ID for category. String

category_display_name

Display name of the

category.

If category display name is

not provided, then

category_id is used as the

display name. String

properties

Properties consisting of

labels and values. Array of PropertyItem Required

shared

Share the widget

configuration with other

users. Boolean Default is False

revision

Revision of this widget

configuration. It is

auto-generated and

auto-updated. Integer Read only

PropertyItem

Parameter Description Type Comments

field Field of the Property. String Required

label Label of the Property. Label Required

render_configuration Render Configuration.

Array of

RenderConfiguration

type Field data type. String

Options are String,

Number, and Date. Default

is String.

drilldown id

ID of the drill-down widget

configuration. String

RenderConfiguration

Parameter Description Type Comments

condition

Expression for evaluating

condition. String

display_value

Overridden value to

display, if any. String

icons

Icons to be applied at

dashboard for widgets and

UI elements. Array of Icon Minimum item is 0

UrlAlias

Parameter Description Type Comments

alias Alias name for URL. String

url URL. String Required

Label

NSX API Guide Version: 6.4 Page 252

Parameter Description Type Comments

text

Text to be displayed at the

label. String

Required

Maximum length is 255

url URL. String Required

Icon

Parameter Description Type Comments

type

Icon is rendered based on

its type.

For example, if ERROR is

chosen, then icon

representing error will be

rendered. String

Options are ERROR,

WARNING, INFO,

INPROGRESS,

SUCCESS, DETAIL,

NOT_AVAILABLE

WidgetConfigurationList

Parameter Description Type Comments

widgetconfigurations

Array of widget

configurations.

Array of

widgetconfiguration Required. Read only

WidgetQueryParameters

Parameter Description Type Comments

widget_ids

Comma separated IDs of

the WidgetConfiguration to

be queried. String Read only

Expressions:

Expressions can be used in widget configurations. Expressions should be evaluable on their own without any “variable

declaration”. For example, you can give following expressions:

* Arithmetic:

€(1 + 2)= evaluates to 3

€(12.0 - 5.2) = evaluates to 6.8

€(6 * 12 + 5 / 2.6) = evaluates to 73.923

€(12 % 2)= evaluates to 0

€(6 / 4 )= evaluates to 1.5

€(-12 + 77.2) = evaluates to 65.2

€(x * 1.1 + y) = Not allowed as x and y are not defined.

* Calling methods:

€"(\"\").isEmpty()" = evaluates to boolean true.

* Accessing properties:

€"(\"Some long string\").length == 16" = evaluates to boolean true. But you can not give expressions like:

€€€“V1 + 2”

€€€“aString.length()” and so on because these expressions require the definition of “V1” and “aString” to be

present in the context, and there is no place in widget configuration to define it.

€€€€* No Java statements are supported, only expressions are supported.

Anatomy of an Expression in Widget Configuration

€€* Expression

€€* Basic form: #{<datasource>.<url-alias>.<jsonpath>}

€€* Examples:

NSX API Guide Version: 6.4 Page 253

€€€€€€* Expression: € #{default.si.versionInfo.majorVersion}

€€€€€€* API: api/1.0/appliance-management/summary/system

€* Expression: € #{default.si.cpuInfoDto.totalNoOfCPUs} €€€€€€€€€€€€€€€€€€€€€€€€€

€€€€€€* API: api/1.0/appliance-management/summary/system

€€€€€€* Expression: #{default.summary.preparedHostsTotalNumber} €€€€€€€€€€€€€

€€€€€€* API: api/2.0/vdn/inventory/hosts/status/summary

€€€€€€* Function form: #{<datasource>.<url-alias>.<jsonpath>}.function()

€€€€€€* Example:

€* Expression: €#{default.se.dataPage.data}.size() €€€€€€€€€€€€€€€

€€€€€€* API: api/2.0/systemevent

Anatomy of a Condition in Widget Configuration

€€€* Condition

€€€€€* Evaluates to a boolean (true or false)

€€€€€€* Form: expression == value

€€€€€€€€€* Examples:

€€€€€€€€€€€€€#{default.status.degraded_count} < 10

€€€€€€€€€€€€€#{default.status.results}.size() < 10

€€€€€€€€€€€€€#{default.status.status} == \"INSTALLED_DISABLED\"

€€€€€€€€€€€€€#{default.config.allow_mirrored} == true

€€€€€€€€€€€€€#{default.config.allow_mirrored} €€€€€€€//A boolean can be used directly in expression.

GET /api/2.0/services/dashboard/ui-views/dashboard/widgetconfigurations

Description:

Retrieves configuration details for all the widgets available on dashboard.

Method history:

Release Modification

6.4.0 Method introduced.

Responses:

Status Code: 200

Body: application/xml

<com.vmware.vshield.vsm.dashboard.dto.custom.WidgetConfigurationListDto>

€<widgetconfigurations>

€<com.vmware.vshield.vsm.dashboard.dto.custom.LabelValueConfigurationDto>

€€€<objectId>LabelValueConfiguration_HostCommunicationChannelStatus</objectId>

€€€<resourceType>LabelValueConfiguration</resourceType>

€€€<subType>aggregate_count</subType>

€€€<objectType>HostCommunicationChannelStatus</objectType>

€€€<displayName>Host Communication Channel Status</displayName>

€€€<systemResourceFlag>true</systemResourceFlag>

€€€<createUser>system</createUser>

€€€<lastUpdatedBy>system</lastUpdatedBy>

€€€<revision>0</revision>

€€€<shared>true</shared>

€€€<categoryId>cluster_preparation_status</categoryId>

€€€<categoryDisplayName>Fabric Status</categoryDisplayName>

€€€<refreshInterval>0</refreshInterval>

€€€<weight>9300</weight>

€€€<datasources>

€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.DatasourceDto>

NSX API Guide Version: 6.4 Page 254

€€€€€€€€€€€<urls>

€€€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.UrlAliasDto>

€€€€€€€€€€€€€€€€€€€<alias>status</alias>

€€€€€€€€€€€€€€€€€€€<url>api/2.0/vdn/inventory/hosts/connection/DOWN</url>

€€€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.UrlAliasDto>

€€€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.UrlAliasDto>

€€€€€€€€€€€€€€€€€€€<alias>summary</alias>

€€€€€€€€€€€€€€€€€€€<url>api/2.0/vdn/inventory/hosts/status/summary</url>

€€€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.UrlAliasDto>

€€€€€€€€€€€</urls>

€€€€€€€€€€€<displayName>default</displayName>

€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.DatasourceDto>

€€€</datasources>

€€€<properties>

€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.PropertyItemDto>

€€€€€€€€€€€<field>0</field>

€€€€€€€€€€€<renderConfiguration>

€€€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€€€€€€€€€€€<displayValue>#{default.summary.downHostsTotalNumber}</displayValue>

€€€€€€€€€€€€€€€€€€€<condition>#{default.summary.downHostsTotalNumber} != 0</condition>

€€€€€€€€€€€€€€€€€€€<icons>

€€€€€€€€€€€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.IconDto>

€€€€€€€€€€€€€€€€€€€€€€€€€€€<type>ERROR</type>

€€€€€€€€€€€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.IconDto>

€€€€€€€€€€€€€€€€€€€</icons>

€€€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€€€</renderConfiguration>

€€€€€€€€€€€<label>

€€€€€€€€€€€€€€€<text>Down</text>

€€€€€€€€€€€</label>

€€€€€€€€€€€<type>Number</type>

€€€€€€€€€€€<drilldownId>GridConfiguration_hccsGrid</drilldownId>

€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.PropertyItemDto>

€€€</properties>

€€€<totalCount>#{default.summary.preparedHostsTotalNumber}</totalCount>

€€€<totalCountDesc>Hosts</totalCountDesc>

€</com.vmware.vshield.vsm.dashboard.dto.custom.LabelValueConfigurationDto>

<com.vmware.vshield.vsm.dashboard.dto.custom.GridConfigurationDto>

€€€<objectId>GridConfiguration_hccsGrid</objectId>

€€€<resourceType>GridConfiguration</resourceType>

€€€<objectType>HostConnStatuses</objectType>

€€€<displayName>Host Communication Channel Status Details</displayName>

€€€<systemResourceFlag>true</systemResourceFlag>

€€€<createUser>system</createUser>

€€€<lastUpdatedBy>system</lastUpdatedBy>

€€€<revision>0</revision>

€€€<shared>true</shared>

€€€<categoryId>drilldown</categoryId>

€€€<categoryDisplayName>drilldown</categoryDisplayName>

€€€<refreshInterval>0</refreshInterval>

€€€<weight>9900</weight>

€€€<datasources>

€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.DatasourceDto>

€€€€€€€€€€€<urls>

€€€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.UrlAliasDto>

€€€€€€€€€€€€€€€€€€€<alias>hosts</alias>

€€€€€€€€€€€€€€€€€€€<url>api/2.0/vdn/inventory/hosts/connection/DOWN</url>

€€€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.UrlAliasDto>

€€€€€€€€€€€</urls>

€€€€€€€€€€€<displayName>default</displayName>

€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.DatasourceDto>

€€€</datasources>

NSX API Guide Version: 6.4 Page 255

€€€<columns>

€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.ColumnItemDto>

€€€€€€€€€€€<field>#{hostName}</field>

€€€€€€€€€€€<renderConfiguration></renderConfiguration>

€€€€€€€€€€€<label>

€€€€€€€€€€€€€€€<text>Host</text>

€€€€€€€€€€€</label>

€€€€€€€€€€€<type>String</type>

€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.ColumnItemDto>

€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.ColumnItemDto>

€€€€€€€€€€€<field>#{hostToControllerConn}</field>

€€€€€€€€€€€<renderConfiguration></renderConfiguration>

€€€€€€€€€€€<label>

€€€€€€€€€€€€€€€<text>Control Plane Agent to Controller</text>

€€€€€€€€€€€</label>

€€€€€€€€€€€<type>String</type>

€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.ColumnItemDto>

€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.ColumnItemDto>

€€€€€€€€€€€<field>#{nsxMgrToFirewallAgentConn}</field>

€€€€€€€€€€€<renderConfiguration></renderConfiguration>

€€€€€€€€€€€<label>

€€€€€€€€€€€€€€€<text>NSX Manager to Firewall Agent</text>

€€€€€€€€€€€</label>

€€€€€€€€€€€<type>String</type>

€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.ColumnItemDto>

€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.ColumnItemDto>

€€€€€€€€€€€<field>#{nsxMgrToControlPlaneAgentConn}</field>

€€€€€€€€€€€<renderConfiguration></renderConfiguration>

€€€€€€€€€€€<label>

€€€€€€€€€€€€€€€<text>NSX Manager to Control Plane Agent</text>

€€€€€€€€€€€</label>

€€€€€€€€€€€<type>String</type>

€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.ColumnItemDto>

€€€</columns>

€€€<rowListField>default.hosts.hostConnStatuses.*</rowListField>

€€€<pageSize>0</pageSize>

</com.vmware.vshield.vsm.dashboard.dto.custom.GridConfigurationDto>

<com.vmware.vshield.vsm.dashboard.dto.custom.LabelValueConfigurationDto>

€€€<objectId>LabelValueConfiguration_ShortLivedSettings</objectId>

€€€<resourceType>LabelValueConfiguration</resourceType>

€€€<displayName>Tools</displayName>

€€€<systemResourceFlag>true</systemResourceFlag>

€€€<createUser>system</createUser>

€€€<lastUpdatedBy>system</lastUpdatedBy>

€€€<revision>0</revision>

€€€<shared>true</shared>

€€€<categoryId>short_lived_settings</categoryId>

€€€<categoryDisplayName>Tools</categoryDisplayName>

€€€<refreshInterval>0</refreshInterval>

€€€<weight>9200</weight>

€€€<datasources>

€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.DatasourceDto>

€€€€€€€€€€€<urls>

€€€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.UrlAliasDto>

€€€€€€€€€€€€€€€€€€€<alias>flowMonStatus</alias>

€€€€€€€€€€€€€€€€€€€<url>api/2.1/app/flow/config</url>

€€€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.UrlAliasDto>

€€€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.UrlAliasDto>

€€€€€€€€€€€€€€€€€€€<alias>appMonStatus</alias>

€€€€€€€€€€€€€€€€€€€<url>api/internal/appmon/currentsession</url>

€€€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.UrlAliasDto>

€€€€€€€€€€€</urls>

NSX API Guide Version: 6.4 Page 256

€€€€€€€€€€€<displayName>default</displayName>

€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.DatasourceDto>

€€€</datasources>

€€€<properties>

€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.PropertyItemDto>

€€€€€€€€€€€<field>#{default.flowMonStatus.collectFlows}</field>

€€€€€€€€€€€<renderConfiguration>

€€€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€€€€€€€€€€€<displayValue>"On"</displayValue>

€€€€€€€€€€€€€€€€€€€<condition>#{default.flowMonStatus.collectFlows} == true</condition>

€€€€€€€€€€€€€€€€€€€<icons>

€€€€€€€€€€€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.IconDto>

€€€€€€€€€€€€€€€€€€€€€€€€€€€<type>WARNING</type>

€€€€€€€€€€€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.IconDto>

€€€€€€€€€€€€€€€€€€€</icons>

€€€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€€€€€€€€€€€<displayValue>"Off"</displayValue>

€€€€€€€€€€€€€€€€€€€<condition>#{default.flowMonStatus.collectFlows} == false</condition>

€€€€€€€€€€€€€€€€€€€<icons></icons>

€€€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€€€</renderConfiguration>

€€€€€€€€€€€<label>

€€€€€€€€€€€€€€€<text>Flow Monitoring</text>

€€€€€€€€€€€</label>

€€€€€€€€€€€<type>String</type>

€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.PropertyItemDto>

€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.PropertyItemDto>

€€€€€€€€€€€<field>#{default.appMonStatus.startTime}</field>

€€€€€€€€€€€<renderConfiguration>

€€€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€€€€€€€€€€€<displayValue>"On"</displayValue>

€€€€€€€€€€€€€€€€€€€<condition>#{default.appMonStatus.startTime} != 0</condition>

€€€€€€€€€€€€€€€€€€€<icons>

€€€€€€€€€€€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.IconDto>

€€€€€€€€€€€€€€€€€€€€€€€€€€€<type>WARNING</type>

€€€€€€€€€€€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.IconDto>

€€€€€€€€€€€€€€€€€€€</icons>

€€€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€€€€€€€€€€€<displayValue>"Off"</displayValue>

€€€€€€€€€€€€€€€€€€€<condition>#{default.appMonStatus.startTime} == 0</condition>

€€€€€€€€€€€€€€€€€€€<icons></icons>

€€€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€€€</renderConfiguration>

€€€€€€€€€€€<label>

€€€€€€€€€€€€€€€<text>Endpoint Monitoring</text>

€€€€€€€€€€€</label>

€€€€€€€€€€€<type>String</type>

€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.PropertyItemDto>

€€€</properties>

</com.vmware.vshield.vsm.dashboard.dto.custom.LabelValueConfigurationDto>

<com.vmware.vshield.vsm.dashboard.dto.custom.LabelValueConfigurationDto>

€€€<objectId>LabelValueConfiguration_SystemScale</objectId>

€€€<resourceType>LabelValueConfiguration</resourceType>

€€€<displayName>System Scale</displayName>

€€€<systemResourceFlag>true</systemResourceFlag>

€€€<createUser>system</createUser>

€€€<lastUpdatedBy>system</lastUpdatedBy>

€€€<revision>0</revision>

€€€<shared>true</shared>

€€€<categoryId>system_scale_overview</categoryId>

NSX API Guide Version: 6.4 Page 257

€€€<categoryDisplayName>System Scale</categoryDisplayName>

€€€<refreshInterval>0</refreshInterval>

€€€<weight>9100</weight>

€€€<datasources>

€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.DatasourceDto>

€€€€€€€€€€€<urls>

€€€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.UrlAliasDto>

€€€€€€€€€€€€€€€€€€€<alias>systemScale</alias>

€€€€€€€€€€€€€€€€€€€<url>/api/2.0/capacity-parameters/report</url>

€€€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.UrlAliasDto>

€€€€€€€€€€€</urls>

€€€€€€€€€€€<displayName>default</displayName>

€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.DatasourceDto>

€€€</datasources>

€€€<properties>

€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.PropertyItemDto>

€€€€€€€€€€€<field>0</field>

€€€€€€€€€€€<renderConfiguration>

€€€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€€€€€€€€€€€<displayValue>#{default.systemScale.scaleSummary.parametersAboveSupportedValue}</displayV

alue>

€€€€€€€€€€€€€€€€€€€<condition>#{default.systemScale.scaleSummary.parametersAboveSupportedValue} !=

0</condition>

€€€€€€€€€€€€€€€€€€€<icons>

€€€€€€€€€€€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.IconDto>

€€€€€€€€€€€€€€€€€€€€€€€€€€€<type>ERROR</type>

€€€€€€€€€€€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.IconDto>

€€€€€€€€€€€€€€€€€€€</icons>

€€€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€€€</renderConfiguration>

€€€€€€€€€€€<label>

€€€€€€€€€€€€€€€<text>Alerts</text>

€€€€€€€€€€€</label>

€€€€€€€€€€€<type>Number</type>

€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.PropertyItemDto>

€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.PropertyItemDto>

€€€€€€€€€€€<field>0</field>

€€€€€€€€€€€<renderConfiguration>

€€€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€€€€€€€€€€€<displayValue>#{default.systemScale.scaleSummary.parametersAboveThreshold}</displayValue>

€€€€€€€€€€€€€€€€€€€<condition>#{default.systemScale.scaleSummary.parametersAboveThreshold} != 0</condition>

€€€€€€€€€€€€€€€€€€€<icons>

€€€€€€€€€€€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.IconDto>

€€€€€€€€€€€€€€€€€€€€€€€€€€€<type>WARNING</type>

€€€€€€€€€€€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.IconDto>

€€€€€€€€€€€€€€€€€€€</icons>

€€€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€€€</renderConfiguration>

€€€€€€€€€€€<label>

€€€€€€€€€€€€€€€<text>Warnings</text>

€€€€€€€€€€€</label>

€€€€€€€€€€€<type>Number</type>

€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.PropertyItemDto>

€€€</properties>

</com.vmware.vshield.vsm.dashboard.dto.custom.LabelValueConfigurationDto>

€</widgetconfigurations>

</com.vmware.vshield.vsm.dashboard.dto.custom.WidgetConfigurationListDto>

POST /api/2.0/services/dashboard/ui-views/dashboard/widgetconfigurations

NSX API Guide Version: 6.4 Page 258

Description:

Creates a new Widget Configuration and adds it to the default Dashboard on UI. Supported resource_type are

LabelValueConfiguration and GridConfiguration.

Notes for Expressions in Widget Configuration

Expressions should be given in a single line. If an expression spans multiple lines, then form the expression in a single

line. Order of evaluation of expressions is as follows:

• First, render configurations are evaluated in their order of appearance in the widget configuration. The field is

evaluated at the end.

• Next, when render configuration is provided then the order of evaluation is as follows:

- If expressions provided in condition and display value are well-formed and free of runtime errors such as null

pointers and evaluates to true; then the remaining render configurations are not evaluated, and the current

render configurations display value is taken as the final value.

- If expression provided in condition of render configuration is false, then next render configuration is evaluated.

- Finally, field is evaluated only when every render configuration evaluates to false and no error occurs during

steps mentioned above. If an error occurs during evaluation of render configuration, then an error message:

"ERROR: See the Error_Messages field of this report for details" is shown. The display value corresponding to

that label is not shown and evaluation of the remaining render configurations continues to collect and show all

the error messages (marked with the Label for identification) as Error_Messages: {}. If during evaluation of

expressions for any label-value pair an error occurs, then it is marked with error. The errors are shown in the

report, along with the label value pairs that are error-free.

Important Note for text in condition, field and render configuration's display value: For elements that take

expressions, strings should be provided by escaping them with a back-slash. These elements are - condition, field and

render_configuration's display_value.

Notes for Drilldowns: Only GridConfiguration is supported as drilldown widget. To make a widget as a drilldown, its

category_id should be set as drilldown. Drilldowns are supported for aggregate_count (subtype of

LabelValueConfiguration) widgets only. In other words, only 'aggregate_count' widgets can have drilldowns.

Notes for Sharing the widget to other users: Use a valid vsphere user, who has an NSX role assigned that has

sufficient permissions, to create the widget and it will get displayed on the UI when that vsphere user logs in. For other

users to view the widget on the UI, the owner (user who owners that widget) needs to share the widget (set shared

parameter to true).

Method history:

Release Modification

6.4.0 Method introduced.

Request:

Body: application/xml

<com.vmware.vshield.vsm.dashboard.dto.custom.LabelValueConfigurationDto>

€<objectId>LabelValueConfiguration_SystemScale</objectId>

€<resourceType>LabelValueConfiguration</resourceType>

€<displayName>System Scale</displayName>

€<systemResourceFlag>true</systemResourceFlag>

€<createUser>system</createUser>

€<lastUpdatedBy>system</lastUpdatedBy>

€<revision>0</revision>

€<shared>true</shared>

€<categoryId>system_scale_overview</categoryId>

€<categoryDisplayName>System Scale</categoryDisplayName>

€<refreshInterval>0</refreshInterval>

€<weight>9100</weight>

€<datasources>

€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.DatasourceDto>

NSX API Guide Version: 6.4 Page 259

€€€€€€€€€<urls>

€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.UrlAliasDto>

€€€€€€€€€€€€€€€€€<alias>systemScale</alias>

€€€€€€€€€€€€€€€€€<url>/api/2.0/capacity-parameters/report</url>

€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.UrlAliasDto>

€€€€€€€€€</urls>

€€€€€€€€€<displayName>default</displayName>

€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.DatasourceDto>

€</datasources>

€<properties>

€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.PropertyItemDto>

€€€€€€€€€<field>0</field>

€€€€€€€€€<renderConfiguration>

€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€€€€€€€€€<displayValue>#{default.systemScale.scaleSummary.parametersAboveSupportedValue}</displayVal

ue>

€€€€€€€€€€€€€€€€€<condition>#{default.systemScale.scaleSummary.parametersAboveSupportedValue} !=

0</condition>

€€€€€€€€€€€€€€€€€<icons>

€€€€€€€€€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.IconDto>

€€€€€€€€€€€€€€€€€€€€€€€€€<type>ERROR</type>

€€€€€€€€€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.IconDto>

€€€€€€€€€€€€€€€€€</icons>

€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€</renderConfiguration>

€€€€€€€€€<label>

€€€€€€€€€€€€€<text>Alerts</text>

€€€€€€€€€</label>

€€€€€€€€€<type>Number</type>

€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.PropertyItemDto>

€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.PropertyItemDto>

€€€€€€€€€<field>0</field>

€€€€€€€€€<renderConfiguration>

€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€€€€€€€€€<displayValue>#{default.systemScale.scaleSummary.parametersAboveThreshold}</displayValue>

€€€€€€€€€€€€€€€€€<condition>#{default.systemScale.scaleSummary.parametersAboveThreshold} != 0</condition>

€€€€€€€€€€€€€€€€€<icons>

€€€€€€€€€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.IconDto>

€€€€€€€€€€€€€€€€€€€€€€€€€<type>WARNING</type>

€€€€€€€€€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.IconDto>

€€€€€€€€€€€€€€€€€</icons>

€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€</renderConfiguration>

€€€€€€€€€<label>

€€€€€€€€€€€€€<text>Warnings</text>

€€€€€€€€€</label>

€€€€€€€€€<type>Number</type>

€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.PropertyItemDto>

€</properties>

</com.vmware.vshield.vsm.dashboard.dto.custom.LabelValueConfigurationDto>

Working With a Specific Widget

GET /api/2.0/services/dashboard/ui-views/dashboard/widgetconfigurations/{widget

configurationId}

URI Parameters:

NSX API Guide Version: 6.4 Page 260

widgetconfigurationId€€(required) ID for a specific widget on the dashboard.

Description:

Retrieves the configuration details about a specific widget on the dashboard.

Method history:

Release Modification

6.4.0 Method introduced.

Responses:

Status Code: 200

Body: application/xml

<com.vmware.vshield.vsm.dashboard.dto.custom.LabelValueConfigurationDto>

€<objectId>LabelValueConfiguration_ShortLivedSettings</objectId>

€<resourceType>LabelValueConfiguration</resourceType>

€<displayName>Tools</displayName>

€<systemResourceFlag>true</systemResourceFlag>

€<createUser>system</createUser>

€<lastUpdatedBy>system</lastUpdatedBy>

€<revision>0</revision>

€<shared>true</shared>

€<categoryId>short_lived_settings</categoryId>

€<categoryDisplayName>Tools</categoryDisplayName>

€<refreshInterval>0</refreshInterval>

€<weight>9200</weight>

€<datasources>

€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.DatasourceDto>

€€€€€€€€€<urls>

€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.UrlAliasDto>

€€€€€€€€€€€€€€€€€<alias>flowMonStatus</alias>

€€€€€€€€€€€€€€€€€<url>api/2.1/app/flow/config</url>

€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.UrlAliasDto>

€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.UrlAliasDto>

€€€€€€€€€€€€€€€€€<alias>appMonStatus</alias>

€€€€€€€€€€€€€€€€€<url>api/internal/appmon/currentsession</url>

€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.UrlAliasDto>

€€€€€€€€€</urls>

€€€€€€€€€<displayName>default</displayName>

€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.DatasourceDto>

€</datasources>

€<properties>

€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.PropertyItemDto>

€€€€€€€€€<field>#{default.flowMonStatus.collectFlows}</field>

€€€€€€€€€<renderConfiguration>

€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€€€€€€€€€<displayValue>"On"</displayValue>

€€€€€€€€€€€€€€€€€<condition>#{default.flowMonStatus.collectFlows} == true</condition>

€€€€€€€€€€€€€€€€€<icons>

€€€€€€€€€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.IconDto>

€€€€€€€€€€€€€€€€€€€€€€€€€<type>WARNING</type>

€€€€€€€€€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.IconDto>

€€€€€€€€€€€€€€€€€</icons>

€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€€€€€€€€€<displayValue>"Off"</displayValue>

€€€€€€€€€€€€€€€€€<condition>#{default.flowMonStatus.collectFlows} == false</condition>

NSX API Guide Version: 6.4 Page 261

€€€€€€€€€€€€€€€€€<icons></icons>

€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€</renderConfiguration>

€€€€€€€€€<label>

€€€€€€€€€€€€€<text>Flow Monitoring</text>

€€€€€€€€€</label>

€€€€€€€€€<type>String</type>

€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.PropertyItemDto>

€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.PropertyItemDto>

€€€€€€€€€<field>#{default.appMonStatus.startTime}</field>

€€€€€€€€€<renderConfiguration>

€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€€€€€€€€€<displayValue>"On"</displayValue>

€€€€€€€€€€€€€€€€€<condition>#{default.appMonStatus.startTime} != 0</condition>

€€€€€€€€€€€€€€€€€<icons>

€€€€€€€€€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.IconDto>

€€€€€€€€€€€€€€€€€€€€€€€€€<type>WARNING</type>

€€€€€€€€€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.IconDto>

€€€€€€€€€€€€€€€€€</icons>

€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€€€€€<com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€€€€€€€€€<displayValue>"Off"</displayValue>

€€€€€€€€€€€€€€€€€<condition>#{default.appMonStatus.startTime} == 0</condition>

€€€€€€€€€€€€€€€€€<icons></icons>

€€€€€€€€€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.RenderConfigurationDto>

€€€€€€€€€</renderConfiguration>

€€€€€€€€€<label>

€€€€€€€€€€€€€<text>Endpoint Monitoring</text>

€€€€€€€€€</label>

€€€€€€€€€<type>String</type>

€€€€€</com.vmware.vshield.vsm.dashboard.dto.custom.PropertyItemDto>

€</properties>

</com.vmware.vshield.vsm.dashboard.dto.custom.LabelValueConfigurationDto>

PUT /api/2.0/services/dashboard/ui-views/dashboard/widgetconfigurations/{widget

configurationId}

URI Parameters:

widgetconfigurationId€€(required) ID for a specific widget on the dashboard.

Description:

Updates the configuration about a specific widget on the dashboard. For example, LabelValueConfiguration, PUT

https://<nsx-mgr>/api/2.0/services/dashboard/ui-views/dashboard/widgetconfigurations/

LabelValueConfiguration_497802b7-e0d9-48b3-abfd-479058540956.

Method history:

Release Modification

6.4.0 Method introduced.

DELETE /api/2.0/services/dashboard/ui-views/dashboard/widgetconfigurations/{wid

getconfigurationId}

URI Parameters:

widgetconfigurationId€€(required) ID for a specific widget on the dashboard.

NSX API Guide Version: 6.4 Page 262

Description:

Deletes a specific widget on the dashboard.

NSX API Guide Version: 6.4 Page 263

Working With the Task Framework

Working with filtering criteria and paging information for jobs on the task framework.

GET /api/2.0/services/taskservice/job

Query Parameters:

startIndex€€(optional) The starting point for returning results.

pageSize€€(optional) The number of results to return.

sortBy€€(optional) Always sorted by "startTime"

sortOrderAscending€€(optional) Sort in ascending order of start time (true/false)

Description:

Query job instances by criterion.

Working With a Specific Job Instance

GET /api/2.0/services/taskservice/job/{jobId}

URI Parameters:

jobId€€(required) Specified job ID.

Description:

Retrieve all job instances for the specified job ID.

NSX API Guide Version: 6.4 Page 264

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.

To register a third-party solution with Guest Introspection, clients can use four REST calls to do the following:

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.

POST /api/2.0/endpointsecurity/registration

NSX API Guide Version: 6.4 Page 265

Description:

Name Comments

vendorId VMware-assigned ID for the vendor.

vendorTitle Vendor-specified title.

vendorDescription Vendor-specified description.

Request:

Body: application/xml

€<id>vendorId</id>

€<title>vendorTitle</title>

€<description>vendorDescription</description>

</VendorInfo>

Working With Registered Guest Introspection Vendors

GET /api/2.0/endpointsecurity/registration/vendors

Description:

Retrieve the list of all registered Guest Introspection vendors.

Working With Guest Introspection Vendors and Endpoint Protection Solutions

GET /api/2.0/endpointsecurity/registration/{vendorID}

URI Parameters:

vendorID€€(required) VMware-assigned ID for the vendor.

Description:

Retrieve registration information for a Guest Introspection vendor.

POST /api/2.0/endpointsecurity/registration/{vendorID}

URI Parameters:

vendorID€€(required) VMware-assigned ID for the vendor.

Description:

NSX API Guide Version: 6.4 Page 266

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.

Request:

Body: application/xml

€<altitude>solutionAltitude</altitude>

€<title>solutionTitle</title>

€<description>solutionDescription</description>

</SolutionInfo>

DELETE /api/2.0/endpointsecurity/registration/{vendorID}

URI Parameters:

vendorID€€(required) VMware-assigned ID for the vendor.

Description:

Unregister a Guest Introspection vendor.

Information About Registered Endpoint Protection Solutions

GET /api/2.0/endpointsecurity/registration/{vendorID}/solutions

URI Parameters:

vendorID€€(required) VMware-assigned ID for the vendor.

Description:

Get registration information for all endpoint protection solutions for a Guest Introspection vendor.

Endpoint Protection Solution Registration Information

GET /api/2.0/endpointsecurity/registration/{vendorID}/{altitude}

URI Parameters:

NSX API Guide Version: 6.4 Page 267

altitude€€(required) VMware-assigned number that uniquely identifies a

solution. Describes the type of solution and the order in

which the solution receives events relative to other

solutions on the same host.

vendorID€€(required) VMware-assigned ID for the vendor.

Description:

Get registration information for an endpoint protection solution.

DELETE /api/2.0/endpointsecurity/registration/{vendorID}/{altitude}

URI Parameters:

altitude€€(required) VMware-assigned number that uniquely identifies a

solution. Describes the type of solution and the order in

which the solution receives events relative to other

solutions on the same host.

vendorID€€(required) VMware-assigned ID for the vendor.

Description:

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.

GET /api/2.0/endpointsecurity/registration/{vendorID}/{altitude}/location

URI Parameters:

altitude€€(required) VMware-assigned number that uniquely identifies a

solution. Describes the type of solution and the order in

which the solution receives events relative to other

solutions on the same host.

vendorID€€(required) VMware-assigned ID for the vendor.

Description:

Get the IP address and port on the vNIC host for an endpoint protection solution.

POST /api/2.0/endpointsecurity/registration/{vendorID}/{altitude}/location

URI Parameters:

altitude€€(required) VMware-assigned number that uniquely identifies a

solution. Describes the type of solution and the order in

which the solution receives events relative to other

solutions on the same host.

vendorID€€(required) VMware-assigned ID for the vendor.

NSX API Guide Version: 6.4 Page 268

Description:

Set the IP address and port on the vNIC host for an endpoint protection solution.

Request:

Body: application/xml

€<ip>solutionIpAddress</ip>

€<port>solutionIPPort</port>

</LocationInfo>

DELETE /api/2.0/endpointsecurity/registration/{vendorID}/{altitude}/location

URI Parameters:

altitude€€(required) VMware-assigned number that uniquely identifies a

solution. Describes the type of solution and the order in

which the solution receives events relative to other

solutions on the same host.

vendorID€€(required) VMware-assigned ID for the vendor.

Description:

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.

GET /api/2.0/endpointsecurity/activation

Query Parameters:

hostId€€(required) Host ID associated with activated security VMs.

Description:

Retrieve activation information for all activated security VMs on the specified host.

Responses:

Status Code: 200

Body: application/xml

€<ActivationInfo>

€€€<moid>vm-819</moid>

€€€<hostMoid>host-9</hostMoid>

€€€<vmName>VMWARE-Solution-Name-XXX.XXX.XXX.XXX</vmName>

€€€<hostName>10.24.130.174</hostName>

NSX API Guide Version: 6.4 Page 269

€€€<clusterName>Dev</clusterName>

€€€<dcName>dev</dcName>

€€€<vendorId>VMWARE</vendorId>

€€€<solutionId>6341068275337723904</solutionId>

€</ActivationInfo>

€***

</ActivatedSVMs>

Activated Security Virtual Machines

GET /api/2.0/endpointsecurity/activation/{vendorID}/{solutionID}

URI Parameters:

vendorID€€(required) VMware-assigned ID for the vendor.

solutionID€€(required) solution ID for the endpoint protection solution.

Description:

Retrieve a list of activated security VMs for an endpoint protection solution.

Responses:

Status Code: 200

Body: application/xml

€<ActivationInfo>

€€€<moid>vm-819</moid>

€€€<hostMoid>host-9</hostMoid>

€€€<vmName>VMWARE-Solution-Name-XXX.XXX.XXX.XXX</vmName>

€€€<hostName>10.24.130.174</hostName>

€€€<clusterName>Dev</clusterName>

€€€<dcName>dev</dcName>

€€€<vendorId>VMWARE</vendorId>

€€€<solutionId>6341068275337723904</solutionId>

€</ActivationInfo>

€***

</ActivatedSVMs>

Activate a Registered Endpoint Protection Solution

POST /api/2.0/endpointsecurity/activation/{vendorID}/{altitude}

URI Parameters:

vendorID€€(required) VMware-assigned ID for the vendor.

NSX API Guide Version: 6.4 Page 270

altitude€€ VMware-assigned number to uniquely identify a solution.

Describes the type of solution and the order in which the

solution receives events relative to other solutions on the

same host.

Description:

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.

Request:

Body: application/xml

€<moid>svmMoid</moid>

</ActivationInfo>

Working With Solution Activation Status

GET /api/2.0/endpointsecurity/activation/{vendorID}/{altitude}/{moid}

URI Parameters:

moid€€(required) Managed object reference of a VM.

vendorID€€(required) VMware-assigned ID for the vendor.

altitude€€ VMware-assigned number to uniquely identify a solution.

Describes the type of solution and the order in which the

solution receives events relative to other solutions on the

same host.

Description:

Retrieve the endpoint protection solution activation status, either true (activated) or false (not activated).

DELETE /api/2.0/endpointsecurity/activation/{vendorID}/{altitude}/{moid}

URI Parameters:

moid€€(required) Managed object reference of a VM.

vendorID€€(required) VMware-assigned ID for the vendor.

altitude€€ VMware-assigned number to uniquely identify a solution.

Describes the type of solution and the order in which the

solution receives events relative to other solutions on the

same host.

Description:

NSX API Guide Version: 6.4 Page 271

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.

GET /api/2.0/endpointsecurity/usvmstats/usvmhealththresholds

Description:

Retrieve Guest Introspection service VM CPU and memory usage thresholds.

Method history:

Release Modification

6.3.5 Method introduced.

Responses:

Status Code: 200

Success

Body: application/xml

€<memThreshold>75</memThreshold>

€<cpuThreshold>75</cpuThreshold>

</UsvmHealthStats>

PUT /api/2.0/endpointsecurity/usvmstats/usvmhealththresholds

Description:

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.

Request:

Body: application/xml

€<memThreshold>70</memThreshold>

€<cpuThreshold>70</cpuThreshold>

</UsvmHealthStats>

NSX API Guide Version: 6.4 Page 272

Responses:

Status Code: 200

Success

Status Code: 400

Bad Request

NSX API Guide Version: 6.4 Page 273

Working With Distributed Firewall

Default Firewall Configuration

GET /api/4.0/firewall/globalroot-0/defaultconfig

Description:

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.

Working with Distributed Firewall 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

NSX API Guide Version: 6.4 Page 274

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

Starting in NSX 6.4.0, the following attributes can be configured at the section level.

Attribute Description Default for new sections

tcpStrict

If TCP strict is enabled on a rule and

a packet matches that rule, the

following check will be performed. If

the packet does not belong to an

existing session, the kernel will

check to see if the SYN flag of the

packet is set. If it is not, then it will

drop the packet. false for all section types.

stateless

If stateless is enabled on a rule,

traffic is monitored statically, and the

state of network connections will be

ignored.

true for L2, false for L3 and L3

redirect.

useSid

If useSid is enabled on a rule, the

source field of the rule must be an

Active Directory Security Group. false for all section types.

tcpStrict was previously configured in the global firewall configuration: PUT

/api/4.0/firewall/config/globalconfiguration. If you upgrade to NSX 6.4.0 or later, the global

configuration setting for tcpStrict is used to configure tcpStrict in each existing layer 3 section. tcpStrict is set to false

in layer 2 sections and layer 3 redirect sections. stateless and useSid are new attributes in NSX 6.4.0 and are set to

the default values during upgrade.

Once all hosts are upgraded to NSX 6.4.0, the global tcpStrict parameter is ignored.

GET /api/4.0/firewall/globalroot-0/config

Query Parameters:

ruleType€€(optional) ruleType can be LAYER3, LAYER2, L3REDIRECT. ruleType is

mandatory if other query parameters are sent. Note: Filtering is not

supported for layer 2 rules, so specifying LAYER2 will return all rule

types.

source€€(optional) source can contain IPv4/v6 address or vm-id.

destination€€(optional) destination can contain IPv4/v6 address or vm-id.

ruleId€€(optional) filter by ruleId

comment€€(optional) comment can contain any portion of the comment entered for the rules.

Search is case insensitive.

name€€(optional) name can contain any portion of the rule name entered for the rules.

Search is case insensitive.

NSX API Guide Version: 6.4 Page 275

siProfile€€(optional) siProfile can contain any portion of the service profile name associated

with L3 redirect rule. Search is case insensitive.

edgeId€€(optional) Filter for rules applicable to the Edge specified by edgeId.

action€€(optional) Filter for specific action (allow, deny).

sectionName€€(optional) Filter firewall configuration based on section name. Example

config?ruleType=LAYER3&sectionName=Test&action=Deny

Description:

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.

Method history:

Release Modification

6.4.0

Method updated. tcpStrict, stateless, and useSid

added as section attributes.

Responses:

Status Code: 200

Body: application/xml

€<contextId>globalroot-0</contextId>

€<layer3Sections>

€€€<section generationNumber="1510700045886" id="2" name="defaultSectionLayer3" stateless="false"

tcpStrict="true" timestamp="1510700045886" type="LAYER3" useSid="false">

€€€€€<rule disabled="false" id="2" logged="false">

€€€€€€€<name>Default Rule</name>

€€€€€€€<action>DENY</action>

€€€€€€€<appliedToList>

€€€€€€€€€<appliedTo>

€€€€€€€€€€€<name>DISTRIBUTED_FIREWALL</name>

€€€€€€€€€€€<value>DISTRIBUTED_FIREWALL</value>

€€€€€€€€€€€<type>DISTRIBUTED_FIREWALL</type>

€€€€€€€€€€€<isValid>true</isValid>

€€€€€€€€€</appliedTo>

€€€€€€€</appliedToList>

€€€€€€€<sectionId>2</sectionId>

€€€€€</rule>

€€€</section>

€</layer3Sections>

€<layer2Sections>

€€€<section generationNumber="1510700045886" id="1" name="defaultSectionLayer2" stateless="false"

tcpStrict="true" timestamp="1510700045886" type="LAYER2" useSid="false">

€€€€€<rule disabled="false" id="1" logged="false">

€€€€€€€<name>Default Rule</name>

€€€€€€€<action>ALLOW</action>

€€€€€€€<appliedToList>

€€€€€€€€€<appliedTo>

€€€€€€€€€€€<name>DISTRIBUTED_FIREWALL</name>

€€€€€€€€€€€<value>DISTRIBUTED_FIREWALL</value>

€€€€€€€€€€€<type>DISTRIBUTED_FIREWALL</type>

€€€€€€€€€€€<isValid>true</isValid>

€€€€€€€€€</appliedTo>

€€€€€€€</appliedToList>

NSX API Guide Version: 6.4 Page 276

€€€€€€€<sectionId>1</sectionId>

€€€€€</rule>

€€€</section>

€</layer2Sections>

</firewallConfiguration>

PUT /api/4.0/firewall/globalroot-0/config

Headers:

If-Match€€(required) The Etag value from the response headers from a GET

of the firewall configuration you want to modify.

Description:

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.

• Starting in NSX 6.4.5, the Etag value returned in the response header of GET /api/4.0/firewall/globalroot-0/config

contains double quotes. You must strip off the double quotes before using the Etag value in the If-Match header. If

you are using the PUT API request in an automation script, ensure that the script strips off the double quotes in the

Etag value.

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.

Method history:

Release Modification

6.4.0

Method updated. tcpStrict, stateless, and useSid

added as section attributes.

Request:

Body: application/xml

€<contextId>globalroot-0</contextId>

€<layer3Sections>

€€€<section generationNumber="1510700045886" id="2" name="defaultSectionLayer3" stateless="false"

tcpStrict="true" timestamp="1510700045886" type="LAYER3" useSid="false">

€€€€€<rule disabled="false" logged="true">

€€€€€€€<name>okn-1</name>

€€€€€€€<action>ALLOW</action>

NSX API Guide Version: 6.4 Page 277

€€€€€€€<sources excluded="false">

€€€€€€€€€<source>

€€€€€€€€€€€<value>datacenter-57</value>

€€€€€€€€€€€<type>Datacenter</type>

€€€€€€€€€</source>

€€€€€€€€€<source>

€€€€€€€€€€€<value>domain-c62</value>

€€€€€€€€€€€<type>ClusterComputeResource</type>

€€€€€€€€€</source>

€€€€€€€€€<source>

€€€€€€€€€€€<value>10.112.1.1</value>

€€€€€€€€€€€<type>Ipv4Address</type>

€€€€€€€€€</source>

€€€€€€€</sources>

€€€€€€€<services>

€€€€€€€€€<service>

€€€€€€€€€€€<destinationPort>80</destinationPort>

€€€€€€€€€€€<protocol>6</protocol>

€€€€€€€€€€€<subProtocol>6</subProtocol>

€€€€€€€€€</service>

€€€€€€€€€<service>

€€€€€€€€€€€<value>application-161</value>

€€€€€€€€€€€<type>Application</type>

€€€€€€€€€</service>

€€€€€€€</services>

€€€€€€€<appliedToList>

€€€€€€€€€<appliedTo>

€€€€€€€€€€€<value>5013bcd8-c666-1e28-c7a9-600da945954f.000</value>

€€€€€€€€€€€<type>Vnic</type>

€€€€€€€€€</appliedTo>

€€€€€€€€€<appliedTo>

€€€€€€€€€€€<value>vm-126</value>

€€€€€€€€€€€<type>VirtualMachine</type>

€€€€€€€€€</appliedTo>

€€€€€€€</appliedToList>

€€€€€</rule>

€€€€€<rule disabled="true" logged="true">

€€€€€€€<name>Matru-1</name>

€€€€€€€<action>ALLOW</action>

€€€€€€€<sectionId>2</sectionId>

€€€€€</rule>

€€€€€<rule disabled="true" logged="true">

€€€€€€€<name>Matru-2</name>

€€€€€€€<action>ALLOW</action>

€€€€€€€<sectionId>2</sectionId>

€€€€€</rule>

€€€€€<rule disabled="true" logged="true">

€€€€€€€<name>Matru-3</name>

€€€€€€€<action>ALLOW</action>

€€€€€€€<sectionId>2</sectionId>

€€€€€</rule>

€€€€€<rule disabled="true" id="2" logged="false">

€€€€€€€<name>Default Rule</name>

€€€€€€€<action>DENY</action>

€€€€€€€<sectionId>2</sectionId>

€€€€€</rule>

€€€</section>

€</layer3Sections>

€<layer2Sections>

€€€<section generationNumber="1510700045886" id="1" name="defaultSectionLayer2" stateless="false"

tcpStrict="true" timestamp="1510700045886" type="LAYER2" useSid="false">

€€€€€<rule disabled="false" id="1" logged="false">

NSX API Guide Version: 6.4 Page 278

€€€€€€€<name>Default Rule</name>

€€€€€€€<action>ALLOW</action>

€€€€€€€<sectionId>1</sectionId>

€€€€€</rule>

€€€</section>

€</layer2Sections>

</firewallConfiguration>

DELETE /api/4.0/firewall/globalroot-0/config

Description:

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.

GET /api/4.0/firewall/globalroot-0/config/layer3sections

Query Parameters:

name€€(required) Name of the section to retrieve.

Description:

Retrieve rules from the layer 3 section specified by section name.

Method history:

Release Modification

6.4.0

Method updated. tcpStrict, stateless, and useSid

added as section attributes.

Responses:

Status Code: 200

Body: application/xml

€<section generationNumber="1510700045886" id="4" name="TestSection" stateless="false" tcpStrict="true"

timestamp="1510700045886" type="LAYER3" useSid="false">

€€€<rule disabled="false" id="16" logged="true">

€€€€€<name>okn-2</name>

€€€€€<action>ALLOW</action>

€€€€€<appliedToList>

€€€€€€€<appliedTo>

NSX API Guide Version: 6.4 Page 279

€€€€€€€€€<name>vm1 - Network adapter 1</name>

€€€€€€€€€<value>5013bcd8-c666-1e28-c7a9-600da945954f.000</value>

€€€€€€€€€<type>Vnic</type>

€€€€€€€€€<isValid>true</isValid>

€€€€€€€</appliedTo>

€€€€€€€<appliedTo>

€€€€€€€€€<name>Small XP-2</name>

€€€€€€€€€<value>vm-126</value>

€€€€€€€€€<type>VirtualMachine</type>

€€€€€€€€€<isValid>true</isValid>

€€€€€€€</appliedTo>

€€€€€</appliedToList>

€€€€€<sectionId>4</sectionId>

€€€€€<sources excluded="false">

€€€€€€€<source>

€€€€€€€€€<name>Site B Datacenter</name>

€€€€€€€€€<value>datacenter-57</value>

€€€€€€€€€<type>Datacenter</type>

€€€€€€€€€<isValid>true</isValid>

€€€€€€€</source>

€€€€€€€<source>

€€€€€€€€€<name>Computer Cluster 6</name>

€€€€€€€€€<value>domain-c62</value>

€€€€€€€€€<type>ClusterComputeResource</type>

€€€€€€€€€<isValid>true</isValid>

€€€€€€€</source>

€€€€€€€<source>

€€€€€€€€€<value>10.112.1.1</value>

€€€€€€€€€<type>Ipv4Address</type>

€€€€€€€€€<isValid>true</isValid>

€€€€€€€</source>

€€€€€</sources>

€€€€€<services>

€€€€€€€<service>

€€€€€€€€€<destinationPort>80</destinationPort>

€€€€€€€€€<protocol>6</protocol>

€€€€€€€€€<subProtocol>6</subProtocol>

€€€€€€€</service>

€€€€€€€<service>

€€€€€€€€€<name>VMware-VDM2.x-Ephemeral</name>

€€€€€€€€€<value>application-161</value>

€€€€€€€€€<isValid>true</isValid>

€€€€€€€</service>

€€€€€</services>

€€€€€<appliedToList>

€€€€€€€<appliedTo>

€€€€€€€€€<name>DISTRIBUTED_FIREWALL</name>

€€€€€€€€€<value>DISTRIBUTED_FIREWALL</value>

€€€€€€€€€<type>DISTRIBUTED_FIREWALL</type>

€€€€€€€€€<isValid>true</isValid>

€€€€€€€</appliedTo>

€€€€€</appliedToList>

€€€</rule>

€€€<rule disabled="true" id="15" logged="true">

€€€€€<name>Matru-3</name>

€€€€€<action>ALLOW</action>

€€€€€<appliedToList>

€€€€€€€<appliedTo>

€€€€€€€€€<name>DISTRIBUTED_FIREWALL</name>

€€€€€€€€€<value>DISTRIBUTED_FIREWALL</value>

€€€€€€€€€<type>DISTRIBUTED_FIREWALL</type>

€€€€€€€€€<isValid>true</isValid>

NSX API Guide Version: 6.4 Page 280

€€€€€€€</appliedTo>

€€€€€</appliedToList>

€€€€€<sectionId>4</sectionId>

€€€</rule>

€€€<rule disabled="true" id="14" logged="true">

€€€€€<name>test-3</name>

€€€€€<action>ALLOW</action>

€€€€€<appliedToList>

€€€€€€€<appliedTo>

€€€€€€€€€<name>DISTRIBUTED_FIREWALL</name>

€€€€€€€€€<value>DISTRIBUTED_FIREWALL</value>

€€€€€€€€€<type>DISTRIBUTED_FIREWALL</type>

€€€€€€€€€<isValid>true</isValid>

€€€€€€€</appliedTo>

€€€€€</appliedToList>

€€€€€<sectionId>4</sectionId>

€€€</rule>

€€€<rule disabled="true" id="13" logged="true">

€€€€€<name>test-2</name>

€€€€€<action>ALLOW</action>

€€€€€<appliedToList>

€€€€€€€<appliedTo>

€€€€€€€€€<name>DISTRIBUTED_FIREWALL</name>

€€€€€€€€€<value>DISTRIBUTED_FIREWALL</value>

€€€€€€€€€<type>DISTRIBUTED_FIREWALL</type>

€€€€€€€€€<isValid>true</isValid>

€€€€€€€</appliedTo>

€€€€€</appliedToList>

€€€€€<sectionId>4</sectionId>

€€€</rule>

€€€<rule disabled="true" id="12" logged="false">

€€€€€<name>test-1</name>

€€€€€<action>DENY</action>

€€€€€<appliedToList>

€€€€€€€<appliedTo>

€€€€€€€€€<name>DISTRIBUTED_FIREWALL</name>

€€€€€€€€€<value>DISTRIBUTED_FIREWALL</value>

€€€€€€€€€<type>DISTRIBUTED_FIREWALL</type>

€€€€€€€€€<isValid>true</isValid>

€€€€€€€</appliedTo>

€€€€€</appliedToList>

€€€€€<sectionId>4</sectionId>

€€€</rule>

€</section>

</sections>

POST /api/4.0/firewall/globalroot-0/config/layer3sections

Query Parameters:

operation€€(optional) operation can be insert_after, insert_before, insert_top,

or insert_before_default.

anchorId€€(optional) Specify the section ID to use for reference with

insert_before or insert_after operations.

Description:

Create a layer 3 distributed firewall section.

NSX API Guide Version: 6.4 Page 281

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.

See "Working with Distributed Firewall Configuration" for information about configuring tcpStrict, stateless, and

useSid for a section.

Method history:

Release Modification

6.4.0

Method updated. tcpStrict, stateless, and useSid

added as section attributes.

Request:

Body: application/xml

€<rule disabled="false" logged="true">

€€€<name>okn-2</name>

€€€<action>ALLOW</action>

€€€<appliedToList>

€€€€€<appliedTo>

€€€€€€€<name>vm1 - Network adapter 1</name>

€€€€€€€<value>5013bcd8-c666-1e28-c7a9-600da945954f.000</value>

€€€€€€€<type>Vnic</type>

€€€€€€€<isValid>true</isValid>

€€€€€</appliedTo>

€€€€€<appliedTo>

€€€€€€€<name>Small XP-2</name>

€€€€€€€<value>vm-126</value>

€€€€€€€<type>VirtualMachine</type>

€€€€€€€<isValid>true</isValid>

€€€€€</appliedTo>

€€€</appliedToList>

€€€<sources excluded="false">

€€€€€<source>

€€€€€€€<name>Site B Datacenter</name>

€€€€€€€<value>datacenter-57</value>

€€€€€€€<type>Datacenter</type>

€€€€€€€<isValid>true</isValid>

€€€€€</source>

€€€€€<source>

€€€€€€€<name>Compute Cluster 6</name>

€€€€€€€<value>domain-c62</value>

€€€€€€€<type>ClusterComputeResource</type>

€€€€€€€<isValid>true</isValid>

€€€€€</source>

€€€€€<source>

€€€€€€€<value>10.112.1.1</value>

€€€€€€€<type>Ipv4Address</type>

€€€€€€€<isValid>true</isValid>

€€€€€</source>

€€€</sources>

€€€<services>

€€€€€<service>

€€€€€€€<destinationPort>80</destinationPort>

€€€€€€€<protocol>6</protocol>

€€€€€€€<subProtocol>6</subProtocol>

€€€€€</service>

€€€€€<service>

NSX API Guide Version: 6.4 Page 282

€€€€€€€<name>VMware-VDM2.x-Ephemeral</name>

€€€€€€€<value>application-161</value>

€€€€€€€<isValid>true</isValid>

€€€€€</service>

€€€</services>

€</rule>

€<rule disabled="true" logged="true">

€€€<name>Matru-3</name>

€€€<action>ALLOW</action>

€</rule>

€<rule disabled="true" logged="true">

€€€<name>test-3</name>

€€€<action>ALLOW</action>

€</rule>

€<rule disabled="true" logged="true">

€€€<name>test-2</name>

€€€<action>ALLOW</action>

€</rule>

€<rule disabled="true" logged="false">

€€€<name>test-1</name>

€€€<action>DENY</action>

€</rule>

</section>

Working With a Specific Layer 3 Distributed Firewall Section

GET /api/4.0/firewall/globalroot-0/config/layer3sections/{sectionId}

URI Parameters:

sectionId€€(required) The ID of the section to modify.

Description:

Retrieve information about the specified layer 3 section.

Method history:

Release Modification

6.4.0

Method updated. tcpStrict, stateless, and useSid

added as section attributes.

Responses:

Status Code: 200

Body: application/xml

<section generationNumber="1510700045886" id="4" name="TestSection" stateless="false" tcpStrict="true"

timestamp="1510700045886" type="LAYER3" useSid="false">

€<rule disabled="false" id="16" logged="true">

€€€<name>okn-2</name>

€€€<action>ALLOW</action>

€€€<appliedToList>

€€€€€<appliedTo>

€€€€€€€<name>vm1 - Network adapter 1</name>

NSX API Guide Version: 6.4 Page 283

€€€€€€€<value>5013bcd8-c666-1e28-c7a9-600da945954f.000</value>

€€€€€€€<type>Vnic</type>

€€€€€€€<isValid>true</isValid>

€€€€€</appliedTo>

€€€€€<appliedTo>

€€€€€€€<name>Small XP-2</name>

€€€€€€€<value>vm-126</value>

€€€€€€€<type>VirtualMachine</type>

€€€€€€€<isValid>true</isValid>

€€€€€</appliedTo>

€€€</appliedToList>

€€€<sectionId>4</sectionId>

€€€<sources excluded="false">

€€€€€<source>

€€€€€€€<name>Site B Datacenter</name>

€€€€€€€<value>datacenter-57</value>

€€€€€€€<type>Datacenter</type>

€€€€€€€<isValid>true</isValid>

€€€€€</source>

€€€€€<source>

€€€€€€€<name>Compute Cluster 6</name>

€€€€€€€<value>domain-c62</value>

€€€€€€€<type>ClusterComputeResource</type>

€€€€€€€<isValid>true</isValid>

€€€€€</source>

€€€€€<source>

€€€€€€€<value>10.112.1.1</value>

€€€€€€€<type>Ipv4Address</type>

€€€€€€€<isValid>true</isValid>

€€€€€</source>

€€€</sources>

€€€<services>

€€€€€<service>

€€€€€€€<destinationPort>80</destinationPort>

€€€€€€€<protocol>6</protocol>

€€€€€€€<subProtocol>6</subProtocol>

€€€€€</service>

€€€€€<service>

€€€€€€€<name>VMware-VDM2.x-Ephemeral</name>

€€€€€€€<value>application-161</value>

€€€€€€€<isValid>true</isValid>

€€€€€</service>

€€€</services>

€€€<appliedToList>

€€€€€<appliedTo>

€€€€€€€<name>DISTRIBUTED_FIREWALL</name>

€€€€€€€<value>DISTRIBUTED_FIREWALL</value>

€€€€€€€<type>DISTRIBUTED_FIREWALL</type>

€€€€€€€<isValid>true</isValid>

€€€€€</appliedTo>

€€€</appliedToList>

€</rule>

€<rule disabled="true" id="15" logged="true">

€€€<name>Matru-3</name>

€€€<action>ALLOW</action>

€€€<appliedToList>

€€€€€<appliedTo>

€€€€€€€<name>DISTRIBUTED_FIREWALL</name>

€€€€€€€<value>DISTRIBUTED_FIREWALL</value>

€€€€€€€<type>DISTRIBUTED_FIREWALL</type>

€€€€€€€<isValid>true</isValid>

€€€€€</appliedTo>

NSX API Guide Version: 6.4 Page 284

€€€</appliedToList>

€€€<sectionId>4</sectionId>

€</rule>

€<rule disabled="true" id="14" logged="true">

€€€<name>test-3</name>

€€€<action>ALLOW</action>

€€€<appliedToList>

€€€€€<appliedTo>

€€€€€€€<name>DISTRIBUTED_FIREWALL</name>

€€€€€€€<value>DISTRIBUTED_FIREWALL</value>

€€€€€€€<type>DISTRIBUTED_FIREWALL</type>

€€€€€€€<isValid>true</isValid>

€€€€€</appliedTo>

€€€</appliedToList>

€€€<sectionId>4</sectionId>

€</rule>

€<rule disabled="true" id="13" logged="true">

€€€<name>test-2</name>

€€€<action>ALLOW</action>

€€€<appliedToList>

€€€€€<appliedTo>

€€€€€€€<name>DISTRIBUTED_FIREWALL</name>

€€€€€€€<value>DISTRIBUTED_FIREWALL</value>

€€€€€€€<type>DISTRIBUTED_FIREWALL</type>

€€€€€€€<isValid>true</isValid>

€€€€€</appliedTo>

€€€</appliedToList>

€€€<sectionId>4</sectionId>

€</rule>

€<rule disabled="true" id="12" logged="false">

€€€<name>test-1</name>

€€€<action>DENY</action>

€€€<appliedToList>

€€€€€<appliedTo>

€€€€€€€<name>DISTRIBUTED_FIREWALL</name>

€€€€€€€<value>DISTRIBUTED_FIREWALL</value>

€€€€€€€<type>DISTRIBUTED_FIREWALL</type>

€€€€€€€<isValid>true</isValid>

€€€€€</appliedTo>

€€€</appliedToList>

€€€<sectionId>4</sectionId>

€</rule>

</section>

PUT /api/4.0/firewall/globalroot-0/config/layer3sections/{sectionId}

URI Parameters:

sectionId€€(required) The ID of the section to modify.

Headers:

If-Match€€(required) The Etag value from the response headers from a GET

of the firewall configuration you want to modify.

Description:

Update the specified layer 3 section in distributed firewall.

• Retrieve the configuration for the specified section.

• Retrieve the Etag value from the response headers.

NSX API Guide Version: 6.4 Page 285

• Extract and modify the configuration from the response body as needed.

• Set the If-Match header to the Etag value, and submit the request.

• Starting in NSX 6.4.5, the Etag value returned in the response header of the GET API request contains double

quotes. You must strip off the double quotes before using the Etag value in the If-Match header. If you are using the

PUT API request in an automation script, ensure that the script strips off the double quotes in the Etag value.

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.

Method history:

Release Modification

6.4.0

Method updated. tcpStrict, stateless, and useSid

added as section attributes.

Request:

Body: application/xml

<section generationNumber="1510700045886" id="4" name="TestSectionRenamed" stateless="false"

tcpStrict="true" timestamp="1510700045886" type="LAYER3" useSid="false">

€<rule disabled="false" id="16" logged="false">

€€€<name>okn-2</name>

€€€<action>ALLOW</action>

€€€<appliedToList>

€€€€€<appliedTo>

€€€€€€€<name>vm1 - Network adapter 1</name>

€€€€€€€<value>5013bcd8-c666-1e28-c7a9-600da945954f.000</value>

€€€€€€€<type>Vnic</type>

€€€€€€€<isValid>true</isValid>

€€€€€</appliedTo>

€€€€€<appliedTo>

€€€€€€€<name>Small XP-2</name>

€€€€€€€<value>vm-126</value>

€€€€€€€<type>VirtualMachine</type>

€€€€€€€<isValid>true</isValid>

€€€€€</appliedTo>

€€€</appliedToList>

€€€<sectionId>4</sectionId>

€€€<sources excluded="false">

€€€€€<source>

€€€€€€€<name>Site B Datacenter</name>

€€€€€€€<value>datacenter-57</value>

€€€€€€€<type>Datacenter</type>

NSX API Guide Version: 6.4 Page 286

€€€€€€€<isValid>true</isValid>

€€€€€</source>

€€€€€<source>

€€€€€€€<name>Compute Cluster 6</name>

€€€€€€€<value>domain-c62</value>

€€€€€€€<type>ClusterComputeResource</type>

€€€€€€€<isValid>true</isValid>

€€€€€</source>

€€€€€<source>

€€€€€€€<value>10.112.1.1</value>

€€€€€€€<type>Ipv4Address</type>

€€€€€€€<isValid>true</isValid>

€€€€€</source>

€€€</sources>

€€€<services>

€€€€€<service>

€€€€€€€<destinationPort>80</destinationPort>

€€€€€€€<protocol>6</protocol>

€€€€€€€<subProtocol>6</subProtocol>

€€€€€</service>

€€€€€<service>

€€€€€€€<name>VMware-VDM2.x-Ephemeral</name>

€€€€€€€<value>application-161</value>

€€€€€€€<isValid>true</isValid>

€€€€€</service>

€€€</services>

€</rule>

€<rule disabled="true" id="15" logged="true">

€€€<name>Matru-3</name>

€€€<action>DENY</action>

€€€<sectionId>4</sectionId>

€</rule>

€<rule disabled="true" id="14" logged="true">

€€€<name>test-3</name>

€€€<action>ALLOW</action>

€€€<sectionId>4</sectionId>

€</rule>

€<rule disabled="true" id="13" logged="true">

€€€<name>test-2</name>

€€€<action>ALLOW</action>

€€€<sectionId>4</sectionId>

€</rule>

€<rule disabled="true" id="12" logged="false">

€€€<name>test-1</name>

€€€<action>DENY</action>

€€€<sectionId>4</sectionId>

€</rule>

</section>

POST /api/4.0/firewall/globalroot-0/config/layer3sections/{sectionId}

URI Parameters:

sectionId€€(required) The ID of the section to modify.

Query Parameters:

action€€(required) Set action to revise to change the position of the firewall

rule section.

NSX API Guide Version: 6.4 Page 287

operation€€(optional) operation can be insert_after, insert_before, insert_top,

or insert_before_default.

anchorId€€(optional) Specify the section ID to use for reference with

insert_before or insert_after operations.

Headers:

If-Match€€(required) The Etag value from the response headers from a GET

of the firewall configuration you want to modify.

Description:

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>

Request:

Body: application/xml

€<name></name>

€<action></action>

€<appliedToList>

€€€<appliedTo>

€€€€€<name></name>

€€€€€<value></value>

€€€€€<type></type>

€€€€€<isValid></isValid>

€€€</appliedTo>

€</appliedToList>

€<sectionId></sectionId>

</section>

DELETE /api/4.0/firewall/globalroot-0/config/layer3sections/{sectionId}

URI Parameters:

sectionId€€(required) The ID of the section to modify.

Description:

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:

NSX API Guide Version: 6.4 Page 288

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

POST /api/4.0/firewall/globalroot-0/config/layer3sections/{sectionId}/rules

URI Parameters:

sectionId€€(required) The ID of the section to modify.

Query Parameters:

operation€€(optional) Specify either insert_after, insert_before, or insert_top.

The default is insert_top.

anchorId€€(optional) Specify the rule ID to use as reference for insert_before

or insert_after operations.

• The anchorId must be present in the section that you

specified in the sectionId.

• If anchorId is the default rule, and the operation is

insert_after, the API throws an error. A rule cannot be

added after the default rule.

Headers:

If-Match€€(required) The Etag value from the response headers from a GET

of the firewall configuration you want to modify.

Description:

Add rules to the specified layer 3 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.

• Starting in NSX 6.4.5, the Etag value returned in the response header of the GET API request contains double

quotes. You must strip off the double quotes before using the Etag value in the If-Match header. If you are using the

POST API request in an automation script, ensure that the script strips off the double quotes in the Etag value.

NSX API Guide Version: 6.4 Page 289

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.

Request:

Body: application/xml

€<name>AddRuleTest</name>

€<action>allow</action>

€<notes></notes>

€<appliedToList>

€€€<appliedTo>

€€€€€<value>datacenter-26</value>

€€€€€<type>Datacenter</type>

€€€</appliedTo>

€</appliedToList>

€<sectionId>2</sectionId>

€<sources excluded="true">

€€€<source>

€€€€€<value>datacenter-26</value>

€€€€€<type>Datacenter</type>

€€€</source>

€</sources>

€<services>

€€€<service>

€€€€€<value>application-216</value>

€€€</service>

€</services>

</rule>

Working With a Specific Rule in a Specific Layer 3 Section

GET

/api/4.0/firewall/globalroot-0/config/layer3sections/{sectionId}/rules/{ruleId}

URI Parameters:

ruleId€€(required) The ID of the rule beeing read, updated or deleted

sectionId€€(required) The ID of the section to modify.

Description:

NSX API Guide Version: 6.4 Page 290

Retrieve information about the specified distributed firewall rule.

PUT

/api/4.0/firewall/globalroot-0/config/layer3sections/{sectionId}/rules/{ruleId}

URI Parameters:

ruleId€€(required) The ID of the rule beeing read, updated or deleted

sectionId€€(required) The ID of the section to modify.

Headers:

If-Match€€(required) The Etag value from the response headers from a GET

of the firewall configuration you want to modify.

Description:

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.

• Starting in NSX 6.4.5, the Etag value returned in the response header of the GET API request contains double

quotes. You must strip off the double quotes before using the Etag value in the If-Match header. If you are using the

PUT API request in an automation script, ensure that the script strips off the double quotes in the Etag value.

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.

Request:

Body: application/xml

€<name>AddRuleTestUpdated</name>

€<action>allow</action>

€<notes></notes>

€<appliedToList>

€€€<appliedTo>

€€€€€<value>datacenter-26</value>

€€€€€<type>Datacenter</type>

€€€</appliedTo>

€</appliedToList>

€<sectionId>2</sectionId>

€<sources excluded="true">

€€€<source>

€€€€€<value>datacenter-26</value>

€€€€€<type>Datacenter</type>

€€€</source>

€</sources>

€<services>

€€€<service>

€€€€€<value>application-216</value>

€€€</service>

€</services>

</rule>

NSX API Guide Version: 6.4 Page 291

DELETE

/api/4.0/firewall/globalroot-0/config/layer3sections/{sectionId}/rules/{ruleId}

URI Parameters:

ruleId€€(required) The ID of the rule beeing read, updated or deleted

sectionId€€(required) The ID of the section to modify.

Headers:

If-Match€€(required) The Etag value from the response headers from a GET

of the firewall configuration you want to modify.

Description:

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.

GET /api/4.0/firewall/globalroot-0/config/layer2sections

Query Parameters:

name€€(required) Name of the Section to read

Description:

Retrieve rules from the layer 2 section specified by section name.

Method history:

Release Modification

6.4.0

Method updated. tcpStrict, stateless, and useSid

added as section attributes.

Responses:

Status Code: 200

Body: application/xml

€<section class="section" generationNumber="1554090322751" id="1001" name="Default Section Layer2"

timestamp="1554090322751" type="LAYER2">

€€€<rule disabled="false" id="1004" logged="false">

NSX API Guide Version: 6.4 Page 292

€€€€€<name>Default Rule</name>

€€€€€<action>allow</action>

€€€€€<appliedToList>

€€€€€€€<appliedTo>

€€€€€€€€€<name>DISTRIBUTED_FIREWALL</name>

€€€€€€€€€<value>DISTRIBUTED_FIREWALL</value>

€€€€€€€€€<type>DISTRIBUTED_FIREWALL</type>

€€€€€€€€€<isValid>true</isValid>

€€€€€€€</appliedTo>

€€€€€</appliedToList>

€€€€€<sectionId>1001</sectionId>

€€€€€<precedence>default</precedence>

€€€€€<direction>inout</direction>

€€€€€<packetType>any</packetType>

€€€</rule>

€</section>

</sections>

POST /api/4.0/firewall/globalroot-0/config/layer2sections

Query Parameters:

operation€€(optional) operation can be insert_after, insert_before, insert_top,

or insert_before_default.

anchorId€€(optional) Specify the section ID to use for reference with

insert_before or insert_after operations.

Description:

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.

See "Working with Distributed Firewall Configuration" for information about configuring tcpStrict, stateless, and

useSid for a section.

Method history:

Release Modification

6.4.0

Method updated. tcpStrict, stateless, and useSid

added as section attributes.

Request:

Body: application/xml

€<rule disabled="" logged="">

€€€<name></name>

€€€<action></action>

€€€<appliedToList>

€€€€€<appliedTo>

€€€€€€€<name></name>

€€€€€€€<value></value>

€€€€€€€<type></type>

€€€€€€€<isValid></isValid>

€€€€€</appliedTo>

NSX API Guide Version: 6.4 Page 293

€€€</appliedToList>

€€€<sources excluded="">

€€€€€<source>

€€€€€€€<name></name>

€€€€€€€<value></value>

€€€€€€€<type></type>

€€€€€€€<isValid></isValid>

€€€€€</source>

€€€</sources>

€€€<destinations excluded="">

€€€€€<destination>

€€€€€€€<name></name>

€€€€€€€<value></value>

€€€€€€€<type></type>

€€€€€€€<isValid></isValid>

€€€€€</destination>

€€€</destinations>

€€€<services>

€€€€€<service>

€€€€€€€<destinationPort></destinationPort>

€€€€€€€<protocol></protocol>

€€€€€€€<subProtocol></subProtocol>

€€€€€</service>

€€€</services>

€</rule>

</section>

Working With a Specific Layer 2 Distributed Firewall Section

GET /api/4.0/firewall/globalroot-0/config/layer2sections/{sectionId}

URI Parameters:

sectionId€€(required) The ID of the section to modify.

Description:

Retrieve information about the specified layer 2 section.

Method history:

Release Modification

6.4.0

Method updated. tcpStrict, stateless, and useSid

added as section attributes.

PUT /api/4.0/firewall/globalroot-0/config/layer2sections/{sectionId}

URI Parameters:

sectionId€€(required) The ID of the section to modify.

Headers:

If-Match€€(required) The Etag value from the response headers from a GET

of the firewall configuration you want to modify.

NSX API Guide Version: 6.4 Page 294

Description:

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.

• Starting in NSX 6.4.5, the Etag value returned in the response header of the GET API request contains double

quotes. You must strip off the double quotes before using the Etag value in the If-Match header. If you are using the

PUT API request in an automation script, ensure that the script strips off the double quotes in the Etag value.

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.

Method history:

Release Modification

6.4.0

Method updated. tcpStrict, stateless, and useSid

added as section attributes.

Request:

Body: application/xml

€<rule disabled="" id="" logged="">

€€€<name></name>

€€€<action></action>

€€€<appliedToList>

€€€€€<appliedTo>

€€€€€€€<name></name>

€€€€€€€<value></value>

€€€€€€€<type></type>

€€€€€€€<isValid></isValid>

€€€€€</appliedTo>

€€€</appliedToList>

€€€<sectionId></sectionId>

€€€<sources excluded="">

€€€€€<source>

€€€€€€€<name></name>

€€€€€€€<value></value>

€€€€€€€<type></type>

€€€€€€€<isValid></isValid>

NSX API Guide Version: 6.4 Page 295

€€€€€</source>

€€€</sources>

€€€<services>

€€€€€<service>

€€€€€€€<destinationPort></destinationPort>

€€€€€€€<protocol></protocol>

€€€€€€€<subProtocol></subProtocol>

€€€€€</service>

€€€</services>

€</rule>

</section>

POST /api/4.0/firewall/globalroot-0/config/layer2sections/{sectionId}

URI Parameters:

sectionId€€(required) The ID of the section to modify.

Query Parameters:

action€€(required) Set action to revise to change the position of the firewall

rule section.

operation€€(optional) operation can be insert_after, insert_before, insert_top,

or insert_before_default.

anchorId€€(optional) Specify the section ID to use for reference with

insert_before or insert_after operations.

Headers:

If-Match€€(required) The Etag value from the response headers from a GET

of the firewall configuration you want to modify.

Description:

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>

Request:

Body: application/xml

€<name></name>

€<action></action>

€<appliedToList>

€€€<appliedTo>

€€€€€<name></name>

NSX API Guide Version: 6.4 Page 296

€€€€€<value></value>

€€€€€<type></type>

€€€€€<isValid></isValid>

€€€</appliedTo>

€</appliedToList>

€<sectionId></sectionId>

</section>

DELETE /api/4.0/firewall/globalroot-0/config/layer2sections/{sectionId}

URI Parameters:

sectionId€€(required) The ID of the section to modify.

Description:

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

POST /api/4.0/firewall/globalroot-0/config/layer2sections/{sectionId}/rules

URI Parameters:

sectionId€€(required) The ID of the section to modify.

Headers:

If-Match€€(required) The Etag value from the response headers from a GET

of the firewall configuration you want to modify.

Description:

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:

NSX API Guide Version: 6.4 Page 297

• 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.

• Starting in NSX 6.4.5, the Etag value returned in the response header of the GET API request contains double

quotes. You must strip off the double quotes before using the Etag value in the If-Match header. If you are using the

POST API request in an automation script, ensure that the script strips off the double quotes in the Etag value.

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.

Request:

Body: application/xml

€<name></name>

€<action></action>

€<notes></notes>

€<appliedToList>

€€€<appliedTo>

€€€€€<value></value>

€€€€€<type></type>

€€€</appliedTo>

€</appliedToList>

€<sources excluded="">

€€€<source>

€€€€€<name></name>

€€€€€<value></value>

€€€€€<type></type>

€€€€€<isValid></isValid>

€€€</source>

€</sources>

€<destinations excluded="">

€€€<destination>

€€€€€<name></name>

€€€€€<value></value>

€€€€€<type></type>

€€€€€<isValid></isValid>

€€€</destination>

€</destinations>

€<services>

€€€<service>

€€€€€<value></value>

€€€</service>

€</services>

</rule>

NSX API Guide Version: 6.4 Page 298

Working With a Specific Rule in a Specific Layer 2 Section

GET

/api/4.0/firewall/globalroot-0/config/layer2sections/{sectionId}/rules/{ruleId}

URI Parameters:

ruleId€€(required) The ID of the rule.

sectionId€€(required) The ID of the section to modify.

Description:

Retrieve the configuration of the specified rule.

PUT

/api/4.0/firewall/globalroot-0/config/layer2sections/{sectionId}/rules/{ruleId}

URI Parameters:

ruleId€€(required) The ID of the rule.

sectionId€€(required) The ID of the section to modify.

Headers:

If-Match€€(required) The Etag value from the response headers from a GET

of the firewall configuration you want to modify.

Description:

Update a distributed firewall rule in a layer 2 section.