osvbng

https://docs.osvbng.v6n.io
Admin
osvbng is a high-performance, scalable, open-source Virtual Broadband Network Gateway for ISPs...
Tokens:145,314
Snippets:1,092
Trust Score:2.4
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Start and Connect to VM

Source: https://docs.osvbng.v6n.io/

Starts the VM and connects to its console. Default login is root / osvbng.

```bash
# Start the VM
sudo virsh start osvbng

# Connect to console
sudo virsh console osvbng

# Default login: root / osvbng

```

--------------------------------

### Quick Install for QEMU/KVM with DPDK

Source: https://docs.osvbng.v6n.io/

Quick install for QEMU/KVM with DPDK. Downloads the deployment script, makes it executable, and runs it with sudo.

```bash
curl -sL https://v6n.io/osvbng -o deploy-vm.sh
chmod +x deploy-vm.sh
sudo ./deploy-vm.sh

```

--------------------------------

### Install systemd service for production

Source: https://docs.osvbng.v6n.io/

Sets up a systemd service for automatic container and interface setup on boot. Requires editing the service file to match your host interface names.

```bash
# Download the service file and setup script
curl -sLO https://raw.githubusercontent.com/veesix-networks/osvbng/main/docker/osvbng.service
curl -sLO https://raw.githubusercontent.com/veesix-networks/osvbng/main/docker/setup-interfaces.sh

# Create working directory
sudo mkdir -p /opt/osvbng
sudo mv setup-interfaces.sh /opt/osvbng/
sudo chmod +x /opt/osvbng/setup-interfaces.sh

# Edit the service file and update the interface names on line 25
# Change eth0:ens19 eth1:ens20 to match your host interface names
sudo nano osvbng.service

# Install and enable the service
sudo mv osvbng.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable osvbng.service
sudo systemctl start osvbng.service
```

--------------------------------

### Manual Install

Source: https://docs.osvbng.v6n.io/

Manual installation: downloads the deployment script and runs the interactive installer.

```bash
# Download the deployment script
curl -sLO https://raw.githubusercontent.com/veesix-networks/osvbng/main/scripts/qemu/deploy-vm.sh
chmod +x deploy-vm.sh

# Run the interactive installer
sudo ./deploy-vm.sh

```

--------------------------------

### Plugin Configuration Example

Source: https://docs.osvbng.v6n.io/architecture/CONFIGURATION

Example of a plugin-specific configuration section under the 'plugins:' key. Plugins define their own typed configuration structure and can access it at runtime.

```yaml
plugins:
  example.hello:
    enabled: true
    message: "Custom greeting"

```

--------------------------------

### Install host prerequisites for QEMU/KVM development VM

Source: https://docs.osvbng.v6n.io/contributing/please_read_first

Install required packages for libvirt-based development VM on Debian/Ubuntu/Pop!_OS, add the current user to the libvirt group, and activate the group membership in the current shell.

```bash
sudo apt install -y \
    virtinst \
    libvirt-daemon-system \
    cloud-image-utils \
    qemu-utils \
    whiptail \
    rsync

sudo usermod -aG libvirt $USER
newgrp libvirt           # or log out and back in
```

--------------------------------

### Install Dependencies (Debian/Ubuntu)

Source: https://docs.osvbng.v6n.io/

Installs required packages for Debian/Ubuntu to run the VM deployment.

```bash
sudo apt install -y libvirt-daemon-system qemu-kvm virtinst curl whiptail gzip bridge-utils

```

--------------------------------

### GET /api/startup-config

Source: https://docs.osvbng.v6n.io/getting-started/api

Retrieves the startup configuration.

```APIDOC
## GET /api/startup-config

### Description
Gets the startup configuration of the system.

### Method
GET

### Endpoint
/api/startup-config

### Response
#### Success Response (200)
- No explicit response body documented.

#### Response Example
No response example provided.
```

--------------------------------

### Start container with custom config

Source: https://docs.osvbng.v6n.io/

Starts the container with a mounted configuration file in read-only mode. Alternatively, update the systemd service file to include the volume mount.

```bash
docker run -d --name osvbng \
  --privileged \
  --network none \
  -v /opt/osvbng/osvbng.yaml:/etc/osvbng/osvbng.yaml:ro \
  -e OSVBNG_WAIT_FOR_INTERFACES=true \
  -e OSVBNG_ACCESS_INTERFACE=eth0 \
  -e OSVBNG_CORE_INTERFACE=eth1 \
  veesixnetworks/osvbng:latest
```

