DEV Community

Sharon
Sharon

Posted on

SafeLine WAF Installation & Upgrade Troubleshooting Guide

#safeline #waf #docker #cybersecurity

Having trouble installing or upgrading SafeLine WAF? Whether you're running into Docker issues, port conflicts, or upgrade compatibility problems, this guide covers the most common pitfalls — and how to fix them.

Common Installation Errors & Fixes

❌ nginx: [emerg] invalid IPv6 address in resolver

Open /etc/resolv.conf and remove any invalid IPv6 resolver lines. Then restart Tengine:

docker restart safeline-tengine
Enter fullscreen mode Exit fullscreen mode

❌ Cannot connect to the Docker daemon at unix:///var/run/docker.sock

This usually means Docker is not installed. Install it with:

curl -fLsS https://get.docker.com/ | sh
Enter fullscreen mode Exit fullscreen mode

Or follow Docker Engine installation docs.

❌ failed to create network safeline-ce

The network safeline-ce is required for SafeLine to function. If creation fails, restart Docker:

systemctl restart docker
Enter fullscreen mode Exit fullscreen mode

❌ docker compose v2 not found

SafeLine requires Docker Compose v2. Follow Docker Compose install instructions.

❌ safeline-tengine: Address already in use

Port conflict detected. Use:

docker logs -f safeline-tengine
Enter fullscreen mode Exit fullscreen mode

Check which port is occupied, then resolve the conflict manually.

Ports used by SafeLine:

  • 9443: Admin panel (can be customized)
  • 65508: Health check (fixed)
  • 65443: Custom error pages (fixed)

❌ safeline-mgt-api: Operation not permitted

This issue happens with older Docker versions (20.10.9 and below). Upgrade Docker if possible.

Alternatively, if your system supports seccomp (check with:

grep CONFIG_SECCOMP= /boot/config-$(uname -r)), use a custom seccomp profile:

  1. Download seccomp.json into the SafeLine install directory.
  2. Edit compose.yaml, under the management service, add: 
security_opt:
  - seccomp=./seccomp.json
Enter fullscreen mode Exit fullscreen mode
  1. Restart containers: 
docker compose down && docker compose up -d
Enter fullscreen mode Exit fullscreen mode

❌ safeline-pg: Operation not permitted

Again, this points to an outdated Docker version. Upgrade Docker to resolve.

❌ Pool overlaps with other one on this address space

This is a Docker network conflict. Change the SUBNET_PREFIX in /data/safeline/.env to a unique subnet.

❌ “It does not belong to any of this network’s subnets…”

Try a clean reinstall:

  • Uninstall SafeLine as per instructions
  • Re-deploy from scratch

Customizing SafeLine

Change the Management Port (default is 9443)

  1. Check current port usage: 
ss -antp | grep LISTEN
Enter fullscreen mode Exit fullscreen mode
  1. Edit the hidden .env file in your SafeLine directory and set: 
MGT_PORT=your_custom_port
Enter fullscreen mode Exit fullscreen mode
  1. Restart: 
docker compose down && docker compose up -d
Enter fullscreen mode Exit fullscreen mode

Change Installation Path

Modify the SAFELINE_DIR variable in your .env file.

Deploying SafeLine and Business Services on the Same Server?

It’s possible — but not recommended. Shared environments increase CPU/memory contention and reduce performance.

macOS / Windows Support?

The Community Edition currently supports only Linux. Contact us if you need Enterprise Edition for other platforms.

Recommended System Requirements

Choose based on your business traffic (QPS = Queries Per Second):

  • QPS < 100: 2 CPU cores, 4 GB RAM
  • QPS 100–1000: 4 CPU cores, 8 GB RAM
  • QPS > 1000: 8+ CPU cores, 16 GB+ RAM

These are baseline recommendations — please benchmark based on your workload.

Upgrade Issues & How to Avoid Them

⚠️ Compatibility Issues Across Major Versions

When upgrading across multiple major versions, data format changes may prevent the system from starting.

Always backup before a big upgrade.

⚠️ Ran Upgrade in the Wrong Directory?

You must run upgrades from the installation directory (default: /data/safeline). If you ran it from a subfolder, the upgrade may silently fail.

How to Backup & Restore Configurations

Backup

Copy the entire installation directory (/data/safeline).

Restore

Place it back, then run:

docker compose down && docker compose up -d
Enter fullscreen mode Exit fullscreen mode

Post-upgrade Issues

  • API errors or Docker misbehavior? Restart Docker.
  • Old settings not working? Manually reconfigure or reset.

Final Tips

  • Upgrade Docker regularly.
  • Always test changes on a staging server before rolling out.
  • Keep backups of .env, compose.yaml, and seccomp.json handy.

Join the SafeLine Community

Top comments (0)