arca-router

README

arca-router

English | 日本語

High-Performance Software Router with Junos-like Configuration

arca-router is a software router with Junos-compatible configuration syntax, powered by VPP (Vector Packet Processing) and FRR (Free Range Routing) for dynamic routing protocols.

---

Status

arca-router is currently in the v0.10.x stabilization and compatibility phase after completing the v0.9.x NETCONF/YANG and operational safety implementation. This README describes the current unified daemon path; detailed release history is kept in CHANGELOG.md, and future scope is tracked in ROADMAP.md.

Current capabilities:

• Unified arca-routerd process for VPP, FRR, NETCONF, and gRPC
• Junos-like set configuration syntax with a thin arca client
• Struct-first configuration model with diff-based 2-phase commit and rollback
• FRR transactional apply through the management candidate datastore
• v0.6-v0.8 config and observability foundations for clustering, VRRP, MPLS, routing instances, QoS, IPv6 parity, BFD, EVPN/VXLAN, streaming telemetry, and NMS APIs
• Prometheus, health, SNMP, Web UI, Grafana observability, and authenticated Web config workflow
• SQLite or etcd-backed candidate/running datastore with commit history and etcd config sync
• v0.10 compatibility preflight, schema migration guardrails, support matrix reporting, gRPC TLS/mTLS, Web API token auth, and admin-only audit export
• v0.10 release readiness/sign-off checklists, NETCONF client evidence gates, and installed-host security audit

---

Prerequisites

System Requirements

• OS: Debian 12 (Bookworm) or RHEL 9 / AlmaLinux 9 / Rocky Linux 9
• CPU: x86_64 with multi-core support (2+ cores recommended)
• Memory: 4GB+ RAM (VPP requires hugepages)
• NIC: Intel (AVF) or Mellanox (RDMA) compatible NICs

Required Software

• VPP 24.10 release series: Vector Packet Processing framework

  • See VPP Setup Guide (Debian) and VPP Setup Guide (RHEL9)

• FRR 8.0+: Free Range Routing for dynamic routing protocols

  • See FRR Setup Guide (Debian) and FRR Setup Guide (RHEL9)
  • Enable bgpd, ospfd, zebra, staticd, mgmtd, vrrpd, and bfdd in /etc/frr/daemons

• Go 1.25+: For building from source (optional)

---

Quick Start

Requires the VPP 24.10 release series and FRR 8.0+ with the standard arca-router FRR daemon set enabled.

1. Install Prerequisites

Debian Bookworm:

# Install VPP 24.10
curl -s https://packagecloud.io/install/repositories/fdio/2410/script.deb.sh | sudo bash
sudo apt-get install -y vpp=24.10-release vpp-plugin-core=24.10-release

# Install FRR
sudo apt-get install -y frr frr-pythontools

# See detailed setup guides:
# - docs/vpp-setup-debian.md
# - docs/frr-setup-debian.md

RHEL note: FD.io does not publish VPP 24.10 RPMs for RHEL9; build VPP from source per docs/vpp-setup-rhel9.md before installing.

RHEL 9 / AlmaLinux 9 / Rocky Linux 9:

# Build VPP 24.10 RPMs from source (see docs/vpp-setup-rhel9.md), then install VPP + FRR
sudo dnf install -y /path/to/vpp-24.10-*.rpm /path/to/vpp-plugin-core-24.10-*.rpm frr frr-pythontools

2. Install arca-router

Debian Bookworm:

# Install DEB package
sudo dpkg -i arca-router_*.deb

# Verify installation
/usr/sbin/arca-routerd --version
arca --version

RHEL 9 / AlmaLinux 9 / Rocky Linux 9:

# Install RPM package
sudo dnf install -y ./arca-router-*.rpm

# Verify installation
/usr/sbin/arca-routerd --version
arca --version

To use arca as a non-root operator, add that login user to the arca-router group and start a new login session:

sudo usermod -aG arca-router $USER

3. Configure Hardware Mapping

