wg-api-client 0.1.9

WireGuard Configuration API Client

WireGuard Configuration API Client

A comprehensive client library and CLI tool for interacting with the WireGuard Configuration Distribution API.

Table of Contents

• Features
• Installation
• Quick Start
• Command Reference
• Configuration Options
• Common Workflows
• Device Roles
• Device ID Generation
• Using as a Library
• Development
• Publishing
• License

Features

• Complete API client for the WireGuard Configuration Distribution API
• Command-line interface for all API operations
• Automatic token authentication and renewal
• Configuration file support
• WireGuard keypair generation
• WireGuard configuration file creation
• Hardware-based device ID generation for reliable device identification
• Custom device ID support for greater flexibility
• Support for custom routing tables and AllowedIPs in WireGuard configurations
• Multiple device roles (uxu, drone, fmo) with expandable architecture

Installation

From PyPI (Recommended)

pip install wg-api-client

From Source

git clone https://github.com/tiiuae/wg-api-client-lib.git
cd wg-api-client-lib
pip install -e .

Prerequisites

Ubuntu/Debian

sudo apt update
sudo apt install -y python3 python3-pip wireguard-tools

Fedora/CentOS/RHEL

sudo dnf install python3 python3-pip wireguard-tools

Quick Start

# Install the package
pip install wg-api-client

# Authenticate with the API
wg-api-client auth

# Get a WireGuard configuration file
wg-api-client get-config --output my-device.conf

# Apply the configuration
sudo wg-quick up my-device.conf

Command Reference

Global Parameters

These parameters can be used with any command:

--api-url URL         Base URL for the API
--hashed-credential HASH  Hashed credential for authentication
--config-file PATH    Path to configuration file (default: ~/.wg_api_config)

Authentication

wg-api-client auth

Authenticates with the API using the provided or configured hashed credential.

Device Configuration

wg-api-client get-config [OPTIONS]

Options:

• --role {uxu|drone|fmo} - Device role (default: uxu)
• --device-id ID - Custom device ID (generated from hardware if not provided)
• --public-key KEY - WireGuard public key (generated if not provided)
• --output FILE - Output configuration file (default: wg.conf)
• --allowed-ips CIDR - Additional IP ranges to allow (can be used multiple times)
• --table NAME or -t NAME - Set routing table for the WireGuard interface
• --listen-port PORT - Specify a listen port for the WireGuard interface

Device Management (Admin only)

# List all devices
wg-api-client list-devices

# Get information about a specific device
wg-api-client get-device DEVICE_ID

# Delete a device
wg-api-client delete-device DEVICE_ID

# Delete all devices
wg-api-client delete-all-devices [--confirm]

FMO Management (Admin only)

# Get current FMO device
wg-api-client get-fmo

# Remove FMO role from current device
wg-api-client delete-fmo

Credential Management (Admin only)

# Add a new credential
wg-api-client add-credential --hashed-credential HASH [--role {user|admin}]

Configuration Options

Configuration File

The tool stores configuration in ~/.wg_api_config by default. This includes:

• API URL
• Hashed credential
• Authentication token
• Refresh token

To specify a different configuration file location:

wg-api-client --config-file /path/to/config [command]

WireGuard Configuration Options

When generating a WireGuard configuration file, you can customize:

1. Device role (--role): uxu, drone, or fmo
2. Device ID (--device-id): Use a custom identifier or auto-generate
3. WireGuard keypair (--public-key): Provide an existing public key or auto-generate
4. Allowed IPs (--allowed-ips): Add custom IP ranges beyond the default (10.8.0.0/24)
5. Routing table (--table or -t): Specify a custom routing table name
6. Listen Port (--listen-port): Specify a custom listen port for the WireGuard interface

Example with all options:

wg-api-client get-config \
  --role drone \
  --device-id "drone-inspection-5" \
  --public-key "AbCdEf123..." \
  --allowed-ips 192.168.128.0/24 \
  --allowed-ips 172.16.0.0/16 \
  --table internet \
  --listen-port 51821 \
  --output drone-5.conf

