HULFT-WebConnect 設定ガイド【Agent方式の設定ポイント】（2/6）

# Agent方式の設定ポイント
こんにちは、よろず相談担当 すぎもんです。本日は、HULFT-WebConnectの設定方法のポイントについてご紹介します。
今回は2回目で、Agent方式の設定について解説いたします。

Agent方式はWebConnectの最も基本的な使い方で、通常のHULFT通信をインターネット経由にするだけになります。ですから、**従来ISDN経由でHULFTを利用していた場合はインターネット経由に簡単に切り替えられる**ので、ぜひ参考にしてください。


## Agent方式の特長
Agent方式は、Agentというモジュールから予めWebConnectサービスにTLSセッションを確立し、このTLSセッションを経由して双方のHULFT同士を通信させる仕組みです。WebConnectではAgent方式が最も基本的な接続方式で、どの転送方式も必ず通信の片側（管理者側のHULFT）がこの方式で接続します。

## 設定の流れ
設定箇所は、次の３ポイントを押さえる必要があります。
1. **WebConnectサービス**側の設定（Management Console）
2. **Agent**の設定（agent.conf/connection.key.store）
3. **HULFT**の設定（各種管理情報）
![005_Agent方式.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/5f6be99e-6ca7-5a5c-4a3d-5ff0ed3e9cc2.png)

