メインコンテンツへスキップ

Link Agent設定ファイル

Eva Ferreira
  • 更新

Link Agentのオプションは、コマンドラインで渡すだけでなく、設定ファイルにまとめておくこともできます。設定ファイルを使用すると、APIキーをコマンドラインに含めずに済み、1つのLink Agentで複数のトンネルを処理でき、エージェントの実行中にトンネルや設定を変更できます。

この記事では、Link Agent設定ファイルで利用できるオプションについて説明します。

WindowsインストーラーとLinuxおよびmacOSのインストーラーは、インストール時の回答をもとに設定ファイルを作成します。作成されたファイルは、後から同じ方法で編集できます。

基本設定

Link Agent設定ファイルは、JSON形式またはYAML形式で記述できます。エージェントはファイルの拡張子から形式を判断します。.yamlまたは.ymlで終わるファイルはYAMLとして、.jsonで終わるファイルを含むそれ以外のファイルはJSONとして読み込まれます。tunnelsセクションには、トンネルごとに少なくとも次の項目を含めてください。

  • apiKey - mablアプリのSettings > APIsで作成した「Link Agent」APIキー
  • name - 小文字の英字、数字、ダッシュで構成される、1～24文字のトンネル名。正規表現で表すと、名前は^[a-z0-9-]{1,24}$に一致する必要があります。
{
   "tunnels": [
       {
           "apiKey": "{your-api-key}",
           "name": "qa-env-01"
       }
   ]
}

tunnels:
  - apiKey: {your-api-key}
    name: qa-env-01

設定ファイルを指定してLink Agentを起動するには、--configまたは-cオプションを使用します。

bin/link-agent --config /path/to/config.json
# or:
bin/link-agent -c /path/to/config.yaml

Link Agentは起動時にAPIキーとトンネル名を確認し、使用できないものがあれば、無期限に再試行するのではなくその旨を報告します。よくある原因は、サンプルからコピーしたファイルにプレースホルダーの値が残っていることです。

エージェントの実行中に設定を変更する

設定ファイルを指定して起動したLink Agentは、そのファイルを監視し、実行中に変更を適用します。そのため、エージェントを再起動する必要はありません。

  • 追加したトンネルは、すぐに接続されます。
  • 削除したトンネルは、新しい接続の受け付けを停止し、現在の接続を完了させるため、すでにそのトンネルを通じて実行中のテストは中断されません。その後、エージェントをシャットダウンするか、mablアプリでトンネルを削除するまで待機します。
  • プロキシ設定、接続フィルター、ログレベルの変更は、実行中のトンネルに適用されます。

変更したファイルを読み取れない場合や無効な設定が含まれている場合、Link Agentは問題をログに記録し、以前の設定で実行を続けます。

監視はデフォルトでオンになっています。オフにするには、--no-config-reloadを付けてエージェントを起動します。-Rおよび--config-reloadオプションも引き続き使用できますが、指定する必要はなくなりました。

任意の設定

次の構成や要件に対応するために、Link Agent設定ファイルをさらにカスタマイズできます。

複数のトンネルを1つの設定ファイルにまとめると、管理するLink Agentの数を減らせます。追加するトンネルごとに、tunnelsセクションにapiKeyとnameを含むエントリを追加してください。

  • 同じmablワークスペースに属するトンネルは、同じ「Link Agent」APIキーを使用できます。
  • 異なるワークスペースに属するトンネルは、それぞれのワークスペースの「Link Agent」APIキーを使用します。
  • 会社トンネルには、会社の「Link Agent」APIキーを使用します。会社トンネルとワークスペーストンネルは同じ名前を共有することもでき、この仕組みを使うと、環境を編集せずにワークスペーストンネルを会社に移行できます。

次のJSONとYAMLの例は、2つのトンネルを処理する設定ファイルを示しています。

{
   "tunnels": [
       {
           "apiKey": "{your-api-key-1}",
           "name": "qa-env-01"
       },
       {
           "apiKey": "{your-api-key-2}",
           "name": "staging-01"
       }
   ]
}

tunnels:
  - apiKey: {your-api-key-1}
    name: qa-env-01
  - apiKey: {your-api-key-2}
    name: staging-01

トンネルを追加するごとに、Link Agentのホストに必要なメモリとCPUが増えます。トラフィックの多いトンネルを1つのエージェントにまとめる前に、Link Agentのサイジングとスケーリングを参照してください。

担当者

pointOfContactに、組織内でLink Agentを保守する担当者またはチームを、メールアドレスやチーム名などで設定します。この値はワークスペース > ネットワークのエージェントの詳細に表示されるため、エージェントの問題に気づいた人が誰に連絡すればよいかがわかります。

{
   "pointOfContact": "qa-platform-team@example.com"
}

pointOfContact: qa-platform-team@example.com

静的プロキシ設定

