diff --git a/DOCS/embedded/lxc-framework.md b/DOCS/embedded/lxc-framework.md new file mode 100644 index 00000000..46df23b7 --- /dev/null +++ b/DOCS/embedded/lxc-framework.md @@ -0,0 +1,66 @@ +# SecuBox LXC Framework (Preview) + +**Version:** 1.0.0 +**Last Updated:** 2025-12-28 +**Status:** Active + +This document captures the baseline LXC tooling added in Step 8. It is a foundation for future “SecuBox Apps” packaged as LXC containers (e.g., Lyrion) and explains the combined CLI/UCI workflow. + +--- + +## Components + +1. **UCI config:** `/etc/config/lxcapps` (one section per container). +2. **Storage root:** `/srv/lxc//` (rootfs, config, logs). +3. **Templates:** `/usr/share/secubox/lxc/templates/` (scripts/tarballs; default `debian`). +4. **CLI helper:** `secubox-tools/lxc/secubox-lxc` (install to `/usr/sbin/secubox-lxc`). + +`secubox-lxc` requires standard OpenWrt LXC packages and uses BusyBox-friendly syntax. + +--- + +## CLI Usage + +```bash +secubox-lxc list # show defined containers +secubox-lxc create lyrion --bridge br-dmz --ip 192.168.50.10 +secubox-lxc start lyrion +secubox-lxc stop lyrion +secubox-lxc status lyrion +secubox-lxc delete lyrion +``` + +Each `create` call ensures the container directory under `/srv/lxc/` and writes a matching `config container ''` section in `/etc/config/lxcapps`. That makes it discoverable for future LuCI integrations. + +--- + +## UCI Schema + +```uci +config container 'lyrion' + option bridge 'br-dmz' + option ip '192.168.50.10' + option gateway '192.168.50.1' + option dns '1.1.1.1' + option memory '1024' +``` + +Additional options (template, rootfs, custom scripts) can be added later; the CLI already supports `--template`, `--memory`, `--bridge`, `--ip`, `--gateway`, and `--dns` flags. + +--- + +## Storage & Templates + +- Default rootfs path: `/srv/lxc//rootfs`. +- Template lookup: CLI `--template` arg → `/usr/share/secubox/lxc/templates/` → system `lxc-create -t debian`. +- Bridge defaults to `br-lan`; pass `--bridge br-dmz` for DMZ containers. + +--- + +## Future Work + +- Expose `/etc/config/lxcapps` via RPC + LuCI so manifests/profiles can declare LXC apps. +- Ship Lyrion and other container templates alongside Docker apps in the App Store. +- Reuse the profile system to install LXC dependencies and provision containers automatically. + +For now, this tooling lets power users validate LXC on OpenWrt ARM64 and gives the App Store a consistent foundation. diff --git a/docs/embedded/lxc-framework.md b/docs/embedded/lxc-framework.md new file mode 100644 index 00000000..2c5a9a4f --- /dev/null +++ b/docs/embedded/lxc-framework.md @@ -0,0 +1,78 @@ +# SecuBox LXC Framework (Preview) + +**Version:** 1.0.0 +**Last Updated:** 2025-12-28 +**Status:** Active + +This document captures the baseline LXC tooling added in Step 8. It is a foundation for future “SecuBox Apps” packaged as LXC containers (e.g., Lyrion) and explains the combined CLI/UCI workflow. + +--- + +## Components + +1. **UCI config:** `/etc/config/lxcapps` (one section per container). +2. **Storage root:** `/srv/lxc//` (rootfs, config, logs). +3. **Templates:** `/usr/share/secubox/lxc/templates/` (scripts/tarballs; default `debian`). +4. **CLI helper:** `secubox-tools/lxc/secubox-lxc` (install to `/usr/sbin/secubox-lxc`). + +`secubox-lxc` requires standard OpenWrt LXC packages (`lxc`, `lxc-templates`, `lxc-start`, etc.) and uses BusyBox-friendly syntax. + +--- + +## CLI Usage + +```bash +# List defined containers +secubox-lxc list + +# Create container using the debian template and attach to br-dmz +secubox-lxc create lyrion --bridge br-dmz --ip 192.168.50.10 + +# Start / stop lifecycle +secubox-lxc start lyrion +secubox-lxc stop lyrion + +# Show detailed config or status +secubox-lxc show lyrion +secubox-lxc status lyrion + +# Remove +secubox-lxc delete lyrion +``` + +`secubox-lxc create ` automatically creates a `config` section under `lxcapps.` capturing bridge/IP/memory metadata, so LuCI (future apps) can introspect containers in a consistent way. + +--- + +## UCI Schema (`/etc/config/lxcapps`) + +```uci +config container 'lyrion' + option bridge 'br-dmz' + option ip '192.168.50.10' + option gateway '192.168.50.1' + option dns '1.1.1.1' + option memory '1024' +``` + +This initial version does not yet tie into LuCI, but the schema is ready for future RPC endpoints and wizards (e.g., mapping profile entries to LXC containers). + +--- + +## Storage & Templates + +- Default rootfs path: `/srv/lxc//rootfs`. +- Template lookup order: CLI `--template` → `/usr/share/secubox/lxc/templates/` → fallback to system `lxc-create -t debian`. +- Bridge defaults to `br-lan`; pass `--bridge br-dmz` to isolate DMZ containers. + +--- + +## Next Steps + +This foundation enables the remaining roadmap items: + +- Expose `/etc/config/lxcapps` via `luci-app-secubox` RPC for integration with the App Store/wizard. +- Add profiles or manifests referencing specific LXC definitions (e.g., `type": "lxc"`). +- Ship ready-made templates (Lyrion, etc.) and document cgroup requirements alongside Docker apps. + +For now, use the CLI + UCI schema to experiment with LXC containers on OpenWrt ARM64 and validate storage/network assumptions. diff --git a/docs/embedded/wizard-profiles.md b/docs/embedded/wizard-profiles.md index 98a508c6..7d6ec56e 100644 --- a/docs/embedded/wizard-profiles.md +++ b/docs/embedded/wizard-profiles.md @@ -59,6 +59,7 @@ Baseline profiles: | `lab` | Monitoring lab | Router mode, ensures Netifyd & Bandwidth Manager | | `hardened` | Security-focused | Enables CrowdSec + Client Guardian | | `gateway_dmz` | Router + DMZ segment | Switches to DMZ mode and enables VHost manager | +| `lxc_base` | (Upcoming) baseline LXC container | Reserved for future `secubox-lxc` integrations | `apply_profile` automatically tars `/etc/config` to `/etc/secubox-profiles/backups/` before modifying settings, so the **Rollback last profile** button (or `rollback_profile` RPC) instantly restores prior UCI files. diff --git a/profiles/README.md b/profiles/README.md new file mode 100644 index 00000000..872692e0 --- /dev/null +++ b/profiles/README.md @@ -0,0 +1,10 @@ +# SecuBox Profiles + +This directory defines baseline profile manifests consumed by `luci-app-secubox`. + +- `home.json`: Home router baseline (router mode, Zigbee2MQTT + Netdata). +- `lab.json`: Lab monitoring preset (Netifyd + Bandwidth Manager). +- `hardened.json`: Security preset (CrowdSec + Client Guardian). +- `gateway_dmz.json`: Gateway + DMZ preset (switches to DMZ mode, enables vhost manager). + +These JSON files also serve as examples for future LXC or Docker app bundles. diff --git a/secubox-tools/lxc/secubox-lxc b/secubox-tools/lxc/secubox-lxc new file mode 100755 index 00000000..a20fccc9 --- /dev/null +++ b/secubox-tools/lxc/secubox-lxc @@ -0,0 +1,171 @@ +#!/bin/sh +# SecuBox LXC helper: create/start/stop LXC containers following SecuBox conventions + +set -eu + +CONFIG="/etc/config/lxcapps" +STORAGE_ROOT="/srv/lxc" +TEMPLATE_DIR="${SECUBOX_LXC_TEMPLATES:-/usr/share/secubox/lxc/templates}" + +usage() { + cat <<'USAGE' +SecuBox LXC Manager +Usage: secubox-lxc [options] + +Commands: + list Show containers defined in /etc/config/lxcapps + show Display config values for a container + create [options] Create container (downloads template if needed) + start Start container via lxc-start + stop Stop container via lxc-stop + delete Stop and remove container directory + status Show runtime state + +Options (create): + --template PATH Rootfs tarball or template script (default debian) + --bridge BRIDGE Bridge to attach (default br-lan) + --ip ADDRESS Static IP address (optional) + --gateway ADDRESS Gateway (optional) + --dns ADDRESS DNS server (optional) + --memory MB Memory limit (optional) + +Examples: + secubox-lxc list + secubox-lxc create secubox-lyrion --bridge br-dmz --ip 192.168.50.10 + secubox-lxc start secubox-lyrion +USAGE +} + +require_tool() { + command -v "$1" >/dev/null 2>&1 || { echo "[ERROR] Missing dependency: $1" >&2; exit 1; } +} + +ensure_storage() { + mkdir -p "$STORAGE_ROOT" +} + +uci_get_container() { + local name="$1" option="$2" + uci -q get lxcapps."$name"."$2" +} + +uci_set_container() { + local name="$1" option="$2" value="$3" + uci set lxcapps."$name"."$option"="$value" +} + +list_containers() { + uci -q show lxcapps 2>/dev/null | grep '=container$' | cut -d. -f2 | cut -d= -f1 +} + +cmd_list() { + require_tool lxc-info + ensure_storage + printf '%-18s %-20s %-10s %-16s\n' "Name" "Bridge" "State" "RootFS" + printf '%-18s %-20s %-10s %-16s\n' "----" "------" "-----" "------" + for name in $(list_containers); do + local bridge rootfs state + bridge=$(uci_get_container "$name" bridge || printf 'br-lan') + rootfs="$STORAGE_ROOT/$name/rootfs" + if lxc-info -n "$name" >/dev/null 2>&1; then + state=$(lxc-info -n "$name" -s 2>/dev/null | awk '{print $2}') + else + state="N/A" + fi + printf '%-18s %-20s %-10s %-16s\n' "$name" "$bridge" "$state" "$rootfs" + done +} + +cmd_show() { + local name="$1" + uci -q show lxcapps."$name" +} + +cmd_create() { + require_tool lxc-create + local name="$1"; shift + local template="debian" + local bridge="br-lan" + local ip="" + local gateway="" + local dns="" + local memory="" + while [ $# -gt 0 ]; do + case "$1" in + --template) template="$2"; shift 2;; + --bridge) bridge="$2"; shift 2;; + --ip) ip="$2"; shift 2;; + --gateway) gateway="$2"; shift 2;; + --dns) dns="$2"; shift 2;; + --memory) memory="$2"; shift 2;; + *) echo "Unknown option: $1" >&2; exit 1;; + esac + done + [ -n "$name" ] || { echo "Container name required" >&2; exit 1; } + ensure_storage + local container_dir="$STORAGE_ROOT/$name" + if [ -d "$container_dir" ]; then + echo "[WARN] Container directory already exists, skipping rootfs creation." + else + mkdir -p "$container_dir" + local tmpl_path="$template" + if [ -f "$TEMPLATE_DIR/$template" ]; then + tmpl_path="$TEMPLATE_DIR/$template" + fi + lxc-create -n "$name" -P "$STORAGE_ROOT" -t "$tmpl_path" + fi + uci batch <<-EOF + set lxcapps.$name=container + set lxcapps.$name.bridge='$bridge' + EOF + [ -n "$ip" ] && uci_set_container "$name" ip "$ip" + [ -n "$gateway" ] && uci_set_container "$name" gateway "$gateway" + [ -n "$dns" ] && uci_set_container "$name" dns "$dns" + [ -n "$memory" ] && uci_set_container "$name" memory "$memory" + uci commit lxcapps + cat </dev/null 2>&1 || true + lxc-destroy -n "$name" + rm -rf "$STORAGE_ROOT/$name" + uci delete lxcapps."$name" + uci commit lxcapps +} + +cmd_status() { + require_tool lxc-info + local name="$1" + lxc-info -n "$name" +} + +case "${1:-}" in + list) shift; cmd_list "$@" ;; + show) shift; [ $# -ge 1 ] || { usage; exit 1; }; cmd_show "$1" ;; + create) shift; [ $# -ge 1 ] || { usage; exit 1; }; cmd_create "$@" ;; + start) shift; [ $# -ge 1 ] || { usage; exit 1; }; cmd_start "$1" ;; + stop) shift; [ $# -ge 1 ] || { usage; exit 1; }; cmd_stop "$1" ;; + delete) shift; [ $# -ge 1 ] || { usage; exit 1; }; cmd_delete "$1" ;; + status) shift; [ $# -ge 1 ] || { usage; exit 1; }; cmd_status "$1" ;; + help|--help|-h|'') usage ;; + *) usage; exit 1 ;; +esac diff --git a/secubox-tools/lxc/templates/debian b/secubox-tools/lxc/templates/debian new file mode 100644 index 00000000..e69de29b