ちなみに、Agent方式では管理者側の設定手順と利用者側の設定手順が同じになります。
下図は、前回も紹介したWebConnectのオンラインマニュアル（[ファーストステップガイド](https://www.hulft.com/help/ja-jp/WebConnect-V3/index.htm)）に記載のある設定の流れで、**赤枠**部分が今回の設定箇所です。同じ内容の**赤枠**が2箇所ありますが、どちらも同じ設定の手順になります。
![006_設定の流れ（Agent）.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/726a8b93-20cc-c3fa-1160-20d5a6a2e738.png)

## 設定の手順
![007_Agent方式（接続設定の全体イメージ）.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/a5683875-ec0e-4ba5-d1dc-8de112e1e9bc.png)


### Management Consoleの設定
1. コネクションIDの設定（接続設定）
**コネクションID**とは、各クライアント（Agent、CLI、Webブラウザ、D-Client）がWebConnectサービスに接続する際の認証に使われる設定です。要するに、ID/PWのIDがコネクションID、PWがコネクションパスワードになります。
クライアント種別は、Agent方式の場合**HULFTにチェック**します。
![008_MC_接続設定.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/0ca7e760-b834-8238-6610-19b79901eb70.png)

:::note warn
注意ポイント
コネクションIDはWebConnectサービス全体でユニークにする必要があります。
重複のないIDをご検討ください。
:::

2. ルーティングの設定（接続許可）
今回は、2つのコネクションIDをもつHULFT同士を相互に集配信させたいため、下図のように4つの中継許可設定を行います。
![009_MC_中継許可設定01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/e8536736-0d45-3b08-0296-a42b5e6ed860.png)

:::note alert
**注意ポイント**
中継許可は、各コネクションID毎に**配信**許可、**集信**許可を設定するものです。
そのため、片方のコネクションIDにだけ許可した場合、もう一方のコネクションIDには未登録なので中継が拒否されます。
必ず、**両方のコネクションIDに登録**してください。
:::

設定方法はシンプルで、自コネクションIDと相手コネクションID、転送の方向として配信か集信を選択するだけです。
![010_MC_中継許可設定02.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/dc42baf4-37e4-d93f-937f-fb3c62e2f434.png)

### Agentの設定

#### Agentモジュールのダウンロード
まず、Management ConsoleのダウンロードページからAgentモジュールを入手します。今回の導入環境は、Windows Server 2019なのでWindows x64版をダウンロードします。
![011_MC_Agentモジュールのダウンロード.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/87f5854e-e69a-de54-33df-e0e28537cf21.png)

#### Agentのインストール
インストール方法は、ダウンロードしたモジュール（zip）を展開するだけです。今回は、HULFT Family製品のデフォルトの導入先に展開します。
![012_Agentモジュールの展開.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/2746e8b7-f211-f03e-deae-e3e16f642b86.png)

#### Agentの設定
Agentは2つの設定ファイルで構成されています。
##### 1. agent.conf（Agent設定ファイル）
agent.confは、Agent識別子（**Agent ID**）、TCPポート番号、WebConnect接続情報、その他の動作設定などを行います。
下に記載のあるAgent.conf（サンプル）が、今回管理者側サーバのagent.confに設定した内容です。ここでは、詳細な設定内容はここでは割愛しWebConnectサービスへの接続に最低限必要なポイントを説明します。

**必ず変更が必要な設定**
| キー名 | 説明 |
|:-|:-|
|agent.id|Agent ID。WebConnectサービスがAgentをユニークに識別するための識別子。|

:::note warn
**注意ポイント**
コネクションID＋Agent IDの組み合わせがWebConnectサービス全体でユニークになる必要があります。
:::

**環境に応じて変更が必要な設定**

| キー名 | 説明 |
|:-|:-|
|connection.keystore.filepath|コネクションID認証ファイルのパス。このファイルにWebConnectサービスへ接続に必要な認証情報を設定する。（後述）|
|agent.sender.port|配信Agentの待受ポート。HULFTの詳細ホスト情報のPROXYポートNo.にこの値を設定する必要がある。|
|agent.command.port|コマンド用内部通信ポート。サーバ内部で利用するのみなのでシステム内で重複が無ければ良い。|

:::note info
これらの値は、特に変更する必要が無ければデフォルトのままでOKです。
:::

```agent.conf（サンプル）
agent.id=AG01（ユニークな値で任意に設定）
agent.sender.port=46000 （デフォルト値）
agent.command.port=1099（デフォルト値）
connection.keystore.filepath=./connection.keystore（デフォルト値）

service.accesspoint=service-ap.tokyo.webconnect.hulft.com
#proxy.host=
#proxy.port=
#proxy.username=
#proxy.password=
windows.service.startup.sender=on
windows.service.startup.receiver=on
update.action=alert
update.action.onError=continue
session.keepalive.interval=60000
session.management.reconnect.times=120
session.management.reconnect.interval=30
jvm.options=-Xms64M -Xmx256M
```

##### 2. connection.keystore（コネクションID認証ファイル）
WebConnectサービスに接続するための認証情報としてID/PWを記述するファイルです。
記述形式はシンプルで次の通りです。
　**コネクションID:コネクションパスワード**


```connection.keystore（サンプル）
CON-AG01:XXXX　（Management Consoleの接続設定で登録したコネクションパスワード）
```

#### Agentの起動
:::note info
AgentはJava上で動作するため、予めJava環境の導入が必要です。ここでは、Java導入方法については割愛します。
[HULFT-WebConnectの動作環境へのリンク](https://www.hulft.com/software/hulft-webconnect/os)
:::

##### 1. 環境変数（JAVA_HOME）の設定
Windows Server 2019 でのJava_HOMEの設定方法を一例として簡単に紹介します。

まず、**システムのプロパティ**->**詳細設定**タブを開きます。
![013_システムのプロパティ.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/6c5581c7-cfeb-482c-b795-649b64229bb2.png)

**環境変数**ボタンを押下します。
![014_環境変数.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/e486fa61-64ac-5b0f-1ef8-bb62c41663a8.png)

**システム環境変数**に**JAVA_HOME**のパスを設定します。今回は、AdoptOpenJDKのJDK11を設定します。
![015_システム変数の編集.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/8944cb32-f661-b209-3528-d095c5fac91e.png)

##### 2. Windowsサービスへの登録
Agentの起動方法はいくつかありますが、今回はWindowsサービスへ登録する方法を紹介します。
サービス登録には、下図のようにサービス登録用のツール **service.bat** を利用します。
![016_Agentサービス登録bat.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/b92f8ef8-c437-85bf-6fa0-d664d4aa09e9.png)

**Windowsサービス登録 コマンド実行例**
``` 
> cd \HULFT Family\webconnect-agent-2.3.1\bin （Agent導入先\bin ディレクトリに移動）
> service install HULFT-WebConnect-020301　（今回は、「HULFT-WebConnect-020301」というサービス名で登録）
```

##### 3. Agentの起動
サービスから**HULFT-WebConnect-020301**を開始します。
![017_サービス.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/f8329910-9bd6-05dc-9b57-4203241459e6.png)

Management Consoleから起動したAgentが表示されていれば正常に動作しています。
![018_Agent接続状況.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/cef2eb33-f4dc-feaf-bcb5-9192d55b932d.png)

:::note info
Agentは起動されると***常時WebConnectサービスとセッション（WebSocket）が確立されている状態***となります。このセッションがVPNと同様の働きをするため、相手側からファイル配信が来てもHULFTは通常の動きと同様にファイル受信することができます。
:::

:::note warn
AgentはWebConnectサービスに正常に接続できなかったときは異常終了するのでご注意ください。
:::

### HULFTの設定
実は、WebConnectの設定の考え方で一番難しいのがHULFTの設定になります。
HULFTの設定をシンプルにまとめると以下の2つの表（utlsendのとき、utlrecvのとき）になります。

#### HULFT設定のサマリ
##### 1. 配信要求（utlsend）を行う場合
|管理情報|配信側|集信側|
|:-|:-|:-|
|配信管理情報|通常の配信設定|-|
|集信管理情報|-|通常の集信設定|
|転送グループ情報|必要|-|
|詳細ホスト情報（ホスト名）|**集信側**のConID_AgID_Host(*1)|配信側のHost(*1)|
|詳細ホスト情報（PROXYサーバ名）|**配信側**AgentのHost(*1)|-|
|詳細ホスト情報（PROXYポートNo.）|**配信側**Agentのagent.sender.port（agent.confに定義）の値|-|

*1 ConID:コネクションID、AgID：Agent ID、Host：ホスト名
##### 2. 送信要求（utlrecv）を行う場合
|管理情報|要求受付（配信）側|送信要求（集信）側|
|:-|:-|:-|
|配信管理情報|通常の配信設定|-|
|集信管理情報|-|通常の集信設定|
|転送グループ情報|-|-|
|詳細ホスト情報（ホスト名）|**集信側**のConID_AgID_Host(*1)|**配信側**のConID_AgID_Host(*1)と**配信側**HULFTのHost(*1)の**両方の登録が必要**|
|詳細ホスト情報（PROXYサーバ名）|**配信側**AgentのHost(*1)|**集信側**AgentのHost(*1)|
|詳細ホスト情報（PROXYポートNo.）|**配信側**Agentのagent.sender.port（agent.confに定義）の値|**集信側**Agentのagent.sender.port（agent.confに定義）の値|

*1 ConID:コネクションID、AgID：Agent ID、Host：ホスト名

#### HULFT設定のポイント
サマリの表でもわかるとおり、**ポイントは詳細ホスト情報だけ**です。
理解しておくポイントは次の４つです。
　１．配信側が設定するのは、相手側の ConID_AgentID_Host
　２．送信要求側が設定するのも、相手側の ConID_AgentID_Host
　３．集信側が設定するは、相手側のHostのみ（通常のホスト設定）
　４．PROXY設定は、自分側Agentのホスト名＋ポート番号

:::note warn
注意点は、**集信側は通常のホスト設定**で良いというところです。
これは、配信側の詳細ホスト情報が**相手先ホストへの転送ルート（コネクションID＋AgentID＋HULFTホスト名＋PROXY）** を設定する必要があるのに対して、集信側は**相手先HULFTホスト名のチェック**しかしないためです。（集信AgentからHULFTにはホスト名しか通知されない）
:::

これをみて、「送信要求（utlrecv）の設定はもっと複雑になっていない？」といった突っ込みが有りそうですが、
HULFTの送信要求の仕組みは、
　・送信要求処理
　・配信処理
は全く別々の独立した処理として動作します。
送信要求（utlrecv）処理は、相手側HULFTに”配信処理を依頼する”だけです。送信要求を受け付けた相手側HULFTが代わりに配信要求（utlsend）を代行処理してくれる、といったイメージです。（正確には少し違いますが、このようにイメージすればここではOKです。）
ですから、**送信要求処理で1トランザクション**が終わり、**別トランザクションとして配信処理**が非同期に処理される、と理解した方がわかりやすい。

ですから、**送信要求処理では相手側のConID_AgentID_Hostが（相手先の接続ルートとして）必要**で、**集信処理として相手側のHost**と、２つの詳細ホスト情報が必要になります。
また、送信要求受付側はイコール配信側なので、配信側と同様の設定が必要になります。
このように理解すると、HULFT設定のサマリの表の内容と辻褄が合うと思います。

### 疎通確認

#### 1. 配信要求
通常のHULFTの操作で問題ありません。
HULFT管理画面からの配信要求でも、コマンド（utlsend）からでも問題ありません。

#### 2. 送信要求
**送信要求についてはWebConnect特有の操作が必要になるので注意が必要です。**

注意点は２つ。
* HULFT管理画面から実行できません。（エラーになります。）
* **WebConnect特有のutlrecvコマンドのお作法**が必須になります。

送信要求のやり方はutlrecvを用いますが、**引数の指定方法**に注意が必要です。
```
> utlrecv -f <FILEID> -h <ConID_AgID_Host> -msg0{{RCVCID:connectionID}}
```
FILEID:ファイルID
ConID_AgID_Host:詳細ホスト情報に登録した**相手側**のホスト名（コネクションID＋Agent ID＋HULFTホスト名）
connectionID:**自分側**のコネクションID

---
では、送信要求処理の実行例を見てみましょう。
##### 送信要求コマンドの実行
![019_utlrecv.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/bdcff092-52a2-dbea-eaa2-b2a5f6554a52.png)

##### 送信要求側（集信側）HULFTの集信状況一覧とコンソールログ
![020_集信状況一覧（utlrecv要求側）.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/d7d209bc-ee7a-19b8-df62-e521a79350a6.png)


##### 送信要求受付側（配信側）HULFTの配信状況一覧とコンソールログ
![021_配信状況一覧（utlrecv要求受付側）.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/75846e78-6fee-7d41-6618-457105959630.png)

---
以上、Agent方式の設定手順はご理解いただけたでしょうか？


---
**HULFT-WebConnect 設定ガイド** は、全6回のシリーズで順次公開予定です。

1. [４つの転送方式の違い](https://qiita.com/sugimon/items/1492714fb668e9a0c910)
2. **Agent方式の設定ポイント**（本記事）
3. [CLI方式の設定ポイント](https://qiita.com/sugimon/items/aed0713cf56dbd0de063)
4. [Webブラウザ方式の設定ポイント](https://qiita.com/sugimon/items/521ec99dc20e4cdb8730)
5. [D-Client方式の設定ポイント](https://qiita.com/sugimon/items/adbb055ae1208ed8143c)
6. [その他設定上の考慮ポイント](https://qiita.com/sugimon/items/0ffa6838d24650e8461f)

次回は、[CLI方式](https://qiita.com/sugimon/items/aed0713cf56dbd0de063)について解説いたします。

***
本記事は、[HULFT-WebConnect V3 マニュアル](https://www.hulft.com/help/ja-jp/WebConnect-V3/index.htm)を参考にしています。