Getting Started with noBGP

noBGP simplifies distributed infrastructure by creating a unified network across multiple environments. It eliminates the complexity of connecting applications and services across clouds, data centers, and container environments.

Introduction

noBGP provides a powerful networking solution for seamless connectivity between distributed applications and services. Key features include:

• Zero-configuration networking across multiple environments
• Secure, encrypted communication between nodes
• Automatic service discovery
• Real-time network topology visualization
• Cross-cloud and cross-datacenter connectivity

Prerequisites

Before installing the noBGP agent, ensure your system meets these requirements:

• Linux-based operating system:
  • Alpine Linux 3.16+
  • Amazon Linux 2023+
  • Debian 11+ / Ubuntu 20.04+
• Root or sudo privileges
• Network connectivity to the noBGP router
• Supported architectures:
  • amd64 (x86_64)
  • arm64 (aarch64)
• System requirements:
  • 512MB RAM minimum
  • 1GB disk space
  • Network interface with IP connectivity

Installation

Obtaining a Network Key

To use noBGP, you need a network key:

1. Visit https://router.nobgp.com
2. Create an account or sign in
3. Navigate to the "Networks" section
4. Create a new network or select an existing one
5. Copy the network key (base64 format, e.g., VSH8vKlciUXLyFcnKptFBoQmhYQvq4PqC3/l0FrG/qQ=)

The network key authenticates your nodes and connects them securely to your private network. You can modify or revoke this key via the web interface or generate new keys with different permissions for the same network.

Installation and Upgrade

noBGP provides an installation script that detects your system and installs the appropriate agent package. You can use either curl or wget:

Using curl:

# Install latest released version
curl -sSL https://downloads.nobgp.com/agent/install.sh | sudo sh

# Install a specific version
curl -sSL https://downloads.nobgp.com/agent/install.sh | sudo NOBGP_VERSION=0.2.1 sh

# Keep the downloaded package file
curl -sSL https://downloads.nobgp.com/agent/install.sh | sudo KEEP_PACKAGE=true sh

Or using wget:

# Download and run the installation script
wget -qO- https://downloads.nobgp.com/agent/install.sh | sudo sh

The installation script supports:

• Alpine Linux 3.16+
• Amazon Linux 2023+
• Debian 11+ / Ubuntu 20.04+

And the following architectures:

• amd64 (x86_64)
• arm64 (aarch64)

After installation, the nobgp command will be available in your system. After configuration, you can run the noBGP agent as a standalone process or system service.

Docker

To run nobgp within a docker container add the following options:

docker run -it --cap-add NET_ADMIN --device=/dev/net/tun alpine

Once within the container, you can install curl and then run through the installation script.

Configuration

The noBGP agent can be configured through multiple methods:

1. Web Interface: Manage certain configuration options through the noBGP web application
2. Configuration File: Local settings stored in a YAML file
3. Command Line Options: Options passed directly to the nobgp command
4. Interactive Configuration: Guided setup process
5. Environment Variables: System environment variables for automation

Configuration File

The noBGP agent uses a YAML configuration file located at /etc/nobgp/agent.yml. A minimal configuration file looks like:

network-key: "VSH8vKlciUXLyFcnKptFBoQmhYQvq4PqC3/l0FrG/qQ="
node-name: "web-server-1"
router: "wss://router.nobgp.com"

Important: The noBGP agent monitors the configuration file for changes. When you modify the configuration file while the agent is running, the new settings will be automatically applied with minimal network disruption.

Configuration Options

