[comment]: # ({e4e11bc3-542796d3})

# 3 スクリプト

[comment]: # ({/e4e11bc3-542796d3})

[comment]: # ({61181e12-58923c7d})
#### 概要

*アラート > スクリプト* セクションでは、ユーザー定義のグローバルスクリプトを設定および管理できます。

このメニューは [SuperAdmin](/manual/config/users_and_usergroups/permissions) ユーザータイプのユーザーのみが利用できます。

グローバルスクリプトは、設定されたスコープとユーザー権限に応じて、次の場所から実行できます。

-   各種 Webインターフェース の場所（*ダッシュボード*、*障害*、*最新データ*、*マップ* など）にある [ホストメニュー](/manual/web_interface/menu/host_menu) から
-   [イベントメニュー](/manual/web_interface/menu/event_menu) から
-   アクションオペレーションとして実行

スクリプトは Zabbix エージェント、Zabbix サーバー（プロキシ）または Zabbix サーバーのみで実行されます。  
[コマンド実行](/manual/appendix/command_execution) も参照してください。

Zabbix エージェントと Zabbix プロキシの両方で、リモートスクリプトはデフォルトで無効です。  
次の方法で有効化できます。

-   Zabbix エージェントで実行されるリモートコマンドの場合:
    - エージェント設定に、許可する各コマンドごとに AllowKey=system.run[<command>,\*] パラメータを追加します。* は wait モードと nowait モードを表します。
-   Zabbix プロキシで実行されるリモートコマンドの場合:
    - **警告: リモートコマンドが Zabbix プロキシによって監視されている Zabbix エージェント上で実行される場合、Zabbix プロキシでリモートコマンドを有効にする必要はありません。** ただし、Zabbix プロキシ上でリモートコマンドを実行する必要がある場合は、プロキシ設定で *EnableRemoteCommands* パラメータを '1' に設定します。

Zabbix サーバーでのグローバルスクリプト実行は、[サーバー設定](/manual/concepts/server/server_params) で `EnableGlobalScripts=0` を設定することで無効にできます。  
新規インストールでは、Zabbix 7.0 以降、Zabbix サーバーでのグローバルスクリプト実行はデフォルトで無効です。

既存のスクリプト一覧とその詳細が表示されます。

![](../../../../../assets/en/manual/web_interface/scripts.png){width="600"}

表示データ:

