Peering Manager: a source of truth for external BGP sessions

From a documentation tool to a configuration source of truth

Peering Manager is a BGP session management tool, and the README describes its own origin and its current aim in two sentences. It was initially conceived as a way to document Internet Exchange points and peering sessions, and its goal is now to provide a source of truth and configuration management for external BGP sessions of all kind, transit, customers, peering and so on.

That shift is the interesting part. A documentation tool records what a session is supposed to be. A configuration source of truth also generates the configuration, and that second role is where the operational risk lives, because a change in the database becomes a change on a router.

The domain is network operations rather than software, which shapes everything about the project. The topics list names autonomous-systems, bgp, internet, internet-exchange, internet-exchange-points, peer, peering, peering-sessions, routing and transit, and the language is Python with Django as the web framework and PostgreSQL as the database.

The surrounding infrastructure is standard for a Django application of this class. Redis is used for caching and task processing, and the requirements list shows both redis at 8.1.0 and rq at 2.11.0 with django-rq at 4.1.1, which is the standard pairing for background job queues in Django. The project is built with Django 6.1, and the manifest pins it to the 6.1 series with djangorestframework and django-filter alongside it, so the API layer and the query filtering are part of the framework rather than bolted on.

The documentation lives on Read the Docs, and there is a public demo instance at demo.peering-manager.net, which for an infrastructure tool is the fastest way to see whether the data model fits the way you think about peering.

What a session record has to contain, and why the domain is awkward

A BGP session between two networks has a lot of state that is not in the configuration, which is the reason a tool like this exists at all.

An internet exchange point is a physical interconnection where many networks meet. A peering session is the agreement and the resulting BGP adjacency between two of them. On top of that sit transit relationships, where one network carries traffic for another, and customer relationships, where one network is the customer. Each of those is a session, and each has to be described, tracked and eventually configured.

The awkward part of the domain is that the description is not derivable from the router. The router knows its neighbour, its address families and its timers. It does not know which exchange point the link physically runs through, which billing relationship applies, which contact is responsible for the relationship, or when the session was last reviewed. That knowledge lives in email threads and spreadsheets, and a database is where it has to go if it is going to be actionable.

That is why the tool is described first as a documentation project and only later as a configuration source of truth. The document is the durable artefact, and the configuration generation is a consequence of the document being complete and structured. A tool that only pushed configuration would lose the contact and the history, and a tool that only documented would need a second system to produce the configuration.

The other awkward part is that the data is largely public but not identical across sources. PeeringDB holds the authoritative view of who runs which network, which exchanges they are present at and what their policies are, and it is maintained as Git repositories rather than an API, which is why a Git library appears in the dependency list. IX-API is the emerging API standard for the same kind of data, and having both client libraries means the tool can source from either and reconcile the two.

The practical result is a database that knows about networks, exchanges, connection points, sessions and the devices that terminate them, with a history of changes. That is the source of truth, and everything else in the project follows from it.

The dependency list is a map of what it automates

The most informative thing about this project is its dependency list, because every entry corresponds to a device family or a data source it can talk to.

The network automation libraries are the clearest group. napalm at 5.2.0 is the vendor-agnostic network automation library that provides a single API over multiple vendors, and pynetbox at 7.8.0 is the NetBox client, which suggests Peering Manager can read device and site information from an existing NetBox instance rather than requiring you to model your network twice. pyeapi at 1.0.4 is the Arista eAPI client, and junos-eznc at 2.8.2 with the ncclient, paramiko, netmiko, scp and text-formating libraries underneath is the Junos library, so Juniper and Arista devices can be configured directly. The ntc-templates and ttp packages are the parsing layer that turns a device's output into structured data.

The data sources are the other group. pyixapi at 0.3.2 is the IX-API client, and the pyproject includes drf-spectacular with drf-spectacular-sidecar, which is the OpenAPI generation and documentation toolchain, so the REST API is a first-class part of the product rather than an afterthought. dulwich at 1.2.15 is a pure Python Git implementation, and with the peeringdb/ directory in the repository, that is the mechanism for pulling exchange and network data from PeeringDB.

