追加のビルドエージェントの設定と実行

共通

エージェントプロセス（Java）は次のことを行う必要があります。

• buildAgent.properties ファイルの serverUrl プロパティで設定されたサーバー URL へのアウトバウンド HTTP 接続を開くことができる（通常は TeamCity UI を表示するためにブラウザーで使用するのと同じアドレス）。設定された URL のパスへのリクエスト送信は制限されるべきではありません。推奨リバースプロキシ設定も参照してください。エージェントマシンまたはサーバーマシンにインストールされているファイアウォール、ネットワーク構成、プロキシ（存在する場合）が、これらの要件に準拠していることを確認してください。

• 次のディレクトリに対する完全な許可（読み取り / 書き込み / 削除）を再帰的に持っている: <agent home> （自動エージェントアップグレードおよびエージェントツールのサポートに必要）、 <agent work> 、 <agent temp> 、エージェントシステムディレクトリ（ buildAgent.properties ファイルの workDir、tempDir、systemDir パラメーターによって設定）。

• （ビルドを実行するための）プロセスを起動できるようにします。

• 次の親プロセス出口でネストされたプロセスを起動できる（これはエージェントのアップグレード中に使用されます）。

Windows

• サービスとしてログオンします（Windows サービスとして実行します）。

• サービスの開始 / 停止（Windows サービスとして実行するには、エージェントのアップグレードが機能するために必要です。マイクロソフトサポート技術情報の記事(英語)も参照してください）。

• プログラムのデバッグ（プロセスダンプの取得機能に必要）。

• マシンを再起動します（エージェントの再起動機能に必要です）。

• Windows サービスとして実行されるビルドエージェントのパフォーマンスを監視できるようにするには、エージェントを開始するユーザーが Performance Monitor Users グループのメンバーである必要があります。

Linux

• ユーザーは、shutdown コマンドを実行できる必要があります（クラウド環境で実行している場合のエージェントマシンの再起動機能とマシンのシャットダウン機能の場合）。

• systemd を使用している場合は、メインプロセス出口でプロセスを強制終了しないでください（ RemainAfterExit=yes (英語) を使用）。Linux で自動エージェント起動を設定する方法も参照してください。

ビルド関連の権限

ビルドプロセスは TeamCity エージェントによって起動され、環境を共有し、TeamCity エージェントによって使用される OS ユーザーで実行されます。TeamCity エージェントがそれに応じて構成されていることを確認してください。関連する Windows サービスの制限については、既知の問題を参照してください。

単方向のエージェント間通信

エージェントは、ポーリングプロトコルを介した単方向のエージェント対サーバー接続を使用します。エージェントは TeamCity サーバーへの HTTP(S) 接続を確立し、サーバーコマンドについてサーバーを定期的にポーリングします。

エージェント間の通信には HTTPS を使用することをお勧めします（関連するサーバー構成に関する注意事項を確認してください）。エージェントとサーバーが安全な環境にデプロイされている場合、サーバーへの接続にプレーン HTTP URL を使用するようにエージェントを構成できます。これにより、転送のオーバーヘッドが削減されます。エージェントからサーバーに確立された接続を介して移動するデータには、ビルド設定、リポジトリアクセス資格情報とキー、リポジトリソース、ビルドアーティファクト、ビルド進行状況メッセージ、ビルドログが含まれることに注意してください。HTTP プロトコルを使用する場合、そのデータは「中間者」攻撃によって危険にさらされる可能性があります。

双方向通信

双方向通信は、エージェントとサーバー間の従来の接続であり、特に有効にする必要があります（以下の例を参照）。有効にすると、エージェントは HTTP（または HTTPS）経由でサーバーに接続し、サーバーは HTTP 経由でエージェントに接続する必要があります。

サーバーによって確立された接続を介してエージェントに転送されるデータは、セキュリティで保護されていない HTTP チャネルを介して渡されるため、サーバーとエージェント間のトラフィックをリッスンする可能性のあるサードパーティーに公開される可能性があります。さらに、エージェントとサーバーは「コマンド」を送信できるため、互いに、HTTP リクエストを送信してレスポンスをキャプチャーできる攻撃者は、理論的にはエージェントをだまして任意のコマンドを実行させ、セキュリティに影響を与える他のアクションを実行する可能性があります。

