クライアント・トラブルシューティング

接続診断の基本フロー

AegisMesh クライアントが Management サーバーや他のピアと正常に通信できない場合は、以下の手順で段階的に切り分けを行います。

flowchart TD
    Start([接続エラー発生]) --> CheckStatus["1. aegismesh status --detail 実行"]
    CheckStatus --> IsDaemonRunning{"デーモンは<br>起動しているか？"}
    
    IsDaemonRunning -- No --> FixDaemon["デーモンの起動 / 権限確認 (TUNデバイス等)"]
    IsDaemonRunning -- Yes --> CheckMgmt{"Managementと<br>接続できているか？"}
    
    CheckMgmt -- No --> FixPort443["ネットワーク/ポート443・DNSの疎通確認"]
    CheckMgmt -- Yes --> CheckPeers{"ピアとの通信は<br>確立しているか？"}
    
    CheckPeers -- No --> FixUDP["ICE/Relay状態確認 & MTU調整"]
    CheckPeers -- Yes --> Success([正常通信])

よくある接続トラブルと対処法

1. TUN デバイスの作成エラー (`failed to create TUN device`)

原因と症状

WireGuard トンネル用の仮想ネットワークインターフェース（wt0 または aegismesh0）の生成に失敗すると、Status: NeedsLogin または Daemon connection failed となり通信が開始されません。

OS別の対処手順

Linux (ホスト環境): /dev/net/tun デバイスファイルの存在とパーミッションを確認します。

# デバイスが存在しない場合の作成
sudo mkdir -p /dev/net
sudo mknod /dev/net/tun c 10 200
sudo chmod 666 /dev/net/tun

Linux (Docker コンテナ環境): Docker コンテナ内で AegisMesh クライアントを実行する場合、特権機能（NET_ADMIN）とデバイスマッピングが必須です。

# docker-compose.yml 例
services:
  aegismesh-client:
    image: aegismesh/client:latest
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    devices:
      - /dev/net/tun:/dev/net/tun
    network_mode: host

Windows:
- WireGuard NT ドライバの競合: 他のVPNソフトや古いOpenVPN TAPドライバと競合している可能性があります。「デバイスマネージャー」>「ネットワークアダプター」から古い仮想アダプタを削除し、PCを再起動してください。
- 管理者権限でのインストール（UAC承認）が必要です。
macOS:
- インストール初回時に表示される 「システム機能拡張がブロックされました（System Extension Blocked）」 ダイアログで「システム設定を開く」を選択し、セキュリティ項目から AegisMesh Network Extension を許可してください。

2. ポート443 / WireGuard UDP の通信遮断

症状

Management サーバーへのログインは成功するが、ピアのステータスが Disconnected のまま変化しない、またはP2P接続が確立されない。

原因と確認コマンド

社内FWによるUDP 51820（WireGuard）の遮断: 多くの企業ネットワークやホテルWi-Fiでは、未知のUDPポートが遮断されます。
AegisMeshの自動フェイルオーバー: AegisMeshはP2PのUDP通信が通らない場合、自動的に 外部ポート443に集約された Relay サーバー（TURN / WSS） を経由してトンネルを維持します。

接続方式の確認：

sudo aegismesh status --detail

出力内の各ピアの Connection Type を確認します：

P2P (Direct WireGuard): 最も高速（直接通信）
Relayed (via AegisMesh Relay): UDPがブロックされているためRelay経由で安全に通信中

Relay接続すら確立できない場合は、アウトバウンドの TCP ポート 443（HTTPS / WSS） が社内プロキシや次世代FWでディープパケットインスペクション（SSL復号）によって遮断されていないかネットワーク管理者に確認してください。

3. MTU ブラックホール問題 (SSH/Webブラウジングのフリーズ)

症状

ping 100.64.0.x は応答するのに、ssh でログインすると途中で固まる。
Web管理画面のHTTPヘッダーは返るが、HTML本文などの大容量パケットを受信するとタイムアウトする。

原因

経由するネットワーク（PPPoEやモバイル回線）の最大伝送単位（MTU）が小さく、パケットが断片化（フラグメンテーション）またはDF（Don’t Fragment）ビットにより破棄されている現象です。

対処法

クライアントの MTU を明示的に 1280（IPv6最小MTU）へ縮小:
Terminal window
```
# Linux / macOS
sudo aegismesh up --mtu 1280
```
Exit Node ゲートウェイ側での TCP MSS Clamping 有効化: Exit Node を自社構築している場合、iptables で MSS を自動調整します：
Terminal window
```
sudo iptables -t mangle -A FORWARD -p tcp --tcp-flags SYN,RST SYN -j TCPMSS --clamp-mss-to-pmtu
```

クライアントデバッグバンドル（ログ取得）手順

サポート窓口（草クラウドお問い合わせ）へ問い合わせる際は、以下のデバッグ情報を添付してください。

1. 詳細ステータスの出力

sudo aegismesh status --detail > aegismesh-status.txt

2. 各OSのログファイル保存場所

OS	デーモンログのパス
Linux	`/var/log/aegismesh/client.log` または `journalctl -u aegismesh -n 200`
macOS	`/var/log/aegismesh.log`
Windows	`C:\ProgramData\AegisMesh\daemon.log`

3. ワンライナーでのデバッグアーカイブ作成 (Linux / macOS)

tar -czvf aegismesh-debug-$(date +%Y%m%d).tar.gz \
  /var/log/aegismesh* \
  /etc/aegismesh/config.json 2>/dev/null

※ config.json 内の秘密鍵（PrivateKey）は自動的にマスクされますが、念のため機密情報が含まれていないか確認の上ご提出ください。

各OS固有の注意事項

Windows: WFP（Windows Filtering Platform）の競合

サードパーティ製のアンチウイルスソフト（Trend Micro, Symantec, ESET等）のパーソナルファイアウォール機能が、AegisMeshのパケットフィルタを妨害する場合があります。

aegismesh.exe および wireguard.dll をセキュリティソフトの リアルタイムスキャンおよび通信検査の除外リスト に登録してください。

macOS: スリープ復帰時のトンネル再接続

MacBook を閉じてスリープから復帰した直後、Wi-FiのIPアドレスが切り替わると一時的にトンネルが切断されることがあります。通常は10〜15秒以内にICE再ネゴシエーションが完了しますが、復帰しない場合は以下を実行します：

sudo aegismesh down && sudo aegismesh up

Linux: `systemd-resolved` とのDNS連携

DNSの逆引きや社内ドメイン解決が機能しない場合、/etc/resolv.conf が systemd-resolved のスタブ（127.0.0.53）に正しく向いているか確認してください。

resolvectl status wt0

AegisMesh経由のプライベートDNSサーバーが wt0 インターフェースに正しくバインドされているか確認できます。