Copy and edit the example configuration:

# Copy example configs
sudo cp /etc/arca-router/hardware.yaml.example /etc/arca-router/hardware.yaml
sudo cp /etc/arca-router/arca-router.conf.example /etc/arca-router/arca-router.conf

Edit /etc/arca-router/hardware.yaml:

interfaces:
  - name: "ge-0/0/0"
    pci: "0000:03:00.0"
    driver: "avf"
    description: "WAN Uplink"
  - name: "ge-0/0/1"
    pci: "0000:03:00.1"
    driver: "avf"
    description: "LAN Interface"

Find your NIC PCI addresses:

lspci | grep Ethernet

4. Configure Interfaces and Routing

Edit /etc/arca-router/arca-router.conf to configure interfaces and routing protocols:

# System configuration
set system host-name arca-router-01

# Interface configuration
set interfaces ge-0/0/0 description "WAN Uplink"
set interfaces ge-0/0/0 unit 0 family inet address 198.51.100.1/30
set interfaces ge-0/0/1 description "LAN Interface"
set interfaces ge-0/0/1 unit 0 family inet address 192.168.1.1/24

# Routing options
set routing-options autonomous-system 65000
set routing-options router-id 198.51.100.1

# BGP configuration
set protocols bgp group external type external
set protocols bgp group external neighbor 198.51.100.2 peer-as 65001
set protocols bgp group external neighbor 198.51.100.2 description "ISP Router"

# OSPF configuration
set protocols ospf area 0.0.0.0 interface ge-0/0/1
set protocols ospf router-id 198.51.100.1

# Static routes
set routing-options static route 0.0.0.0/0 next-hop 198.51.100.2

See examples/arca-router.conf for a complete configuration example.

5. Start arca-router

# Start the service
sudo systemctl start arca-routerd

# Enable at boot
sudo systemctl enable arca-routerd

# Check status
sudo systemctl status arca-routerd

# View logs
sudo journalctl -u arca-routerd -f

6. (Optional) Configure NETCONF and Security

Enable NETCONF Server:

Edit /etc/arca-router/arca-router.conf to enable NETCONF and create users:

# Enable NETCONF on loopback port 830
set security netconf ssh enabled true
set security netconf ssh port 830

# Create admin user
set security users user admin password YourSecurePassword123
set security users user admin role admin

# Create operator user for automation
set security users user operator password OperatorPass456
set security users user operator role operator

# Rate limiting
set security rate-limit per-ip 10
set security rate-limit per-user 20

NETCONF is built into arca-routerd; no separate NETCONF daemon is needed. When --netconf-listen is omitted, NETCONF remains disabled until security netconf ssh enabled true or a configured NETCONF SSH listen address/port is present. Enabled NETCONF binds to 127.0.0.1:830 by default unless listen-address or port is configured.

Standard NETCONF :xpath capability advertisement is enabled by default. Use arca-routerd --netconf-standard-xpath=false only for compatibility testing against clients that cannot handle advertised XPath filters. The NETCONF startup datastore is intentionally unsupported and is not advertised.

For automation against the Web/NMS API, provide a 0600 token file with one name:role:token or name:role:sha256:<hex>[:not-after=<RFC3339>] entry per line and start the daemon with --web-api-token-file=/etc/arca-router/web-api-tokens. Plain token values must be at least 32 characters, must not contain whitespace, and should be generated from random bytes, for example openssl rand -base64 32. Prefer storing sha256:<hex> token hashes in the file, with not-after for bounded rotation windows; clients still present the original token through Authorization: Bearer <token> or X-API-Key: <token> and reuse the read-only, operator, and admin RBAC roles. During request authentication the daemon checks token file metadata and reloads the file when it changes, so atomic file replacement can rotate or revoke tokens without restarting the daemon.

Test NETCONF connection:

# Connect via NETCONF (requires netconf-console or similar client)
netconf-console --host localhost --port 830 --user admin --password YourSecurePassword123

