Files
zapret-autotune/deploy/managed-target/README.md
T
2026-10-10 23:27:53 +03:00

113 lines
6.3 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 unit.
Use a managed target image, not the generic image; the systemd command never
builds images. Do not enable the production service with a tag or local default.
Offline static guard (from repository root):
`python3 deploy/managed-target/check_static.py`.
## Optional native systemd supervision
For unattended boot, place this checkout at `/opt/zapret2-autotune`, provision
`deploy/managed-target/.env` and state as above, and build the target image first.
For production, select and pull the immutable managed-target digest as above
instead of using a local build tag.
Install `deploy/managed-target/zapret-autotune.service` in `/etc/systemd/system/`,
then run `systemctl daemon-reload` and `systemctl enable --now zapret-autotune`.
Do not simultaneously start the same project with detached Compose.
Enabling the unit starts this isolated target on subsequent boots. `ExecStop`
only stops `target`; it does not replace the foreground process's failure code.
An explicit service stop suppresses restart, including during a shutdown race.
Compose has no automatic restart. The foreground systemd unit restarts **only
exit 75**, with at most three starts per six hours. 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. Investigate and
repair nonretry failures before manually starting again; do not clear state.
Monitor cancellation/join is bounded to 60 seconds, 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 120
seconds; systemd grants 180 seconds.
## 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. Monitor fatal exits stop the
entrypoint. Monitor health is YouTube Player API status through the owned SOCKS,
not video playback/SABR; GGC candidates are scoped to the exact discovered
hostname.
The deployment has not yet passed live runtime acceptance. Validate the pinned
image's JSON config loading, Lua/fakes, `ZAPRET_CONFIG` binding, target-local
routing, NFQUEUE activation/rollback, signal cleanup and persistent recreation
on this new target only. Do not widen capabilities or reuse existing config or
network as a workaround. Verify the complete unattended path: empty profile →
frontend/API candidate scan and apply → exact-host GGC candidate scan and apply
→ ongoing probes → saved-first recovery, falling back to scan only when saved
scenarios validly fail.