Common Workflows

Basic Device Setup

# Authenticate
wg-api-client auth

# Generate config for a UXU device (default role)
wg-api-client get-config --output uxu.conf

# Apply configuration
sudo wg-quick up uxu.conf

Drone Device with Custom ID

# Generate configuration with descriptive ID
wg-api-client get-config \
  --role drone \
  --device-id "drone-inspection-team-1" \
  --output drone-team1.conf

FMO Device with Custom Routing Table

# Generate FMO configuration with custom routing table
wg-api-client get-config \
  --role fmo \
  --device-id "fmo-ground-station" \
  --table internet \
  --output fmo.conf

Custom Device with Specific Listen Port

# Generate configuration with custom listen port
wg-api-client get-config \
  --role uxu \
  --device-id "custom-device-1" \
  --listen-port 51822 \
  --output custom.conf

Administrator Tasks

# Check all registered devices
wg-api-client list-devices

# Add a new admin credential
wg-api-client add-credential --hashed-credential "your-hashed-credential" --role admin

# Clean up old devices
wg-api-client delete-device old-device-id

# Set up a new FMO (removing previous one if needed)
wg-api-client get-fmo
wg-api-client delete-fmo
wg-api-client get-config --role fmo --output new-fmo.conf

Device Roles

The client supports multiple device roles:

• uxu: Default role for UXU devices
• drone: For drone devices
• fmo: For Field Management Operator devices (only one can be active)

Each role may have different capabilities and network access within the WireGuard setup.

Device ID Generation

Custom Device ID

Using a custom device ID with the --device-id parameter offers:

• More descriptive names for easier management
• Alignment with your organization's naming conventions
• Better tracking across deployments
• Independence from hardware changes

Auto-generated ID

When no custom ID is provided, the client generates a unique ID based on hardware information:

1. Network interface MAC addresses
2. Machine UUID from OS-specific sources
3. Other machine-specific information

This ensures a stable, unique identifier that persists across reboots.

Using as a Library

from wg_api_client import WireGuardAPI, WireGuardHelper, DEFAULT_ROLE
from wg_api_client.unique_id import get_unique_device_id

# Initialize the API client
api = WireGuardAPI(
    api_url="your-api-url",
    hashed_credential="your-hashed-credential"
)

# Authenticate
api.authenticate()

# Generate a device ID
device_id = get_unique_device_id()

# Generate a keypair
private_key, public_key = WireGuardHelper.generate_keypair()

# Request configuration
success, config_data = api.request_wireguard_config(
    device_id=device_id,
    role="drone",
    public_key=public_key
)

if success:
    # Create configuration with additional options
    additional_allowed_ips = ["192.168.128.0/24"]
    routing_table = "internet"
    
    WireGuardHelper.create_client_config(
        config_data, 
        "drone.conf", 
        additional_allowed_ips, 
        routing_table
    )

Development

Setup Development Environment

# Clone repository
git clone https://github.com/tiiuae/wg-api-client-lib.git
cd wg-api-client-lib

# Install development dependencies
pip install -r requirements-dev.txt

# Install in development mode
pip install -e .

Run Tests

pytest

Run Linters

# Format code with Black
black .

# Sort imports
isort .

Project Structure

wg_api_client/
├── __init__.py   # Package initialization and version
├── __main__.py   # CLI entry point
├── api.py        # WireGuard API client
├── cli.py        # Command-line interface
├── config.py     # Configuration management
├── helper.py     # WireGuard utilities
└── unique_id.py  # Device ID generation

Publishing

Automatic Publishing

1. Update version in wg_api_client/__init__.py and setup.py
2. Create a GitHub release with tag v{version} (e.g., v0.1.2)
3. GitHub Actions will automatically build and publish to PyPI

Manual Publishing

For detailed instructions on manual publishing, see PUBLISHING.md.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.