PoolRotater Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== v7 operator commands ======

These are administrative commands on the hosting machine, **not dot commands to send in osu! or Discord**. Use the protected admin entry from the currently registered release, as root, with the exact instance selected. An entry from an old release intentionally refuses after upgrade. Get the entry path and artifact hashes from the qualified kit or maintainer; do not guess a release directory.

^ Reference | Reviewed v7.0.1 dev12 operator kit and qualified v7.0.2 controller additions, October 14, 2026 |
^ Installation guide | Follow the exact kit's README and upgrade guide; this overview does not replace their admission checks or configuration schemas |

The examples use ''$E'' as shorthand for the complete, instance-bound protected administrator invocation. It must already select the correct installed entry and instance. Do not paste the shorthand until your kit has defined it.

===== Inspect the installation =====
^ Action ^ Purpose ^
| ''check'' / ''code-proof'' | Validate the protected installation/code binding |
| ''status'' / ''support'' | Inspect lifecycle, authorization, catalog and ownership summaries; support is suitable for redacted diagnostics |
| ''room-settings-status'' | Read saved room settings |
| ''network-status'' / ''network-support'' | Inspect enrollment, heartbeat and network-agent observations |
| ''ratings-status'' / ''ratings-support'' | Distinguish local capture, pending uploads, synchronization and selected feedback mode |
| ''ownership-review'' | Read-only ownership preparation with the hosting and network services stopped as required by the kit |

Systemd failure and room ownership are different facts. A stopped old process can leave a failed unit while the authoritative journal and committed recovery receipt report clean ownership. A local ''start_allowed: false'' with ''startup_admission_not_evaluated_by_local_status'' means status has not performed startup admission. ''recovery_required'' is a real recovery hold. Fresh startup still checks identity, client/scopes and ownership; do not treat a valid token alone as permission to start.

===== Setup, catalogs and services =====
^ Action ^ Purpose and boundary ^
| ''configure'' / ''authorize'' | Configure the operator's local OAuth client and complete their own sign-in; keep secret inputs local |
| ''catalog-import'' | Download/import full prepared catalogs using the kit's exact HTTPS origin, trusted keys, CA and hash pins |
| ''room-settings-configure'' | Apply supported saved settings through the protected schema; existing topology changes require review |
| ''unit'' / ''start'' / ''stop'' | Install the service unit, perform fresh startup admission, or intentionally close this instance's rooms |
| ''network-configure'' / ''network-enroll'' | Apply bound hub configuration and redeem that operator's invitation |
| ''network-unit'' / ''network-start'' / ''network-stop'' | Manage the separate network agent |
| ''ratings-configure'' / ''ratings-reader-configure'' | Explicitly configure sharing and feedback-reading preferences |
| ''ratings-sync'' / ''ratings-fetch'' | Supported one-shot upload/fetch operations; a running agent normally handles its own schedule |

Configuration and catalog actions have additional required arguments or protected standard-input schemas. Follow the shipped guide rather than running an incomplete action name. Hub contribution permission is separate from enrollment and sharing consent. Running two controllers on one hosting account is not a supported way to add rooms.

===== v7.0.2 compatible worker updates =====
**Requires the new controller to be installed and active. These actions are not available merely because the owner has queued v7.0.2, and they are not part of the published dev12 controller.**

<code sh>
$E worker-stage --bundle /path/to/approved-worker.zip --sha256 <runtime-sha256>
$E worker-queue --sha256 <runtime-sha256> --room room1 --room room4
$E worker-status
$E worker-cancel
</code>

Omit ''--room'' to select all configured rooms. Stage verifies compatibility and writes a root approval bound to this installation; it does not replace the controller. Queue waits for native empty/idle admission, and status reports its durable progress. Cancel affects pending rooms after an active handoff settles. A failed attempt needs explicit requeueing. Completed promotions remain selected after a clean restart.

Shared controller/dependency/storage changes require their separate approved procedure. The first owner's all-four-empty controller queue is a bounded migration and is not an instruction to install that artifact on an unrelated operator instance.

===== Recovery and useful reports =====
Ownership, pacing and catalog recovery commands require fresh evidence and exact transaction or journal bindings. Use REPAIR_UPGRADE.md from the actual kit with the maintainer. Do not delete journals, reset state or repeatedly start to escape a hold. ''systemctl reset-failed'' only clears systemd's failure marker; it does not prove a room has closed or repair ownership.

Return room links, times/timezone, versions, completed maps, player-visible behavior and redacted support/network/ratings output. For failures include the safe failure code, HTTP status when known, and a short relevant traceback. Never send OAuth credentials/codes/URLs, token files, bound invitations, private state hashes, backups or raw player chat.

[[guides:hosting|Hosting checklist]] · [[wiki:distributed_hosting|Hub participation]] · [[wiki:room_updates|Updates and recovery]]