google/seesaw: an LVS load balancer with a two-node failover pair

What Seesaw v2 is for and who should run it

Seesaw v2 is a load balancing platform built on Linux Virtual Server. The README states that it covers basic load balancing for servers on the same network through to anycast, Direct Server Return, multiple VLANs and centralised configuration. The design goal named first is reliability and ease of maintenance.

The audience is narrower than that sentence suggests. A Seesaw cluster requires exactly two Seesaw nodes, physical or virtual, and each node needs two network interfaces: one for the host itself and one for the cluster VIP. All four interfaces must sit on the same layer 2 network. That is a hardware and topology commitment, not a software install. If you are deploying one load balancer on a cloud instance and want it to work across subnets, this project is the wrong shape.

The people who benefit are operators already comfortable with LVS and IPVS, who want the virtual service and real server definitions kept in one place and pushed to both nodes, and who want failover between the pair handled by the platform rather than by a script they wrote. The README notes that this is not an official Google product, so there is no support contract behind it.

The watchdog, the five components and the floating VIP

The architecture is visible in the repository layout and the troubleshooting section. Six binaries are installed: seesaw_cli, seesaw_ecu, seesaw_engine, seesaw_ha, seesaw_healthcheck and seesaw_ncc. Five of them run under seesaw_watchdog, which starts and restarts the others. The CLI is separate and is installed as /usr/bin/seesaw.

Configuration is split in two. Each node has /etc/seesaw/seesaw.cfg, which describes the node and its peer. The cluster-wide definition lives in /etc/seesaw/cluster.pb, a text-based protobuf. The README lists the minimal keys for seesaw.cfg: anycast_enabled, name, node_ipv4, peer_ipv4 and vip_ipv4. The VIP floats between the two nodes and is only active on the current master, and it must be allocated in the same netblock as both the node and peer addresses.

cluster.pb carries a seesaw_vip entry and two node entries. Every service you balance needs its own vserver entry, with one or more vserver_entry sections for each port and protocol pair, plus backends and healthchecks. The protobuf definition in pb/config/config.proto is where the full schema lives; the README points there rather than restating it. That is a deliberate choice: the config format is the interface, and the .proto file is the documentation.

The ha component is what needs raw sockets, which is why the install step sets file capabilities on seesaw_ha and seesaw_healthcheck instead of running everything as root.

Installing Seesaw v2 from source on Debian or Ubuntu

There is no package to install. The README describes a source build. On a Debian or Ubuntu style system, the build dependencies are installed first, including the libnl development packages, because Seesaw has a compile and runtime dependency on libnl.

apt-get install golang
apt-get install libnl-3-dev libnl-genl-3-dev

The README warns that a distribution Go older than 1.18 may need a newer release from golang.org/dl. Once the toolchain is in place, build and install from the repository root:

make test
make install

make install runs go install for each of the seven binaries. They land in ${GOPATH}/bin with a seesaw_ prefix. The README then lays out the on-disk layout and copies the binaries into place, with the CLI renamed to seesaw in /usr/bin:

SEESAW_BIN="/usr/local/seesaw"
SEESAW_ETC="/etc/seesaw"
SEESAW_LOG="/var/log/seesaw"

install -d "${SEESAW_BIN}" "${SEESAW_ETC}" "${SEESAW_LOG}"
install "${GOPATH}/bin/seesaw_cli" /usr/bin/seesaw

for component in {ecu,engine,ha,healthcheck,ncc,watchdog}; do
  install "${GOPATH}/bin/seesaw_${component}" "${SEESAW_BIN}"
done

Raw socket access is granted with setcap rather than by running the daemons as root. The README notes that setcap comes from the libcap2-bin package on Debian and Ubuntu.

/sbin/setcap cap_net_raw+ep "${SEESAW_BIN}/seesaw_ha"
/sbin/setcap cap_net_raw+ep "${SEESAW_BIN}/seesaw_healthcheck"

