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.

NOTE: 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 (2081185).

Symptoms:

 

Environment

VMware vSphere ESXi 5.5
VMware ESXi 4.0.x Embedded
VMware ESXi 3.5.x Embedded
VMware vSphere ESXi 7.0.0
VMware ESXi 4.1.x Embedded
VMware vSphere ESXi 6.0
VMware vSphere ESXi 5.1
VMware vSphere ESXi 5.0
VMware ESXi 4.0.x Installable
VMware vSphere ESXi 6.5
VMware ESXi 4.1.x Installable
VMware ESXi 3.5.x Installable
VMware vSphere ESXi 6.7

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:

1. Open a console to the ESXi or ESX host. For more information, see Using ESXi Shell in ESXi
2. In ESXi 4.x and 5.0:
    

   1. To add a static route, run the command:
      
      esxcfg-route -a target_network_IP netmask default_gateway
      
      For example, to add a route to the 192.168.100.0 network with a /24 bit subnet mask (255.255.255.0) through a router with an IP address of 192.168.0.1, run one of these commands:
       

      • esxcfg-route -a 192.168.100.0/24 192.168.0.1
        
        Or
         
      • esxcfg-route -a 192.168.100.0 255.255.255.0 192.168.0.1
         
   2. To delete a static route, run the command:
      
      esxcfg-route -d target_network_IP netmask default_gateway
      
      For example, to delete a route from the 192.168.100.0 network with a /24 bit subnet mask (255.255.255.0) through a router with an IP address of 192.168.0.1, run one of these commands:
       
      • esxcfg-route -d 192.168.100.0/24 192.168.0.1
        
        Or
      • esxcfg-route -d 192.168.100.0 255.255.255.0 192.168.0.1
        
         
3. In ESXi 5.1, and ESXi 5.5, and ESXi 6.0, and 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_router --network IPv4_address
      
      For example, to add a route to 192.168.100.0 network with a /24 bit subnet mask (255.255.255.0) through a router with an IP address of 192.168.0.1, run this command:
      
      esxcli network ip route ipv4 add --gateway 192.168.0.1 --network 192.168.100.0/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 192.168.100.0 network with a /24 bit subnet mask (255.255.255.0) through a router with an IP address of 192.168.0.1, run this command:
      
      esxcli network ip route ipv4 remove -n 192.168.100.0/24 -g 192.168.0.1
4. When finished, check the host's current routing table with the esxcfg-route -l command. Any static routes display in the output.

Note: The Host Profile feature in vCenter Server does not save or apply static routes with ESXi 5.0 and 4.x hosts. In ESXi 5.1 and ESXi 5.5, any manually configured static routes are saved or applied using Host Profiles. In order for this functionality to work correctly, the static routes must be added by the process outlined in steps 1-3, then a host profile created from the host. This profile can then be applied to other hosts, which includes the static routes.


Note: In ESXi 5.0 and later, static routes are not persistent across reboots. To ensure that any added static routes are persistent, add the command to the /etc/rc.local file. For more information, see Modifying the rc.local or sh.local file in ESX/ESXi to execute commands while booting (2043564).

 

Additional Information

NOTE: 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 (2081185).

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 192.168.100.0/24 network through the gateway router 192.168.0.1, the host must have a vmkernel port configured in the 192.168.0.0/24 network. Without this vmkernel port, it cannot communicate with 192.168.0.1 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 192.168.100.0/24 network, an error similar to this occurs:

Duplicate route to network x.x.x.x/xx 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. For more information, see VMware AutoDeploy Documentation Center.

For more information, see Troubleshooting vSphere Auto Deploy (2000988).
Adding a static route to an ESX host for an extra Service Console interface
Change to ICMP ping response behavior in ESXi 5.1 and ESXi 5.5
Modifying the rc.local or local.sh file in ESX/ESXi to execute commands while booting