feat(linux-port): bootstrap MVP boxctl, config loader, supervisor, firewall skeleton, and systemd units

.github/workflows/ci.yml

@@ -0,0 +1,135 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - '**'
+    tags:
+      - 'v*'
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint-and-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Bash syntax checks
+        run: |
+          bash -n \
+            cmd/boxctl \
+            lib/*.sh \
+            lib/firewall/*.sh \
+            lib/supervisor/*.sh \
+            tests/integration/test_phase2.sh \
+            tests/integration/test_real_kernel.sh \
+            tests/integration/test_arch_package_smoke.sh \
+            tests/fixtures/mockbin/ip \
+            tests/fixtures/mockbin/iptables \
+            packaging/scripts/systemd-lifecycle.sh \
+            packaging/arch/box4linux.install
+
+      - name: ShellCheck (if available)
+        run: |
+          if command -v shellcheck >/dev/null 2>&1; then
+            # SC1091: dynamic source paths are expected in this repo layout.
+            # SC2034: shared globals/constants are intentionally defined in common libs.
+            shellcheck \
+              -e SC1091,SC2034 \
+              cmd/boxctl \
+              lib/*.sh \
+              lib/firewall/*.sh \
+              lib/supervisor/*.sh \
+              tests/integration/test_phase2.sh \
+              tests/integration/test_real_kernel.sh \
+              tests/integration/test_arch_package_smoke.sh \
+              packaging/scripts/systemd-lifecycle.sh
+            shellcheck -e SC1091,SC2034 -s sh packaging/arch/box4linux.install
+          else
+            echo "shellcheck not available; skipping"
+          fi
+
+      - name: Mock integration tests
+        run: ./tests/integration/test_phase2.sh
+
+      - name: Real-kernel integration tests (skip-capable)
+        run: sudo ./tests/integration/test_real_kernel.sh
+
+  build-arch-package:
+    runs-on: ubuntu-latest
+    needs:
+      - lint-and-tests
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build Arch package in container
+        run: |
+          docker run --rm \
+            -v "$PWD":/work \
+            -w /work \
+            archlinux:base-devel \
+            bash -lc '
+              set -euo pipefail
+              # Avoid relying on distro default unprivileged accounts (for example `nobody`)
+              # because some base images can mark them as expired.
+              useradd -m -U builder
+              chown -R builder:builder /work
+              su builder -s /bin/bash -c "cd /work/packaging/arch && makepkg --nodeps --noconfirm -f"
+            '
+
+      - name: Capture package path
+        id: pkg
+        run: |
+          pkg_path="$(ls -1 packaging/arch/*.pkg.tar.* | head -n 1)"
+          echo "package_path=${pkg_path}" >> "${GITHUB_OUTPUT}"
+          echo "Built package: ${pkg_path}"
+
+      - name: Upload Arch package artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: box4linux-arch-pkg
+          path: ${{ steps.pkg.outputs.package_path }}
+
+  smoke-package:
+    runs-on: ubuntu-latest
+    needs:
+      - build-arch-package
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Download Arch package artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: box4linux-arch-pkg
+          path: ./dist
+
+      - name: Package smoke test
+        run: |
+          pkg_path="$(ls -1 ./dist/*.pkg.tar.* | head -n 1)"
+          ./tests/integration/test_arch_package_smoke.sh "${pkg_path}"
+
+  release:
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs:
+      - smoke-package
+    permissions:
+      contents: write
+    steps:
+      - name: Download Arch package artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: box4linux-arch-pkg
+          path: ./dist
+
+      - name: Publish release assets
+        uses: softprops/action-gh-release@v2
+        with:
+          files: ./dist/*.pkg.tar.*
+          generate_release_notes: true

.gitignore

@@ -0,0 +1,19 @@
+# OS / editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Box references
+box-reference/
+
+# Local Linux dev runtime state
+.box-dev/
+
+# Arch packaging build artifacts
+packaging/arch/*.pkg.tar.*
+packaging/arch/pkg/
+packaging/arch/src/

README.md

@@ -0,0 +1,132 @@
+# box4linux workspace
+
+Linux-native control plane lives in:
+- `cmd/boxctl`
+- `lib/common.sh`
+- `lib/config.sh`
+- `lib/supervisor/`
+- `lib/firewall/`
+- `systemd/`
+- `tests/integration/`
+- `packaging/arch/`
+
+Android reference artifacts are kept untouched in `box-reference/`.
+
+## Quick run (dev)
+
+1. Use repo-local fallback config at `etc/box/box.toml` (auto-used when `/etc/box/box.toml` is missing).
+   - If `BOX_CONFIG_FILE` is explicitly set, it must exist; commands fail fast instead of falling back.
+2. Run status commands:
+   - `./cmd/boxctl service status`
+   - `./cmd/boxctl service status --json`
+   - `./cmd/boxctl firewall status`
+   - `./cmd/boxctl firewall status --json`
+3. Run privileged actions as root:
+   - `sudo ./cmd/boxctl service start|stop|restart`
+   - `sudo ./cmd/boxctl firewall enable|disable|renew`
+   - `./cmd/boxctl firewall dry-run`
+4. Run integration checks:
+   - `./tests/integration/test_phase2.sh`
+   - `sudo ./tests/integration/test_real_kernel.sh`
+
+## Arch Package Build/Install
+
+Build package from repo root:
+- `cd packaging/arch && makepkg --noconfirm -f`
+
+Install package:
+- `sudo pacman -U ./box4linux-*.pkg.tar.zst`
+
+Installed layout:
+- `/usr/bin/boxctl`
+- `/usr/lib/box4linux/cmd/boxctl`
+- `/usr/lib/box4linux/lib/...`
+- `/etc/box/box.toml`
+- `/usr/lib/systemd/system/box.service`
+- `/usr/lib/systemd/system/box-firewall.service`
+- `/usr/share/doc/box4linux/`
+
+Config upgrade behavior:
+- Package marks `/etc/box/box.toml` as backup config.
+- Local edits are preserved across upgrades.
+- New template versions land as `.pacnew` when needed.
+
+## Service Lifecycle (Packaged Install)
+
+Use helper script from package docs:
+- `sudo /usr/share/doc/box4linux/systemd-lifecycle.sh enable`
+- `sudo /usr/share/doc/box4linux/systemd-lifecycle.sh status`
+- `sudo /usr/share/doc/box4linux/systemd-lifecycle.sh disable`
+
+Manual equivalent:
+- `sudo systemctl daemon-reload`
+- `sudo systemctl enable --now box.service box-firewall.service`
+- `sudo systemctl disable --now box-firewall.service box.service`
+
+## Packaged Operational Quickstart
+
+1. Verify command and units:
+   - `boxctl service status --json`
+   - `boxctl firewall status --json`
+2. Preview firewall operations:
+   - `boxctl firewall dry-run`
+3. Start runtime:
+   - `sudo systemctl start box.service`
+4. Renew firewall policy safely:
+   - `sudo systemctl reload box-firewall.service`
+
+## CI/Release Flow
+
+Workflow file: `.github/workflows/ci.yml`
+
+On push/PR:
+- `bash -n` checks on shell scripts
+- `shellcheck` when available
+- mock integration: `./tests/integration/test_phase2.sh`
+- privileged integration: `sudo ./tests/integration/test_real_kernel.sh` (suite prints `SKIP` when capabilities/tooling are unavailable)
+- Arch package build in Arch container
+- package smoke test: `./tests/integration/test_arch_package_smoke.sh <pkg>`
+
+On tags (`v*`):
+- built package artifact is published to GitHub Releases
+
+## Phase 3 Notes
+
+- Supported cores: `mihomo`, `sing-box`
+- Runtime overlays rendered under `/run/box/rendered` (or dev fallback)
+- Firewall backends:
+  - `iptables` (mature path)
+  - `nftables` (MVP parity)
+- Supported modes on both backends: `tun`, `tproxy`, `redirect`, `mixed`, `enhance`
+- DNS strategies: `tproxy`, `redirect`, `disable`
+- Coexistence modes:
+  - `preserve_tailnet` (default): apply tailscale and MagicDNS bypasses
+  - `strict_box`: skip tailscale/MagicDNS bypass insertion
+- Route convergence: renew/reapply prunes stale BOX fwmark rules and enforces one current `route_pref` rule
+- Idempotent + lock-protected: `enable|renew|disable`
+- `BOX_TRACE_COMMANDS=1` logs external command executions with component/action context
+- `boxctl firewall status --json` exposes stable diagnostics (backend, capabilities, coexist fields, errors)
+
+## Backend Capability Notes
+
+- `iptables`:
+  - `cap_ipv4=true`
+  - `cap_ipv6=false` (full ip6tables graph pending)
+- `nftables`:
+  - `cap_ipv4=true`
+  - `cap_ipv6=false` (full IPv6 interception/hijack graph pending)
+
+## Rollback/Uninstall
+
+Safe uninstall (keeps config backups/data unless manually removed):
+- `sudo pacman -R box4linux`
+
+Optional manual purge of local state:
+- `sudo rm -rf /etc/box /var/lib/box /run/box /var/log/box`
+
+## Remaining TODO
+
+- Full UID/GID/interface/MAC policy graph in firewall.
+- Full IPv6 interception/hijack parity.
+- API-based reload hooks for `mihomo` and `sing-box`.
+- Broader kernel-capability probing across distro variants.

cmd/boxctl

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+
+# shellcheck shell=bash
+
+set -euo pipefail
+
+CMD_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LIB_DIR_CANDIDATES=(
+  "${BOX_LIB_DIR:-}"
+  "${CMD_DIR}/../lib"
+  "/usr/lib/box4linux/lib"
+)
+LIB_DIR=""
+
+find_lib_dir() {
+  local candidate
+  for candidate in "${LIB_DIR_CANDIDATES[@]}"; do
+    [[ -n "${candidate}" ]] || continue
+    if [[ -f "${candidate}/common.sh" ]]; then
+      LIB_DIR="${candidate}"
+      export BOX_LIB_DIR="${LIB_DIR}"
+      return 0
+    fi
+  done
+  return 1
+}
+
+if ! find_lib_dir; then
+  printf 'failed to locate box4linux lib directory; checked:\n' >&2
+  local_candidate_list="$(printf '  %s\n' "${LIB_DIR_CANDIDATES[@]}")"
+  printf '%s' "${local_candidate_list}" >&2
+  exit 1
+fi
+
+source "${LIB_DIR}/common.sh"
+source "${LIB_DIR}/config.sh"
+source "${LIB_DIR}/supervisor/supervisor.sh"
+source "${LIB_DIR}/firewall/firewall.sh"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  boxctl service <start|stop|restart|status> [--json]
+  boxctl firewall <enable|disable|renew|status|dry-run> [--json]
+EOF
+}
+
+main() {
+  local component="${1:-}"
+  local action="${2:-}"
+  shift 2 || true
+
+  for arg in "$@"; do
+    if [[ "${arg}" == "--json" ]]; then
+      BOX_OUTPUT_FORMAT="json"
+      export BOX_OUTPUT_FORMAT
+    fi
+  done
+
+  enable_command_trace "${component:-boxctl}" "${action:-none}"
+  trap 'disable_command_trace' EXIT
+
+  case "${component}" in
+    service)
+      supervisor_cmd "${action}"
+      ;;
+    firewall)
+      firewall_cmd "${action}"
+      ;;
+    -h|--help|help|"")
+      usage
+      ;;
+    *)
+      printf 'unknown component: %s\n' "${component}" >&2
+      usage >&2
+      return 2
+      ;;
+  esac
+}
+
+main "$@"

docs/linux-port/04-component-firewall-routing.md

@@ -72,6 +72,27 @@ If unsupported, apply controlled downgrade with explicit logs.
 - Do not hardcode interface names like `wlan0`.
 - Make route table id configurable to avoid collisions.
 
+## Tailscale Coexistence Requirements
+For hosts that run Tailscale alongside Box, firewall apply/cleanup must preserve Tailscale routing and DNS behavior.
+
+Hard requirements:
+
+- Never flush/delete non-BOX chains or global policy rules.
+- Never touch Tailscale policy-routing entries (commonly table `52`, fwmark rules like `0x80000/0xff0000`, or rule priorities around `5210..5270`).
+- Add explicit bypass for Tailscale interface traffic:
+- `-i tailscale0 -j RETURN` and `-o tailscale0 -j RETURN` in relevant chains.
+- Add destination bypass CIDRs for tailnet traffic:
+- IPv4 `100.64.0.0/10`
+- IPv6 `fd7a:115c:a1e0::/48`
+- Exclude Tailscale DNS endpoint from DNS hijack:
+- `100.100.100.100:53`
+- Keep Box rule/table/pref IDs configurable and in a dedicated namespace to avoid collisions with existing local policy routing (for example `2022`, `2024`, `52` already in use on some hosts).
+
+DNS guidance:
+
+- When transparent DNS interception is enabled, provide `dns_exclude_servers` and `dns_exclude_domains` settings.
+- Default excludes should include Tailscale resolver and tailnet domains (`*.ts.net` and local MagicDNS suffix).
+
 ## Required Tests
 - each mode on IPv4-only and dual-stack
 - idempotent enable/renew/disable loops