Windows 向け Tunaclo Agent Service Tool プログラム(Front Agent / Back Agent)

Tunaclo AC で利用する Tunaclo Agent Service Tool の概要および利用方法について記載します。

Tunaclo Agent Service Toolとは

Tunaclo Agent Service Tool は、Windows OS 上で動作する、 Front Agent および、Back Agent を管理するツールです。

Tunaclo Agent Service Tool のアーキテクチャーは以下のとおりです。

Agent Service Tool のアーキテクチャー
Tunaclo Agent Service Tool には、以下の3つのツールが同梱されており、OS にインストールすることで Agent の起動・停止などを操作できるようになります。

Front Agent / Back Agent
Windows 版の Agent 。実際に通信を中継するためのバイナリプログラム。
Tunaclo Agent Service （tunaclo-agent-service.exe）
Front/Back Agent を Windows サービスとして動かすためのサービスプログラム
Agent Service Tool （tunaclo-ast.exe）
Windows サービスの作成・開始・表示などの管理を行うための CLI コマンド

※上記以外にも、インストーラーにより Windows OS 上に以下のファイルがインストールされます。

既定の証明書（default_https.crt / default_https.key）
Agent の設定ファイルテンプレート（front_agent_config_template.yaml / back_agent_config_template.yaml）
Tuanclo Agent Service Tool 自体の設定ファイル（settings.yaml）

Tunaclo AC を介した Web アプリとの通信は、 Agent がインターネット上のルーターと確立した HTTP/2 コネクションが利用されます。利用にあたっては、Agent Service Tool をインストールした端末からインターネット向けの HTTPS（ポート 443）通信ができることをご確認ください。

事前準備

Tunaclo portal の My profile ページの末尾にある Links のうち、

　Links
　　・Download Tunaclo Agent Service Tool Installer for Windows

をクリックしてダウンロードしてください。

Tunaclo Agent Service のインストール

Tunaclo Agent Service Tool は、Windows OS 上で動作する Tunaclo Agent ならびに、Agent を管理するコマンドを OS に Wizard 形式でインストールするアプリケーションツールです。ダウンロードした "tunaclo-ast-installer.zip"ファイルを任意の場所に展開し、展開した"tunaclo-ast-installer"フォルダの"tunaclo-ast-x.x.x.msi"ファイルをダブルクリックすることでインストールが開始されます。

マウス右クリックで「すべて展開(T)」を選択します
使用許諾契約書が表示されますので、内容を確認後、「□ I accept the terms in the License Agreement」にチェックを入れ、[Install]ボタンをクリックします。

インストール中に、OS のユーザーアカウント制御 (UAC) の画面「このアプリがデバイスに変更を加えることを許可しますか?」というメッセージが表示されるため、「はい」を選択してください。

インストールが完了すると、「Completed the Tunaclo Agent Service Tool Setup Wizard」と表示されますので[Finish]ボタンをクリックして、インストーラーを終了させてください。

Tunaclo Agent Service の管理

Tunaclo Agent Service Tool の利用方法について説明します。 Tunaclo Agent Service Tool には、Windows OS 上で動作する Tunaclo Agent（Front/Back）、Tunaclo Agent Service（tunaclo-agent-service.exe）ならびに、それらを管理する tunaclo-ast コマンドがまとめられています。

tunaclo-ast コマンドで動作可能な機能は以下のとおりです。これらのコマンドを実行するには、OS の管理者権限が必要です。コマンドプロンプトもしくは、Powershell を「管理者権限」で開いてから実行してください。

Tunaclo Agent 管理ツール(tunaclo-ast.exe)コマンド一覧

コマンド名	パラメータ	動作	備考
tunaclo-ast create	--config (agent のファイルパス名) --force --startType {manual\|auto}	Agent Service を Windows service として作成する	--startType のオプションは以下になります。 manual : 手動で Agent service を起動する必要があります。 auto : 自動で Agent service が起動します。
tunaclo-ast delete	--name (agent 名)	create コマンドで作成した Agent Service を削除する。もし指定された Agent Service が動作していた場合は停止後削除されます。
tunaclo-ast list	--name (agent 名)	現在登録されている Agent Service の一覧を表示します	パラメータを省略したときは登録されているすべての Agent の状態が、"--name (agent 名)" と入力すると、指定した Agent の状態が表示されます
tunaclo-ast start	--name　(agent 名)	create コマンドで作成した Agent Service を開始します
tunaclo-ast stop	--name　(agent 名)	指定した Agent Service を停止します
tunaclo-ast version	(なし)	ツールのバージョン情報を表示する
tunaclo-ast --help	(なし)	各コマンドの詳細を表示する

