プラグイン: 最小構成 (macOS)

想定読者: macOSエンドポイントに常駐型の管理プラグインを登録する統合担当者。

本ページはプラグイン: 最小構成 (Windows) のmacOS向け版です。プラグインの構造と各フィールドの意味は同じで、違いはバイナリパス、supportedPlatforms、および他のOSより厳しいmacOS特有の署名要件です。各フィールドの詳しい説明は、上記のWindows版ページを先に読み、本ページではmacOSで変わる点のみを扱います。

プラグインのJSON

{
  "id": "MyBridge",
  "name": "My Bridge",
  "description": "Long-running bridge component.",
  "version": "1.0.0",

  "pluginType": "Executable",
  "executablePath": "bin/MyBridge/MyBridge",
  "supportedPlatforms": ["macOS"],

  "Subscription": {
    "Topic": "MyBridge",
    "Qos": 2,
    "CleanSession": true
  },

  "metadata": {
    "mqttRole": ["subscriber", "publisher"],
    "mqttTopics": {
      "publish": ["KeeperLogger"],
      "subscribe": ["MyBridge", "MyBridge/Commands/+"]
    }
  },

  "startupPriority": 60,
  "autoStart": true,
  "executionContext": "Service",
  "requiresMonitoring": true,
  "autoRestart": true
}

変更する箇所

フィールド

内容

id	ファイル名と一致する安定した一意の識別子 ("id": "MyBridge" なら MyBridge.json)。
executablePath	エージェントルートからの相対パスで、拡張子 .exe は付けません。macOSでのエージェントのデフォルトルートは /usr/local/KeeperPrivilegeManager のため、bin/MyBridge/MyBridge は /usr/local/KeeperPrivilegeManager/bin/MyBridge/MyBridge に解決されます。インストールルートは管理者へ確認してください。
supportedPlatforms	macOS専用なら ["macOS"]。
Subscription.Topic	当該プラグインの主たるMQTTトピック。慣例としてプラグインの id を使います。
metadata.mqttTopics.publish	バイナリがパブリッシュするすべてのトピック。ログメッセージを出す場合は KeeperLogger を含めます。
metadata.mqttTopics.subscribe	主たる Subscription.Topic 以外にバイナリがサブスクライブするすべてのトピック。

拡張子 .exe は付けない: Linuxと同様、executablePath とディレクトリ名に拡張子はありません。

ファイルのパーミッション: オーケストレーターが起動する前に、バイナリがエージェントのサービスアカウントから実行可能である必要があります。

chmod +x /usr/local/KeeperPrivilegeManager/bin/MyBridge/MyBridge

署名と公証は必須: macOS特有の最重要要件で、エージェントがバイナリを起動する前に満たす必要があります。Gatekeeperは未署名または未公証のバイナリをOSレベルでブロックし、隔離されたバイナリはオーケストレーターが登録または起動する前に止められます。Apple Developer ID証明書で署名し、リリース工程の一環として公証を提出します。ジョブタスク用バイナリに加え、プラグイン用バイナリはKEPMのより厳しいプラグインパス信頼チェックの対象でもあるため、署名の重要性は二重になります。

署名後、MQTTやプラグイン設定へオーケストレーター起動以外の文脈からアクセスさせる必要がある場合は、appsettings.json の Settings:AlternativeSignatures に証明書のサムプリントを追加します。

autoRestart と launchd: macOSではKEPMエージェントは多くの場合 launchd デーモンとして動きます。autoRestart: true でプラグインが異常終了した場合、オーケストレーターが launchd とは独立に再起動します。Linuxと同様、短時間での再起動ループはログ量とCPU負荷が大きくなり得ます。想定どおりの停止ではきれいに終了し、その前に明確なログを出すようにします。

デプロイ前に

1. バイナリに署名し公証する: macOSエンドポイントへ配布する前に完了させます。配布後に対象マシン上だけで後から済ませることはできません。

2. executablePath が解決する場所へバイナリを置き、chmod +x で実行権限を付与します。

3. JSONファイルを {AgentRoot}/Plugins/MyBridge.json に置き、ファイル名を id と一致させます。

4. 環境ごとの正式な投入手順は管理者と確認します。

5. オーケストレーターが新しい登録を読み込むよう、エージェントを再起動します。

sudo launchctl stop com.keeper.privilegemanager
sudo launchctl start com.keeper.privilegemanager

launchd のサービスラベルはパッケージにより異なる場合があるため、管理者へ確認してください。

検証

エージェント再起動後、ログでプラグイン名を確認して起動したことを確かめます。続いて、起動時にバイナリ内からプラグイン設定が取得できるかを確認します。

curl -s https://127.0.0.1:6889/api/PluginSettings/MyBridge \
  --cert /path/to/client.pem \
  --key /path/to/client.key \
  --cacert /path/to/ca.pem

この呼び出しにはプラグイン階層の認証が必要で、任意のシェルセッションからは 403 になります。起動時のスモークテストとして、同等の呼び出しをプラグインバイナリ内から実行します。