set failover

Purpose

The IP network failover feature provides a dynamic method for selecting and configuring the default gateway for the Digi device server. IP network failover uses of a set of rules and link tests to determine whether a particular network interface can be used to communicate with a specified destination. The user configures these rules, link tests and the priority order of the interfaces.

IP network failover can support the use of Ethernet, Wi-Fi and Mobile (cellular) network interfaces. The available interfaces vary among different Digi products.

IP network failover maintains a network interface list, ordered by the configured failover interface priority, and containing information on the state of the network interface and recent success or failure of the link tests for that interface. The failover status for a network interface is one of the following:

The number shown above for each status value, indicates the priority of that status, used by failover in selecting the interface to use as the default gateway. Status priority 1 is the most suitable for use, with lower priorities considered suitable if there are no interfaces at the highest priority.

When any network interface changes status, the interface list is examined for the interface that has the highest status priority, nearest the start of the list. The highest priority interface with a Responding status is used as the default gateway. If no interface is marked Responding then the highest Up interface is used, and so on.

When IP network failover performs a link test, it adds a temporary static host route to the destination IP address for the link test, using the network interface that the link test is configured to test. The static host route is removed when the link test completes. whether successfully or in failure. Users should be careful to avoid manually configuring static host routes to any of the failover link test destinations, as such host routes may interfere with IP failover's link testing. Static IP routes are configured by the set forwarding command that configures the IP forwarding settings. See set forwarding.

The set network command’s gwpriority (gateway priority) option provides a simpler method for selecting the default gateway. However, if IP network failover is properly configured and enabled, it overrides any gwpriority value that is set. For a description of this non-failover gateway priority selection and information on how to configure it, see set network.

For IP Network Failover status and statistics, use the display failover command, or see the web interface under Administration > System Information > IP Network Failover.

Required permissions

For Digi products with two or more users, permissions must be set to set permissions s-net-failover=read to display IP network failover settings, and set permissions s-net-failover=rw to display and configure IP network failover settings. See set permissions for details on setting user permissions for commands.

Syntax

General options

set failover [state={off|on}]
  [fallback={off|on}]
  [prioritylist=list]

Configure IP network failover settings for a network interface

Note if can be used as an abbreviation for interface.

set failover [interface=interface name] 
  [ifstate={off|on}]
  [testtype={none|ping|tcp}] 
  [maxfailures=1-255] 
  [interval=10-3600]
  [retryinterval=10-3600]
  [norespinterval=10-3600]

ICMP ping link test options

set failover [pingdest1=IPv4 address] 
  [pingdest2=IPv4 address]
  [pingcount=1-10] 
  [pinginterval=time]

TCP connection link test options

set failover [tcpdest1=IPv4 address] 
  [tcpport1=1-65535]
  [tcpdest2=IPv4 address]
  [tcpport2=1-65535]
  [tcpconntimeout=time]

Display current IP network failover settings

set failover

Options

General options

state={off|on}

The IP network failover state; enables or disables the IP Network Failover feature in the Digi device.

fallback={off|on}

Enables or disables fallback to the non-failover default gateway priority method: The fallback option is used if a default gateway cannot be configured by IP network failover. Failure to configure a default gateway could occur if one or more interfaces are not enabled (on) for IP Network Failover use, or if the enabled interfaces are not up or do not have a gateway associated with them.

prioritylist=list

A comma-separated list of network interface names in priority order, used by failover to determine the default gateway. The default gateway is used to route IP packets to an outside network, unless controlled by another route. Default is mobile0,eth0. An empty list value means “Use the default.”

A network interface may have a static gateway configured for it, or it may obtain a gateway from DHCP or other means when the interface is configured. The first interface in this list that supplies a gateway will be used as the default gateway. The default gateway may change as interfaces connect and disconnect, and as failover link tests determine that an interface is providing the desired IP packet routing to a remote network destination.

Options for IP network failover for a particular network interface

ifstate={off|on}

The state for the IP network failover for a particular interface in the priority list of interface names, such as eth0.

testtype={none|ping|tcp}

The type of link test for this interface.

none

No link tests will be used for the network interface. Since no link tests are run, failover is only aware of the Up or Down status of the interface. This limited status information may affect the use of this interface as the default gateway.

ping

ICMP ping link test. For a description of this test, see the ICMP ping link test options.

tcp

