install

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

wget 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

wget 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