ネットワークでフォワードプロキシを使用している場合は、送信するLinkトラフィックがmablに届くように、プロキシ設定を含めてください。

  • httpProxy - （必須）プロキシサーバーのhostとport
  • proxyAuth - プロキシサーバーで認証が必要な場合は、usernameとpassword
  • proxyMode - プロキシを使用するトラフィック。mabl、all、upstream、none、autoのいずれか
  • proxyExclusions - 送信するLinkトラフィックがプロキシを経由せずに直接接続するIPアドレス、CIDRレンジ、ホスト、またはドメイン

設定ファイルにプロキシ設定がまったくない場合、Link Agentはホストのオペレーティングシステムのプロキシ構成に従います。PACスクリプトが構成されている場合は、それも含まれます。ホストにプロキシが構成されていても直接接続するには、proxyModeをnoneに設定します。

これらのプロパティの詳細については、mabl Linkトラフィックのフォワードプロキシを参照してください。

次のJSONとYAMLの例は、静的プロキシ設定を設定ファイルに含める方法を示しています。

{
   "httpProxy": {
       "host": "proxy.example.com",
       "port": 8080
   },
   "proxyAuth": {
       "password": "{proxy-password}",
       "username": "{proxy-username}"
   },
   "proxyExclusions": [
       "localhost",
       "127.0.0.1"
   ],
   "proxyMode": "all"
}

httpProxy:
  host: proxy.example.com
  port: 8080
proxyAuth:
  password: {proxy-password}
  username: {proxy-username}
proxyExclusions:
  - localhost
  - 127.0.0.1
proxyMode: all

プロキシ自動構成（PAC）ファイル

組織でPACファイルを使用してプロキシ設定を構成している場合は、PAC設定を設定ファイルに追加します。静的プロキシ設定とは組み合わせないでください。proxyAutoConfigurationを追加する前に、httpProxyとproxyExclusionsを削除してください。

PAC設定には、少なくともURLを含める必要があります。

  • url - 通常はhttp://形式のURLです。代わりにローカルファイルシステムからPACスクリプトを読み込むには、file://形式のURLを使用します。例: file:///opt/mabl/link-agent/pac.js
  • auth - 認証が必要なプロキシサーバーがある場合は、プロキシごとに個別のエントリを追加します。各プロキシは、PACスクリプトが返すとおりに、ホスト名とポートの両方を含めて指定してください。例: proxy.example.com:8080
  • reloadPeriodMinutes - Link AgentがPACを再読み込みする頻度。接続を高速に保つため、エージェントは接続のたびにPACを再読み込みしません。代わりにバックグラウンドで再読み込みし、デフォルトでは1分に1回です。

次のJSONとYAMLの例は、PAC設定を設定ファイルに含める方法を示しています。

{
 "proxyAutoConfiguration": {
   "auth": {
     "proxy1.example.com:8080": {
       "username": "{proxy-username-1}",
       "password": "{proxy-password-1}"
     },
     "proxy2.example.com:8080": {
       "username": "{proxy-username-2}",
       "password": "{proxy-password-2}"
     }
   },
   "reloadPeriodMinutes": 5,
   "url": "http://proxy.example.com/pac.js"
 }
}

proxyAutoConfiguration:
  auth:
    proxy1.example.com:8080:
      username: {proxy-username-1}
      password: {proxy-password-1}
    proxy2.example.com:8080:
      username: {proxy-username-2}
      password: {proxy-password-2}
  reloadPeriodMinutes: 5
  url: http://proxy.example.com/pac.js

PACを使用するようにLink Agentを設定した場合、proxyModeを自分で設定しない限り、エージェントはすべてのトラフィックをPACの判定に従って送信します。プロキシを使用するURLと直接接続するURLは、PACスクリプトによって決まるためです。

接続フィルター

接続フィルターを使用すると、Link Agentが接続できるホストを制限できます。接続フィルターは、必須のセキュリティ要件やコンプライアンス要件を満たす場合など、必要なときにのみ使用してください。アプリケーションが依存するリソースへの接続が接続フィルターによってブロックされると、mablのテスト実行が失敗する可能性があります。

接続フィルターには、modeとdestinationsの2つの設定が必要です。

指定できるモードは次の3つです。

  • allow: Link Agentは、フィルターに一致するターゲットにのみ接続できます
  • deny: Link Agentは、フィルターに一致するターゲットを除くすべてのターゲットに接続できます
  • disabled: 接続フィルターは無効です。主にデバッグ用のオプションで、設定を削除せずにフィルターのオン／オフを切り替えられます

宛先は、接続フィルターの対象を表します。宛先は、ホスト式、ポート、またはその両方を使用して、次のいずれかの形式で指定できます。

  • ホストのみ: [host-expression]
  • ポートのみ: :[port]
  • ホストとポート: [host-expression]:[port]

次のJSONとYAMLの例は、接続フィルターを設定ファイルに含める方法を示しています。

