Skip to content

server.md

Latest commit

 

History

History
228 lines (174 loc) · 8.14 KB

server.md

File metadata and controls

228 lines (174 loc) · 8.14 KB

Bolt Server Documentation

Overview

Bolt is a production-ready Python-based server for managing lightweight sandboxes on Debian/Ubuntu systems. It uses debootstrap to create sandbox environments, cgroups for resource limiting, iptables for port forwarding, and a custom TCP-based shell for remote access. The server provides a secure HTTPS API with authentication, supports project-based sandbox grouping, and includes features like port forwarding (host-to-sandbox and sandbox-to-host), resource management, and detailed status reporting.

Features

  • Sandbox Management: Create and delete sandboxes from Debian/Ubuntu base images.
  • Project Grouping: Organize sandboxes into projects for better management.
  • Resource Limits: Configure CPU and memory limits per project using cgroups.
  • Port Forwarding: Support both host-to-sandbox and sandbox-to-host port forwarding.
  • TCP Shell: Secure, token-based remote shell access to sandboxes.
  • HTTPS API: Secure API with HTTP Basic Authentication and SSL/TLS.
  • Systemd Integration: Runs as a systemd service under a dedicated bolt user.
  • Runtime Tracking: Accurate tracking of project and sandbox creation times.
  • Update Checks: Checks for server updates via an API endpoint.
  • Security: Input sanitization, restricted file permissions, and namespace isolation with unshare.

Requirements

  • Debian or Ubuntu server with cgroups enabled.
  • Installed packages: debootstrap, iptables, cgroup-tools, openssl, python3, python3-pip.
  • Python dependencies: flask, werkzeug, psutil, netifaces, requests.
  • A dedicated bolt user for running the server.

Installation

Step 1: Install Dependencies

sudo apt update
sudo apt install debootstrap iptables python3 python3-pip cgroup-tools openssl
pip3 install flask werkzeug psutil netifaces requests

Step 2: Create Dedicated User

sudo useradd -r -s /bin/false -d /var/bolt bolt

Step 3: Setup Directories and Permissions

sudo mkdir -p /var/bolt/sandboxes /var/bolt/projects /var/bolt/base_images /var/log/bolt /etc/bolt
sudo chown -R bolt:bolt /var/bolt /var/log/bolt
sudo chmod -R 750 /var/bolt /etc/bolt
sudo touch /var/log/bolt_server.log
sudo chown bolt:bolt /var/log/bolt_server.log
sudo chmod 640 /var/log/bolt_server.log
sudo mkdir -p /sys/fs/cgroup/cpu/bolt /sys/fs/cgroup/memory/bolt
sudo chown -R bolt:bolt /sys/fs/cgroup/cpu/bolt /sys/fs/cgroup/memory/bolt
sudo chmod -R 750 /sys/fs/cgroup/cpu/bolt /sys/fs/cgroup/memory/bolt

Step 4: Install Server

Copy the bolt_server.py script to /usr/local/bin:

sudo cp bolt_server.py /usr/local/bin/bolt_server.py
sudo chown bolt:bolt /usr/local/bin/bolt_server.py
sudo chmod 750 /usr/local/bin/bolt_server.py

Step 5: Setup Systemd Service

Create /etc/systemd/system/bolt.service with the following content:

[Unit]
Description=Bolt Sandbox Server
After=network.target

[Service]
User=bolt
Group=bolt
ExecStart=/usr/bin/python3 /usr/local/bin/bolt_server.py --host 0.0.0.0 --port 5000
Restart=always
RestartSec=10
Environment=PYTHONUNBUFFERED=1

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo cp bolt.service /etc/systemd/system/bolt.service
sudo chmod 644 /etc/systemd/system/bolt.service
sudo systemctl enable bolt
sudo systemctl start bolt

Step 6: SSL Configuration

The server generates a self-signed certificate at /etc/bolt/cert.pem and /etc/bolt/key.pem if none exist. For production, replace these with a trusted certificate from a Certificate Authority.

Configuration

The server configuration is stored in /etc/bolt/config.json with the following defaults:

