Installation using Debian/Ubuntu Package

How to install Wiretastix using pre-built Debian/Ubuntu packages.

Wiretastix provides Debian/Ubuntu packages for streamlined installation on Debian-based systems. This installation method is recommended for production deployments as it includes systemd integration, proper file permissions, and automatic dependency management.

Supported Distributions

The Debian packages are compatible with:

Debian 12 (Bookworm) or newer
Ubuntu 22.04 LTS (Jammy) or newer
Linux Mint 21 or newer
Other Debian-based distributions with compatible package versions

Package Contents

The Wiretastix Debian package installs:

wiretastix-daemon: The main VPN management daemon (/usr/sbin/wiretastix-daemon)
wiretastix-cli: Command-line management tool (/usr/bin/wiretastix-cli)
Configuration file: Default configuration template (/etc/wiretastix/wiretastix.yaml)
Web UI assets: HTML templates and static assets (/usr/lib/wiretastix/)
systemd service: Service unit for automatic startup (/etc/systemd/system/wiretastix.service)
Environment file: Service environment configuration (/etc/default/wiretastix)

Dependencies

The package automatically installs required dependencies:

wireguard-tools: WireGuard utilities (wg, wg-quick)
nftables: Netfilter packet filtering framework
System libraries and runtime dependencies

Optional suggested packages:

ntp or systemd-timesyncd: Time synchronization (recommended for token validation)

Installation from Pre-Built Package

If you have obtained a pre-built .deb package from a release or artifact:

Step 1: Download the Package

Download the appropriate package for your architecture:

# For amd64 (x86_64)
wget https://github.com/wiretastix/wiretastix-vpn/releases/download/v1.0.0/wiretastix_1.0.0_amd64.deb

# For arm64 (aarch64)
wget https://github.com/wiretastix/wiretastix-vpn/releases/download/v1.0.0/wiretastix_1.0.0_arm64.deb

Note: Replace version numbers and URLs with actual release information.

Step 2: Install the Package

Install the package and resolve dependencies:

sudo dpkg -i wiretastix_1.0.0_amd64.deb
sudo apt-get install -f

The -f flag resolves and installs any missing dependencies automatically.

Step 3: Verify Installation

Check that the binaries are installed:

wiretastix-daemon -V
wiretastix-cli -V

You should see version information for both commands.

Building the Debian Package from Source

If you prefer to build the package yourself, you have several options.

Prerequisites for Building

Before building, ensure you have:

Git: To clone the repository
Make: Build automation
Go 1.26+: Go programming language
Build tools: One of the following:
- Native: build-essential, debhelper, devscripts, fakeroot
- Docker: Docker engine with BuildKit support

Option A: Build Natively on Host

This method builds the package directly on your system.

1. Install Build Dependencies

sudo apt-get update
sudo apt-get install -y build-essential debhelper devscripts fakeroot git golang-go

2. Clone the Repository

git clone https://github.com/wiretastix/wiretastix-vpn.git
cd wiretastix-vpn

3. Install Package-Specific Build Dependencies

sudo mk-build-deps -ir -t "apt-get -y --no-install-recommends"

This command reads the debian/control file and installs all required build dependencies.

4. Build the Package

dpkg-buildpackage -us -uc -b

Flags explained:

-us: Do not sign the source package
-uc: Do not sign the changes file
-b: Build binary packages only (no source package)

5. Locate the Built Package

The .deb files will be created in the parent directory:

cd ..
ls -lh wiretastix*.deb wiretastix-cli*.deb

You should see:

wiretastix_<version>_<arch>.deb - Main daemon package
wiretastix-cli_<version>_<arch>.deb - CLI tool package

Option B: Build Using Docker (Recommended for Consistency)

Using Docker ensures a clean, reproducible build environment regardless of your host system.

Method 1: Extract Artifacts Directly (Recommended)

This method uses BuildKit to extract built packages directly to your host:

# Ensure you're in the project root
cd wiretastix-vpn

# Build and extract in one command
DOCKER_BUILDKIT=1 docker build \
  -f contrib/deb-build/Dockerfile \
  --target artifact \
  --output type=local,dest=out \
  .

After completion, your packages will be in the ./out/ directory:

ls -lh out/

You’ll find:

wiretastix_<version>_<arch>.deb
wiretastix-cli_<version>_<arch>.deb
wiretastix_<version>_<arch>.changes
wiretastix_<version>_<arch>.buildinfo

Method 2: Two-Step Docker Build

Alternatively, build in a container and then extract artifacts:

Build the container image:

docker build \
  -f contrib/deb-build/Dockerfile \
  --target build \
  -t wiretastix-deb-builder \
  .

Extract the artifacts:

docker run --rm -v "$PWD/out:/out" wiretastix-deb-builder \
  bash -lc 'shopt -s nullglob; mkdir -p /out; cp -v -t /out /build/*.{deb,changes,buildinfo}'

Verify extraction:
```
ls -lh out/
```

