Link Agent設定ファイル – mablヘルプ

コマンドラインでLink Agentの構成オプションを渡す方法に加えて、ファイルからLink Agentの構成オプションを渡すこともできます。コマンドラインでAPIキーを公開したくない場合や、単一のLink Agentで複数のLink Tunnelに対応したい場合は、Link Agentの構成ファイルが有効な選択肢です。

この記事では、Link エージェントの構成ファイルを使用する際に利用できるオプションをまとめています。

基本設定
任意の設定
サンプルテンプレート

基本設定

Link Agent の構成ファイルは、JSON または YAML 形式の場合があります。最低限、tunnels セクションには次の項目を含めてください。

apiKey - mabl アプリで作成した「Link Agent」API キー： Settings > APIs
name - 小文字の英字、数字、ダッシュで構成され、長さが1～24文字のリンクエージェント名。正規表現では、^[a-z0-9-]{1,24}$ に適合する必要があります。

{
   "tunnels": [
       {
           "apiKey": "apiKey1",
           "name": "name1"
       }
   ]
}

tunnels:
  - apiKey: my-api-key-1
    name: my-tunnel-name-1

複数の Link Tunnel を扱う場合や、プロキシ設定や接続フィルターを追加する場合など、Link エージェントの設定ファイルをカスタマイズする方法の詳細は、オプション設定のセクションをご覧ください。

構成ファイルで Link エージェントを起動するには、次の例のとおり、--config または -c オプションを使用します。

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

将来の構成ファイルの更新中も Link Tunnel をアクティブに保つには、Link エージェントを開始するときにコマンドラインオプション -R または --config-reload を渡します。例:

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

自動リロード設定をリンクエージェントの設定ファイルと併用すると、エージェントはそのファイルの変更を自動で監視し、変更を検出すると適用します

任意の設定

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

複数の Link Tunnel の運用
静的プロキシ設定
プロキシ自動構成（PAC）ファイル
接続フィルター
自動更新を無効にする

複数の Link Tunnel の運用

複数のトンネルを1つの設定ファイルにまとめると、管理が必要な固有の Link エージェントインスタンスの数を減らせます。複数の低トラフィックのトンネルがある場合に便利です。

サービスしたい追加の Link Tunnel ごとに、構成ファイルの tunnels セクションに、apiKey と name を含むエントリを追加してください。

同じ mabl ワークスペースに関連付けられているトンネルは、同じ「Link Agent」API キーを使用できます。
異なる mabl ワークスペースに関連付けられているトンネルは、それぞれのワークスペースの「Link Agent」APIキーを使用してください。

次の JSON および YAML の例は、2 つの Link Tunnel を提供する構成ファイルを示します。

{
   "tunnels": [
       {
           "apiKey": "apiKey1",
           "name": "name1"
       },
       {
            "apiKey": "apiKey2",
            "name": "name2"
        }
    ]
}

tunnels:
  - apiKey: my-api-key-1
    name: my-tunnel-name-1
  - apiKey: my-api-key-2
    name: my-tunnel-name-2

複数のトンネルを組み合わせると、パフォーマンスと安定性に影響する可能性があります

同じリンクエージェントで処理するトラフィック量を増やすと、必要なメモリや CPU が増える場合があります。複数のトンネルを同一のリンクエージェントインスタンスにまとめる場合は、次のアプローチをおすすめします。

Link Agentが動作しているホストのベースラインの使用量を把握します。
トンネルは一度に1つずつ追加します。
各トンネルを追加した後、エージェントのログでエラーを確認し、ホストのメモリ使用量とCPU使用率がベースラインに対してどう変化するかを観察してください。正確に測定するには、管理対象のすべてのトンネルでテストが稼働している間、ホストを監視してください。
必要な場合は、JVMに利用できるメモリを増やします。

静的プロキシ設定

ネットワークでフォワードプロキシを使用している場合は、プロキシ設定を含めて、送信するリンクトラフィックが mabl リンクサービスに正しくルーティングされるようにしてください。

httpProxy - （必須）接続先のプロキサーサーバーのホスト
proxyAuth - プロキシサーバーが認証を必要とする場合は、ユーザー名とパスワードを入力してください
proxyMode - どのトラフィックでプロキシを使用するかを指定します。既定値は mabl です。
proxyExclusions - 特定のIPアドレス、CIDRレンジ、ホスト、またはドメインをバイパスするように、送信のmabl リンクのトラフィックを設定します。

これらのプロパティの詳細は、mabl リンクのトラフィック向けフォワードプロキシに関する記事をご覧ください。

次の JSON および YAML の例は、静的プロキシ設定を Link エージェントの構成ファイルに組み込む方法を示します。

