Difference between revisions of "Cluster"

From VyOS Wiki
Jump to: navigation, search
Line 1: Line 1:
{{Migrated | url = https://vyos.readthedocs.io/en/latest/clustering.html}}
The cluster feature allows 2 vyos routers to share IP adresses and various services.   
The cluster feature allows 2 vyos routers to share IP adresses and various services.   

Latest revision as of 19:36, 11 July 2019

Warning sign.png This page is migrated to Readthedocs .
Information found on this page is migrated to readthedocs and information found here could be outdated or misleading. https://vyos.readthedocs.io/en/latest/clustering.html
For a complete status of all migrations, see Project:Migration

The cluster feature allows 2 vyos routers to share IP adresses and various services.

It is more powerful than VRRP as one can have a service linked to an IP address on cluster members. For exemple, you can't have vpn service shared on 2 hosts using VRRP as tunnel won't come up when a failover occurs.

Configuration commands

   dead-interval <int> # Interval after which a node is considered dead after missing heartbeats (milliseconds)
   keepalive-interval <int> # Time interval between heartbeat packets (milliseconds)
   mcast-group <x.x.x.x> # Multicast group for sending/receiving heartbeat packets
   monitor-dead-interval # Interval after which a monitor node is considered dead (milliseconds)
   pre-shared-secret <text> # Pre-shared secret for authentication between cluster nodes [REQUIRED]
   interface <text> # Interface(s) for sending/receiving heartbeat packets [REQUIRED]
   group <text>
      auto-failback <boolean> # Fail back to primary node if it recovers from failure
      primary <text> # Host name of the primary node [REQUIRED]
      secondary <text> # Host name(s) of the secondary node(s) [REQUIRED]
      monitor <x.x.x.x> # IP address(es) for monitoring connectivity
      service # IP address(es) or service name(s) in this resource group [REQUIRED]
         <x.x.x.x/cidr/interface name> # IP address (with subnet mask length and interface) to be clustered
         <service name> # Name of system service to be clustered


There is a general cluster configuration for VyOS, and then there is configuration for a cluster group.

general cluster configuration

In the general cluster configuration the network interfaces used for monitoring and negotiation of the cluster health is defined. Additionally, the communication interval settings, multicast group (for sending/receiving heartbeat messages), and pre-shared secret used in this monitoring is defined.

  • set cluster <parameter> <value>
    • dead-interval <milliseconds> (Optional; default=20000 or 20 seconds)
    • interface <interface> (Required; Multiple interface allowed)
    • keepalive-interval <milliseconds> (Optional; default=5000 or 5 seconds)
    • mcast-group <ipv4> (Optional; default=
    • monitor-dead-interval <milliseconds> (Optional; default=20000 or 20 seconds)
    • pre-shared-secret <string> (Required)

cluster group configuration

For the cluster group configuration, the group name must be defined before the groups configuration can be set (See Example below). After the group name is defined, the specific service to be clustered between primary and secondary nodes is configured.

  • set cluster group <groupname>
    • <groupname> (Required; String)
  • set cluster group <groupname> <parameter> <value>
    • auto-failback <(true|false)> (Optional; default=false)
    • monitor <ipv4> (Optional; Multiple monitor allowed)
    • primary <hostname> (Required)
    • secondary <hostname> (Required)
    • service <(ipv4/cidr/interface|service-name)> (Required; Multiple service allowed)

review cluster status

 vyos_{a,b}# show cluster status


For this example, a cluster will be configured to serve an IP Address on an interface as the service.

In this configuration, the following is true:

  • The primary node is named: vyos_a
  • The secondary node is named: vyos_b
  • egress IP route:
  • vyos clustered IP:
  • vyos_a IP address is
  • vyos_b IP address is

Set the hostnames on each node. The host name is used to identify each node in the cluster.

 vyos_a# set system host-name vyos_a
 vyos_b# set system host-name vyos_b

Set the local IP addresses on each node.

 vyos_a# set interfaces ethernet eth1 address
 vyos_b# set interfaces ethernet eth1 address

Set the cluster configuration on both nodes. This is the same configuration for both node a and node b.

 vyos_{a,b}# set cluster dead-interval 1100
 vyos_{a,b}# set cluster interface eth1
 vyos_{a,b}# set cluster keepalive-interval 500
 vyos_{a,b}# set cluster mcast-group
 vyos_{a,b}# set cluster monitor-dead-interval 1100
 vyos_{a,b}# set cluster pre-shared-secret cluster1234
 vyos_{a,b}# set cluster group vyosabcluster

Configure the cluster group settings. This is the same configuration for both node a and node b.

 vyos_{a,b}# set cluster group vyosabcluster auto-failback false
 vyos_{a,b}# set cluster group vyosabcluster monitor
 vyos_{a,b}# set cluster group vyosabcluster primary vyos_a
 vyos_{a,b}# set cluster group vyosabcluster secondary vyos_b
 vyos_{a,b}# set cluster group vyosabcluster service

Commit and save the new configuration.

 vyos_{a,b}# commit
 vyos_{a,b}# save

Use Scenario

The clustering could be configured to serve a specific IP address between the primary and secondary nodes for a VPN service. When a failover occurs from one node to the next, the TCP connections will be reset unless Stateful Failover is configured. VyOS's stateful failover can be used to fail over TCP sessions using Clustering (as documented on this page), and VRRP. If configuring VyOS's NAT, there are additional considerations when configuring stateful failover.