TeamCity エージェントが使用する通信プロトコルは、teamcity.agent.communicationProtocols サーバーの内部プロパティの値によって決まります。このプロパティは、コンマで区切られたプロトコルの順序付きリスト（polling および xml-rpc はサポートされているプロトコル名です）を受け入れ、デフォルトで teamcity.agent.communicationProtocols=polling に設定されています。複数のプロトコルが指定されている場合、エージェントはこのリストの最初のプロトコルを使用して接続を試み、失敗した場合はリストの 2 番目のプロトコルを介して接続を試みます。 polling は単方向プロトコル、xml-rpc - より古い双方向通信を意味します。

通信プロトコルの変更

• すべてのエージェントの通信プロトコルを変更するには、TeamCity サーバーの teamcity.agent.communicationProtocols サーバーの内部プロパティを設定します。新しい設定は、変更後にサーバーに接続するすべてのエージェントによって使用されます。既存の接続のプロトコルを変更するには、TeamCity サーバーを再起動します。

• デフォルトでは、エージェントのプロパティは設定されていません。エージェントが最初にサーバーに接続するとき、エージェントは TeamCity サーバーからそれを受信します。エージェントの初期設定後に個々のエージェントのプロトコルを変更するには、エージェントの特性の teamcity.agent.communicationProtocols プロパティの値を変更します。エージェントのプロパティはサーバープロパティをオーバーライドします。変更後、実行中のビルドがある場合は、終了するとエージェントが自動的に再起動します。

リモートホスト要件

リモートホストにはいくつかの要件があります。

インストール

1. TeamCity サーバーの WebUI で、エージェント | エージェントプッシュタブに移動し、エージェントをインストールをクリックします。
   複数のターゲットホストに同じ設定を使用する場合は、これらの設定でプリセットを作成し、エージェントを別のリモートホストにインストールするたびに使用できます。

2. エージェントのインストールダイアログで、保存されたプリセットを選択するか、カスタム設定を使用するを選択し、ターゲットホストプラットフォームを指定して、対応する設定を構成します。SSH を介した Linux システムへのエージェントプッシュは、SSH ポートパラメーターとして指定されたカスタムポート（デフォルトは 22）をサポートします。プリセットで指定されたポートは、実際のエージェントのインストール中に、ホスト名（たとえば、hostname.domain:2222 ）でオーバーライドできます。

3. Sysinternals psexec.exe をダウンロードする必要があるかもしれません。その場合は、対応する警告と、それをダウンロードできる管理 | ツールページへのリンクが表示されます。

Windows での自動エージェント起動

Windows のマシンブートでエージェントを自動的に実行するには、エージェントを Windows サービスとして実行するように設定するか、別の方法で自動プロセスを開始します。
Windows サービスアプローチを使用するのが最も簡単な方法ですが、Windows はこの方法で実行されるプロセスにいくつかの制約を適用します。
TeamCity エージェントは、すべての要件が満たされていれば、Windows サービスで確実に機能しますが、エージェントで実行するように構成されたビルドプロセスには当てはまらないことがよくあります。

そのため、すべてのビルドスクリプトがこれをサポートしている場合にのみ、TeamCity エージェントを Windows サービスとして実行することをお勧めします。それ以外の場合は、別の OS 固有の方法を使用して TeamCity エージェントを自動的に起動することをお勧めします。
1 つの方法は、Windows の起動時にユーザー(英語)の自動ログオン(英語)を構成してから、ユーザーのログオン（たとえば、Windows タスクスケジューラ(英語)を介して）で TeamCity エージェントの開始を（ agent.bat start を介して）構成することです。

Windows サービスとしてのエージェントの構築

Windows では、ユーザーがログオンしていなくても TeamCity エージェントを実行できるように、Windows サービスとして実行することをお勧めします。Windows エージェントインストーラーを使用する場合は、インストールウィザードでサービスをインストールするオプションがあります。

以下の手順を使用して、Windows サービスを手動でインストールすることができます（たとえば、.zip エージェントのインストール後）。この手順は、同じマシン上で 2 番目以降のエージェント用の Windows サービスを作成するためにも実行する必要があります。

サービスをインストールするには:

1. 必要な名前と ID を持つサービス（下記の #4 を参照、サービス名はデフォルトで TeamCity Build Agent です）が存在しないか確認してください。インストールされている場合は取り外します。

