Module admin 

The admin socket (kernel spec §4.2): <data>/admin.sock, a Unix socket only the collector’s own user may use, for hennery admin … recovery commands that work without a browser or a session: print the setup link, reset the password or public_url, list the hosts, mint a pairing code.

• Who may connect: the socket is 0600, and a peer whose user id is not the collector’s is dropped without an answer. The client refuses, in turn, a socket served by another user. Any process of the collector’s own user is the operator here, agents of the all-in-one install included (kernel spec §10): it can reset the password or public_url and mint pairing codes. The CLI’s confirmation on a terminal stops accidents, not a process that speaks this protocol.
• The protocol: one JSON AdminRequest on one line, at most MAX_REQUEST_BYTES, within REQUEST_TIMEOUT; one JSON AdminResponse on one line back; then the connection closes.
• One collector per data directory: binding refuses a socket that still answers, replaces one that refuses the connection (a collector that was killed), and stops at any other error. The socket is removed when its AdminSocket is dropped.

Structs

Admin

What the admin commands act on: the router’s own Operator and Hosts, never a second instance, since the cached public_url and the setup token live in that one.

AdminHost

One paired host, as list_hosts shows it. Times are seconds since the Unix epoch.

AdminSocket

A bound admin socket. Dropping it removes the socket file, however the collector stops.

Enums

AdminRequest

AdminResponse

Constants

ADMIN_SOCKET

The socket’s name in the collector’s data directory (kernel spec §1).

CLIENT_TIMEOUT

How long the client waits for the whole exchange: connecting, sending the request and reading the answer. The slowest command is a password reset, one Argon2 hash on a blocking thread: about 0.1 s, measured in a debug build (where argon2 is built optimised), run at most MAX_CONCURRENT_HASHES at a time with the logins’. Only a login flood queued ahead of it (rate limited per address, not in total) could take it past this; the client then says the outcome is unknown.

MAX_REQUEST_BYTES

The longest request line read, newline included.

REQUEST_TIMEOUT

A connection that has not sent its whole request by then, or not taken its whole answer, is dropped.

Functions

bind

Bind dir/admin.sock, mode 0600. Ok(None), with a warning, when that path is too long for a Unix socket: the collector then runs without it. Refused when the socket there still answers: another collector serves this data directory. One that refuses the connection is replaced; any other error (not a socket, not ours to connect to) stops the start and is named.

max_socket_path_bytes

The longest path a Unix socket can be bound or reached at, in bytes: sun_path less its terminating NUL (103 on macOS, 107 on Linux).

probe

Check, sending nothing, that a collector of this user’s serves socket: what a command that prompts does first, so that nothing is typed into a dead end. The connection is closed unused. Bounded by timeout, like request_within.

read_answer

One AdminResponse line from stream, at most MAX_RESPONSE_BYTES.

request

The client’s side: send request to the collector at socket and read its answer, within CLIENT_TIMEOUT.

request_within

request, bounded by timeout. The answer is read one line, not to the end of the stream: a collector that closes with part of a request unread resets the connection on Linux, after its answer.

serve

Answer admin commands until shutdown resolves, then remove the socket (by dropping it).

socket_path_too_long

Whether path is too long for a Unix socket: the collector then runs without its admin socket, and the client says so rather than failing to connect (3b-ii’s O7).