OpenR is Facebook's interior routing protocol, and the build tells you what it costs

Two Facebook networks are the reason OpenR exists

OpenR, short for Open Routing, is described as Facebook's internally designed and developed Interior Routing Protocol and platform. The key word in that description is interior, which in network engineering means routing inside a single administrative domain rather than between domains.

The original target was Terragraph, the mesh network Facebook built from commodity wireless units, and that context explains much of the design. A mesh has thousands of nodes with changing adjacencies, which is a different routing problem from a switched backbone. The documentation then notes that OpenR's flexible design led to its adoption in other networks, including Facebook's WAN network, Express Backbone.

So the same platform ended up serving both a wireless mesh and a WAN, which is the strongest evidence in the repository that the design was not narrowly tied to one topology.

The project itself is a platform, not just a protocol, and the repository description calls it a distributed platform for building autonomic network functions. The word autonomic is doing real work there: the intent is that routing decisions are made by the network itself rather than by an operator issuing configuration. That is also where the difficulty lies, because a self-directing routing system has to be correct before anyone can debug it.

The README is deliberately short and points outward, to the extensive documentation hosted at openr.readthedocs.io, to a Developer Guide, and to an examples directory with working code such as KvStorePoller and SetRibPolicyExample.

The dependency list is the real specification

OpenR requires a specific set of system dependencies, and the list is short enough to read in one pass: cmake, gflags, gtest, libsodium, zstd, folly, fbthrift and re2-devel.

folly and fbthrift are the two that carry the most weight in practice. fbthrift is the Thrift implementation that provides the RPC layer OpenR's control interfaces are built on, and folly is the C++ library that supplies the concurrency primitives and container types the codebase leans on. Building them means building a large Facebook C++ stack, which is why the README warns that some library dependencies need a newer version than the default package manager provides and are therefore compiled from source instead.

The remaining entries split into ordinary system libraries and tooling. gflags handles command line flags, gtest the unit tests, libsodium the cryptography, zstd the compression, re2-devel the regular expression engine, and cmake drives the build. The CMakeLists.txt at the repository root, along with ThriftLibrary.cmake and FBGenCMakeBuildInfo.cmake, is what ties those together.

The install step gives a good picture of the resulting layout. Binaries, generated Thrift libraries, source and generated Thrift headers go under /opt/facebook/openr, and Python modules land in the Python site-packages directory. One architectural decision stands out: OpenR executables and tests link the granular component libraries directly, and the build does not install a monolithic OpenR implementation library. Anyone who expects a single libopenr to link against will not find it.

One shell script compiles the whole stack

The build documentation gives you a script first and the manual steps second, which tells you the manual path is the fallback. The script lives at build/build_openr.sh and has been tested on Ubuntu LTS releases. It uses gendeps.py to install the necessary dependencies and then compiles and installs the OpenR C++ binaries, and the README asks you to modify it as needed for your platform.

# Install dependencies and build openr
bash ./build/build_openr.sh

Running the test suite is a separate step with its own invocation, and the script notes that some tests require sudo privileges.

# To Run tests (some tests requires sudo privileges)
python3 build/fbcode_builder/getdeps.py test \
  --src-dir=. \
  --project-install-prefix openr:/opt/facebook \
  openr

For iterating on your own changes, the README points you at plain cmake and make from the build directory, running cmake ../openr and then make. That is the standard cmake workflow, and it is much faster than re-running the full dependency script once the dependencies are in place.

The repository root is organised around this. The build directory holds the gen tool with the scripts for building the project, and the openr directory holds the source. The presence of fbcode_builder in the test command shows that OpenR still builds through Facebook's internal build tooling even though it lives on GitHub.

Docker packaging exposes the Thrift port and needs a config bind mount

OpenR now has a Dockerfile, and it uses gendeps.py to build all dependencies plus OpenR itself. The base image is ubuntu:24.04 with the development tools installed, the source copied into /src, and the OpenR build run inside the image.

docker build --network host .

The network host flag is not optional decoration. The Dockerfile exposes the OpenR Thrift port, declared as 2018/tcp, and the running container needs to reach other OpenR instances, so host networking keeps the addressing simple.

Running it requires you to supply configuration. The documentation says you can specify a config file by bind mounting a directory with an openr.cfg file in /config, and the container run is given as:

docker run --name openr --network host openr_ubuntu

There is a naming inconsistency worth noting. The Dockerfile copies example_openr.conf into /etc/openr.conf, while the README text says the OpenR binary will look for /config/openr.conf in the bind-mounted directory. The two files have different names, so the config you bind mount and the sample shipped in the image are not the same artefact, and you will need to check which path the binary actually reads in your build.

The container image also installs the breeze CLI. The Docker build runs build/build_breeze.sh to generate modern Thrift Python bindings, install the matching fbthrift-python runtime, and install the breeze CLI in an isolated virtual environment, with the openr/py/setup.py script packaging the staged source and generated bindings. The README is explicit that this script is not a standalone source-tree build entry point, so do not expect to run setup.py directly in a fresh checkout.

