Skip to main content

Install PortGuard Server on Linux

PortGuard Server packages are published from the open-source portguard server repository. The release workflow runs on GitHub Actions, builds packages for each supported platform, and publishes the package manifest, checksums, and assets to the latest GitHub Release.

Use the installer on a fresh Debian, Ubuntu, Rocky, CentOS, or compatible RHEL-like server:

curl -fsSL https://portguard.net/install.sh | sudo bash

The installer reads the latest GitHub Release manifest.tsv, detects your OS, downloads the matching package, verifies SHA256, installs runtime dependencies, then creates /etc/fwknop/fwknopd.conf and /etc/fwknop/access.conf. Client import payloads and QR output are generated on demand with fwknopd -Q.

By default, SPA_SERVER is the detected public IPv4 address. If public detection is unavailable, the installer uses the server's local IPv4 address. The hostname is used only as the client profile section name. Pass --server to override the detected address.

Common options:

curl -fsSL https://portguard.net/install.sh | sudo bash -s -- \
  --server vpn.example.com \
  --access tcp/22,tcp/443 \
  --knock-port 62201 \
  --protocol udp \
  --user portguard \
  --timeout 60

Upgrade an existing server​

Use --upgrade to install the latest matching release package while preserving the existing /etc/fwknop configuration and client keys:

curl -fsSL https://portguard.net/install.sh | sudo bash -s -- --upgrade

For older installations that still export the machine hostname as SPA_SERVER, this command updates only PORTGUARD_CLIENT_SERVER to the detected public IPv4 address. Existing access rules and keys are preserved. An explicitly configured server hostname or IP address is not changed.

If you pass configuration options together with --upgrade, the installer treats that as an intentional config reset and regenerates the client import keys.

Supported prebuilt packages​

The download page syncs with the latest GitHub Release assets and links directly to the package files:

  • Debian 12 and 13: amd64 .deb
  • Ubuntu 22.04, 24.04, and 26.04: amd64 .deb
  • Rocky Linux 8 and 9: x86_64 .rpm
  • CentOS 7, 8, and 9: x86_64 .rpm
  • OpenWrt 24.10: x86_64, mips_24kc, and aarch64_cortex-a53 .ipk

The installer always prefers an exact Debian or Ubuntu release package. If a newer release is detected before its native package is published, it can use the newest package for the same distribution that is not newer than the host. The selected compatibility package is reported in the installer log. RPM packages never fall back across Rocky or CentOS major versions.

Open the PortGuard download page or the latest GitHub Release to download packages manually. Use checksums.txt or manifest.tsv to verify the package before installing.

Manual package install​

Debian or Ubuntu:

sudo apt-get update
sudo apt-get install -y ./portguard-server_*.deb

Rocky, CentOS 8/9, or compatible RHEL-like systems:

sudo dnf install -y ./portguard-server-*.rpm

CentOS 7:

sudo yum install -y ./portguard-server-*.rpm

OpenWrt:

scp portguard-server_*.ipk root@router:/tmp/
ssh root@router opkg install /tmp/portguard-server_*.ipk

Source install fallback​

If your platform is not covered by the package manifest, build from source with the same installer:

git clone https://github.com/yangcancai/portguard.git
cd portguard
curl -fsSL https://portguard.net/install.sh -o /tmp/portguard-install.sh
sudo bash /tmp/portguard-install.sh --source-dir "$PWD"

You can also provide a source tarball:

sudo PORTGUARD_SOURCE_URL=https://example.com/portguard-source.tar.gz \
  bash /tmp/portguard-install.sh

Verify after installation​

sudo fwknopd --exit-parse-config \
  -c /etc/fwknop/fwknopd.conf \
  -a /etc/fwknop/access.conf

sudo systemctl status fwknopd
sudo portguard-fwknopd -Q

Import the payload printed by fwknopd -Q into PortGuard Client, or scan the QR output. Make sure your firewall allows the SPA listener port, which defaults to UDP 62201.