install

1 Get the compose file ?Two containers, one file: admin (the daemon: admin UI, challenge verification, ban list, stats) and nginx (the official nginx image with the unmask module). Images come from unmask.sh/ (served like the packages; mirrored at ghcr.io/unmask-sh/), and a stand-in app is included so the example answers on its own.

The volumes matter: /etc/unmask holds the rendered nginx config and the secrets that sign pass cookies, /var/lib/unmask is the database. Keep them across upgrades.

Upgrade: docker compose pull && docker compose up -d.

Runs on any Linux with Docker Engine and Compose v2 (Docker Desktop on macOS / Windows too) — there is no OS / distro to choose.

mkdir unmask && cd unmask
curl -fsSLO https://unmask.sh/dl/docker/docker-compose.yml

2 Start it and pick up the token ?The first start brings :443 up with a self-signed certificate (your browser warns once). The upstream, the hostnames and the real certificate are all set in the admin UI in the next step (Settings → Gateway), so the compose file needs no editing.

The gateway forwards passing requests with Host, X-Real-IP, X-Forwarded-For and X-Forwarded-Proto, passes WebSocket upgrades, and sets no body-size limit of its own.

docker-compose.yml works as it is. Start it and pick up the setup token from the log:

docker compose up -d
docker compose logs admin | grep "setup token"

3 Finish the wizard, then set up the Gateway ?The admin UI sits behind the same protection as the rest of the site, so the first thing you see on the setup URL is a short security check; pass it and the wizard follows. Only /unmask/admin/ is challenged at this point — until an upstream is set the gateway answers with a notice saying so, and once it is, your site is served as before.

Certificates: Settings → Gateway shows what :443 is serving right now (issuer, expiry, whether the name matches). Pick Let's Encrypt and enter a contact address (the hostname must resolve to this host, with :80 reachable; the account is created on the first issuance), or paste a purchased certificate there (certificate, chain, key — the key is stored readable by nobody else and never shown again); a renewal is pasting the new pair.

2 Install the unmask core ?repo method: install unmask-release once first to set up the repo config + GPG public key → from then on you can install / upgrade the core with dnf install unmask / apt install unmask. Signature verification is handled automatically by the package manager.

sudo dnf install -y https://unmask.sh/dl/rpm/unmask-release-latest.noarch.rpm
sudo dnf install -y unmask

sudo yum install -y https://unmask.sh/dl/rpm/unmask-release-latest.noarch.rpm
sudo yum install -y unmask

sudo yum install -y https://unmask.sh/dl/rpm/unmask-release-latest.noarch.rpm
sudo yum install -y unmask

curl -fsSLO https://unmask.sh/dl/deb/unmask-release-latest.deb
sudo apt install -y ./unmask-release-latest.deb
sudo apt update && sudo apt install -y unmask

wget https://unmask.sh/dl/apk/unmask-release-latest.apk
sudo apk add --allow-untrusted ./unmask-release-latest.apk
sudo apk update && sudo apk add unmask

3 Install unmask-web-nginx (web config snippet) ?Prerequisite: nginx must already be installed (if not, dependency resolution installs it automatically). For forward-auth mode the distro's bundled nginx is fine.

postinstall: places /etc/unmask/forward-auth/{server,protect}.inc + the upstream symlink, validates with nginx -t, and prints the setup token / URL. It does not touch the running nginx — the wizard URL becomes reachable after the reload you run below.

sudo dnf install -y unmask-web-nginx

sudo yum install -y unmask-web-nginx

sudo yum install -y unmask-web-nginx

sudo apt install -y unmask-web-nginx

sudo apk add unmask-web-nginx

4 Enable forward-auth in the server {} you want to protect (ON/OFF switch) ?This single block is unmask's ON/OFF switch. Add it and bot protection runs; remove it and blocking / challenges stop immediately.

Dashboard aggregation path: in forward-auth mode, only requests for which the /_unmask/check subrequest was called are counted in the kind/cnt aggregation (the cookie-pass chart). The syslog path used by nginx-native mode (counts every request) is not used here, so requests outside protected locations don't show up in the dashboard. If you want every request counted, choose nginx-native mode.

In the target server {} block (the .conf of your existing nginx vhost), add the blue (highlighted) lines. Everything else is your existing config — a reverse proxy is shown, but a static site (root + try_files) adds the same lines.

No need to edit existing locations — just add this one block.