※ tunaclo-ast コマンドは、“tunaclo-ast (サブコマンド) -h” と入力すれば、各サブコマンドで利用できるパラメタや文法が表示できます。

インストール後、“tunaclo-ast version"と入力して以下のようにバージョン番号が出力されれば、インストールは成功です。

Agent サービスの管理・操作

以下、Tunaclo Agent Service Tool を介して Windows OS 上の Front/Back Agent を操作する手順を示します。Tunaclo Agent Service Tool（tunaclo-ast.exe コマンド）は、管理者権限でコマンドプロンプト、または、PowerShell を起動して操作してください。

サービスの登録

tunaclo-ast.exe コマンドの create サブコマンドを使用してサービスを登録します。

(コマンド詳細)

C:\>tunaclo-ast.exe create --help
create new agent service
Copyright 2021 FUJITSU LIMITED

Usage:
  tunaclo-ast.exe create [flags]

Flags:
      --config string      config file path of agent
      --force              erase previous agent data before creating service without prompt
  -h, --help               help for create
      --startType string   start type of agent service (manual or auto) (default "manual")

Global Flags:
      --debug            Show debug logs.
      --setting string   setting file path

(コマンド実行例)

C:\> tunaclo-ast create --config .\config_back.yaml --startType auto
Agent service ast-example was successfully created

※ tunaclo-ast create コマンドで Agent Service を作成する際、startType を指定しなかった場合はデフォルトで”manual”となります。

設定ファイル(config.yaml)のダウンロード

Tunaclo portal のルート一覧から接続先ルートを選択してください。

Front Agent として起動する場合は Client detail の Download config file ボタンをクリックし、Font Agent 用の設定ファイル（client_config.yaml）をダウンロードしてください。

Back Agent として起動する場合は Service detail の Download config file ボタンをクリックし、Back Agent 用の設定ファイル（service_config.yaml）をダウンロードしてください。

サービスの削除

tunaclo-ast.exe コマンドの delete サブコマンドを使用してサービスを削除します。

(コマンド詳細)

C:\>tunaclo-ast.exe delete --help
delete the agent service
Copyright 2021 FUJITSU LIMITED

Usage:
  tunaclo-ast.exe delete [flags]

Flags:
  -h, --help          help for delete
      --name string   name of the agent

Global Flags:
      --debug            Show debug logs.
      --setting string   setting file path

(コマンド実行例)

C:\> tunaclo-ast delete --name ast-example
Agent service ast-example was successfully deleted

サービスの状態表示

tunaclo-ast.exe コマンドの list サブコマンドを使用してサービスの状態を表示できます。

(コマンド詳細)

C:\>tunaclo-ast.exe list --help
list agent service info 
Copyright 2021 FUJITSU LIMITED

Usage:
  tunaclo-ast.exe list [flags]

Flags:
  -h, --help          help for list
      --name string   name of the agent

Global Flags:
      --debug            Show debug logs.
      --setting string   setting file path

(コマンド実行例)

C:\> tunaclo-ast list

Successfully get agent service list:
agentName          : ast-example
agentMode          : backAgent
agentStatus        : Stopped
agentConfigPath    : C:\ProgramData\Fujitsu\TunacloAC\agent-services\ast-example\config.yaml
agentLogDir        : C:\ProgramData\Fujitsu\TunacloAC\agent-services\ast-example
servicetName       : Tunaclo_ast-example
serviceStatus      : Stopped
serviceStartType   : Automatic
logLevel           : info
maxLogSize         : 20971520
logBackups         : 2

サービスの開始

tunaclo-ast.exe コマンドの start サブコマンドを使用してサービスを開始します。

(コマンド詳細)

C:\>tunaclo-ast.exe start --help
start agent service
Copyright 2021 FUJITSU LIMITED

Usage:
  tunaclo-ast.exe start [flags]

Flags:
  -h, --help          help for start
      --name string   name of the agent

Global Flags:
      --debug            Show debug logs.
      --setting string   setting file path

(コマンド実行例)

C:\> tunaclo-ast start --name ast-example
Agent service ast-example was successfully started
C:\> tunaclo-ast list

Successfully get agent service list:
agentName          : ast-example
agentMode          : backAgent
agentStatus        : Running
agentConfigPath    : C:\ProgramData\Fujitsu\TunacloAC\agent-services\ast-example\config.yaml
agentLogDir        : C:\ProgramData\Fujitsu\TunacloAC\agent-services\ast-example
servicetName       : Tunaclo_ast-example
serviceStatus      : Running
serviceStartType   : Automatic
logLevel           : info
maxLogSize         : 20971520
logBackups         : 2

サービスの停止

