install

1 compose ファイルを取得 ?ファイル 1 つでコンテナ 2 つ: admin (デーモン: 管理画面、challenge 検証、BAN リスト、統計) と nginx (公式 nginx イメージ + unmask module)。イメージは unmask.sh/ から取得され（パッケージと同じ配信元。ghcr.io/unmask-sh/ にもミラー）、例がそのまま動くように仮の app も入っています。

volume は残す: /etc/unmask には描画済みの nginx 設定と通過証 cookie の署名鍵、/var/lib/unmask にはデータベースが入ります。アップグレードをまたいで保持してください。

アップグレード: docker compose pull && docker compose up -d。

Docker Engine + Compose v2 の入った Linux ならどの distro でも動きます (macOS / Windows の Docker Desktop も)。OS / distro の選択は不要です。

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

2 起動してトークンを拾う ?初回起動は自己署名証明書で :443 が上がります (ブラウザは一度警告します)。転送先・ホスト名・本番の証明書はすべて次のステップの管理画面 (設定 → Gateway) で設定するので、compose ファイルを書き換える必要はありません。

gateway は通過したリクエストに Host、X-Real-IP、X-Forwarded-For、X-Forwarded-Proto を付けて転送し、WebSocket の upgrade も通し、body サイズの上限は設けません。

docker-compose.yml はそのままで構いません。起動して、ログからセットアップトークンを拾います:

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

3 ウィザードを済ませ、Gateway を設定 ?管理画面もサイトと同じ保護の内側にあるので、セットアップ URL を開くとまず短い security check が表示され、通過するとウィザードが続きます。この時点で challenge されるのは /unmask/admin/ だけ — 転送先を設定するまで gateway はその旨の案内ページを返し、設定すればサイトはこれまでどおり配信されます。

証明書: 設定 → Gateway に、:443 がいま配信している証明書 (発行者、有効期限、名前の一致) が表示されます。Let's Encrypt を選べば連絡先メールを入れるだけ (ホスト名がこのホストに解決し、:80 に到達できること。アカウントは初回取得時に自動作成)。購入した証明書は同じタブに貼り付けます (証明書、チェーン、鍵 — 鍵は他から読めない権限で保存され、二度と表示されません)。更新は新しい組を貼り直すだけです。

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

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 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

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 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