Server/User Management

From Bondix Wiki
Revision as of 14:56, 22 January 2026 by Red (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

(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
Retrieved from "https://wiki.bondix.dev/index.php?title=Server/User_Management&oldid=936"