跳至主要内容

Quick installer and fwknopd management

The fastest way to install PortGuard Server is the official installer. It installs packages built by GitHub Actions from the public source repository, so the build pipeline and source code are both open for review.

1. Install​

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

The generated SPA_SERVER uses the server's public IPv4 address when one can be detected. If public detection is unavailable, the installer falls back to the local IPv4 address. The hostname remains the default profile section name. Use --server only when you need to override the detected address with a DNS name or another IP address.

Customize the generated client profile during installation:

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

The installer creates:

  • /etc/fwknop/fwknopd.conf
  • /etc/fwknop/access.conf

2. Upgrade​

Upgrade or reinstall the latest matching release package without changing the existing keys:

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

3. Verify the service​

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

sudo systemctl status fwknopd

If systemd is not active, start it manually:

sudo fwknopd -c /etc/fwknop/fwknopd.conf -a /etc/fwknop/access.conf

4. Import into PortGuard Client​

Show the generated client payload and QR output:

sudo portguard-fwknopd -Q

Open PortGuard Client and import the config, or scan the QR output. The generated profile contains SPA_SERVER, SPA_SERVER_PORT, ACCESS, KEY_BASE64, HMAC_KEY_BASE64, SPOOF_USER, and timeout settings.

5. Change ports, username, or keys​

To change the protected ports, edit /etc/fwknop/access.conf:

sudo vim /etc/fwknop/access.conf

Example:

SOURCE                      ANY
OPEN_PORTS                  tcp/22,tcp/443
KEY_BASE64                  <your-key>
HMAC_KEY_BASE64             <your-hmac-key>
REQUIRE_SOURCE_ADDRESS      Y
REQUIRE_USERNAME            portguard
FW_ACCESS_TIMEOUT           60
MAX_FW_TIMEOUT              60

Generate new keys:

sudo fwknopd --key-gen

After editing, validate and restart:

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

sudo systemctl restart fwknopd

Regenerate the PortGuard Client profile after changing keys:

curl -fsSL https://portguard.net/install.sh | sudo bash -s -- \
  --server vpn.example.com \
  --access tcp/22,tcp/443 \
  --user portguard

6. Telegram access notifications​

Configure a Telegram bot to receive the source IP, requested access, opening time, and expiration time after a successful SPA knock:

sudo portguard-fwknopd --fw-console

Select option 5, or follow the complete Telegram notification guide.

7. Firewall note​

Keep a backup SSH session open before changing firewall policy. The installer generates fwknopd configuration and client import data, but it does not force a destructive firewall reset by default. Make sure UDP 62201 is reachable, then let fwknopd add temporary rules for the protected TCP ports after a valid SPA packet.