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

共通

エージェントプロセス（java）は

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

• 再帰的に以下のディレクトリーへのフルパーミッション（read / write / delete）を持つ: <agent home> （自動エージェントアップグレードおよびエージェントツールサポートに必要）、 <agent work> 、 <agent temp> 、およびエージェントシステムディレクトリー ( workDir , tempDirおよび buildAgent.properties ファイルの systemDir パラメーターで設定)

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

• 次の親プロセスでネストしたプロセスを起動できるようにする (これはエージェントのアップグレード中に使用されます)

Windows

• サービスとしてログオン (Windowsサービスとして実行する)

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

• デバッグプログラム (テイクプロセスダンプ機能に必要)

• マシンを再起動する (エージェントの再起動機能に必要)

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

Linux

• ユーザーは shutdown コマンドを実行できなければなりません (クラウド環境で運用している場合のエージェントマシン再起動機能およびマシンシャットダウン機能について)

• systemdを使用する場合、メインプロセス出口でプロセスを強制終了してはいけません (RemainAfterExit = yes(英語)を使用 )

ビルド関連の権限

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

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

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

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

双方向通信

双方向通信は、エージェントとサーバー間の従来の接続であり、特に有効にする必要があります。（以下の例を参照）。有効にすると、エージェントは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 プロパティーの値を変更します。エージェントのプロパティーはサーバープロパティーをオーバーライドします。変更後は、実行中のビルドが終了したときにエージェントが自動的に再起動します。

• バージョン2018.1+のTeamCityエージェントをバージョン9.1より前のTeamCityサーバーに接続する場合（アップグレード後のロールバック後など）、古いバージョンに接続できるようにするには、エージェントを更新して xml-rpc プロトコルを使用する必要があります。自己更新手順を実行するサーバー。

リモートホスト要件

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

インストール

1. TeamCityサーバーWeb UIで、エージェント | エージェントプッシュタブにナビゲートし、エージェントをインストールしています...をクリックします。
   複数のターゲットホストに同じ設定を使用する場合は、これらの設定でプリセットを作成し、エージェントを別のリモートホストにインストールするときに毎回使用することができます。

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起動時(英語)に自動ユーザーログオン(英語)を構成し、ユーザーログオン（たとえば、タスクスケジューラ(英語)経由）で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番目以降のインストールの場合） <agent>\launcher\conf\wrapper.conf ファイルを変更して、wrapper.console.title , wrapper.ntservice.name , wrapper.ntservice.displaynameおよび wrapper.ntservice.description プロパティーがコンピューター内で固有の値を持つようにします。

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/Mac OS Xの場合、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/ ディレクトリーにコピーします。

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

8. リブート。

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

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

Mac OSでセカンドビルドエージェントを設定する

複数のビルドエージェントを起動する場合は、次の変更を加えてビルドエージェントのインストールと起動の手順を繰り返します。

• 2番目のビルドエージェントを別のディレクトリーにインストールします。

• conf/buildAgent.properties で別のエージェント名を指定してください。

• buildAgent/bin/mac.launchd.shを実行しないでください: 代わりに

  • $HOME/Library/LaunchAgents/jetbrains.teamcity.BuildAgent.plist ファイルのコピーを $HOME/Library/LaunchAgents/jetbrains.teamcity.BuildAgent2.plistとして作成します。

  • $HOME/Library/LaunchAgents/jetbrains.teamcity.BuildAgent2.plist ファイルを編集して、以下のパラメータを設定します。

    • Label パラメーターを jetbrains.teamcity.BuildAgent2に設定

    • 2番目のビルド・エージェント・ホームへの正しいパスへの WorkingDirectory パラメーター

  • コマンド launchctl load $HOME/Library/LaunchAgents/jetbrains.teamcity.BuildAgent2.plistで2番目のエージェントを開始する

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