Skip to content

VPN tunnels

VPN tunnels are where you record the encrypted links between sites or peers - the tunnel itself, the groups that organize tunnels, and reusable crypto profiles you can share across many tunnels.

You build it in three layers: tunnel groups (how you organize tunnels), IPSec profiles (reusable crypto settings), and the tunnels themselves.

Add a tunnel group

A group bundles related tunnels together - for example by region, customer, or purpose.

  1. Open VPN → Tunnel groups in the sidebar and click Add group.
  2. Give it a name and a slug (a short URL-friendly identifier).
  3. Optionally add a description.
  4. Save.

Add an IPSec profile

An IPSec profile captures a set of crypto settings once so you can reuse it on every tunnel that shares that policy - no retyping the same parameters.

  1. Open VPN → IPSec profiles and click Add IPSec profile.
  2. Give it a name.
  3. Fill in the crypto parameters:
Field What it records
IKE version 1 or 2.
Encryption the encryption algorithm.
Authentication the authentication/hashing algorithm.
DH group the Diffie-Hellman group for key exchange.
PFS group the Perfect Forward Secrecy group (optional).
SA lifetime how long a security association stays valid.
Pre-shared key the IKE pre-shared key - stored in the secret store, never in this record (see below).
  1. Save.

The pre-shared key

A pre-shared key is a credential, so Danbyte treats it exactly as it treats an SSID's passphrase (see Wireless): the profile holds only a reference, and the key itself is written to the deployment's secret store.

  • Type the key into Pre-shared key on the profile form. On an existing profile the box is always empty: leaving it blank keeps the stored key, and typing a new one rotates it.
  • The profile page shows •••••••• when a key is set, with an eye button to reveal it. Revealing is a separate request, needs the reveal permission on IPSec profiles, and is written to the change log.
  • Deleting the profile, or clearing the field, removes the key from the store.
  • Without a secret store, saving a key is refused with a message pointing at Settings → Security → Secret store; the rest of the profile still saves. Danbyte never keeps a key in the database in the clear.

Nothing is pre-filled

Danbyte ships no sample groups, profiles, or tunnels - you create exactly the ones your network uses.

Add a tunnel

  1. Open VPN → Tunnels and click Add tunnel.
  2. Give it a name (must be unique).
  3. Pick the encapsulation - IPSec (tunnel or transport), GRE, IP-in-IP, or WireGuard.
  4. Set a status and, optionally, a tunnel ID.
  5. Optionally put it in a group. For IPSec encapsulations, you can also pick an IPSec profile - that field only appears when the encapsulation is IPSec.
  6. Optionally set its Capacity - how fast the tunnel's path is.
  7. Save.

Capacity

Capacity is typed the way an interface's speed is - 500M, 1G, 2.5G, with the common speeds offered as you type; a bare number is kbps. Leave it empty when you don't know. The tunnel's page shows it on its Overview (500 Mbps), and the site map writes it on the tunnel's line and colors the line by it under Color by → Speed. Every spoke of a hub tunnel shows the hub's figure.

Nothing works the figure out from the tunnel's interfaces or the path under it: it is only what you set. In the API it is capacity_kbps on /api/tunnels/, in kbps, null when unknown.

Terminate a tunnel

A tunnel is inert until its ends are bound. Each termination attaches one end of the tunnel to a device interface or a VM interface (exactly one), with:

  • a role - peer (point-to-point), or hub / spoke for hub-and-spoke topologies;
  • an optional outside IP - the underlay / public address the tunnel rides on. The tunnel's inside addresses attach to the terminating interface the normal way. The API returns outside_ip as null to a caller who may not view that address (IP view permission, its site scope and row constraints), on the tunnel and on /api/tunnel-terminations/.

  • Open the tunnel's detail page → Terminations tab.

  • Add termination, pick the device (or VM) and its interface, set the role, and optionally the outside IP.

A point-to-point tunnel has two peer terminations; a hub-and-spoke design has one hub and many spokes.

WireGuard

On a tunnel whose encapsulation is WireGuard, each termination also carries what a wg set line needs. The fields are refused on any other encapsulation.

Field Meaning
Listen port The UDP port this end listens on (1-65535).
Endpoint port The port the far end dials to reach this end, when NAT or a port forward makes it differ from the listen port. Empty means the listen port.
Public key This end's public key: 44 characters of base64 (32 bytes). Unique among the tenant's tunnel ends.
Private key reference Where the private key lives, printed verbatim by a template: a <keychain:NAME> placeholder naming a routing keychain in the tenant, or an absolute path on the box (/etc/wireguard/private.key).
Allowed IPs The addresses behind this end, as CIDRs.
Keepalive Persistent keepalive in seconds; empty or 0 is off.

Allowed IPs means "behind this end". That is WireGuard's own meaning: every other end prints this end's list in its peer block for this end, so the list says what the others route to it. A spoke lists its LAN; a hub lists what sits behind the hub. Hub-and-spoke works without per-pair data.

The private key never passes through Danbyte. The router generates its own key (wg genkey), the push tool writes the public key back (PATCH /api/tunnel-terminations/<id>/ with public_key), and the far ends re-render. A value pasted into Private key reference that decodes as a 32-byte key is refused. A deployment that wants Danbyte to hold the key puts it in a routing keychain (the secret store, read through the audited reveal-psk) and references it as <keychain:NAME>; the push tool replaces the placeholder as it does for BGP passwords. See Secrets in a render.

Which ends an end talks to follows its role: a peer talks to every other end, a hub to every spoke and other hub, and a spoke to the hubs (or to every other end when the tunnel has no hub). The tunnel's Terminations tab shows the listen port and the public key; a device's Tunnels card shows each far end's outside address and port.

