Skip to main content

CLI Reference

Complete command-line reference for the noBGP agent. This covers all commands, options, and configuration methods.

Overview​

The nobgp command-line tool provides:

  • Agent runtime management
  • Configuration management
  • Service installation and control
  • Shared file system access
  • Diagnostic utilities

Command Structure​

nobgp [command] [options]

Commands​

nobgp agent​

Run the noBGP agent as a standalone process.

Usage:

nobgp agent [options]

Examples:

# Run with default config from /etc/nobgp/agent.yml
sudo nobgp agent

# Run with inline configuration
sudo nobgp agent --key "YOUR_KEY" --name "my-server"

# Run with debug output
sudo nobgp agent --debug

# Run with custom log level
sudo nobgp agent --log-level debug

Options:

OptionShortTypeDescription
--key-kstringNetwork authentication key (required if not in config)
--name-nstringNode name (defaults to hostname)
--router-rstringRouter WebSocket URL (default: wss://router.nobgp.com)
--debug-dbooleanEnable debug mode
--log-level-lstringLog level: error, warning, info, debug, trace (default: info)
--compress-zbooleanEnable compression (default: true)
--encrypt-ebooleanRequire encryption (default: true)
--interface-istringNetwork interface to use (default: auto)
--pingdurationPing interval for health checks (default: 58s)

Exit Codes:

  • 0 - Clean shutdown
  • 1 - General error
  • 2 - Configuration error
  • 3 - Network error

nobgp config​

Create or update the agent configuration file.

Usage:

nobgp config [options]

Examples:

# Interactive configuration
sudo nobgp config

# Set specific values
sudo nobgp config --key "YOUR_KEY"
sudo nobgp config --name "web-server-1"
sudo nobgp config --router "wss://custom.example.com"

# Set multiple values at once
sudo nobgp config --key "YOUR_KEY" --name "web-server-1" --debug

Options:

All options from nobgp agent are supported. Values provided are saved to /etc/nobgp/agent.yml.

Interactive Mode:

When run without options, enters interactive configuration:

$ sudo nobgp config

Agent Configuration
===================
Press Enter to keep current values, or type new values.

network-key: ************************************
node-name [current: my-server]: web-server-1
router [wss://router.nobgp.com]:
debug [false]:

Configuration saved to /etc/nobgp/agent.yml

nobgp service​

Manage the noBGP agent as a system service.

note

Service commands require systemd and do not work in Docker containers.

Usage:

nobgp service <subcommand>

Subcommands:

install​

Install the noBGP agent as a system service.

sudo nobgp service install

Creates a systemd service unit at /etc/systemd/system/nobgp.service and enables it to start on boot.

uninstall​

Remove the noBGP system service.

sudo nobgp service uninstall

Stops the service, disables it, and removes the service unit file.

start​

Start the noBGP service.

sudo nobgp service start

stop​

Stop the noBGP service.

sudo nobgp service stop

restart​

Restart the noBGP service.

sudo nobgp service restart

Equivalent to stop followed by start.

status​

Check the status of the noBGP service.

sudo nobgp service status

Example output:

● nobgp.service - noBGP Agent
     Loaded: loaded (/etc/systemd/system/nobgp.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2024-11-04 10:30:15 GMT; 2h 15min ago
   Main PID: 1234 (nobgp)
      Tasks: 5 (limit: 4915)
     Memory: 32.5M
        CPU: 1.234s
     CGroup: /system.slice/nobgp.service
             └─1234 /usr/bin/nobgp agent

Nov 04 10:30:15 server systemd[1]: Started noBGP Agent.
Nov 04 10:30:16 server nobgp[1234]: Connected to router

nobgp version​

Display the noBGP agent version.

Usage:

nobgp version

Example output:

noBGP Agent v0.2.1
Build: 2024-03-20
Git Commit: abc123def
Go Version: go1.22.1
OS/Arch: linux/amd64

nobgp help​

Display help information.

Usage:

nobgp help [command]

Examples:

# General help
nobgp help

# Help for specific command
nobgp help agent
nobgp help config
nobgp help service

Configuration File​

Location​

/etc/nobgp/agent.yml

Format​

YAML format with the following structure:

# Required
network-key: "VSH8vKlciUXLyFcnKptFBoQmhYQvq4PqC3/l0FrG/qQ="

# Optional (with defaults)
node-name: "my-server"
router: "wss://router.nobgp.com"
debug: false
log-level: "info"
compress: true
encrypt: true
interface: "auto"
ping-interval: "58s"

Configuration Priority​

Configuration is loaded in this order (later values override earlier):

  1. Configuration file (/etc/nobgp/agent.yml)
  2. Environment variables
  3. Command-line options

Example Configuration Files​

Minimal:

network-key: "VSH8vKlciUXLyFcnKptFBoQmhYQvq4PqC3/l0FrG/qQ="

Production:

network-key: "VSH8vKlciUXLyFcnKptFBoQmhYQvq4PqC3/l0FrG/qQ="
node-name: "web-server-1"
router: "wss://router.nobgp.com"
log-level: "warning"
compress: true
encrypt: true
ping-interval: "58s"

Development:

network-key: "VSH8vKlciUXLyFcnKptFBoQmhYQvq4PqC3/l0FrG/qQ="
node-name: "dev-machine"
debug: true
log-level: "debug"
compress: false

Environment Variables​

All configuration options can be set via environment variables:

VariableEquivalent ConfigExample
NOBGP_NETWORK_KEYnetwork-keyexport NOBGP_NETWORK_KEY="abc..."
NOBGP_NODE_NAMEnode-nameexport NOBGP_NODE_NAME="server1"
NOBGP_ROUTERrouterexport NOBGP_ROUTER="wss://router.nobgp.com"
NOBGP_DEBUGdebugexport NOBGP_DEBUG=true
NOBGP_LOG_LEVELlog-levelexport NOBGP_LOG_LEVEL="debug"
NOBGP_COMPRESScompressexport NOBGP_COMPRESS=true
NOBGP_ENCRYPTencryptexport NOBGP_ENCRYPT=true
NOBGP_INTERFACEinterfaceexport NOBGP_INTERFACE="eth0"
NOBGP_PING_INTERVALping-intervalexport NOBGP_PING_INTERVAL="120s"

Usage:

export NOBGP_NETWORK_KEY="YOUR_KEY"
export NOBGP_NODE_NAME="server1"
export NOBGP_DEBUG=true

sudo -E nobgp agent
tip

Use -E flag with sudo to preserve environment variables.

Log Levels​

The --log-level option controls output verbosity:

LevelDescriptionUse Case
errorOnly errorsProduction (minimal logging)
warningErrors and warningsProduction (standard)
infoInformational messagesDefault
debugDetailed debug informationDevelopment
traceVery detailed tracingTroubleshooting

Examples:

# Minimal output
nobgp agent --log-level error

# Standard production
nobgp agent --log-level warning

# Development
nobgp agent --log-level debug

# Detailed troubleshooting
nobgp agent --log-level trace

Exit Signals​

The agent handles standard Unix signals:

SignalBehavior
SIGTERMGraceful shutdown
SIGINT (Ctrl+C)Graceful shutdown
SIGHUPReload configuration
SIGUSR1Increase log level
SIGUSR2Decrease log level

Examples:

# Gracefully stop the agent
sudo pkill -TERM nobgp

# Reload configuration without restarting
sudo pkill -HUP nobgp

# Temporarily increase logging
sudo pkill -USR1 nobgp

Logging​

Service Logs​

When running as a service, logs go to systemd journal:

# View recent logs
sudo journalctl -u nobgp.service

# Follow logs in real-time
sudo journalctl -u nobgp.service -f

# View logs from the last hour
sudo journalctl -u nobgp.service --since "1 hour ago"

# View logs with priority
sudo journalctl -u nobgp.service -p err  # Only errors
sudo journalctl -u nobgp.service -p warning  # Warnings and errors

Standalone Logs​

When running standalone, logs go to stdout/stderr:

# Standard output
sudo nobgp agent

# Redirect to file
sudo nobgp agent > /var/log/nobgp.log 2>&1

# Pipe to logger
sudo nobgp agent 2>&1 | logger -t nobgp

Common Usage Patterns​

Development Workflow​

# Quick test with inline config
sudo nobgp agent --key "KEY" --name "dev-$(whoami)" --debug

# Monitor logs in another terminal
sudo journalctl -u nobgp.service -f

Production Deployment​

# 1. Configure once
sudo nobgp config --key "KEY" --name "$(hostname)" --log-level warning

# 2. Install service
sudo nobgp service install

# 3. Start and enable
sudo nobgp service start

# 4. Verify
sudo nobgp service status

Containerized Deployment​

# Use environment variables
docker run -d \
  --name nobgp \
  --cap-add NET_ADMIN \
  --device /dev/net/tun \
  -e NOBGP_NETWORK_KEY="KEY" \
  -e NOBGP_NODE_NAME="container-$(hostname)" \
  nobgp:latest

Debugging Connection Issues​

# Run with maximum logging
sudo nobgp agent --log-level trace --debug

# Check if router is reachable
curl https://router.nobgp.com

# Verify network key format
echo "YOUR_KEY" | base64 -d  # Should decode without errors

Configuration Best Practices​

1. Use Configuration File in Production​

Good:

sudo nobgp config --key "KEY" --name "server"
sudo nobgp service install

Avoid:

sudo nobgp agent --key "KEY" --name "server"  # Inline config

2. Set Appropriate Log Levels​

  • Production: warning or error
  • Development: info or debug
  • Troubleshooting: debug or trace

3. Use Descriptive Node Names​

Good:

  • web-server-prod-1
  • api-server-staging
  • db-primary-us-east

Avoid:

  • server1
  • node
  • test

4. Secure Your Configuration File​

# Restrict permissions
sudo chmod 600 /etc/nobgp/agent.yml
sudo chown root:root /etc/nobgp/agent.yml

5. Monitor Service Health​

# Add to cron or monitoring system
*/5 * * * * systemctl is-active nobgp.service || systemctl restart nobgp.service

Troubleshooting Commands​

Check Configuration​

# View current config
cat /etc/nobgp/agent.yml

# Validate YAML syntax
python3 -c "import yaml; yaml.safe_load(open('/etc/nobgp/agent.yml'))"

Test Connectivity​

# Check router accessibility
curl -v https://router.nobgp.com

# Test WebSocket connection
websocat wss://router.nobgp.com  # If websocat is installed

Diagnose Service Issues​

# Check service status
sudo nobgp service status

# View service logs
sudo journalctl -u nobgp.service -n 100

# Check for errors
sudo journalctl -u nobgp.service -p err

# Restart service
sudo nobgp service restart

Resource Usage​

# Check process
ps aux | grep nobgp

# Memory usage
ps -o pid,user,%mem,rss,command -C nobgp

# CPU usage
top -p $(pgrep nobgp)

Advanced Topics​

Custom Router​

Enterprise Feature

Custom routers are available for enterprise deployments only. Contact sales@nobgp.com for more information.

For enterprise deployments with custom routers:

router: "wss://custom-router.example.com:8080"

Multiple Networks​

Run multiple agents on the same machine (different networks):

# Network 1
sudo nobgp agent --key "KEY1" --name "server-net1"

# Network 2 (in another terminal or via systemd)
sudo nobgp agent --key "KEY2" --name "server-net2"

Interface Selection​

Force specific network interface:

interface: "eth0"  # Or eth1, wlan0, etc.

Next Steps​

See Also​

  • Configuration file: /etc/nobgp/agent.yml
  • Service unit: /etc/systemd/system/nobgp.service
  • Binary location: /usr/bin/nobgp (or /usr/local/bin/nobgp)