Overview

This page documents the Purplerain Headscale client auto-setup script. It installs Tailscale, applies interface optimizations, advertises local subnets to your Headscale server, and installs security tools like Nmap and Suricata.

Where to get the installer

Log in to your PurpleRain Dashboard and navigate to Devices > Add Device to download the secure, authenticated installer package for your organization.

Download, verify, run (recommended)

To protect our intellectual property and ensure the highest security for our customers, PurpleRain distributed agents are pre-compiled and authenticated uniquely for your organization.

# Download the deployment package from the dashboard UI
chmod +x purplerain-agent-linux-amd64
sudo ./purplerain-agent-linux-amd64 install

Checksum verification (SHA256) is provided during the download process.

Non-interactive / automation

For CI or unattended installs (Enterprise), you can use your Headscale preauth key to silently deploy the agent. Contact support for your CI/CD deployment package.

What the installer does (summary)

Installs Tailscale from upstream packages and configures it to use your Headscale login server.
Enables IP forwarding (IPv4/IPv6) for subnet routing.
Applies ethtool UDP-GRO optimizations to all active, non-loopback interfaces and creates a systemd oneshot to reapply them on boot.
Auto-detects local subnets and advertises them to Headscale.
Installs security tools: Nmap, Masscan, Suricata, etc., and configures Suricata to monitor a detected interface.
Prepares the node as an edge Network Intrusion Detection instance.

Troubleshooting

If no local subnets are detected the agent will exit with an error; ensure your interfaces have addresses and try again.
Check journal logs for systemd services: sudo journalctl -u purplerain-agent.service.