インストールとアップグレード
のトラブルシューティング

インストールが止まったが、役に立つメッセージが出ない

スクリプトは set -e で実行されます。最初に失敗したコマンドで処理全体が 即座に終了し、そのコマンド自身のエラーメッセージはすでに画面外へ流れていることがあります。 トレースを付けて実行し直し、最後の数行を残してください:

curl -fsSL https://raw.githubusercontent.com/jasoncheng7115/jt-wazuh-mgr/main/install.sh -o /tmp/jt-install.sh
sudo bash -x /tmp/jt-install.sh 2>&1 | tail -40

エラーの直前にある最後の + の行が、実際に失敗したコマンドです。 それを下の各章と照らし合わせてください。

インストールスクリプトが変更する場所

• /opt/jt-wazuh-mgr/ —— プログラムファイル、ルールパック、および config.yaml
• /etc/systemd/system/jt-wazuh-mgr.service —— サービス定義ファイル。実行のたびに上書きされます
• requirements.txt に基づき pip でインストールされる Python パッケージ

どのサーバーにインストールすればよいか

Wazuh Manager 本体にインストールします。クラスタ構成の場合はマスターノードです。 本ツールは /var/ossec からルールセットとマネージャー自身のファイルを読み取るため、 別のマシンからマネージャーを管理することはできません。

エージェントではなくマネージャー上にいることを確認します:

/var/ossec/bin/wazuh-control info
ls /var/ossec/etc/rules/    # マネージャーには存在し、エージェントには存在しません

curl: (6) Could not resolve host / (7) Failed to connect

このマネージャーから GitHub へ到達できません。これは珍しいことではなく、 Wazuh Manager は意図的に隔離ネットワークへ置かれていることが多くあります。対処は 2 つです:

• プロキシがある場合は、実行前に設定します:

  export https_proxy=http://proxy.example.com:3128
  export http_proxy=$https_proxy
  curl -fsSL https://raw.githubusercontent.com/jasoncheng7115/jt-wazuh-mgr/main/install.sh | sudo -E bash

  sudo -E が重要です。これがないと sudo がプロキシ変数を破棄します。
• 外部への経路がまったくない場合は、下のオフラインインストールを使います。

curl: (60) SSL certificate problem

多くの場合、CA 証明書が古いか、社内のセキュリティ機器が TLS を検査して独自の証明書を 提示しているかのどちらかです。

# CA 証明書を更新する
sudo apt update && sudo apt install --reinstall ca-certificates   # Debian / Ubuntu
sudo dnf reinstall ca-certificates                                  # RHEL / Rocky

機器が通信を検査している場合は、検証を無効にするのではなく、その CA をシステムの 証明書ストアへ追加してください。インストールスクリプトに curl -k を 使ってはいけません —— 出所を検証できないコードをダウンロードすることになります。

インストールできたが「ルールパック」タブが空になる

ルールパックのファイルは可能な範囲でダウンロードされます。索引や個々のファイルを 取得できない場合、インストーラーはその旨を表示して処理を続行し、 インストール全体を失敗させることはしません。

通信が回復してからインストーラーをもう一度実行してください。事前に元へ戻す必要はありません。

error: externally-managed-environment

Debian 12、Ubuntu 23.04 以降では、pip とディストリビューションのパッケージ管理が 同じファイルを奪い合うことを防ぐため、システム Python への pip install が 拒否されます。新しめの OS では、インストールやアップグレードが止まる最も多い原因です。

次の順で検討してください:

1. ディストリビューションのパッケージとして導入する。最も安全で、OS のアップグレードにも追随します:

   sudo apt install python3-flask python3-requests python3-yaml

   その後インストーラーを再実行すると、pip はすべて導入済みと判断します。
2. リスクを承知のうえで pip に指示する（ディストリビューションの版が古すぎる場合）:

   sudo pip install --break-system-packages -r /opt/jt-wazuh-mgr/requirements.txt
   sudo systemctl restart jt-wazuh-mgr

   このオプション名は正直です。pip がパッケージ管理の管理下にあるファイルを置き換える可能性があります。
3. 完全に分離したい場合は仮想環境を使います —— 仮想環境で動かすを参照してください。

pip: command not found

多くのシステムでは pip3 はあっても pip という名前が 用意されておらず、どちらも無い場合もあります。導入してからインストーラーを再実行してください:

sudo apt install python3-pip     # Debian / Ubuntu
sudo dnf install python3-pip     # RHEL / Rocky / Alma

運用方針で pip の使用が認められていない場合は、3 つの依存パッケージを ディストリビューションのパッケージとして導入してください（前の項目を参照）。

pip が PyPI に到達できない

