# event_handler: Event Handlers

You can make Plesk run a particular action every time a certain event occurs in Plesk. For example, you are able to save each added IP address to a log file or perform other routine operations.

Plesk triggers actions relying on event handles - links between events and actions. When an event happens, Plesk finds all event handlers linked to this event and runs actions assigned to these handlers.

Event handlers management is available via the command line interface or the Plesk GUI. For more information on creating event handlers via GUI, see the section Adding Event Handlers (Linux Hosting) of the Administrator’s Guide.

To manage event handlers via command line, use the `event_handler` utility. This utility performs the following tasks:

- creating an event handler
- updating event handler settings
- listing all event handlers and their settings
- listing events that can trigger event handlers
- listing users on behalf of which scripts defined in event handler settings are executed
- removing event handlers

Note

The utility is available since Plesk 9.0.

If you want to create an event handler for a particular event, you first need to find out if Plesk supports handlers for this event. To do it, execute the following command:

    plesk bin event_handler --list-events

After you make sure that the event you need is present in the list, define the following parameters: an action to perform, a user who performs this action, and the action priority.

An action that Plesk will perform after the event occurs may be specified in three ways:

- Run a snippet of code
- Run a specific script file.
- Run a binary file.

A user on behalf of which Plesk will execute the script must have enough permissions to perform the action.

A priority is an integer number from 0 to 100 that defines the execution sequence of event handlers assigned to a single event. The highest priority handlers are executed first.

## Usage

    event_handler <command> [<handler_id>] [
    <option_1> [<param>]
    [<option_2> [<param>]]
    ... [<option_N> [<param>]]

## Example

The following command creates the event handler for the “IP address created” action that triggers the email_ip.sh script if an IP address is added. The handler priority is set to 50.

    plesk bin event_handler --create -command /bin/events/email_ip.sh -priority 50 -user root -event 5

## Commands

Command | Parameter | Description | Example
--- | --- | --- | ---
`--create` or `-c` |  | Creates an event handler. Requires `-command` , `-priority` , `-user` , and `-event` options. | To create an event handler with priority 50 that triggers the email_ip.bat script if an IP address is added:
    plesk bin event_handler --create -command email_ip.sh -priority 50 -user root -event 5
or
    plesk bin event_handler -c -command email_ip.sh -priority 50 -user root -event 5
`--update` or `-u` | `<handler_id>` | Updates event handler settings. Requires `-user` option. | To change the priority of event handler with ID 1 :
    plesk bin event_handler --update 1 -user jdoe -priority 12
or
    plesk bin event_handler -u 1 -user jdoe -priority 12
`--delete` or `-d` | `<handler_id>` | Removes an event handler. | To remove the event handler with ID 1:
    plesk bin event_handler --delete 1
or
    plesk bin event_handler -d 1
`--list` or `-l` |  | Provides information about existing handlers and their settings. | To list event handlers:
    plesk bin event_handler --list
or
    plesk bin event_handler -l
`--list-events` or `-le` |  | Lists events that can trigger event handlers. Each record includes event ID and description. | To view the available events:
    plesk bin event_handler --list-events
or
    plesk bin event_handler -le
`--list-users` or `-lu` |  | Lists users on behalf of which scripts defined in event handler settings (`-command` option) are executed. | To list users:
    plesk bin event_handler --list-users
or
    plesk bin event_handler -lu
`--help` or `-h` |  | Displays help on the utility use. | To view help on the use of this utility:
    plesk bin event_handler --help
or
    plesk bin event_handler -h

## Options

Note

These options are used with `--update` and `--create` operations only.

Option | Parameter | Description | Example
--- | --- | --- | ---
`-user` | `<login>` | Specifies the login name of a Plesk user on behalf of which scripts/files defined in event handler settings are executed. Note Login name of Plesk Administrator is “root”. | To run scripts of the event handler with ID 1 on behalf of John:
    plesk bin event_handler --update 1 -user jdoe
`-priority` | `<0-100>` | Value that determines the importance of an event handler relative to other event handlers assigned to the same event. Lowest priority is 0. Highest priority is 100. | To set the priority of the handler with ID 1 and user jdoe to 75:
    plesk bin event_handler --update 1 -user jdoe -priority 75
`-command` | `<command>` | Specifies one of the following: Script code Full name of the file which stores the code Full name of an executable file This code/file is executed on triggering a particular event handler. Use “” symbol to escape quotes within commands. | To update the event handler command:
    plesk bin event_handler --update 1 -user jdoe -command ipconfig.sh
`-event` | `<event name>` | Specifies the event that triggers a particular event handler. Use `--list-events` or `-le` command to find the required ID. | To set the event ID of the event handler (with ID 2) to 17:
    plesk bin event_handler --update 2 -event 17 -user root