Both options produce .deb files you can install with the steps below.

If you just want to run Wiretastix locally without producing a package at all (for development), see Installation from Source instead.

Installing the Built Package

Once you have the .deb files (either pre-built or self-built):

Install Both Packages

sudo dpkg -i wiretastix_*.deb wiretastix-cli_*.deb
sudo apt-get install -f

Or install them separately:

# Main daemon package (required)
sudo dpkg -i wiretastix_<version>_<arch>.deb
sudo apt-get install -f

# CLI tool (optional but recommended)
sudo dpkg -i wiretastix-cli_<version>_<arch>.deb
sudo apt-get install -f

Verify Installation

Check installed files:

dpkg -L wiretastix
dpkg -L wiretastix-cli

Verify service installation:

systemctl status wiretastix

Post-Installation Configuration

1. Review Default Configuration

The package installs a default configuration file at /etc/wiretastix/wiretastix.yaml. Review and customize it:

sudo nano /etc/wiretastix/wiretastix.yaml

Important configuration items:

Database settings (db.type, db.dsn)
WireGuard interface settings (wireguard.ifname, wireguard.port, wireguard.ipv4)
OIDC provider configuration (must be configured before first start)
API and web server bindings

See the Configuration Reference for detailed explanations.

2. Initialize the WireGuard Interface

Before starting Wiretastix, initialize the WireGuard interface. On Debian/Ubuntu, add to /etc/network/interfaces:

sudo nano /etc/network/interfaces

Add the following (replace wg0 with your interface name from the config):

auto wg0
iface wg0 inet manual
    pre-up ip link add $IFACE type wireguard
    post-down ip link del $IFACE

Bring up the interface:

sudo ifup wg0

Verify the interface exists:

ip link show wg0

3. Generate Private Key for WireGuard

Generate a private key and save a backup copy:

wg genkey | sudo tee /etc/wiretastix/wg-private.key
sudo chmod 600 /etc/wiretastix/wg-private.key

Update /etc/wiretastix/wiretastix.yaml with the key value itself – wireguard.pvtkey must contain the actual key string, not a file path:

wireguard:
  pvtkey: YOUR_GENERATED_PRIVATE_KEY

4. Initialize the API Token

Generate an initial API token for CLI access:

sudo wiretastix-daemon --initialize -c /etc/wiretastix/wiretastix.yaml

Copy the output token immediately - it won’t be displayed again. Store it securely.

If you need to regenerate (this will invalidate the old token):

sudo wiretastix-daemon --initialize --wipe -c /etc/wiretastix/wiretastix.yaml

5. Set Environment Variables for CLI (Optional)

To avoid passing token and API URL every time:

# Add to ~/.bashrc or ~/.profile
export WIRETASTIX_API="https://127.0.0.1:8095/wiretastix/api/v1/"
export WIRETASTIX_TOKEN="your-api-token-here"

Then reload:

source ~/.bashrc

Managing the Wiretastix Service

The package installs a systemd service for automatic daemon management.

Start the Service

sudo systemctl start wiretastix

Check Service Status

sudo systemctl status wiretastix

You should see “active (running)” in green.

Enable at Boot

To start Wiretastix automatically on system boot:

sudo systemctl enable wiretastix

Stop the Service

sudo systemctl stop wiretastix

Restart the Service

After configuration changes:

sudo systemctl restart wiretastix

View Service Logs

Real-time log viewing:

sudo journalctl -u wiretastix -f

View recent logs:

sudo journalctl -u wiretastix -n 100

View logs since boot:

sudo journalctl -u wiretastix -b

Systemd Service Configuration

The service unit is installed at /lib/systemd/system/wiretastix.service.

Service Features

The systemd service includes:

Automatic restart: Restarts on failure after 15 seconds
Security hardening: Restricted filesystem access, namespace isolation
Environment file: Configuration via /etc/default/wiretastix
Dependency management: Starts after network is available

Customizing Service Environment

Edit the environment file:

sudo nano /etc/default/wiretastix

Example contents:

# Optional: Set custom environment variables
WIRETASTIX_TOKEN="your-token-here"
# WIRETASTIX_LOG_LEVEL="debug"

After editing, reload and restart:

sudo systemctl daemon-reload
sudo systemctl restart wiretastix

Service Security

The service runs with several security restrictions:

Private /tmp directory
Protected system directories
Restricted address families
No new privileges
Memory execution protection

These restrictions enhance security but may need adjustment for specific deployments.

Upgrading Wiretastix

To upgrade to a newer version:

1. Download New Package

wget https://github.com/wiretastix/wiretastix-vpn/releases/download/v1.1.0/wiretastix_1.1.0_amd64.deb

2. Install the Upgrade

sudo dpkg -i wiretastix_1.1.0_amd64.deb

The package will automatically:

Stop the running service
Install new binaries
Preserve your configuration file
Restart the service

3. Verify Upgrade

