Server/User Management

(this is a work in progress article for the upcoming 1.26.01 Bondix release. Content is subject to change.)

Overview

The Managed User system provides a complete user management solution for the BondingServer, including tunnel management, port forwarding, QoS settings, and optional remote synchronization. This system is designed for multi-tenant scenarios where users need to manage their own tunnels through a dedicated web interface.

Modes of Operation

The system operates in two modes:

Local Mode (Default)

• Configuration stored in a local JSON file
• No remote synchronization
• Ideal for single-server deployments
• All configuration changes saved locally

Remote Mode

• Configuration synchronized with a remote server
• Periodic sync every 30 minutes
• Changes pushed to remote server automatically
• Events sent to webhook endpoint
• Ideal for distributed/multi-server deployments

Local Configuration File Layout

While users can be stored in the main server configuration, it’s discouraged. Using a separate configuration file offers greater flexibility and cleaner separation.

Recommended file: /path/to/managed-users.json

Structure:

{
   "version": 1,
   "config": {
       "user@example.com": {
           "password": "sha256_hash",
           "tunnels": [
               {
                   "config": {
                       "name": "office-tunnel",
                       "enabled": true,
                       "password": "tunnel_password",
                       "mtu": 1500,
                       "qos": "default"
                   }
               }
           ],
           "portForwarding": [],
           "qos": []
       },
       "admin@example.com": {
           "password": "sha256_hash",
           "tunnels": [
               {
                   "config": {
                       "name": "main-tunnel",
                       "enabled": true,
                       "password": "secure_pass",
                       "mtu": 1400,
                       "qos": "custom"
                   }
               }
           ],
           "portForwarding": [],
           "qos": {
               "classes": [
                   {
                       "name": "high-priority",
                       "priority": 1,
                       "bandwidth": 1000,
                       "rules": []
                   }
               ]
           }
       }
   }
}

Root Fields:

• version: Configuration version number (uint64, required)
• config: Object containing user configurations keyed by username

Per-User Fields:

• password: SHA256 hash of the user’s password
• tunnels: Array of tunnel configurations
• portForwarding: Array of port forwarding rules (currently not implemented!)
• qos: QoS configuration object
• Enabling Managed Users

Action: enable-user-management

The following command must be added to /etc/bondixserver.json

Configuration JSON:

{
   "target": "server",
   "action": "enable-user-management",
   "settings": {
       "config": "/path/to/managed-users.json"
   },
   "caFile": "/etc/ssl/certs/root-ca.pem"
}

{
   "target": "server",
   "action": "enable-user-management",
   "settings": {
       "config": "/var/lib/bonding/managed-users.json"
   }
}

Settings Object Fields:

• config: Path to local configuration file (string, required for local mode)
• configEndpoint: Remote sync URL (string, optional)
• configAuth: Authentication token for remote endpoints (string, optional)
• eventEndpoint: Webhook URL for events (string, optional)
• users: Array of initial users (optional, discouraged)

SSL/TLS Options:

• caDirectory: Directory containing CA certificates
• caFile: Single CA file path

Remote Mode Configuration

When configEndpoint is specified, the system operates in remote mode:

{
   "target": "server",
   "action": "enable-user-management",
   "settings": {
       "config": "/var/lib/bonding/managed-users.json",
       "configEndpoint": "https://management.example.com/api/config",
       "configAuth": "Bearer universal_auth_token",
       "eventEndpoint": "https://management.example.com/api/events"
   }
}

Remote Sync Behavior:

1. Initial Fetch: On startup, fetches configuration from remote endpoint
2. Periodic Sync: Every 30 minutes, checks for remote updates
3. Change Push: Every 5 seconds after local changes, syncs to remote
4. Version Control: Uses version numbers to prevent conflicts

Event Webhook Events:

password_request: Triggered when user requests password reset - Payload includes temporary password for the user

Remote Endpoint Requirements:

• configEndpoint must accept GET for fetch and POST for store
• Both endpoints require Authorization header with configured auth token
• Fetch returns 204 if no newer version exists, 200 with config JSON otherwise

Web Frontend

Frontend Location: /user

Automatic Redirect: When user management is enabled, the server automatically redirects requests from / to /user. Use /admin for full access.

The frontend provides:

• User login interface
• Tunnel management dashboard
• QoS settings management
• Password change functionality

TODO: Port forwarding configuration to be implemented.

API Endpoints

All endpoints require authentication via Bearer token or universal auth token.

Authentication Endpoints

POST /api/login

// Request
{
   "username": "user@example.com",
   "password": "password"
}

// Response (200 OK)
{
   "token": "session_token",
   "user": {
       "email": "user@example.com",
       "name": "User"
   }
}

// Response (401 Unauthorized)
{"allowReset": true}  // If eventEndpoint configured

POST /api/forgot-password

// Request
{
   "email": "user@example.com"
}

// Response: 204 No Content (if user exists and eventEndpoint configured)

Configuration Endpoints

GET /api/config

// Response
{
   "tunnels": [...],
   "portForwarding": [...],
   "qos": [...]
}

POST /api/config

// Request
{
   "tunnels": [
       {
           "config": {
               "name": "tunnel_name",
               "enabled": true,
               "password": "new_password",
               "mtu": 1500,
               "qos": "default"
           }
       }
   ],
   "portForwarding": [...],
   "qos": [...]
}

// Response
{
   "tunnels": [...],
   "portForwarding": [...],
   "qos": [...]
}

