FAQ & Troubleshooting

Frequently asked questions and common troubleshooting scenarios for Wiretastix.

This page contains frequently asked questions and solutions to common issues you may encounter when installing, configuring, or operating Wiretastix.

General Questions

What is Wiretastix?

Wiretastix is a WireGuard VPN management system that integrates with OpenID Connect (OIDC) identity providers. It enables user self-service VPN provisioning, dynamic group-based access control, and automated user lifecycle management.

What are the system requirements?

Minimum requirements:

• Linux kernel 5.6+ (for native WireGuard support) or WireGuard kernel module
• 2 CPU cores
• 2 GB RAM
• 10 GB disk space
• Network access to your OIDC Identity Provider

Recommended for production:

• 4+ CPU cores
• 4+ GB RAM
• 50+ GB disk space (depends on number of users)
• Backup storage for database

Which database should I use: SQLite or PostgreSQL?

Use SQLite if:

• You have fewer than 100 concurrent users
• You want simplicity
• You’re running a single-instance deployment
• You’re in a development/testing environment

Use PostgreSQL if:

• You have 100+ concurrent users
• You need high availability
• You want advanced backup/replication features
• You’re running in production with strict uptime requirements

Which OIDC provider should I use?

The best OIDC provider depends on your organization:

• Authentik: Best for self-hosted, modern deployments with full group support
• Keycloak: Best for enterprise with existing infrastructure and federation needs
• Okta: Best commercial SaaS solution with extensive features
• Azure AD: Best for Microsoft-centric organizations
• Google: Simple for consumer accounts, limited group support
• LinkedIn: Niche use cases, limited group support

See the OIDC provider comparison for details.

Can I use Wiretastix without OIDC?

While Wiretastix is designed for OIDC integration, you can create static peers via the API/CLI without OIDC authentication. However, the web UI self-service portal requires OIDC to be configured.

How many users can Wiretastix support?

With proper hardware:

• SQLite: Up to ~100 concurrent users
• PostgreSQL: Thousands of concurrent users (tested with 5,000+)

Actual limits depend on traffic patterns, peer configurations, and hardware resources.

What ports does Wiretastix use?

• 51820/UDP: WireGuard VPN traffic (configurable)
• 8085/TCP: Web UI (configurable)
• 8095/TCP: API server (configurable)
• 9100/TCP: Prometheus metrics (configurable)
• 5353/UDP: DNS resolver (optional, configurable)

Installation & Setup Issues

WireGuard Interface Not Created

Symptoms: Wiretastix fails to start, logs show “cannot create WireGuard interface” errors.

Causes:

• WireGuard kernel module not loaded
• Interface name already in use
• Insufficient permissions

Solutions:

1. Check if WireGuard module is loaded:

   lsmod | grep wireguard
   

2. Load the module if missing:

   sudo modprobe wireguard
   

3. Verify kernel support:

   uname -r  # Should be 5.6+ for native support
   

4. Check if interface exists:

   ip link show wg0
   # If it exists, delete it first
   sudo ip link delete wg0
   

5. For Debian/Ubuntu, configure network interfaces:

   sudo nano /etc/network/interfaces
   # Add:
   auto wg0
   iface wg0 inet manual
       pre-up ip link add $IFACE type wireguard
       post-down ip link del $IFACE
   
   sudo ifup wg0
   

Permission Denied Errors

Symptoms: “Permission denied” when accessing files, creating interfaces, or managing nftables.

Solutions:

1. Fix configuration file permissions:

   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  # If using file-based key
   

2. Ensure daemon runs as root (required for network operations):

   sudo systemctl status wiretastix
   # Check User= line, should be root
   

3. For Docker, ensure capabilities:

   cap_add:
     - NET_ADMIN
     - SYS_MODULE
   

Port Already in Use

Symptoms: Daemon fails to start with “address already in use” error.

Solutions:

1. Check what’s using the port:

   sudo netstat -tulpn | grep -E ':(51820|8085|8095)'
   # Or with ss:
   sudo ss -tulpn | grep -E ':(51820|8085|8095)'
   

2. Stop conflicting service:

   # Example for port 8085
   sudo systemctl stop <service-name>
   

