How to Upgrade SafeLine LTS Version to the Latest Version

⚠️ Important Notice on SafeLine LTS

The SafeLine team has decided to discontinue maintenance and updates for the LTS version (The latest LTS version is 9.1.0-LTS) in order to focus engineering resources on the main release branch.

This allows us to deliver new features, security improvements and bug fixes more efficiently and consistently.

When a new version is released, please validate the new version in a testing environment first.

If a direct production upgrade is necessary, we strongly recommend waiting at least 1–2 weeks after release, allowing time for broader community validation and potential hotfix releases.

This guide describes the standard procedure for smoothly upgrading from SafeLine WAF LTS version to the latest version.

1. Back Up Existing Files

Before performing any upgrade operation, ensure that the entire SafeLine installation directory is fully backed up to prevent accidental data loss.

# Assuming the default installation directory is /data/safeline  
cp -a /data/safeline /data/safeline\_bak

2. Update the Compose File

Go to the SafeLine installation directory and pull the latest compose.yaml configuration file.

cd /data/safeline
wget "https://waf-ce.chaitin.cn/release/latest/compose.yaml" --no-check-certificate -O compose.yaml

3. Modify the Configuration File

Edit the .env file in the installation directory and update the RELEASE and IMAGE_TAG parameters as follows:

• RELEASE: Leave this field empty.
• IMAGE_TAG: Set it to the target latest version (for example: 9.3.7).

Example .env file after modification:

SAFELINE_DIR=/data/safeline  
POSTGRES_PASSWORD=xxx  
MGT_PORT=9443  
RELEASE=  
CHANNEL=  
REGION=-g
IMAGE_PREFIX=swr.cn-east-3.myhuaweicloud.com/chaitin-safeline  
IMAGE_TAG=9.3.7  
SUBNET_PREFIX=192.168.0  
ARCH_SUFFIX=  
MGT_PROXY=0

4. Perform the Upgrade

Pull the latest container images and recreate the runtime environment.

docker compose up -d

5. Migrate Website Configurations

Starting from version 9.2.7, SafeLine introduced persistent storage support for website configurations.

If you are upgrading from an LTS release earlier than 9.2.7, some existing website configurations must be migrated manually.

Please execute the official migration script provided by the SafeLine team: https://docs.waf.chaitin.com/en/Reference/Changelog#h-927-28-october-2025

Or for existing applicationss where you need to manually add custom configuration files, you can also refer to the reference script we provide below, which can be executed after the upgrade:

#!/bin/bash

# Directory definitions
CUSTOM_DIR="/data/safeline/resources/nginx/custom_params"
SITES_DIR="/data/safeline/resources/nginx/sites-enabled"

echo "=== Starting configuration optimization script ==="

# Check if directory exists
if [ ! -d "$CUSTOM_DIR" ]; then
    echo "❌ Directory does not exist: $CUSTOM_DIR"
    exit 1
fi

# Step 1: Clean old proxy configs from IF_backend_* files
echo "➡️ Checking and cleaning old proxy configurations in $SITES_DIR/IF_backend_* ..."

# Find matching files
sites_files=$(find "$SITES_DIR" -maxdepth 1 -type f -name "IF_backend_*")

if [ -n "$sites_files" ]; then
    echo "$sites_files" | while read -r f; do
        echo "  - Cleaning file: $f"

        # Remove matching lines if they exist
        sed -i '/proxy_ssl_server_name on;/d' "$f"
        sed -i '/proxy_ssl_name \$host;/d' "$f"
    done
else
    echo "⚠️ No matching IF_backend_* files found, skipping cleanup step."
fi

# Step 2: Append configs to backend_* files only if missing
echo "➡️ Appending proxy configurations to $CUSTOM_DIR/backend_* files ..."

find "$CUSTOM_DIR" -maxdepth 1 -type f -name "backend_*" | while read -r file; do
    echo "Checking file: $file"
    added=0

    if ! grep -qE '^\s*proxy_ssl_server_name\s+on;' "$file"; then
        echo "proxy_ssl_server_name on;" >> "$file"
        added=1
    fi

    if ! grep -qE '^\s*proxy_ssl_name\s+\$host;' "$file"; then
        echo "proxy_ssl_name \$host;" >> "$file"
        added=1
    fi

    if [ $added -eq 1 ]; then
        echo "✅ Missing configurations added to $file"
    else
        echo "↩️ Configuration already exists in $file, no changes made"
    fi
done

echo "=== ✔️ All operations completed ==="

6. Future Maintenance and Upgrades

For future routine upgrades, you can refer to the Upgrade Guide directly or use the official one-click upgrade script:

bash -c "$(curl -fsSLk https://waf.chaitin.com/release/latest/manager.sh)" -- --en