2. <agent home>\launcher\conf\wrapper.conf ファイルの wrapper.java.command プロパティに、JDK インストールディレクトリの Java 実行可能ファイルへの有効なパスが含まれていることを確認してください。Windows ディストリビューションとともにインストールされたエージェントには wrapper.java.command=../jre/bin/java を使用できます。引用符なしで java.exe ファイルのパスを指定してください。

3. "System" ではなく、ユーザーアカウント（推奨）でエージェントを実行する場合は、適切な資格情報を使用して wrapper.ntservice.account プロパティと wrapper.ntservice.password プロパティを <agent home>\launcher\conf\wrapper.conf ファイルに追加します。

4. （2 回目以降のインストールの場合） wrapper.console.title、wrapper.ntservice.name、wrapper.ntservice.displayname、wrapper.ntservice.description プロパティがコンピューター内で一意の値を持つように、<agent>\launcher\conf\wrapper.conf ファイルを変更します。

5. 新しいエージェントサービスを登録するのに十分な特権を持つユーザーで <agent home>\bin\service.install.bat スクリプトを実行します。説明されているように構成された後にのみ、初めてエージェントを開始するようにしてください。

サービスを開始するには

• 実行 <agent home>/bin/service.start.bat (または標準の Windows サービスアプレットを使用する)

サービスを停止するには

• 実行 <agent home>/bin/service.stop.bat (または標準の Windows サービスアプレットを使用する)

インストール後、標準の Windows net.exe ユーティリティを使用してサービスを管理することもできます。
例（デフォルトのサービス名を想定）:

<agent home>\launcher\conf\wrapper.conf ファイルを使用して、エージェントの JVM パラメーターを変更することもできます。

ビルドエージェントサービスを実行するために使用されるユーザーアカウントには、前述のように、エージェントサービスを開始または停止するのに十分な権限が必要です。

Linux での自動エージェント起動

Linux のマシンブートでエージェントを自動的に実行するには、デーモンプロセスを構成して agent.sh start コマンドで開始し、agent.sh stop コマンドで停止します。

systemd については、teamcityagent.service 設定ファイルの例を参照してください。

init.d の場合は、手順例を参照してください。

1. サービスの開始 / 停止サービススクリプトディレクトリに移動します。

2. ビルドエージェントサービススクリプトを開きます。

3. 以下をファイルに貼り付けます。

4. ファイルを実行する権限を設定します。

5. 適切なツールを使用して、マシンの起動時および再起動時にエージェントサービスを開始するリンクを作成します。

• Debian/Ubuntu の場合:

• Red Hat/CentOS の場合:

macOS での自動エージェント開始

macOS の場合、TeamCity はビルドユーザーがログインしたときに自動的にビルドエージェントをロードする機能を提供します。

LaunchAgent アプローチ:

LaunchAgent を介して自動ビルドエージェント起動を設定するには、次の手順に従います。

1. buildAgent.zip を介して Mac にビルドエージェントをインストールします。

2. conf/buildAgent.properties ファイルを準備します（少なくともそこにエージェント名を設定します）。

3. 適切なエージェントアップグレードプロセスを確保するために、buildAgent ディレクトリのすべてのファイルが your_build_user によって所有されていることを確認してください。

4. 次のコマンドでビルドエージェントをロードします。

your_build_user アカウントでこれらのコマンドを実行します。

ビルドエージェントが TeamCity サーバーから自動アップグレードするための数分待つ。ログでプロセスを見ることができます:

5. ビルドエージェントがアップグレードされ、TeamCity サーバーに正常に接続したら、エージェントを停止します。

6. ビルドエージェントを TeamCity サーバーからアップグレードした後、buildAgent/bin/jetbrains.teamcity.BuildAgent.plist ファイルを $HOME/Library/LaunchAgents/ ディレクトリにコピーします。ルート権限で TeamCity を起動したくない場合は、.plist ファイルで UserName キーを指定します。例:

7. ここで説明するように、ビルドユーザーとして自動的にログインするように Mac システムを構成します。

8. リブート。

システムの起動時に、ビルドユーザーは自動的にログインし、ビルドエージェントが起動します。

ビルドエージェントが実行されていることをすばやく確認するには、次のコマンドを使用します。