In the API the six fields are listen_port, endpoint_port, public_key, private_key_ref, allowed_ips and persistent_keepalive on /api/tunnel-terminations/. A termination read on its own (or nested in a tunnel's detail) also carries a read-only peers list - the far ends with endpoint (host:port), public_key and allowed_ips resolved. A CSV import takes allowed_ips as a JSON list or as 0.0.0.0/0, ::/0. Templates read the same values from the tunnels block.

Tunnel map

The tunnel's detail page has a Map tab: the tunnel drawn from its terminations the way the Topology Diagram draws a map, Detailed with Elbow lines.

  • Each end is a card. A device's card is the one the Topology page draws: its role's color and its card lines. A VM's is a neutral card that says Virtual machine. The end's role - Hub, Spoke or Peer - is the pill in the card's corner; while a device is down, the monitoring pill takes its place if the card lines show it.
  • Each link is a dash-dot line with the terminating interface's name and the end's outside IP on the line at each end. Hovering a line names the tunnel.
  • Hub-and-spoke tunnels read top to bottom. The hub's tunnel interface is one nub: its line runs to a split point and on to every spoke, the way a breakout cable is drawn. With two hubs, each reaches every spoke.
  • Point-to-point / peer tunnels put two peers side by side. Three or more sit on a ring, each linked to every other.

Clicking a card opens its device (or VM). A device you may not view shows its name only. Legend keys the roles, the monitoring pill and the Tunnel line. Export saves the map as PNG, SVG, PDF or draw.io, or prints it, titled after the tunnel, with every line linking back to it (see Export). The map fills in as you add terminations on the Terminations tab; until then it says No terminations yet.

Where tunnels show up on interfaces

An interface that terminates a tunnel is flagged everywhere interfaces are listed:

  • Interface tables (the interfaces list, a device's Interfaces tab, the whole-stack view) show a small tunnel chip next to the interface name, linking to the tunnel.
  • The interface detail page shows the same chip in its header and lists each tunnel with the end's role under Relationships → Tunnels.

Behind this, the interface API (/api/interfaces/) exposes a read-only tunnel_terminations field - [{id, role, role_display, tunnel: {id, name}}], scoped to the interface's tenant.

Tunnel status

Status Meaning
Planned Designed but not yet built.
Active Up and carrying traffic.
Disabled Configured but turned off.

Groups and profiles in use can't be deleted

If a group or IPSec profile still has tunnels attached, Danbyte blocks the delete. Reassign or remove those tunnels first.

Tunnel group & IPSec profile pages

Click a tunnel group or IPSec profile name in its list to open its detail page - the pencil in the header edits it.

  • A tunnel group page shows its name, slug and description, with a Tunnels tab listing every tunnel in the group.
  • An IPSec profile page puts the crypto parameters - IKE version, encryption, authentication, DH and PFS groups, SA lifetime, and whether a pre-shared key is stored - on its Overview, with a Tunnels tab listing every tunnel that inherits them. Read that tab before changing a profile: the edit lands on all of them at once.

Both tunnel lists are the same table the main Tunnels page draws, minus the column that repeats the object you are already looking at. They are powered by GET /api/tunnels/?group=<id> and ?ipsec_profile=<id>.

Each page also carries Journal and Change log tabs. Groups and profiles have been audited all along, so the Change log tab shows every recorded change to the row, including ones made before the page existed.

L2VPN overlays

Alongside point-to-point tunnels, Danbyte models L2VPNs - layer-2 overlay services such as EVPN, VXLAN, VPWS, and VPLS. An L2VPN records the overlay itself; terminations attach it to the VLANs and interfaces that carry it.

Add an L2VPN

  1. Open VPN → L2VPNs and click Add L2VPN.
  2. Fill in the form:
Field What it records
Name and slug A label and a URL-friendly identifier (slug unique per tenant).
Type The overlay technology - VXLAN, VXLAN-EVPN, MPLS-EVPN, PBB-EVPN, VPWS, VPLS, EPL, EVPL, SPB, or TRILL.
Identifier The overlay identifier - a VNI or VC-ID (optional). A VNI is unique per tenant across the VXLAN types.
VRF EVPN types only. Set it and this VNI is that VRF's L3VNI - see the overlay.
Status Your own status catalog, same as elsewhere.
Import / export route targets BGP route targets, picked from your existing route targets.
  1. Save.

Terminate an L2VPN

Like a tunnel, an L2VPN is inert until it's attached to something. Each termination binds it to exactly one endpoint - a VLAN, a device interface, or a VM interface - from the L2VPN's detail page.

  • An endpoint can terminate at most one L2VPN - Danbyte blocks a second.
  • Point-to-point types (VPWS, EPL, EVPL) typically get two terminations; multipoint types (VPLS, the EVPN family) get as many as the overlay spans.
  • A VLAN's page lists the L2VPNs terminating on it under L2VPNs.

Which leaves carry a VXLAN VNI is a different question - that is the VTEPs tab, fed by each device's VTEP.

The L2VPN list

Tick rows on VPN → L2VPNs - with the change or delete grant on L2VPNs - for the bulk bar:

  • Export downloads the selected L2VPNs as CSV, Excel or JSON.
  • Edit sets the Status, VRF, Description, tags and custom fields on every selected L2VPN. A VRF only lands on an EVPN type, as in the form: a selection holding another type is refused, naming it.
  • Delete shows a preview first - the terminations and VTEP memberships that go with the L2VPNs - then deletes them, each with a change-log entry.

Tags & custom fields

Need to track something extra - a peer IP, a pre-shared-key reference, a contract ID? Add a custom field for tunnels (or L2VPNs) and it appears on every form. See Tags & custom fields.