Server/User Management

From Bondix Wiki
Revision as of 11:57, 22 January 2026 by Red (talk | contribs) (add page; work in progress)
(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.)

Managed User Configuration Documentation

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

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

- Port forwarding configuration

- QoS settings management

- Password change functionality

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

<syntaxhighlight lang="json">// Request - Update any combination of tunnels, port forwarding, or QoS { 

// 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

<syntaxhighlight lang="json">// Response { 

// 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"}

7. 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

{
   "classes": [
       {
           "name": "class_name",
           "priority": 1,
           "bandwidth": 1000,
           "rules": [...]
       }
   ]
}


Fields:

- classes: Array of QoS classes

- name: Class identifier (string)

- priority: Priority level (uint16)

- bandwidth: Bandwidth allocation (uint16)

- rules: Traffic classification rules

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 (/var/lib/bonding/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=934"