学ぶ (英語版)
ドキュメント (英語版)
サポート (英語のみ)
コミュニティ (英語版)

Macでのリモートアクション用スクリプトの作成

この記事で説明されている操作の実行に助けが必要な場合は、Nexthink認定パートナーにお問い合わせください。

この記事は、MacにおけるNexthinkリモートアクションスクリプトの準備プロセスについて詳しく説明しています。 スクリプトは、Unix系の多くのオペレーティングシステムでサポートされているコマンドラインシェルおよびスクリプティング言語であるBashで書かれた後、セキュリティーのために証明書で署名されます。 Bashスクリプトはタスクや構成管理の自動化に適しています。これにより、従業員のデバイスでリモートアクションを実行できます。

リモートアクションの主なユースケースは、デバイスからのオンデマンドデータ収集、セルフヒーリングタスク、および構成設定の変更です。

この記事は、読者がBashスクリプティングに精通していることを前提としています。

詳細については、Remote Actionsグループのコミュニティのドキュメントを参照してください。

スクリプトの作成

一般的なスクリプトと入力変数

デジタル署名されたスクリプトにカスタマイズが必要なとき、一般的なスクリプトが役立ちます。署名されたスクリプトを変更すると、その署名が無効になります。 一般的なスクリプトはパラメータでカスタマイズでき、署名が保たれます。

スクリプトの冒頭でパラメータを宣言し、Bashの位置パラメータとして次のように2つの特別なコメントの間に挿入します：

# NXT_PARAMETERS_BEGIN
Parameter1=$1
Parameter2=$2
Parameter3=$3
# NXT_PARAMETERS_END

リモートアクションの設定中にスクリプトをアップロードすると、システムはBashスクリプト内の特別なNexthinkのコメント間にあるパラメータを取得して、スクリプトテキストの下のパラメータセクションにリストします。 各パラメータ名の右側に表示されたテキスト入力ボックスに、実際の値を提供してください。

実際の値は常にテキストとしてスクリプトに渡されます。 スクリプトがstring以外の型でパラメータを宣言している場合は、スクリプトが期待する型に変換できる値を提供してください。

アウトプット変数の作成

スクリプトを実行すると、オンデマンドデータとして保存したいアウトプットが生成されることがあります。 Nexthinkは、Collectorと同時に従業員デバイスにインストールされるBashスクリプト（nxt_ra_script_output.sh）を提供しています。 このスクリプトには、結果をデータレイヤーに書き込むための関数が含まれています。

リモートアクションのアウトプットにNexthinkスクリプトの関数を使用するには、Bashスクリプトの最初に以下のヘッダーを追加してください。

#!/bin/bash
. "${NEXTHINK}"/bash/nxt_ra_script_output.sh

すべての書き込み方法は、アウトプット名と書き込む値の2つの引数を受け入れます。 例えば、ディレクトリ内のファイル数をデータレイヤーに返したい場合、スクリプト内の変数nfilesにその数が含まれます。 nfilesの値をFileNumberというアウトプット名でデータレイヤーに書き込むには、符号なし整数の書き込み関数を呼び出してください。

nxt_write_output_uint32 'FileNumber' $nfiles

リモートアクションエディタは、スクリプト内のアウトプットの書き込み呼び出しを認識し、アウトプット変数をアウトプットセクションに一覧表示します。 アウトプットのラベルを設定して、調査やメトリクスでどのように参照するかを示してください。

各writeメソッドの終了はアウトプットの種類を示します。 Bashは、緩やかに型付けされた言語であるため、アウトプットの種類は文脈によって解釈されます。 利用可能なメソッドの一覧は次のとおりです。

nxt 書き込み方法
制約

nxt_write_output_string

0 - 1024文字（アウトプットが大きい場合は切り詰められます）

nxt_write_output_bool

true / false

nxt_write_output_uint32

  • 最小値: 0

  • 最大値: 4 294 967 295

nxt_write_output_float

  • 最小値: -3.4E+38

  • 最大値: 3.4E+38

nxt_write_output_size

  • 最小値: 0

  • 最大値: 3.4E+38

nxt_write_output_ratio

nxt_write_output_bitrate

nxt_write_output_duration

  • 最小値: 0ミリ秒

  • 最大値: 49日

  • ミリ秒単位の精度

nxt_write_output_date_time

DD.MM.YYYY@HH:MM

nxt_write_output_string_list

0 - 1024文字（アウトプットが大きい場合は切り詰められます）

キャンペーンの実装

従業員が独自に問題を解決できるよう、リモートアクションとキャンペーンを組み合わせましょう。 キャンペーンを使用して、従業員に問題の検出を通知し、その解決に向けて誘導します。