--------------------------------

### MPLS and LDP example configuration

Source: https://docs.osvbng.v6n.io/configuration/mpls

Example configuration enabling MPLS and LDP, with OSPF on eth1 and a passive loopback. eth1 is MPLS-enabled and enrolled in LDP; loop0 is MPLS-enabled but does not form LDP adjacencies.

```yaml
protocols:
  mpls:
    enabled: true
  ldp:
    enabled: true
    router-id: 10.254.0.1
    address-families:
      ipv4:
        transport-address: 10.254.0.1
  ospf:
    enabled: true
    router-id: 10.254.0.1
    areas:
      "0.0.0.0":
        interfaces:
          eth1:
            network: point-to-point
          loop0:
            passive: true

```

--------------------------------

### Generate and install config file

Source: https://docs.osvbng.v6n.io/

Generates a default configuration file and moves it to /etc/osvbng/ for customization.

```bash
docker run --rm veesixnetworks/osvbng:latest config > osvbng.yaml
sudo mv osvbng.yaml /etc/osvbng/
```

--------------------------------

### Configure example.hello plugin

Source: https://docs.osvbng.v6n.io/configuration/plugins/example-hello

Configuration for the example.hello plugin. Set enabled to true to activate the plugin and provide a custom greeting message.

```yaml
plugins:
  example.hello:
    enabled: true
    message: "Hello, World!"

```

--------------------------------

### Show Handler to Component Flow

Source: https://docs.osvbng.v6n.io/architecture/HANDLERS

Example flow of a show handler collecting state: user runs 'show example hello status', StatusHandler.Collect() gets the component instance, calls GetMessage(), and returns the current state to the user.

```text
User: show example hello status
  → StatusHandler.Collect()
    → Gets hello.Component instance
    → Calls component.GetMessage()
    → Returns current state to user
```

--------------------------------

### Config Handler to Component Flow

Source: https://docs.osvbng.v6n.io/architecture/HANDLERS

Example flow of a config handler applying a change: user sets a message, MessageHandler.Apply() gets the component instance, calls SetMessage(), and the component updates its runtime state.

```text
User: set example hello message "test"
  → MessageHandler.Apply()
    → Gets hello.Component instance
    → Calls component.SetMessage("test")
    → Component updates its runtime state
```

--------------------------------

### Example configuration for subscriber.auth.http

Source: https://docs.osvbng.v6n.io/configuration/plugins/auth-http

Complete YAML configuration for the HTTP subscriber authentication plugin. It sets the endpoint, method, timeout, bearer token authentication, response allowed condition and attribute mappings, and accounting events for start and stop. Use this as a template for your own configuration.

```yaml
plugins:
  subscriber.auth.http:
    endpoint: https://auth.example.com/api/auth
    method: POST
    timeout: 5s
    auth:
      type: bearer
      token: my-secret-token
    response:
      allowed_condition:
        jsonpath: "$.allowed"
        value: "true"
      attribute_mappings:
        - path: "$.ip_address"
          attribute: ipv4_address
        - path: "$.download_rate"
          attribute: qos.download-rate
    accounting:
      enabled: true
      start:
        endpoint: https://auth.example.com/api/acct/start
        method: POST
      stop:
        endpoint: https://auth.example.com/api/acct/stop
        method: POST

```

--------------------------------

### Register vendor in all.go init()

Source: https://docs.osvbng.v6n.io/reference/nics/adding-vendor-support

Registration code in pkg/config/system/nic/all.go. Add the new vendor before Generic, which must be last because it matches everything.

```go
func init() {
    Register(Mellanox{})
    Register(Intel{})
    Register(Broadcom{})  // Add before Generic
    Register(Generic{})   // Generic must be last (matches everything)
}

```

--------------------------------

### Create vendor file pkg/config/system/nic/broadcom.go

Source: https://docs.osvbng.v6n.io/reference/nics/adding-vendor-support

Example vendor implementation file for Broadcom. Defines the Broadcom struct with Name, Match, and BindStrategy methods. Match checks for vendor ID "14e4" and BindStrategy returns BindStrategyVFIO.

```go
package nic

type Broadcom struct{}

func (b Broadcom) Name() string { return "Broadcom" }

func (b Broadcom) Match(vendorID string) bool {
    return vendorID == "14e4"
}

func (b Broadcom) BindStrategy() BindStrategy {
    return BindStrategyVFIO
}

```