server {
    listen 443 ssl http2;
    server_name example.com;
    ssl_certificate ...;

    include /etc/unmask/forward-auth/server.inc;   # ← unmask itself (challenge serving, BAN, admin UI)
    include /etc/unmask/forward-auth/protect.inc;  # ← outside any location (protects every location)

    location / {                              # ← your existing location stays unedited
        proxy_pass http://your-upstream;
    }
}

server {
    listen 443 ssl http2;
    server_name example.com;
    ssl_certificate ...;

    include /etc/unmask/forward-auth/server.inc;   # ← unmask itself (challenge serving, BAN, admin UI)

    location /login {                         # ← protect just the auth endpoint (brute-force defense)
        include /etc/unmask/forward-auth/protect.inc;  # ← scoped to this location only
        proxy_pass http://your-upstream;
    }

    location / {                              # ← everything else is unprotected
        proxy_pass http://your-upstream;
    }
}

server {
    listen 443 ssl http2;
    server_name example.com;
    ssl_certificate ...;

    include /etc/unmask/forward-auth/server.inc;   # ← unmask itself (challenge serving, BAN, admin UI)

    location /api/ {                          # ← exclude the JSON API (token auth, no browser cookie needed)
        proxy_pass http://your-api-upstream;
    }

    location /static/ {                       # ← exclude static assets
        root /var/www/example;
        expires 1d;
    }

    location / {                              # ← catch-all (protects everything not excluded)
        include /etc/unmask/forward-auth/protect.inc;  # ← inside the catch-all (protects everything not excluded)
        proxy_pass http://your-upstream;
    }
}

Once you're done editing, reload nginx to apply the config:

sudo nginx -t && sudo systemctl reload nginx

2 Install the unmask core ?repo method: install unmask-release once first to set up the repo config + GPG public key → from then on you can install / upgrade the core with dnf install unmask / apt install unmask. Signature verification is handled automatically by the package manager.

sudo dnf install -y https://unmask.sh/dl/rpm/unmask-release-latest.noarch.rpm
sudo dnf install -y unmask

sudo yum install -y https://unmask.sh/dl/rpm/unmask-release-latest.noarch.rpm
sudo yum install -y unmask

sudo yum install -y https://unmask.sh/dl/rpm/unmask-release-latest.noarch.rpm
sudo yum install -y unmask

curl -fsSLO https://unmask.sh/dl/deb/unmask-release-latest.deb
sudo apt install -y ./unmask-release-latest.deb
sudo apt update && sudo apt install -y unmask

3 Install unmask-web-apache (auto-places the snippet) ?Prerequisite: Apache must already be installed (if not, dependency resolution also auto-installs httpd + mod_lua + mod_proxy_http).

postinstall: places /etc/httpd/conf.d/unmask-web.conf + /etc/httpd/unmask.lua, runs apachectl graceful, and prints the setup token / URL. The conf.d snippet sets up the /unmask/* proxy (makes https://<host>/unmask/admin/setup/ reachable from every VirtualHost) but does NOT auto-protect any VirtualHost — you opt in per-VirtualHost by adding the LuaHookAccessChecker line in section 4 (consistent with nginx mode's per-server include protect.inc;).

sudo dnf install -y unmask-web-apache

sudo yum install -y unmask-web-apache

sudo yum install -y unmask-web-apache

sudo apt install -y unmask-web-apache

4 Enable forward-auth in the VirtualHost you want to protect (ON/OFF switch) ?This single block is unmask's ON/OFF switch. Add it and bot protection runs; remove it and blocking / challenges stop immediately.

Dashboard aggregation path: unlike nginx-native (plugin + unix datagram socket access_log), in Apache mode the kind/cnt aggregation (the cookie-pass chart) is incremented by 1 each time a request reaches admin's /_unmask/check via the forward-auth subrequest. In other words only requests for protected VirtualHosts are aggregated — it's not an "all requests counted" model like nginx-native.

fail-open: /etc/httpd/unmask.lua returns OK when the subrequest to admin fails (the request flows through to the backend / DocumentRoot).

<VirtualHost *:443>
    ServerName example.com
    SSLEngine on
    SSLCertificateFile ...

    LuaHookAccessChecker /etc/httpd/unmask.lua handle_request

    ProxyPass        / http://your-upstream/
    ProxyPassReverse / http://your-upstream/
</VirtualHost>

<VirtualHost *:443>
    ServerName example.com
    SSLEngine on
    SSLCertificateFile ...

    LuaHookAccessChecker /etc/httpd/unmask.lua handle_request

    DocumentRoot /var/www/example
</VirtualHost>

sudo apachectl configtest && sudo systemctl reload httpd

sudo apachectl configtest && sudo systemctl reload apache2