OpenGNB: a peer to peer virtual LAN for NAT traversal

A virtual LAN, without a hub in the middle

OpenGNB is an open source P2P decentralized Software Defined Virtual Network with extreme intranet penetration capability, and the way it puts it is that it allows you to combine your company and home networks into a direct access LAN.

The four features it lists are the whole pitch. Intranet penetration P2P VPN with no public IP required. Extreme link capability, described in the README as unlimited speed effects. Data security, with reliable authentication between GNB nodes based on elliptic curve digital signature. And multi-platform support.

That last one has a specific reason behind it. GNB is developed in C and does not need to refer to third-party library files when compiling, which the README presents as the reason it can be ported to the popular operating systems. The supported list is Linux, Windows, macOS, FreeBSD, OpenBSD, NetBSD, Raspberry Pi and OpenWRT, and the claim is that the range runs from a server environment down to an OpenWRT router with only 32M of memory.

The project is written in C, licensed under GPL-3.0, and the most recent releases are 1.6.8 on 2026-08-12, 1.6.7 two days earlier and 1.6.6 on 2026-07-06.

One caveat about the documentation itself, stated at the top of the README. The communication protocol of version 1.6.0 has been upgraded and is not compatible, and most of the article is translated by Google Translate from the Chinese version of the OpenGNB User Manual, with the Chinese version being the authoritative one. For a project with a protocol break in it, that is a detail worth taking seriously.

Five forwarding topologies, and the one you probably want

The README illustrates the forwarding models with a set of Mermaid diagrams, and reading them together is the clearest explanation of what the software does.

The first is standard VPN payload forwarding, where a client in one LAN sends its payload to a VPN server, which forwards it to a client in the other LAN. That is the familiar model, and it needs a server in the middle.

The second is the point-to-point NAT traversal model. The two nodes exchange addresses through a GNB public index node, and once they have each other's address, the payload flows directly between them. The index is used for the address exchange, not as a relay for the traffic. This is the topology the project is really about, because it removes the middle server from the data path.

The third is relay forwarding, where the payload hops through a chain of nodes, drawn as several parallel routes between the two endpoints. The fourth is unified forwarding, where one node reaches another through several intermediate nodes at once. The fifth is forwarding over TCP, where a UDP payload is tunnelled through a TCP leg, drawn as UDP from node A to an upd_over_tcp component, then TCP across the internet, then UDP again to node B.

That last one exists because some networks break UDP, and a TCP tunnel will get through where a UDP hole punch will not. It is the usual fallback in this class of software, and knowing it is there is more useful than knowing it is fast.

Lite mode trades the key exchange for convenience

The authentication story has two layers, and the README is clear about which one the quick start uses.

The full model relies on elliptic curve digital signature for reliable authentication between GNB nodes, which is what gives you a node-to-node identity that is not just a shared secret.

Lite mode is the demonstration path, and the README says the security will be much less modular, which is a slightly odd way of putting it. The substance is in the next sentence: in lite mode, asymmetric encryption is not enabled, and only the passcode and the node id generate the encryption key. So the key is derived from a shared secret plus an identifier, with no signature involved, and the README says to use it for a quick trial rather than in practice.

The passcode itself deserves attention, because it has a scope that surprises people. It is a 32-bit hexadecimal string with a length of 8 characters, represented as 0xFFFFFFFF or FFFFFFFF, and under a public index the same passcode means the same GNB node, which means the same virtual network. The README uses 12345678 for the demonstration and warns against it in real use, for a specific reason: another user with the same passcode can cause a communication failure.

So the passcode is not a password in the usual sense. It is a network membership token, and choosing a common one puts you in someone else's network.

Building it on Linux, and the four binaries you get

The quick start is a compilation step and a deployment step, and the compilation is one command on Linux.

git clone https://github.com/gnbdev/opengnb.git
cd opengnb
make -f Makefile.linux install