デバイスとやり取りしている従業員のデスクトップにキャンペーンを表示するには:

  • キャンペーンはリモートアクショントリガーを持ち、公開されなければなりません。

  • リモートアクションのスクリプトは以下のいずれかで実行できます。

    • 特別な権限を必要としないアクションの場合、従業員のコンテクストで。

    • 管理者特権を必要とするアクションの場合、ローカルシステムアカウントのコンテクストで。

キャンペーン識別子の取得

リモートアクションからキャンペーンを実行するメソッドでは、引数としてキャンペーン識別子を渡す必要があります。 キャンペーンNQL ID（推奨）とキャンペーンUID（クラシックオプション）の両方を使用できます。

NQL IDを識別子としてサポートするには、Collectorバージョン23.5以上が必要です。

リモートアクションにキャンペーン識別子を渡すには、必要なキャンペーンごとにリモートアクションのスクリプトでパラメータを宣言します。 リモートアクションを編集するときに、実際の値としてNQL ID（またはUID）を使用します。

キャンペーンのNQL IDやUIDを取得する方法については、キャンペーンのトリガー のドキュメントを参照してください。

リモートアクションのスクリプトからキャンペーンを実行する

次の関数はリモートアクションのスクリプト機能を拡張します。

nxt_run_campaign( id )

この関数は、引数として渡されたNQL ID（推奨）またはUIDに一致するキャンペーンを実行し、解答を内部に保存します。

  • キャンペーンのステータスを受信した場合、関数は0を返します。

  • その他のケースでは関数は1を返し、エラーはログに記録されます。

この関数を呼び出すと、従業員がキャンペーンを完了するか、却下するまでリモートアクションの実行が一時停止されます。

nxt_run_campaign_with_timeout( id timeout)

この関数は、引数として渡されたNQL ID（推奨）またはUIDとタイムアウト（秒単位: 0 < T < 1 週間）に一致するキャンペーンを実行し、解答を内部に保存します。

  • キャンペーンのステータスを受信した場合、関数は0を返します。

  • その他のケースでは関数は1を返し、エラーはログに記録されます。

この関数を呼び出すと、従業員がキャンペーンを完了するか却下するか、タイムアウト前にキャンペーンを完了できなかった場合までリモートアクションの実行が一時停止されます。

nxt_run_standalone_campaign( id )

この関数は、引数として渡されたNQL ID（推奨）またはUIDに一致するキャンペーンを実行し、解答を内部に保存します。

  • キャンペーンのステータスを受信した場合、関数は0を返します。

  • その他のケースでは関数は1を返し、エラーはログに記録されます。

この関数を実行すると、キャンペーンの開始がトリガーされ、従業員の回答を待たずにリモートアクションの実行が続行されます。

nxt_get_campaign_status( res_var )

この関数は、最後のキャンペーンのステータスを返します。

  • 完全: 従業員がキャンペーンの質問に完全に回答しました。

  • タイムアウト: ユーザーが回答を終える前にキャンペーンがタイムアウトしました。

  • 延期: 従業員がキャンペーンへの参加に同意しました。

  • 拒否: 従業員がキャンペーンへの参加を拒否しました。

  • 接続失敗: スクリプトがキャンペーン通知を制御するCollectorコンポーネントに接続できませんでした。

  • 通知失敗: スクリプトがキャンペーンを正常に表示できなかった理由は次のいずれかです。

    • プラットフォームからのキャンペーン定義を取得できない非存在キャンペーンまたは公開されていないキャンペーン。

    • 別のキャンペーンが既に従業員に表示されています。

    • Collectorの集中保護または「邪魔しないで」ルールのために急を要しないキャンペーンを表示できません。 詳細については、キャンペーンの受信率を制限する方法のドキュメントを参照してください。

  • 最後のキャンペーンが失敗した場合は空白になります。

nxt_get_response_answer( res_var question_key)

質問ラベルを文字列パラメータのクエリ_keyとして使用して、最後のキャンペーンに問い合わせます。 この関数は文字列値として回答を抽出し、指定された変数res_varに保存します。

  • キャンペーンのステータスを受信した場合は0を返します。

  • その場合は1を返します。

スクリプトのエンコード

リモートアクション用Bashスクリプトを書くには:

  • スクリプトを含むファイルをBOMなしのUTF-8でエンコードします。

  • コードの各行は、UNIXシステムの通常の文字 LF で終了します。

エンコードを正しく行い、エラーや機能しないスクリプトを避けてください。

コード例

キャンペーンを呼び出す

この例では、リモートアクションがIDによって基本的なキャンペーン呼び出しを実行し、成功した場合はステータスメッセージを出力し、失敗した場合はエラーメッセージを出力します。

if nxt_run_campaign "#my_campaign_nql_id"; then
    nxt_get_campaign_status status
    if [[ status == "fully" ]]; then
        echo "キャンペーンが成功しました"
    else
        echo "ステータスは $status"
    fi
