Configuring static routes for vmkernel ports on an ESXi host
search cancel

Configuring static routes for vmkernel ports on an ESXi host

book

Article ID: 308786

calendar_today

Updated On:

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).

Environment

VMware vSphere ESXi 7.0.x
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:
  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_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
  3. When finished, check the host's current routing table with the esxcfg-route -l command. Any static routes display in the output.

 

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