Linux only, and the C++20 floor that decides your toolchain

The requirements section is where most evaluations stop. The project has been tried on Ubuntu 24.04 LTS, with earlier versions no longer supported, and on CentOS Stream 9. It should work on all Linux based platforms. There is no Windows or macOS path mentioned anywhere in the build documentation.

The compiler requirement is C++20 or higher, and Python 3.10 or higher is needed for the Breeze CLI. That is a real constraint on older distributions whose default compilers predate C++20.

The consequence is that you are building on a modern base image, and the Docker path handles the package versions for you. The Dockerfile pulls in build-essential, git, libssl-dev, m4, patchelf, python3-dev, python3-pip, python3-setuptools, python3-venv and python3-wheel, then removes the build tools again at the end so the final image stays small.

Another detail in the Dockerfile explains a change that would otherwise puzzle you. The CMakeLists builds routing_policy.thrift from configerator/structs/neteng/config, and that directory must be present in /src for the build to work. It was previously available only because getdeps cloned the full upstream repository, so the image now copies the configerator directory explicitly. The configerator directory at the repository root is the source of those config structures, which is the closest thing in this project to a declarative description of OpenR's own configuration.

For the Python side, the packages land in site-packages and the CLI is called breeze. The documentation at openr.readthedocs.io covers the CLI in detail, and the Developer Guide at openr/docs/Developer_Guide/DeveloperGuide.md covers contribution practice, including the requirement that any single change should be well tested for regressions and version compatibility.

Where OpenR is the wrong tool

The clearest case for not using OpenR is a network that does not resemble the ones it was built for. The design targets a Terragraph style mesh first and a WAN backbone second, with an emphasis on autonomic behaviour that assumes an operator who wants the network to route itself. A small campus or lab network wants a conventional protocol with a documentation trail and a debugging story, not a distributed platform for autonomous functions.

The second case is anything outside Linux with a modern toolchain. There is no supported Windows path and no macOS path in the build documentation, and the C++20 floor rules out older distributions without backported toolchains.

The third case is operational maturity. The published release history stops in 2019. The three most recent releases listed for the repository are rc-20191208-10906 from December 2019, rc-20191110-10905 from November 2019 and rc-20191020-10905 from October 2019. That is a release cadence that effectively ended years before the current work in the tree, even though the repository itself is not archived and the last push was on 2026-10-21.

That gap is the thing to weigh. The source is current and the licence is permissive, but the tagged artifacts a production operator would pin to are old. The repository does carry a CHANGELOG.md at the root, which is where you would look to see whether the recent commits are bug fixes, platform refreshes or larger changes to the routing logic itself.

The licence itself is MIT, which is permissive enough for commercial use and modification with attribution. The examples directory has its own LICENSE-examples file, which is worth reading if you plan to copy the sample applications into a product.

Two ways to get a build, and what each one costs

For a project this size there is a real choice between approaches, and OpenR offers both rather than pushing one.

The first is the script plus getdeps route. bash ./build/build_openr.sh resolves and compiles the dependency stack, including the libraries whose versions are newer than what the distribution ships, and the getdeps.py test invocation runs the suite. The cost is time and a large dependency tree that you did not choose: folly, fbthrift and their own requirements get compiled on your machine. The benefit is that the result matches what Facebook's build system produces, including version choices that the README refuses to pin in prose.

The second is the Docker route. docker build --network host . produces an image with the same dependencies built inside it, the breeze CLI installed, and the Thrift port exposed. The cost is the container boundary: host networking, a bind-mounted config directory, and the fact that the image runs a helper script as its command rather than the OpenR binary directly. The benefit is that the toolchain and the OS version are fixed for everyone who uses the image, which is exactly what you want when the underlying dependency stack keeps moving.

Between them sits the third option, plain cmake ../openr and make from the build directory, which is the right choice once you are editing OpenR itself rather than evaluating it.

Whichever route you take, the configuration remains the same shape: the configerator directory supplies the config structures, an example_openr.conf sits at the repository root as the starting point, and the running process reads its configuration from a file.

Editorial conclusion

OpenR makes sense if you are running a Linux network that resembles Facebook's own, that is, a Terragraph style mesh or a backbone of switches, and you want the same routing platform software rather than a general purpose routing stack. It is the wrong choice for a small lab network, for a Windows host, or for anyone who needs a vendor support contract, since the code was designed inside one network operator's environment. Before you commit, verify the build on Ubuntu 24.04 LTS or CentOS Stream 9 with a compiler supporting C++20, then confirm that bash ./build/build_openr.sh completes, since that script compiles several dependencies from source rather than taking the distribution packages.

Frequently asked questions

Official sources

1. facebook/openr on GitHub
2. Issues
3. License: MIT
4. README
5. Releases