21 KiB
Fresh managed-test target contract (not deployed)
managed init|status|active-ids|apply is exclusively for a new dedicated container
which owns its entire config. The existing/dev/production container must refuse
these commands. A role env or CLI-created identity is not enough. Provisioning
must supply all of the following before any managed command can run:
| Setting | Exact required value |
|---|---|
ZAPRET_AUTOTUNE_TARGET_ROLE |
managed-test |
ZAPRET_AUTOTUNE_TARGET_ID |
zapret-autotune-managed-v1 |
ZAPRET_AUTOTUNE_TARGET_DIR |
/var/lib/zapret-autotune/target |
ZAPRET_CONFIG |
/var/lib/zapret-autotune/target/config |
SOCKS_PORT |
Base image's actual ss-local service port (canonical decimal, 1–65535) |
ZAPRET_AUTOTUNE_SOCKS_PROXY |
socks5://127.0.0.1:$SOCKS_PORT (expanded value) |
The fixed directory must already be a private runtime-user-owned dedicated
persistent volume mountpoint, not just a directory under another mount.
The production verifier checks the exact path in /proc/self/mountinfo.
Provisioning must also supply /etc/zapret-autotune/target-id containing exactly
zapret-autotune-managed-v1 followed by a newline. Init never writes that marker.
Base runtime executables must exist: /opt/zapret2/init.d/sysv/zapret2,
/opt/zapret2/nfq2/nfqws2, and /usr/bin/blockcheckw.
There are no arbitrary directory flags or env overrides of these fixed values.
These are operator safety guards, not protection against a privileged user
deliberately forging a provisioned runtime.
The managed config is a standalone full config only in this fresh volume.
Never replace, adopt, or symlink over /opt/zapret2/config or any existing
service config. The new deployment entrypoint must ensure the base daemon
actually honors the exact ZAPRET_CONFIG path; compatibility remains unproven.
Existing services would require a separately designed managed include
fragment, not this full-config adapter. No such integration is implemented.
# Only after fresh-target provisioning establishes the entire contract above:
zapret-autotune managed init
zapret-autotune managed status
zapret-autotune managed apply --frontend-candidate 1 # bootstrap before discovery
zapret-autotune managed active-ids # JSON for supervisor; no health probe
zapret-autotune managed apply --frontend-candidate 1 --googlevideo-candidate 2
Init refuses nonempty directories except an exact private disabled baseline;
it never overwrites/adopts another config. It creates identity, journal and
backup; repeated initialization, symlinks, hardlinks, public/unowned files and
unsafe ancestors are refused. Status reports generation/hash/transaction state,
validated active IDs/groups and unresolved groups, not config, secrets or live
health. Pending or unverifiable state reports unknown groups and no active IDs;
drift fails closed. active-ids fails closed on pending or unverifiable state.
Init/status do not reload or probe, but both verify runtime and listener ownership.
All managed commands verify that the expected IPv4 listener is owned by a running
ss-local executable in the target PID/network namespace: /proc/net/tcp socket
inodes must match that process's file descriptors. A process alone, a wrong port,
or another loopback proxy is insufficient. Health repeats this validation before
its Player API request. The host's published SOCKS port may map to this listener,
but is never used inside the target. The standalone health youtube command
retains its separate generic loopback contract; managed activation is stricter.
Ambient proxies/direct fallback are disabled. Player API OK is not playback.
Apply accepts one or both frontend/exact-GGC SQLite candidate IDs, requiring
distinct positive IDs, at most one per group, complete endpoint × TLS evidence
and inert shell-safe arguments. The arguments are the full desired active set,
not patches: omitting a group removes it. Frontend-only bootstrap supports Player
API discovery before GGC scanning; GGC-only is also permitted. No missing profile
is invented, and missing groups remain unresolved. Player API OK never asserts
GGC/video playback or full-profile health. A supervisor can read managed active-ids
and explicitly retain the other group while replacing a failed one. It opens
the candidate DB read-only via ZAPRET_AUTOTUNE_DB; candidates are not active
state. Bindings/inputs are checked before pending transaction reconciliation.
Production reload is exclusively the fixed argv
/opt/zapret2/init.d/sysv/zapret2 restart, no shell, with a 30-second deadline.
Apply and rollback both use this full firewall/daemon restart; daemon-only
restart is not a supported fallback. This changes only the new target
container's dedicated network namespace, never the host or old container's
firewall. Provisioning must not use host networking or share an existing
container's network namespace.
The baseline explicitly sets INIT_APPLY_FW=1, NFQWS2_ENABLE=0, empty
NFQWS2_OPT, TCP ports 80,443, UDP ports 443, and TCP/UDP in/out packet
limits of 15. QNUM is deliberately inherited from the base runtime default.
Active configs keep those fixed firewall values and set NFQWS2_ENABLE=1
with the qualified managed strategy arguments. Restoring the baseline and
running full restart removes its target-local queues and stops nfqws2;
restoring an earlier active config reinstates its firewall/daemon state.
The config replacement is atomic; the init script's stop/start sequence is
not a zero-interruption or kernel-atomic firewall transaction.
Journal v2 persists complete committed and pending candidate ID lists alongside
their hashes. Commit promotes the pending list; rollback/crash reconciliation
restores the prior list and hash. Reporting validates qualification/groups and
exact rendered hash against the read-only DB. Status reports invalid refs as
unresolved; active-ids and activation fail closed on invalid refs.
Legacy v1 journals keep the exact deployed hash and unknown IDs: status marks
both groups unresolved, and active-ids refuses to infer a list. A guarded full-set
apply upgrades to v2 only after the exact old hash matches; rollback preserves
the unknown legacy deployment. Re-init cannot adopt an existing deployment.
The transaction engine retains same-directory staging/fsync/rename, durable journal/backup, advisory locking, external drift rejection, rollback and fail-closed crash reconciliation. Failed rollback reload remains pending. Directories must not be writable by untrusted processes; hostile concurrent filesystem mutation is outside the transaction boundary. Shell config safety and exact GGC filtering are unchanged.
The isolated Compose definition now supplies
the marker, mount and ordered startup; it has not been built or deployed.
No Docker socket, remote/container operations, old target paths, Xray edits,
or host firewall provisioning are included. Before deployment,
provisioning must verify the pinned image honors ZAPRET_CONFIG, supports all
listed variables, and starts ss-local while the baseline leaves nfqws2 disabled.
Start the fresh target with that baseline, then verify active apply installs
target-local nft NFQUEUE rules and starts nfqws2, and rollback restores both.
These image/startup/routing gates remain unverified: if any is unsupported or
uncertain, deployment must fail closed, not substitute restart-daemons or
alter an old config. Persistent volume durability is a provisioning
requirement; mountinfo alone cannot establish the storage lifecycle.
Internal recoverManagedTarget and wireManagedRecovery add injectable startup
bootstrap and saved-first recovery callbacks for the persisted monitor. Bootstrap
scans/checks/saves frontend and applies it alone with Player API post-check.
Recovery keeps an already healthy frontend, otherwise stops only the fixed
target zapret service, tries up to ten qualified saved IDs newest-first, and
scans only after complete valid non-pass results or health-rejected rollbacks.
Malformed reports/runner errors fail closed. GGC discovery uses the injected
managed-SOCKS path, revalidates against the fresh exact host, and saves new
immutable evidence before full-set apply. A frontend-only rollback boundary
survives GGC failure; unresolved GGC is reported separately, not playback health.
Cancelled/failed downtime restores the committed configuration and runs fixed
target start with an independent 30-second cleanup deadline. Failed cleanup or
rollback is fatal to the supervisor; unresolved journal state is never started.
The callback caller must hold the monitor singleton; the wiring repeats runtime
identity/SOCKS guards. Fake-only checks are added, but tests/build are deferred
to the orchestrator. managed monitor now binds those callbacks and only the
dedicated target entrypoint starts it; no live/runtime validation has occurred.
Dedicated monitor integration (live acceptance pending)
zapret-autotune managed monitor [--interval 5m] [--failure-threshold 3] [--cooldown 30m] uses the health environment defaults. Interval is positive and
at most 24h, threshold 1–1000, cooldown positive and at most 168h; explicit empty
or invalid settings fail before any lock. No executable/path/proxy flags exist.
The DB environment must be exactly /var/lib/zapret-autotune/target/candidates.db;
existing DB/sidecars must be private, owned regular files without aliases/hard links.
Runtime/SOCKS, directory, identity and DB path guards run before the singleton.
SQLite opens writable target-owned state; active IDs remain journal/DB/hash validated.
Probe reuses health youtube's Player API contract, forced owned loopback SOCKS,
no direct fallback. Discovery uses that same SOCKS adapter. Scan/check execute
only /usr/bin/blockcheckw, daemon operations only fixed target-local
/opt/zapret2/init.d/sysv/zapret2 start/stop/restart argv; no shell/eval command
strings. Context cancellation kills/waits process groups and bounded restoration
finishes before returning. Reports suppress untrusted diagnostics and credentials.
Startup reconciles transactions under the singleton and bootstraps only when no qualified active frontend exists. Bootstrap/recovery checks saved candidates first; GGCError reports unresolved and continues probing, not playback success. Other DB/safety/journal/runner failures stop nonzero; joined cancellation plus a cleanup failure is also fatal. A qualified frontend at startup is probed immediately, not rescanned merely because the process restarted.
Entrypoint ordering is SS children → listener → managed init/status → zapret start
→ one installed /usr/local/bin/zapret-autotune managed monitor child. It supervises
all three children; monitor exit is fatal even if it exits zero unexpectedly.
SIGTERM/SIGINT cancels and waits the monitor before target-local zapret stop and
SS child termination/wait. Existing targets and Xray remain unchanged. Deployment
allows 120s Compose shutdown grace and 180s systemd stop timeout for bounded
monitor cancellation/restoration and child joins. Code integration is not
image/routing/signal live verification.
Injected unit tests cover exact identity/path/config, mountpoint refusal, old-container-like env, SOCKS port/process refusal, correct fresh-target success, non-overwrite, transaction rollback and redaction. Tests/build/network are deferred to the orchestrator; not run by this increment:
go test ./cmd/zapret-autotune -run TestManaged
go build ./cmd/zapret-autotune
Production preparation
This is a standalone new isolated target candidate, not a production-approved
deployment and not an integration into existing zapret/Xray. Keep the exact
managed-test role, ID, marker, mount, config, DB and owned-listener guards above.
Do not change the role to production, adopt old state, share an old network
namespace, or relax a refusal. Provisioning and optional service installation
are described in deploy/managed-target/README.md.
Build once, promote the same image
Use Dockerfile.target for the supervised target; root Dockerfile is the
proposal CLI image, not the managed service. Both pin Go 1.25.3 and the runtime
by digest, use GOTOOLCHAIN=local, CGO_ENABLED=0, go.sum, and -trimpath.
Pins constrain build inputs; they do not establish live acceptance or guarantee
bit-for-bit builds on different platforms. Record the source commit, platform,
builder/runtime digests and resulting image digest for every release.
Example (replace registry and release; never reuse a release tag):
IMAGE=registry.example/team/zapret-autotune-managed-target:2026-10-10-r1
docker build --pull -f Dockerfile.target -t "$IMAGE" .
docker push "$IMAGE"
docker image inspect --format '{{index .RepoDigests 0}}' "$IMAGE"
Promote the printed registry/repository@sha256:... reference unchanged from
validation to deployment; do not rebuild or use latest. Authenticate separately,
never put registry credentials in these commands. The supplied Compose file
selects ${ZAPRET_AUTOTUNE_IMAGE:-zapret-autotune-managed-target:local}. Set
ZAPRET_AUTOTUNE_IMAGE=registry.example/team/zapret-autotune-managed-target@sha256:<digest>
in the same private deployment .env as SS_PASSWORD (mode 0600), using the
actual printed digest. Tags and the local default are build/test candidates only;
an immutable managed-target digest is required for production promotion. From
the repository root, validate and pull without printing the rendered secrets:
docker compose --env-file deploy/managed-target/.env -f deploy/managed-target/compose.yaml config --quiet
docker compose --env-file deploy/managed-target/.env -f deploy/managed-target/compose.yaml pull target
The supplied systemd unit uses this same .env and starts with --no-build;
no image-selection override or unit edit is needed. Keep the selected digest and
private configuration together for upgrades and rollback. Never run a build
against the production digest selector; build/tag separately as shown above.
Configuration and secrets
Create fresh empty target-state owned by root/runtime UID 0, mode 0700, and
the private deployment .env mode 0600; rootless/remapped Docker needs the
mapped owner. Bootstrap is for empty provisioned state only; recreation retains
identity, journal, candidate DB, sidecars and lock file. Never automatically wipe
state to make startup succeed. The entrypoint creates Shadowsocks JSON in private
tmpfs (0700 directory, 0600 files), unsets the password before children, and
does not put it in argv. Docker administrators/root can still read container env
and runtime config. Do not print .env, rendered Compose config, diagnostics or
signed URLs; use docker compose ... config --quiet for validation.
| Existing setting | Default / accepted value for managed target |
|---|---|
ZAPRET_AUTOTUNE_IMAGE |
Local build/test default zapret-autotune-managed-target:local; production promotion requires a managed-target repository@sha256:<digest> |
SS_PASSWORD |
Required independent hex-only secret, at least 32 characters; deployment README generates 64 |
ZAPRET_AUTOTUNE_HOST_SOCKS_PORT |
11080; choose an available TCP/UDP port 1–65535, published only on 127.0.0.1 |
SOCKS_PORT |
Supplied deployment fixes internal listener to 1080; not a host-port override |
ZAPRET_AUTOTUNE_SOCKS_PROXY |
Fixed socks5://127.0.0.1:1080 inside this target, no credentials/direct fallback |
ZAPRET_AUTOTUNE_VIDEO_ID |
dQw4w9WgXcQ; exactly 11 ASCII letters, digits, _ or - |
ZAPRET_AUTOTUNE_HEALTH_INTERVAL |
5m; duration in (0,24h] for monitor |
ZAPRET_AUTOTUNE_FAILURE_THRESHOLD |
3; integer 1–1000 for monitor |
ZAPRET_AUTOTUNE_RECOVERY_COOLDOWN |
30m; duration in (0,168h] for monitor |
ZAPRET_AUTOTUNE_DB |
Fixed /var/lib/zapret-autotune/target/candidates.db |
The monitor's three policy flags override corresponding environment defaults;
explicit empty/invalid environment settings are rejected. The entrypoint accepts
no arguments. The supplied Compose environment does not forward the video/policy
settings from .env: add the desired existing variables to target.environment
in your deployment copy/override if needed. Keep all fixed identity/path settings
unchanged. No public SS listener is published; Xray configuration is external and
operator-owned, optionally using the host's loopback SOCKS port. Do not modify an
existing Xray deployment as part of bootstrap.
Supervision and failure handling
Compose restart is disabled. Optional native systemd runs foreground Compose
with --no-build --abort-on-container-exit --exit-code-from target; do not also
run detached Compose for that project. The unit requests restart only for exit
75 via Restart=no plus RestartForceExitStatus=75, bounded by
StartLimitBurst=3 in six hours (starts, including the initial
start, not three additional retries). Compose stop grace is 120s, systemd 180s.
| Target exit | Operator meaning |
|---|---|
64 |
Invalid configuration; fix settings before starting |
78 |
Safety/DB/journal/rollback/cleanup failure; investigate, no automatic restart |
75 |
Technical failure eligible for bounded restart only after safe cleanup |
0 |
Graceful signal shutdown; no automatic restart |
Bootstrap/recovery has a fixed 90-minute whole-job deadline, plus an independent 30-second restoration reserve. This is a catastrophic technical ceiling, not a normal candidate-check timeout and not an operator tunable. Valid nonpassing candidates/unresolved GGC are normal recovery outcomes governed by the persisted threshold/cooldown, not a reason to restart the container. Failed restoration or unsafe state vetoes retry: timeout exit 75 requires the job's own deadline and only timeout/cancellation-related errors, with no joined cleanup, DB or safety failure. Unexpected monitor/SS failures are separately technical only if shutdown cleanup succeeds. Shutdown joins the monitor for up to 60s, target-local zapret stop gets 30s then forced kill after five more, and SS children get 5s each; failure to join/restore is fail-closed. The reserve is not extra scanning time. The 90-minute budget is shared by the whole bootstrap/recovery job, not renewed per candidate or phase.
Monitor health means Player API OK through owned SOCKS. GGC evidence covers
only the exact discovered hostname and tested TLS protocols, not wildcard
googlevideo coverage, video transfer, SABR or playback. Unresolved GGC must not
be reported as complete playback health.
Upgrade, rollback and operator recovery
- Record the current image digest and private deployment configuration. Stop the service (or foreground Compose), wait for complete cleanup, and verify the target is stopped. If cleanup fails, investigate before upgrading.
- With the target stopped, make a root-only backup of the entire state
directory (including DB sidecars, journal, config, identity and lock file),
preserving ownership/modes. Store
.envand image/config records privately with it; do not print archive contents, diagnostics or signed URLs. A live copy of onlycandidates.dbis not a consistent rollback backup. - Select/pull the new immutable digest and start without building. Inspect sanitized status/logs, verify identity/hash and expected active groups, owned SOCKS, target-local queues, health scope and persistent recreation. Keep the old image and backup until acceptance; DB migrations may prevent image-only downgrade.
- To roll back, stop and verify cleanup again. Preserve failed state separately for investigation. Restore the matched stopped-state backup as a whole into the same dedicated mount with private ownership/modes, select its old digest/config, then start. Do not merge journals/DB generations or re-init. A restored legacy/live/unverifiable recovery owner can fail closed; never clear its lease or unlink the lock merely to force startup.
On drift, pending transaction, rollback failure, or exhausted systemd start limit, leave state intact and service stopped. Diagnose using sanitized status and private artifacts; repair the actual provisioning/configuration issue or restore a known consistent backup. Only then manually start (and reset the systemd failed/start-limit state if needed). There is no automatic wipe or automatic adoption path.
Rollout acceptance remains pending real isolated-target restart/deadline tests: empty bootstrap, saved-first recovery, exact-host GGC rotation, image binding, NFQUEUE activation/rollback, SIGTERM during downtime, deadline restoration, retry limits/exit propagation through foreground Compose/systemd, persistent recreation and backup restore. Perform these on the new target only; local unit or static checks cannot establish production readiness.