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.

Right after install: the unmask daemon starts on its own (127.0.0.1:9477), and the package prints the setup token and keeps it in /var/lib/unmask/.setup-token. The setup wizard launches in section 4.

Upgrade: sudo dnf upgrade 'unmask*' (on deb, sudo apt upgrade; on Alpine, sudo apk upgrade). The package restarts the daemon itself.

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-plugin-nginx (native plugin) ?Prerequisite: nginx must be installed (auto-pulled in step 4 via unmask-web-nginx dependencies).

postinstall: places load_module into the distro's conventional dir (/usr/share/nginx/modules/ or /etc/nginx/modules-enabled/) automatically. 15 nginx versions × OpenSSL 1.0 / 1.1 / 3 ABIs are bundled (1.10–1.30 series / glibc) so the matching module is picked at install time. No manual editing.

After an nginx upgrade: ABI mismatch surfaces as nginx -t errors → sudo dnf upgrade unmask-plugin-nginx (or sudo apt install --only-upgrade unmask-plugin-nginx on deb) realigns versions.

sudo dnf install -y unmask-plugin-nginx

sudo yum install -y unmask-plugin-nginx

sudo yum install -y unmask-plugin-nginx

sudo apt install -y unmask-plugin-nginx

sudo apk add unmask-plugin-nginx

sudo dnf module reset -y nginx
sudo dnf module install -y nginx:1.24

sudo yum install -y epel-release
sudo yum install -y nginx

# A. via EPEL (nginx 1.10.3 / within the OS ecosystem. recommended)
sudo rpm -Uvh http://archive.kernel.org/centos-vault/6.10/extras/x86_64/Packages/epel-release-6-8.noarch.rpm
sudo yum install -y nginx

# B. nginx.org HTTP repo (nginx 1.18.0 / newer)
sudo tee /etc/yum.repos.d/nginx.repo <<'EOF'
[nginx]
name=nginx repo
baseurl=http://nginx.org/packages/centos/6/x86_64/
gpgcheck=0
enabled=1
EOF
sudo yum install -y nginx

4 Install unmask-web-nginx (web config snippet) ?postinstall places the upstream symlink and the include described below, validates with nginx -t, and prints the setup wizard URL. It does not touch the running nginx — the wizard URL becomes reachable after the restart you run below.

The JA4 maps include is fully automatic: postinstall places a symlink at /etc/nginx/conf.d/00-unmask.conf → /var/lib/unmask/nginx/http.inc. Since every distro's default include /etc/nginx/conf.d/*.conf; auto-loads it (/etc/nginx/http.d/ on Alpine), you do not need to edit the http {} block.

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

5 Fire the challenge in the server {} you want to protect (ON/OFF switch) ?These highlighted lines are unmask's ON/OFF switch. Add them and bot protection fires; remove them and blocking / challenges stop immediately, with no effect on user traffic. The access-log statistics feed keeps flowing either way, so a safe rollout is step-by-step: monitoring (stats only) → trial (fire on one location) → production (fire site-wide).

What you actually write is 2 lines: include /var/lib/unmask/nginx/server.inc; directly inside server { }, and include /var/lib/unmask/nginx/protect.inc; wherever you want protection. Everything else (rate-limit zones, challenge dispatch, JA4 maps) is rendered by the admin into /var/lib/unmask/nginx/ and auto-loaded via the conf.d symlink placed in section 4.

Rate / burst / target paths live on the Settings → rate-limit tab. To restrict which domain can reach the admin UI, use Settings → Network → admin_allowed_hosts.

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 /var/lib/unmask/nginx/server.inc;   # ← unmask itself (challenge serving, BAN, admin UI)
    include /var/lib/unmask/nginx/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 /var/lib/unmask/nginx/server.inc;   # ← unmask itself (challenge serving, BAN, admin UI)

    location /login {                         # ← protect just the auth endpoint (brute-force defense)
        include /var/lib/unmask/nginx/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 /var/lib/unmask/nginx/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 /var/lib/unmask/nginx/protect.inc;  # ← inside the catch-all (protects everything not excluded)
        proxy_pass http://your-upstream;
    }
}

Once you're done editing, apply the config. If you have not restarted nginx since installing the plugin, restart (a reload does not load a new module); afterwards plain reloads are enough:

sudo nginx -t && sudo systemctl restart nginx

sudo nginx -t && sudo service nginx restart

sudo nginx -t && sudo rc-service nginx restart

From 0.1.53 the reload after a settings save can run by itself: sudo systemctl enable --now unmask-nginx-reload.timer. The timer ships disabled with unmask-web-nginx; every five minutes it reloads nginx when a render changed the configuration and nginx -t passes, at most once per ten minutes, and never restarts it; while the nginx master still maps a library an OS update has replaced, it logs that a restart is needed instead of reloading. Without systemd, run /usr/share/unmask/nginx-reload-if-stale.sh from cron.