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

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

スクリプトは 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 では証明書が自己署名のため ブラウザーが一度警告を出すことに注意してください。

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

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

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/ に記録されています。 ツールのアップグレードで更新されるのは、提示されるパックのカタログだけです。

以前のバージョンへ戻す

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

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

マネージャーに外部接続がまったくない場合

接続できるマシンで取得し、その結果を持ち込みます。

接続できるマシンで:

git clone --depth 1 https://github.com/jasoncheng7115/jt-wazuh-mgr.git
tar czf jt-wazuh-mgr.tgz -C jt-wazuh-mgr lib packs images \
    wazuh_agent_mgr.py create_api_user.py requirements.txt \
    config.yaml jt-wazuh-mgr.service uninstall.sh
pip download -r jt-wazuh-mgr/requirements.txt -d wheels
tar czf wheels.tgz wheels

マネージャー上で:

sudo mkdir -p /opt/jt-wazuh-mgr
sudo tar xzf jt-wazuh-mgr.tgz -C /opt/jt-wazuh-mgr
tar xzf wheels.tgz
sudo pip install --no-index --find-links=wheels -r /opt/jt-wazuh-mgr/requirements.txt
sudo cp /opt/jt-wazuh-mgr/jt-wazuh-mgr.service /etc/systemd/system/
sudo systemctl daemon-reload && sudo systemctl enable --now jt-wazuh-mgr

オフライン環境でのアップグレード

そこで install.sh を実行しないでください。GitHub と PyPI へ 接続しようとしますし、その環境向けにカスタマイズしたサービス定義を上書きします。 プログラムファイルだけを入れ替えます:

sudo systemctl stop jt-wazuh-mgr
sudo tar xzf jt-wazuh-mgr.tgz -C /opt/jt-wazuh-mgr
sudo rm -rf /opt/jt-wazuh-mgr/lib/__pycache__
sudo systemctl start jt-wazuh-mgr
grep __version__ /opt/jt-wazuh-mgr/lib/__init__.py

依存パッケージがバージョン間で変わることはめったにありません。 requirements.txt が変わっていた場合は、新しい wheel も併せて持ち込んでください。

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

ここで使うのは 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 を作成してください。