else
    echo "キャンペーンが失敗しました"
fi
回答を得る

この例では、リモートアクションがキャンペーンの回答データを呼び出し、配列に出力します。 各回答はそれぞれ対応する番号付きオプションとして表されます。 Bashは0を最低オプションとして使用し、Zshは1を使用します。

nxt_get_campaign_status status
echo "回答のステータスは $status"
nxt_get_response_answer answersArray key1
echo ${answersArray[1]}
タイムアウト付きキャンペーンを実行する

この例では、リモートアクションがタイムアウトして指定された時間後に終了するキャンペーンを実行するように設定されています。入力は秒単位です。

# タイムアウトは秒単位です (100s または 00:01:40)

if nxt_run_campaign_with_timeout "#my_campaign_nql_id" 100; then
    nxt_get_campaign_status status
    if [[ status == "fully" ]]; then
        echo "キャンペーンが成功しました"
    else
        echo "ステータスは $status"
    fi
else
    echo "キャンペーンが失敗しました"
fi
非ブロッキングキャンペーンを実行する

この例では、リモートアクションがユーザーの入力を必要とせず、キャンペーンをトリガー後に処理を続行します。 ユーザーは、いつでもキャンペーンを却下することができます。 これは主にユーザーに情報を提供するために使用され、データを取得するためではありません。

魅力的なキャンペーンの実施のドキュメントを参照してください。

if nxt_run_standalone_campaign "#my_campaign_nql_id"; then
    nxt_get_campaign_status status
    if [[ status == "fully" ]]; then
        echo "キャンペーンが成功しました"
    else
        echo "ステータスは $status"
    fi
else
    echo "キャンペーンが失敗しました"
fi

スクリプトの署名

セキュリティ上の理由から、NexthinkはmacOSでのリモートアクション用Bashスクリプトをcodesignツールでデジタル署名することを求めています。 署名済みスクリプトをtar.gzファイルとしてパッケージ化し、拡張属性を保持してください。 Nexthink web インターフェースは、macOSを対象としたリモートアクションのスクリプトをインポートする際、tar.gz拡張子のファイルのみを受け付けます。

Nexthinkは、実稼働環境でのすべてのスクリプトの署名を推奨しています。 署名のないスクリプトはテスト環境でのみ使用するべきです。

証明書の作成

  • Macデバイスでキー チェーンアクセスを起動します。

  • キー チェーンアクセス > 証明書アシスタント > 証明書を作成… に移動します。

  • 証明書名を入力してください。

  • 証明書の種類としてコード署名を選択してください。

  • テスト目的の場合、デフォルトの上書きを許可するのチェックを外したままにしておくことができます。

  • 作成および完了をクリックしてください。 システムが証明書を生成しました。

署名

標準macOSコードサインユーティリティを使用してリモートアクションスクリプトに署名します。

codesign -s <あなたの証明書のアイデンティティ> --timestamp --prefix=<コード署名識別子のプレフィックス> --force <スクリプトファイル名>

パラメータ:

-s <あなたの証明書のアイデンティティ>

コード署名証明書のアイデンティティはキーチェーン内にあります。 通常、これは証明書主題の共通名または証明書のハッシュです。 詳細については、codesignマニュアルページを参照してください。

--timestamp

署名の信頼できるタイムスタンプ。

--prefix

コード署名識別子へのプレフィックス。 企業のアイデンティティを識別子に付加し、識別子をユニークにするのに役立ちます。 コード署名識別子生成規則については、UNIXのcodesignマニュアルページを参照してください。

--force

既存のコード署名を上書きすることを強制します。

例

example_ra_script.sh リモートアクションスクリプトのテスト証明書の例:

codesign -s "RAスクリプトコード署名証明書" --timestamp --prefix=com.my-organisation.remote-action.macos. --force example_ra_script.sh

スクリプトファイルの署名は、ファイルに関連付けられたファイルシステムの拡張属性で生成されます。 コードサインの詳細を取得し署名を検証するためにcodesignユーティリティを使用してください。

パッケージング

.tarアーカイブと.gzip圧縮を用いてリモートアクションスクリプトをパッケージ化してください。 ".tar.gz"拡張子は必須です。

tar -czvf ./<スクリプト名>.tar.gz ./<スクリプト名>.sh

スクリプトファイルが署名されている場合、tarユーティリティはその拡張属性もパックします。 この方法で、システムはコード署名とスクリプトファイルを転送できます。

制限事項

  • 一つのアーカイブには一つのスクリプトしか入れられません。

  • スクリプトファイルはルートパッケージフォルダに配置する必要があります。./myscript/myscript.sh パスは正しくありません。

  • スクリプトは.sh拡張子を持っていなければなりません。

  • スクリプトファイル名はUTF-8エンコードである必要があります。これはmacOSでデフォルト設定です。