--------------------------------

### Create the development VM with make dev-vm

Source: https://docs.osvbng.v6n.io/contributing/please_read_first

Downloads a Debian 12 cloud image (~400 MB, cached), creates a 30 GB qcow2 disk, defines a 6 GB / 4 vCPU domain named 'osvbng-dev', and runs the provisioner. First run takes ~10 minutes. Override defaults via env: VM_MEMORY=8192 make dev-vm.

```bash
make dev-vm
```

--------------------------------

### Peering vs Transit Local-Preference: route-policies for transit, IXP, PNI, and customer

Source: https://docs.osvbng.v6n.io/examples/routing-policies

Defines route policies that set local-preference values based on peer type. Transit gets the lowest preference (100), IXP peers get 140, private peering (PNI) gets 150, and customer routes get the highest (200). Each policy also tags routes with a specific BGP community.

```yaml
routing-policies:
  route-policies:
    # Transit upstreams — lowest preference (default BGP is 100)
    TRANSIT-IN-V4:
      - sequence: 10
        action: deny
        match:
          prefix-set: BOGONS-V4
      - sequence: 100
        action: permit
        set:
          local-preference: 100
          community: "64500:950"
          community-additive: true

    # IXP peers — medium preference
    IXP-PEER-IN-V4:
      - sequence: 10
        action: deny
        match:
          prefix-set: BOGONS-V4
      - sequence: 100
        action: permit
        set:
          local-preference: 140
          community: "64500:930"
          community-additive: true

    # Private peering (direct interconnect) — higher preference
    PNI-PEER-IN-V4:
      - sequence: 10
        action: deny
        match:
          prefix-set: BOGONS-V4
      - sequence: 100
        action: permit
        set:
          local-preference: 150
          community: "64500:920"
          community-additive: true

    # Customer routes — highest preference
    CUSTOMER-IN-V4:
      - sequence: 10
        action: deny
        match:
          prefix-set: BOGONS-V4
      - sequence: 100
        action: permit
        set:
          local-preference: 200
          community: "64500:960"
          community-additive: true
```

--------------------------------

### Attach virtual interfaces for testing

Source: https://docs.osvbng.v6n.io/

Runs the setup-interfaces.sh script for testing without physical hardware, using virtual interfaces eth0 and eth1.

```bash
./setup-interfaces.sh osvbng eth0 eth1
```

--------------------------------

### Run locally with Docker

Source: https://docs.osvbng.v6n.io/contributing/please_read_first

Builds the Docker image, creates the network topology, and starts osvbng. Run from the docker/dev directory.

```bash
make build
cd docker/dev
./dev.sh start

```

--------------------------------

### Scope examples for commit messages

Source: https://docs.osvbng.v6n.io/contributing/commit-messages

Examples of commit messages with scopes, demonstrating how to specify the affected area. Scopes are optional and should be lowercase.

```text
feat(dhcpv6): add basic IA_NA and IA_PD support
feat(plugin): add HTTP authentication provider
fix(ipoe): prevent session crash on nil reference during teardown
feat(api): add auto-generated OpenAPI documentation
feat(routing): add IS-IS and OSPF integration
refactor(logging): move component logging to generic sub-logging

```

--------------------------------

### Install Mellanox packages and check kernel module

Source: https://docs.osvbng.v6n.io/reference

Install rdma-core and libibverbs-dev packages, then check if the mlx5 kernel module is loaded. This is needed for Mellanox devices to work.

```bash
apt install rdma-core libibverbs-dev
lsmod | grep mlx5

```

--------------------------------

### Plugin configuration example under plugins: section

Source: https://docs.osvbng.v6n.io/architecture/CONFIGURATION

Shows the YAML structure for enabling a plugin and setting a message. The plugin key is 'example.hello' and the configuration includes 'enabled: true' and a message string. This configuration is stored under the 'plugins:' section of the unified config file.

```yaml
plugins:
  example.hello:
    enabled: true
    message: "Hello world"

```

--------------------------------

### Initialize submodules

Source: https://docs.osvbng.v6n.io/contributing/please_read_first

Fetches the vpp and context submodules on an existing clone. Requires SSH access to the submodule remotes.

```bash
git submodule update --init --recursive

```

--------------------------------

### BGP VRF Configuration Example

