Server Setup

The paqet server receives encrypted raw TCP packets from clients and forwards traffic to destination servers. It must be deployed on a machine with a public IP address.

Find Your Network Details

Before configuring the server, you need to gather network information for your server machine.

Linux
macOS
Windows

Find Interface and Local IP:

ip a

Look for your primary network interface (e.g., eth0, ens3). The IP address is listed under inet.Find Gateway MAC Address:

# First, find your gateway's IP
ip r | grep default

# Then, find its MAC address (replace with your gateway IP)
arp -n 192.168.1.1

Find Interface and Local IP:

ifconfig

Look for your primary interface (e.g., en0). The IP is listed under inet.Find Gateway MAC Address:

# First, find your gateway's IP
netstat -rn | grep default

# Then, find its MAC address (replace with your gateway IP)
arp -n 192.168.1.1

Find Interface and Local IP:

ipconfig /all

Note your active network adapter’s IP Address and Gateway IP Address.Find Interface GUID:Windows requires the Npcap device GUID. Run in PowerShell:

Get-NetAdapter | Select-Object Name, InterfaceGuid

Note the Name and InterfaceGuid of your active network interface. Format the GUID as:

\Device\NPF_{YOUR-GUID-HERE}

Find Gateway MAC Address:

arp -a 192.168.1.1

Replace with your gateway IP address.

Create Server Configuration File

Create a file named config.yaml in the same directory as your paqet binary:

config.yaml

# Role must be explicitly set
role: "server"

# Logging configuration
log:
  level: "info" # none, debug, info, warn, error, fatal

# Server listen configuration
listen:
  addr: ":9999" # CHANGE ME: Server listen port (must match network.ipv4.addr port)
                 # WARNING: Do not use standard ports (80, 443, etc.)

# Network interface settings
network:
  interface: "eth0" # CHANGE ME: Network interface (eth0, ens3, en0, etc.)
  ipv4:
    addr: "10.0.0.100:9999" # CHANGE ME: Server IPv4 and port (port must match listen.addr)
    router_mac: "aa:bb:cc:dd:ee:ff" # CHANGE ME: Gateway/router MAC address

# Transport protocol configuration
transport:
  protocol: "kcp" # Transport protocol (currently only "kcp" supported)
  kcp:
    block: "aes" # Encryption algorithm
    key: "your-secret-key-here" # CHANGE ME: Secret key (must match client)

Do not use standard ports like 80 or 443 for listen.addr. The iptables rules required by paqet can affect outgoing connections on these ports. Use non-standard ports like 9999 or 8888 instead.

See the complete server configuration reference for all available options.

Configure Listen Address

Set the port your server will listen on:

listen:
  addr: ":9999" # Listen on all interfaces, port 9999

You can also bind to a specific IP:

listen:
  addr: "10.0.0.100:9999" # Listen only on this IP

The port in listen.addr must match the port in network.ipv4.addr.

Configure Network Interface

Update the network section with your server’s network details from Step 1:

network:
  interface: "eth0" # Your server's network interface
  ipv4:
    addr: "10.0.0.100:9999" # Your server's IP and port
    router_mac: "aa:bb:cc:dd:ee:ff" # Your gateway MAC address

The port in network.ipv4.addr must match the port in listen.addr.

Set Encryption Key

Configure the encryption key that matches your client:

transport:
  kcp:
    block: "aes"
    key: "your-secret-key-here" # Must match client exactly

Generate a secure key using:

./paqet secret

Share this key securely with your client configuration.

Configure Firewall Rules

Critical: You must configure iptables to prevent kernel interference.

# Replace 9999 with your actual port
PORT=9999

# Bypass connection tracking
sudo iptables -t raw -A PREROUTING -p tcp --dport $PORT -j NOTRACK
sudo iptables -t raw -A OUTPUT -p tcp --sport $PORT -j NOTRACK

# Prevent kernel from sending RST packets
sudo iptables -t mangle -A OUTPUT -p tcp --sport $PORT --tcp-flags RST RST -j DROP

See the Firewall Configuration guide for detailed instructions.

Without these iptables rules, the server will not function properly. The kernel will interfere with raw packet handling.

Configure Cloud Provider Security Group

If running on a cloud provider (AWS, GCP, Azure, etc.), ensure your security group allows TCP traffic on your listen port:

Protocol: TCP
Port: Your listen port (e.g., 9999)
Source: Your client’s IP or 0.0.0.0/0 for any source

Run the Server

Make the binary executable and run with root privileges:

Linux
macOS
Windows

# Make executable
chmod +x ./paqet_linux_amd64

# Run the server
sudo ./paqet_linux_amd64 run -c config.yaml

# Make executable
chmod +x ./paqet_darwin_arm64

# Run the server
sudo ./paqet_darwin_arm64 run -c config.yaml

# Run as Administrator in PowerShell
.\paqet_windows_amd64.exe run -c config.yaml

Root/Administrator privileges are required to use raw sockets.

Example Configuration

Here’s a complete working example for a Linux server:

role: "server"

log:
  level: "info"

listen:
  addr: ":9999"

network:
  interface: "eth0"
  ipv4:
    addr: "203.0.113.50:9999"
    router_mac: "a0:b1:c2:d3:e4:f5"

transport:
  protocol: "kcp"
  kcp:
    block: "aes"
    key: "my-secret-encryption-key"

Running as a Service

For production deployments, consider running paqet as a systemd service:

/etc/systemd/system/paqet.service

[Unit]
Description=paqet Server
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/paqet
ExecStart=/opt/paqet/paqet run -c /opt/paqet/config.yaml
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl enable paqet
sudo systemctl start paqet
sudo systemctl status paqet

Setup

Usage

Server Setup

Example Configuration

Running as a Service

Next Steps

Build docs developers (and LLMs) love

Setup

Usage

​Example Configuration

​Running as a Service

​Next Steps

Build docs developers (and LLMs) love

Example Configuration

Running as a Service

Next Steps