280 lines
6.2 KiB
Groff
280 lines
6.2 KiB
Groff
.\" Manual page for prx
|
|
.\" Copyright (C) 2026 Amir Husayn Panahifar <ahp@panahifar.ir>
|
|
.TH PRX 1 "2026-10-15" "prx 0.1.0" "User Commands"
|
|
.SH NAME
|
|
prx \- safe proxy routing manager
|
|
.SH SYNOPSIS
|
|
.B prx
|
|
.RI [ options ]
|
|
.I command
|
|
.RI [ arguments ]
|
|
.SH DESCRIPTION
|
|
.B prx
|
|
turns proxy routing on and off without breaking the connections that reach
|
|
your host.
|
|
In particular, an inbound session that is already open when the proxy is
|
|
enabled (for example an SSH login) keeps working, regardless of the port it
|
|
uses.
|
|
.PP
|
|
The tool orchestrates an external proxy engine (by default
|
|
.BR sing-box (1)
|
|
in TUN mode, managed through systemd) and installs the network configuration
|
|
needed to keep reply traffic on the physical uplink:
|
|
.IP "1." 4
|
|
Incoming connections on the WAN interface are tagged with a conntrack mark
|
|
(\fB0x100\fR by default).
|
|
.IP "2." 4
|
|
Outgoing packets belonging to a connection whose
|
|
.I original
|
|
destination is one of the host's WAN addresses are tagged as well.
|
|
Because the original destination is matched, connections that were already
|
|
established before
|
|
.B prx on
|
|
are protected too.
|
|
.IP "3." 4
|
|
An
|
|
.BR ip-rule (8)
|
|
entry routes marked packets through a dedicated routing table whose default
|
|
route points at the physical gateway rather than the tunnel.
|
|
.PP
|
|
Because the decision is based on the connection and not on a port number, the
|
|
protection is port\-independent.
|
|
.PP
|
|
All privileged work is performed by a small helper,
|
|
.BR prx-helper (1),
|
|
which the unprivileged
|
|
.B prx
|
|
CLI invokes through
|
|
.BR pkexec (1)
|
|
(polkit), falling back to
|
|
.BR sudo (8)
|
|
when polkit is not installed.
|
|
.SH OPTIONS
|
|
.SS Global options
|
|
.TP
|
|
.BR \-\-config " " \fIFILE\fR
|
|
Read configuration from
|
|
.IR FILE .
|
|
Defaults to
|
|
.IR $XDG_CONFIG_HOME/prx/config.json
|
|
(or
|
|
.IR ~/.config/prx/config.json ).
|
|
The environment variable
|
|
.B PRX_CONFIG
|
|
overrides this default.
|
|
.TP
|
|
.BR \-v ", " \-\-verbose
|
|
Enable verbose logging on standard error.
|
|
.TP
|
|
.BR \-h ", " \-\-help
|
|
Show help for
|
|
.B prx
|
|
or for a subcommand.
|
|
.SH COMMANDS
|
|
.TP
|
|
.BR on " [" \-\-skip\-engine "] [" \-\-dry\-run ]
|
|
Enable proxy routing.
|
|
Installs the nftables table
|
|
.BR "inet prx" ,
|
|
the policy rule and route, and (for extra bypass CIDRs) the bypass rules and
|
|
routes, then ensures the engine service is running and runs health checks.
|
|
If a blocking health check fails, every change made so far is rolled back and
|
|
the command exits non\-zero.
|
|
Re\-running
|
|
.B on
|
|
is idempotent.
|
|
.TP
|
|
.B off
|
|
Disable proxy routing.
|
|
Removes only the objects
|
|
.B prx
|
|
created: the
|
|
.B "inet prx"
|
|
table, any rules that look up
|
|
.BR prx 's
|
|
routing tables, and
|
|
.BR prx 's
|
|
routes.
|
|
It never flushes the whole ruleset.
|
|
Running
|
|
.B off
|
|
twice is a no\-op.
|
|
.TP
|
|
.B toggle
|
|
Run
|
|
.B on
|
|
or
|
|
.B off
|
|
depending on the current state.
|
|
.TP
|
|
.BR status " [" \-\-json ]
|
|
Print the current status.
|
|
Reads the state snapshot and inspects the policy rules without requiring root.
|
|
With
|
|
.B \-\-json
|
|
the result is emitted as JSON.
|
|
.TP
|
|
.B doctor
|
|
Run diagnostics.
|
|
Checks required binaries, the configuration, the engine configuration, mark
|
|
collisions, the applied rules and the engine status.
|
|
Exits non\-zero when a critical (local) problem is found, or when
|
|
.B prx
|
|
is enabled but the applied rules are inconsistent.
|
|
.TP
|
|
.BR bypass " add " \fICIDR\fR | \fIIP\fR | \fIDOMAIN\fR
|
|
Add a destination to the bypass list.
|
|
A CIDR or bare IP is additionally enforced at the routing layer: a route is
|
|
installed in the bypass table and a destination\-based
|
|
.B ip-rule
|
|
is added, so traffic to it never enters the tunnel.
|
|
A domain is recorded as an engine hint only.
|
|
.TP
|
|
.BR bypass " rm " \fICIDR\fR | \fIIP\fR | \fIDOMAIN\fR
|
|
Remove an entry from the bypass list.
|
|
.TP
|
|
.B bypass ls
|
|
List the bypass entries.
|
|
.TP
|
|
.BR logs " [" \-f | \-\-follow ]
|
|
Show the proxy engine's journal output (via
|
|
.BR journalctl (1)).
|
|
.TP
|
|
.BR init " [" \-\-force "] [" \-\-engine\-config "]"
|
|
Write a default configuration file to the configured path.
|
|
With
|
|
.B \-\-engine\-config
|
|
also generate a baseline engine (sing\-box) configuration.
|
|
.TP
|
|
.B version
|
|
Print version information.
|
|
.SH "ON OPTIONS"
|
|
.TP
|
|
.B \-\-skip\-engine
|
|
Apply only the routing layer without starting or stopping the engine.
|
|
Useful for testing and when the engine is managed separately.
|
|
.TP
|
|
.B \-\-dry\-run
|
|
Validate the plan with
|
|
.BR "nft \-c"
|
|
without changing anything.
|
|
.SH "INIT OPTIONS"
|
|
.TP
|
|
.B \-\-force
|
|
Overwrite an existing configuration file.
|
|
.TP
|
|
.B \-\-engine\-config
|
|
Also write a baseline engine configuration containing a TUN inbound and a
|
|
placeholder outbound.
|
|
.TP
|
|
.BR \-\-engine\-config\-path " " \fIPATH\fR
|
|
Path for the generated engine configuration.
|
|
Defaults to
|
|
.B engine.config_path
|
|
from the prx configuration.
|
|
.SH FILES
|
|
.TP
|
|
.I ~/.config/prx/config.json
|
|
User configuration.
|
|
.TP
|
|
.I /run/prx/state.json
|
|
Runtime snapshot written when
|
|
.B prx
|
|
is enabled; used by
|
|
.B off
|
|
and for rollback.
|
|
.TP
|
|
.I /run/prx/prx.lock
|
|
Advisory lock held during
|
|
.B on
|
|
and
|
|
.B off
|
|
so concurrent runs do not interleave.
|
|
.TP
|
|
.I /etc/sing-box/config.json
|
|
Default engine configuration.
|
|
.TP
|
|
.I /usr/share/polkit-1/actions/org.prx.policy
|
|
Polkit action definition mapping
|
|
.B prx-helper
|
|
to
|
|
.BR org.prx.manage .
|
|
.TP
|
|
.I /usr/lib/prx/prx-helper
|
|
Installed location of the privileged helper.
|
|
.B prx
|
|
also searches
|
|
.IR /usr/libexec/prx ,
|
|
.IR /usr/local/lib/prx
|
|
and
|
|
.IR /usr/local/libexec/prx .
|
|
.SH ENVIRONMENT
|
|
.TP
|
|
.B PRX_CONFIG
|
|
Default configuration file path, used when
|
|
.B \-\-config
|
|
is not given.
|
|
.TP
|
|
.B PRX_HELPER
|
|
Explicit path to the privileged helper, overriding the search locations.
|
|
.SH "EXIT STATUS"
|
|
.TP
|
|
.B 0
|
|
Success.
|
|
.TP
|
|
.B 1
|
|
An error occurred; a message is printed to standard error.
|
|
.TP
|
|
.B 126
|
|
Authorization was cancelled or is not permitted (from
|
|
.BR pkexec ).
|
|
.TP
|
|
.B 127
|
|
The privileged helper could not be started.
|
|
.SH EXAMPLES
|
|
Enable the proxy:
|
|
.PP
|
|
.RS 4
|
|
.B prx on
|
|
.RE
|
|
.PP
|
|
Enable only the routing layer, without touching the engine:
|
|
.PP
|
|
.RS 4
|
|
.B prx on \-\-skip\-engine
|
|
.RE
|
|
.PP
|
|
Validate without making changes:
|
|
.PP
|
|
.RS 4
|
|
.B prx on \-\-dry\-run
|
|
.RE
|
|
.PP
|
|
Keep a subnet out of the tunnel and refresh the rules:
|
|
.PP
|
|
.RS 4
|
|
.B prx bypass add 203.0.113.0/24
|
|
.RE
|
|
.PP
|
|
Check status as JSON:
|
|
.PP
|
|
.RS 4
|
|
.B prx status \-\-json
|
|
.RE
|
|
.PP
|
|
Disable the proxy:
|
|
.PP
|
|
.RS 4
|
|
.B prx off
|
|
.RE
|
|
.SH "SEE ALSO"
|
|
.BR prx-helper (1),
|
|
.BR nft (8),
|
|
.BR ip-rule (8),
|
|
.BR ip-route (8),
|
|
.BR pkexec (1),
|
|
.BR sudo (8),
|
|
.BR systemctl (1)
|
|
.SH AUTHOR
|
|
Amir Husayn Panahifar <ahp@panahifar.ir>.
|