LWS - Linux Web Services CLI

Features • Installation • Documentation • Contributing

---

Documentation

Complete documentation is published on GitHub Pages.

• Getting Started - Installation and first steps
• Architecture - Modular design and structure
• CLI Reference - Complete command reference
• API Reference - REST API endpoints
• Configuration - Advanced configuration
• Contributing - How to contribute

---

Overview

LWS is a command-line interface (CLI) tool for managing LXC containers on Proxmox VE hosts. It performs common tasks - creating, starting, stopping, terminating, and managing LXC instances, as well as interacting with Proxmox hosts themselves - from a single command.

Recent changes:

• Modular core: config/SSH/Proxmox/utility functions are extracted into lws_core/; the CLI command layer (lws.py) and the REST API (api.py) remain monolithic - see Architecture for the exact boundary
• REST API: programmatic access to LWS functionality over HTTP (api.py)
• Web UI: a single-page interface (ui.html) for interacting with the API
• Swagger documentation: interactive API documentation at /api/v1/docs
• Security and reliability fixes: allow-listed input validation on remote-command arguments, SSH host key verification and env-var password passing, non-zero exit codes on failure, a production WSGI server for the API, and a fixed Docker image build - see Security Considerations

Table of Contents

• Introduction
• Features
• Getting Started
• Usage
  • Proxmox Host Management
  • LXC Container Management
  • Docker Management
  • Container Backups & Restores
  • Monitoring & Reporting
  • Security Tools
  • Managing Scaling Thresholds and Triggers
  • API Server
  • Web UI
  • Swagger Documentation
• Security Considerations

Introduction

lws (Linux Web Services) is an open-source CLI tool for managing Proxmox hosts, LXC containers, and Docker services within those containers, through a single command set executed locally or over SSH.

Features

General

• Unified Interface: Manage Proxmox hosts, LXC containers, and Docker services with a single tool
• Remote Operations: Execute commands locally or remotely via SSH
• Error Handling: Robust error detection and reporting
• Logging: Comprehensive logging with both text and JSON formats
• Command Alias Support: Use short aliases for common commands

Proxmox Management

• Host Monitoring: Monitor CPU, memory, and disk usage of Proxmox hosts
• Cluster Operations: Manage Proxmox clusters (start, stop, restart)
• Template Management: Upload, create, and delete LXC templates
• Firewall Rules: Define and manage security groups and firewall rules
• Host Backups: Create and manage backups of Proxmox configurations

LXC Container Management

• Container Operations: Create, start, stop, reboot, and destroy containers
• Resource Scaling: Dynamically adjust CPU, memory, and storage resources
• Snapshot Management: Create, list, and delete container snapshots
• Network Configuration: Configure network settings for containers
• Volume Management: Attach and detach storage volumes to containers
• Container Migration: Migrate containers between Proxmox hosts
• Clone Containers: Create identical copies of existing containers
• Command Execution: Run arbitrary commands within containers
• Network Testing: Test network connectivity from containers
• Backup & Restore: Create and restore container backups

Docker Management

• Installation: Install Docker and Docker Compose within LXC containers
• Container Operations: Run, stop, and manage Docker containers
• Application Deployment: Deploy applications using Docker Compose
• Log Access: View logs from Docker containers
• Container Listing: List running Docker containers
• Application Updates: Update applications with new images

Security Tools

• Security Scanning: Perform security audits on containers
• Network Discovery: Discover reachable hosts in container networks
• Health Checks: Check CPU, memory, disk and DNS inside a container against fixed limits
• Monitoring: Monitor real-time resource usage with thresholds

Resource Reporting

• Advanced Container Reports: Generate comprehensive reports on container status and resources
• Resource Monitoring: Real-time monitoring of container CPU, memory, and disk usage
• Scaling Recommendations: Get intelligent scaling suggestions based on usage patterns

Getting Started

Prerequisites

• Python 3.10 or higher. The supported range is declared once, as requires-python in pyproject.toml, and the CI matrix and the Docker image are checked against it. The published image ships 3.14.
• Proxmox Virtual Environment 6.x or higher
• SSH access to Proxmox hosts
• The following Python packages:
  • click
  • pyyaml
  • requests
  • tqdm

Installation

1. Clone the repository:

git clone https://github.com/fabriziosalmi/lws.git
cd lws

2. Install required Python packages:

pip install -r requirements.txt

3. Create a configuration file config.yaml with your Proxmox server details:

regions:
  eu-south-1:
    availability_zones:
      az1:
        host: proxmox1.example.com
        user: root
        ssh_password: your_password
      az2:
        host: proxmox2.example.com
        user: root
        ssh_password: your_password

instance_sizes:
  small:
    memory: 512
    cpulimit: 1
    storage: local:8
  medium:
    memory: 1024
    cpulimit: 2
    storage: local:16
  large:
    memory: 2048
    cpulimit: 4
    storage: local:32