TCP connection link test. For a description of this test, see the TCP connection link test options.

maxfailures=1-255

The number of consecutive link test failures before a Not Responding status is reported and a failover action may be taken. The default is 3.

interval=10-3600

The time interval in seconds between the end of a successful link test and the start of the next link test for the network interface. This interval is used only after a successful test. The default is 240.

Shorter intervals verify the link more often, but they also increase the packet traffic over the network interface being tested. The frequency of tests should be considered carefully for network connections such as mobile (cellular) connections, which may be expensive, depending on the service plan in effect with your mobile service provider.

retryinterval=10-3600

The time interval in seconds between the end of a failed link test and the start of the next link test for the network interface. This interval is used after a failed test, but only until the “not responding consecutive failures” threshold (the maxfailures option) has been reached. The default is 240.

A possible strategy is to configure a shorter retry interval than the success interval, to more quickly test the network connection to determine whether it is truly not working or there was just a transient test failure. Determining the validity of the link helps IP network failover determine whether it is necessary to reconfigure the default gateway.

norespinterval=10-3600

The time interval (N) in seconds between the end of a failed link test and the start of the next link test for the network interface. This interval is used after a failed test, but only after the “not responding consecutive failures” threshold (maxfailures option) has been reached. The default is 240.

ICMP ping link test options

The ping test sends ICMP Echo Request packets to the configured destination IP address. If an ICMP Echo Reply is received (ping reply), the link test has successfully demonstrated that the network interface can be used to communicate with the specified destination.

pingdest1=IPv4 address

The primary, or first, destination to ping. The destination must be a valid IPv4 address. If this option is not specified, no primary destination link test will be attempted.

pingdest2=IPv4 address

The secondary, or second, destination to ping. The destination must be a valid IPv4 address. If this option is not specified, no Secondary Destination link test will be attempted.

pingcount=1-10

The maximum number of ping requests to send for a ping link test. When a reply is received, the ping test ends successfully and does not continue to send ping requests. If no ping reply is received after Send Count ping requests have been sent, the link test ends in failure. The default is 5.

pinginterval=1-10

The time interval in seconds between sending ping requests during a ping link test. The ping tests sends a ping request. If no ping reply is received before the Send Interval expires, another ping request is sent. The default is 5.

TCP connection link test options

The TCP Connection Test attempts to establish a TCP connection to the configured destination IP address and port number. If a connection is successfully established, or if the remote host actively rejects (resets) the connection attempt, the link test has successfully demonstrated that the network interface can be used to communicate with the specified destination. If a TCP connection is successfully established, it is immediately closed.

tcpdest1=IPv4 address

The primary, or first, destination to which to establish a TCP connection. The Primary TCP Port is used as the port to which the test connects at the Primary Destination. The destination must be a valid IPv4 address. If the destination is left empty, the device does not attempt a Primary Destination link test.

tcpport1=1-65535

The destination TCP port to use to connect to the Primary Destination address. Default is 80.

tcpdest2=IPv4 address

The secondary, or second, destination to which to establish a TCP connection. The Secondary TCP Port is used as the port to which the test connects at the Secondary Destination. The destination must be a valid IPv4 address. If the destination is left empty, the device does not attempt a Secondary Destination link test.

tcpport2=1-65535

The destination TCP port to use to connect to the Secondary Destination address. The default is 80.

tcpconntimeout=10-60

The timeout in seconds to wait for a TCP test connection to be established or actively refused. The TCP test fails if the connection attempt times out. The default is 30.

Examples

Determine whether IP network failover needs to occur. This command sets a ping test of interface eth0 at an interval of 10 seconds.

#> set failover interface=eth0 ifstate=on testtype=ping interval=10

Next, set the retryinterval option, which sets how long to wait before sending the request again, in this case, ping, and the norespinterval option, which sets (how long to wait for the ping response, for the destination 192.168.250.1, and enable IP network failover.

#> set failover interface=eth0 retryinterval=10 norespinterval=10 pingdest1=192.168.250.1 state=on

These commands set up a ping test, sending a request every 10 seconds to the destination 192.168.250.1.  When ping test fails, the gateway for the interface will change, according to the table in the display failover output for this device:

  Priority  Interface       Status              Gateway         State  Tests
     1      mobile0         2 (up)              10.0.0.1         on      0
     2      eth0            2 (up)              10.30.1.1        on      0

See also