Files
zapret-autotune/deploy/managed-target/README.md
T
2026-10-10 09:45:34 +03:00

5.6 KiB

Isolated managed-test definition — deployment deferred

This definition is not autonomous acceptance-ready: managed monitor and entrypoint recovery integration exist in code but are not live verified. Do not build/pull/start it as part of this change. Existing containers, production and Xray configuration are out of scope.

For a later approved deployment, from this directory:

  1. Copy .env.example to .env and restrict it to 0600; it sets only the host loopback SOCKS port. Generate a new independent secret locally: (umask 077; set -C; openssl rand -hex 32 > ss_password). This refuses to overwrite an existing file. Never copy existing secrets or put the password in .env, environment variables or command arguments. ss_password, .env and state are gitignored and excluded from the build context. Do not commit the secret file. Compose mounts it read-only at /run/secrets/ss_password; keep the host file owned by the invoking user with mode 0600 (no deploy-time chown or world-readable permissions). Use only this newly generated regular file at ./ss_password, not a symlink or a reused secret. Do not mount its parent directory or other host secrets.
  2. Provision a new empty ./target-state, owned by host UID 0 (runtime user), mode 0700. Rootless/user-remapped Docker needs the mapped owner. Never reuse mounts/state. Compose refuses a missing bind source. Retain state for recreation; deletion loses identity, journal, backups and DB.
  3. Orchestrator may validate without deploying: docker compose --env-file .env -f compose.yaml config --quiet. Rendered Compose config contains only the secret file path, not its value. Build/run require separate approval and runtime validation gates.

Offline static guard (from repository root): python3 deploy/managed-target/check_static.py. It pins the capability allowlist and single-secret/single-state mount shape; it does not prove runtime readability.

Only SOCKS TCP/UDP is published on host 127.0.0.1:${ZAPRET_AUTOTUNE_HOST_SOCKS_PORT:-11080} for same-host Xray; no Xray edits are supplied. SS port 8388 is internal, never published. The server binds 0.0.0.0:8388 only inside the dedicated bridge namespace; ss-local binds 0.0.0.0:1080. Startup requires a hex-only secret of at least 32 characters and writes JSON configs to the dedicated target-owned tmpfs /run/zapret-autotune-ss (directory 0700, files 0600). Both Shadowsocks processes receive only -c <config_path>, never a password in argv or env. Docker administrators/root can still read mounted secrets and runtime configs; file-backed Compose secrets are not encrypted storage. The dedicated bridge is not shared with existing services. No host networking, Docker socket, existing mounts, host Lua/fakes or privileged mode; all capabilities are dropped except NET_ADMIN, NET_RAW, SETUID, SETGID and DAC_OVERRIDE. NET_ADMIN covers nft/NFQUEUE; NET_RAW covers nfqws2 raw sends. Zapret2's nfqws2 --user=tpws needs SETUID/SETGID for UID/GID switching, then retains only CAP_NET_RAW and CAP_NET_ADMIN. DAC_OVERRIDE lets the root entrypoint read the invoking user's mode-0600 file-backed secret despite its different host UID; it does not make the host file world-readable or writable through the read-only secret mount. This capability is container-wide, not restricted to one pathname: its safe scope depends on exposing only ./ss_password → /run/secrets/ss_password (read-only) and the fresh ./target-state → /var/lib/zapret-autotune/target bind, plus dedicated runtime tmpfs. Never add host directories, other secrets or existing state to this container. No default-all capability set is used. Rootless/user-remapped Docker must validate secret readability separately; this does not bypass user-namespace or host filesystem restrictions.

Go builder matches Dockerfile; runtime digest is pinned and image-owned Lua/fakes retained. Startup: ss-server/ss-local → internal listener 1080 (30-second bound) → guarded managed init on fresh state (status on recreation) → zapret2 start using target config → one installed managed monitor child. Drift/pending state refuses startup; no automatic adoption of unknown state. SIGTERM/SIGINT cancels and waits the monitor before stopping target-local zapret and the entrypoint's Shadowsocks children. Monitor fatal exits stop the entrypoint; no restart policy hides fail-closed exits. Monitor probes Player API via owned loopback SOCKS; unresolved GGC is not playback health.

Inside target, zapret-autotune health youtube uses socks5://127.0.0.1:1080, never the host port. It is one-shot Player API health, not playback or scheduling.

The supplied remote read-only inspection verified shadowsocks-libev 3.3.5 and ss-server -h supports -c <config_file>; runtime JSON loading remains unverified. Before deployment acceptance, validate Lua/fakes, ZAPRET_CONFIG binding and full zapret start/stop/restart with only the explicit NET_ADMIN, NET_RAW, SETUID, SETGID, DAC_OVERRIDE capability set (including the tpws user drop). Prove target-local routing, NFQUEUE activation/rollback, signal cleanup and persistent recreation on the new target only. Compose syntax, build and runtime integration are unverified by this producer. Do not widen capabilities or reuse existing config/network as a workaround. Autonomous acceptance also needs tests/build and live verification of monitor/recovery and crash reconciliation, including shutdown grace sufficient for bounded restoration (which may exceed the defined 45s). Docker configuration has not been changed by this code integration increment.