Files
zapret-autotune/deploy/managed-target/README.md
T
2026-10-11 10:59:25 +03:00

150 lines
8.6 KiB
Markdown

# Isolated managed-test target
This Compose project provisions a new, isolated target. It does not attach to,
reconfigure, or stop the existing `zapret2-ss-autotune` container. The target
starts from a disabled managed baseline; `managed monitor` bootstraps the
frontend/API strategy, then discovers and applies an exact-host GGC strategy.
## Provisioning
From this directory, create a private `.env` with a fresh independent password
and the configured host SOCKS port:
```sh
(umask 077; set -C; printf 'SS_PASSWORD=%s\nZAPRET_AUTOTUNE_HOST_SOCKS_PORT=11080\n' "$(openssl rand -hex 32)" > .env)
```
This refuses to overwrite an existing `.env`; do not print it or commit it.
Compose passes `SS_PASSWORD` as a container environment variable. It is removed
from the entrypoint environment before Shadowsocks children start and is never
placed in argv or logs. Docker administrators/root can still read container
environment and runtime config, so use this only for the isolated test target.
Create a **new empty** `./target-state`, owned by host UID 0 (runtime user),
mode `0700`; rootless/user-remapped Docker needs the mapped owner. Never reuse
state. Compose refuses a missing bind source. Retain state for recreation;
deletion loses transaction identity, journal, backups and candidate DB.
Validate without printing interpolated values:
`docker compose --env-file .env -f compose.yaml config --quiet`.
Then build and start only this Compose project. The rendered configuration
contains the environment password, so never use plain `docker compose config`
in logs or shared terminals.
By default Compose uses the locally built `zapret-autotune-managed-target:local`.
Tags are only local build/test candidates, not production release references.
For production promotion, set `ZAPRET_AUTOTUNE_IMAGE=<registry>/<managed-target>@sha256:<digest>`
in the private `.env` and pull that immutable image before starting the target.
Use a managed target image, not the generic image. Do not deploy production
with a tag or local default.
Offline static guard (from repository root):
`python3 deploy/managed-target/check_static.py`.
Isolated, accelerated shell supervision fixtures (no network):
`python3 deploy/managed-target/check_supervision.py`.
## In-container supervision
Compose has no automatic restart. PID 1 restarts the entire owned runtime only
for technical failures, with three starts per rolling six hours (including initial
startup) and cancellable 15/30-second cooldowns. Clean typed recovery timeouts,
unexpected monitor exits/crashes, and Shadowsocks failures qualify only if
shutdown cleanup succeeds. Configuration (64), safety/database/rollback/cleanup
failures (78), and graceful SIGTERM (0) never request restart. Exhausting the
restart budget exits 78. Investigate and
repair nonretry failures before manually starting again; do not clear state.
Monitor cancellation/join is bounded to 45 seconds, reconciliation gets 45 seconds
plus five to force kill, and final target-local zapret
stop gets 30 seconds then forced kill after five more, and each Shadowsocks join
gets five seconds. Exceeding a join bound fails closed. Compose grants 240
seconds. Reconcile after joining the monitor and before even stopping zapret:
stop also sources config, so unknown state is never sourced. The sequential
cleanup budget is 146 seconds; 240 seconds also covers an in-flight startup
command and scheduling grace. Watchdogs run in fresh shell interpreters and
cancel/join their own sleepers, including during PID 1's EXIT trap.
The monitor has a verified private session. After a crash, remaining check/NFQ
workers in that session are terminated and verified gone before reconciliation
or reactivation; Shadowsocks, watchdogs and unrelated exec peers are excluded.
## Isolation and runtime contract
Only SOCKS TCP/UDP is published on host
`127.0.0.1:${ZAPRET_AUTOTUNE_HOST_SOCKS_PORT:-11080}` for optional same-host
Xray use; no Xray edits are supplied. SS port `8388` is internal and 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 validates a hex-only password
of at least 32 characters, writes JSON configs to target-owned tmpfs
`/run/zapret-autotune-ss` (directory `0700`, files `0600`), then unsets the
password before starting child processes.
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`, `KILL`.
`NET_ADMIN` covers nft/NFQUEUE; `NET_RAW` covers nfqws2 raw sends. Zapret2's
`nfqws2 --user=tpws` needs `SETUID`/`SETGID` for UID/GID switching.
`KILL` allows bounded cleanup of workers that have dropped their UID.
Startup order: ss-server/ss-local → listener 1080 → guarded managed init on
fresh state → `managed reconcile` on every startup → target-local `zapret2 start`
→ supervised managed monitor. Reconciliation uses the fixed private target DB
and restores an interrupted prepared transaction's qualified last-good bytes
before any daemon reload/start. Drift, unknown state or failed rollback exits
78 (no automatic retry); nothing is adopted. Restore a consistent whole-state
backup if needed; do not wipe/re-init persisted state.
Startup init and reconcile each have a 45-second deadline; initial daemon start
has 30 seconds, with forced kill after five more seconds for each command.
Any startup command failure/timeout exits 78, never the retry code 75. These
bounds do not shorten the monitor's 90-minute bootstrap/recovery scan budget.
SIGTERM/SIGINT cancels and waits for the monitor before stopping target-local
zapret and Shadowsocks children. Nonretry monitor fatal exits stop the
entrypoint; technical exits and Shadowsocks failures restart from private configs
only after safe cleanup. Monitor health is YouTube Player API status through the owned SOCKS,
not video playback/SABR; GGC candidates are scoped to the exact discovered
hostname.
## Recorded clean-run acceptance (2026-10-11): PASS
Tested source RC: `d8316e695bc36e1243c111e19bb1e527355907b6`; local tag
`zapret-autotune-managed-target:rc-d8316e6`; immutable image
`sha256:5636aa9031fd0f6a0513f2e22cc0c39b1c806e9714b7f9ac040c8713d6a26c6c`.
The image was built from that source git archive with pinned inputs, not from
the later documentation commit. Private source root:
`/home/agent/zapret2-autotune-rc-d8316e6`.
The additional clean Compose project `zapret-autotune-clean-d8316e6-45bb14ba`
uses root `/home/agent/zapret2-managed-clean-d8316e6-45bb14ba` and host SOCKS
TCP/UDP `127.0.0.1:11081`. It is left running for inspection; the existing
managed target on `11080` and older SS target remain untouched.
- Before launch, state was empty, root-owned and mode `0700`; the independent
secret was 64 hex characters and `.env` mode `0600`. Real `blockcheckw` was
used, without mocks or copied config/candidates. Fresh init was observed;
fast bootstrap meant no exact generation-0 status snapshot was captured.
- Bootstrap committed generation2, frontend ID1 (verified layout-safe fake +
multidisorder seed) and exact-host GGC ID2 for
`rr17---sn-n8v7kn7d.googlevideo.com`. Both have valid raw TLS1.2/TLS1.3
evidence, 3/3 each. Periodic `lastProbeAt` advanced, counter0, recovery idle.
- Monitor SIGKILL changed host PID522765→525271 in the same container/PID1,
DockerRestartCount0, preserving IDs[1,2] and config hash
`57e639c98420be73a8ec4754b20ba975d81aced44215ed547b1ac029c89c14de`.
Graceful stop exited0 in 0.61s with no worker leaks. Forced recreation
(`5af686e2ad94…`, host PID525625) retained generation2, IDs and hash.
- Post-recreation counters1 then2 were observed; their cause is unproven.
A fresh-discovery GGC mismatch sample is not proof of the actual error cause.
The next default probe at 07:54 reset the counter to0, no active recovery.
Player API was OK and host SOCKS curl to `www.youtube.com` returned HTTP200.
- Both older targets' images, IDs, PIDs, start times and ports were unchanged
(managed PID518298, old SS PID266922); no host-manager or Xray changes.
Private PASS report: `final-cleanrun-report.json` under the clean root above;
raw artifacts: `final-evidence/`. This is isolated clean-run acceptance, not
blanket production approval or media playback/SABR verification. No real
90-minute watchdog wait was performed; shortened/injected tests cover expiry.
Saved-first recovery, rollback and other fault-injection results are recorded
separately in [PROGRESS.md](../../PROGRESS.md), not implied by this clean run.
For any new rollout, validate its own image binding, routing and lifecycle gates
on the new target only; never widen capabilities or reuse existing config/network
as a workaround.