Skip to content

operations.md

Latest commit

 

History

History
115 lines (85 loc) · 4.7 KB

operations.md

File metadata and controls

115 lines (85 loc) · 4.7 KB
Raw

Operations

Inspect service state, diagnose setup and manage the lifetime of running instances.

Contents

Read local status

Read one snapshot from the local service processes:

nowhere status

Status discovers protected IPC endpoints, queries at most eight instances at a time with a two-second deadline per instance, and exits without requiring a terminal. Results are sorted by role, PID and instance ID. Successful snapshots remain visible when another instance fails; partial failures are reported.

Display Meaning
Role, PID, instance ID and endpoint Process identity
TCP/UDP upload and download Per-process cumulative logical payload
TCP/UDP Flows Active business Flow owners

Counters continue without clients. JSON IPC carries statistics; stdout carries startup, TLS fingerprint and graceful shutdown logs, while stderr carries raw errors. Collectors must not add different processes' totals as unique end-to-end bytes.

Diagnose target setup

Perform one real TCP Flow setup using Vector's configured transport:

nowhere probe "vector://KEY@relay.example:2000?pin=TRUSTED_SHA256" "example.com:443"

in is optional for probe. READY verifies the selected Portal output; probe sends no target payload. Output failures return the fixed SetupResult described in the wire specification.

Read a presented certificate over TCP/TLS:

nowhere fingerprint "nowhere://KEY@relay.example:2000?morph=1"

fingerprint requires morph=0|1 matching Portal; #NAME and an sni DNS name are optional. Inspection uses TCP/TLS even with net=udp, so the shared host and port must expose TLS. Compare the result through a trusted channel before configuring a pin. See Security.

Running nowhere without arguments displays help and exits normally.

Check deployment settings

Expose the declared Portal carrier ports and the intended SOCKS ingress. Confirm certificate trust, Morph agreement, the endpoint carrier, in and out. Startup output shows the effective role URL with explicit defaults and redacted credentials.

See Configuration for parsing and redaction rules, and Platforms for firewall and container exposure.

Monitor Egress

Portal's out is fixed for its lifetime. out=egress requires a QUIC listener and cannot specify dial, dial4 or dial6. New Flows fail immediately while Egress is offline; a second registrant receives BUSY.

Registration ownership remains internal to forwarding. An idle registered Egress has no business Flow. Diagnostic stderr reports registration, reconnection and target failures. Use nowhere probe to test a real target setup; process running means the process is alive, not that every target is reachable. See Egress.

Understand failure boundaries

Failure Effect
Ordinary setup or forwarding failure Ends the affected Flow
Authentication or business Stream direction violation Closes the connection
Egress connection loss Ends every dependent bridge
UDP control FIN, RESET, STOP_SENDING, idle timeout or connection loss Reclaims that Flow's routes and resources

TLS is dedicated per Flow. QUIC carries business Streams in one initiation direction. Reconnection starts new Flows. UDP control Streams remain open through their lifetime; losing a CLOSE DATAGRAM does not keep a route alive.

Manage capacity and shutdown

Admission and business resources are bounded. UDP budgets cover queued and reassembly bytes; full Flow queues drop datagrams without blocking the connection dispatcher. A shared Egress also shares congestion and budgets. Observe per-process and per-Flow behavior when choosing concurrency or rate settings. Use Testing for measurements.

Shutdown stops admission, cancels service work and drains within NOW_SHUTDOWN_TIMEOUT (default 5s). Tasks and owned resources are reclaimed; active counters decrement with their owners. Pending handshakes, authentication and Egress registration waits are cancelled without waiting for their timeouts. A timed-out drain aborts remaining tasks. QUIC UDP ID exhaustion also stops new Flows and closes or reconnects after bounded drain, without an additional protocol frame.

See process control for native shutdown signals.