Pathfabric Linux installer manual
PATHFABRIC-INSTALL(8)
Name
pathfabric-install.sh — install, switch the outbound routing mode of, or remove one service-specific Pathfabric IPv4 tunnel.
Synopsis
sudo ./pathfabric-install.sh --install [--default-gateway=tunnel|default]
[--wireguard-private-key-file=/path/to/private.key] [--unattended]
sudo ./pathfabric-install.sh --switch-gateway
[--default-gateway=tunnel|default] [--unattended]
sudo ./pathfabric-install.sh --uninstall [--unattended]
./pathfabric-install.sh --help
Description
Each downloaded installer belongs to one Pathfabric service and contains that service's tunnel protocol, hub endpoint, private transport /31, and assigned public IPv4 /32. It creates routed IPv4 Layer 3 networking only. It does not create a bridge, provide customer Ethernet, configure NAT, or install customer firewall rules.
The installer preserves the provider's main default route for the tunnel underlay, provider-sourced traffic, and emergency access. Pathfabric traffic uses a separate policy-routing table. Exactly one installer-managed Pathfabric service is supported on a server.
The install payload and the operation that switches ordinary traffic to Pathfabric are service-specific. The script does not contain its installer download token. When Pathfabric generated the WireGuard key and still holds it, the downloaded installer contains that private key and uses it automatically. Treat that installer as a secret. If the customer supplied the public key or previously retrieved the generated configuration, the installer contains no private key and asks for a protected key file.
The saved script does not expire. Keep it for future changes. If it is unavailable, any current Pathfabric installer can switch an existing recorded installation back to the provider default or uninstall it. Switching ordinary outbound traffic to Pathfabric still requires the installer for the recorded service.
Download
Open the service's Configuration page in the customer portal and generate an installer link. The link is single-use, expires after 24 hours, and is consumed by the first successful browser, wget, or curl download. Generating another link revokes the previous unused link.
Choose one download method. Do not run both commands with the same link.
wget
umask 077 INSTALLER_URL='paste the complete installer URL here' wget -O pathfabric-install.sh "$INSTALLER_URL"
curl
umask 077 INSTALLER_URL='paste the complete installer URL here' curl -fL -o pathfabric-install.sh "$INSTALLER_URL"
Inspect the complete file before running it:
chmod 700 pathfabric-install.sh less pathfabric-install.sh sudo ./pathfabric-install.sh --help
Do not use curl | bash or wget -O- | bash. Saving the file is required if it will later be used to switch the gateway or uninstall Pathfabric. If an installer containing a generated WireGuard key is lost, regenerate the service's WireGuard key before downloading another installer.
Requirements
- A supported x86_64 server or VM with root access and systemd.
- One provider IPv4 address and working provider routing. Keep provider console or recovery access available during network changes.
- No existing Pathfabric installer state, reserved Pathfabric interfaces, NetworkManager profiles, policy rules, or routes when using
--install. - Routing table
4242and policy-rule priorities29000,29010,29020,29030, and29040must be unused. - Exactly one installer action may run at a time.
| Operating system | Supported releases | Networking backend |
|---|---|---|
| AlmaLinux | 8, 9, 10 | Active NetworkManager required |
| Rocky Linux | 8, 9, 10 | Active NetworkManager required |
| Ubuntu Server | 22.04, 24.04, 26.04 | Active NetworkManager when present; otherwise Pathfabric systemd backend |
| Debian | 11, 12, 13 | Active NetworkManager when present; otherwise Pathfabric systemd backend |
Containers, desktop distributions, non-x86_64 systems, Windows, macOS, Ubuntu 20.04, CentOS, CentOS Stream, and unlisted Enterprise Linux derivatives are not supported. Concurrent active NetworkManager and systemd-networkd services are not supported.
Actions
--install
Validates the server, detects its provider interface, gateway, source IPv4, and persistence backend, selects a routing mode, and prints the complete change plan. Interactive installation changes nothing until Apply? is confirmed.
Installation creates the tunnel, private transport address, public /32, direct provider route to the Pathfabric hub, persistent policy rules, and loose IPv4 reverse-path filtering required by the routed tunnel. It then validates the provider and Pathfabric routes plus real outbound connectivity from the assigned public IPv4.
A second --install is rejected while any Pathfabric installation is recorded. Use --switch-gateway or --uninstall instead.
--switch-gateway
Changes only the persistent policy selecting ordinary outbound IPv4. It does not rebuild the tunnel, rotate WireGuard keys, or change the tunnel or public addresses. Both directions require valid root-owned Pathfabric installer state.
Switching to default may be run with any current Pathfabric installer. It uses the recorded installation rather than the script's embedded service configuration and validates that ordinary outbound connectivity uses the provider. Switching to tunnel requires the installer for the recorded service and tunnel type and validates Pathfabric connectivity.
The requested plan is displayed and protected by a two-minute rollback. Requesting the already-active mode exits successfully without making changes.
--uninstall
Makes the provider the ordinary default, then removes only Pathfabric-created interfaces, profiles, routes, policy rules, reverse-path-filter settings, managed WireGuard key material, persistence units, and installer state. Recorded provider settings are restored and verified before tunnel removal.
Any current Pathfabric installer may uninstall a valid recorded installation; the script's embedded service configuration is not used. Packages installed for WireGuard are left installed. --default-gateway and --wireguard-private-key-file cannot be used with this action.
--help or no arguments
Displays concise built-in usage and exits without inspecting or changing networking.
Options
| Option | Meaning |
|---|---|
--install | Install this service-specific Pathfabric tunnel. |
--switch-gateway | Switch between Pathfabric and provider ordinary outbound routing. |
--uninstall | Remove the recorded Pathfabric installation. |
--default-gateway=tunnel | Use Pathfabric for ordinary outbound IPv4. |
--default-gateway=default | Keep the provider as the ordinary default. |
--wireguard-private-key-file=PATH | Override an included generated key, or provide the protected private key when the installer does not contain one. The key must match the WireGuard public key configured for this service. Valid only with WireGuard --install. |
--unattended | Skip interactive prompts. Installation and gateway switching then require an explicit --default-gateway. WireGuard installation requires an explicit private-key path only when the installer does not contain a generated key. |
--help | Display built-in help and exit. |
Unknown options, multiple actions, missing required values, and incompatible option combinations fail before a network change.
Routing modes
| Mode | Ordinary outbound IPv4 | Pathfabric-bound traffic | Provider and hub traffic |
|---|---|---|---|
tunnel | Uses Pathfabric and prefers the assigned public /32 as its source. | Uses Pathfabric. | Provider-sourced traffic and outer tunnel traffic continue through the provider. |
default | Uses the provider. | An application can use Pathfabric outbound by binding to the assigned public /32. | Continues through the provider. |
Inbound traffic to the assigned Pathfabric IPv4 uses the tunnel in both modes. Switching modes does not interrupt the Pathfabric address assignment on the service.
Tunnel protocols
The installer persistently sets every GRE, IPIP, and WireGuard tunnel interface to MTU 1240. This keeps IPv4 outer packets at or below 1,264 bytes for GRE, 1,260 bytes for IPIP, and 1,300 bytes for WireGuard, avoiding dependence on path-MTU ICMP feedback on reduced-MTU provider paths.
GRE
Requires a stable public provider IPv4 and permission for IP protocol 47. GRE is unencrypted and is generally unsuitable behind NAT.
IPIP
Requires a stable public provider IPv4 and permission for IP protocol 4. IPIP carries IPv4 unicast, is unencrypted, and is generally unsuitable behind NAT.
WireGuard
Works with authenticated keys and is generally the easiest choice behind NAT. A still-available Pathfabric-generated private key is included directly in the downloaded installer and used automatically. Store that script as a root-only secret.
If the public key was supplied by the customer or the generated configuration was already retrieved, place the matching private key in a root-protected file:
chmod 600 /root/pathfabric.key sudo ./pathfabric-install.sh --install \ --wireguard-private-key-file=/root/pathfabric.key
The file must contain one standard base64 X25519 private key, must not be readable by group or other users, and must derive to the public key configured for the service. When no key is included, interactive installation prompts for the file and unattended installation requires the option. An explicitly supplied file overrides an included generated key.
If WireGuard tools are absent, the installer uses the system package manager to install them. AlmaLinux 8 and Rocky Linux 8 also install EPEL and ELRepo support and perform the required package update. WireGuard packages are not removed by --uninstall.
Safety and validation
- The script must run as root and holds a local lock so two installer actions cannot run concurrently.
- Interactive actions display the exact plan and require
Apply?. Any response other than an explicit yes exits without changes. - Installation fails rather than taking ownership of conflicting interfaces, profiles, table 4242, rule priorities, or existing installer state.
- A direct route keeps the hub endpoint and outer tunnel packets on the original provider interface and source IPv4.
- A two-minute automatic rollback is armed through systemd before installation or gateway switching changes networking.
- If the action fails while rollback is armed, the script immediately attempts restoration. The timer remains protection if the process or SSH connection is lost.
- After applying, the script validates routes, policy rules, provider access, the public source IPv4 observed by Pathfabric, and byte-for-byte 128-byte and 4,096-byte echo transfers.
- The rollback is cancelled only after validation succeeds.
If automatic restoration is incomplete, the script prints a CRITICAL message and preserves the root-only recovery script path for inspection and retry.
Files and reserved networking
| Path or name | Purpose |
|---|---|
/etc/pathfabric/customer-installation.conf | Root-owned mode-0600 installation state used by switching, reboot recovery, and uninstall. |
/etc/sysctl.d/99-zz-pathfabric-customer.conf | Pathfabric IPv4 reverse-path-filter settings. |
/etc/wireguard/pathfabric-private.key | Root-owned managed WireGuard key on the Pathfabric systemd backend. |
/usr/local/sbin/pathfabric-customer-network | Persistent network reconciliation helper on the Pathfabric systemd backend. |
pathfabric-customer-network.service and .timer | Boot restoration and periodic repair on the Pathfabric systemd backend. |
pathfabric-tunnel and pathfabric-public | Reserved NetworkManager connection names. |
pf-gre, pf-ipip, or pf-wg | Protocol-specific tunnel interface. |
pf-public | Interface carrying the assigned public IPv4 /32. |
Routing table 4242 | Pathfabric tunnel routes. |
Rules 29000–29040 | Hub, provider-source, Pathfabric-source, connected-route, and tunnel-default policy selection. |
Do not edit the installer state or Pathfabric-managed profiles, units, routes, rules, interfaces, or key file by hand. The installer validates recorded ownership and fails rather than guessing when state is incomplete or inconsistent.
Examples
Interactive installation
sudo ./pathfabric-install.sh --install
Unattended GRE or IPIP installation using Pathfabric as the ordinary default
sudo ./pathfabric-install.sh --install --unattended \ --default-gateway=tunnel
Unattended WireGuard installation with an included generated key
sudo ./pathfabric-install.sh --install --unattended \ --default-gateway=default
Unattended WireGuard installation with a customer-held key
sudo ./pathfabric-install.sh --install --unattended \ --default-gateway=default \ --wireguard-private-key-file=/root/pathfabric.key
Interactively switch ordinary outbound traffic to the provider
sudo ./pathfabric-install.sh --switch-gateway \ --default-gateway=default
Unattended switch to Pathfabric
sudo ./pathfabric-install.sh --switch-gateway --unattended \ --default-gateway=tunnel
Interactive uninstall
sudo ./pathfabric-install.sh --uninstall
Unattended uninstall
sudo ./pathfabric-install.sh --uninstall --unattended
Exit status
Exit status 0 means the requested action succeeded, the requested routing mode was already active, help was displayed, or an interactive plan was declined before changes. A nonzero status means validation or the requested action failed. Read the complete error output before retrying.
Limitations and recovery
- Only one installer-managed Pathfabric tunnel is supported per server.
- The installer manages IPv4 only. It does not provide Pathfabric IPv6.
- It does not modify provider network configuration beyond a recorded direct hub route when one is needed.
- It does not update a running installation after the service tunnel protocol changes. Use any current Pathfabric installer to switch back to the provider or uninstall the recorded installation, then run the current service installer with
--install. - If the original script is lost, any current Pathfabric installer can switch the recorded installation to the provider default or uninstall it. Generate a fresh installer from the same service before switching ordinary outbound traffic back to Pathfabric.
- If a rollback timer is already pending, wait for it to complete before retrying.
- If state is missing, duplicated, has unsafe permissions, or is internally inconsistent, switching and uninstall fail rather than attempting recovery by guesswork.
Manual configuration
The customer portal's Configuration page also displays the current public /32, private transport /31, hub endpoint, and tunnel-specific reference settings. Those steps are intended for experienced network administrators. The installer is recommended because it makes the configuration persistent, preserves provider access, validates real traffic, and provides automatic rollback.