A set of three PowerShell scripts to export, import, and clean up NSX segments and segment profiles across any NSX environment.
Compatible with NSX 4.x and NSX 9.x.
By Paul van Dieen www.hollebollevsan.nl
| Script | Purpose |
|---|---|
Export-NSXSegments.ps1 |
Exports segments, custom profiles, and profile binding maps from a source NSX to a JSON + CSV file pair |
Import-NSXSegments.ps1 |
Imports the JSON + CSV pair into a target NSX, with interactive transport zone selection, overlay validation, and name remapping |
Remove-NSXSegments.ps1 |
Interactively selects and deletes segments and/or profiles, with a typed confirmation gate |
tests/New-NSXSMTestSet.ps1 |
Builds, shows and removes a throwaway NSXSM-T-* test set in a lab NSX Manager |
tests/New-NSXSMScaleSet.ps1 |
Builds and removes a large NSXSM-S-* set (default 500 segments) in a lab NSX Manager |
- PowerShell 5.1 or later (PS7 recommended)
- Network access to the NSX Manager REST API (port 443)
- NSX admin credentials
.\Export-NSXSegments.ps1 -NSXManager nsx-source.corp.local -SkipCertCheckOn first run you will be prompted for your username and password, then asked whether to save them for future runs. Select which segments to export from the interactive menu. Two files are written:
nsx-export_<timestamp>.json— full object data for the importernsx-export_<timestamp>.csv— name-mapping table; edit before importing
Open the CSV in Excel or any text editor. Fill in the NewName column for any object you want renamed on the target NSX. Leave NewName identical to OldName to keep the existing name.
| Type | Controls | Edit when... |
|---|---|---|
Segment |
Segment display_name and id | You want a different name on the target |
SegmentProfile |
Profile name; binding paths update automatically | Profile should be renamed |
T1Gateway |
T1 gateway id in connectivity_path | Target NSX has a different gateway id |
.\Import-NSXSegments.ps1 -NSXManager nsx-target.corp.local `
-InputPath ./nsx-export_<timestamp>.json -WhatIf.\Import-NSXSegments.ps1 -NSXManager nsx-target.corp.local `
-InputPath ./nsx-export_<timestamp>.json -SkipCertCheckThe script will prompt you to:
- Select which segments to import
- Choose a transport zone from the target NSX
- Fill in any missing gateway or subnet values (overlay segments only)
.\Remove-NSXSegments.ps1 -NSXManager nsx-source.corp.local -SkipCertCheckAll three scripts handle credentials the same way:
First run (no saved credential):
NSX username: admin
NSX password: ********
Save credential for future runs? (Y/N): Y
Credential saved to: C:\Scripts\nsx-segment-migration\creds\nsx-source.corp.local.cred
Subsequent runs (saved credential found):
Saved credential found for 'nsx-source.corp.local' (user: admin)
[1] Use saved credential
[2] Enter new credential and save over existing
[3] Enter new credential without saving
Select: 1
Credentials are saved per NSX Manager in creds\<manager>.cred next to the scripts, so source and target environments each have their own file (creds/ is in .gitignore). On Windows the password is encrypted with DPAPI and can only be decrypted by your Windows user account on the same machine; on Linux and macOS Export-Clixml does not encrypt it, and the scripts say so when they save.
Before v2.2 / v2.4 / v1.3 the file was %USERPROFILE%\.nsx_cred_<manager>.xml. The scripts still read that file if there is no creds\ file yet; choose [2] once to save it in the new place.
To bypass the interactive flow entirely, pass a credential object directly:
$cred = Import-Clixml .\creds\nsx-source.corp.local.cred
.\Export-NSXSegments.ps1 -NSXManager nsx-source.corp.local -Credential $cred -SkipCertCheckThe scripts need an interactive console for their menus. Without one (input redirected, a scheduled task) a prompt stops the script with "No console input for the prompt ..." instead of an unclear error.
| Parameter | Required | Default | Description |
|---|---|---|---|
-NSXManager |
Yes | — | FQDN or IP of the source NSX Manager |
-Credential |
No | Interactive | PSCredential for the NSX admin account |
-OutputBase |
No | ./nsx-export_<timestamp> |
Base path for output files (no extension) |
-SegmentFilter |
No | * |
Wildcard filter on segment display_name |
-SkipCertCheck |
No | — | Bypass TLS certificate validation |
- Segments (selected interactively)
- All custom segment profiles (QoS, SpoofGuard, IP Discovery, MAC Discovery, Segment Security)
- Profile binding maps per segment:
segment-discovery-profile-binding-maps(IP Discovery, MAC Discovery)segment-security-profile-binding-maps(Segment Security, SpoofGuard)segment-qos-profile-binding-maps(QoS)
# Basic export
.\Export-NSXSegments.ps1 -NSXManager nsx.corp.local -SkipCertCheck
# Filter segments and set output path
.\Export-NSXSegments.ps1 -NSXManager nsx.corp.local `
-SegmentFilter "prod-*" `
-OutputBase ./exports/prod-migration `
-SkipCertCheck| Parameter | Required | Default | Description |
|---|---|---|---|
-NSXManager |
Yes | — | FQDN or IP of the target NSX Manager |
-Credential |
No | Interactive | PSCredential for the NSX admin account |
-InputPath |
Yes | — | Path to the .json file from Export |
-MappingPath |
No | Same path as InputPath with .csv extension |
Explicit path to the CSV name-mapping file |
-TransportZoneId |
No | Interactive menu | Transport zone id to apply to all imported segments |
-Disconnected |
No | — | Import the selected segments without a gateway connection (connectivity_path removed, subnets kept); skips the overlay prompts |
-SkipCertCheck |
No | — | Bypass TLS certificate validation |
-WhatIf |
No | — | Preview all changes without making any API calls |
Objects are always imported in this sequence to satisfy dependencies:
- Custom segment profiles — all profiles from the export (idempotent PATCH, safe to re-run)
- Segments — only the ones selected in the menu
- Profile binding maps — applied per-segment immediately after each segment is created
After connecting, an interactive menu lists all transport zones on the target NSX. Select one to apply it to all imported segments, or press Enter to keep the transport zone from the export file. Supply -TransportZoneId on the command line to skip the menu.
When the selected transport zone is an overlay zone (OVERLAY_BACKED, OVERLAY_STANDARD or OVERLAY_ENS), the script checks each segment for the two fields NSX requires:
connectivity_path— T0 or T1 gateway connectionsubnets— gateway IP and prefix (e.g.192.168.10.1/24)
Missing values trigger an interactive prompt before any import begins. VLAN-backed segments skip this step entirely. With -Disconnected the check is skipped.
-Disconnected imports every selected segment with Connectivity None: the script removes connectivity_path before the PATCH and keeps the subnets. Use it for overlay subnets that keep their IP addresses in a side-by-side migration without HCX: the old Tier-1 keeps the gateway until the cutover, so the target segment must not advertise the same subnet yet. NSX allows this ("If a segment is not connected to a gateway, subnet is optional") and lets you change the connectivity from None to a Tier-0 or Tier-1 later (Create an NSX Segment).
The summary ends with a table per segment: ConnectAtCutover (the source gateway, with a Tier-1 renamed per the CSV) and the subnets. Select the segments in the menu, so you can import some connected and some disconnected in two runs.
.\Import-NSXSegments.ps1 -NSXManager nsx-target.corp.local `
-InputPath ./nsx-export_<timestamp>.json -Disconnected -WhatIf# Standard import
.\Import-NSXSegments.ps1 -NSXManager nsx-target.corp.local `
-InputPath ./nsx-export_20260101_120000.json -SkipCertCheck
# Skip transport zone menu
.\Import-NSXSegments.ps1 -NSXManager nsx-target.corp.local `
-InputPath ./exports/prod-migration.json `
-TransportZoneId tz-overlay-prod `
-SkipCertCheck
# Dry run
.\Import-NSXSegments.ps1 -NSXManager nsx-target.corp.local `
-InputPath ./nsx-export_20260101_120000.json -WhatIf| Parameter | Required | Default | Description |
|---|---|---|---|
-NSXManager |
Yes | — | FQDN or IP of the NSX Manager |
-Credential |
No | Interactive | PSCredential for the NSX admin account |
-SegmentFilter |
No | * |
Wildcard filter on segment display_name |
-SkipCertCheck |
No | — | Bypass TLS certificate validation |
-WhatIf |
No | — | Preview all deletions without making any API calls |
The script enforces the correct deletion sequence automatically:
- Profile binding maps — removed silently from each segment before the segment DELETE
- Segments — deleted after their binding maps are cleared
- Profiles — deleted after all segments are gone
- Independent menus for segments and profiles — press Enter at either to skip that category
- Port check before confirmation — segments with attached ports are flagged as a warning
- Typed
YESconfirmation required before any DELETE is executed - Full
-WhatIfsupport
# Interactive cleanup
.\Remove-NSXSegments.ps1 -NSXManager nsx.corp.local -SkipCertCheck
# Filter segments shown in the menu
.\Remove-NSXSegments.ps1 -NSXManager nsx.corp.local `
-SegmentFilter "test-*" -SkipCertCheck
# Dry run
.\Remove-NSXSegments.ps1 -NSXManager nsx.corp.local -SkipCertCheck -WhatIf| Path format | NSX version |
|---|---|
/infra/segment-profiles/<type>/<id> |
NSX 4.x (legacy) |
/infra/<type>/<id> |
NSX 9.x (flat) |
All three scripts try both path formats automatically and use whichever responds. The path that succeeds on GET is the same path used for subsequent PATCH and DELETE calls on the same object.
-SkipCertCheck bypasses TLS validation and works for self-signed certificates. If your NSX uses a certificate signed by an internal CA, you may still see validation errors because Windows cannot build a trust chain to the CA root. The fix is to import your CA certificate into the Windows Trusted Root store:
Import-Certificate -FilePath "your-internal-ca.cer" `
-CertStoreLocation Cert:\LocalMachine\RootOnce your CA is trusted, -SkipCertCheck is no longer needed.
tests/New-NSXSMTestSet.ps1 builds a test set in a lab NSX Manager (-Mode Create): one custom profile of each type the export carries (QoS, SpoofGuard, IP Discovery, MAC Discovery, Segment Security), a Tier-1 without an Edge cluster, and four segments: two overlay segments with a gateway and subnet (one with all five profiles bound), an overlay segment without a gateway and a VLAN segment. -Mode Show lists each segment's transport zone, gateway, subnets, VLAN and bound profiles; -Mode Remove deletes the set. It only touches NSXSM-T-* objects and reads the same credential file as the scripts.
Suggested run: Create, Export the NSXSM-T-Ovl-GW* segments, give them a new name in the CSV (NSXSM-T-Imp-GW1, ...) so the import doesn't overwrite them, Import with -WhatIf, Import with -Disconnected, compare with Show.
Lab results (2026-11-16):
- NSX 4.2.4.1 to itself: the
-Disconnectedimport gave both copies Connectivity None with their subnets and all profile bindings, and the cutover table namedNSXSM-T-T1.Remove-NSXSegments.ps1removed the copies (bindings first) after the port check and the typedYES. - NSX 4.2.4.1 to NSX 9.1.1: the whole set imported (overlay segments with a gateway via
-Disconnected, the one without a gateway and the VLAN segment in separate runs, one transport zone per run); the profiles landed on NSX 9's flat/infra/<type>/paths with all bindings. Removed again withRemove-NSXSegments.ps1.
tests/New-NSXSMScaleSet.ps1 builds a large set for scale tests: the five custom profiles as NSXSM-S-*, three Tier-1s without an Edge cluster (-Tier1Count) and 500 segments (-SegmentCount): 60% overlay with a /24 gateway, 20% overlay without gateway, 20% VLAN, every tenth with all five profiles bound. On NSX 9.1.1 the set takes about 1.5 minutes; -Mode Remove deletes it. Test cases and results: tests/TESTPLAN.md.
Get-Helpshows the full help again: a blank line between#Requiresand the help block (without itGet-Helpignored the whole help block). Same fortests/New-NSXSMTestSet.ps1(v1.0.1), whose changelog also moved out of the help block.
- Overlay validation runs for every overlay transport zone type; it was skipped for
OVERLAY_STANDARD, the type of NSX 4's defaultnsx-overlay-transportzone(#5).
- Prompts without console input stop with "No console input for the prompt ..." instead of failing on
.Trim()of$null(#3). - Credentials are saved in
creds\<manager>.crednext to the scripts; the old%USERPROFILE%\.nsx_cred_<manager>.xmlis still read (#3). - Import:
-WhatIflists the binding maps it would write and ends with a dry-run summary (what would be written, nothing changed) instead of "All items imported successfully!" (#3). - New
tests/New-NSXSMTestSet.ps1(#3).
- Added
-Disconnected: imports the selected segments without a gateway connection (connectivity_pathremoved, subnets kept), skips the overlay prompts and ends with aConnectAtCutovertable. Replaces editing the export JSON by hand (#1).
- Added built-in credential save and reset. On first run credentials are prompted and optionally saved per NSX Manager using Windows DPAPI encryption. Subsequent runs offer to reuse, overwrite, or ignore the saved credential.
- Replaced
Get-CredentialwithRead-Hostprompts to fix null credential errors in non-interactive PowerShell hosts. - Fixed
PropertyNotFoundExceptioncrash underSet-StrictMode -Version LatestwhenGet-Credentialreturned null. - Added
$ScriptMetabranding banner (Name, Author, Blog, Date) consistent with other scripts in the toolkit.
- Added interactive transport zone selection menu after connecting to the target NSX.
- Added overlay segment validation: prompts for missing gateway and subnet before import begins when an OVERLAY_BACKED transport zone is selected.
- Full rewrite with clean comments and consistent style.
- Added
Get-AllPagespagination support. - Profile binding maps now exported and imported via typed child paths (
segment-discovery-profile-binding-maps,segment-security-profile-binding-maps,segment-qos-profile-binding-maps). - NSX 4.x and 9.x profile path formats handled automatically.
- Profile path remap table ensures binding maps reference the correct renamed paths on the target.
- Added port count check before confirmation prompt.
- Fixed extra confirmation prompts caused by
ConfirmImpact = 'High'. - Binding map deletion no longer triggers
ShouldProcessprompts.
- Initial release of Remove-NSXSegments.ps1.
MIT
More posts and tools at hollebollevsan.nl