82 lines
2.2 KiB
Groff
82 lines
2.2 KiB
Groff
|
.\" 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>.
|