Event Handlers

Certain actions in Plesk, such as:

  • Creating a customer account
  • Removing an IP address
  • Updating the hosting settings of a domain, and many others

are recognized by Plesk as events. For every event, you can create one or more event handlers that execute a predetermined command every time the event occurs.

Event handlers are useful if you want a certain action or a set of actions to be carried out every time a specific event occurs. For example, you can create an event handler that triggers every time a subscription is created and configure it to automatically create a mailbox, send a request to an external service, and so on.

このセクションの内容:

イベントハンドラの追加

Passing Event Parameters

Editing and Removing Event Handlers

イベントハンドラが受け渡すイベントパラメータ

 

イベントハンドラの追加

  1. [ツールと設定]>[イベントマネージャ]の順に選択します。
  2. [イベントハンドラを追加]をクリックします。
  3. ハンドラをトリガするイベントを「イベント」リストから選択します。
  4. [優先度]の下で、ハンドラの実行優先度を設定します。これには、リストから選択するか、フィールドにカスタム番号を入力します。1 つのイベントに複数のハンドラを割り当てる場合に優先度が重要になります。この場合、ハンドラは優先度に従って降順でトリガされます(優先度が最高のハンドラが最初にトリガされ、続いて優先度が 2 番目のハンドラがトリガされます)。
  5. ハンドラが代理で実行されるシステムユーザを「ユーザ」リストから選択します。

    (Plesk for Linux)の注記: サーバ管理者は root ユーザの代わりにサーバで実行されるイベントハンドラを作成できます。root アカウントの使用を制限したい場合、root.event_handler.lock という名前の空ファイルを /usr/local/psa/var/ に作成します。

  6. イベントハンドラが起動されると常に実行されるコマンドが含まれるシェルスクリプトまたは .bat ファイルのパスを、[コマンド]フィールドに入力します(たとえば、/usr/local/psa/bin/script.sh または C:\Windows\Temp\script.bat)。
  7. [OK]をクリックします。
 

Passing Event Parameters

Whenever an event handler triggers, it passes certain data ("Event Parameters") associated with the event (which data are passed depends on the event handler in question). For example, the "Domain created" event handler passes the following parameters:

  • The name of the newly created domain.
  • The GUID of the newly created domain.
  • The GUID of the customer account owning the newly created domain.

Each parameter is passed as an environment variable that you can use in your shell script or .bat file as follows:

Plesk for Linux

Use the placeholder ${ENVIRONMENT_VARIABLE_NAME} (for example, "${NEW_DOMAIN_NAME}") in your shell script. When the event handler triggers, the placeholder will be replaced by the value corresponding to the event.

Plesk for Windows

Use the placeholder %N (for example, "%1") in your bat file, and append the name of the desired environment variable in the corresponding position at the end of the command in the event handler settings. In the following example

2

the placeholder "%1" will be replaced with the value of the "NEW_DOMAIN_NAME" environment variable, and the "%2" will be replaced with the value of "NEW_DOMAIN_GUID". If you use "%3" in the .bat file, it will not be replaced with anything, as only two environment variable names were specified after the command.

You can see the complete list of event parameters and associated environment variable names for each event handler here.

For reference, here are two examples of scripts for the ‘Customer account created’ event:

  • (Plesk for Linux) test-handler.sh

    #!/bin/bash

    echo "--------------" >> /tmp/event_handler.log

    /bin/date >> /tmp/event_handler.log # information on the event date and time

    /usr/bin/id >> /tmp/event_handler.log # information on the user, on behalf of which the script was executed (to ensure control)

    echo "customer created" >> /tmp/event_handler.log # information on the created customer account

    echo "name: ${NEW_CONTACT_NAME}" >> /tmp/event_handler.log # customer's name

    echo "login: ${NEW_LOGIN_NAME}" >> /tmp/event_handler.log # customer's username in Plesk

    echo "--------------" >> /tmp/event_handler.log

  • (Plesk for Windows) test-handler.bat

    echo "--------------" >> c:\windows\temp\event_handler.log

    rem information on the event date and time

    date /T >> c:\windows\temp\event_handler.log

    rem information on the created customer account

    echo "customer created" >> c:\windows\temp\event_handler.log

    rem customer's name

    echo "name: %1" >> c:\windows\temp\event_handler.log

    rem customer's username in Plesk

    echo "login: %2" >> c:\windows\temp\event_handler.log

    echo "--------------" >> c:\windows\temp\event_handler.log

If you log in to Plesk and create a customer account with the name "John Doe" and login “john_doe”, the event handler will trigger and the following records will be added to the event_handler.log file:

  • (Plesk for Linux)

    Fri Mar 16 15:57:25 NOVT 2007

    uid=0(root) gid=0(root) groups=0(root)

    customer created

    name: John Doe

    login: john_doe

  • (Plesk for Windows)

    Mon March 15 21:46:34 NOVT 2010

    customer created

    name: John Doe

    login: john_doe

 

Editing and Removing Event Handlers

To see the list of currently active event handlers, go to Tools & Settings > Event Manager. Here, you can also edit and remove event handlers:

  • To edit an event handler, click its name, make the desired changes, and click OK.
  • To remove an event handler, select the corresponding checkbox and click Remove.