Link is not Keepalived - Virtual IP manager backed by etcd
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
ip Not etiennem ... Dec 10, 2018
mocks_sig.json Fix Client interface Feb 13, 2019


Build Status

Link is not Keepalived

LinK is a networking agent that will let multiple hosts share a virtual IP. It chooses which host must bind this IP and inform other members of the network of the host owning this IP.

The IP owner election is performed using etcd lease system and other hosts on this network is informed of the current IP owner using gratuitous ARP requests (see How do we bind IPs?).

To ease the cluster administration, LinK comes with it's own CLI.



Project goals

  1. KISS: our goal is to follow the UNIX philosophy: "Do one thing and do it well". This component is only responsible of the IP attribution part. It will not manage load balancing or other higher level stuff.
  2. If an IP is registered on the cluster there must always be at least one server that binds the IP


** No central manager** Each agent only have knowledge of their local configuration. They do not know nor care if other IP exists or if other hosts have the same IP configured. The synchronization is done by creating locks in etcd.

** Fault resilience** If for any reason something went wrong (lost connection with etcd) LinK will always try to have at least one host this means that if one agent fails to contact the etcd cluster it will take the IP.


In order to be able to run LinK, you must have a working etcd cluster. Installation and configuration instructions are available on the etcd website.

LinK uses etcd v3 API. So you'll need etcd version 3.0.0 or higher.

The easiest way to get LinK up and running is to use pre-build binary available on the release pages.


LinK configuration is entirely done by setting environment variables.

  • INTERFACE: Name of the interface where LinK should add and remove IPs.
  • USER: Username used for basic auth
  • PASSWORD: Password used for basic auth
  • PORT (default: 1313): Port where the LinK HTTP interface will be available
  • ETCD_HOSTS: The different endpoints of etcd members
  • ETCD_TLS_CERT: Path to the TLS X.509 certificate
  • ETCD_TLS_KEY: Path to the private key authenticating the certificate
  • ETCD_CACERT: Path to the CA cert signing the etcd member certificates


  • GET /ips: List all currently configured IPs
  • POST /ips: Add an IP
  • GET /ips/:id: Get a single IP
  • DELETE /ips/:id: Remove an IP
  • POST /ips/:id/lock: Try to get the lock on this IP

How do we bind the IPs?

To add an interface LinK adds the IP to the configured interface and send an unsolicited ARP request on the network (see Gratuitous ARP).

This is the equivalent of:

ip addr add MY_IP dev MY_INTERFACE

To unbind an IP we will just remove it from the interface.

This is the equivalent of:

ip addr del MY_IP dev MY_INTERFACE

State machine

Each IP can be in any of these three states:

  • ACTIVATED: This machine owns the IP
  • STANDBY: This machine does not own the IP but is available for election
  • FAILING: Health checks for this IP failed, this machine is not available for election

At any point five types of events can happen:

  • fault: There was some error when coordinating with other nodes
  • elected: This machine was elected to own the IP
  • demoted: This machine just loosed ownership on the IP
  • health_check_fail: The health checks configured with this IP failed.
  • health_check_success: The health checks configured with this IP succeeded.

This is what the state machine looks like:

Sate Machine

Dev environment

To make it work in dev you might want to some a dummy interfaces:

modprobe dummy
ip link add eth10 type dummy
ip link set eth10 up
ip link add eth11 type dummy
ip link set eth11 up
ip link add eth12 type dummy
ip link set eth12 up

The script can be executed as root to automatically do that.