{ "product": "Cenvero Stratum", "generated_at": "2026-08-03T07:17:07+00:00", "format": "cenvero-docs-v1", "document_count": 1, "documents": [ { "slug": "networking/overview", "title": "Networking Overview", "category": "Networking", "url": "https://stratum.cenvero.com/docs/networking/overview", "headings": [ { "level": 1, "text": "Networking Overview" }, { "level": 2, "text": "The two bridges" }, { "level": 2, "text": "Networks as L2 segments" }, { "level": 3, "text": "What it does not do" }, { "level": 2, "text": "Worked example: two servers talking over a private network" }, { "level": 3, "text": "1. Create the network" }, { "level": 3, "text": "2. Claim an endpoint for each server" }, { "level": 3, "text": "3. Put each server on the workload bridge with its MAC" }, { "level": 3, "text": "4. Give each server its address" }, { "level": 3, "text": "5. They can talk" }, { "level": 3, "text": "Removing it" }, { "level": 3, "text": "What this network is and is not" }, { "level": 2, "text": "Endpoints — how a workload joins a network" }, { "level": 2, "text": "Addresses, networks and endpoints — which one do you want?" }, { "level": 3, "text": "The address pool is a ledger" }, { "level": 3, "text": "The endpoint is an identity" }, { "level": 3, "text": "You do not create pools for networks" }, { "level": 3, "text": "So, in practice" }, { "level": 2, "text": "What runs on the network" }, { "level": 2, "text": "Stretching a network across nodes with VXLAN" }, { "level": 3, "text": "How a frame crosses the overlay" }, { "level": 2, "text": "VRF & Geneve" }, { "level": 2, "text": "Firewall and routing" }, { "level": 2, "text": "See also" } ], "word_count": 3002, "markdown": "# Networking Overview\n\nEvery network you define is a managed segment with its own subnet, addressing and DNS, carried on the host's workload bridge — and every usable address in it becomes an endpoint you can attach a workload to. This page describes that model: what a network gives you, how a workload joins one, and how a network is stretched across several hosts. Follow the links in each section for deeper coverage.\n\n## The two bridges\n\nEvery node owns two Linux bridges:\n\n| Bridge | Purpose |\n|--------|---------|\n| Management bridge | Carries agent control traffic, cluster communication, and the Gateway HA channel. Keep this reachable at all times. |\n| Workload bridge | Carries all workload traffic. This is where your networks live. |\n\nThe split is deliberate: workload saturation or a misconfigured network policy cannot starve the control plane.\n\n## Networks as L2 segments\n\nA *network* is a named managed L2 segment on the workload bridge.\n\n```bash\nsudo cenvero-str-ctl network create \\\n --name app-net \\\n --cidr 10.20.0.0/24 \\\n --gateway 10.20.0.1\n```\n\nCreating one gives you:\n\n- The segment itself — subnet, VLAN id if you gave one, and owning tenant.\n- An **address pool** covering the usable range, which `network delete` removes again.\n- An **endpoint profile** (IP ↔ generated MAC) for every usable host address, which\n you claim with `network attach`.\n- The gateway address **reserved** out of that range, so no endpoint is ever handed it.\n\n### What it does not do\n\nWorth knowing before you automate against it, because the difference is invisible\nuntil a workload fails to come up.\n\n`network create` does **not**:\n\n- assign the gateway address to any interface — nothing on the host answers on it;\n- create a DHCP scope;\n- create a DNS zone.\n\nThe gateway address matters if you expect workloads to route *off* the segment.\nTwo workloads on the same network talk to each other without it; reaching\nanything else needs something actually holding that address.\n\nThe DHCP point is the one that bites. The address pool exists, but **the DHCP\nserver will not hand out addresses for the network until a scope is bound to that\npool** — see [DHCP and DNS](/docs/networking/dhcp-dns). Until then the server has\nnothing to offer, and per RFC 2131 a server with nothing to offer stays silent:\nthe client retries with no reply, which looks exactly like a broken L2 path. The\nagent logs a warning naming the client when this happens. Give the workload a\nstatic address and it works immediately.\n\nNone of this depends on how a node is deployed. Every node runs the same DHCP and\nDNS servers, and every node routes — there is one kind of node.\n\nA single node can host many independent networks with non-overlapping subnets. In a cluster, the VXLAN overlay stretches each network across every node so an endpoint can move hosts without changing its IP — see [Clustering Overview](/docs/clustering/overview).\n\n## Worked example: two servers talking over a private network\n\nEnd to end, with nothing assumed. Every command here was run on a live node and\nthe output is what it actually printed.\n\n### 1. Create the network\n\n```bash\nsudo cenvero-str-ctl network create --name doctest --cidr 10.77.0.0/24 --gateway 10.77.0.1\n```\n\n```json\n{ \"status\": \"created\", \"network\": { \"id\": \"net-953e5ae21abd5029\", \"cidr\": \"10.77.0.0/24\", \"gateway\": \"10.77.0.1\" } }\n```\n\nKeep the `id` — the next step needs it. The address pool and one endpoint profile\nper usable address are created with it.\n\n### 2. Claim an endpoint for each server\n\n```bash\nsudo cenvero-str-ctl network attach net-953e5ae21abd5029\n```\n\n```json\n{ \"status\": \"attached\", \"endpoint\": { \"ip\": \"10.77.0.2\", \"mac\": \"02:ce:0a:4d:00:02\", \"state\": \"bound\" } }\n```\n\nRun it once per server. The second returns `10.77.0.3` / `02:ce:0a:4d:00:03`.\n\n**Write down the IP and MAC pairs.** They are the whole configuration — the MAC\nidentifies the workload to the fabric and the IP is what it is allowed to use.\nAttaching also registers the pairing in the packet path, which is what permits\nthat workload's traffic; an unregistered MAC is dropped.\n\n### 3. Put each server on the workload bridge with its MAC\n\nConfigure the virtual machine's network interface to use the **workload bridge**\nand the **MAC from step 2**. On a hypervisor this is a per-guest setting; the\nexact field name varies, but it is the one that sets the guest's hardware address.\n\nThe MAC must match exactly. A guest presenting any other address is refused —\nthat is the anti-spoofing working, not a fault.\n\n### 4. Give each server its address\n\nConfigure the address from step 2 inside the guest, with prefix `/24` and gateway\n`10.77.0.1`:\n\n```\n10.77.0.2/24 on the first server\n10.77.0.3/24 on the second\n```\n\nUse a static address. DHCP will not answer for this network until a scope is\nbound to its pool, and a client that gets no answer looks exactly like a broken\nconnection — see [DHCP and DNS](/docs/networking/dhcp-dns).\n\n### 5. They can talk\n\n```bash\n# from the first server\nping 10.77.0.3\n```\n\nTraffic between them stays on this node and never touches your uplink.\n\n### Removing it\n\n```bash\nsudo cenvero-str-ctl network delete net-953e5ae21abd5029\n```\n\nThis removes the network, its endpoints and its address pool together, so a\ndeleted network leaves nothing behind.\n\n### What this network is and is not\n\n- **Private, and private between customers.** Traffic between the private\n networks of two *different* tenants is refused in the packet path. Those\n addresses are not reachable from outside either, so there is no way around it.\n- **On one node.** Two workloads on the same node talk over it directly. To\n stretch a network across several nodes, see the overlay section below.\n- **Not routed off the segment by itself.** Nothing holds the gateway address\n until you configure something to. Workloads on the network reach each other\n regardless.\n\n## Endpoints — how a workload joins a network\n\nThis is the model to understand before automating anything.\n\nCreating a network does not create workloads; it creates **endpoints**. An\nendpoint is one address on that network paired with a hardware address, and one\nis prepared for every usable host address the moment the network exists. They sit\nunused until something claims them.\n\n```\nnetwork 10.20.0.0/24 ─┬─ endpoint 10.20.0.2 free\n ├─ endpoint 10.20.0.3 free\n └─ ...\n```\n\n**Attaching** claims one. You can name the address you want or take the next\nfree one, and you can supply the hardware address if the workload already has one\nof its own:\n\n```bash\n# take the next free address\nsudo cenvero-str-ctl network attach \n\n# or claim a specific address for a workload that already has a MAC\nsudo cenvero-str-ctl network attach --ip 10.20.0.50 --mac 52:54:00:ab:01:02\n```\n\n**Detaching** returns the endpoint to the free pool, and the address becomes\navailable again.\n\nTwo properties follow, and they are the reason the model works this way:\n\n> **The address and hardware address are decided before the workload exists.**\n> You can build your network layout, firewall policy and DNS records first, then\n> attach machines into a plan that is already in place.\n\n> **The pairing is enforced on every packet.** Traffic claiming to come from an\n> endpoint must carry that endpoint's address and hardware address, so one\n> workload cannot impersonate another. This is not a convention — it is checked\n> in the packet path.\n\nBecause the endpoint is the unit, moving a workload between hosts is a matter of\nattaching the same endpoint elsewhere; the address travels with it.\n\n## Addresses, networks and endpoints — which one do you want?\n\nThree things sound alike and are not, and picking the wrong one is the most common\nway to get stuck. Here is the whole distinction.\n\n| | **Address pool** (`ipam`) | **Network** | **Endpoint** (`network attach`) |\n|---|---|---|---|\n| What it is | A ledger of addresses | An L2 segment | One address bound to one hardware address |\n| Gives you | An address | A place for workloads to live | An address **and** a MAC |\n| Enforced on packets | No | — | **Yes** |\n| Use it for | Tracking addresses you own | Building a segment | Putting a workload on that segment |\n\n### The address pool is a ledger\n\n`ipam` answers one question: *which addresses are taken, and by whom.*\n\n```bash\nsudo cenvero-str-ctl ipam allocate 15 testhost\n```\n\n```json\n{ \"id\": 9, \"ip\": \"161.248.163.3\", \"pool_id\": 15, \"hostname\": \"testhost\" }\n```\n\nAn address and a label. **No hardware address, and nothing enforced.** Nothing\nstops a machine using that address anyway — the pool records that you assigned\nit, it does not police it. That is the right tool for keeping track of addresses\nyou own, such as the public addresses your provider routed to you.\n\n### The endpoint is an identity\n\n`network attach` answers a different question: *which workload may use this\naddress.*\n\n```bash\nsudo cenvero-str-ctl network attach net-953e5ae21abd5029\n```\n\n```json\n{ \"ip\": \"10.77.0.2\", \"mac\": \"02:ce:0a:4d:00:02\", \"state\": \"bound\" }\n```\n\nAn address **and** a hardware address, paired — and that pairing is registered in\nthe packet path. Traffic must carry both or it is refused. A workload cannot take\nan address it was not given, and cannot impersonate one that was given to another.\n\n**That enforcement is the entire difference.** A pool entry is a note; an endpoint\nis a rule.\n\n### You do not create pools for networks\n\n`network create` makes the pool for you, covering the network's usable range, and\n`network delete` removes it again. You will see it in `ipam pools` under the\nnetwork's name. There is no step where you build one by hand.\n\nYou create a pool directly only for addresses that are **not** a network's — a\nblock of public addresses, for instance, that you want to track allocation of.\n\n### So, in practice\n\n- **Two workloads that need to talk?** Create a network, attach an endpoint for\n each. You get the addresses and the hardware addresses, and the fabric enforces\n them.\n- **Just recording which addresses are spoken for?** Use a pool directly.\n- **Wondering where the MAC comes from?** Attaching generates one, unless the\n workload already has a hardware address of its own — pass `--mac` and it will be\n bound to the address instead.\n\n## What runs on the network\n\nOnce a network exists it comes with services already attached, rather than\nneeding separate ones configured:\n\n- **Addresses handed out automatically**, or reserved to a specific workload —\n see [DHCP & DNS](/docs/networking/dhcp-dns).\n- **A DNS zone** the network answers for, so workloads can find each other by\n name.\n- **Firewall policy**, applied wherever traffic enters — see\n [Zero-Trust Firewall](/docs/networking/firewall).\n- **Bandwidth limits** per tenant.\n- **Load balancing** for published services — see\n [Load Balancer](/docs/networking/load-balancer).\n\nFor how a packet actually travels through a node and where it can be stopped,\nsee [How Stratum Works](/docs/architecture).\n\n## Stretching a network across nodes with VXLAN\n\nAn overlay carries a network between nodes, so two endpoints on different hosts share one subnet. Creating it is a two-part job, and both parts are needed before a single packet moves.\n\n### How a frame crosses the overlay\n\nUnderstanding this explains why the setup has two halves, and why a missing peer produces silence rather than an error.\n\nA workload on node A sends a frame to a workload on node B. As far as both are concerned they are on the same flat network — same subnet, no router in between. What actually happens:\n\n1. **Node A wraps the frame.** The original frame — addresses, contents and all — is placed inside an ordinary UDP packet addressed from node A to node B. The workload's addresses are now payload; the outer packet carries only the two nodes' addresses.\n2. **That packet crosses your existing network** like any other traffic. Every switch and router between the nodes sees a normal UDP packet between two hosts. They neither know nor care that a whole frame is inside.\n3. **Node B unwraps it** and delivers the original frame to the destination workload, which sees it as though it arrived over a local switch port.\n\nTwo consequences you will actually run into:\n\n> **A node can only deliver to peers it has been told about.** The wrapping step needs a destination — node A must know that this workload's address lives behind node B. That is what a peer entry is. Without it, node A has nowhere to send the wrapped packet, so the frame is dropped **silently**: no error, just traffic that never arrives. This is the single most common overlay problem, and it is why peers must be registered on *every* node, in both directions.\n\n> **The overlay travels on your existing network, so that network must let it through.** The wrapped packets are UDP on port 4789 between the nodes' own addresses. On a cloud provider that means the security group or firewall in front of each node, not just the node's own firewall — and it must be open in **both** directions.\n\nWrapping also adds bytes to every packet. If your underlying network only just accommodates a standard-size packet, a full-size frame plus its wrapper can exceed it, and the symptom is characteristic: small packets work perfectly, large transfers stall. If you see that, the overlay is fine and the size limit is the problem.\n\nThe **VNI** is the overlay's identifier. It must match on every participating node, and it is what keeps overlays separate — two overlays on the same nodes with different VNIs cannot see each other's traffic even though they share the same underlying network.\n\n**Create the overlay on every node that participates.** The VNI identifies the overlay and must match; the subnet is the address range the overlay carries.\n\n```bash\nsudo cenvero-str-ctl vxlan create 4711 10.211.0.0/24\n```\n\nThe response names the tunnel device it created, `cnv-vx`:\n\n```json\n{\"data\":{\"vni\":4711,\"subnet\":\"10.211.0.0/24\",\"kernel_device\":\"cnv-vx4711\",\"status\":\"created\"},\"status\":\"ok\"}\n```\n\nIf it reports `\"kernel_device\": false` instead, the node has no address to send encapsulated traffic from and the overlay will carry nothing — the message explains what is missing.\n\n**Then tell each node about the others.** A node only delivers to peers it has been given, so every node needs an entry for every other node. A peer is its hostname, the address of its tunnel device, and the public address its traffic arrives from:\n\n```bash\n# Read the peer's tunnel-device address ON THAT PEER\ncat /sys/class/net/cnv-vx4711/address # e.g. ce:f0:ef:6b:18:f1\n\n# ...then register it here, with the peer's underlay address\nsudo cenvero-str-ctl vxlan peer-add 4711 node-b ce:f0:ef:6b:18:f1 203.0.113.9\n```\n\nRepeat in the other direction on `node-b`, pointing back at this node. Then confirm both sides agree:\n\n```bash\ncenvero-str-ctl vxlan peers 4711\ncenvero-str-ctl vxlan fdb\n```\n\nPeers persist and are re-applied when the agent restarts, so an overlay comes back on its own after a reboot. Removing a peer stops traffic to it immediately; deleting the overlay removes the tunnel device and every peer with it.\n\nThe underlay must allow UDP port 4789 between the nodes' addresses in both directions — on a cloud provider that means the firewall or security group in front of each node, not just the node's own firewall.\n\n## VRF & Geneve\n\nAlongside the VXLAN overlay, Stratum manages two more kernel networking constructs directly from `cenvero-str-ctl`. Both are control-plane device management: the agent creates the kernel devices, tracks them, persists them in its local database, and recreates them on startup — nothing is created at boot until you define it. The devices are ordinary kernel objects, visible with tools like `ip link show`.\n\n**VRF (virtual routing and forwarding)** gives a node more than one independent routing table.\n\n*Why you would want that:* normally a host has one routing table, so one destination has one answer — and two customers who both use `10.0.0.0/24` internally cannot both be routed correctly, because the address is ambiguous. A VRF removes the ambiguity by giving each its own table: the same address can route to different places depending on which VRF the traffic arrived in. It is also how you keep two upstream providers' routes from mixing on one box.\n\nYou create a VRF bound to a routing-table id and attach interfaces to it; traffic on those interfaces is then routed in that VRF's table instead of the main one. The kernel device is named `cnv-vrf-`.\n\n```bash\n# Create a VRF \"red\" on routing table 100 and enslave a NIC to it\nsudo cenvero-str-ctl vrf create red --table 100\nsudo cenvero-str-ctl vrf attach red --iface cnv-nic-1\n\n# Inspect, then release the interface and delete the VRF\ncenvero-str-ctl vrf list\ncenvero-str-ctl vrf show red\nsudo cenvero-str-ctl vrf detach red --iface cnv-nic-1\nsudo cenvero-str-ctl vrf delete red\n```\n\nDeleting a VRF releases every enslaved interface first, so none is left orphaned.\n\n**Geneve** is an overlay tunnel type (RFC 8926) — a sibling of VXLAN that wraps frames the same way, described above.\n\n*When to reach for it instead of VXLAN:* almost never, unless something you must interoperate with requires it. Geneve's advantage is an extensible header that can carry additional metadata alongside the frame, which matters to some hardware and to some other platforms. For stretching a Stratum network across your own nodes, **use VXLAN** — it is the path that clustering uses and the one that is proven end-to-end across hosts. Choose Geneve when you are terminating a tunnel from equipment that speaks Geneve and not VXLAN.\n\nA Geneve device carries a 24-bit VNI to a remote endpoint IP, with an optional outer UDP port (default 6081) and TTL; the kernel device is named `cnv-gnv-`.\n\n```bash\nsudo cenvero-str-ctl geneve create blue --vni 42 --remote 10.0.0.2\nsudo cenvero-str-ctl geneve create green --vni 7 --remote 10.0.0.3 --port 6081 --ttl 64\n\ncenvero-str-ctl geneve list\ncenvero-str-ctl geneve show blue\nsudo cenvero-str-ctl geneve delete blue\n```\n\nCreating a Geneve device configures the tunnel endpoint on this host. Carrying packets across the overlay also requires the remote endpoint to be configured to match; validate cross-host Geneve forwarding in your own environment before relying on it.\n\n## Firewall and routing\n\nThe firewall is a dual-stack L3/L4 ACL operating at the network level. For a zero-trust posture, set its default action to `deny` so all inter-network and external traffic is blocked unless you add an explicit allow rule. See [Zero-Trust Firewall](/docs/networking/firewall).\n\nTraffic that exits the fabric hits the BGP speaker for north-south routing, and published services can be fronted by the L4 or L7 load balancer. See [BGP Edge Routing](/docs/networking/bgp) and [Load Balancer](/docs/networking/load-balancer).\n\n## See also\n\n- [DHCP & DNS](/docs/networking/dhcp-dns) — pool configuration, leases, zones, and forwarders.\n- [Zero-Trust Firewall](/docs/networking/firewall) — policy model and rule examples.\n- [Load Balancer](/docs/networking/load-balancer) — L4 VIPs plus the Layer-7 HTTP proxy.\n- [BGP Edge Routing](/docs/networking/bgp) — announcing networks upstream.\n- [Clustering Overview](/docs/clustering/overview) — VXLAN overlay and multi-host networking.\n" } ] }