Version 2

    Table of Contents

    • Author

    • Description

    • Category

    • Requirements

    • Version Support

    • Sample Execution

    • Script Download




    William Lam



    This script was motivated by VMTN community member and blogger Cody Bunch who posed a question on the VMware forums regarding vCLI and configuring advanced NIC teaming policy for a vSwitch. With today's current implementation of VMware's vCLI esxcfg-vswitch, it lacks quite on configuring advanced configurations for a vSwitch:




    • Number of ports when creating a new vSwitch



    • Promiscuous Mode

    • MAC Address Changes

    • Forged Transmits


    Traffic Shaping

    • Status

    • Average Bandwidth

    • Peak Bandwidth

    • Burst Size


    NIC Teaming

    • Load Balancing

    • Network Failover Detection

    • Notify Switches

    • Failback

    • Failover Order


    All these can be configured through the vSphere API, I'm guessing VMware decided not to include these features within esxcfg-vswitch, thinking that not many users will be automating these configurations via the CLI. Even with classic ESX, there were quite a few users wanting to automate these configurations and had to rely on unsupported vimsh wrapper (vmware-vim-cmd/vim-cmd) to setup the more advanced configurations for a vSwitch. This script allows you to configure all of these parameters.



    • Initial Server Set Up




    Version Support

    • Supports ESX(i) (licensed version only)



    [vi-admin@scofield ~]$ ./
    The options are invalid.
    Synopsis: ./ OPTIONS [<vswitch>]
    Command-specific options:
              Add a new virtual switch
              Add an uplink adapter (pnic) to a DVPort (valid for vSphere 4.0 and later)
              Add a portgroup to a virtual switch
              Add an uplink adapter (pnic) to a portgroup (valid for vSphere 4.0 and later)
              Average Bandwidth (Kbits/sec)
              Burst Size (Kbytes)
              Check to see if virtual switch exists
              Check to see if a portgroup exists
              Delete an uplink adapter from a DVPort (valid for vSphere 4.0 and later)
              Delete the portgroup from the virtual switch
              Delete an uplink adapter from a portgroup (valid for vSphere 4.0 and later)
              Delete the virtual switch
              The name of the DVPort (valid for vSphere 4.0 and later)
              Failback [yes|no]
              Network Failover Detection [LINK|BEACON]
              Enable or disable promiscous mode [accept|reject]
              Print the current CDP setting for this virtual switch (valid for vSphere 4.0 and later)
              Sets a pnic as an uplink for the virtual switch
              List vswitches and port groups
              Load Balancing policy [PORTID|IPHASH|MACHASH|FAILOVER]
              Enable or disable promiscous mode [accept|reject]
              Set MTU for the virtual switch
              List of linked vmnics to be set as active network adapters used for load balancing
              List of linked vmnics to be set as standby network adapters used for failover
              Notify Switches [yes|no]
              Peak Bandwidth (Kbits/sec
              The name of the portgroup
              The number of ports to vSwitch [8|24|56|120|248|504|1016|2040|4088]
              Enable or disable promiscous mode [accept|reject]
              Set the CDP status for a given virtual switch (valid for vSphere 4.0 and later).
              To set pass "down", "listen", "advertise", or "both"
              Enable or or disable promiscous mode [true|false]
              Removes a pnic from the uplinks for the virtual switch
              The host to use when connecting via Virtual Center
              Set vlan id for portgroup specified by -p
    Common VI options:
       --config (variable VI_CONFIG)
          Location of the VI Perl configuration file
       --credstore (variable VI_CREDSTORE)
          Name of the credential store file defaults to <HOME>/.vmware/credstore/vicredentials.xml on Linux and <APPDATA>/VMware/credstore/vicredentials.xml on Windows
       --encoding (variable VI_ENCODING, default 'utf8')
          Encoding: utf8, cp936 (Simplified Chinese), iso-8859-1 (German), shiftjis (Japanese)
          Display usage information for the script
       --passthroughauth (variable VI_PASSTHROUGHAUTH)
          Attempt to use pass-through authentication
       --passthroughauthpackage (variable VI_PASSTHROUGHAUTHPACKAGE, default 'Negotiate')
          Pass-through authentication negotiation package
       --password (variable VI_PASSWORD)
       --portnumber (variable VI_PORTNUMBER)
          Port used to connect to server
       --protocol (variable VI_PROTOCOL, default 'https')
          Protocol used to connect to server
       --savesessionfile (variable VI_SAVESESSIONFILE)
          File to save session ID/cookie to utilize
       --server (variable VI_SERVER, default 'localhost')
          VI server to connect to. Required if url is not present
       --servicepath (variable VI_SERVICEPATH, default '/sdk/webService')
          Service path used to connect to server
       --sessionfile (variable VI_SESSIONFILE)
          File containing session ID/cookie to utilize
       --url (variable VI_URL)
          VI SDK URL to connect to. Required if server is not present
       --username (variable VI_USERNAME)
       --verbose (variable VI_VERBOSE)
          Display additional debugging information
          Display version information for the script


    Sample Execution


    Create a new vSwitch specifying the number of ports:


    [vi-admin@scofield ~]$ ./ --server -a vSwitch2 --port 504


    Configure Promiscuous Mode (accept|reject):


    [vi-admin@scofield ~]$ ./ --server --promiscuous accept vSwitch2 --server


    Configure MAC Address change (accept|reject):


    [vi-admin@scofield ~]$ ./ --server --mac accept vSwitch2


    Configure Forged Transmits (accept|reject):


    [vi-admin@scofield ~]$ ./ --server --forged accept vSwitch2


    Enable Traffic Shapping:


    [vi-admin@scofield ~]$ ./ --server --trafficshape true vSwitch2


    Configure Average Bandwidth (Kbits/sec):


    [vi-admin@scofield ~]$ ./ --server --avgband 100 vSwitch2


    Configure Peak Bandwidth (Kbits/sec):


    [vi-admin@scofield ~]$ ./ --server --peakband 300 vSwitch2


    Configure Burst Size (Kbytes):


    [vi-admin@scofield ~]$ ./ --server --burstsize 400 vSwitch2


    Configure Load Balancing (PORTID|IPHASH|MACHASH|FAILOVER):


    [vi-admin@scofield ~]$ ./ --server --loadbalance IPHASH vSwitch2


    Configure Network Failover Detection (LINK|BEACON):


    [vi-admin@scofield ~]$ ./ --server --faildetect BEACON vSwitch2


    Configure Notify Switches (yes|no):


    [vi-admin@scofield ~]$ ./ --server --notifysw yes vSwitch2


    Configure Failback (yes|no):


    [vi-admin@scofield ~]$ ./ --server --failback no vSwitch2


    Configure Failover Order:


    Let's say we have 2 vmnic's that have been teamed using -L option and we want to set vmnic1 to active and vmnic2 to standby


    [vi-admin@scofield ~]$ ./ --server --nic-active vmnic1 --nic-standby vmnic2 vSwitch2


    *Note:* You can specify multiple vmnic devices to either --nic-active or --nic-standby


    [vi-admin@scofield ~]$ ./ --server --nic-standby vmnic1,vmnic2 vSwitch2


    With all these options, it could be painful if you had to run each one at a time? All the features added can actually be specified all on 1 line, assuming you meet all the requirements.


    Here is the scenario of creating a new vSwitch named vSwitch2 with 504 ports and teamed with 2 pNIC (vmnic1 and vmnic2) and configured with the following advanced options:


    Promiscuous Mode


    MAC Address Change


    Forged Transmits


    Traffic Shaping


    Average Bandwidth

    100 Kbits/sec

    Peak Bandwidth

    300 Kbits/sec

    Burst Size

    390 Kbytes

    Load Balancing

    Route based on source MAC hash

    Network Failover Detection

    Beacon Probing

    Notify Switches




    Failover Order

    Active=vmnic1 Standby=vmnic2


    [vi-admin@scofield ~]$ ./ --server -a vSwitch2 --port 504
    [vi-admin@scofield ~]$ ./ --server -L vmnic1 vSwitch2
    Update uplinks : vmnic1
    [vi-admin@scofield ~]$ ./ --server -L vmnic2 vSwitch2
    Update uplinks : vmnic1, vmnic2
    [vi-admin@scofield ~]$ ./ --server --promiscuous reject --mac accept --forged reject --trafficshape true --avgband 100 --peakband 300 --burstsize 390 --loadbalance MACHASH --faildetect BEACON --notifysw yes --failback no --nic-active vmnic1 --nic-standby vmnic2 vSwitch2


    Download script[here|]