install

2 unmask 本体をインストール ?リポジトリ方式: まず unmask-release を 1 回インストールしてリポジトリ設定と GPG 公開鍵を入れる。以降は dnf install unmask / apt install unmask で本体をインストール / アップグレードできる。署名検証はパッケージマネージャーが自動で行う。

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 unmask-web-nginx (Web 連携スニペット) をインストール ?前提: nginx は事前にインストール済み (未インストールなら依存解決で自動的にインストールされます)。forward-auth mode は distro 同梱の nginx で OK。

postinstall: /etc/unmask/forward-auth/{server,protect}.inc と upstream のシンボリックリンクを配置し、nginx -t で検証してからセットアップトークンと URL を表示します。動作中の nginx には触りません — ウィザードの URL は、この後ご自身で行う reload のあとに開けるようになります。

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 保護したい server {} で forward-auth を有効化 (ON/OFF スイッチ) ?この block 1 つが unmask の ON/OFF スイッチです。追加すれば bot 対策が作動し、外せば ブロック / challenge は即停止します。

ダッシュボード集計の経路: forward-auth mode では /_unmask/check サブリクエストが呼ばれたリクエストだけが kind/cnt 集計 (cookie 通過チャート) に乗ります。nginx-native mode の syslog 経路 (全リクエストをカウント) は使われないため、保護対象の location 外のリクエストはダッシュボードに出ません。全リクエストの集計が欲しい場合は nginx-native mode を選んでください。

対象の server {} block (既存 nginx vhost の .conf) に 青色 (ハイライト) の行を追加します。ハイライト以外はあなたの既存の設定です (例は reverse proxy。静的配信 (root + try_files) でも追加する行は同じ)。

既存の location を編集せず、この block を 1 つ追加するだけです。

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

    include /etc/unmask/forward-auth/server.inc;   # ← unmask 本体 (challenge 配信・BAN・管理画面)
    include /etc/unmask/forward-auth/protect.inc;  # ← location 外 (全 location 対象)

    location / {                              # ← user の既存 location は無編集
        proxy_pass http://your-upstream;
    }
}

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

    include /etc/unmask/forward-auth/server.inc;   # ← unmask 本体 (challenge 配信・BAN・管理画面)

    location /login {                         # ← 認証 endpoint だけ保護 (brute-force 対策)
        include /etc/unmask/forward-auth/protect.inc;  # ← この location だけ対象
        proxy_pass http://your-upstream;
    }

    location / {                              # ← 他は保護対象外
        proxy_pass http://your-upstream;
    }
}

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

    include /etc/unmask/forward-auth/server.inc;   # ← unmask 本体 (challenge 配信・BAN・管理画面)

    location /api/ {                          # ← JSON API は除外 (token auth, browser cookie 不要)
        proxy_pass http://your-api-upstream;
    }

    location /static/ {                       # ← 静的資産は除外
        root /var/www/example;
        expires 1d;
    }

    location / {                              # ← catch-all (除外以外をここで保護)
        include /etc/unmask/forward-auth/protect.inc;  # ← catch-all 内 (除外以外を保護)
        proxy_pass http://your-upstream;
    }
}

編集が終わったら nginx を reload して設定を反映します:

sudo nginx -t && sudo systemctl reload nginx

2 unmask 本体をインストール ?リポジトリ方式: まず unmask-release を 1 回インストールしてリポジトリ設定と GPG 公開鍵を入れる。以降は dnf install unmask / apt install unmask で本体をインストール / アップグレードできる。署名検証はパッケージマネージャーが自動で行う。

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 unmask-web-apache をインストール (スニペット自動配置) ?前提: Apache は事前にインストール済み (未インストールなら依存解決で httpd + mod_lua + mod_proxy_http も自動的にインストールされます)。

postinstall: /etc/httpd/conf.d/unmask-web.conf と /etc/httpd/unmask.lua を配置し、apachectl graceful を実行して、セットアップトークンと URL を表示します。conf.d のスニペットが /unmask/* の proxy を立てるので (全 VirtualHost で https://<host>/unmask/admin/setup/ が開く)、インストールしただけでは保護は発火しません — section 4 の LuaHookAccessChecker 行を VirtualHost に追加して有効化する形です (nginx mode の 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 保護したい VirtualHost で forward-auth を有効化 (ON/OFF スイッチ) ?この block 1 つが unmask の ON/OFF スイッチです。追加すれば bot 対策が作動し、外せば ブロック / challenge は即停止します。

ダッシュボード集計の経路: nginx-native (plugin + unix datagram socket access_log) とは違い、Apache mode では forward-auth のサブリクエスト経由で admin の /_unmask/check に 1 リクエスト来るたびに、kind/cnt 集計 (cookie 通過状況のチャート) が +1 されます。つまり 保護対象の VirtualHost のリクエストだけが集計対象になり、nginx-native のように「全リクエストをカウント」にはなりません。

fail-open: /etc/httpd/unmask.lua 内で、admin へのサブリクエストが失敗した場合に OK を返す実装です (リクエストはバックエンド / 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