Systemd

Run the p2pstream release binary as a Linux systemd service, or operate an agent installed by the generated Linux installer.

Use This When

Use systemd when you install the release binary directly on a host, or when managing an agent installed from the Install agent modal opened from Agents.

Prerequisites

• Linux with systemd.
• /usr/local/bin/p2pstream installed.
• A persistent server data directory such as /var/lib/p2pstream, or an agent env file generated by the installer.

Steps

1. Create server directories:

   sudo install -d -m 0700 /var/lib/p2pstream
   sudo install -d -m 0755 /etc/p2pstream

2. Create /etc/p2pstream/server.env:

   CONFIG_DIR=/var/lib/p2pstream
   MANAGEMENT_PORT=8081
   MANAGEMENT_PUBLIC_URL=https://proxy.example.com:8081
   ENV=production

3. Create /etc/systemd/system/p2pstream.service:

   [Unit]
   Description=p2pstream reverse proxy
   After=network-online.target
   Wants=network-online.target
   
   [Service]
   EnvironmentFile=/etc/p2pstream/server.env
   ExecStart=/usr/local/bin/p2pstream server
   Restart=always
   RestartSec=5s
   User=root
   
   [Install]
   WantedBy=multi-user.target

4. Enable the server:

   sudo systemctl daemon-reload
   sudo systemctl enable --now p2pstream
   sudo systemctl status p2pstream

Root is required when binding privileged ports such as 80 or 443. If you only use high ports, run as a dedicated user and adjust ownership of /var/lib/p2pstream.

Agent Service

The generated Linux installer writes:

/etc/p2pstream/agent.env
/etc/systemd/system/p2pstream-agent.service

The service runs:

[Service]
EnvironmentFile=/etc/p2pstream/agent.env
ExecStart=/usr/local/bin/p2pstream agent
Restart=always
RestartSec=5s
User=p2pstream
Group=p2pstream
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/p2pstream-agent

Operate it with:

sudo systemctl status p2pstream-agent
sudo systemctl restart p2pstream-agent
sudo journalctl -u p2pstream-agent -f

Use Agents → More → Reinstall / repair for an existing Linux host. This shares the install/enrollment dialog, including the Management URL, TLS, release, and optional local-file fields. When the selected remote server advertises localhost, the saved environment address supplies the default; edit it if hosts use another address.

Reinstall reads the existing host credential through systemd's EnvironmentFile parser, checks that its agent ID matches the selected agent, and runs the verified installer with that token. It does not rotate the token on the server. It refreshes configuration and restarts the agent, and includes managed-update enrollment when authority and a trusted release are available. An active update campaign blocks preparation. Existing destination and capacity settings are preserved unless explicitly replaced.

For an already enrolled host, repair refreshes the rescue updater and agent configuration while preserving the current managed agent slot and rollback state. It does not upgrade the running agent binary. Use Agents → Updates → Plan rollout to upgrade that agent. On staging, the target matches the selected management server's release; update that server first when moving to a newer staging release.

Rotate token is a separate action that immediately revokes the old credential. Its Linux command atomically appends the new effective AGENT_TOKEN assignment to the existing environment file, preserves its ownership, permissions and other settings, and restarts the connection. It does not download or reinstall software. Both existing-host commands verify the agent identity before modifying the host.

The generated Linux command includes the issued tokens, downloads the versioned installer and architecture-specific binary from the selected GitHub release, and checks them against that release's checksums.txt. It runs the verified installer by absolute path with P2PSTREAM_AGENT_BINARY_FILE pointing to the verified local binary. Temporary downloads are cleaned up on success or failure. No separate token prompt or manual path editing is required. Independently verified local files remain optional advanced overrides.

Managed updates require an exact release or prerelease. Other installs can use latest, which the command resolves once before fetching any release assets. Mutable staging aliases remain rejected. Managed prerelease installs pin P2PSTREAM_AGENT_UPDATE_CHANNEL=staging; final releases pin stable. The installer continues to reject piped execution and symlinked installer/binary files. The explicit management-trust repair mode is separate and does not require a binary or version.

The installer also creates /var/lib/p2pstream-agent/management-ca.pem as the service-owned durable trust bundle. Management certificate rotation updates this file atomically. If forced activation strands an otherwise current agent, use the trust-repair command shown under Settings → Management TLS. If the agent version is incompatible or its configuration is damaged, rerun the full generated install command instead.

Uninstall Agent

Use this only for agents installed with the generated Linux systemd installer. Docker Compose agents should be removed with your Compose workflow instead.

The full-purge uninstall removes the agent service, service drop-ins, /etc/p2pstream, /var/lib/p2pstream-agent, /usr/local/bin/p2pstream, and the p2pstream service user and group. Do not run it on a host where those paths or that user are shared with a p2pstream server or another install you want to keep.

Open the agent row's More menu and select Show uninstall command. Copy the generated command and run it on the agent host. It downloads the selected release's source archive, verifies its SHA-256 checksum, and runs the extracted uninstaller with P2PSTREAM_UNINSTALL_CONFIRM=full-purge.

For a preview, add P2PSTREAM_UNINSTALL_DRY_RUN=true immediately after sudo env in the copied command. An independently verified local uninstaller remains supported as an optional override.

Uninstalling the host service does not remove the management record. After the remote host is removed, open the agent row's More menu under Agents and delete or disable the management record.

Verification

Check server or agent status:

sudo systemctl status p2pstream
sudo journalctl -u p2pstream -f
sudo systemctl status p2pstream-agent

Troubleshooting

Symptom	Check
Server cannot bind low ports	Run as root or use capabilities/high ports.
Agent fails after token rotation	Apply the generated token-change command on the existing agent host.
Uninstall refuses to run	Set P2PSTREAM_UNINSTALL_CONFIRM=full-purge; unsafe paths are intentionally rejected.

Next Steps

• Release binary
• CLI reference
• Troubleshooting