default_storage: local
default_network: vmbr0
use_local_only: false

4. Make the script executable and create an alias:

chmod +x lws.py && alias lws='python3 /path/to/lws.py'

5. Verify the installation:

lws --version

Usage

Proxmox Host Management

List Proxmox Hosts

lws px list

Check Host Status

lws px status --region eu-south-1 --az az1

List Clusters

lws px clusters --region eu-south-1 --az az1

Backup Proxmox Configuration

lws px backup /path/to/backup/directory --region eu-south-1 --az az1

Start/Stop/Restart Cluster Services

lws px cluster-start --region eu-south-1 --az az1
lws px cluster-stop --region eu-south-1 --az az1
lws px cluster-restart --region eu-south-1 --az az1

Execute Command on Proxmox Host

lws px exec "free -m" --region eu-south-1 --az az1

Upload Template to Proxmox

lws px upload ./ubuntu-20.04-template.tar.gz ubuntu-20.04 --region eu-south-1 --az az1

LXC Container Management

Create and Start LXC Container

lws lxc run --image-id local:vztmpl/ubuntu-20.04-standard_20.04-1_amd64.tar.gz --size small --count 3 --hostname web-server

Start/Stop/Reboot Container

lws lxc start 100 101 102
lws lxc stop 100 101 102
lws lxc reboot 100

Show Container Details

lws lxc show 100

Show All Containers

lws lxc show

Scale Container Resources

lws lxc scale 100 --memory 2048 --cpulimit 2 --storage-size 32G

Monitor Container Resources

lws lxc status 100

Execute Command in Container

lws lxc exec 100 "apt-get update"
lws lxc exec 100 "sh -c 'apt-get update && apt-get -y upgrade'"

The command runs in the container without a shell. For &&, | or redirections, wrap it in sh -c '...' as in the second line.

Create and Manage Snapshots

lws lxc snapshot-add 100 snap1
lws lxc snapshots 100
lws lxc snapshot-rm 100 snap1

Check Network Connectivity

lws lxc net 100 tcp 80

Show Container Info and IP

lws lxc show-info 100
lws lxc show-public-ip 100

Clone Container

lws lxc clone 100 101 --full

Scale Recommendations

lws lxc scale-check 100

Manage Container Services

lws lxc service status nginx 100
lws lxc service restart nginx 100

Advanced Health Check

lws lxc health-check 100 --fix

Resource Monitoring

lws lxc resources 100 --interval 5 --count 10

Generate Container Report

lws lxc report 100 --output json --file container_report.json

Container Backups & Restores

Create Container Backup

lws lxc backup-create 100 --download

Restore Container from Backup

lws lxc backup-restore 100 --backup-file /var/lib/vz/dump/vzdump-lxc-100-2026_10_10-02_00_00.tar.zst

Docker Management

Install Docker on Container

lws app setup 100

Run Docker Container

lws app run 100 -- -d -p 80:80 nginx

Deploy with Docker Compose

lws app deploy install 100 --compose-file docker-compose.yml --auto-start

Update Docker Compose Application

lws app update 100 docker-compose.yml

View Docker Logs

lws app logs 100 nginx --tail 100

List Docker Containers

lws app list 100

Remove Docker

lws app remove 100 --purge

Security Tools

Perform Security Scan

lws sec scan 100 --scan-type full

Network Discovery

lws sec discovery 100

Scaling Thresholds

lws lxc scale-check <id> reads the scaling section of config.yaml and prints suggested CPU core, memory and disk values for a container. It compares what the container is allocated (pct config) with the host's total cores and memory. Nothing runs automatically: apply a suggestion with lws lxc scale.

scaling:
  lxc_cpu:
    min_threshold: 0.30      # suggest more cores below 30% of the host's cores
    max_threshold: 0.80      # suggest fewer above 80%
    step: 1
    scale_up_multiplier: 1.5
    scale_down_multiplier: 0.5

  lxc_memory:
    min_threshold: 0.40
    max_threshold: 0.70
    step_mb: 256
    scale_up_multiplier: 1.25
    scale_down_multiplier: 0.75

  limits:
    min_cpu_cores: 1
    max_cpu_cores: 4
    min_memory_mb: 512
    max_memory_mb: 8192
    min_storage_gb: 10
    max_storage_gb: 500

Thresholds are fractions between 0 and 1. The full description of the keys is in the configuration reference.

API Server

The API server provides HTTP access to LWS functions.

1. Set a real api_key in config.yaml. The server refuses to start while it's empty or still the placeholder — generate one with python3 -c 'import secrets; print(secrets.token_urlsafe(32))'.

2. Run the API server:

   python3 api.py
   

   By default it listens on 127.0.0.1:8080 (loopback only). Change api.host/api.port in config.yaml if you need it reachable elsewhere — see the Security Considerations below before binding to anything but loopback.