For a first real use, copy the example files and edit them. The README points at etc/seesaw/seesaw.cfg.example for the node file and etc/seesaw/cluster.pb.example for the cluster file, which contains a seesaw_vip entry and two node entries. Set name, node_ipv4, peer_ipv4 and vip_ipv4 in seesaw.cfg, then add a vserver for the service you want to balance. On an upstart system, restart seesaw_watchdog starts the watchdog, which starts the rest. Then run seesaw for the interactive prompt and type ? for the command list. The README lists config reload, failover, show vservers and show vserver <name> as the top-level commands worth knowing. If something is missing, check /var/log/seesaw, for example seesaw_engine.log.

Where Seesaw v2 stops being the right tool

The two-node, four-interface requirement is the first hard boundary. Every interface must be on the same layer 2 network. A deployment that spans availability zones, or that runs the load balancer as a single instance behind a cloud provider's floating IP, does not match the model the README describes. You would be fighting the design rather than using it.

Anycast has its own constraint. The README states that Quagga must be installed and configured, with BGP peers accepting host-specific routes advertised from the Seesaw nodes within the anycast range, and that this range is currently hardcoded as 192.168.255.0/24. Hardcoded means exactly that: if your addressing plan does not fit that block, anycast is not available to you without changing the source.

Configuration is file-based and reloaded, not dynamically discovered. There is no mention of a Kubernetes integration, a service registry, or a REST API. The interface is a protobuf file on disk and an interactive CLI. Teams that expect services to appear as pods come and go will find the model manual.

The README also does not document rollback of a configuration reload, nor does it describe what happens to established connections during a failover. Those are questions to answer from the code in ha/ and engine/ before trusting the pair in production.

Seesaw v2 compared with HAProxy and keepalived

The closest conventional stack is HAProxy for the proxy layer plus keepalived for VIP failover. The difference is where the traffic handling happens. HAProxy terminates and re-establishes connections in user space, so it can inspect and route on HTTP headers, and it runs happily on one machine. Seesaw does not proxy. It programs Linux Virtual Server through IPVS, so packets are forwarded at layer 4 and Direct Server Return can send replies straight from the backend to the client.

That buys throughput and keeps the load balancer out of the return path, at the cost of layer 7 awareness and of the topology requirements above. With HAProxy you can run a single node and add a second later. With Seesaw the second node is part of the definition of the cluster from the start.

keepalived overlaps with the ha component: both manage a floating VIP with VRRP-style failover. keepalived can also drive IPVS directly, which makes it a lighter option if all you want is a VIP and a handful of virtual services. Seesaw's argument over that is centralised configuration of vservers, backends and healthchecks in one protobuf, plus the ecu, engine and ncc components that keep both nodes in agreement. If your configuration is small and static, that machinery is overhead you would not miss.

Maintenance, build dependencies and licence

The repository was last pushed on 2026-07-11 and is not archived, so it is not abandoned. It is also not a project with a release cadence you can plan around: no recent releases were retrieved, and the README does not describe a versioning or upgrade policy. Upgrades mean pulling the source, rebuilding with make install and reinstalling the binaries, then restarting the watchdog. There is no documented migration path for cluster.pb between versions, so a schema change in pb/config/config.proto is something you would discover by reading the diff.

The dependency surface is small and listed in go.mod: goconf for config parsing, glog for logging, the protobuf runtime, miekg/dns for the ncc component, fsnotify, godebug and golang.org/x/crypto for SSH. The module declares go 1.25.0. Because libnl is a compile and runtime dependency, the build is not a pure Go build and will not cross-compile without the C library present.

Seesaw v2 is licensed under Apache-2.0. That permits commercial use and modification, and it includes a patent grant. It also requires that you preserve the licence and notices, and it does not grant trademark rights, which matters because the README states this is not an official Google product. This is a description of the licence text, not legal advice; check it against your own distribution obligations.

Editorial conclusion

Adopt Seesaw v2 if you already run Linux Virtual Server and want centralised cluster configuration, anycast VIPs and DSR without writing your own control plane. Do not adopt it if you cannot give the cluster two dedicated nodes, four interfaces on the same layer 2 network, and root access to set raw socket capabilities. Before deploying, read pb/config/config.proto to confirm that vserver, backend and healthcheck entries express the topology you need, and verify that your BGP peers accept host routes inside 192.168.255.0/24 if you plan to use anycast.

Frequently asked questions

Official sources

1. google/seesaw on GitHub
2. Issues
3. License: Apache-2.0
4. README