129 lines
7.8 KiB
Markdown
129 lines
7.8 KiB
Markdown
# 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.
|
||
|
||
```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) 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,
|
||
monitor loop 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.
|
||
|
||
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:
|
||
|
||
```sh
|
||
go test ./cmd/zapret-autotune -run TestManaged
|
||
go build ./cmd/zapret-autotune
|
||
```
|