SamWaf on Ubuntu 24.04 on Azure User Guide

Overview

SamWaf is a lightweight, open source, self-hosted web application firewall. It sits in front of your web applications as a reverse proxy, inspecting traffic for SQL injection, cross site scripting, remote command execution, path traversal and scanner activity, and gives you a web admin console for defining protected hosts, IP and URL allow/block lists, CC (rate-limit) protection against bots and scrapers, and automatic ACME TLS certificates. Everything is stored in a single embedded, encrypted SQLite database — there is no separate database service to run or secure.

Upstream SamWaf already generates a fresh, cryptographically random administrator password the very first time it starts against an empty database (rather than shipping a fixed default), and forces a password change on that account's first login. This image builds on that: the database is genuinely empty at capture time, so every VM's first real boot is a truly fresh install, and cloudimg's first-boot automation completes the mandatory password-change step for you — rotating to a second, independently generated password — so your first sign-in is a clean, fully working session rather than a forced-change interstitial. The generated password is written to a root-only file. Backed by 24/7 cloudimg support.

What is included:

• SamWaf 1.3.23 installed from the official release binary, running as a systemd service under a dedicated unprivileged samwaf user
• The admin console on port 26666
• A unique administrator account generated on first boot and recorded in a root-only file (username admin)
• The mandatory first-login password change already completed for you, by cloudimg's first-boot automation, before you ever sign in
• AmbientCapabilities=CAP_NET_BIND_SERVICE so you can bind protected hosts to ports below 1024 (e.g. 80/443) without running as root
• The full Apache License 2.0 text shipped at /opt/samwaf/LICENSE
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is ample — SamWaf is a single lightweight binary with an embedded database. NSG inbound: allow 22/tcp from your management network and 26666/tcp for the admin console. If you plan to protect sites on the standard web ports, also allow 80/tcp and 443/tcp.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for SamWaf by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and add a custom rule for 26666. Review your choices, then Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name samwaf \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name samwaf --port 26666 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the service is running

systemctl is-active samwaf.service

This reports active. SamWaf runs as the unprivileged samwaf system user, with its database, configuration and logs under /opt/samwaf.

Step 5 - Retrieve your administrator credential

The administrator account is generated uniquely on the first boot of your VM, and the mandatory first-login password change has already been completed by cloudimg's first-boot automation. The final, ready-to-use credential is written to a root-only file:

sudo cat /root/samwaf-credentials.txt

You will see the admin console URL, the username (admin) and the per-VM password. Keep this password safe — it is the administrator for your SamWaf instance.

Step 6 - Verify the credential round-trips end to end

The image ships a self-test that proves the per-VM admin login actually works, that an authenticated WAF-configuration API is reachable with the resulting session, and that a known legacy default password is rejected:

sudo /usr/local/sbin/samwaf-selftest.sh

The self-test logs in with the per-VM password from Step 5, calls the protected-host list API with the resulting session token, and confirms the legacy default password admin868 is refused.

Step 7 - Review the security posture

ps -o user= -p "$(systemctl show -p MainPID --value samwaf.service)"
sudo ss -lnt | grep -E ':26666|:80 |:443 '
sudo grep -c '^SAMWAF_ADMIN_PASSWORD=.\+$' /root/samwaf-credentials.txt

SamWaf runs as the unprivileged samwaf user (never root), the admin console listens on 26666, and the credentials file holds a real generated password rather than a placeholder.

Step 8 - Sign in to the admin console

In your browser, go to http://<vm-public-ip>:26666/. Sign in as admin with the password from Step 5.

Step 9 - Define your first protected host

Once signed in, open Host Management and click Add Host. Give the protected host a domain name and point it at your backend (protocol, address and port), then save. SamWaf immediately begins reverse-proxying and inspecting traffic for that host, and it appears in your host list on the dashboard.

From here you can define IP and URL allow/block lists, enable CC (rate-limit) protection, request an automatic ACME TLS certificate for the host, and review the attack log — all from the same console.

Step 10 - Review the attack log

Open Attack Log to see every request SamWaf has inspected and blocked for your protected hosts, with the rule that matched, the source IP and a geo lookup.

Maintenance

Secure the admin console. By default the console is reachable on 26666 to anyone who can route to the VM. Restrict the NSG rule for 26666 to your management network's IP range rather than leaving it open to the internet, and consider putting the console itself behind a VPN or bastion.

Back up your configuration. Everything SamWaf stores — protected hosts, rules, accounts and logs — lives in the embedded encrypted database under /opt/samwaf/data. Snapshot the OS disk from the Azure portal, or copy the directory while the service is stopped:

sudo systemctl stop samwaf.service
sudo tar czf /var/tmp/samwaf-data-backup.tgz -C /opt/samwaf data
sudo systemctl start samwaf.service

Reset your password if you lose it. SamWaf ships a CLI reset tool (this stops the service briefly, so run it during a maintenance window):

sudo systemctl stop samwaf.service
sudo -u samwaf /opt/samwaf/SamWafLinux64 resetpwd
sudo systemctl start samwaf.service

Update SamWaf. The admin console offers a one-click online upgrade under System. To upgrade from the command line instead, download the new release, verify its checksum, and replace the binary:

sudo systemctl stop samwaf.service
# download + verify the new SamWafLinux64 release binary, then:
sudo install -m 0755 -o samwaf -g samwaf SamWafLinux64 /opt/samwaf/SamWafLinux64
sudo systemctl start samwaf.service

Review the upstream release notes before upgrading.

Support

This image is maintained by cloudimg with 24/7 support. If you need help deploying or operating SamWaf on Azure, contact cloudimg support through the Azure Marketplace listing.

SamWaf is an open source project (Apache-2.0). This image packages unmodified upstream SamWaf with cloudimg configuration and automation, and is not affiliated with or endorsed by the SamWaf project.