After compiling, you get the gnb, gnb_crypto, gnb_ctl and gnb_es files in the opengnb/bin/ directory. The README then says to copy those four to host A and host B respectively, so the deployment step is a file copy rather than an installation.

The build files in the repository reflect the platform list in the feature description, with a Makefile for Darwin, for FreeBSD, for Linux, for NetBSD, for OpenBSD, for mingw x86_64 and for OpenWRT, plus shared include files and a couple of OpenWRT specific variants, one of them a local build. There are also libs/, scripts/, src/, docs/ and an examples/ directory with a node_config_example.

The note about the repository address is worth flagging for anyone following along. The clone URL in the quick start points at the gnbdev organisation rather than the opengnb organisation that hosts the repository this README comes from, so the project has moved, and the two names are both in circulation.

Two nodes, one virtual subnet, and a tun device that appears

Starting a node is a single command, and the parameters are worth understanding one at a time.

On host A, executed with root, the node is given a node id of 1001, an address of the public index at 101.32.178.3 on port 9001, multi-socket enabled, and the passcode.

gnb -n 1001 -I "101.32.178.3/9001" --multi-socket=on -p 12345678

The second node on host B differs only in the node id, 1002, with the same index address and the same passcode.

gnb -n 1002 -I "101.32.178.3/9001" --multi-socket=on -p 12345678

After a successful start, running ip addr on the host shows the result, and this is where the project stops being a diagram and becomes an interface. A tun device named gnb_tun appears carrying 10.1.0.1/16 on host A, with 10.1.0.2/16 on host B, along with the usual IPv6 and link local addresses.

From there the test is the oldest one in the book. If the NAT traversal worked and no firewall interfered, the two hosts can ping each other's virtual address.

ping 10.1.0.2

The reason the virtual addresses look like an ordinary private subnet is the point of the whole design. Everything above the tun device, routing, firewall rules, services, monitoring, is unchanged from what it would be on a physical LAN, which is what makes it usable rather than merely impressive.

The ecosystem around it, and the state of the project

The README points at two companion projects that are worth knowing about, because they tell you what kind of project this is. There is an easy-to-deploy cross-platform OpenGNB management platform, opengnb-admin, and an easy-to-deploy OpenGNB GUI, opengnb-gui. Both are separate repositories, and their existence says that running a GNB network is an operational task with a control plane, not just a binary you start on two machines.

The documentation situation is the weak point. The English README is a Google translation of the Chinese original, and the Chinese version of the user manual is the one that governs. There is a docs/ directory in the repository, so a reader of the English text is working from a translation of a subset.

The protocol break is the other thing to plan around. The version 1.6.0 upgrade is described as not compatible, which in a mesh means every node has to move together. A network with nodes on older and newer protocol versions will not interoperate, and there is no negotiation described in the README, so upgrading is a coordinated operation rather than a rolling one.

The releases themselves are frequent. Three releases in five weeks, 1.6.6 on 2026-07-06, 1.6.7 on 2026-08-10 and 1.6.8 on 2026-08-12, and the last push to the repository is on 2026-08-12. For a project with a protocol break and a translation-only English documentation set, that cadence is the most reassuring thing in the repository.

Editorial conclusion

OpenGNB fits a network engineer who needs a routed link between sites that cannot have a public address, and who wants the peers to find each other without a permanent hub in the middle. It does not fit a team that needs a vendor-supported product, since the project is community run and the documentation is a translation of a Chinese manual, and it does not fit a deployment that mixes 1.6 nodes with older ones, because the protocol was upgraded incompatibly. Verify three things before you build a node: that every node on the network runs the same protocol generation, that you are not planning to rely on lite mode for anything you care about securing, since lite mode drops asymmetric encryption and derives the key from the passcode and the node id, and that the passcode you choose is not one other user has chosen, because under a public index the same passcode means the same virtual network and a collision breaks your connectivity.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. opengnb/opengnb on GitHub
4. README
5. Releases