|Column|Description|
|--|--------|
|*Name*|スクリプト名。スクリプト名をクリックすると、スクリプトの[設定フォーム](scripts#configuring-a-global-script)が開きます。|
|*Scope*|スクリプトのスコープ - アクションオペレーション、手動ホストアクション、または手動イベントアクション。 この設定により、スクリプトを利用できる場所が決まります。|
|*Used in actions*|スクリプトが使用されているすべてのアクションが、該当アクションの総数を先頭に付けて表示されます。<br>アクション名をクリックすると、アクション設定フォームが開きます。ユーザーにそのアクションへの権限がない場合、名前はクリックできません。|
|*Type*|スクリプトの種類が表示されます - *URL*、*Webhook*、*Script*、*SSH*、*Telnet*、または *IPMI* コマンド。|
|*Execute on*|スクリプトが Zabbix エージェント、Zabbix プロキシ、サーバー、または Zabbix サーバーのみのどこで実行されるかが表示されます。|
|*Commands*|スクリプト内で実行されるすべてのコマンドが表示されます。<br>webhook ではここには何も表示されません。|
|*User group*|スクリプトを利用できるユーザーグループが表示されます（すべてのユーザーグループの場合は *All*）。|
|*Host group*|スクリプトが利用可能なホストグループが表示されます（すべてのホストグループの場合は *All*）。|
|*Host access*|ホストグループの権限レベルが表示されます - *Read* または *Write*。必要な権限レベルを持つユーザーのみがスクリプトを実行できます。|

新しいスクリプトを設定するには、右上隅の *Create script* ボタンをクリックします。

[comment]: # ({/61181e12-58923c7d})

[comment]: # ({b4b6453f-44c45ea0})
##### 一括編集オプション

一覧の下にあるボタンでは、1つの一括編集オプションを利用できます。

-   *削除* - スクリプトを削除します

このオプションを使用するには、対象のスクリプトの前にあるチェックボックスを選択し、*削除* をクリックします。

[comment]: # ({/b4b6453f-44c45ea0})

[comment]: # ({38c09c27-1c5dd978})
##### フィルターの使用

フィルターを使用すると、関心のあるスクリプトだけを表示できます。
検索性能を向上させるため、データはマクロが展開されていない状態で検索されます。

*フィルター* リンクは、スクリプト一覧の上にあります。
これをクリックするとフィルターが表示され、名前とスコープでスクリプトを絞り込めます。

![](../../../../../assets/en/manual/web_interface/script_filter.png){width="600"}

[comment]: # ({/38c09c27-1c5dd978})

[comment]: # ({c3e70269-201a0633})
#### グローバルスクリプトの設定

![](../../../../../assets/en/manual/web_interface/script.png){width="600"}

::: noteclassic
グローバルスクリプトでは、セキュリティ向上のため、単純なマクロの代わりに [macro functions](/manual/config/macros/macro_functions) を使用することを推奨します。マクロは自動的にエスケープされないためです。
:::

スクリプト属性:

|Parameter|<|Description|
|-|----------|----------------------------------------|
|*Name*|<|スクリプトの一意な名前。<br>例: `Clear /tmp filesystem`|
|*Scope*|<|スクリプトの範囲 - アクション操作、手動ホストアクション、または手動イベントアクション。 この設定により、スクリプトをどこで使用できるかが決まります。つまり、それぞれアクション操作のリモートコマンド、[ホストメニュー](/manual/web_interface/menu/host_menu)、または [イベントメニュー](/manual/web_interface/menu/event_menu) から使用できます。<br>範囲を「Action operation」に設定すると、*Alerts* > *Actions* へのアクセス権を持つすべてのユーザーがスクリプトを利用できるようになります。<br>スクリプトが実際にアクションで使用されている場合、その範囲を「action operation」以外に変更することはできません。<br>**マクロのサポート**<br>範囲によって利用可能なマクロの種類が変わります。たとえば、ユーザー関連マクロ ({USER.\*}) は、スクリプトを起動したユーザーに関する情報を渡せるようにするため、スクリプトでサポートされています。ただし、スクリプトの範囲がアクション操作の場合は、アクション操作は自動的に実行されるため、サポートされません。<br>{MANUALINPUT} マクロを使用すると、スクリプト実行時に手動入力を指定できます。これは手動ホストアクションおよび手動イベントアクションのスクリプトでサポートされています。<br>他にどのマクロがサポートされているかを確認するには、[supported macro](/manual/appendix/macros/supported_by_location) テーブルで 'Trigger-based notifications and commands/Trigger-based commands'、'Manual host action scripts'、'Manual event action scripts' を検索してください。マクロがスペースを含む値（たとえばホスト名）に展開される場合は、必要に応じて必ず引用符で囲んでください。|
|*Menu path*|<|スクリプトへのメニューのパス。たとえば、`Default` または `Default/` とすると、スクリプトは対応するディレクトリに表示されます。メニューは入れ子にできます。例: `Main menu/Sub menu1/Sub menu2`。監視セクションのホスト/イベントメニューからスクリプトにアクセスする場合、指定されたディレクトリに従って整理されます。<br>このフィールドは、*Scope* に「Manual host action」または「Manual event action」を選択した場合にのみ表示されます。|
|*Type*|<|該当するボタンをクリックしてスクリプトタイプを選択します:<br>**URL**, **Webhook**, **Script**, **SSH**, **Telnet** または **[IPMI](/manual/config/notifications/action/operation/remote_command#ipmi-remote-commands)** コマンド。<br> タイプ **URL** は、*Scope* に「Manual host action」または「Manual event action」を選択した場合にのみ使用できます。 |
| |Script type: **URL**|<|
|^|*URL*|[ホストメニュー](/manual/web_interface/menu/host_menu) または [イベントメニュー](/manual/web_interface/menu/event_menu) からすばやくアクセスできる URL を指定します。<br>[マクロ](/manual/appendix/macros/supported_by_location) とカスタム [user macros](/manual/config/macros/user_macros) がサポートされています。マクロのサポートはスクリプトの範囲に依存します（上記の *Scope* を参照）。<br>このフィールドでは {MANUALINPUT} マクロを使用して、スクリプト実行時に手動入力を指定できます。例:<br>`http://{MANUALINPUT}/zabbix/zabbix.php?action=dashboard.view`<br>マクロの値は URL エンコードしてはいけません。 |
|^|*Open in new window*|URL を新しいブラウザタブで開くか、同じタブで開くかを決定します。|
| |Script type: **Webhook**|<|
|^|*Parameters*|webhook の変数を属性と値のペアとして指定します。<br>あわせて [Webhook](/manual/config/notifications/media/webhook) メディア設定も参照してください。<br>[マクロ](/manual/appendix/macros/supported_by_location) とカスタム [user macros](/manual/config/macros/user_macros) がパラメータ値でサポートされています。マクロのサポートはスクリプトの範囲に依存します（上記の *Scope* を参照）。|
|^|*Script*|パラメータ欄またはその横の鉛筆アイコンをクリックすると開くモーダルエディタに、JavaScript コードを入力します。<br>マクロのサポートはスクリプトの範囲に依存します（上記の *Scope* を参照）。<br>あわせて [Webhook](/manual/config/notifications/media/webhook) メディア設定、[Additional Javascript objects](/manual/config/items/preprocessing/javascript/javascript_objects) も参照してください。|
|^|*Timeout*|JavaScript の実行タイムアウト（1-60秒、デフォルト 30秒）。<br>30s、1m のような時間サフィックスがサポートされています。|
| |Script type: **Script**|<|
|^|*Execute on*|該当するボタンをクリックして、シェルスクリプトを次のいずれかで実行します:<br>**Zabbix エージェント** - スクリプトはホスト上の Zabbix エージェントによって実行されます（system.run アイテムが [許可されている](/manual/config/items/restrict_checks) 場合）。<br>**Zabbix プロキシまたはサーバー** - スクリプトは、ホストがプロキシまたはサーバーのどちらで監視されているかに応じて、Zabbix プロキシまたはサーバーによって実行されます。<br>[EnableRemoteCommands](/manual/concepts/proxy/proxy_params#enableremotecommands) により有効化されている場合は、プロキシ上で実行されます。<br>[EnableGlobalScripts](/manual/concepts/server/server_params#enableglobalscripts) サーバーパラメータでグローバルスクリプトが有効な場合は、サーバー上で実行されます。<br>**Zabbix サーバー** - スクリプトは Zabbix サーバーのみで実行されます。<br>[EnableGlobalScripts](/manual/concepts/server/server_params#enableglobalscripts) サーバーパラメータでグローバルスクリプトが無効な場合、このオプションは使用できません。|
|^|*Commands*|スクリプト内で実行するコマンドの完全なパスを入力します。<br>マクロのサポートはスクリプトの範囲に依存します（上記の *Scope* を参照）。カスタム [user macros](/manual/config/macros/user_macros) がサポートされています。|
| |Script type: **SSH**|<|
|^|*Authentication method*|認証方式を選択します - パスワードまたは公開鍵。|
|^|*Username*|ユーザー名を入力します。|
|^|*Password*|パスワードを入力します。<br>このフィールドは、認証方式として「Password」を選択した場合に使用できます。|
|^|*Public key file*|公開鍵ファイルへのパスを入力します。<br>このフィールドは、認証方式として「Public key」を選択した場合に使用できます。|
|^|*Private key file*|秘密鍵ファイルへのパスを入力します。<br>このフィールドは、認証方式として「Public key」を選択した場合に使用できます。|
|^|*Passphrase*|パスフレーズを入力します。<br>このフィールドは、認証方式として「Public key」を選択した場合に使用できます。|
|^|*Port*|Zabbix が接続する対象ホスト上のリモート SSH サービスポートを入力します。|
|^|*Commands*|コマンドを入力します。<br>マクロのサポートはスクリプトの範囲に依存します（上記の *Scope* を参照）。カスタム [user macros](/manual/config/macros/user_macros) がサポートされています。|
| |Script type: **Telnet**|<|
|^|*Username*|ユーザー名を入力します。|
|^|*Password*|パスワードを入力します。|
|^|*Port*|Zabbix が接続する対象ホスト上のリモート Telnet サービスポートを入力します。|
|^|*Commands*|コマンドを入力します。<br>マクロのサポートはスクリプトの範囲に依存します（上記の *Scope* を参照）。カスタム [user macros](/manual/config/macros/user_macros) がサポートされています。|
| |Script type: **IPMI**|<|
|^|*Command*|IPMI コマンドを入力します。<br>マクロのサポートはスクリプトの範囲に依存します（上記の *Scope* を参照）。カスタム [user macros](/manual/config/macros/user_macros) がサポートされています。|
|*Description*|<|スクリプトの説明を入力します。|
|*Host group*|<|スクリプトを利用可能にするホストグループを選択します（すべてのホストグループに対しては *All*）。|
|*User group*|<|スクリプトを利用可能にするユーザーグループを選択します（すべてのユーザーグループに対しては *All*）。<br>このフィールドは、*Scope* に「Manual host action」または「Manual event action」を選択した場合にのみ表示されます。|
|*Required host permissions*|<|ホストグループに必要な権限レベルを選択します - *Read* または *Write*。必要な権限レベルを持つユーザーのみがスクリプトを実行できます。<br>このフィールドは、*Scope* に「Manual host action」または「Manual event action」を選択した場合にのみ表示されます。|
|*Advanced configuration*|<|*Advanced configuration* の見出しをクリックすると、[advanced configuration](#advanced-configuration) オプションが表示されます。<br>このフィールドは、*Scope* に「Manual host action」または「Manual event action」を選択した場合にのみ表示されます。|

[comment]: # ({/c3e70269-201a0633})

[comment]: # ({a4589038-71b76cf1})
#### 詳細設定

折りたたみ可能な *詳細設定* セクションで、詳細設定オプションを利用できます。

![](../../../../../assets/en/manual/web_interface/script_advanced.png){width="600"}

|Parameter|Description|
|----------|----------------------------------------|
|*Enable user input*|チェックボックスをオンにすると、スクリプト実行前に手動のユーザー入力を有効にできます。<br>手動のユーザー入力は、スクリプト内の {MANUALINPUT} マクロ値を置き換えます。<br>参照: [手動のユーザー入力](#manual-user-input)。|
|*Input prompt*|カスタムのユーザー入力を促すテキストを入力します。このテキストは、*Manual input* ポップアップの入力欄の上に表示されます。<br>*Manual input* ポップアップのプレビューを表示するには、*Test user input* をクリックします。プレビューでは、入力文字列が入力検証ルールに適合しているかどうかも確認できます（下記のパラメータを参照）。<br>マクロおよびユーザーマクロのサポートは、スクリプトのスコープに依存します（一般的なスクリプト設定パラメータの *Scope* を参照）。|
|*Input type*|手動入力の種類を選択します:<br>**String** - 単一の文字列;<br>**Dropdown** - 複数のドロップダウンオプションから値を選択します。|
|*Dropdown options*|ユーザー入力用ドロップダウンの一意の値を、カンマ区切りのリストで入力します。<br>ドロップダウンに空のオプションを含めるには、リストの先頭、中間、または末尾に余分なカンマを追加します。<br>このフィールドは、*Input type* で 'Dropdown' が選択されている場合にのみ表示されます。|
|*Default input string*|ユーザー入力のデフォルト文字列を入力します（または空欄にします）。<br>このフィールドは、*Input validation rule* フィールドで指定された正規表現に対して検証されます。<br>ここで入力した値は、*Manual input* ポップアップにデフォルトで表示されます。<br>このフィールドは、*Input type* で 'String' が選択されている場合にのみ表示されます。|
|*Input validation rule*|ユーザー入力文字列を検証するための正規表現を入力します。<br>グローバル正規表現がサポートされています。<br>このフィールドは、*Input type* で 'String' が選択されている場合にのみ表示されます。|
|*Enable confirmation*|チェックボックスをオンにすると、スクリプト実行前に確認メッセージを表示できます。この機能は、再起動スクリプトのような潜在的に危険な操作や、時間がかかる可能性のある操作で特に有用です。|
|*Confirmation text*|上記のチェックボックスで有効にした確認ポップアップ用のカスタム確認テキストを入力します（例: *Remote system will be rebooted. Are you sure?*）。テキストの表示を確認するには、フィールドの横にある *Test confirmation* をクリックします。<br>[マクロ](/manual/appendix/macros/supported_by_location) およびカスタム [ユーザーマクロ](/manual/config/macros/user_macros) がサポートされています。<br>*注:* 確認メッセージのテスト時には、マクロは展開されません。|

手動のユーザー入力と確認メッセージの両方が設定されている場合、それらは連続したポップアップウィンドウで表示されます。

[comment]: # ({/a4589038-71b76cf1})

[comment]: # ({90545584-346cf40f})
#### 手動ユーザー入力

手動ユーザー入力では、スクリプトの実行ごとにカスタムパラメータを指定できます。  
これにより、1つのパラメータだけが異なる複数の類似したユーザースクリプトを作成する必要がなくなります。

例えば、実行時に異なる整数値や異なるURLアドレスをスクリプトに渡したい場合があります。

手動ユーザー入力を有効にするには、次のいずれかを行います。

-   必要な箇所で、スクリプト（コマンド、スクリプト、スクリプトパラメータ）内、またはURLスクリプトのURLフィールドで {MANUALINPUT} マクロを使用します。
-   [高度なスクリプト設定](#advanced-configuration)で、手動ユーザー入力を有効にし、入力オプションを設定します。

ユーザー入力を有効にすると、スクリプトの実行前に、ユーザーにカスタム値の入力を求める *手動入力* ポップアップが表示されます。  
入力された値は、スクリプト内の {MANUALINPUT} に置き換えられます。

設定に応じて、ユーザーは文字列値の入力を求められます。

![](../../../../../assets/en/manual/web_interface/manual_input_field.png)

または、あらかじめ定義されたオプションのドロップダウンから値を選択します。

![](../../../../../assets/en/manual/web_interface/manual_input_field2.png)

手動ユーザー入力は、スコープが「手動ホストアクション」または「手動イベントアクション」であるスクリプトでのみ使用できます。

[comment]: # ({/90545584-346cf40f})

[comment]: # ({9e2bfd47-ca68e16a})
#### スクリプトの実行と結果

Zabbixサーバーによって実行されるスクリプトは、[コマンド実行ページ](/manual/appendix/command_execution)で説明されている順序で実行されます。

スクリプトの結果は、スクリプトの実行後に表示されるポップアップウィンドウに表示されます。
スクリプトの戻り値は標準出力です。

-   スクリプトが正常に終了した場合（[終了コード](/manual/appendix/command_execution#exit-code-checking) `0`）、戻り値は16MBに制限されます（切り捨てられる末尾の空白文字を含む）。
-   スクリプトがエラーで終了した場合（終了コードが0以外）、戻り値は標準エラーとなり、2KBに制限されます。

Zabbixは、デフォルトでは拡張されたスクリプト出力を保存しません。
出力の詳細全体を保持するには、スクリプト自体にロギングを実装できます（例: 出力をローカルのログファイルにリダイレクトする）。

ZabbixサーバーまたはZabbixプロキシ上で実行されるスクリプトには、[データベースの制限](/manual/config/items/item#item-data-limits)も適用されることに注意してください。

以下は、スクリプトと結果ウィンドウの例です。

```bash
uname -v
/tmp/non_existing_script.sh
echo "This script was started by {USER.USERNAME}"
```

![](../../../../../assets/en/manual/web_interface/frontend_sections/administration/script_result.png)

スクリプトの結果には、スクリプト自体は表示されません。

[comment]: # ({/9e2bfd47-ca68e16a})

[comment]: # ({6447bc3c-5b600786})
#### Zabbix エージェントでのスクリプトタイムアウト

スクリプトの実行中にタイムアウトが発生する場合があります。

以下は、Zabbix エージェント上で実行されるスクリプトの例と、その結果ウィンドウです。

```bash
sleep 5
df -h
```

![](../../../../../assets/en/manual/web_interface/frontend_sections/administration/script_timeout_1.png)

この場合のエラーメッセージは次のとおりです。

```default
Timeout while executing a shell script.
```

このような状況を避けるには、`Timeout` パラメータを [Zabbix agent configuration](/manual/concepts/agent/agentd_params#timeout) や [Zabbix server configuration](/manual/concepts/server/server_params#timeout) で調整するのではなく、スクリプト自体を最適化することを推奨します。

[Zabbix agent configuration](/manual/concepts/agent/agentd_params) で `Timeout` パラメータが変更されている場合、次のエラーメッセージが表示されます。

```default
Get value from agent failed: ZBX_TCP_READ() timed out.
```

これは、[Zabbix agent configuration](/manual/concepts/agent/agentd_params) で変更が行われたものの、[Zabbix server configuration](/manual/concepts/server/server_params) の `Timeout` パラメータも変更する必要があることを意味します。

[comment]: # ({/6447bc3c-5b600786})

[comment]: # ({9a94b46e-f4f6f7e1})
#### アクティブエージェントでのスクリプトタイムアウト

[scripts](/manual/web_interface/frontend_sections/alerts/scripts) は、アクティブモードで動作しているエージェント上でのみ実行できます。
スクリプトの実行は、アクションの[operation](/manual/config/notifications/action/operation)または手動でのスクリプト実行によってトリガーされると、そのコマンドはアクティブチェックの設定に含まれ、アクティブエージェントが受信した時点で実行されます。

手動スクリプトは、スクリプト実行用のサーバー/プロキシのタイムアウトとともにアクティブエージェントへ送信されます。デフォルトの[server](/manual/concepts/server/server_params#timeout)/[proxy](/manual/concepts/proxy/proxy_params#timeout)のスクリプト実行タイムアウトを増やしてください。
このタイムアウトは、アクティブチェックの更新頻度よりも大きくする必要があります。そうでない場合、アクティブエージェントがスクリプトを受信して結果を返せるようになる前にタイムアウトしてしまいます。

[comment]: # ({/9a94b46e-f4f6f7e1})

[comment]: # ({1ae7eae2-0b38e381})
#### Zabbixサーバー/プロキシでのスクリプトタイムアウト

Zabbixサーバー上で実行されるスクリプトの例と、その結果ウィンドウを以下に示します。

```bash
sleep 11
df -h
```

![](../../../../../assets/en/manual/web_interface/frontend_sections/administration/script_timeout_3.png)

また、スクリプト自体を最適化することも推奨されます（[Zabbixサーバーの設定](/manual/concepts/server/server_params)を変更して `TrapperTimeout` パラメーターを対応する値（この場合は `11` より大きい値）に調整するのではなく）。

[comment]: # ({/1ae7eae2-0b38e381})