Troubleshooting

Common issues and solutions for Camouflage desktop app, Community Edition, and Enterprise Edition.

Desktop App (Camouflage Hub)

Daemon Issues

"Daemon not running"

The daemon is a system-level service that manages VPN connections. This error means the daemon didn't install properly or has crashed.

Solutions:

Check if the daemon is installed:

macOS:

ls /Library/LaunchDaemons/com.camouflage.client.plist
ls /usr/local/bin/camouflage-client

Windows:

sc.exe query CamouflageVPN

Reinstall the daemon from the app:
- Open Camouflage Hub
- Click the tray icon (menu bar on macOS, system tray on Windows)
- Select "Reinstall Daemon"
- Enter your admin password when prompted
Check daemon logs:

macOS:
```
cat /var/log/camouflage-client.log
# or
sudo tail -f /var/log/camouflage-client.log
```
Windows: Check Event Viewer → Windows Logs → Application for CamouflageVPN entries

"Update Required"

The daemon version doesn't match the app version. This happens after app updates when the daemon wasn't automatically updated.

Solution:

Click "Reinstall Daemon" in the Camouflage Hub app. This installs the daemon binary that matches your app version.

Daemon won't start after macOS update

macOS updates can sometimes disable LaunchDaemons or reset permissions.

Solution:

Reinstall the daemon from the tray menu: "Reinstall Daemon"

If that doesn't work, manually reload the daemon:

sudo launchctl unload /Library/LaunchDaemons/com.camouflage.client.plist
sudo launchctl load -w /Library/LaunchDaemons/com.camouflage.client.plist

Permission denied installing daemon

The daemon installer requires admin privileges to write to system directories.

macOS:

/Library/LaunchDaemons/ requires root access
/usr/local/bin/ requires root access
You must enter your admin password when prompted

Windows:

Installing Windows Services requires Administrator privileges
Right-click Camouflage and "Run as Administrator" if needed

Connection Issues (Silo)

"Connection failed"

The VPN tunnel couldn't be established with the server.

Check these:

Server address and port are correct:
- Open the connection details in Silo
- Verify the server address matches what you were given
- Default port is 61700/udp for Network 1, 61701/udp for Network 2

Server is reachable:

# Test if the server host is reachable
ping your-server-ip

# Check if UDP port is open (requires nc with UDP support)
nc -u -v your-server-ip 61700

Authentication key is valid:
- Keys can be revoked from the server
- Keys can expire if time-limited
- Generate a new key from the Cloud dashboard or CE server
Firewall isn't blocking UDP:
- Camouflage uses UDP ports 61700 and 61701
- Check local firewall (macOS Firewall, Windows Firewall)
- Check network firewall if on corporate network

"Auth key rejected"

The authentication key was rejected by the server.

Reasons:

Key has been revoked from the server
Key has expired (if time-limited)
Wrong key for this network
Key format is corrupted

Solution:

Generate a new key from the server:
- Cloud Edition: Network dashboard → Add Node → Download new profile
- Community Edition: Control Plane → Add Node → Download new profile
Re-import the .camouflage profile with the new key

Connected but no traffic flows

You're connected to the VPN but can't reach other nodes or services.

Check these:

Routes are configured:
- If "Route All Traffic" is disabled, only the VPN subnet is routed
- Enable "Route All Traffic" if you want all internet through the VPN
- Check the network's routing configuration in the server
ACL rules aren't blocking:
- Check firewall rules on the server
- Verify your node is allowed to communicate with the destination
- Check if the destination node is online
Destination node is connected:
- Verify the other node shows as "Online" in the server dashboard
- Try pinging the destination node's VPN IP

Slow connection

Potential causes:

KEX mode overhead:
- Hybrid (post-quantum + Noise) has more overhead than pure Noise
- Try switching to Noise mode if latency is critical
- Edit network settings in the server to change KEX mode
Network path:
- Check latency to the relay server: ping your-server-ip
- High latency to relay = high latency between peers
- Consider deploying relay servers closer to users
Bandwidth limitations:
- Check if relay server is resource-constrained
- Monitor CPU and network usage on relay server

Can't import .camouflage profile

Common issues:

File format invalid:
- .camouflage files are JSON
- Open in a text editor and verify it's valid JSON
- Check for missing braces, quotes, or commas
File corrupted during transfer:
- Re-download the profile from the server
- Ensure file wasn't modified
Wrong file extension:
- File must end with .camouflage
- Rename if needed: mv profile.txt profile.camouflage

Lens Issues

Lens shows no connections

Lens monitoring is off, or permissions are missing.

Solutions:

Toggle monitoring on:
- Open Lens window
- Click the monitoring toggle in the top bar
- Should turn green and say "Monitoring"
Grant network permissions (macOS):
- System Preferences → Security & Privacy → Privacy tab
- Select "Full Disk Access"
- Add Camouflage.app to the list
- Restart the app
Check if daemon is running:
- Lens requires the daemon for packet capture
- Verify daemon status in Hub

App names show as "Unknown"

Process resolution requires system permissions to map network connections to applications.

macOS:

Grant "Full Disk Access" in System Preferences → Security & Privacy
Restart Camouflage Hub after granting permission

Windows:

Ensure the app is running with Administrator privileges
Some system processes may still show as "Unknown" due to Windows security

High CPU usage

Lens captures and processes every network connection, which can be CPU-intensive with many active connections.

Solutions:

Filter capture scope:
- Use the Rules tab to exclude high-volume apps
- Disable monitoring when not actively analyzing traffic
Reduce connection table size:
- Clear old connections from the Connections tab
- Restart monitoring to reset the capture buffer
Close Lens window when not in use:
- Lens only captures while the window is open and monitoring is on

Mirror Issues

Tunnel not accessible

The Mirror tunnel isn't reachable from the internet.

Check these:

Daemon is running:
- Verify daemon status in Hub
- Restart daemon if needed
Tunnel is active:
- Open Mirror window
- Verify the tunnel shows as "Active" with a public URL
Public URL is correct:
- Copy the URL from Mirror window
- Verify it matches what you're trying to access
- Check if URL is active in Cloud dashboard
Local service is running:
- The service you're exposing must be running locally
- Test local access first: curl http://localhost:8080

"Session expired"

Mirror tunnels have session limits for security.

Solution:

Close the old tunnel in Mirror window
Create a new tunnel
Use the new public URL

Community Edition (Server)

Installation

Container won't start

Check these:

Docker version:

docker --version
# Should be 20.10 or later

Port conflicts:

# Check if ports are already in use
netstat -tulpn | grep -E '9443|61700|61701'
# or
lsof -i :9443
lsof -i :61700
lsof -i :61701

If ports are in use, either:

Stop the conflicting service
Change Camouflage ports: -p 10443:9443 etc.

Check container logs:
```
docker logs camouflage-ce
```

"Permission denied"

The container needs elevated capabilities to create network tunnels.

Required flags:

docker run -d \
  --cap-add=NET_ADMIN \
  --cap-add=NET_RAW \
  --device=/dev/net/tun:/dev/net/tun \
  # ... other flags

What they do:

--cap-add=NET_ADMIN — Network administration (routing, tunneling)
--cap-add=NET_RAW — Raw socket access (packet manipulation)
--device=/dev/net/tun — Access to TUN device for VPN

If you're getting permission errors:

Verify you included all three flags
Check that /dev/net/tun exists:
```
ls -l /dev/net/tun
```
On some systems, load the tun kernel module:
```
sudo modprobe tun
```

Can't access web UI

Check these:

Container is running:

docker ps | grep camouflage-ce

If not running, check logs:

docker logs camouflage-ce

Use HTTPS, not HTTP:
- URL is https://localhost:9443 (note the https)
- Self-signed certificate will show browser warning
- Click "Advanced" and "Proceed anyway"
Try server IP instead of localhost:
```
https://your-server-ip:9443
```

Firewall allows port 9443:

# UFW
sudo ufw allow 9443/tcp

# iptables
sudo iptables -A INPUT -p tcp --dport 9443 -j ACCEPT
sudo iptables-save

Credentials are case-sensitive:

Username: admin
Password: camouflage

If still failing:

Check container logs for initialization errors:
```
docker logs camouflage-ce | grep -i admin
```

Reset admin password by recreating container:

docker stop camouflage-ce
docker rm camouflage-ce
docker volume rm camouflage_data
# Run docker run command again

Network Issues

Nodes can't connect

Server-side checks:

UDP port 61700 is open:

# Check if port is listening
netstat -tulpn | grep 61700

# Test from client machine
nc -u -v your-server-ip 61700

Firewall allows UDP:

# UFW
sudo ufw allow 61700/udp
sudo ufw allow 61701/udp

# iptables
sudo iptables -A INPUT -p udp --dport 61700 -j ACCEPT
sudo iptables -A INPUT -p udp --dport 61701 -j ACCEPT
sudo iptables-save