{
    "admin_user": "admin",
    "admin_password": "<hashed_password>",
    "base_image_dir": "/var/bolt/base_images",
    "default_distro": "debian:bullseye",
    "allowed_ports": [10000, 10001, ..., 19999],
    "shell_port_range": [20001, 20002, ..., 25000],
    "default_resource_limits": {
        "cpu_quota_us": 100000,
        "memory_limit_bytes": 536870912
    },
    "shell_token_expiry": 3600
}
  • Update the admin credentials via the /api/config endpoint.
  • File permissions are set to 0600 for security.
  • Logs are written to /var/log/bolt_server.log.

API Endpoints

All endpoints require HTTP Basic Authentication with the admin credentials and are served over HTTPS.

Project Management

  • Create Project: POST /api/projects
    • Payload: { "name": "project_name" }
    • Response: 201 Created or 400 Bad Request
  • Delete Project: DELETE /api/projects/<name>
    • Response: 200 OK or 400 Bad Request

Sandbox Management

  • Create Sandbox: POST /api/projects/<project_name>/sandboxes
    • Payload: { "name": "sandbox_name", "distro": "debian:bullseye" }
    • Response: 201 Created or 400 Bad Request
  • Delete Sandbox: DELETE /api/projects/<project_name>/sandboxes/<name>
    • Response: 200 OK or 400 Bad Request

Shell Access

  • Start Shell: POST /api/projects/<project_name>/sandboxes/<name>/shell
    • Response: 200 OK with { "port": <port>, "token": <token> } or 400 Bad Request

Port Forwarding

  • Forward Port (Host to Sandbox): POST /api/projects/<project_name>/sandboxes/<name>/ports
    • Payload: { "host_port": 10001, "container_port": 80 }
    • Response: 200 OK or 400 Bad Request
  • Remove Port Forward: DELETE /api/projects/<project_name>/sandboxes/<name>/ports/<host_port>
    • Response: 200 OK or 400 Bad Request
  • Reverse Port Forward (Sandbox to Host): POST /api/projects/<project_name>/sandboxes/<name>/reverse_ports
    • Payload: { "container_port": 8080, "host_port": 10002 }
    • Response: 200 OK or 400 Bad Request
  • Remove Reverse Port Forward: DELETE /api/projects/<project_name>/sandboxes/<name>/reverse_ports/<container_port>
    • Response: 200 OK or 400 Bad Request

Resource Limits

  • Set Resource Limits: PUT /api/projects/<project_name>/resources
    • Payload: { "cpu_quota_us": 50000, "memory_limit_bytes": 268435456 }
    • Response: 200 OK or 400 Bad Request

Configuration

  • Update Admin Credentials: PUT /api/config
    • Payload: { "admin_user": "newadmin", "admin_password": "newpass" }
    • Response: 200 OK or 400 Bad Request

Status and Updates

  • Server Status: GET /api/status

    • Response: 200 OK with system and project details

    • Example:

      {
    "projects": [
        {
            "name": "project1",
            "sandboxes": [
                {
                    "name": "sandbox1",
                    "distro": "debian:bullseye",
                    "created_at": "2025-05-21T10:00:00",
                    "port_mappings": { "10001": 80 },
                    "reverse_port_mappings": { "8080": 10002 }
                }
            ],
            "resource_limits": { "cpu_quota_us": 100000, "memory_limit_bytes": 536870912 },
            "created_at": "2025-05-21T09:00:00"
        }
    ],
    "system": {
        "cpu_usage": 10.5,
        "memory_usage": 75.2,
        "disk_usage": 20.1
    },
    "version": "1.0.0"
}

  • Check Updates: GET /api/update

    • Response: 200 OK with { "update_available": true, "latest_version": "1.0.1", "current_version": "1.0.0" }

Security Considerations

  • HTTPS: Use a trusted certificate in production.
  • Shell Authentication: TCP shells require a unique token, valid for 1 hour.
  • Permissions: Files and directories are owned by the bolt user with restricted permissions (750 for directories, 600 for files).
  • Isolation: Sandboxes use unshare for namespace isolation and cgroups for resource limits.
  • Input Sanitization: All inputs are sanitized to prevent injection attacks.
  • Firewall: Restrict access to ports 5000 (API) and 20001–25000 (shells) using a firewall (e.g., ufw).

Troubleshooting

  • Check logs at /var/log/bolt_server.log for errors.
  • Ensure cgroups are mounted: mount -t cgroup -o cpu cpu /sys/fs/cgroup/cpu.
  • Verify the bolt user has appropriate permissions.
  • If HTTPS fails, check certificate validity and permissions.