7. Verify Configuration

# Check daemon logs
sudo journalctl -u arca-routerd -n 50

# View running configuration with arca
arca show configuration
arca show configuration rollback 1

# Save configuration backups before maintenance
arca check upgrade
arca check upgrade backup /var/backups/arca-router/running.conf
arca backup configuration /var/backups/arca-router/running.conf
arca backup configuration rollback 1 /var/backups/arca-router/rollback-1.conf

# Restore a backup into candidate configuration for review before commit
arca
configure
restore configuration /var/backups/arca-router/running.conf
show | compare
commit check
commit comment "Restore configuration backup"

# Check managed interface state, counters, QoS profile, queue placement, and QoS capabilities through arca-routerd
arca show interfaces
arca show routing-instances
arca show routes
arca show routes protocol bgp
arca show route
arca show route inet6
arca show bgp neighbors
arca show bgp summary
arca show ospf neighbor
arca show ospf3 neighbor
arca show vrrp
arca show bfd status
arca show bfd
arca show bfd counters
arca show evpn
arca show lcp
arca show ha
arca show class-of-service
arca show telemetry paths
arca show telemetry paths live
arca show telemetry paths cardinality per-route
arca show telemetry paths live payload-schema arca.telemetry.routes.v1
arca show telemetry path /system path /interfaces path /overlays/evpn

# Query the schema-versioned NMS status API when the Web API is enabled
curl -u monitor:ReadOnly789 http://127.0.0.1:8080/api/nms/v1/status
curl -u monitor:ReadOnly789 http://127.0.0.1:8080/api/nms/v1/telemetry/paths
curl -u monitor:ReadOnly789 'http://127.0.0.1:8080/api/nms/v1/telemetry/paths?cardinality=per-route&payload_schema=arca.telemetry.routes.v1'
curl -u monitor:ReadOnly789 'http://127.0.0.1:8080/api/nms/v1/telemetry/paths?path=system,evpn&encoding=json'
curl -u monitor:ReadOnly789 'http://127.0.0.1:8080/api/nms/v1/telemetry/schemas?path=/evpn'
curl -u monitor:ReadOnly789 'http://127.0.0.1:8080/api/nms/v1/telemetry/snapshot?path=/system&path=/interfaces&path=/overlays/evpn&timeout=5s&max_payload_bytes=8388608&max_events=64'
curl -u monitor:ReadOnly789 'http://127.0.0.1:8080/api/nms/v1/telemetry/snapshot?cardinality=per-route&payload_schema=arca.telemetry.routes.v1&max_events=1'

# Check VPP/FRR directly (optional)
sudo vppctl show interface
sudo vppctl show lcp
sudo vtysh -c 'show running-config'
sudo vtysh -c 'show ip route'

---

Configuration Reference

The full configuration syntax and supported set hierarchy is documented in SPEC.md.

Top-level stanzas:

• system
• interfaces
• routing-options
• protocols
• policy-options
• security

Interface Naming Convention

• ge-X/Y/Z: Gigabit Ethernet (1GbE)
• xe-X/Y/Z: 10 Gigabit Ethernet (10GbE)
• et-X/Y/Z: 100 Gigabit Ethernet (100GbE)

---

Building from Source

Prerequisites

• Go 1.25+
• NFPM 2.35.0+ (for DEB/RPM packaging)

Build Steps

# Clone repository
git clone https://github.com/akam1o/arca-router.git
cd arca-router

# Build binaries
make build

# Run tests
make test

# Build DEB package (nfpm config: build/package/nfpm.yaml)
make deb

# Build RPM package
make rpm

# Packages will be in dist/ directory
ls -lh dist/

Makefile Targets