Cloud provider security groups:
- AWS: EC2 → Security Groups → Inbound rules
- GCP: VPC Network → Firewall rules
- Azure: Network Security Groups → Inbound rules
- Add rules allowing UDP 61700, 61701 from 0.0.0.0/0
Authentication keys are valid:
- Check in Control Plane that the node's auth key hasn't been revoked
- Regenerate key if needed

Client-side checks:

Server address is correct in .camouflage profile
Client firewall allows outbound UDP

Node shows "Pending"

The node has connected but hasn't been approved yet.

Solution:

Log in to Control Plane
Navigate to Nodes
Find the pending node
Click "Approve"

Some configurations require manual approval for security.

Node shows "Offline"

The client disconnected from the server.

Check client-side:

Daemon is running on the client device
Connection is active in Silo
Network connectivity from client to server
Check client logs:
- macOS: /var/log/camouflage-client.log
- Windows: Event Viewer

Check server-side:

Server is running:
```
docker ps | grep camouflage-ce
```
Server logs:
```
docker logs camouflage-ce | tail -50
```

Data & Backup

How to backup

All data is in the Docker volume. Backup the SQLite database:

# Backup database
docker cp camouflage-ce:/data/db.sqlite3 ./camouflage-backup-$(date +%Y%m%d).sqlite3

# Backup entire data directory
docker cp camouflage-ce:/data ./camouflage-data-backup

Automated backup script:

#!/bin/bash
BACKUP_DIR="/backups/camouflage"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR
docker cp camouflage-ce:/data/db.sqlite3 $BACKUP_DIR/db_$DATE.sqlite3

# Keep only last 7 days
find $BACKUP_DIR -name "db_*.sqlite3" -mtime +7 -delete

How to restore

# Stop the container
docker stop camouflage-ce

# Copy backup into volume
docker cp ./backup.sqlite3 camouflage-ce:/data/db.sqlite3

# Restart container
docker start camouflage-ce

# Verify logs
docker logs -f camouflage-ce

Full restore from scratch:

# Remove old container and volume
docker stop camouflage-ce
docker rm camouflage-ce
docker volume rm camouflage_data

# Create new volume
docker volume create camouflage_data

# Start temporary container to restore data
docker run --rm -v camouflage_data:/data -v $(pwd):/backup alpine \
  cp /backup/db.sqlite3 /data/db.sqlite3

# Start Camouflage container normally
docker run -d \
  -p 9443:9443 \
  -p 61700:61700/udp \
  -p 61701:61701/udp \
  --name camouflage-ce \
  --cap-add=NET_ADMIN \
  --cap-add=NET_RAW \
  --device=/dev/net/tun:/dev/net/tun \
  -v camouflage_data:/data \
  camouflagenetworks/camouflage-ce:latest

Enterprise Edition (Server)

Relay Server

Health check failing

The relay server's health endpoint isn't responding.

Check these:

Container is running:
```
docker ps | grep camouflage-relay
```

Health endpoint:

curl http://localhost:8080/health
# Should return: {"status":"healthy"}

Check relay logs:
```
docker logs camouflage-relay
```

Container has network access:

docker exec camouflage-relay ping -c 3 8.8.8.8

Clients can't connect through relay

Server-side checks:

Relay container is running and healthy

UDP port 61700 is reachable:

# From client machine
nc -u -v relay-server-ip 61700

Firewall allows UDP 61700:
```
sudo ufw allow 61700/udp
```
Cloud provider security groups allow UDP 61700

Check relay logs for connection attempts:

docker logs -f camouflage-relay | grep -i connection

Client-side checks:

Server address points to relay server (not control plane)
Client firewall allows outbound UDP
Check client logs for connection errors

High latency through relay

Relay adds latency since all traffic passes through it.

Optimizations:

Deploy relay closer to users:
- Use multiple relay servers in different regions
- Assign users to nearest relay
Check relay server resources:
```
docker stats camouflage-relay
```
- High CPU = relay is overloaded
- High network = bandwidth limit reached
- Scale up server or add more relays
Network path:
- Check latency from client to relay
- Check latency from relay to destination
- Consider direct P2P connections instead of relay

Gateway

Gateway not registering

The gateway node isn't showing up in the Control Plane.

Check these:

Network ID is correct:
- Verify in gateway config file
- Must match the network ID in Control Plane
Auth token is valid:
- Token may be expired or revoked
- Generate new token from Control Plane
Gateway can reach Control Plane:
```
curl https://control-plane-url/health
```

Gateway logs:

docker logs camouflage-gateway
# or
journalctl -u camouflage-gateway

Traffic not routing through gateway

Gateway is online but traffic isn't being routed through it.

Check these:

