> For AI agents: the complete documentation index is available at /resource/ucidm/docs/on-premise/dev/llms.txt, the full documentation bundle is available at /resource/ucidm/docs/on-premise/dev/llms-full.txt.

# Windowsサーバーコマンド連携手順 \{#winrm}

UCIDMのconsumerコンテナにはWinRM接続を行うためのPythonライブラリ [pywinrm](https://pypi.org/project/pywinrm/) がインストールされています。
設定を行うことで、UCIDMからWindowsサーバーへコマンド連携が可能になります。
WinRMではいくつかの認証方式で接続できますが、ここではkerberos認証を使ってWindowsサーバーへ、WinRM接続する設定手順を説明します。

# 前提条件 \{#prerequisites}

設定手順を説明するにあたって、以下の条件を前提とします。

- UCIDMがインストール・設定済みであること
- WindowsサーバーにてActiveDirectoryがインストール・設定済みであること
- UCIDMインストール済みサーバーからWindowsサーバーへ通信が可能であること
  - TCP/5985 (HTTP)

# 設定手順概要 \{#overview}

設定手順はおおまかに以下の手順になります。
設定には接続元になるUCIDMサーバーと、接続先になるWindowsサーバーの両方で作業が必要になります。

1. kerberosの設定
2. pythonスクリプトの作成
3. UCIDMの設定

## kerberosの設定 \{#kerberos}

kerberos認証を行うために、Kerberosの設定を行います。
kerberos認証には認証情報を含めたkeytabファイルを利用します。
keytabファイルの作成はWindowsサーバー側で行います。

### Windowsサーバー側の設定 \{#windows}

Windowsサーバー側での設定手順は以下の通りです。

1. 接続用アカウントの作成
2. keytabファイルの作成

また以下の情報が必要になるので、事前に確認してください。

- ActiveDirectoryのドメイン名 (例: EXAMPLE.COM)
  - PowerShell上 `Get-ADDomain | select Forest` コマンドで確認出来ます
- Windowsサーバーのホスト名 (例: WIN-SERVER)
  - PowerShell上 `hostname` コマンドで確認出来ます

#### 接続用アカウントの作成 \{#create-account}

winrm接続用のアカウントをActiveDirectoryに作成します。
ユーザー名とパスワードは特に制約はありません。
ここでは `winrm / password` とします。

作成したユーザーは `Administrators` グループに所属させてください。

#### keytabファイルの作成 \{#create-keytab}

keytabファイルは `ktpass` というコマンドで作成します。
Windowsサーバー上でPowerShellを起動し、以下のコマンドを実行してください。

```powershell
ktpass -princ <プリンシパルネーム> -mapuser <接続用ユーザー名> -pass * -crypto AES256-SHA1 -out <keytabファイル名>
```

ここで、各パラメータは以下の通りです。

- プリンシパルネーム: `HTTP/<Windowsサーバーのホスト名>@<Active Directoryのドメイン名>` という形式になります。
- 接続用ユーザー名: 先ほど作成した接続用アカウントのユーザー名
- keytabファイル名: 作成するkeytabファイルの名前を指定します。ここでは `winrm-<ドメイン名>.keytab` とします。

例として、ドメイン名が `EXAMPLE.COM`、Windowsサーバーのホスト名が `WIN-SERVER`、接続用アカウントが `winrm` の場合、以下のようになります。

```powershell
ktpass -princ HTTP/WIN-SERVER@EXAMPLE.COM -mapuser winrm -pass * -crypto AES256-SHA1 -out winrm-example.com.keytab
```

コマンドを実行するとパスワードの入力を求められるので、接続用アカウントのパスワードを入力してください。

コマンド実行後keytabファイルが作成されるので、UCIDMサーバーに転送します。
機密情報を含むので、慎重に取り扱ってください。

### UCIDMサーバー側の設定 \{#ucidm}

UCIDMサーバー側での設定手順は以下の通りです。

1. kerberosの設定ファイルの作成・配置
2. keytabファイルの配置
3. composeファイルの編集

#### kerberosの設定ファイルの作成・配置 \{#create-krb5}

kerberosの設定ファイルを作成します。

winrmに関連するファイルをまとめるために、`/opt/osstech/var/lib/ucidm/krb5/` というディレクトリを作成します。

kerberosの設定ファイルは `/opt/osstech/var/lib/ucidm/krb5/winrm.conf` というパスに作成します。
以下は設定ファイルの例です。

```ini
[libdefaults]
default_client_keytab_name = /etc/winrm.keytab

[realms]
EXAMPLE.COM = {
  kdc = win-server.example.com
  admin_server = win-server.example.com
}
```

`[realms]` セクションの値は環境に合わせて変更してください。

```
<ドメイン名> = {
    kdc = <WindowsサーバーのFQDN>
    admin_server = <WindowsサーバーのFQDN>
}
```

ファイル作成後パーミッションを調整します。

```console
chmod 644 /opt/osstech/var/lib/ucidm/krb5/winrm.conf
```

#### keytabファイルの配置 \{#deploy-keytab}

前章で作成したディレクトリにkeytabファイルを配置します。
`/opt/osstech/var/lib/ucidm/krb5/winrm-<ドメイン名>.keytab` というパスに配置します。

配置後パーミッションを調整します。

```console
chmod 640 /opt/osstech/var/lib/ucidm/krb5/winrm-<ドメイン名>.keytab
rootlesskit chown 1001:root /opt/osstech/var/lib/ucidm/krb5/winrm-<ドメイン名>.keytab
```

#### composeファイルの編集 \{#edit-compose}

composeファイルを編集して、作成したファイルをコンテナにバインドマウントします。
`/opt/osstech/var/lib/ucidm/compose.yml` ファイルを編集します。
winrmによるコマンド連携を行うconsumerコンテナの記述がされている箇所に、volumesの設定を追加します。

```yml
    volumes:
      - type: bind
        source: ./krb5/winrm.conf
        target: /etc/krb5.conf.d/winrm.conf
        bind:
          create_host_path: false
      - type: bind
        source: ./krb5/winrm-<ドメイン名>.keytab
        target: /etc/winrm.keytab
        bind:
          create_host_path: false
```

変更を反映するにはconsumerコンテナを再生成してください。

## pythonスクリプトの作成 \{#create-script}

pywinrmを使ってWindowsサーバーへコマンドを送信するサンプルスクリプトを示します。

```python
import sys
import winrm

AD_SERVER = "win-server.example.com"  # WindowsサーバーのFQDN

def main():
    session = winrm.Session(AD_SERVER,
                            auth=(None, None),
                            transport="kerberos",
                            )
    res = session.run_cmd("ipconfig")
    print(res.std_out.decode("CP932"))
    sys.exit(res.status_code)

if __name__ == "__main__":
    main()
```

WindowsサーバーのFQDNとホスト名が一致していない場合は、 `kerberos_hostname_override` というパラメーターで別途ホスト名を指定してください。

```python
    session = winrm.Session(AD_SERVER,
                            auth=(None, None),
                            transport="kerberos",
                            kerberos_hostname_override="WIN-SERVER.EXAMPLE.COM"  # Windowsサーバーのホスト名
                            )
```

作成したスクリプトは保存します。
保存先は外部連携名や実行タイミングに応じて変動します。
詳細は[外部連携の前処理/後処理で実行するスクリプトの配置](/resource/ucidm/docs/on-premise/dev/administration/admin-ui/destination/script.md)を参照してください。
ここでは例として `/opt/osstech/var/lib/ucidm/server-data/destination/local-001/scripts/UserAdded/connect_ad.py` というパスに保存します。

作成したスクリプトのパーミッションを調整します。

```console
chmod 700 /opt/osstech/var/lib/ucidm/server-data/destination/local-001/scripts/UserAdded/connect_ad.py
rootlesskit chown 1001:root /opt/osstech/var/lib/ucidm/server-data/destination/local-001/scripts/UserAdded/connect_ad.py
```

変更を反映するにはconsumerコンテナとapiコンテナを再生成してください。

## UCIDMの設定 \{#ucidm-setup}

UCIDMの管理画面から前処理/後処理で実行するスクリプトとして、今回作成したスクリプトを追加してください。

追加手順は [外部連携の前処理/後処理で実行するスクリプトの設定](/resource/ucidm/docs/on-premise/dev/administration/admin-ui/scriptsettings.md#setup) を参照してください。