Configuring Standard vSwitch (vSS) or virtual Distributed Switch (vDS) from the command line in ESXi
search cancel

Configuring Standard vSwitch (vSS) or virtual Distributed Switch (vDS) from the command line in ESXi

book

Article ID: 326175

calendar_today

Updated On: 02-11-2025

Products

VMware vSphere ESXi

Issue/Introduction

This article provides commands and information to configure or restore network connectivity via the Command Line Interface/ESXi shell. For guidance on recovering management connectivity to a vSphere Standard switch via CLI specifically, please see: Recover ESXi host connectivity when management is on DVS

Environment

VMware vSphere ESXi

Resolution

In ESXi 6.x and above


All of the below commands can be run in an SSH session with the host, or from the DCUI shell console:

  • View the current vSwitch configuration and vmkernel interface configuration using these commands:

esxcfg-vswitch -l # list all current virtual switch information
esxcli network vswitch standard list # list current standard vswitch configuration
esxcli network vswitch dvs vmware list # list Distributed Switch configuration
esxcli network ip interface list # list vmkernel interfaces and their configuration
esxcli network nic list # display listing of physical adapters and their link state

 

  • If an existing Standard vSwitch does not exist, one can be created with the below command:

esxcli network vswitch standard add --vswitch-name=vSwitch

Note: When creating a virtual switch, there are no linked vmnics by default, thus they will need to be linked using the commands described below. Additionally, follow Linux best practices when creating/modifying entities via CLI, for example avoiding special characters or spaces whenever possible.

 

  • Add or remove network cards (known as vmnics) to or from a Standard vSwitch using these commands:

esxcli network vswitch standard uplink remove --uplink-name=vmnic --vswitch-name=vSwitch # unlink an uplink
esxcli network vswitch standard uplink add --uplink-name=vmnic --vswitch-name=vSwitch # add an uplink

 

  • Add or remove network cards (known as vmnics) to or from a virtual Distributed Switch (vDS) using these commands:

esxcfg-vswitch -Q vmnic -V dvPort_ID_of_vmnic dvSwitch # unlink/remove a vDS uplink
esxcfg-vswitch -P vmnic -V unused_dvPort_ID dvSwitch # add a vDS uplink

 

  • To set the MTU of a Standard vSwitch to Jumbo Frames:

esxcfg-vswitch -m 9000 vswitch_name or
esxcli network vswitch standard set -m 9000 -v vswitch_name

 

  • A standard portgroup can be created on a S vSwitch with this command:

esxcli network vswitch standard portgroup add --portgroup-name=portgroup --vswitch-name=vSwitch

 

  • If the VMNICs associated with the network are VLAN trunks on the physical switchport, a VLAN ID for the corresponding standard portgroup will need to be applied as well. To set or correct the VLAN ID required for connectivity on a Standard vSwitch, run this command:

esxcli network vswitch standard portgroup set --portgroup-name=portgroup --vlan-id VLAN

 

  • If the physical NICs that are being adding to the standard virtual switch are in a port channel facing ESXi, then the load balancing policy on the portgroup using those NICs must be set to "Route Based on IP Hash" using the below command:

esxcli network vswitch standard policy failover set -l iphash -v vswitch_name

Note: If only one NIC is being moved to the Standard vSwitch/portgroup then an alternative would be to remove the NIC from the port channel on the physical switch. E.g. if vmnic0 and vmnic1 are in a port channel with each other but only vmnic0 is being added to the Standard vSwitch temporarily then vmnic0 can be removed from the port channel on the physical switch and nothing would need to be changed from an ESXi perspective.

 

  • View existing VMkernel adapter information using these commands:

esxcfg-vmknic -l or
esxcli network ip interface list # view vmkernel adapter information
esxcli network ip interface tag get --interface-name=vmkX # get the services that are tagged on the vmkernel adapter, such as Management or vMotion

 

  • Add new or remove existing vmkernel adapters using the following commands:

esxcli network ip interface remove --interface-name=vmkX # remove vmkernel adapter
esxcli network ip interface add --interface-name=vmkX --portgroup-name=portgroup # create vmkernel adapter

 

  • Modify an existing vmkernel adapter's networking configurations using the following commands:

esxcli network ip interface ipv4 set --interface-name=vmkX --ipv4=ipaddress --netmask=netmask -g=gatewayip --type=static # configure existing vmkernel adapter networking information

Note: The value must be a valid IPv4 address. If no gateway IP is provided, the gateway IP would be reset to "0.0.0.0" and need to be set before communication can occur

 

  • Add a tag to an existing vmkernel adapter's networking configurations using the following commands:

esxcli network ip interface tag add --interface-name=vmkX --tagname=tag # add a tag to a vmkernel adapter

add: Adds a tag on a given VMkernel network interface. Supported tags are: Management, VMotion, faultToleranceLogging,vSphereReplication, vSphereReplicationNFC, vSphereProvisioning, VSAN, VSANWitness, vSphereBackupNFC, PrecisionTimeProtocol, NVMeTCP, NVMeRDMA

remove: Removes a tag on a given VMkernel network interface.

Note: If there is no vmkernel adapter already tagged for Management services, then Management will automatically be tagged on the newly-created adapter

 

  • To set the MTU of a vmkernel adapter:

esxcli network ip interface set -m 9000 -i vmkX

Note: If the VMkernel (VMK) interface, which is part of a vSwitch, is configured to use Jumbo Frames (i.e. any MTU value over 1500) then the vSwitch it resides on must also be configured for Jumbo Frames as well. The command to adjust the MTU for a Standard vSwitch is listed above.

 

  • View and modify the default route on the esxi host using these commands:

esxcfg-route -l or
esxcli network ip route ipv4 list # list the default routes on the host
esxcfg-route -a <default gateway ip> # add a static route to the host's routing table

 

  • It may be necessary to restart the host's management agents if network connectivity is not restored despite a correct configuration:

services.sh restart

 

Notes:

  • The network to a Standard vSwitch may be restored using the Restore Standard Switch option from the Direct Console User Interface (DCUI) console screen (press F2 from console). This results in a blank network configuration (1 x vSwitch with 1 x vmkernel port group) on the ESXi host.
    • WARNING: Any existing vSwitch, portgroup, and VMkernel information is removed as a result of this option.
    • VMware recommends taking a screenshot of the network configuration from the vSphere Client or saving the output from the esxcfg-vswitch -l and esxcfg-vmknic -l commands before using this option.
  • The command-line tool provides limited functionality when running the esxcfg-vswitch or esxcli network commands with a Virtual Distributed Switch. For example, a dvportgroup or assign VLAN IDs to dvportgroups cannot be created or modified using this command. Some tasks must be completed from vCenter Server using the vSphere Client or vSphere Web Client.






Additional Information

Powered by Wolken Software