make help             # Show all available targets
make version          # Display version information
make build            # Build v0.5.x unified daemon + CLI
make build-cli        # Build only current arca CLI
make generate-proto   # Generate typed gRPC bindings
make test             # Run unit tests
make integration-test # Run integration tests
make package-lint     # Validate package metadata and service expectations
make frr-mgmtd-smoke  # Run live FRR mgmtd smoke test
make fmt              # Format code
make vet              # Run go vet
make check            # Run all checks (fmt, vet, test)
make clean            # Clean build artifacts
make install-nfpm     # Install NFPM tool
make deb              # Build DEB package
make deb-test         # Test DEB package metadata
make deb-verify       # Verify DEB package reproducibility
make rpm              # Build RPM package
make rpm-test         # Test RPM package metadata
make rpm-verify       # Verify reproducible build
make packages         # Build both RPM and DEB packages

---

Project Structure

arca-router/
├── api/
│   └── v1/
│       └── router.proto        # gRPC API definitions (Config/Session/State/Telemetry)
├── cmd/
│   ├── arca-routerd/           # Unified daemon
│   │   └── main.go             # Single process: VPP + FRR + NETCONF + gRPC
│   └── arca/                   # Thin gRPC CLI client
│       └── main.go             # Communicates via Unix socket
├── internal/                   # v0.6.x-v0.8.x core packages
│   ├── model/                  # Canonical config & state types
│   │   ├── config.go           # RouterConfig (struct-first model)
│   │   ├── state.go            # OperationalState
│   │   ├── validate.go         # Validation logic
│   │   └── convert.go          # Text config ↔ canonical model conversion
│   ├── engine/                 # Config engine
│   │   ├── engine.go           # 2-phase commit, atomic apply
│   │   ├── diff.go             # Minimal diff computation
│   │   └── plugin.go           # Southbound plugin interface
│   ├── southbound/
│   │   ├── vpp/plugin.go       # VPP plugin (govpp)
│   │   └── frr/plugin.go       # FRR plugin (transactional/file apply)
│   ├── northbound/
│   │   └── grpc/               # gRPC server + client
│   │       ├── server.go       # Session mgmt, config ops
│   │       └── client.go       # Thin client for CLI
│   ├── store/                  # Persistence abstraction
│   │   ├── store.go            # ConfigStore interface
│   │   └── sqlite/sqlite.go    # SQLite backend
│   └── auth/auth.go            # Auth/RBAC/audit wrapper
├── pkg/                        # Reusable packages used by daemon and CLI
│   ├── config/                 # Set-command parser
│   ├── vpp/                    # VPP client interface
│   ├── frr/                    # FRR config generator
│   ├── datastore/              # SQLite/etcd datastore
│   ├── netconf/                # NETCONF/SSH server
│   ├── cli/                    # CLI session management
│   ├── auth/                   # Password/SSH key auth
│   ├── audit/                  # Audit logging
│   ├── device/                 # Hardware abstraction
│   ├── logger/                 # Structured logging
│   └── errors/                 # Error handling
├── build/
│   ├── systemd/                # systemd unit files
│   └── package/                # nfpm config and scripts
├── docs/                       # Documentation
├── examples/                   # Sample configurations and integration examples
└── Makefile                    # Build automation

---

Documentation

• Documentation Index - All docs in one place
• Roadmap - Planned feature scope
• VPP Setup Guide for Debian - VPP installation for Debian
• VPP Setup Guide for RHEL9 - VPP installation for RHEL9
• FRR Setup Guide for Debian - FRR installation for Debian
• FRR Setup Guide for RHEL9 - FRR installation for RHEL9
• Design Specification - Architecture and design decisions
• JSON Schema Convention - Naming conventions
• Changelog - Release history
• Support Policy - Support channels and expectations

---

Contributing

Contributions are welcome! See CONTRIBUTING.md.

---

License

Licensed under the Apache License 2.0. See LICENSE.

---

Support

• Community Support: GitHub Issues - https://github.com/akam1o/arca-router/issues
• Support Policy: See SUPPORT.md
• Security: See SECURITY.md

---

Acknowledgments

• VPP: FD.io Vector Packet Processing
• FRR: Free Range Routing
• NFPM: GoReleaser NFPM