The rest of the stack is what a Django application of this size needs. django-tables2 for the list views, django-taggit for tagging, django-htmx for the partial page updates, django-prometheus for metrics, social-auth-app-django for authentication, psycopg with the pool extra for the database, and Jinja2 alongside Markdown for the templating and documentation rendering.

That last group is worth pausing on, because the combination of a Prometheus exporter, an OpenAPI schema and a webhooks directory at the top level tells you this is designed to sit inside an existing automation stack rather than to be the whole stack.

The directory layout maps onto the network concepts

The top level of the repository is a domain map, and reading it tells you what the application models.

The peering/ directory is the heart of it, holding the peering objects. The bgp/ directory covers the BGP side, the autonomous systems and the sessions themselves. The net/ directory is for the network side, and devices/ is for the routers. There is a peeringdb/ directory for the integration with the PeeringDB data, and an extras/ directory for the pieces that do not fit elsewhere.

The rest is the Django skeleton. peering_manager/ holds the project settings and the top level application, users/ is the authentication and user management, messaging/ is for the notification layer, webhooks/ is for outbound event delivery, templates/ holds the HTML, utils/ holds shared helpers, and core/ and scripts/ hold the shared base and the management commands. project-static/ holds the images and assets, including the SVG logo in the header of the readme. docs/ contains the source for the Read the Docs build, which is driven by mkdocs.yaml, and manage.py is the Django entry point.

The requirements file is fully pinned, with every transitive dependency at an exact version, down to annotated-types at 0.8.0 and asgiref at 3.12.1, and it includes the platform-specific markers for PyPy and for Windows. That is the right way to pin a deployment of an infrastructure tool, because the difference between a working and a broken environment here is a specific version of a network library, and an unpinned install would drift under you.

A few entries carry the reason they are pinned. psycopg-binary and psycopg-pool are pinned separately from psycopg itself, and there is a tzdata pin marked for Windows only, which tells you the tool is deployed on Windows as well as on Unix.

Webhooks, metrics and the two discussion channels

Three integration points are visible in the tree and in the dependency list, and they are what you would hook into if you wanted to build on this.

The webhooks/ directory at the top level means outbound event delivery is a first-class feature, and combined with the drf-spectacular stack and the Prometheus exporter, the application is designed to sit inside a pipeline that reacts to state changes rather than being the only place the data lives.

The README points at two discussion venues with different purposes. GitHub Discussions is described as the discussion forum hosted by GitHub, ideal for Q&A and other structured discussions, and the NetDev Community Slack is the real-time chat, best for unstructured discussion or just hanging out, in the #peering-manager channel.

The support model around the project is also worth noting. The README says you can ask for features, give ideas for future development, open issues and contribute code with pull requests and patches, and you can support development by donating some coins. There is a sponsors section in the readme too, thanking the sponsors for believing in the project, which is the pattern of a project that has found a sustainable funding model.

The release naming is distinctive. The tags are titled with a Roman numeral, Version 1.11.0 | MARK I, and the same MARK I appears on 1.10.4 and 1.10.3. Whatever the numeral is counting, it signals that a batch of releases share a common marking, which for a tool that operators upgrade on their own schedule is a useful way to group changes.

The current versions tell you where the project is. The manifest says 1.11.1-dev, and the tagged releases are 1.10.3 in February 2026, 1.10.4 in March and 1.11.0 in September, with the last push on 2026-10-14.

Editorial conclusion

Peering Manager suits a network operator running many external BGP sessions who needs the intent of each session recorded in a database rather than in a wiki page, and the per-vendor configuration generation through NAPALM is what turns documentation into automation. It does not suit you for internal peering, since the scope is external sessions, and it does not replace a routing platform. Before you deploy it, read the requirements file rather than the summary, because the network device libraries alone pull in a large tree, and check the version numbering, since 1.11.1 is marked as a development version in the manifest while the latest tagged release is 1.11.0.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. peering-manager/peering-manager on GitHub
3. Project website
4. README
5. Releases