Configuring static routes for vmkernel ports on an ESXi host

Products

• VMware vSphere ESXi

Issue/Introduction

• This article provides steps to configure routes to additional gateways for vmkernel ports on an ESXi host.

Environment

VMware vSphere ESXi 8.0.x

Resolution

Unlike ESX, ESXi does not have a service console. The management network is on a vmkernel port and therefore, uses the default vmkernel gateway. Only one vmkernel default gateway can be configured on an ESXi/ESX host. However, you can add static routes to additional gateways/routers from the command line.

 

To configure a static route to a second gateway/router for the management network, follow the below steps:

1. Open a console to the ESXi or ESX host. For more information, see Using ESXi Shell in ESXi
2. In ESXi 7.0, and ESXi 8.0:
    
   1. To add a static route, run the command:
      
      esxcli network ip route ipv4/ipv6 add --gateway IPv4_address_of_source_router --network IPv4_address_destination_network
      
      For example, to add a route to ##.##.##.## network with a /24 bit subnet mask (255.255.255.0) through a router with an IP address of xx.xx.xx.xx, run this command:
      
      esxcli network ip route ipv4 add --gateway xx.xx.xx.xx --network ##.##.##.##/24
       
   2. To list the route, run the command:
      
      esxcli network ip route ipv4 list
      
      
   3. To remove a static route, run the command:
      
      esxcli network ip route ipv4 remove -n network_ip/mask -g gateway_ip
      
      For example, to remove a route from ##.##.##.## network with a /24 bit subnet mask (255.255.255.0) through a router with an IP address of xx.xx.xx.xx, run this command:
      
      esxcli network ip route ipv4 remove -n ##.##.##.##/24 -g xx.xx.xx.xx
      
      
3. When finished, check the host's current routing table with the esxcfg-route -l command. Any static routes display in the output.

Note : # and xx Represents the ip4 address.

Additional Information

• If there are routes listed that were not statically added, they may have been dynamically added through ICMP Redirects. These routes cannot be removed through ESXi. See Internet Control Management Protocol Redirects.
  
  
• To successfully add a static route, the host must have direct subnet access to the router being specified through one of its vmkernel ports. If not, it cannot communicate with the gateway router and reports the error:
  
  Unable to route to gateway address x.x.x.x no route to that subnet exists
  
  For example, to route to the ##.##.##.#/24 network through the gateway router xx.xx.xx.xx, the host must have a vmkernel port configured in the xx.xx.xx.xx/24 network. Without this vmkernel port, it cannot communicate with xx.xx.xx.x to forward traffic relating to this static route.
  
  You must ensure that an entry exists for the network in the host's routing table as a Local Subnet Access network. To validate this, use the esxcfg-route -l command.
  
  
• You cannot add a new gateway for an existing subnet in the vmkernel as you cannot have two default gateway. In the aforementioned example, if an attempt is made to add a new gateway for x.x.x.x/24 network, an error similar to this occurs:
  
  Duplicate route to network x.x.x.x/24 found. Please delete the old route first.
  
  
• Note: When configuring routes in auto-deploy, the preferred way to create custom network entries use the answer file from a reference host. See: https://techdocs.broadcom.com/us/en/vmware-cis/vsphere/vsphere/8-0/esxi-installation-and-setup-8-0.html