{
  "connectionFilter": {
    "mode": "deny",
    "destinations": [
      "example.com",
      "10.0.0.0/8:22",
      "127.0.0.1",
      "[2001:db8::1]:443",
      ":80"
    ]
  }
}

connectionFilter:
  mode: deny
  destinations:
  - example.com
  - 10.0.0.0/8:22
  - 127.0.0.1
  - "[2001:db8::1]:443"
  - :80

ホストの宛先には、単一のIPアドレス、CIDRブロック、またはFQDNサフィックスを指定できます。IPv6アドレスとIPv6のCIDRブロックにも対応しています。IPv6アドレスにポートを付けるには、アドレスを角かっこで囲みます。次の表に、サポートされるホスト式の例を示します。

式 一致する例 一致しない例
単一のIPアドレス 10.1.2.3 10.1.2.3 10.1.2.4, 10.0.0.1
CIDRブロック 10.0.0.0/8 10.1.2.3, 10.24.36.200 11.1.2.3, 192.168.1.1
IPv6 CIDRブロック 2001:db8::/32 2001:db8::1, 2001:db8:1::5 2001:db9::1
FQDNサフィックス（ドメイン） example.co example.co, www.example.co example.com, example.co.uk
特定のFQDN www.example.com www.example.com, 1.www.example.com www1.example.com, api.example.com

自動アップデートの無効化

Link Agentは、起動するたびに新しいバージョンがあるかを確認します。新しいバージョンがある場合、エージェントはトンネルを接続する前にそのバージョンをインストールし、新しいバージョンで再起動します。実行中のエージェントは、ネットワークの中断後に再接続した場合も含め、再度確認することはありません。そのため、長期間実行しているエージェントが新しいバージョンを取り込むのは、サービスやホストを再起動したときなど、次に起動したときだけです。待たずに最新バージョンをインストールするには、今すぐアップデートをインストールするを参照してください。

mabl link-agents startが実行するLink Agentはmabl CLIの一部であり、自動ではアップデートされません。アップデートするには、新しいバージョンのmabl CLIをインストールしてください。

自動アップデートをオフにするには、disableAutoUpdatesをtrueに設定します。アップデートを自分でインストールする方法については、Link Agentのメンテナンスとアップデートを参照してください。

{
   "disableAutoUpdates": true
}

disableAutoUpdates: true

シャットダウン時の完了処理のタイムアウト

Link Agentは停止する際、処理中の接続を先に完了させます。接続の完了を待つ時間を制限するには、shutdownDrainTimeoutSecondsに秒数を設定します。

非推奨の設定

connectionsとmaxConnectionAttemptsの設定は、レガシーLinkプロトコルにのみ適用されます。Link 3.0ではこれらの設定は無視され、設定されている場合はLink Agentが通知をログに記録します。今後のリリースで削除される予定のため、設定ファイルから削除してください。レガシーLinkからLink 3.0への移行を参照してください。

mabl CLIでの設定ファイルの使用

mabl link-agents startも同じ設定ファイルを読み込みます。ただし、このLink AgentはPAC設定とautoプロキシモードに対応していないため、ネットワークでこれらが必要な場合は、ほかのインストール方法を使用してください。

サンプルテンプレート

独自のLink Agent設定ファイルを作成する際は、次のテンプレートを参考にしてください。Link Agentの配布物のconfigディレクトリにも、config.example.jsonやconfig.example.yamlなどのサンプル設定ファイルがあります。

{
   "pointOfContact": "qa-platform-team@example.com",
   "disableAutoUpdates": false,
   "httpProxy": {
       "host": "proxy.example.com",
       "port": 8080
   },
   "proxyAuth": {
       "password": "{proxy-password}",
       "username": "{proxy-username}"
   },
   "proxyExclusions": [
       "localhost",
       "127.0.0.1"
   ],
   "proxyMode": "all",
   "connectionFilter": {
       "mode": "deny",
       "destinations": [
           "example.com",
           "10.0.0.0/8:22",
           "127.0.0.1",
           ":80"
        ]
   },
   "tunnels": [
       {
           "apiKey": "{your-api-key-1}",
           "name": "qa-env-01"
       },
       {
           "apiKey": "{your-api-key-2}",
           "name": "staging-01"
       }
   ]
}

pointOfContact: qa-platform-team@example.com
disableAutoUpdates: false
httpProxy:
  host: proxy.example.com
  port: 8080
proxyAuth:
  password: {proxy-password}
  username: {proxy-username}
proxyExclusions:
  - localhost
  - 127.0.0.1
proxyMode: all
connectionFilter:
  mode: deny
  destinations:
  - example.com
  - 10.0.0.0/8:22
  - 127.0.0.1
  - :80
tunnels:
  - apiKey: {your-api-key-1}
    name: qa-env-01
  - apiKey: {your-api-key-2}
    name: staging-01

関連記事