前述のダウンロード失敗と同じ隔離が、より後の手順で現れたものです。 この時点でプログラムファイルはすでに配置済みで、足りないのは依存パッケージだけです。 ディストリビューションのパッケージを使うか、wheel ファイルを自分で持ち込んでください —— オフラインインストールを参照。

仮想環境で動かす

システム Python に一切手を触れたくない場合:

sudo python3 -m venv /opt/jt-wazuh-mgr/venv
sudo /opt/jt-wazuh-mgr/venv/bin/pip install -r /opt/jt-wazuh-mgr/requirements.txt

そのうえで drop-in を使ってサービスに参照させます。drop-in は今後のアップグレードでも失われません:

sudo mkdir -p /etc/systemd/system/jt-wazuh-mgr.service.d
sudo tee /etc/systemd/system/jt-wazuh-mgr.service.d/override.conf <<'EOF'
[Service]
Environment=PATH=/opt/jt-wazuh-mgr/venv/bin:/usr/bin:/bin
EOF
sudo systemctl daemon-reload && sudo systemctl restart jt-wazuh-mgr

まず本当の原因を読み出す

次の 2 つのコマンドが原因を教えてくれます。以下の回答のほとんどはここから得られたものです:

systemctl status jt-wazuh-mgr --no-pager -l
journalctl -u jt-wazuh-mgr -n 50 --no-pager

ModuleNotFoundError: No module named 'flask'

ファイルは配置されたものの依存パッケージが入っていません。pip の手順がそれより前に 失敗しており、set -e のため気付きにくくなっています。 Python の依存パッケージを解決してから:

sudo systemctl restart jt-wazuh-mgr

Address already in use／ポート 5000 が応答しない

別のプログラムがそのポートを使用しています。まず特定します:

sudo ss -tlnp | grep :5000

そのサービスを停止するか、drop-in でポートを変更します。こうすればアップグレードで戻されません:

sudo mkdir -p /etc/systemd/system/jt-wazuh-mgr.service.d
sudo tee /etc/systemd/system/jt-wazuh-mgr.service.d/override.conf <<'EOF'
[Service]
ExecStart=
ExecStart=/opt/jt-wazuh-mgr/wazuh_agent_mgr.py --web --ssl-auto --port 5443
EOF
sudo systemctl daemon-reload && sudo systemctl restart jt-wazuh-mgr

空の ExecStart= は必須です。元の設定を消してから新しい行が有効になります。

サービスは起動しているのにブラウザーから接続できない

マシン本体から外側へ向かって確認します。1 つ目が応答して 2 つ目が応答しない場合は、 ツールではなくファイアウォールの問題です:

curl -kIs https://127.0.0.1:5000/ | head -1      # マネージャー上で実行
sudo firewall-cmd --add-port=5000/tcp --permanent && sudo firewall-cmd --reload   # RHEL 系
sudo ufw allow 5000/tcp                                                            # Ubuntu

URL が https であることに注意してください。--ssl-auto では、Wazuh Dashboard が 同じホストにある場合は Dashboard の証明書をそのまま使います（1.11.3 以降）。それ以外は自己署名 証明書のため、ブラウザーが一度警告を出します。

Wazuh Dashboard を開いた直後に「接続が切断されました」と表示される

Chrome と Edge は、自己署名証明書に対する「続行」を port ではなくホスト単位で記憶し、 そのホストで有効な証明書を一度でも見ると、それらの例外をすべて取り消します。Dashboard が 同じマシンで動いていて、その証明書をブラウザーが信頼している場合、Dashboard を開いた時点で 本ツールが使っていた例外が消えます。以降のリクエストはすべて TLS ハンドシェイクで失敗し、 画面には「接続が切断されました」と出ますが、リクエストが届いていないためツールのログには 何も残りません。F5 を押すと証明書の警告が再び表示されます。Firefox では起きません。

1.11.3 以降にアップグレードし、--ssl-auto のままにしてください。ツールが Dashboard の 証明書を使うため、取り消される例外そのものがなくなります。独自の証明書を使う場合は、 ブラウザーが信頼するものを指定してください:

./wazuh_agent_mgr.py --web --ssl-cert /path/to/cert.pem --ssl-key /path/to/key.pem

画面に「セッションの有効期限が切れました」と出てログイン画面に戻る場合は、Wazuh API が トークンを取り消しています。その時刻の /var/ossec/logs/api.log に DELETE /security/user/authenticate または PUT /security/user/revoke が ないか確認し、ツールには Dashboard の wazuh-wui ではなく専用の API ユーザーで ログインしてください。

アップグレードは終わったのにバージョンが変わらない

インストーラーの最後の要約行を信用せず、インストール先のパスから直接バージョンを読み出します:

grep __version__ /opt/jt-wazuh-mgr/lib/__init__.py
systemctl is-active jt-wazuh-mgr

ファイルは新しいバージョンなのに画面が古いままの場合は、古いバイトコードを削除して再起動します:

