Deployment Overview of Haltdos Community WAF on Server¶

Prerequisites and Basic Requirements¶

To successfully deploy the Haltdos Community WAF, the following system requirements and conditions must be met:

• Operating System: Ubuntu-based Linux distribution.
• Privileges: Root access or sudo privileges are required to install packages, modify system configurations, and manage services.
• Domain Configuration: A fully qualified domain name (FQDN) must be configured to point to the server's IP address. The FQDN is constructed using the format {{ prefix }}{{ server_id }}.{{ zone }}.
• Ports: Ports 80 and 443 must be available. Any existing services (such as Apache, Nginx, or Docker containers) occupying these ports will be stopped during the deployment process.
• Docker: Docker must be installed and running on the server to manage the application and proxy containers.

File and Directory Structure¶

The deployment establishes the following directory structure and file locations for configuration, data, and certificates:

• System Host Configuration:
• /etc/hosts: Updated to include the Haltdos FQDN mapping to 127.0.1.1.
• Nginx Configuration:
• /etc/nginx/sites-available/haltdos.conf: The main virtual host configuration file for the reverse proxy.
• /etc/nginx/sites-enabled/haltdos.conf: A symbolic link enabling the Haltdos site.
• /data/nginx/user_conf.d/: Directory containing custom user configuration files, including {{ prefix }}{{ server_id }}.hostkey.in.conf.
• Let's Encrypt Certificates:
• /etc/letsencrypt/live/{{ haltdos_fqdn }}/: Directory containing the SSL certificate (fullchain.pem) and private key (privkey.pem).
• Docker Compose Configuration:
• /root/nginx/compose.yml: The Docker Compose file defining the Nginx and Certbot services.
• /data/nginx/nginx-certbot.env: Environment file for the Nginx-Certbot container.
• Installation Script:
• /root/setup.sh: The official installation script downloaded from https://binary.haltdos.com/community/waf/setup.sh.

Application Installation Process¶

The Haltdos Community WAF is installed using the official setup script provided by the developers. The installation process involves the following steps:

1. System Preparation:

   • The system hostname is set to the Haltdos FQDN.
   • Base packages including curl, nginx, and certbot are installed via apt.
   • Existing web servers (nginx, apache2) and Docker containers listening on ports 80 and 443 are stopped to free the ports for certificate issuance.
   • If a Docker Swarm is active, it is forcibly left to ensure a clean environment.

2. Script Execution:

   • The installation script is downloaded to /root/setup.sh from https://binary.haltdos.com/community/waf/setup.sh.
   • The script is made executable and executed with the following command:

     cd /root
     chmod +x setup.sh
     ./setup.sh
     

3. SSL Certificate Acquisition:

   • If Let's Encrypt is enabled, the certbot tool is used in standalone mode to obtain or renew the SSL certificate for the Haltdos FQDN.
   • The command used is:

     certbot certonly --standalone --non-interactive --agree-tos --email <email> -d <haltdos_fqdn>
     

Proxy Servers¶

The deployment configures Nginx as a reverse proxy to handle incoming HTTP and HTTPS traffic, forwarding requests to the Haltdos application.

• HTTP to HTTPS Redirect:
• Port 80 is configured to listen for requests and immediately redirect them to HTTPS using a 301 status code.
• HTTPS Configuration:
• Port 443 is configured with SSL/TLS support using the certificates obtained from Let's Encrypt.
• Supported protocols are TLSv1.2 and TLSv1.3.
• Server ciphers are preferred (ssl_prefer_server_ciphers on).
• Proxy Settings:
• Traffic is proxied to the Haltdos application running locally on port 9000 via https://127.0.0.1:9000.
• The following headers are forwarded to the backend:
  • Host
  • X-Real-IP
  • X-Forwarded-For
  • X-Forwarded-Proto
• SSL verification for the backend connection is disabled (proxy_ssl_verify off).
• Docker-based Proxy (Alternative/Additional):
• A Docker Compose setup is deployed in /root/nginx using the jonasal/nginx-certbot:latest image.
• This container runs in host network mode and mounts the nginx_secrets volume for Let's Encrypt data.
• It also mounts /data/nginx/user_conf.d to /etc/nginx/user_conf.d inside the container.
• A specific configuration file {{ prefix }}{{ server_id }}.hostkey.in.conf is modified to include a proxy_pass directive pointing to http://127.0.0.1:3000.

Docker Containers and Their Deployment¶

The deployment utilizes Docker containers to manage the Nginx proxy and Certbot services.

• Container Image: jonasal/nginx-certbot:latest
• Deployment Method: Docker Compose
• Compose File Location: /root/nginx/compose.yml
• Service Configuration:
• Restart Policy: unless-stopped
• Network Mode: host
• Environment Variables:
  • CERTBOT_EMAIL: Set to [email protected] (or defined in the env file).
• Volumes:
  • nginx_secrets (external) mapped to /etc/letsencrypt.
  • /data/nginx/user_conf.d mapped to /etc/nginx/user_conf.d.
• Execution:
• The container stack is started using the command:

  docker compose up -d
  

• This command is executed from the /root/nginx directory.

Access Rights and Security¶

Security measures are implemented through service management, firewall port availability, and SSL configuration.

• Service Isolation:
• Conflicting services on ports 80 and 443 are stopped to prevent conflicts.
• Docker Swarm is disabled if active to ensure the deployment runs in a standard Docker environment.
• SSL/TLS Security:
• Only secure TLS versions (1.2 and 1.3) are permitted.
• Server ciphers are prioritized to ensure strong encryption.
• File Permissions:
• The /root/nginx directory is owned by root with permissions 0755.
• The compose.yml file is owned by root with permissions 0644.
• The Nginx configuration file /etc/nginx/sites-available/haltdos.conf is set to 0644.

Starting, Stopping, and Updating¶

The following commands and procedures are used to manage the services after deployment.

• Nginx Service Management:
• To start the Nginx service:

  systemctl start nginx
  

• To enable Nginx to start on boot:

  systemctl enable nginx
  

• To verify the Nginx configuration syntax:

  nginx -t
  

• Docker Compose Management:
• To start the proxy containers:

  cd /root/nginx
  docker compose up -d
  

• To stop the proxy containers:

  cd /root/nginx
  docker compose down
  

• Haltdos Application:
• The application is managed via the installation script and runs as a background service. Specific start/stop commands for the Haltdos binary itself are handled by the setup.sh script during installation.