tunaclo-ast.exe コマンドの stop サブコマンドを使用してサービスを停止します。

(コマンド詳細)

C:\>tunaclo-ast.exe stop --help
stop agent service
Copyright 2021 FUJITSU LIMITED

Usage:
  tunaclo-ast.exe stop [flags]

Flags:
  -h, --help          help for stop
      --name string   name of the agent

Global Flags:
      --debug            Show debug logs.
      --setting string   setting file path

(コマンド実行例)

C:\> tunaclo-ast stop --name ast-example
Agent service ast-example was successfully stopped
C:\> tunaclo-ast list

Successfully get agent service list:
agentName          : ast-example
agentMode          : backAgent
agentStatus        : Stopped
agentConfigPath    : C:\ProgramData\Fujitsu\TunacloAC\agent-services\ast-example\config.yaml
agentLogDir        : C:\ProgramData\Fujitsu\TunacloAC\agent-services\ast-example
servicetName       : Tunaclo_ast-example
serviceStatus      : Stopped
serviceStartType   : Automatic
logLevel           : info
maxLogSize         : 20971520
logBackups         : 2

版数表示

tunaclo-ast.exe コマンドの version サブコマンドを使用して版数を表示できます。

(コマンド詳細)

C:\>tunaclo-ast.exe version --help
Print the version number of Tunaclo Agent Service.
Copyright 2021 FUJITSU LIMITED

Usage:
  tunaclo-ast.exe version [flags]

Flags:
  -h, --help   help for version

Global Flags:
      --debug            Show debug logs.
      --setting string   setting file path

(コマンド実行例)

C:\>tunaclo-ast.exe version
version: x.x.x
Copyright 2021 FUJITSU LIMITED

プロキシ環境での利用について

プロキシ環境での利用時は、Windows のシステム環境変数にて、HTTP_PROXY、HTTPS_PROXY の値をご利用のプロキシ環境に応じて適切に設定ください。

「コントロールパネル」-> 「システムとセキュリティ」->「システム」-> 「システムの詳細設定」-> 「環境変数」-> 「システム環境変数」-> 「新規」もしくは「編集」
HTTP_PROXY に利用しているプロキシ環境の HTTP_PROXY 設定値を入力
HTTPS_PROXY に利用しているプロキシ環境の HTTPS_PROXY 設定値を入力

Tunaclo Agent Service Tool のアンインストール

下記の手順でツールをアンインストールしてください。

起動中の Agent サービスがある場合はサービスの停止をもとにサービスを停止します。
コントロールパネルから「プログラム」-> 「プログラムのアンインストール」を選択します。
表示されるプログラム一覧から、Tunaclo Agent Service Tool のエントリを選択します。
右クリックして、「アンインストール」を選択します。
「Tunaclo Agent Service Tool をアンインストールしますか?」の画面が表示されるため、「はい」を選択します。
UAC（ユーザーアカウント制御）の画面が「このアプリがデバイスに変更を加えることを許可しますか?」というメッセージで表示されるため、「はい」を選択すれば、アンインストールが完了します。

※ Agent サービスの実行中にアンインストールしようとする場合、以下の画面が表示されます。「キャンセル」を選択し、アンインストールをキャンセルしてください。

アンインストールが中断されたら、サービスを停止し、再度アンインストールを実施してください。

Tunaclo Agent Service Toolのアップデート

下記の手順でツールをアップデートしてください。

基本的にインストールと同様の手順を実施します。

起動中の Agent サービスがある場合はサービスの停止をもとにサービスを停止します。
新しいバージョンの "tunaclo-ast-installer.zip"ファイルをダウンロードし、任意の場所に展開します。
展開した"tunaclo-ast-installer"フォルダの"tunaclo-ast-x.x.x.msi"ファイルをダブルクリックします。
使用許諾契約書の内容を確認後、「□ I accept the terms in the License Agreement」にチェックを入れ、[Install]ボタンをクリックします。
UAC（ユーザーアカウント制御）の画面が「このアプリがデバイスに変更を加えることを許可しますか?」というメッセージで表示されるため、「はい」を選択すれば、アップデートが開始されます。
アップデートが完了すると、「Completed the Tunaclo Agent Service Tool Setup Wizard」と表示されますので[Finish]ボタンをクリックして、インストーラーを終了させてください。

※ Agent サービスの実行中にアップデートしようとする場合、以下の画面が表示されます。「cancel」を選択し、アップデートをキャンセルしてください。

「Are you sure you want to cancel Tunaclo Agent Service Tool instllation?」と表示されるため、「Yes」を選択してください。

アップデートが中断されると、「Tunaclo Agent Service Tool Setup Wizard was interrupted」と表示されますので[Finish]ボタンをクリックして、インストーラーを終了させてください。