Config File Key	Command Line Option	Environment Variable	Required	Description	Default
network-key	-k, --key	NOBGP_NETWORK_KEY	Yes	Authentication key for the network	(required)
node-name	-n, --name	NOBGP_NODE_NAME	No	Name of the node in the network	Hostname
router	-r, --router	NOBGP_ROUTER	No	URL of the noBGP router	wss://router.nobgp.com
debug	-d, --debug	NOBGP_DEBUG	No	Enable debug mode	false
log-level	-l, --log-level	NOBGP_LOG_LEVEL	No	Logging level (error, warning, info, debug, trace)	info
compress	-z, --compress	NOBGP_COMPRESS	No	Enable compression	true
encrypt	-e, --encrypt	NOBGP_ENCRYPT	No	Require encryption	true
interface	-i, --interface	NOBGP_INTERFACE	No	Network interface to use	auto
ping-interval	--ping	NOBGP_PING_INTERVAL	No	Interval for connection health checks	58s

Using the Config Command

Create or update your configuration using the nobgp config command:

# Set the network key
sudo nobgp config --key "VSH8vKlciUXLyFcnKptFBoQmhYQvq4PqC3/l0FrG/qQ="

# Set the node name
sudo nobgp config --name "web-server-1"

# Set the router URL
sudo nobgp config --router "wss://custom-router.example.com"

The command saves your settings to the configuration file for future runs.

Quick Configuration

For a quick setup, run the nobgp config command without parameters:

sudo nobgp config

This starts an interactive session where you'll be prompted to enter or confirm values for required configuration options:

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

network-key: 
node-name: web-server-1

Configuration saved to /etc/nobgp/agent.yml

Environment Variables

Environment variables override configuration settings without modifying the configuration file. This is useful for automation or containerized environments.

Command Line Options

Override configuration settings with command line options when running nobgp:

sudo nobgp agent --key "YOUR_NETWORK_KEY" --name "web-server-1" --debug

Web Application Configuration

Manage your noBGP network through the web interface at https://router.nobgp.com:

• Network creation and management
• Network key management
• Node authorization and discovery
• Network topology visualization
• Connection monitoring

Changes made through the web application to your network configuration automatically propagate to your nodes, potentially causing them to restart to apply new settings.

Running the noBGP Agent

Running as a Standalone Process

Start the noBGP agent as a standalone process:

sudo nobgp agent

This connects to the router and sets up the required networking components.

For verbose output, add the debug flag or set the log level:

sudo nobgp agent --debug

Service Management

Run the noBGP agent as a system service for automatic startup (recommended for production environments). The service automatically starts on system boot and can be managed using standard system commands. Service commands do not work in docker containers.

# Install the service
sudo nobgp service install

# Check service status
sudo nobgp service status

# Start the service
sudo nobgp service start

# Stop the service
sudo nobgp service stop

# Restart the service
sudo nobgp service restart

# Uninstall the service
sudo nobgp service uninstall

When running as a service, the noBGP agent uses the settings from your configuration file.

Usage

When the noBGP agent runs on your system, you can access any other node on the same network by simply using their name.

Troubleshooting

If you encounter issues:

1. Enable debug mode: sudo nobgp agent --debug
2. Check the logs: sudo journalctl -u nobgp.service (when running as a service)
3. Verify the configuration file: cat /etc/nobgp/agent.yml
4. Ensure your network key is valid and correctly entered
5. Check that the router URL is accessible from your machine
6. Verify that you have root privileges when running the noBGP agent

Common Issues and Solutions

Issue	Possible Cause	Solution
Connection failed	Invalid network key	Verify key in web interface
Service won't start	Missing permissions	Check sudo access
Node not visible	Firewall blocking	Check router access

For more detailed troubleshooting and support, visit https://www.nobgp.com/contact.

Support and Resources

• Official Documentation: https://docs.nobgp.com/
• GitHub Repository: https://github.com/nobgp/nobgp-agent
• Official Website: https://www.nobgp.com/

License

The noBGP agent and noBGP router are proprietary software. All rights reserved. Unauthorized copying, modification, distribution, or use of this software, via any medium, is strictly prohibited. Users of the software must comply with the terms of the license agreement.

For licensing inquiries, please contact licensing@nobgp.com.