3. Interact with the API: Use tools like curl, Postman, or the provided Web UI. Remember to include the API key in the X-API-Key header for protected endpoints.

   # Example: Health Check (no API key needed)
   curl http://localhost:8080/api/v1/health
   
   # Example: List LXC Instances (requires API key)
   curl -H "X-API-Key: your-secure-api-key" http://localhost:8080/api/v1/lxc/instances
   

Web UI

A simple web interface is provided to interact with the API.

1. Ensure the API server (api.py) is running.
2. Access the UI:
   • Navigate your browser to the root URL of the running API server (e.g., http://localhost:8080/). The API server serves ui.html directly.
   • Opening ui.html from disk (file:///.../ui.html) does not work: the page calls the API at a relative address.
3. Enter your API Key in the input field and use the buttons to trigger API calls. Responses will be displayed in a formatted view.

Swagger Documentation

Interactive API documentation is available via Swagger UI.

1. Ensure the API server (api.py) is running.
2. Access Swagger UI: Navigate your browser to /api/v1/docs relative to the API server's URL (e.g., http://localhost:8080/api/v1/docs).
3. You can explore the available endpoints, view parameters, and even try API calls directly from the Swagger interface (remember to authorize using your API key via the "Authorize" button).

Security Considerations

Critical Security Recommendations

• Secure Storage of Credentials:

  • LWS currently only supports password-based SSH authentication (via sshpass) — there is no SSH key-based auth, and no environment-variable or vault indirection for ssh_password. Both are read as plain values straight out of config.yaml
  • Until that changes, treat config.yaml as a credentials file: keep it out of version control (it is .gitignored — see config.yaml.example for the committed template) and don't reuse the passwords it holds elsewhere
  • Set restrictive file permissions on config.yaml (600 or 640)

• Network Security:

  • Use VPN or private networks for Proxmox host access
  • Configure firewall rules to restrict SSH access to known IP addresses
  • Change default SSH ports and disable password authentication when possible

• API Security:

  • Use strong, randomly generated API keys (minimum 32 characters)
  • Enable HTTPS/TLS for all API communications in production
  • Implement rate limiting to prevent abuse
  • Regularly rotate API keys

• Container Security:

  • Run lws sec scan regularly on your containers to detect security issues
  • Keep container images and software up to date
  • Use security groups to restrict network access between containers
  • Enable container logging and monitoring

• Input Validation:

  • Container/instance IDs are validated as numeric everywhere they're accepted (CLI arguments and the REST API)
  • Security group names, template names, firewall protocol/port fields, source/destination IP/CIDR values, and lxc run's free-text container-creation options (hostname, password, network config, DNS, lock) are validated against an allow-list, parsed as a real IP/CIDR, or shell-quoted for the remote command before being used - this closes the command-injection surface in the affected commands rather than attempting to escape it after the fact
  • host/user/ssh_password come from config.yaml, which you control, and aren't user-supplied CLI input - see Secure Storage of Credentials above for how to protect that file instead

• File Security:

Security Properties Currently Implemented

• Allow-listed validation (or shlex.quote) on every CLI value known to reach a remote shell/sed/grep command, instead of escaping output after construction
• API key compared with hmac.compare_digest (timing-safe); the server refuses to start with an empty or placeholder key
• SSH password passed via the SSHPASS environment variable, never in argv, ps, or logs
• SSH host key verification (StrictHostKeyChecking=accept-new): a changed key for an already-known host is rejected
• CORS denies all cross-origin browser access by default; origins must be listed explicitly
• api.py runs behind a production WSGI server (waitress) unless debug: true is explicitly set, and never enables Werkzeug's interactive debugger regardless of that setting
• Failed commands exit with a non-zero process exit code instead of looking like a success
• The Web UI (ui.html) renders API responses and error messages through textContent, not innerHTML, so a value reflected in a response cannot execute as markup in the viewer's browser

Best Practices

• Resource Planning: Use lws lxc scale-check to get recommendations on optimal resource allocation.
• Regular Backups: Create regular backups with lws lxc backup-create to prevent data loss.
• Monitoring: Use lws lxc resources to monitor resource usage patterns.
• Health Checks: Run lws lxc health-check periodically to detect and fix issues.
• Documentation: Generate reports with lws lxc report for documentation and auditing purposes.

Contributing

lws is an open-source, single-maintainer project. Issues, feature requests, and pull requests are welcome.

How to Contribute

1. Fork the Repository
2. Create a Branch

   git checkout -b feature-branch
   

3. Make Changes
4. Submit a Pull Request

[!TIP] Include clear commit messages and documentation with your pull requests to make the review process smoother.

Roadmap

Unscheduled, not committed to a release:

• SSH key-based authentication, as an alternative to the current password-only model
• Configuration versioning for container configurations
• Kubernetes cluster management, alongside the current Proxmox/LXC scope

License

MIT License. See LICENSE.

Acknowledgements

• Proxmox VE, the virtualization platform this tool manages
• Click, the CLI framework this tool is built on