Source: https://docs.osvbng.v6n.io/configuration/protocols

YAML example showing a BGP configuration with ASN, router ID, peer groups, neighbors, and IPv4 unicast settings including networks and redistribution.

```yaml
protocols:
  bgp:
    asn: 65000
    router-id: 10.255.0.1
    peer-groups:
      upstream:
        remote-as: 65001
        ipv4-unicast:
          next-hop-self: true
          send-community: both
    neighbors:
      10.0.0.1:
        peer-group: upstream
        description: Core Router
        bfd: true
    ipv4-unicast:
      networks:
        10.100.0.0/16: {}
      redistribute:
        connected: true

```

--------------------------------

### Start OSvBNG container

Source: https://docs.osvbng.v6n.io/

Starts the OSvBNG container with privileged mode, no network, and environment variables for interface configuration. Requires Docker and at least two physical network interfaces for non-test deployments.

```bash
docker run -d --name osvbng \
  --privileged \
  --network none \
  -e OSVBNG_WAIT_FOR_INTERFACES=true \
  -e OSVBNG_ACCESS_INTERFACE=eth0 \
  -e OSVBNG_CORE_INTERFACE=eth1 \
  veesixnetworks/osvbng:latest
```

--------------------------------

### Attach physical network interfaces

Source: https://docs.osvbng.v6n.io/

Downloads and runs the setup-interfaces.sh script to attach physical network interfaces to the container. Replace enp0s1 and enp1s1 with your host interface names.

```bash
curl -sLO https://raw.githubusercontent.com/veesix-networks/osvbng/main/docker/setup-interfaces.sh
chmod +x setup-interfaces.sh
./setup-interfaces.sh osvbng eth0:enp0s1 eth1:enp1s1
```

--------------------------------

### AAA configuration example with local auth provider and policies

Source: https://docs.osvbng.v6n.io/configuration/aaa

Example AAA configuration showing three policies: default-policy (no authentication), credential-policy (authenticate: true), and radius-dhcp-policy (type: dhcp with placeholder password).

```yaml
aaa:
  auth_provider: local
  nas_identifier: osvbng
  policy:
    - name: default-policy
      format: "$mac-address$"
      max_concurrent_sessions: 1
    - name: credential-policy
      format: "$mac-address$"
      authenticate: true
      max_concurrent_sessions: 1
    - name: radius-dhcp-policy
      format: "$remote-id$"
      password: "example"
      type: dhcp
      max_concurrent_sessions: 1

```

--------------------------------

### Method 1: Simple Show Commands with commands.ShowHandlerFunc

Source: https://docs.osvbng.v6n.io/architecture/PLUGINS

Use this method for most show commands. The CLI framework automatically validates required arguments based on the Arguments field. The example registers a root command and two subcommands: one with no arguments and one with a required 'session-id' argument.

```go
package myplugin

import (
    "github.com/veesix-networks/osvbng/cmd/osvbngcli/commands"
    "github.com/veesix-networks/osvbng/pkg/cli"
)

func init() {
    cli.RegisterRoot(Namespace, &cli.RootCommand{
        Path:        []string{"show", "myplugin"},
        Description: "My plugin commands",
    })

    // Command with no arguments
    cli.Register(Namespace, &cli.Command{
        Path:        []string{"show", "myplugin", "status"},
        Description: "Display plugin status",
        Handler:     commands.ShowHandlerFunc(ShowStatusPath),
    })

    // Command with required argument (automatic validation)
    cli.Register(Namespace, &cli.Command{
        Path:        []string{"show", "myplugin", "session"},
        Description: "Display session details",
        Handler:     commands.ShowHandlerFunc(ShowSessionPath),
        Arguments: []*cli.Argument{
            {Name: "session-id", Description: "Session identifier", Type: cli.ArgUserInput},
        },
    })
}

```

--------------------------------

### Static Routes YAML Example

Source: https://docs.osvbng.v6n.io/configuration/protocols

YAML configuration example for defining static routes under the protocols.static section. It includes two IPv4 routes (one with a next-hop, one with a device) and one IPv6 default route with a next-hop.

```yaml
protocols:
  static:
    ipv4:
      - destination: 0.0.0.0/0
        next-hop: 10.0.0.1
      - destination: 192.168.0.0/16
        device: eth2
    ipv6:
      - destination: ::/0
        next-hop: 2001:db8::1

```
Tokens:
Raw