NSX CLI Guide

Copyright © 2014-2024 VMware, Inc. All rights reserved. Copyright and trademark information.

NSX CLI Guide

NSX 4.2.1

Overview

The NSX Command-Line Interface Reference describes how to use the NSX Command-Line Interface (CLI) and includes examples and command overviews.

Intended Audience

The information in this guide is written for experienced systems and network administrators who are familiar with virtual machine technology and virtual datacenter operations.

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.

Document Feedback

VMware welcomes your suggestions for improving our documentation. If you have comments, send your feedback to [email protected].


Introduction to the NSX CLI

Each NSX virtual appliance contains a command-line interface (CLI). The command syntax and output format of NSX commands are not guaranteed to be the same from release to release. If you are automating tasks, please use the API. See the NSX API Guide for details.

Logging In and Out of the CLI

Before you can run CLI commands, you must connect to an NSX virtual appliance. You can connect to the console or through SSH.

If you did not enable SSH while installing the appliance, you can use the set service ssh start-on-boot command to enable the SSH service.

To log out, type exit from Basic mode.

CLI Command Modes

The commands available to you at any given time depend on the mode you are currently in.

  • Basic. Basic mode provides commands to manage and view the status of the NSX appliance.

  • VRF. VRF mode, available on NSX Edge appliances, provides commands to view properties of a VRF (Virtual Routing and Forwarding) context

  • Tier0 SR. Tier0_sr mode, available on NSX Edge appliances, provides commands to view properties of a tier 0 service router VRF (Virtual Routing and Forwarding) context.

  • Tier1 SR. Tier1_sr mode, available on NSX Edge appliances, provides commands to view properties of a tier 1 service router VRF (Virtual Routing and Forwarding) context.

  • Path. Path mode, available on NSX Edge appliances, provides commands to view properties of the logical router interfaces and logical switch ports in the path between a logical router interface and an IP address.

    • CLI Command Output Modifiers

    You can apply output modifiers on some NSX CLI commands which provides modified command output per usage.

    For example, get files | sort, sorts the output of the get files command.

    Entering | ? after a command shows applicable output modifiers command supports. If command does not support any output modifiers, an % Output modifiers are not supported for this command error message is displayed upon execution.

    List of available modifiers:

  • awk: Show awk command output

  • count: Count number of specified entities

  • find: Only show lines that contain regex pattern

  • first: Show first N lines of output

  • ignore: Ignore lines that contain regex pattern

  • json: Show output in JSON format

  • last: Show last N lines of output

  • more: Show output one page at a time

  • sed: Show sed command output

  • sort: Sort command output

  • uniq: Show uniq command output

    • Note, Command Output modifier awk, more, sed and uniq are not supported in Windows Physical Server.

    Remote (Central and SmartNIC) CLI

    Remote CLI provides ability to issue command on remote nodes from different source platforms -

    • Central CLI issue a command from NSX Manager nodes in cluster on any other remote NSX nodes under same management cluster or fabric node.

    • NSX enabled DPU/SmartNICs NSX includes command data from VMware DPUs installed on ESXi nodes.

    For example, in case of Central CLI command is
    nsxmanager> on ?

    uuid node-type         ip-address    ipv6-address   hostname   display-name
    15df7116-7f5d-11eb-a9e3-020057648652 edg 10.206.184.78 2620:124:6020:c306:250:56ff:fe81:b1f2 nsx-edge-1.hostname nsx-edge-1.displayname
    4502cf74-7f5d-11eb-af38-0200576945d9 esx 10.206.185.69 N/A esx1.hostname esx1.displayname

    Central CLI commands can only be issued on NSX manager nodes, which always starts with on followed by multiple (one or more) remote node uuids, node ips, node fqdns or node display names.

    For example,
    nsxmanager> on 10.206.184.78 4502cf74-7f5d-11eb-af38-0200576945d9 exec get node-uuid
    ---------------------------------------------------------------------------------------
    15df7116-7f5d-11eb-a9e3-020057648652          edg          nsx-edge1.hostname
    ---------------------------------------------------------------------------------------
    uuid: 15df7116-7f5d-11eb-a9e3-020057648652
    ---------------------------------------------------------------------------------------
    4502cf74-7f5d-11eb-af38-0200576945d9          esx          esx1.hostname
    ---------------------------------------------------------------------------------------
    uuid: 4502cf74-7f5d-11eb-af38-0200576945d9

    Above command get node-uuid is executed on two remote nodes (10.206.184.78 & 4502cf74-7f5d-11eb-af38-0200576945d9) and displays the result as soon as command completes.
    Note, results can not always be guaranteed to display in the order specified during execution.

    whereas for example, remote SmartNIC CLI can be executed on ESXi node with configured VMware DPUs as follows
    esx-nsxcli> on esxio 02b9e95c-51fd-5cd4-bff6-2bc2ac7b595c exec get vswitch runtime

    IGMPQueries: 2
    IGMPQueryInterval: 125
    ...
    RARPAdvertisementDuration: 60
    TeamPolicyUpDelay: 100

    Note, by default ESXi hosts configured with DPUs, include NSX enabled data from remote SmartNIC accelerators.

    Session Mode

    You can connect to remote session on NSX Manager to any NSX node under same management cluster or fabric node. It launches remote CLI session for a specified node; where available commands on the respective node can be executed.

    For example,
    nsxmanager1> on 4502cf74-7f5d-11eb-af38-0200576945d9 exec
    Entering session mode
    SESSION-MODE> get version
    ----------------------------------------------------------------------------------------
    4502cf74-7f5d-11eb-af38-0200576945d9          esx          esx1.hostname
    ----------------------------------------------------------------------------------------
    VMware NSX Software, Version 3.2.0.0.0.44911683
    Technical Support: http://www.vmware.com/support.html
    .....
    or more patents listed at http://www.vmware.com/go/patents.


    nsxmanager1> on nsxedge-fqdn exec
    Entering session mode
    SESSION-MODE> get version
    ----------------------------------------------------------------------------------------
    8ba31c66-6af9-11ed-8589-060624c0b332          esx          esx1.hostname
    ----------------------------------------------------------------------------------------
    VMware NSX Software, Version 3.2.0.0.0.44911683
    Technical Support: http://www.vmware.com/support.html
    .....
    or more patents listed at http://www.vmware.com/go/patents.

    To exit from session mode issue an exit command under current session context.

    CLI Exit Codes

    Following are different types of Exit Codes NSX CLI session can return on command execution:

    Return Value Type Details
    0 CMD_EXECUTED Command Executed successfully
    1 CMD_UNEXPECTED_ERROR Command executed with unexpected error
    2 CMD_NOT_EXECUTED Unable to execute command
    3 CMD_EXECUTED_REQUESTED_EXIT Exit command executed successfully
    4 CMD_EXECUTED_WITH_ERROR_RESULT Command executed with error output
    10 CMD_SESSION_TIMEOUT CLI Session timed-out
    11 CMD_UNEXPECTED_EXCEPTION Command executed with unexpected exception
    12 CMD_UNSUPPORTED_MODE CLI request unsupported
    20 CLI_LOG_FILE_CREATE_ERROR Failed to launch CLI - unable to create log file
    99 CLI_START_ERROR Unable to launch CLI
    100 - 164 CLI_ABRUPT_EXIT CLI session exited abruptly

    CLI Command Markers

    As per the behaviour or functionality of command it might be marked with one or more icons as represent in legend below:

    Icon Flag Details
    Central CLI Unsupported Specifies whether the given NSX-CLI command is available for remote execution in Management cluster
    Output Modifiers Unsupported Specifies whether usage of Command Output Modifiers is not supported on particular NSX-CLI command
    Windows Physical Server Unsupported Specifies that given command or feature is not supported on Windows Physical Server
    Cluster based Specifies that given functionality of command will impact the settings or configuration applicable for all the nodes under same Management cluster

    Important Note

    Starting with NSX 2.1, the NSX Manager GUI uses the term N-VDS (NSX managed virtual distributed switch) to refer to what was known as host switch in previous releases. In this document, the term host switch is still used. The two terms are synonyms.

    The NSX Command-Line Interface Reference describes how to use the NSX Command-Line Interface (CLI) and includes examples and command overviews.

    The information in this guide is written for experienced systems and network administrators who are familiar with virtual machine technology and virtual datacenter operations.