{
   "httpProxy": {
       "host": "host",
       "port": 1234
   },
   "proxyAuth": {
       "password": "password",
       "username": "username"
   },
   "proxyExclusions": [
       "localhost",
       "127.0.0.1"
   ],
   "proxyMode": "all"
}

httpProxy:
  host: host
  port: 1234
proxyAuth:
  password: my-proxy-password
  username: my-proxy-username
proxyExclusions:
  - localhost
  - 127.0.0.1
proxyMode: all

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

組織でプロキシ設定の構成に PAC ファイル／スクリプトを使用している場合は、その PAC 設定を Link エージェントの構成ファイルに追加できます。構成ファイルに PAC 設定を追加する際は、静的なプロキシ設定を同時に構成しないようにしてください。 httpProxy、proxyAuth、および proxyExclusions の設定は、proxyAutoConfiguration の設定を追加する前に削除する必要があります。

最低限、PAC には URL を含める必要があります。PAC ファイルの設定には、次の項目が含まれます。

url - 通常は http:// 形式のURLです。ローカルファイルシステム上のファイルからPACスクリプトを読み込みたい場合は、file:// 形式のURLを使用できます。例: file:///opt/mabl/link-agent/[pac.js](http://pac.js)。
auth: 認証が必要なプロキシサーバーがある場合は、認証が必要なプロキシごとにauthエントリを追加します。各認証情報設定に対するプロキシは、ホスト名とポートの両方を含む形式で、PACスクリプトで返されるとおりに指定する必要があります。例: proxy.example.com:8080
reloadPeriodMinutes: この設定は、Link エージェントが PAC を再読み込みする頻度を決めます。接続の待ち時間を抑えるため、Link エージェントは接続のたびに PAC を再読み込みしません。代わりに、バックグラウンドで定期的に PAC を再読み込みします。多くの場合、PAC は頻繁に変更されないため、数分ごとに再読み込みするだけでも安全です。既定では、PAC を毎分 1 回再読み込みします。

次の JSON と YAML の例は、PAC 設定を Link エージェントの構成ファイルに組み込む方法を示します。

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

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

PACを使用するようにLink Agentを設定すると、proxyModeの設定は無視されます。これは、プロキシを使用するURLと、直接接続を行うURLが、PACスクリプトによって確定するためです。

接続フィルター

接続フィルターを使用すると、Link エージェントが接続を許可されるホストを制限できます。接続フィルターは、必須のセキュリティ要件やコンプライアンス要件を満たす必要がある場合など、本当に必要なときにのみ推奨されます。テスト対象のアプリケーションで依存するリソースへの接続が接続フィルターによってブロックされると、mabl のテスト実行でエラーが発生する可能性があります。

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

可能な接続モードは次の三つです:

allow: Linkエージェントは、フィルターに一致するターゲットにのみ接続できます
deny: リンクエージェントは、フィルターに一致するターゲットを除くすべてのターゲットへの接続が許可されます
disabled: 接続フィルターは無効です。主にデバッグ目的で使用し、設定を削除せずにフィルターのオン／オフを切り替えられます

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

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

次の JSON と YAML の例では、接続フィルターを Link エージェントの構成ファイルに組み込む方法を示します。

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

connectionFilter:
  mode: deny
  destinations:
  - example.com
  - 10.0.0.0/8:22
  - 127.0.0.1
  - :80

ホストの宛先は、単一のIPアドレス、CIDRブロック、またはFQDNのサフィックスで指定できます。次の表に、サポートされるホスト表現の例を示します。

式	マッチングの例	不一致の例
単一の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
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

自動更新の無効化

mabl リンクのエージェントは、常に最新の追加、変更、修正を取り込んで実行できるよう、自動的に更新されます。自動更新を無効にするには、disableAutoUpdates 設定を追加し、true に設定してください。

{
   "disableAutoUpdates": true
}

disableAutoUpdates: true

サンプルテンプレート

独自の Link エージェントの構成ファイルを設定するときは、次の包括的なテンプレートをガイドとして使用できます。Link エージェント配布物の config ディレクトリには、サンプルの構成ファイルもあります: config.example.json と config.example.yaml。

{
   "disableAutoUpdates": false,
   "httpProxy": {
       "host": "host",
       "port": 1234
   },
   "proxyAuth": {
       "password": "password",
       "username": "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": "apiKey1",
           "name": "name1"
       },
       {
           "apiKey": "apiKey2",
           "name": "name2"
       }
   ]
}

disableAutoUpdates: false
httpProxy:
  host: host
  port: 1234
maxConnectionAttempts: 1
proxyAuth:
  password: my-proxy-password
  username: my-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: my-api-key-1
    name: my-tunnel-name-1
  - apiKey: my-api-key-2
    name: my-tunnel-name-2