Skip to main content

Installation

Detailed installation instructions for AthenaBNG.

Prerequisites​

  • Debian 13 (Trixie) with Linux 6.x kernel
  • Root or sudo access
  • Minimum 4GB RAM, recommended 8GB+
  • 50GB+ storage for logs and session database
  • Network interfaces configured and up

Required Packages​

sudo apt-get update
sudo apt-get install -y \
  build-essential \
  git \
  accel-ppp \
  frr \
  nftables \
  net-snmp \
  python3-venv \
  python3-dev

Rust Toolchain (for source builds)​

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
rustup default stable

Installation Methods​

Method 1: Build from Source​

# Clone repository
git clone https://gitlab.athenanetworks.com.au/athenanetworks/athena-bng.git
cd athena-bng

# Build and install
make install-all

# Verify installation
/opt/athena-bng/bin/abngd --version

Build targets:

  • make build — Debug build
  • make release — Optimized release build
  • make install-dirs — Create directory structure
  • make install — Install binaries
  • make install-api — Install Python API
  • make install-services — Install systemd units
  • make install-all — All of the above

Method 2: Debian Package​

# Build package
cd athena-bng
make deb

# Install
sudo dpkg -i ../athenabng_0.1.0_amd64.deb

# Verify
dpkg -l | grep athenabng

Method 3: Ansible Playbook​

cd athena-bng/ansible

# Copy and edit inventory
cp inventory.ini.example inventory.ini
# Edit inventory.ini with your target hosts

# Run playbook
ansible-playbook -i inventory.ini playbook.yml

Post-Installation Setup​

1. Create Configuration​

# Copy base configuration (all services disabled)
sudo cp /opt/athena-bng/config/AthenaBNG.yaml.base \
  /opt/athena-bng/etc/running-config.yaml

# Or use the example configuration
sudo cp /opt/athena-bng/config/AthenaBNG.yaml.example \
  /opt/athena-bng/etc/running-config.yaml

2. Edit Configuration​

sudo nano /opt/athena-bng/etc/running-config.yaml

Minimum required changes:

  • Set system.hostname to your BNG hostname
  • Set system.router_id to a loopback IP (e.g., 10.255.0.1)
  • Set interface names to match your hardware:
    • interfaces.management — Management interface
    • interfaces.subscriber_trunk — Subscriber-facing trunk
    • interfaces.upstream — Upstream/transit interface

3. Enable Services​

Start with the base config (all disabled) and enable services one at a time:

# Enable VLAN demux
abng# set demux enabled true
abng# set demux profiles[0] name "residential"
abng# set demux profiles[0] trunk_interface "eth1"

# Enable PPPoE
abng# set pppoe enabled true
abng# set pppoe ac_name "AthenaBNG"

# Enable RADIUS
abng# set radius servers[0] host "10.255.0.10"
abng# set radius servers[0] secret "your-secret"

# Commit changes
abng# commit

4. Start Services​

# Start all services
sudo systemctl start AthenaBNG.target

# Check status
sudo systemctl status AthenaBNG.target

# Enable auto-start on boot
sudo systemctl enable AthenaBNG.target

5. Verify Installation​

# Check service status
sudo systemctl status abngd
sudo systemctl status abng-demux
sudo systemctl status abng-dhcpd
sudo systemctl status abng-qos

# Check logs
sudo journalctl -u abngd -n 20

# Test CLI
/opt/athena-bng/bin/abng -c "show version"

Troubleshooting Installation​

Services fail to start​

Check logs:

sudo journalctl -u abngd -f
sudo journalctl -u abng-demux -f

Common issues:

  • Socket permission denied — Ensure /opt/athena-bng/run/ is writable
  • Port already in use — Check if another service is using the port
  • Configuration error — Validate YAML syntax in running-config.yaml

CLI cannot connect to abngd​

# Check if abngd is running
sudo systemctl status abngd

# Check socket exists
ls -la /opt/athena-bng/run/abngd.sock

# Try connecting with explicit socket path
/opt/athena-bng/bin/abng --socket /opt/athena-bng/run/abngd.sock

Build fails​

Ensure Rust toolchain is up to date:

rustup update
cargo --version

Check for required system packages:

apt-get install -y build-essential pkg-config libssl-dev

Next Steps​

  1. Quick Start — Get a minimal system running
  2. Configuration — Configure services
  3. CLI Reference — Learn the CLI