sudo rm -rf /opt/jt-wazuh-mgr/lib/__pycache__
sudo systemctl restart jt-wazuh-mgr

そのうえでキャッシュを無視してブラウザーを再読み込みします（Ctrl+Shift+R）。

カスタマイズしたサービス定義がアップグレードで消えた

一度復元したうえで、設定を drop-in へ移してください。インストーラーは drop-in には触れません:

sudo mkdir -p /etc/systemd/system/jt-wazuh-mgr.service.d
sudo tee /etc/systemd/system/jt-wazuh-mgr.service.d/override.conf <<'EOF'
[Service]
Environment=PYTHONPATH=/opt/jt-wazuh-mgr/vendor
EOF
sudo systemctl daemon-reload && sudo systemctl restart jt-wazuh-mgr

実際に有効な内容は systemctl cat jt-wazuh-mgr で確認できます。

アップグレードで設定やインストール済みのルールパックは変更されますか

変更されません。config.yaml は既に存在すれば読み飛ばされます。 インストール済みのルールパックは Wazuh マネージャー自身のディレクトリ （/var/ossec/etc/rules、etc/lists、etc/decoders）にあり、 その状態は /var/ossec/etc/jt-packs/ に記録されています。 ツールのアップグレードで更新されるのは、提示されるパックのカタログだけです。

更新後のカタログに、インストール済みより新しいバージョンのパックがあれば、「ルールパック」タブの その横に更新が表示されます（1.12.0 以降）。変更内容を先に示し、管理しているリストと編集した ファイルは、別途選ばない限りそのまま残します。お使いのバージョン以降に追加されたエージェント側の 手順も一覧表示します。更新後はすべてのノードでルールセットを再読み込みしてください。

以前のバージョンへ戻す

アップグレード前に控えを取っておけば、いつでも戻せます:

sudo tar czf /root/jt-wazuh-mgr-backup-$(date +%F).tar.gz -C /opt jt-wazuh-mgr
# 戻す場合
sudo systemctl stop jt-wazuh-mgr
sudo tar xzf /root/jt-wazuh-mgr-backup-YYYY-MM-DD.tar.gz -C /opt
sudo systemctl start jt-wazuh-mgr

Manager がインターネットに接続できない場合のインストールとアップグレード

インターネットに接続できるマシンで、リリース本体と Manager の Python バージョンに合う wheel を 1 つのアーカイブにまとめて 持ち込み、その中のインストーラーを実行します：

tar xzf /root/jt-wazuh-mgr-X.Y.Z-offline.tar.gz -C /root
sudo bash /root/jt-wazuh-mgr-X.Y.Z/install.sh --offline

--offline を付けると、インストーラーは展開したディレクトリからすべてをコピーし、その wheels/ の パッケージを /opt/jt-wazuh-mgr/vendor に入れます。curl・apt・dnf は実行せず、 pip も必須ではありません。アップグレードも同じ手順で、config.yaml は保持されます。

アーカイブの作り方、Python バージョンの合わせ方、確認、アップグレード、切り戻し、v1.19.0 以前向けの手動の手順は 専用ページにまとめています：オフラインでのインストールとアップグレード。

ログイン画面は出るが認証情報が拒否される

ここで使うのは Wazuh API のユーザーであり、OS のアカウントでも Dashboard の ログインアカウントでもありません。まず API 自体が応答するか確認します:

curl -k -u <ユーザー名>:<パスワード> https://127.0.0.1:55000/security/user/authenticate

Wazuh のインストール時に生成されたパスワードは wazuh-install-files.tar の中にあり、 通常は Wazuh のインストーラーを実行したディレクトリに置かれています。 本ツール専用のアカウントを作る場合:

sudo /opt/jt-wazuh-mgr/create_api_user.py

設定エディターに構文の色付けがない

エディター部品は CDN から読み込まれるため、隔離ネットワークでは取得できません。 編集そのものは正常に動作し、色が付かないだけです。対処は不要です。

完全に削除する

sudo bash /opt/jt-wazuh-mgr/uninstall.sh

マネージャーへインストールしたルールパックはこのコマンドでは削除されません。 併せて削除したい場合は、先に「ルールパック」タブから削除してください。 そうすることで、上書きされていた元のファイルが正しく復元されます。

問い合わせの際に添えていただきたい情報

次の 4 つがあれば、ほとんどのインストール問題は一目で判断できます:

cat /etc/os-release | head -2
python3 -V
grep __version__ /opt/jt-wazuh-mgr/lib/__init__.py
journalctl -u jt-wazuh-mgr -n 50 --no-pager

加えて、このページの最初の項目にある bash -x の出力の最後 40 行をお願いします。 github.com/jasoncheng7115/jt-wazuh-mgr/issues で issue を作成してください。