例

test.sh スクリプトのパッケージ化の例:

tar -czvf ./example_ra_script.tar.gz ./example_ra_script.sh

生成された example_ra_script.tar.gz はリモートアクションスクリプトファイルです。

Nexthinkは署名とパッケージ化のプロセスを簡素化するために、このスクリプトを使用することを推奨しています。

#!/bin/bash
#
# script_signing.sh
# 
# Copyright (C) 2023 by Nexthink S.A., Switzerland. Any usage, copy or partial copy of
# this code without the explicit agreement of Nexthink S.A. is prohibited and will be
# pursued to the full extend of the law.
#
# The arguments for the script:
# - input script filename
# - output archive filename
# - Certificate owner
# - Prefix
#
 
 
# Error handling
set -euo pipefail
trap "echo unrecoverable error !" ERR
 
 
# Check codesign
if [[ ! -x /usr/bin/codesign ]]
then
    echo "Error: this script requires that codesign is installed"
    exit 2
fi
 
# Check tar
if [[ ! -x /usr/bin/tar ]]
then
    echo "Error: this script requires that tar is installed"
    exit 2
fi
 
 
# Check arguments
if [[ $# -lt 4 ]]
then
    echo "Usage: script_signing.sh inputScriptFilename outputArchiveFilename CertificateOwner prefix"
    echo "Example: ./script_signing.sh script.sh script.tar.gz \"John Doe\" com.john.remote-action.macos."
    exit 1
fi
 
/usr/bin/codesign -s "$3" --timestamp --prefix="$4" --force "$1"
/usr/bin/tar czf "$2" "$1"

証明書をendpointにデプロイする

キーチェーンにコード署名証明書がある場合、その公開バージョンをendpointにインストールするためには、まずエクスポートする必要があります。

  • ポップアップウィンドウで公開証明書用に 証明書 (.cer) ファイル形式を選択します。

証明書をendpointのキーチェーンにインポートする

  • 署名済みの証明書をSystemキーチェーンにインポートして、Trusted Publisher 実行ポリシーを使用してリモートアクションスクリプトを使用します。

  • .cerファイルをダブルクリックし、キーチェーンのドロップダウンメニューでシステムオプションを選択します。

  • 証明書をインポートするためにルートパスワードを入力してください。

証明書が自己署名の場合、コード署名のために信頼されるべきです。

  • キーチェーンアクセスユーティリティの証明書をダブルクリックし、コード署名オプションで常に信頼を選択してください。

これらの作業を自動化するために、セキュリティユーティリティ（外部リンク）または自動化フレームワークを使用してください。

証明書が正しくendpointにインポートされたか確認する

  • 署名済みのリモートアクションスクリプトをendpointにコピーして解凍してください。

tar -xzvf example_ra_script.tar.gz

  • あなたの署名を確認してください。

codesign -vvvv -R="証明書リーフは信頼されている" example_ra_script.sh

署名が正しくインポートされている場合、次の出力が表示される必要があります:

スクリプトの保守

比較と検証

リモートアクションスクリプトを展開する前に、Nexthinkが準備した他のスクリプトと比較することができます。 このステップはオプションですが、初めてスクリプトを準備する場合は推奨されます。

  1. Nexthink Libraryで、コンテンツを選択してください。

  2. リモートアクションでフィルタリングします。

  3. リモートアクション管理ページに移動してください。

  4. Nexthink Library から直接インストールされたリモートアクションスクリプトの中で、ターゲットオペレーティングシステムに一致するものを選択してください。

  5. スクリプトをエクスポートし、その構文を自分のスクリプトと比較してください。

スクリプトの終了とタイムアウト

リモートアクションスクリプトからサブプロセスを開始し、リモートアクションスクリプトが終了またはタイムアウトすると、Collectorはサブプロセスを自動的に終了します。 リモートアクションが終了した後もサブプロセスを実行し続けるには、&文字を使用してスクリプトがサブプロセスをデタッチすることを確認してください。例:

some_script.sh -arg1 -arg2 &

Zshコマンドインタープリタ

Collectorバージョン6.27.2以降では、Zsh Unixシェル用に書かれたスクリプトを実行できます。 シェルスクリプトの一番最初に以下の行を追加する必要があります:

#!/bin/zsh

これはシバンと呼ばれる文字列です(シバンとは（外部リンク）)。

システムがMac上でリモートアクションを実行すると、Collectorはコードの最初の行をチェックし、指定されたインタープリタを使用して残りの指示を実行します。 シバンのないスクリプトは、Bashコマンドインタープリタを使って実行されます。

Nexthinkは常にシェルスクリプトにシバンを使用し、標準インタープリタに従うことを推奨しています。

Last updated

© Nexthink

プライバシーポリシー (英語版)責任ある情報開示ポリシー (英語版)