3. Change Wiretastix ports: Edit /etc/wiretastix/wiretastix.yaml:

   wireguard:
       port: 51821  # Change from 51820
   webserver:
       binding: :8086  # Change from :8085
   apiserver:
       binding: 127.0.0.1:8096  # Change from :8095
   

Database Connection Failed

Symptoms: Daemon starts but can’t connect to database, logs show connection errors.

For PostgreSQL:

1. Verify PostgreSQL is running:

   sudo systemctl status postgresql
   # Or for Docker:
   docker compose ps postgres
   

2. Test connection manually:

   psql -h localhost -U wiretastix -d wiretastix
   

3. Check DSN in configuration:

   db:
       type: postgres
       dsn: postgresql://wiretastix:password@localhost:5432/wiretastix?sslmode=disable
   

   Ensure: correct password, host, port, database name

4. Check PostgreSQL allows connections:

   # Edit pg_hba.conf
   sudo nano /etc/postgresql/*/main/pg_hba.conf
   # Add line:
   host    wiretastix    wiretastix    127.0.0.1/32    md5
   
   sudo systemctl restart postgresql
   

For SQLite:

1. Check directory permissions:

   ls -ld /var/lib/wiretastix
   sudo chown -R wiretastix:wiretastix /var/lib/wiretastix
   

2. Verify DSN path:

   db:
       type: sqlite
       dsn: file:/var/lib/wiretastix/wiretastix.db?_journal=WAL&_fk=1
   

3. Create directory if missing:

   sudo mkdir -p /var/lib/wiretastix
   sudo chown wiretastix:wiretastix /var/lib/wiretastix
   

API Token Lost or Invalid

Symptoms: CLI returns “unauthorized” or “invalid token” errors.

Solutions:

1. Regenerate API token:

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

   Warning: This invalidates all existing tokens.

2. Set environment variable:

   export WIRETASTIX_TOKEN="your-new-token-here"
   

3. Verify token in environment file:

   sudo nano /etc/default/wiretastix
   # Ensure WIRETASTIX_TOKEN is set correctly
   

Service Fails to Start

Symptoms: systemd service fails immediately after start.

Solutions:

1. Check service status:

   sudo systemctl status wiretastix
   

2. View detailed logs:

   sudo journalctl -u wiretastix -n 100 --no-pager
   

3. Common causes:

   • Configuration file syntax errors (check YAML indentation)
   • Missing WireGuard interface
   • Database connection issues
   • Port conflicts
   • Invalid private key

4. Test configuration:

   # Try running manually to see errors
   sudo wiretastix-daemon -c /etc/wiretastix/wiretastix.yaml -v
   

5. Validate YAML syntax:

   # Use Python or online YAML validators
   python3 -c "import yaml; yaml.safe_load(open('/etc/wiretastix/wiretastix.yaml'))"
   

Docker-Specific Issues

Container Won’t Start

Symptoms: Docker container exits immediately or won’t start.

Solutions:

1. Check container logs:

   docker compose logs wiretastix
   docker logs wiretastix-daemon
   

2. Verify volume mounts:

   docker compose config
   # Check that paths exist on host
   ls -la config/wiretastix.yaml
   ls -la config/nftables.conf
   

3. Check for syntax errors in docker-compose.yml:

   docker compose config --quiet
   

/dev/net/tun Permission Denied

Symptoms: Docker container can’t access TUN device for WireGuard.

Solutions:

1. Create TUN device on host:

   sudo mkdir -p /dev/net
   sudo mknod /dev/net/tun c 10 200
   sudo chmod 666 /dev/net/tun
   

2. Add device to docker-compose.yml:

   devices:
     - /dev/net/tun:/dev/net/tun
   

3. Or use privileged mode (less secure):

   privileged: true
   

WireGuard Interface Not Accessible in Container

Symptoms: Container can’t create or manage WireGuard interface.

Solutions:

1. Use host network mode:

   network_mode: host
   

2. Or use sidecar pattern (see Docker Compose Installation)

3. Ensure capabilities are added:

   cap_add:
     - NET_ADMIN
     - SYS_MODULE
   

4. Mount /lib/modules:

   volumes:
     - /lib/modules:/lib/modules:ro
   

Database Service Not Ready

Symptoms: Wiretastix starts before PostgreSQL is ready, connection fails.

Solutions:

1. Add health check to PostgreSQL:

   postgres:
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U wiretastix"]
       interval: 10s
       timeout: 5s
       retries: 5
   

2. Use condition in depends_on:

   wiretastix:
     depends_on:
       postgres:
         condition: service_healthy
   

3. Increase retry interval in Wiretastix config if needed

OIDC Authentication Issues

Redirect URI Mismatch

Symptoms: After login, OIDC provider shows “redirect_uri_mismatch” error.

Solutions:

1. Verify redirect URL in Wiretastix config:

   oidc:
       redirect-url: https://vpn.example.com/callback
   

2. Ensure it matches EXACTLY in IdP settings:

   • Same protocol (https)
   • Same domain
   • Same path (/callback)
   • No trailing slash unless configured

3. Check for proxy/load balancer issues: If behind a proxy, ensure it forwards the correct Host header

User Not Authorized / Access Denied

Symptoms: User can log in to IdP but Wiretastix shows “not authorized” or “access denied”.

Causes:

• User not in allowed groups
• User email not in constraints
• Group claims not in token
• Case sensitivity mismatch

Solutions:

1. Check group membership in IdP

2. Verify constraints in config:

   oidc:
       constraints:
           groups:
               - vpn-users  # Must match exact group name
           email:
               - user@example.com
   

3. Enable verbose logging:

   oidc:
       verbose: true
   

   Check logs to see what claims are received:

   sudo journalctl -u wiretastix -f | grep -i oidc
   

4. For Azure AD: Ensure using group Object IDs, not names:

   constraints:
       groups:
           - a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890  # Object ID
   

Tunnel Creation Fails with “not found”

Symptoms: A user signs in successfully, but clicking “Create a new VPN tunnel” shows an error like “Error creating additional device: not found” instead of producing a tunnel.

Cause: The user’s OIDC claims didn’t match any configured group, and the default_group fallback either isn’t set or points at a group that doesn’t exist/isn’t enabled – see Manage Groups. A fresh install seeds default_group to the placeholder string fallback, but doesn’t create a group with that name for you.

Solutions:

1. Create the group default_group actually points at:

   > group create oidc fallback name "Fallback" policy accept
   

2. Or point default_group at a group you’ve already created:

   > config set default_group developers
   

3. Also check default_endpoint – the same generic error appears if it was never changed from its 192.168.0.1:51820 placeholder, since generating any peer’s client config requires a real endpoint. See Configuring Global Defaults.

Groups Not Appearing in Token

Symptoms: User authenticates but has no group memberships in Wiretastix.

Solutions:

1. Verify groups scope is requested:

   oidc:
       scopes:
           - openid
           - email
           - profile
           - groups  # Ensure this is present
   

2. Check IdP configuration:

   • Keycloak: Configure group membership mapper
   • Okta: Add groups claim to token
   • Azure AD: Configure group claims in token configuration
   • Authentik: Ensure property mapping includes groups

3. Test token claims: Use jwt.ms or similar to decode the ID token and verify groups claim exists

Token Refresh Failures

Symptoms: User is logged out frequently, logs show token refresh errors.

Solutions:

1. Ensure offline_access scope:

   oidc:
       scopes:
           - offline_access  # Required for refresh tokens
   

2. Check refresh interval:

   oidc:
       refresh-min-interval-sec: 300  # 5 minutes
   

3. Verify IdP token lifetime settings

4. Disable auto-disable on error (temporary workaround):

   # In Wiretastix config (via API/CLI)
   auto_disable_on_auth_error: 0
   

Invalid Client or Client Secret Errors

Symptoms: OIDC authentication fails with “invalid_client” error.

Solutions:

1. Verify client ID and secret: Double-check both match exactly in IdP and config

2. Regenerate client secret if needed: In IdP, create new secret and update config

3. Check for hidden characters: Copy-paste issues can introduce invisible characters

4. For Azure AD: Ensure secret hasn’t expired: Check expiration date in Azure Portal

Network & Firewall Issues

NFTables Rules Not Applied

Symptoms: Network rules configured but not enforced, traffic not filtered.

Solutions:

1. Verify nftables.conf is loaded:

   sudo nft list tables
   # Should show 'wiretastix' table
   

2. Check Wiretastix can access nftables:

   sudo nft list table wiretastix
   

3. Apply rules manually:

   # Via CLI
   wiretastix-cli
   > rule apply
   
   # Or via API
   curl -X POST -H "Authorization: Bearer ${TOKEN}" \
     https://127.0.0.1:8095/wiretastix/api/v1/rules/apply
   

4. Check daemon has permissions: Daemon needs to run as root or with CAP_NET_ADMIN

5. Verify nftables service is running:

   sudo systemctl status nftables
   

Clients Can’t Connect to VPN

Symptoms: WireGuard clients show as not connected, no handshake.

Solutions:

1. Check WireGuard service is running:

   sudo wg show
   # Should show wg0 interface with peers
   

2. Verify port is open in firewall:

   # For UFW
   sudo ufw allow 51820/udp
   
   # For firewalld
   sudo firewall-cmd --add-port=51820/udp --permanent
   sudo firewall-cmd --reload
   

3. Check NAT/port forwarding: If behind NAT, ensure UDP 51820 is forwarded to Wiretastix server

4. Verify endpoint in client config: Client’s WireGuard config should have correct server IP/hostname:

   [Peer]
   Endpoint = vpn.example.com:51820
   

5. Check peer is active in Wiretastix:

   wiretastix-cli
   > peer status
   

6. Test connectivity:

   # From client, ping VPN gateway
   ping 10.100.200.1  # Use your VPN gateway IP
   

DNS Resolution Not Working for VPN Clients

Symptoms: Clients connected but can’t resolve hostnames.

Solutions:

1. Check DNS configuration in peer settings:

   wiretastix-cli
   > peer list
   # Verify DNS field has valid DNS servers
   

2. Verify DNS resolver is running:

   # If using built-in resolver
   sudo netstat -tulpn | grep :5353
   

3. Test DNS from server:

   dig @10.100.200.1 example.com  # Use your VPN gateway IP
   

4. Configure DNS in Wiretastix:

   resolver:
       binding: 10.100.200.1:53
       domain: vpn.local
   

5. Update default DNS for new peers: Via CLI:

   wiretastix-cli config set default_dns "1.1.1.1,8.8.8.8"
   

Can’t Access Web UI

Symptoms: Browser can’t reach web interface at configured URL.

Solutions:

1. Verify service is listening:

   sudo netstat -tulpn | grep :8085
   

2. Check firewall:

   sudo ufw allow 8085/tcp
   

3. Test from localhost first:

   curl -k https://127.0.0.1:8085
   

4. Check binding address in config:

   webserver:
       binding: :8085  # Listen on all interfaces
       # or
       binding: 0.0.0.0:8085  # Explicit all interfaces
   

5. For Docker, verify port mapping:

   docker compose port wiretastix 8085
   

6. Check TLS certificate issues: Browser may block self-signed certs - try with -k flag or accept exception

Performance & Scaling Issues

High CPU Usage

Symptoms: CPU usage is consistently high, server slow.

Causes:

• Too many concurrent connections
• Frequent token refreshes
• Large number of nftables rules
• Database queries not optimized

Solutions:

1. Check active peers:

   wiretastix-cli
   > peer status
   # Reduce if too many
   

2. Increase token refresh interval:

   oidc:
       refresh-min-interval-sec: 600  # 10 minutes instead of 5
   

3. Optimize database: For PostgreSQL:

   VACUUM ANALYZE;
   REINDEX DATABASE wiretastix;
   

4. Add more CPU resources

5. Monitor with Prometheus metrics

High Memory Usage

Symptoms: Memory consumption grows over time or is very high.

Solutions:

1. Check for memory leaks in logs

2. Restart service periodically (temporary workaround):

   # Add to cron
   0 3 * * 0 systemctl restart wiretastix
   

3. For Docker, set memory limits:

   deploy:
     resources:
       limits:
         memory: 1G
   

4. Monitor memory with Prometheus

5. Upgrade server resources

Slow API Responses

Symptoms: CLI commands take a long time, API timeouts.

Solutions:

1. Check database performance:

   # For PostgreSQL
   psql -U wiretastix -d wiretastix -c "SELECT * FROM pg_stat_activity;"
   

2. Add database indexes (if missing)

3. Optimize database queries

4. Increase database connection pool

5. Use PostgreSQL instead of SQLite for large deployments

6. Add caching layer (Redis) if needed

Maintenance & Operations

How do I backup Wiretastix?

For SQLite:

# Stop service
sudo systemctl stop wiretastix

# Backup database
sudo cp /var/lib/wiretastix/wiretastix.db /backup/wiretastix-$(date +%Y%m%d).db

# Backup configuration
sudo cp -r /etc/wiretastix /backup/wiretastix-config-$(date +%Y%m%d)

# Restart service
sudo systemctl start wiretastix

For PostgreSQL:

sudo -u postgres pg_dump wiretastix > wiretastix-$(date +%Y%m%d).sql

# Backup configuration
sudo cp -r /etc/wiretastix /backup/wiretastix-config-$(date +%Y%m%d)

For Docker:

docker compose exec postgres pg_dump -U wiretastix wiretastix > backup.sql
cp -r config/ backup-config/

How do I restore from backup?

For SQLite:

sudo systemctl stop wiretastix
sudo cp /backup/wiretastix-20250101.db /var/lib/wiretastix/wiretastix.db
sudo systemctl start wiretastix

For PostgreSQL:

sudo systemctl stop wiretastix
sudo -u postgres psql wiretastix < wiretastix-20250101.sql
sudo systemctl start wiretastix

How do I upgrade Wiretastix?

See specific installation guide for your method:

• Debian Package Upgrade
• Docker Compose Upgrade
• From Source - rebuild and reinstall

How do I migrate from SQLite to PostgreSQL?

1. Backup current SQLite database
2. Install and configure PostgreSQL
3. Export data from SQLite:

   sqlite3 /var/lib/wiretastix/wiretastix.db .dump > dump.sql
   

4. Convert and import to PostgreSQL (manual process, schema may need adjustment)
5. Update wiretastix.yaml to use PostgreSQL DSN
6. Restart service

Note: This is a manual process. Test thoroughly in development first.

How do I check which version I’m running?

wiretastix-daemon -V
wiretastix-cli -V

# Or check service
systemctl status wiretastix

# For Docker
docker compose exec wiretastix wiretastix-daemon -V

Security Questions

Is it safe to expose the Web UI to the internet?

Yes, with proper configuration:

• Use HTTPS with valid TLS certificates (Let’s Encrypt recommended)
• Configure OIDC authentication properly
• Use strong cookie secrets
• Keep Wiretastix updated
• Use firewall/rate limiting
• Monitor access logs

Should the API server be exposed to the internet?

No, unless necessary. The API server should:

• Bind to 127.0.0.1 (localhost only) by default
• Only be exposed if needed for remote CLI access
• Use HTTPS if exposed
• Require strong API tokens
• Use firewall rules to restrict access

How do I rotate API tokens?

Use the CLI’s own token commands, not wiretastix-daemon --initialize – that flag only bootstraps the very first token on a fresh system and explicitly refuses to run once any token already exists (“you can’t initialize an initialized system”). --initialize --wipe would work, but it deletes every existing token and leaves you with exactly one new one – there’s no graceful overlap while you update clients.

wiretastix-cli
# Create an additional token without touching existing ones
> token create rotated-token "replacement for old-token-name"

Copy the printed token value now – it’s shown once and can’t be retrieved again. Update your clients with it, confirm everything still works, then remove the old one:

> token list
> token delete old-token-name

How secure is the WireGuard private key storage?

The WireGuard private key should be:

• Stored in /etc/wiretastix/wiretastix.yaml or separate file
• File permissions: 600 (read/write for root only)
• Never committed to version control
• Backed up securely
• Rotated if compromised

Getting More Help

If your issue isn’t covered here:

1. Check the logs:

   sudo journalctl -u wiretastix -n 100
   

2. Enable verbose logging:

   oidc:
       verbose: true
   

   Then restart and check logs

3. Search GitHub issues: Wiretastix Issues

4. Review documentation:

   • Configuration Reference
   • API Endpoints
   • CLI Commands

5. Community support:

   • GitHub Discussions
   • Project documentation
   • Related forums

6. File a bug report: Include:

   • Wiretastix version
   • Installation method
   • Operating system
   • Configuration (sanitized)
   • Relevant log excerpts
   • Steps to reproduce