Important: This endpoint is the primary method for updating any configuration. When remote mode is enabled, calling this endpoint triggers the synchronization methods automatically.

POST /api/change-password

// Request
{
   "currentPassword": "old_password",
   "newPassword": "new_password"
}

// Response
{"result": "ok"}

Tunnel Management Endpoints

GET /api/status

// Response
{
   "tunnel": [
       {
           "name": "tunnel_name",
           "status": "connected|disconnected|disabled",
           "uptime": 12345,
           "clientIp": "10.0.0.1/24",
           "gatewayIp": "10.0.0.254",
           "channelConnected": 2,
           "currentIncoming": 1024,
           "currentOutgoing": 2048,
           "activeProxyConnections": 1,
           "qosName": "default",
           "totalIncoming": 1024000,
           "totalOutgoing": 2048000,
           "environment": "env_name",
           "connectedChannels": 2,
           "channels": [
               {
                   "status": "connected",
                   "enabled": true,
                   "name": "channel_name",
                   "interface": "eth0",
                   "address": "10.0.0.1",
                   "uptime": 3600,
                   "lastError": "",
                   "totalOutgoing": 512000,
                   "totalIncoming": 1024000,
                   "connectionAttempts": 1,
                   "connectionType": "TCP",
                   "stats": {
                       "currentLatency": 15,
                       "idleLatency": 10,
                       "inTransit": 1024,
                       "packetloss": 0.1
                   }
               }
           ]
       }
   ]
}

POST /api/restart

// Request
{
   "tunnel": "tunnel_name"
}

// Response
{"result": "ok"}

Universal Authentication Token

For third-party frontend integration or administrative operations, a universal auth token can be used to impersonate any user.

Authentication Method:

1. Set Authorization header to the configured configAuth token
2. Set X-Username header to the target user’s email

Example Request:

TODO: add request

....

Security Note: The universal auth token should be kept secure and only used for trusted applications.

Tunnel Configuration Structure

{
   "config": {
       "name": "tunnel_name",
       "enabled": true,
       "password": "tunnel_password",
       "mtu": 1500,
       "qos": "default|custom|<preset_name>"
   }
}

Fields:

• name: Unique tunnel identifier (string, required)
• enabled: Enable/disable tunnel (boolean, default: true)
• password: Tunnel password (string, required)
• mtu: MTU value between 1100-1500 (uint16, default: 1500)
• qos: QoS mode selection (string, default: “default”) - "default": Use client QoS settings - "custom": Use custom QoS configuration
• Other values: Use named QoS preset

Port Forwarding Configuration

TODO: currently not implemented

{
   "enabled": true,
   "tunnel": "tunnel_name",
   "publicPort": 8080,
   "targetIp": "192.168.1.100",
   "targetPort": 80,
   "description": "Web server forward"
}

Fields:

• enabled: Enable/disable this port forward (boolean)
• tunnel: Associated tunnel name (string)
• publicPort: External port number (uint16)
• targetIp: Internal target IP address (string)
• targetPort: Internal target port (uint16)
• description: Note/description (string, max 1024 chars)

QoS Configuration

TODO

Complete Example

Enable Managed Users (Local Mode):

{
   "target": "server",
   "action": "enable-user-management",
   "settings": {
       "config": "/var/lib/bonding/managed-users.json"
   }
}

Remote Mode with Events:

{
   "target": "server",
   "action": "enable-user-management",
   "settings": {
       "config": "/var/lib/bonding/managed-users.json",
       "configEndpoint": "https://management.example.com/api/config",
       "configAuth": "Bearer abc123universal456",
       "eventEndpoint": "https://management.example.com/api/events"
   },
   "caFile": "/etc/ssl/certs/root-ca.pem"
}

Initial Config File (/etc/bondix/managed-users.json):

{
   "version": 1,
   "config": {
       "admin@example.com": {
           "password": "5e884898da1904719...",
           "tunnels": [
               {
                   "config": {
                       "name": "office-tunnel",
                       "enabled": true,
                       "password": "secure123",
                       "mtu": 1500,
                       "qos": "default"
                   }
               }
           ],
           "portForwarding": [],
           "qos": []
       }
   }
}

Error Handling

Common Error Responses:

• {"result": "error", "error": "already enabled"} - Managed users already active
• 401 Unauthorized - Invalid or missing authentication
• 403 Forbidden - Invalid current password for change
• 500 Internal Server Error - Server-side errors

Version Conflicts:

When remote mode is enabled and version conflicts occur:

• Local changes with higher version take precedence
• Remote changes with higher version are applied
• Synchronization retries automatically

Password Management Details

Password Storage:

Passwords stored as SHA256 hashes (OpenSSL 1.x/3.x compatible), no plaintext password storage.

Password Reset Flow:

1. User POSTs to /api/forgot-password with email
2. Server generates 16-character temporary password
3. Event sent to eventEndpoint with eventType: "password_request"
4. Temporary password valid for 30 minutes
5. Rate-limited to 15 minutes between requests

Password Change:

• Requires current password verification
• New password hashed and stored
• Temporary password cleared on successful change

Synchronization Timing

Local Mode:

• Changes saved immediately to config file
• No periodic sync required

Remote Mode:

• Initial fetch on handler startup
• Store sync: Every 5 seconds after changes
• Fetch sync: Every 30 minutes if no pending changes
• Automatic retry on failure