wiretastix-daemon -V
sudo systemctl status wiretastix

Configuration Preservation

Your configuration file (/etc/wiretastix/wiretastix.yaml) is marked as a conffile and will not be overwritten during upgrades. If the package includes a new default configuration, you’ll be prompted to:

Keep your current configuration
Install the package maintainer’s version
View differences

Choose based on your needs. Always back up your configuration before major upgrades.

Uninstalling Wiretastix

To remove Wiretastix:

Remove Package (Keep Configuration)

sudo apt-get remove wiretastix wiretastix-cli

This removes binaries but keeps configuration files in /etc/wiretastix/.

Purge Package (Remove Everything)

sudo apt-get purge wiretastix wiretastix-cli

This removes everything including configuration files.

Clean Up Completely

Remove residual files and dependencies:

sudo apt-get autoremove
sudo rm -rf /var/lib/wiretastix
sudo rm -rf /etc/wiretastix

Troubleshooting

For comprehensive troubleshooting, see the FAQ & Troubleshooting Guide.

Quick Checks

If you encounter issues:

Check service status and logs:

sudo systemctl status wiretastix
sudo journalctl -u wiretastix -n 50

Verify configuration syntax:

python3 -c "import yaml; yaml.safe_load(open('/etc/wiretastix/wiretastix.yaml'))"

Test manual execution:

sudo wiretastix-daemon -c /etc/wiretastix/wiretastix.yaml -v

Common Package-Specific Issues

Service Fails to Start:

Check logs: sudo journalctl -u wiretastix -n 50
Common causes: YAML syntax errors, database connection, missing WireGuard interface
Test config: sudo wiretastix-daemon -c /etc/wiretastix/wiretastix.yaml -v

Permission Denied Errors:

sudo chown -R root:root /etc/wiretastix
sudo chmod 755 /etc/wiretastix
sudo chmod 644 /etc/wiretastix/wiretastix.yaml
sudo chmod 600 /etc/wiretastix/wg-private.key

Package Installation Conflicts:

# Force overwrite if safe
sudo dpkg -i --force-overwrite wiretastix_*.deb
sudo apt-get install -f

Missing Dependencies:

sudo apt-get update
sudo apt-get install -y wireguard-tools nftables
sudo apt-get install -f

Database Migration Issues:

# For SQLite - remove and restart
sudo systemctl stop wiretastix
sudo rm /var/lib/wiretastix/wiretastix.db
sudo systemctl start wiretastix

For additional troubleshooting including OIDC issues, networking problems, and database configuration, see the FAQ & Troubleshooting Guide.

Package Information

View Package Details

apt-cache show wiretastix

List Installed Files

dpkg -L wiretastix

Check Package Version

dpkg -l | grep wiretastix

View Package Dependencies

apt-cache depends wiretastix

Advanced: Building from Git HEAD

To build the latest development version:

git clone https://github.com/wiretastix/wiretastix-vpn.git
cd wiretastix-vpn
git checkout main  # or a specific branch

# Update version in debian/changelog if needed
dch --newversion "1.0.0+git$(date +%Y%m%d)" "Development build"

# Build
dpkg-buildpackage -us -uc -b

Backup Considerations

After installation, set up regular backups of critical data:

Database: /var/lib/wiretastix/wiretastix.db (SQLite) or PostgreSQL database
Configuration: /etc/wiretastix/wiretastix.yaml, /etc/default/wiretastix
NFTables config: /etc/nftables.conf
WireGuard key: Ensure the private key in config is backed up

Quick Backup Command

# Create backup directory
sudo mkdir -p /backup/wiretastix

# Backup everything
sudo tar czf /backup/wiretastix/wiretastix-backup-$(date +%Y%m%d).tar.gz \
  /var/lib/wiretastix/ \
  /etc/wiretastix/ \
  /etc/nftables.conf \
  /etc/default/wiretastix

For comprehensive backup strategies, automated backups, and restore procedures, see the Backup and Recovery Guide.

Security Considerations

After installation:

Firewall Configuration: Wiretastix manages its own nftables base chains and opens the ports it needs (WireGuard, Web UI, API) automatically when the daemon starts – don’t manage these ports with ufw or another firewall frontend alongside it, as the two can conflict. See Network Firewall (NFTables) for how this works and Configure Network Rules to customize it.

Secure Configuration Files: Protect sensitive data:

sudo chmod 600 /etc/wiretastix/wiretastix.yaml
sudo chmod 600 /etc/default/wiretastix

API Token Security: Store API tokens securely, never in version control
Regular Updates: Keep the package updated for security patches
Regular Backups: Follow the backup procedures in Backup and Recovery Guide
Log Monitoring: Regularly review logs for suspicious activity

Next Steps

After successful installation:

Initial Setup - Configure Wiretastix and generate API tokens
Configure OIDC - Set up authentication with your identity provider
Managing Peers - Create your first VPN clients
Configuration Reference - Detailed configuration options