アップデートが中断されたら、サービスを停止し、再度アップデートを実施してください。

アップデート完了後は必要に応じて、サービスの開始をもとにサービスを開始してください。

トラブルシューティング

Tunaclo Agent Service Tool で問題が発生した際のチェック項目を記述します。その他の事例や Tunaclo AC サービスに関する FAQ はこちらを参照ください。

発生事象	説明
インストール時、『別のバージョンの製品が既にインストールされています』というエラーが発生する。	コントロールパネルの「プログラムのアンインストール」-> 「プログラムのアンインストールまたは変更」のメニューから、Tunaclo Agent Service Tool のエントリを選択し、右クリックから「アンインストール」-> 「はい」を選択して一旦古い版数のソフトをアンインストールします。
tunaclo-ast.exe list コマンド実行時、agentError の欄に以下のエラーが表示される。 Failed to initialize agent service: open C:\ProgramData\Fujitsu\TunacloAC\agent-services\サービス名\config.yaml: The system cannot find the file specified.	設定ファイルが消失しています。サービスの削除と再追加をお試しください。

エラーメッセージと対処法

以下、Tunaclo Connect Client で表示される主なエラーメッセージとその対処方法です。この他のメッセージが出た場合は、 Troubleshooting のページも参照ください。

　tunaclo-ast.exe コマンドを実行時した際に表示されるエラーメッセージ

エラーメッセージ	コマンド種別	原因	対処方法
Failed to get setting file: <ファイル名>	共通	setting オプションで指定されたファイルが存在しません	設定ファイルのファイルパスやファイル名に誤りがないかご確認ください。
Invalid settings was specified: <エラー詳細>	共通	設定ファイルに誤りがあります	設定ファイル（settings.yaml）の各パラメタと設定値が正しいか確認してください。
Invalid start type <サービス開始タイプ> is specified. Please set manual or auto	create	startType オプションの値に誤りがあります	startType オプションの指定値が正しいか確認してください。
Failed to parse a config file: <ファイル名>	create	設定ファイルの文字コード、もしくは形式に問題があります	設定ファイルの文字コードが UTF-8 であること、形式が YAML 形式であることを確認してください。
Specified config file has invalid option: <エラー項目一覧>	create	設定ファイルに誤りがあります	設定ファイルの各パラメタと設定値が正しいか確認してください。
Agent service <サービス名> is not installed	delete	指定したサービスが存在しません	name オプションの指定値が正しいか確認してください。
Agent service <サービス名> is not installed	start, stop	指定したサービスが存在しません	name オプションで指定したサービス名が正しいか確認してください。
Failed to start agent service <サービス名>: An instance of the service is already running.	start	指定したサービスは既に起動しています	list コマンドやサービス管理ツールでサービスの状態を確認してください。
Failed to stop agent service <サービス名>: service state was already changed	stop	指定したサービスは既に停止しています	list コマンドやサービス管理ツールでサービスの状態を確認してください。

list コマンドで出力される値の説明

list コマンドで出力される項目の意味は以下のとおりです。

パラメータ	説明	例
servicetName	サービス名	Tunaclo_connect-client
serviceStatus	サービスの状態	Running, Stopped など
serviceStartType	サービス起動時の設定	Automatic, Manual など
logLevel	ログレベル	info, またはdebug
maxLogSize	ログローテーション時の最大ログサイズ(バイト数単位)	20971520 (20MB)
logBackups	ログローテーション時に保持されるバックアップファイルの最大数	2
agentName	エージェント名	connect-client
agentType	エージェントタイプ	Front AgentもしくはBack Agent
agentStatus	エージェントの状態	Running、Stopped など
agentConfigPath	agent config ファイルのパス	C:\ProgramData\Fujitsu\TunacloAC\agent-services\connect-client\config.yaml
agentLogDir	agent log ファイルのディレクトリパス	C:\ProgramData\Fujitsu\TunacloAC\agent-services\connect-client
agentError	Agent サービスで発生したエラー内容を表示（エラーが起きた場合）	Failed to start the agent : exit status 2

ログの格納場所について

Front/Back Agent または Agent Service でエラーが発生した場合のログはログディレクトリに格納されています。
ログディレクトリの場所は、tunaclo-ast list コマンドのagentLogDir です。

Front/Back Agent　のログファイル: agent.log
Agent Service　のログ: ast.log

※ログファイルは、maxLogSize（デフォルト20MB）で別ファイルにアーカイブされ、logBackups　分過去のアーカイブを保持します。

※アーカイブファイル名には日付が付加されます。（例: agent-2021-01-21T04-34-41.182.log）

最終更新 Dec 3, 2021