docs: add README and manual pages

2026-10-15 14:29:19 +03:30
parent 7f11dd2c01
commit 5cb1c282c1
3 changed files with 716 additions and 0 deletions
@@ -0,0 +1,81 @@
+.\" Manual page for prx-helper
+.\" Copyright (C) 2026 Amir Husayn Panahifar <ahp@panahifar.ir>
+.TH PRX-HELPER 1 "2026-10-15" "prx 0.1.0" "User Commands"
+.SH NAME
+prx-helper \- privileged core of prx
+.SH SYNOPSIS
+.B prx-helper
+.SH DESCRIPTION
+.B prx-helper
+is the privileged half of
+.BR prx (1).
+It reads a single JSON
+.I plan
+from standard input, validates it, executes it, and writes a JSON result to
+standard output.
+.PP
+It is not meant to be run by hand; the unprivileged
+.B prx
+CLI launches it through
+.BR pkexec (1)
+or
+.BR sudo (8),
+and communicates over standard input and standard output.
+It refuses to run without root privileges.
+.PP
+Every field of the incoming plan is re\-validated before any system change is
+made, so the privileged attack surface stays small.
+The
+.B apply
+operation is transactional: if a post\-apply health check fails, the changes
+made so far are rolled back.
+If a rollback step itself fails, that is reported in the result rather than
+being ignored.
+.SH ACTIONS
+The plan's
+.B action
+field selects one of:
+.TP
+.B apply
+Detect the WAN interface and gateway, install the nftables table, the policy
+rule and route, any bypass rules and routes, ensure the engine is running, run
+health checks, and record the state snapshot.
+A health\-check failure triggers a rollback.
+.TP
+.B remove
+Remove the prx\-managed rules, tables and routes, optionally stop the engine,
+and delete the state snapshot.
+.TP
+.B inspect
+Report the state of the rules, tables, engine and TUN interfaces without
+changing anything.
+.TP
+.B engine
+Start, stop, reload or query the engine service.
+.TP
+.B init-engine
+Write a generated engine configuration to disk after validating it as JSON.
+.SH SECURITY
+Input is treated as untrusted.
+Interface names, IP addresses, CIDR blocks, route table identifiers, rule
+priorities, marks and service names are validated against strict patterns and
+ranges before being used to build nftables scripts or
+.B ip
+commands.
+.SH "EXIT STATUS"
+.TP
+.B 0
+The action succeeded.
+.TP
+.B 1
+The action failed, or the process was not run as root.
+.TP
+.B 2
+The plan on standard input was malformed, or the result could not be encoded.
+.SH "SEE ALSO"
+.BR prx (1),
+.BR polkit (8),
+.BR pkexec (1),
+.BR sudo (8)
+.SH AUTHOR
+Amir Husayn Panahifar <ahp@panahifar.ir>.