Gateway mode is correct:
- Gateway mode: All traffic routes through gateway
- Mixed mode: Traffic can go P2P or gateway
- P2P mode: No gateway routing
- Verify in network settings
iptables rules are correct:
```
# On gateway machine
sudo iptables -L -n -v | grep camouflage
```
Should see rules for:
- FORWARD chain allowing VPN subnet
- NAT/MASQUERADE for internet access

IP forwarding is enabled:

cat /proc/sys/net/ipv4/ip_forward
# Should return: 1

# If 0, enable it:
sudo sysctl -w net.ipv4.ip_forward=1
# Make permanent:
echo "net.ipv4.ip_forward=1" | sudo tee -a /etc/sysctl.conf

Gateway has internet access:
```
ping -c 3 8.8.8.8
```

Check gateway logs for routing events:

docker logs camouflage-gateway | grep -i route

General

Logs

Logs are your best friend for troubleshooting. Here's where to find them:

Desktop App Logs

macOS:

# App logs
~/Library/Logs/com.camouflagenetworks.camouflage/

# Daemon logs
/var/log/camouflage-client.log

# View in real-time
tail -f /var/log/camouflage-client.log

Windows:

# App logs
%LOCALAPPDATA%\com.camouflagenetworks.camouflage\logs\

# Daemon logs
# Open Event Viewer (eventvwr.msc)
# Navigate to: Windows Logs → Application
# Filter for source: CamouflageVPN

Community Edition Logs

# View logs
docker logs camouflage-ce

# Follow logs in real-time
docker logs -f camouflage-ce

# Last 100 lines
docker logs --tail 100 camouflage-ce

# Logs since 1 hour ago
docker logs --since 1h camouflage-ce

Relay Server Logs

# View relay logs
docker logs camouflage-relay

# Follow in real-time
docker logs -f camouflage-relay

# Filter for errors
docker logs camouflage-relay 2>&1 | grep -i error

Getting Help

If you're stuck after trying these solutions:

GitHub Issues:
- Search existing issues: https://github.com/camouflage-network/camouflage/issues
- Create a new issue with:
  - Your OS and version
  - Camouflage version (Help → About)
  - Steps to reproduce
  - Relevant logs
Community Support:
- GitHub Discussions: https://github.com/camouflage-network/camouflage/discussions
- Ask questions, share solutions, discuss features
Include in support requests:
- Operating system and version
- Camouflage version
- What you were trying to do
- What happened instead
- Error messages (exact text)
- Relevant log excerpts

Log safety:

Before sharing logs publicly, redact:

IP addresses (if sensitive)
Auth keys
Usernames
Server hostnames (if private)

Desktop App (Camouflage Hub)​

Daemon Issues​

"Daemon not running"​

"Update Required"​

Daemon won't start after macOS update​

Permission denied installing daemon​

Connection Issues (Silo)​

"Connection failed"​

"Auth key rejected"​

Connected but no traffic flows​

Slow connection​

Can't import .camouflage profile​

Lens Issues​

Lens shows no connections​

App names show as "Unknown"​

High CPU usage​

Mirror Issues​

Tunnel not accessible​

"Session expired"​

Community Edition (Server)​

Installation​

Container won't start​

"Permission denied"​

Can't access web UI​

Default login not working​

Network Issues​

Nodes can't connect​

Node shows "Pending"​

Node shows "Offline"​

Data & Backup​

How to backup​

How to restore​

Enterprise Edition (Server)​

Relay Server​

Health check failing​

Clients can't connect through relay​

High latency through relay​

Gateway​

Gateway not registering​

Traffic not routing through gateway​

General​

Logs​

Desktop App Logs​

Community Edition Logs​

Relay Server Logs​

Getting Help​

Desktop App (Camouflage Hub)

Daemon Issues

"Daemon not running"

"Update Required"

Daemon won't start after macOS update

Permission denied installing daemon

Connection Issues (Silo)

"Connection failed"

"Auth key rejected"

Connected but no traffic flows

Slow connection

Can't import .camouflage profile

Lens Issues

Lens shows no connections

App names show as "Unknown"

High CPU usage

Mirror Issues

Tunnel not accessible

"Session expired"

Community Edition (Server)

Installation

Container won't start

"Permission denied"

Can't access web UI

Default login not working

Network Issues

Nodes can't connect

Node shows "Pending"

Node shows "Offline"

Data & Backup

How to backup

How to restore

Enterprise Edition (Server)

Relay Server

Health check failing

Clients can't connect through relay

High latency through relay

Gateway

Gateway not registering

Traffic not routing through gateway

General

Logs

Desktop App Logs

Community Edition Logs

Relay Server Logs

Getting Help