fixsts.pyスクリプトを用いたvCenter 503エラー(STS証明書期限切れ)の緊急復旧手順

VMware tutorial - IT technology blog
VMware tutorial - IT technology blog

週の初めにvSphere Clientを開くと、真っ白な画面とともに503 Service UnavailableやSigning certificate is not validというエラーコードが表示されることがあります。サーバールームのESXiホスト群や稼働中の仮想マシン(VM)、業務システム自体は正常に動作しているにもかかわらず、vCenterが応答しなくなったことで、VMの起動・停止、vMotionによる移行、リソース監視が一切行えなくなってしまいます。vCenter運用開始から約2年が経過した環境で最も多く見られる原因が、内部のSTS証明書のサイレントな有効期限切れです。

5分で完了する緊急対応(クイックフィックス)

STS証明書の期限切れによってvSphere Clientへ接続できないことが確認できた場合は、以下の4ステップで迅速に対応し、管理機能を取り戻しましょう。

ステップ1:vCenter仮想マシンのスナップショット取得(必須)

vCenter Server Appliance(VCSA)の仮想マシンが稼働しているESXiホストに直接ログインし、バックアップ用のスナップショットを直ちに取得します。この際、「仮想マシンのメモリのスナップショット」には絶対にチェックを入れないでください。メモリを含めないことで30秒以内にスナップショットの取得が完了し、万が一ロールバックが必要になった場合でも、VCSA内部のPostgreSQLデータベースのロック競合や不整合を防ぐことができます。

ステップ2:SSHの有効化とBash Shellへのアクセス

PuTTYやターミナルを使用して、rootアカウントでVCSAのIPアドレス宛てにSSH接続します。次のコマンドを実行してLinux標準のBashシェルを有効化します。

# アプライアンスシェルから標準のBashシェルへ切り替え
shell.set --enabled True
shell

ステップ3:checksts.pyによる有効期限の確認

Broadcom(旧VMware)はナレッジベース記事KB 79248にて簡易チェックツールを提供しています。WinSCP経由でVCSAのテンポラリディレクトリにスクリプトを転送するか、あるいはvi /tmp/checksts.pyを実行してスクリプトのコードを直接貼り付け、実行します。

cd /tmp
python checksts.py

実行結果の画面にSTS Signing Certificate Status: Expiredという赤字の警告メッセージが出力された場合、認証トークン署名用証明書の有効期限が切れています。

ステップ4:fixsts.pyの実行とサービスの再起動

fixsts.pyスクリプトを実行すると、新しいキーペアが再生成され、VMware Endpoint Certificate Store(VECS)へ直接反映されます。

# 実行権限を付与し、/tmpディレクトリでスクリプトを実行
chmod +x fixsts.py
python fixsts.py

# プロンプトが表示されたら[email protected]のパスワードを入力
# 「Finished successfully!」と表示されたら、全サービス群を一括再起動:
service-control --stop --all && service-control --start --all

サービスの再起動には、VCSAに割り当てられたRAMやvCPUのリソース量に応じて通常5〜8分ほどかかります(Tiny/Small構成では起動に時間がかかる傾向があります)。vmware-vpxdやvsphere-uiなどのコアサービスがすべてStarted状態になったら、ログイン画面をリロードしてください。

STS証明書の役割とvCenterが突然停止する仕組み

Security Token Service(STS)は、VMwareのSingle Sign-On(SSO)機構における心臓部です。このサービスは、内部通信全体に向けてSAML形式の暗号化トークンを発行する役割を担っています。制御コアであるvpxdから管理UIであるvsphere-ui、さらにはVeeam Backup & ReplicationなどのバックアップソリューションやSANストレージプラグインに至るまで、すべての内部コンポーネントが相互通信のためにこのトークンを必須とします。

vCenter 6.5 Update 2、6.7、および7.0の初期バージョンを新規インストールした場合、VMwareはSTS証明書のデフォルト有効期限をわずか2年間(730日)に設定していました。危険な点は、ブラウザのアドレスバーに表示されるMachine SSL証明書(ポート443)とは異なり、このSTS証明書の期限が外部からは視覚的に確認できないことです。VECSデータベースや内部LDAPディレクトリであるvmdirの奥深くに格納されています。

そして証明書が有効期限を迎えた瞬間、認証チェーン全体が一気に崩壊します。

  • SSOがあらゆるセッションに対する新規トークンの署名・発行を拒絶する。
  • vpxdサービスとWeb Clientインターフェース間の通信が途絶し、HTTP 503エラーが発生する。
  • ローカルアカウントの[email protected]やActive Directory連携アカウントでのログインがすべて失敗する。

Linked Mode環境での対応とよくあるトラブル

単一のスタンドアロン環境(Embedded PSC)であれば、fixsts.pyによる復旧の成功率は95%以上です。しかし、大規模なエンタープライズ基盤では次のような特有のシナリオに留意する必要があります。

1. Enhanced Linked Mode構成(単一SSOドメイン内に複数vCenterが存在する場合)

複数のvCenterが同一のSingle Sign-Onドメインにリンクされている場合、STS証明書はVMware Directory Service(vmdir)プロセスによって自動的にレプリケーションされます。以下の手順を厳格に守って作業を進めてください。

  • 必ず単一ノードでのみ実行する:プライマリとなる1台目のvCenterサーバーを選び、そこでpython fixsts.pyを実行します。他のノードで同時にスクリプトを実行することは絶対に避けてください。
  • レプリケーションステータスを確認する:セカンダリノードのサービスを再起動する前に、以下のコマンドを実行して新しい証明書データが正常に同期されているかを確認します。
/usr/lib/vmware-vmdir/bin/vdcrepadmin -f showpartnerstatus -h localhost -u administrator

各ノード間のPartner is at USNの値が一致していれば同期完了です。スクリプトを再実行することなく、残りのvCenterで順番にサービスを再起動してください。

2. サービス再起動時のハングアップ

メモリ上に残存した古いSSOキャッシュとの競合により、service-control --start --allコマンドがvmware-vmonで停止したり、vmware-vpxdでエラーになったりすることがあります。その際はログファイルを開いて状況を確認してください。

tail -n 100 /var/log/vmware/vpxd/vpxd.log

スクリプトが正常終了したにもかかわらずログにFailed to authenticate with STSエラーが記録され続ける場合、最も確実な対処法はrebootコマンドでアプライアンス全体を再起動し、RAM上に残留しているプロセスを完全にクリアすることです。

運用現場で役立つ実践ノウハウ

  1. 有効期限前の自動チェックをスケジュール設定する:システム障害が発生してから対処するのではなく、ZabbixやPrometheusなどのLinux監視サーバー上でシンプルなCronジョブを設定するか、30日ごとにConnect-VIServerを実行するPowerShellスクリプトを用いて、証明書の有効期限切れを事前に検知・アラート通知できるようにしておきましょう。
  2. STS証明書とMachine SSL証明書を明確に区別する:fixsts.pyスクリプトはSAMLトークン署名キーのみを更新します。ブラウザ向けのSSL証明書は更新されません。ポート443の証明書も期限が近い場合は、/usr/lib/vmware-vmca/bin/certificate-managerのメニュー1を使用して別途更新する必要があります。
  3. 24〜48時間後にスナップショットを削除する:vCenterクラスタが安定稼働し、夜間のバックアップ処理も問題なく完了したことを確認したら、ステップ1で取得したスナップショットを速やかに削除してください。スナップショットを長期間放置するとVMDKファイルが肥大化し、ストレージのI/Oパフォーマンス低下を招く原因となります。
Share: