Files
zapret-autotune/MANAGED_TARGET.md
T
2026-10-13 16:10:37 +03:00

605 lines
40 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Fresh managed-test target contract (isolated acceptance, not production approval)
## Managed DoH live acceptance (2026-10-13): DNS verified, NOT READY
Supplied verified reports bind source `544dda7c85965fc3200de3af17fca9ef9999b2ce`
(DoH `367d956`, TCP deadline `721cad4`, public-health `socks5h` fix `544dda7`)
to image `sha256:b3085b7ceca4a629c28bd58f23bf97f02a34c2a38df08b57756e40594ba2d427`,
container `4ad54175a54c`, owned SOCKS `127.0.0.1:11082`.
The 303-second LIVE snapshot retained root/DNS22/SS59,60/monitor253 PIDs,
children PPID1, owned readiness ACK and parent FD8/9 anchors. UDP/TCP DNS
IDs/questions matched, rcode0, answers2/8; SOCKS `0500`, WWW HTTP200/SSL0
and configured `health youtube` exit0 passed. Wire evidence: 41 marked direct
DoH connections, zero external port53. Scope `suffix`, generation9, IDs `[1,9]`
and hash preservation versus staging are measured snapshots, not universal
state; autonomous updates have occurred since the earlier generation8 snapshot.
In isolated staging, blocking both bootstrap IPs for 61 seconds returned
UDP/TCP SERVFAIL/rcode2 at about 5000ms without changing root, DNS, SS or monitor
PIDs or sending external port53 traffic. DNS recovered immediately after removal;
WWW HTTP200 passed after 46 seconds without restart. Graceful stop: 1 second,
exit0, no survivors. Staging nft fault rules were removed; this is a tested DNS
dependency failure, not all-outage or nonconfiguration-guard acceptance.
No new runtime firewall policy beyond normal generated native rules is supplied.
Existing shared GGC qualification is separate evidence, not an 18-transfer rerun
under DoH. Fresh TLS1.3 media: HTTP206/65536 bytes/MP4 `ftyp`/SSL0; TLS1.2
TIMEOUT is not qualified. Avatar/thumbnail qualification remains independently
outstanding; no whole-service READY claim. Historical media results below do
not close these gates on this image. Generic service integration and maximum
strategy collection remain future work, without a new policy framework.
Private supplied reports (not reread here):
`/home/agent/zapret2-autotune-rc-doh-721cad4/live-upgrade-private/`, then latest
`/home/agent/zapret2-autotune-rc-doh-544dda7/live-upgrade-private/`.
No deployment/probes accompany this docs update; later docs are not tested source.
State/credentials/private env were preserved, staging containers removed, old
user SS1080 and user-stopped proxy unchanged. See the deployment guide for the
four DNS settings, LIVE env location, privacy boundary and recreation lifecycle.
## Autonomous three-CDN acceptance (2026-10-13): media qualified, NOT READY
Supplied field results bind source `3fc8563995e890310580ba8f78850b92fea42136`
to managed image `sha256:a902e4efd949a7ffce4414fd99ab4a815a643b40cf9b9e30e2bd2db7b452817a`,
container `4c6b34…`, Compose project `rc0398e6f…`, SOCKS `127.0.0.1:11082`.
Native post-cooldown recovery at 08:07–08:09 automatically discovered three actual
ordinary signed-media hosts without manual domains and promoted Adaptive candidate10
through fresh version-1 `owned-nfq-media-range-v1` proof and deployed checks.
Generation9→10, IDs `[1,3,9]`→`[1,9,10]`, scope
`experimental_googlevideo_suffix`→`suffix`; frontend1, thumbnail9 and common
`googlevideo.com` hostlist were preserved (config hash prefix `dc997ac91…`).
Measured hosts were `rr16---sn-n8v7znsz.googlevideo.com`,
`rr18---sn-n8v7zns6.googlevideo.com`, and `rr5---sn-n8v7kn76.googlevideo.com`:
each passed post-warmup 3/3 on TLS1.2 and TLS1.3, all18 HTTP206/65536-byte
MP4 `ftyp` transfers with Range `0..65535` and valid SSL verification.
Separate warm attempts/failures were 2/0, 3/1, 3/1 respectively, not cold evidence.
Fresh owned proof checked at `2026-10-13T08:08:28.752Z` retains actual endpoints,
source IDs and native-owner Lua binding; three roots/prefixes were measured.
Native request statistics were not persisted; manual request count is unknown.
At 08:21:48 the reported container and monitor were alive, but whole-service
health remained false / DEGRADED. Probe failures405 at 08:20:37 do not independently
establish an avatar-specific cause; yesterday's avatar timeouts are separate.
The orchestrator's fresh owned-SOCKS greeting was `0500`; native `socks5h` uses
SS DNS `8.8.8.8`. The passive SSH watch vanished after about ten minutes;
no normally completed 18-minute watch is claimed. No cooldown was reset.
Private supplied proof: `/home/agent/zapret2-autotune-rc-3fc8563/field-private/proof/final.safe.json`
(not independently reread by this docs update). No new deployment/probes here.
See [PROGRESS.md](PROGRESS.md) for the measured snapshot and remaining gates.
The user's three-CDN requirement is retained; the proposed single-CDN relaxation
was withdrawn. Service-mode discovery needs no manual domains: missing/empty
`ZAPRET_AUTOTUNE_GOOGLEVIDEO_VIDEO_IDS` uses primary `ZAPRET_AUTOTUNE_VIDEO_ID`
(default `dQw4w9WgXcQ`) plus `aqz-KE-bpKQ` and `jNQXAC9IVRw`, deduplicated.
A nonempty JSON array of 1..5 unique VideoIDs overrides this inventory. VideoIDs
are discovery inputs, not proof of distinct CDNs.
Fresh round-robin Player requests are bounded to three rounds (at most 15 requests)
and three minutes. Qualification selects three actual signed MP4 media hosts,
with at least two roots and two prefixes, and twenty-minute remaining URL TTL.
Only the existing version-1 owned native proof factory authorizes qualification:
post-warmup actual media 3/3 on both TLS protocols for each measured endpoint.
The common `googlevideo.com` suffix is an authorized extrapolative scope, not
measured evidence for every Googlevideo host or cold/uniform behavior.
Experimental promotion uses the same proof and fresh deployed three-host media
checks before committing apply. Insufficient inventory preserves the current
experiment and uses configured retry cooldown; genuine exhausted strategy search
still waits at least two hours. Qualified frontend is required; avatar success
does not block this media stage, but whole-service health remains DEGRADED until
actual avatar checks pass. Legacy service-off/exact-host behavior is unchanged.
The representative three-CDN Adaptive promotion is field-qualified above;
whole-service/avatar acceptance remains open. The 2026-10-12 measured results
below are historical, not the new factory evidence. New images still require
their own source/image binding and guarded apply/rollback acceptance. Maximum
strategy collection/search diversity and PID1 global-failure stay-alive remain unfinished future
increments. Arbitrary declarative service configuration is future work; no new
generic policy framework is supplied. See [GOOGLEVIDEO_DISCOVERY.md](GOOGLEVIDEO_DISCOVERY.md).
`managed init|reconcile|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` | `socks5h://127.0.0.1:$SOCKS_PORT` (expanded value; legacy `socks5` validated and canonicalized internally) |
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 deployment entrypoint must ensure the base daemon actually
honors the exact `ZAPRET_CONFIG` path; isolated RC acceptance does not waive
that check for a new image.
Existing services would require a separately designed managed **include
fragment**, not this full-config adapter. No such integration is implemented.
```sh
# 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](deploy/managed-target/README.md) supplies
the marker, mount and ordered startup; isolated deployments are recorded below.
No Docker socket, old target paths, Xray edits or host firewall provisioning
are included. Before each new 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.
If any image/startup/routing requirement 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. `managed monitor` binds those callbacks and only the
dedicated target entrypoint starts it; local and isolated runtime validation
results, with their limits, are recorded in [PROGRESS.md](PROGRESS.md).
## Dedicated monitor integration (isolated clean-run acceptance passed)
`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 owned DNS readiness (default DoH) → SS children → listener → fresh managed init if needed → managed reconcile → zapret start
→ one installed `/usr/local/bin/zapret-autotune managed monitor` child. It supervises
the DNS, SS and monitor children; unexpected monitor exit is not a successful shutdown.
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 240s Compose shutdown grace for bounded
monitor cancellation/restoration and child joins. Clean RC `d8316e6` has passed
isolated image/routing, bootstrap, periodic probe, monitor-crash cleanup, graceful
stop and persistent recreation gates; see the
[recorded source/image and PASS report](deploy/managed-target/README.md#recorded-clean-run-acceptance-2026-10-11-pass).
This does not establish playback or blanket production approval.
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. Verification results are
recorded in [PROGRESS.md](PROGRESS.md). Focused local checks can be rerun with:
```sh
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. Container provisioning instructions
are described in [deploy/managed-target/README.md](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.
Both Dockerfiles require BuildKit for the compilation-cache mount at
`/root/.cache/go-build` (enable with `DOCKER_BUILDKIT=1` if not already default).
This cache only speeds rebuilds; it is not copied into the final runtime image
and is not a secret store. No deployment credentials are needed or passed to
the build; keep secrets out of build arguments and cache contents.
Example (replace registry and release; never reuse a release tag):
```sh
IMAGE=registry.example/team/zapret-autotune-managed-target:2026-10-10-r1
docker build --pull -f Dockerfile.target -t "$IMAGE" .
test "$(docker image inspect --format '{{json .Config.Entrypoint}}' "$IMAGE")" = '["/bin/sh","/opt/managed-target-entrypoint.sh"]'
docker run --rm --network none --entrypoint /bin/sh "$IMAGE" -ec 'test "$(cat /etc/zapret-autotune/target-id)" = zapret-autotune-managed-v1; test -f /opt/managed-target-entrypoint.sh'
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:
```sh
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
```
Do not omit `-f Dockerfile.target`: root `Dockerfile` builds the proposal/prototype,
not the PID-1-managed target. Assert both entrypoint and provisioned marker on the
exact selected image before promotion; the assertions above are image-contract
checks, not live resource qualification. A managed-looking tag is insufficient.
Start the selected container image with Compose `up --no-build`;
no host service installation is required. 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_DNS_MODE` | `doh` default; explicit `native` opts into the old resolver, never automatic fallback |
| `ZAPRET_AUTOTUNE_DOH_URL` | `https://dns.google/dns-query`; HTTPS/443 path, no userinfo/query/fragment; path may be secret |
| `ZAPRET_AUTOTUNE_DOH_BOOTSTRAP_IPS` | Compose default empty: parser selects `8.8.8.8,8.8.4.4` only for exact default Google URL; custom provider requires explicit 1–4 comma-separated literal IPs without spaces |
| `ZAPRET_AUTOTUNE_DOH_TIMEOUT_SEC` | `5`; integer 1–30 |
| `SS_DNS_SERVER` | Explicit native mode only: empty retains base resolver or literal IPv4/IPv6; ignored in DoH mode |
| `ZAPRET_AUTOTUNE_YOUTUBE_SERVICE` | `0` (legacy) or opt-in `1`; explicitly forwarded by Compose |
| `ZAPRET_AUTOTUNE_GOOGLEVIDEO_MODE` | `cold` default or `adaptive` (requires service `1`); explicitly forwarded |
| `ZAPRET_AUTOTUNE_GOOGLEVIDEO_VIDEO_IDS` | JSON array of 1..5 unique VideoIDs; defaults to only the primary ID; explicitly forwarded |
| `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 `socks5h://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` |
Managed Player, metadata, image, media and warmup requests send hostnames through
the owned SS listener (`socks5h`), so they respect target-native DNS instead of
bypassing it with curl's local resolution. Older private environment overrides
using `socks5` are canonicalized internally after validation; arbitrary proxies
remain rejected by the listener/port/process ownership guard. Legacy public CLI
discovery and root checker `--resolve` pinning are unchanged. This corrects a DNS
path bypass, not a proven explanation of earlier peer certificate failures.
The monitor's three policy flags override corresponding environment defaults;
explicit empty/invalid environment settings are rejected. The entrypoint accepts
no arguments. Compose forwards the primary/sample VideoIDs and service/mode settings.
It does not forward the interval/threshold/cooldown policy
settings from `.env`: add those 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.
Current service/adaptive hardware acceptance is **pending**, independent of the
recorded legacy RC PASS. Adaptive means post-warmup, not cold: first connections
may fail and native learning repeats after restart. At least three real unique
signed ordinary media host samples are required; multiple VideoIDs may yield one
CDN host and leave `DEGRADED` with no authorized suffix. Sampled thumbnail/avatar
routes do not prove availability of the whole thumbnail pool. The reported
`8.8.8.8` DNS diagnostic corrected a tampered avatar, not all thumbnail routes;
native DNS correction is not full asset availability proof. Default DoH uses
SS `-d 127.0.0.1:5353`; explicit native mode uses validated literal `-d` argv,
with installed-option support checked at image build. Passwords remain private
JSON only. No permanent service IP pins, global host DNS edits or external
startup manager are introduced.
### Supervision and failure handling
The container entrypoint is PID 1 and owns all technical child restart control.
After a retryable monitor/SS failure it joins children, reconciles trusted state
and stops target-local zapret before starting a new runtime cycle in the **same
container**. Retries use cancellable backoff (15s, 30s, capped at 60s) and at most
three runtime starts per rolling six hours, including the initial start. Exhaustion
stops fail-closed with 78; configuration, safety, DB, journal, rollback or cleanup
errors never authorize retry. No new dependency, host service installation or
external process manager is required. SIGTERM/SIGINT cancels backoff or the running
monitor, waits for bounded restoration and joins children before exit.
In default DoH mode PID 1 first starts the stdlib UDP/TCP loopback DNS forwarder
inside the existing Go binary (no dependency or new container),
waits at most five seconds for its owned private PID marker, and only then starts
ss-server with `-d 127.0.0.1:5353`. No host DNS port or DNS/iptables changes are
made. Hostname SOCKS traffic and managed `socks5h` checks use the same encrypted
HTTPS resolver; clients must enable remote SOCKS DNS, not resolve locally or
send IP literals. Bootstrap uses configured literal IPs with verified TLS and
mark `0x50000000` direct sockets excluding probe/live NFQUEUE, with no system DNS, proxy
or plaintext fallback. The DoH resolver sees queries directly, not SS-tunneled;
the plaintext helper exchange stays on loopback5353. Endpoint failures produce
SERVFAIL without child exit or plaintext fallback. A forwarder crash, unlike an
upstream outage, uses the same bounded technical retry budget. The DNS child
stays alive through monitor restoration, zapret stop and SS joins; it is then
terminated/joined within five seconds and only its validated readiness inode is
removed using PID1-held directory/file anchors. Foreign/stale/replaced readiness
is preserved and vetoes startup/retry; SIGKILL does not lose owned cleanup proof. Explicit
native mode has no DNS child. See the deployment README for provider settings
and scope limits. Supplied staged-outage and LIVE DNS acceptance are recorded
above; they do not establish all-outage resilience or whole-service readiness.
Compose restart remains disabled: a blanket container restart could loop over a
safety refusal or reset the in-container retry budget. Compose stop grace is 240s:
the sequential cleanup budget is 145s (45s monitor join, 45s reconciliation plus
5s kill grace, 30s zapret stop plus 5s kill grace, two 5s SS joins and a 5s DNS join), with room
for a deferred 45s startup command plus kill grace and scheduling overhead.
The join watchdog runs in a fresh shell and is cancelled when its child finishes;
graceful shutdown does not wait out the watchdog's full deadline.
Container-platform lifecycle, creation/recreation and host-boot policy belong to
the deployment operator, not an external manager supplied by this project.
| Target exit | Operator meaning |
| --- | --- |
| `64` | Invalid configuration; fix settings before starting |
| `78` | Safety/DB/journal/rollback/cleanup failure; investigate, no automatic restart |
| `75` | Internal technical-cycle result; PID 1 retries only after safe cleanup, within its budget |
| `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, not a reason
to restart the container. Genuine **no qualified strategy** from validated scan/check
evidence persists a recovery wait of at least **two hours** in SQLite, including
empty bootstrap and frontend/GGC exhaustion. The same container stays alive and
continues light periodic Player API probes; it does not scan or apply during that
wait. Startup respects the durable expiry, and recovery resumes after expiry under
the normal failure-threshold policy. In both fresh bootstrap and periodic recovery,
the delay is the greater of two hours and the configured recovery cooldown;
a longer configured cooldown is not shortened.
Other ordinary recovery outcomes retain the configured cooldown (default **30m**).
Malformed/incomplete reports, runner errors and unsafe state are not strategy
absence and must not enter this wait. The two-hour minimum absence policy is not a
new operator setting, technical retry backoff, or the **90-minute watchdog**. 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 uses bounded monitor join,
guarded reconciliation, target-local zapret stop and SS child joins;
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
1. Record the current image digest and private deployment configuration. Stop
the target with Compose, wait for complete cleanup, and verify
the target is stopped. If cleanup fails, investigate before upgrading.
2. 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 `.env` and image/config records privately
with it; do not print archive contents, diagnostics or signed URLs. A live
copy of only `candidates.db` is not a consistent rollback backup.
3. 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.
4. 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 startup, `managed reconcile` accepts no flags and uses only the fixed private
`/var/lib/zapret-autotune/target/candidates.db`. Known interrupted prepared state
is rolled back to qualified committed bytes before any reload/start; fresh
baseline and known committed state are idempotent. Unknown/legacy state, drift,
missing qualification or failed rollback blocks startup with a non-retry exit.
On drift, unreconcilable pending transaction, rollback failure, or exhausted PID 1 retry
budget, leave state intact and the container stopped. Diagnose using sanitized status
and private artifacts; repair the actual provisioning/configuration issue or
restore a known consistent backup. Only then manually start the target with Compose.
There is no automatic wipe or
automatic adoption path.
The recorded clean RC PASS covers empty-state bootstrap through qualified frontend
and exact-host GGC apply, image/config binding, ongoing probes, in-container monitor
crash restart, graceful stop and persistent recreation. Earlier recovery, rollback,
rotation, retry and absence fixtures are distinguished in [PROGRESS.md](PROGRESS.md);
do not attribute all of them to the clean run. No media playback, real 90-minute
watchdog expiry or real two-hour absence expiry wait is claimed. Production rollout
and backup-restore acceptance remain operator gates on a new isolated target;
local unit/static checks and isolated PASS do not establish blanket production readiness.
### Explicit experimental Googlevideo suffix
Normal `--googlevideo-scope suffix` still requires representative qualification,
media proof, and both qualified image profiles. An operator may explicitly own
the audited native circular A/E composite without claiming those results:
```sh
zapret-autotune managed apply --googlevideo-experiment native-circular --googlevideo-scope experimental_googlevideo_suffix
```
This command requires the monitor singleton to be free, a matching native Lua
hash, a fresh Player-discovered exact GGC identity, and existing qualified
frontend/assets. It preserves their candidate IDs and uses the normal guarded
transaction/reload/Player-health/rollback hooks. The new candidate definition
has no cold/adaptive evidence and is not a qualified candidate. Both pending
and committed journal policy record `experimental_googlevideo_suffix`; legacy
rendered bytes and qualification gates are unchanged. Unknown policies fail closed.
For PID-1-controlled application, while this dedicated target is stopped and
after taking a complete private state backup, create a private empty file named
`.autotune-experimental-suffix-request` in its owned state directory. It must be
an empty regular 0600 file owned by the runtime UID, with no symlink/hardlink.
Startup validates it before init/reconcile, then atomically claims the validated
inode before guarded apply (before launching the monitor). Only a successful
apply removes that claim; a replacement request is never deleted. Failure exits
closed and retains the private `.autotune-experimental-request-claim-*` artifact;
do not blindly retry it. Use the matched whole-state/image rollback above.
Candidate-ID CLI apply cannot select/inherit the experimental policy; explicit
native-circular authorization is required. Internal journal recovery is unchanged.
Resource probes still run. In service mode (legacy or adaptive), healthy actual
image/media probes short-circuit recovery, but operational health does not mean
family qualification or playback READY. Experimental media recovery preserves
the operator suffix and all committed profile IDs: a validated transfer failure
permits one guarded restart of that same deployed daemon, then at most 10 native
relearning attempts within 120s and a final fresh signed media 3/3 for each of
TLS1.2 and TLS1.3. Learning stays in the persistent daemon's RAM; no temporary
NFQ worker or replacement/qualified candidate is created. Expiring media is
rediscovered, never rewritten or persisted. Missing inventory remains degraded,
not strategy absence; mixed, guard, infrastructure and cancellation errors do
not authorize relearning. Unrelated missing image inventory may coexist with
usable media, but successful media recovery does not repair or qualify it.
Avatar inventory first parses fresh homepage `ytInitialData`. Only absent metadata
or no allowed avatar permits one fallback to the configured video's watch page,
using a validated video ID, the same trusted HTTPS WWW origin and SOCKS proxy,
bounded time/body size, no redirects, and discarded diagnostics. Malformed JSON,
transfer errors and safety/cancellation failures do not trigger fallback. Both
pages and discovered resource URLs remain ephemeral; discovering an allowed URL
is not image-transfer qualification or a guarantee of full-family coverage.
`managed status` reports active-profile `covered=` separately from qualified
`groups` and `unresolved_groups`; `managed active-ids` adds `covered_groups` and
`googlevideo_scope` to its JSON. An experimental Googlevideo profile can be
covered yet qualification-unresolved; one image profile does not establish full
asset-inventory success. Status is read-only and reports live health NOT CHECKED.
Historical `a60f62d` restart/recreation and status checks passed, but its upgrade
hit `BrokenPipe` and rolled back; that run did not accept media recovery. Later
supplied final field results for source `fd25cb8`, managed image
`sha256:73e955e7fdc6efaef88c62ebe4f7afeab71c29d29ba3c88b2a2b7547bb647da5`
on SOCKS11082 completed a 15-minute watch with restart count0 and a live monitor.
Validated rejection/no-qualified-strategy recovery continued with naturally
advanced cooldown and unchanged experimental profiles; it did not repair avatars.
Three fresh media hosts across two roots passed post-warmup 3/3 on each TLS
protocol (18 actual HTTP206/65536-byte MP4 transfers). This is field evidence,
not persisted family qualification, a cold/all-host claim or candidate promotion.
Watch fallback discovered allowed avatar metadata, but both-TLS curl28 transfers
had zero samples: avatar evidence/profile qualification is still absent and
overall health is **DEGRADED / NOT READY**. Automatic durable multi-host family
qualification remains unimplemented. See [PROGRESS.md](PROGRESS.md) for exact
hosts, separate warmup results, timestamps, private proof and remaining gates.
No new network checks accompany this documentation. Generic production
media behavior and signed-URL/SS secret privacy remain unchanged, as do the
persisted minimum two-hour strategy-absence pause and 90-minute whole-job budget.