Elinaトラフィックコントローラー(Elina-TC)
はじめに
Elina-TCは、Linux向けの強力なコマンドラインネットワーク障害およびエミュレーションツールです。Linuxカーネルの組み込みトラフィックコントロール(tc)およびNetEm(netem)サブシステムへのユーザーフレンドリーなインターフェースを提供し、特定のネットワークインターフェース上でさまざまな現実的なネットワーク状態をシミュレートできます。
Elina-TCは、ネットワークテスト、アプリケーション耐性分析、パフォーマンス検証のためのスタンドアロンツールとして優れています。また、Elina-TGなどのトラフィックジェネレーターと統合できるように設計されており、ネットワークパスを劣化させながら同時にアプリケーショントラフィックを生成できます。これにより、ネットワーク障害がアプリケーションのパフォーマンスに与える直接的な影響を測定し理解できます。
仕組み
Elina-TCは、指定されたネットワークインターフェースの入力(ダウンロード)および出力(アップロード)トラフィックにネットワーク障害ルールを適用し、ネットワーク状態がアプリケーションに与える影響をテストできます。これは、中間機能ブロック(ifb)仮想デバイスを活用してこれらの変更を行います。
重要 — 対称シェーピング: 障害は両方向に適用されます。delay: "50ms" のプロファイルは、アップロードに約50ms、かつダウンロードに約50msを追加します(RTTで約100ms)。rate: "10mbit" の制限は両方向に適用されます。これは特に /asymmetric プロファイルを使う場合に重要です。特定の方向(例:400 Mbpsダウンロード)をテストするには、そのボトルネックに合わせた対称レートのプロファイルを適用し、もう一方の方向をテストするときは別のプロファイルに切り替えてください。
このツールは、いくつかのモードで実行できます:
- オンザフライ: コマンドラインから一時的な障害を迅速に適用するため。
- バッチ: 事前定義された障害プロファイルを循環させて自動テストシーケンスを実行するため。
- インタラクティブ: ネットワーク状態のリアルタイム制御。デバッグと探索的テストに理想的。
- 検証: 使用前にプロファイルファイルの構文と論理的正確性をチェックするため。
機能
- レート制限(TBF)、遅延、ジッター、パケットロス、複製、破損、並び替え、キュー制限(netem)
- IFBデバイスによる対称的な入力/出力シェーピング
- 適用せずに
tcコマンドをプレビューするドライランモード - バッチモード(
--show-stats)およびインタラクティブモード(stats、watch stats)でのオプションのtc -s統計 - エラー報告にファイル名、プロファイルインデックス、説明を含むプロファイル検証
セットアップ
Elina-TCはPythonアプリケーションであり、Linuxオペレーティングシステム上でPython 3.7+が必要です。
1. 前提条件: 必要なシステムパッケージがインストールされていることを確認してください。Debian/Ubuntuでは、次のコマンドで実行できます:
sudo apt-get update && sudo apt-get install -y python3-pip python3-venv iproute2
2. ツールのダウンロードと解凍:
wget https://api.latence.ca/software/elina-tc.zip
unzip elina-tc.zip
cd elina-tc-release
3. 仮想環境のセットアップ(推奨): Elina-TCの依存関係を分離するため、これを強く推奨します。
python3 -m venv venv
source venv/bin/activate
4. Elina-TCのインストール: * コアコマンドラインツールとWeb UI(ベータ版)の場合:
pip install .[ui]
これにより、elina-tcコマンドが使用可能になり、Webサーバーに必要なライブラリがインストールされます。
5. Sudoers設定(重要):
UIおよび一部のCLI機能は、sudoを使用してelina-tcを実行します。パスワードなしの操作のためには、ユーザーがパスワードなしでelina-tcコマンドを実行できるようにsudoersファイルを設定する必要があります。
まず、コマンドの完全なパスを見つけます:
# 仮想環境がアクティブであることを確認
which elina-tc
# 出力例:/home/user/elina-tc-release/venv/bin/elina-tc
次に、対応する行をsudoersファイルに追加します。your_usernameとパスの例を実際の詳細に置き換えてください。sudo visudoを使用して/etc/sudoersを安全に編集します:
your_username ALL=(ALL) NOPASSWD: /home/your_username/elina-tc-release/venv/bin/elina-tc
使用モード(コマンドラインインターフェース)
インストール後、Elina-TCはelina-tcコマンドを使用して実行されます。注: ネットワークルールを変更するすべてのコマンドにはsudo権限が必要です。
1. 検証モード
- プロファイルファイルのエラーをチェック:
elina-tc --validate -f profiles/satellite/profiles_LEO_Starlink.json
2. オンザフライモード
- 障害を直接適用:
elina-tc -i eth0 --onthefly "delay 100ms loss 1%"
- これにより、
eth0を通過するすべてのトラフィックに100msの遅延と1%のパケットロスが適用されます。 - オンザフライのパラメータはプロファイルフィールドと同じキーを使います(下記のプロファイルパラメータを参照)。例:
delay、jitter、loss、corrupt、rate、duplicate、reorder。
3. バッチモード
- プロファイルからテストシーケンスを実行:
elina-tc -i eth0 -f profiles/impairments/profiles_PacketLoss_Degradation.json -n 1 --show-stats
- 便利なオプション:
-n COUNT(サイクル数)、--loop(連続実行)、--start_at "YYYY-MM-DD HH:MM:SS"(開始スケジュール)、--dry-run(適用せずにtcコマンドを表示)、-d SEC(各フェーズのデフォルト時間)。複数の-fファイルを渡してプロファイルシーケンスを連結できます。
4. インタラクティブモード
- ライブコントロールとデバッグ用:
elina-tc -i eth0 -f profiles/cellular/5g_5qi_profiles.json --interactive
インタラクティブコマンド(連続セッション):
help— 利用可能なコマンドを一覧表示list— 読み込まれた全プロファイルを表示apply <index_or_name> [for Xs] [with stats]— インデックスまたは説明の部分文字列でプロファイルを適用;オプションのfor 30sはX秒後に自動クリア;オプションのwith statsは適用後にtc -sを表示status— egressおよびingress(ifb0)のtcルールを表示stats [interface]— 詳細なtc -s統計を表示watch stats [interval]— interval秒ごと(デフォルト:2)に更新するライブ統計;Ctrl+Cで停止clear— インターフェースとifb0からすべてのtcルールをクリアexit/quit— セッションを終了してクリーンアップ
Web UI(ベータ版)
Elina-TCには、CLIを直接使わずに頻繁な操作を簡単にする補完的なWeb UI(ベータ版)が含まれています。pip install .[ui] と上記の sudoers設定 の後:
cd web_ui
python3 elina-tc-ui.py
# ブラウザで http://127.0.0.1:5000/ を開く
典型的なワークフロー:
- Discover Interfaces — アダプターを一覧表示し、障害を適用するインターフェースを選択。
- Browse Profiles — プロファイルツリーが自動読み込みされ、JSONファイルをクリックするとエディターに表示。
- Edit & Save — エディターでJSONを編集し、Save をクリックしてディスクに書き戻す。
- Validate — 選択したファイルに対して
elina-tc --validateと同じチェックを実行。 - Apply — ファイル内の全フェーズを順に実行(バッチモードと同様)、または On-the-Fly でワンショットの障害文字列を使用。
- Stats / Clear —
tc -s統計の表示、またはインターフェースとifb0からルールを削除。
セキュリティ: 信頼できないネットワークにUIを公開しないでください。sudo 経由で特権的なネットワーク操作を行います。詳細はパッケージ内の web_ui/README_web_ui.md を参照してください。
プロファイルの扱い方
プロファイルは、1つ以上の障害フェーズを定義するJSONまたはCSVファイルです。事前構築のシナリオは profiles/ 配下にあり、独自のシナリオはライブラリを壊さないよう profiles/custom/ に置いてください。
新しいプロファイルを作成する
profiles/custom/(または既存のライブラリファイル)からテンプレートを新しい名前にコピーします。例:profiles/custom/my_scenario.json。- フィールドを編集します(プロファイルパラメータを参照)。ファイルは単一オブジェクトでも、バッチモード用のフェーズ配列でも構いません。
- 使用前に検証:
elina-tc --validate -f profiles/custom/my_scenario.json
- 適用(バッチまたはインタラクティブ):
sudo elina-tc -i eth0 -f profiles/custom/my_scenario.json -n 1
# または
sudo elina-tc -i eth0 -f profiles/custom/my_scenario.json --interactive
最小例(単一フェーズ):
{
"description": "Flaky 4G Mobile in a Vehicle",
"duration_sec": "120",
"rate": "25mbit",
"delay": "70ms",
"jitter": "30ms",
"delay_dist": "normal",
"loss": "0.8%"
}
ヒント: パッケージには、有効なプロファイル案をAIに作成させるためのプロンプトテンプレート(profiles/_prompt-profile-generator/)とJSONスキーマ(profiles/schema/elina-tc-profile-schema.json)が含まれます。生成したファイルには必ず --validate を実行してください。
既存のプロファイルを編集する
- CLI / ファイル: 任意のエディターで
.jsonまたは.csvを開き、保存後に--validateして再適用。変更前にライブラリファイルをprofiles/custom/へコピーすることを推奨します。 - Web UI: ツリーでファイルを選択し、パネルで編集して Save、その後 Validate / Apply。UIは既存ファイルの編集のみで、新しいプロファイルファイル名の作成はしません — 先にディスク上で作成(またはテンプレートをコピー)してください。
プロファイルパラメータ
不要なパラメータは省略してください。空文字列は無視されます。
| パラメータ | 例 | 備考 |
|---|---|---|
description |
"Congested Wi-Fi" |
インタラクティブの list / apply マッチングに表示 |
duration_sec |
"30" |
バッチモードでこのフェーズが有効な秒数 |
rate |
"100mbit" |
帯域制限(TBF)。単位:kbit/mbit/gbit または kbps/mbps/gbps |
tbf_burst |
"128kb" |
トークンバケットのバースト;省略時はデフォルト(--default-tbf-burst) |
tbf_latency |
"50ms" |
TBFキューの最大待ち時間;省略時はデフォルト |
delay |
"100ms" |
基本遅延(ms/us/s) |
jitter |
"10ms" |
遅延のばらつき — delay が必須 |
delay_dist |
"normal" |
uniform、normal、pareto、paretonormal — jitter が必須 |
loss |
"1%" |
パケットロス率 |
loss_correlation |
"25%" |
ロスをバースト気味に — loss が必須 |
duplicate |
"0.5%" |
パケット複製 |
corrupt |
"0.1%" |
ビット破損 |
reorder |
"5%" |
順序乱れ配信 |
reorder_correlation |
"20%" |
— reorder が必須 |
reorder_gap |
"5" |
パケット間隔 — reorder が必須 |
netem_limit |
"1000" |
netemキューに保持できる最大パケット数 |
CSVファイルも同じ列名を使います(profiles/custom/custom_profiles.csv を参照)。# で始まるコメント行はスキップされます。
事前定義されたプロファイルライブラリ
Elina-TCには、profiles/ ディレクトリにある障害プロファイルの広範なライブラリが付属し、ネットワーク技術別に整理されています:
- /basic:入門向けの汎用サンプルプロファイル — 開始点として最適。
- /custom:独自プロファイル用。コピー用のJSON/CSVテンプレートを含む。
- /cellular:モバイルネットワーク状態をエミュレート。QoSクラス識別子(QCI)に基づく4G LTEおよび5G QoS識別子(5QI)とネットワークスライシング(eMBB、URLLC)に基づく5Gのプロファイルが含まれます。モバイルアプリ、IoTデバイス、コネクテッドビークル(V2X)ユースケースのテストに最適。
- /satellite:衛星ネットワークの独自の特性をシミュレート。Starlinkなどの低軌道(LEO)コンステレーション(低レイテンシー、可変パフォーマンス)、中軌道(MEO)、および従来の静止軌道(GEO)衛星(高く安定したレイテンシー)のプロファイルが含まれます。海事、航空宇宙、リモートIoTアプリケーションに理想的。
- /wireless:一般的なワイヤレスローカルエリアネットワークをモデル化。さまざまなWi-Fi状態(理想的、混雑)、Bluetooth、低電力IoTネットワークのプロファイルが含まれ、家庭、オフィス、または短距離デバイス環境でのアプリケーションのテストに役立ちます。
- /asymmetric:アップロードとダウンロード特性が異なるネットワークをシミュレート(DOCSIS、FTTH、4G/5G)。Elina-TCは対称シェーピングのため、これらのプロファイルは一度に一方向を適用する想定です — 仕組みの対称シェーピングの説明を参照。
- /industrial:運用技術(OT)環境で見られるネットワークをモデル化。Profinet、EtherNet/IP、Modbusなどの産業プロトコルのプロファイルが含まれます。産業オートメーションおよびSCADAシステムの耐性をテストするために不可欠。
- /impairments:特定の問題に対するアプリケーション耐性をテストするために設計された汎用的なビルディングブロックプロファイルが含まれます。パケットロスの段階的な悪化、レイテンシーの増加、または混雑したインターネットパスのシミュレーションのシーケンスが含まれます。アプリケーションの破損ポイントを特定するのに最適。
トラフィックジェネレーターとともにElina-TCを使用する
Elina-TCの真の力は、Elina-TGなどの別のツールによって生成されたトラフィックのネットワーク状態を制御するために使用されるときに発揮されます。
- サーバーマシン上(Elina-TCを実行): Elina-TCを使用して、特定のネットワーク状態(例:不安定な5Gモバイルエッジネットワーク)をサーバーのネットワークインターフェースに適用します。
- クライアントマシン上(Elina-TGを実行): Elina-TGを使用して、サーバーに向けた現実的なアプリケーションワークロード(例:Zoom通話シミュレーション)を生成します。
この組み合わせにより、特定の、再現可能で現実的なネットワーク障害シナリオの下で、アプリケーションがどのようにパフォーマンスを発揮するかを正確に測定できます。
重要な注意事項
- 権限: ネットワークを変更するほぼすべての
elina-tcコマンドにはsudo権限が必要です。注: 上記の セットアップ のステップ5でelina-tcにパスワードなしのsudoを設定済みの場合、これは適用されません — パスワードの入力は求められません。 - 状態スナップショット: インターフェースを変更する前に、Elina-TCは既存の
tc設定を現在のディレクトリのタイムスタンプ付きログファイル(elina-tc_state_*.log)に自動的に保存し、監査証跡を提供します。 - クリーンアップ: Elina-TCは、終了または中断(
Ctrl+C)されたときに、すべてのルールと仮想デバイスを確実にクリーンアップするように設計されています。 - 同時実行: あるインターフェース(および共有の
ifb0デバイス)を同時に制御できるElina-TCの実行は1つだけです。2つ目の実行は、最初のものが終了するまで明確なエラーで拒否されます。ロックファイルはデフォルトで$TMPDIR/elina-tc-locks/に置かれます(上書きはELINA_TC_LOCK_DIR)。 - 詳細なドキュメント: 完全なコマンドラインリファレンス(
elina-tc -h)、エラーコード表、パッケージ内READMEについては、配布物に含まれるファイルを参照してください。
トラブルシューティング
| 症状 | 確認すること |
|---|---|
elina-tc: command not found |
仮想環境を有効化し(source venv/bin/activate)、which elina-tc でインストールを確認。必要ならパッケージルートで pip install .[ui] を再実行。 |
| Permission denied / 毎回パスワードを求められる | 適用モードには sudo が必要。Web UI(およびパスワードなしCLI)では、which elina-tc が返すフルパスで sudoers を設定。 |
プロファイル検証エラー(EC1004–EC1010) |
elina-tc --validate -f <file> を実行。よくある原因:単位の誤り(100 ではなく 100ms)、delay なしの jitter、loss なしの loss_correlation、0–100外のパーセント。報告されたインデックス/説明を修正して再検証。 |
不明なオンザフライパラメータ(EC1003) |
プロファイルパラメータ と同じキーを使用(例:delay 50ms loss 1%)。値は各キーの直後に置きます。 |
インターフェース使用中(EC3001) / 共有 ifb0 の競合 |
別のElina-TCプロセス(CLIセッションまたはWeb UIのApply)がまだロックを保持しています。先にそのセッションを終了またはクリア。強制終了後の古いロックは通常自動回収されます。ロックファイルは $TMPDIR/elina-tc-locks/。 |
tc / ip / modprobe 失敗(EC2001) |
Linuxで iproute2 が入っていること、インターフェース名が正しいこと(ip link)、ifb モジュールを読み込めること(sudo modprobe ifb)を確認。 |
測定RTTがプロファイルの delay の約2倍 |
想定どおり:シェーピングは対称です。delay: "50ms" は各方向に約50ms(RTT約100ms)を追加します。 |
| Web UIでApplyできない / 保存に失敗 | pip install .[ui]、sudoers設定、ホスト上でUIを開いていること(http://127.0.0.1:5000/)を確認。信頼できないネットワークに公開しないでください。 |
| クラッシュ後にルールが残る | sudo elina-tc -i <iface> --interactive clear を実行。通常は終了時または Ctrl+C でクリーンアップされます。 |
エラーには [EC2001] のような安定したコードが付きます。完全な表はパッケージ内の documentation/ERROR_CODES.md にあります。サポートへ連絡する際は、ECnnnn コードと実行したコマンドを含めてください。