### Adding Event Handlers

Let's, for example, create an event handler for the 'client account creation' event. The handler will accept a client name and the client's login from environment variables. For simplicity we will use a shell-script called `test-handler.sh` that looks as follows:

#!/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 "client created" >> /tmp/event_handler.log # information on the created client account

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

echo "login: ${NEW_LOGIN_NAME}" >> /tmp/event_handler.log # client's login

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

This script prints some information to a file so that we could control its execution (we cannot output information to stdout/stderr, as the script is executed in the background mode).

Suppose, that our script is located in the directory `/plesk_installation_directory``/bin` (for instance). Let's register it by creating an event handler via the control panel:

1. Select the Server shortcut in the navigation pane.
2. Click the Event Manager icon in the Control Panel group.
3. Click the Add New Event Handler icon. The event handler setup page appears:
4. Select the event, you wish to assign a handler to in the Event drop-down box.
5. Select the priority for handler execution, or specify a custom value. To do this, select custom in the Priority drop-down list and type in the value.

   When assigning several handlers to a single event you can specify the handler execution sequence, setting different priorities (higher value corresponds to a higher priority).

6. Select the system user, on behalf of which the handler will be executed ("root" user, for example).
7. In the Command input field, specify a command to be executed upon the selected event. In our example it is `/usr/local/psa/bin/test-handler.sh`.
8. Click OK.

Note: In the script, we have specified the variables $NEW_CONTACT_NAME and $NEW_LOGIN_NAME. During execution of the handler, they will be replaced with name and login of the created client respectively. The entire list of available variables is provided in the following section. You should keep in mind that with the removal operations, the variables of type $NEW_xxx are not set. And with creation operations the parameters of type $OLD_xxx are not set.

Now if you login to your Plesk control panel and create a new client, specifying the value 'Some Client' in the Contact name field, and 'some_client' in the field Login, the handler will be invoked, and the following records will be added to the `/tmp/event_handler.log`:

Fri Mar 16 15:57:25 NOVT 2007

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

client created

name: Some client

login: some_client

If you want to specify one or few handlers more, repeat the actions above for another handler.

The parameter templates that can be used when setting up an event handler are presented in the table below:

Table. Available Event Handler Parameter Templates

Component name and description | Environment variable name | Notes
Previously used value | New value
For the events 'Client account created', 'Client account updated', 'Client account removed'
Login name | OLD_LOGIN_NAME | NEW_LOGIN_NAME | Required
Contact name | OLD_CONTACT_NAME | NEW_CONTACT_NAME | Required
Company name | OLD_COMPANY_NAME | NEW_COMPANY_NAME |
Phone | OLD_PHONE | NEW_PHONE |
Fax | OLD_FAX | NEW_FAX |
E-mail | OLD_EMAIL | NEW_EMAIL |
Address | OLD_ADDRESS | NEW_ADDRESS |
City | OLD_CITY | NEW_CITY |
State/province | OLD_STATE_PROVINCE | NEW_STATE_PROVINCE |
Postal/zip code | OLD_POSTAL_ZIP_CODE | NEW_POSTAL_ZIP_CODE |
Country | OLD_COUNTRY | NEW_COUNTRY |
For the events 'Domain created', 'Domain updated', 'Domain deleted'
Domain Name | OLD_DOMAIN_NAME | NEW_DOMAIN_NAME | required
For the events 'Subdomain created', 'Subdomain updated', 'Subdomain deleted'
Subdomain Name | OLD_SUBDOMAIN_NAME | NEW_SUBDOMAIN_NAME | Required
Parent domain name | OLD_DOMAIN_NAME | NEW_DOMAIN_NAME | Required
FTP account | OLD_SYSTEM_USER_TYPE | NEW_SYSTEM_USER_TYPE |
Subdomain administrator's login name | OLD_SYSTEM_USER | NEW_SYSTEM_USER |
Hard disk quota | OLD_HARD_DISK_QUOTA | NEW_HARD_DISK_QUOTA |
SSI support | OLD_SSI_SUPPORT | NEW_SSI_SUPPORT |
PHP support | OLD_PHP_SUPPORT | NEW_PHP_SUPPORT |
CGI support | OLD_CGI_SUPPORT | NEW_CGI_SUPPORT |
Perl support | OLD_MOD_PERL_SUPPORT | NEW_MOD_PERL_SUPPORT |
Python support | OLD_MOD_PYTHON_SUPPORT | NEW_MOD_PYTHON_SUPPORT |
ColdFusion support | OLD_COLDFUSION_SUPPORT | NEW_COLDFUSION_SUPPORT |
Apache::ASP support | OLD_APACHE_ASP_SUPPORT | NEW_APACHE_ASP_SUPPORT |
SSL support | OLD_SSL_SUPPORT | NEW_SSL_SUPPORT |
For the events 'Domain alias created, updated, deleted, DNS zone modified'
Domain alias name | OLD_DOMAIN_ALIAS_NAME | NEW_DOMAIN_ALIAS_NAME | Required
--- | --- | --- | ---
Domain alias switched on or off | OLD_STATUS | NEW_STATUS |
Web service for domain alias is on or off | OLD_DOMAIN_ALIAS_WEB | NEW_DOMAIN_ALIAS_WEB |
Mail service for domain alias is on or off | OLD_DOMAIN_ALIAS_MAIL | NEW_DOMAIN_ALIAS_MAIL |
Support for accessing web applications in java for domain alias visitors (on or off) | OLD_DOMAIN_ALIAS_TOMCAT | NEW_DOMAIN_ALIAS_TOMCAT |
For the events 'Physical hosting created', 'Physical hosting updated'
Domain name | OLD_DOMAIN_NAME | NEW_DOMAIN_NAME | Required
IP address | OLD_IP_ADDRESS | NEW_IP_ADDRESS |
IP type | OLD_IP_TYPE | NEW_IP_TYPE |
System user | OLD_SYSTEM_USER | NEW_SYSTEM_USER |
System user's password | OLD_SYSTEM_USER_PASSWORD | NEW_SYSTEM_USER_PASSWORD |
Shell access | OLD_SYSTEM_SHELL | NEW_SYSTEM_SHELL |
FP support | OLD_FP_SUPPORT | NEW_FP_SUPPORT |
FP-SSL support | OLD_FPSSL_SUPPORT | NEW_FPSSL_SUPPORT |
FP authoring | OLD_FP_AUTHORING | NEW_FP_AUTHORING |
FP admin login | OLD_FP_ADMIN_LOGIN | NEW_FP_ADMIN_LOGIN |
FP admin password | OLD_FP_ADMIN_PASSWORD | NEW_FP_ADMIN_PASSWORD |
SSI support | OLD_SSI_SUPPORT | NEW_SSI_SUPPORT |
PHP support | OLD_PHP_SUPPORT | NEW_PHP_SUPPORT |
CGI support | OLD_CGI_SUPPORT | NEW_CGI_SUPPORT |
Perl support | OLD_MOD_PERL_SUPPORT | NEW_MOD_PERL_SUPPORT |
Apache ASP support | OLD_APACHE_ASP_SUPPORT | NEW_APACHE_ASP_SUPPORT |
SSL support | OLD_SSL_SUPPORT | NEW_SSL_SUPPORT |
Web statistics | OLD_WEB_STATISTICS | NEW_WEB_STATISTICS |
Custom error documents | OLD_APACHE_ERROR_DOCUMENTS | NEW_APACHE_ERROR_DOCUMENTS |
Hard disk quota | OLD_HARD_DISK_QUOTA | NEW_HARD_DISK_QUOTA |
For the event 'Physical hosting deleted'
Domain name | OLD_DOMAIN_NAME | NEW_DOMAIN_NAME | Required
For the events 'Mail account created', 'Mail account deleted'
E-mail address | OLD_MAILNAME | NEW_MAILNAME | Required (in the format mailname@domain)
For the event 'Mail account updated'
E-mail address | OLD_MAILNAME | NEW_MAILNAME | Required (in the format mailname@domain)
Mailbox | OLD_MAILBOX | NEW_MAILBOX |
Password | OLD_PASSWORD | NEW_PASSWORD |
Mailbox quota | OLD_MAILBOX_QUOTA | NEW_MAILBOX_QUOTA |
Redirect | OLD_REDIRECT | NEW_REDIRECT |
Redirect address | OLD_REDIRECT_ADDRESS | NEW_REDIRECT_ADDRESS |
Mail group | OLD_MAIL_GROUP | NEW_MAIL_GROUP |
Autoresponders | OLD_AUTORESPONDERS | NEW_AUTORESPONDERS |
Mail user control panel access | OLD_MAIL_CONTROLPANEL_ACCESS | NEW_MAIL_CONTROLPANEL_ACCESS |
For the event 'Web user deleted'
Domain name | OLD_DOMAIN_NAME | NEW_DOMAIN_NAME | Required
Web user name | OLD_WEBUSER_NAME | NEW_WEBUSER_NAME | Required
For the events 'Web user created', 'Web user updated'
Domain name | OLD_DOMAIN_NAME | NEW_DOMAIN_NAME | Required
Web user name | OLD_WEBUSER_NAME | NEW_WEBUSER_NAME | Required
Web user's password | OLD_WEBUSER_PASSWORD | NEW_WEBUSER_PASSWORD |
SSI support | OLD_SSI_SUPPORT | NEW_SSI_SUPPORT |
PHP support | OLD_PHP_SUPPORT | NEW_PHP_SUPPORT |
CGI support | OLD_CGI_SUPPORT | NEW_CGI_SUPPORT |
Perl support | OLD_MOD_PERL_SUPPORT | NEW_MOD_PERL_SUPPORT |
Python support | OLD_MOD_PYTHON_SUPPORT | NEW_MOD_PYTHON_SUPPORT |
Apache ASP support | OLD_APACHE_ASP_SUPPORT | NEW_APACHE_ASP_SUPPORT |
Hard disk quota | OLD_HARD_DISK_QUOTA | NEW_HARD_DISK_QUOTA |
For the event 'Client limits updated'
Contact Name | OLD_CONTACT_NAME | NEW_CONTACT_NAME | Required
Maximum Number of Domains | OLD_MAXIMUM_DOMAINS | NEW_MAXIMUM_DOMAINS |
Maximum Amount of Disk Space | OLD_MAXIMUM_DISK_SPACE | NEW_MAXIMUM_DISK_SPACE |
Maximum Amount of Traffic | OLD_MAXIMUM_TRAFFIC | NEW_MAXIMUM_TRAFFIC |
Maximum Number of Web Users | OLD_MAXIMUM_WEBUSERS | NEW_MAXIMUM_WEBUSERS |
Maximum Number of Databases | OLD_MAXIMUM_DATABASES | NEW_MAXIMUM_DATABASES |
Maximum Number of Mailboxes | OLD_MAXIMUM_MAILBOXES | NEW_MAXIMUM_MAILBOXES |
Mailbox Quota | OLD_MAXIMUM_MAILBOX_QUOTA | NEW_MAXIMUM_MAILBOX_QUOTA |
Maximum Number of Mail Redirects | OLD_MAXIMUM_MAIL_REDIRECTS | NEW_MAXIMUM_MAIL_REDIRECTS |
Maximum Number of Mail Groups | OLD_MAXIMUM_MAIL_GROUPS | NEW_MAXIMUM_MAIL_GROUPS |
Maximum Number of Mail Autoresponders | OLD_MAXIMUM_MAIL_AUTORESPONDERS | NEW_MAXIMUM_MAIL_AUTORESPONDERS |
Maximum Number of Mailing Lists | OLD_MAXIMUM_MAIL_LISTS | NEW_MAXIMUM_MAIL_LISTS |
Maximum Number of Java Applications | OLD_MAXIMUM_TOMCAT_WEB_APPLICATIONS | NEW_MAXIMUM_TOMCAT_WEB_APPLICATIONS |
Expiration Date | OLD_EXPIRATION_DATE | NEW_EXPIRATION_DATE |
For the event 'Domain limits updated'
Domain name | OLD_DOMAIN_NAME | NEW_DOMAIN_NAME | Required
Maximum amount of disk space | OLD_MAXIMUM_DISK_SPACE | NEW_MAXIMUM_DISK_SPACE |
Maximum amount of traffic | OLD_MAXIMUM_TRAFFIC | NEW_MAXIMUM_TRAFFIC |
Maximum number of web users | OLD_MAXIMUM_WEBUSERS | NEW_MAXIMUM_WEBUSERS |
Maximum number of databases | OLD_MAXIMUM_DATABASES | NEW_MAXIMUM_DATABASES |
Maximum number of mailboxes | OLD_MAXIMUM_MAILBOXES | NEW_MAXIMUM_MAILBOXES |
Mailbox quota | OLD_MAXIMUM_MAILBOX_QUOTA | NEW_MAXIMUM_MAILBOX_QUOTA |
Maximum number of mail redirects | OLD_MAXIMUM_MAIL_REDIRECTS | NEW_MAXIMUM_MAIL_REDIRECTS |
Maximum number of mail groups | OLD_MAXIMUM_MAIL_GROUPS | NEW_MAXIMUM_MAIL_GROUPS |
Maximum number of mail autoresponders | OLD_MAXIMUM_MAIL_AUTORESPONDERS | NEW_MAXIMUM_MAIL_AUTORESPONDERS |
Maximum number of mailing lists | OLD_MAXIMUM_MAIL_LISTS | NEW_MAXIMUM_MAIL_LISTS |
Maximum number of java applications | OLD_MAXIMUM_TOMCAT_WEB_APPLICATIONS | NEW_MAXIMUM_TOMCAT_WEB_APPLICATIONS |
Expiration date | OLD_EXPIRATION_DATE | NEW_EXPIRATION_DATE |
For the events 'Mailing list created', 'Mailing list updated', 'Mailing list deleted'
Domain Name | OLD_DOMAIN_NAME | NEW_DOMAIN_NAME | Required
Mailing list name | OLD_MAIL_LIST_NAME | NEW_MAIL_LIST_NAME | Required
Mailing list enabled | OLD_MAIL_LIST_ENABLED | NEW_MAIL_LIST_ENABLED |
For the events 'Control panel user logged in', 'Control panel user logged out'
Contact name | OLD_CONTACT_NAME | NEW_CONTACT_NAME |
For the event 'Domain administrator account updated'
Allow domain administrator access | OLD_ALLOW_DOMAIN_USER_ACCESS | NEW_ALLOW_DOMAIN_USER_ACCESS |
Login Name | OLD_LOGIN_NAME | NEW_LOGIN_NAME | Required
Domain Name | OLD_DOMAIN_NAME | NEW_DOMAIN_NAME | Required
Contact Name | OLD_CONTACT_NAME | NEW_CONTACT_NAME |
Company Name | OLD_COMPANY_NAME | NEW_COMPANY_NAME |
Phone | OLD_PHONE | NEW_PHONE |
Fax | OLD_FAX | NEW_FAX |
E-mail | OLD_EMAIL | NEW_EMAIL |
Address | OLD_ADDRESS | NEW_ADDRESS |
City | OLD_CITY | NEW_CITY |
State/Province | OLD_STATE_PROVINCE | NEW_STATE_PROVINCE |
Postal/ZIP Code | OLD_POSTAL_ZIP_CODE | NEW_POSTAL_ZIP_CODE |
Country | OLD_COUNTRY | NEW_COUNTRY |
For the events 'Site application installed', 'Site application reconfigured', Site application uninstalled'
Site application package name | OLD_PACKAGE_NAME | NEW_PACKAGE_NAME | Required
Domain type (domain or subdomain) | OLD_DOMAIN_TYPE | NEW_DOMAIN_TYPE | Required
Installation path (httpdocs or httpsdocs) | OLD_DIRECTORY | NEW_DIRECTORY | Required
Installation path within the destination directory | OLD_INSTALLATION_PREFIX | NEW_INSTALLATION_PREFIX | Required
For the events 'Site application package installed', 'Site application package uninstalled'
Site application package name | OLD_PACKAGE_NAME | NEW_PACKAGE_NAME | Required
For the events 'Service stopped, started, or restarted'
Service | OLD_SERVICE | NEW_SERVICE | Required
For the events 'IP address created, changed, or deleted'
IP address | OLD_IP_ADDRESS | NEW_IP_ADDRESS | Required
IP mask | OLD_IP_MASK | NEW_IP_MASK |
Interface | OLD_INTERFACE | NEW_INTERFACE |
IP type | OLD_IP_TYPE | NEW_IP_TYPE |
For the events 'Forwarding created, changed, deleted'
Domain name | OLD_DOMAIN_NAME | NEW_DOMAIN_NAME | Required
Forwarding type | OLD_FORWARDING_TYPE | NEW_FORWARDING_TYPE |
URL | OLD_URL | NEW_URL |
For the event 'Administrator information changed'
Login name | OLD_LOGIN_NAME | NEW_LOGIN_NAME | Required
Contact name | OLD_CONTACT_NAME | NEW_CONTACT_NAME |
Company name | OLD_COMPANY_NAME | NEW_COMPANY_NAME |
Phone number | OLD_PHONE | NEW_PHONE |
Fax | OLD_FAX | NEW_FAX |
E-mail | OLD_EMAIL | NEW_EMAIL |
Address | OLD_ADDRESS | NEW_ADDRESS |
CIty | OLD_CITY | NEW_CITY |
State/Province | OLD_STATE_PROVINCE | NEW_STATE_PROVINCE |
Postal/Zip code | OLD_POSTAL_ZIP_CODE | NEW_POSTAL_ZIP_CODE |
Country | OLD_COUNTRY | NEW_COUNTRY |
For the events 'Site application installed, reconfigured, uninstalled'
Site application name | OLD_PACKAGE_NAME | NEW_PACKAGE_NAME | Required
For the events 'Client status updated'
Contact name | OLD_CONTACT_NAME | NEW_CONTACT_NAME | Required
Login name | OLD_LOGIN_NAME | NEW_LOGIN_NAME | Required
Status | OLD_STATUS | NEW_STATUS |
For the events 'Client preferences updated'
Contact name | OLD_CONTACT_NAME | NEW_CONTACT_NAME | Required
Login name | OLD_LOGIN_NAME | NEW_LOGIN_NAME | Required
Page size | OLD_LINES_PER_PAGE | NEW_LINES_PER_PAGE |
Interface skin | OLD_INTERFACE_SKIN | NEW_INTERFACE_SKIN |
For the event 'Client's IP pool changed'
Contact name | OLD_CONTACT_NAME | NEW_CONTACT_NAME | Required
IP address | OLD_IP_ADDRESS | NEW_IP_ADDRESS | Required
Status | OLD_STATUS | NEW_STATUS |
For the event 'Limit on disk space reached for the client account'
Contact name | OLD_CONTACT_NAME | NEW_CONTACT_NAME | Required
Disk space limit | OLD_MAXIMUM_DISK_SPACE | NEW_MAXIMUM_DISK_SPACE | Required
For the events 'Limit on traffic reached for the client account'
Contact name | OLD_CONTACT_NAME | NEW_CONTACT_NAME | Required
Traffic limit | OLD_MAXIMUM_TRAFFIC | NEW_MAXIMUM_TRAFFIC |
For the events 'Domain status changed'
Domain name | OLD_DOMAIN_NAME | NEW_DOMAIN_NAME | Required
Domain status | OLD_STATUS | NEW_STATUS |
For the event 'DNS zone updated for domain'
Domain name | OLD_DOMAIN_NAME | NEW_DOMAIN_NAME | Required
For the event 'Limit on disk space reached for domain'
Domain name | OLD_DOMAIN_NAME | NEW_DOMAIN_NAME | Required
Disk space limit | OLD_MAXIMUM_DISK_SPACE | NEW_MAXIMUM_DISK_SPACE |
For the event 'Limit on traffic reached for domain'
Domain name | OLD_DOMAIN_NAME | NEW_DOMAIN_NAME | Required
Traffic limit | OLD_MAXIMUM_TRAFFIC | NEW_MAXIMUM_TRAFFIC |
For the event 'License key update'
License key number | OLD_LICENSE | NEW_LICENSE | Required
License key type (Plesk, additional) | OLD_LICENSE_TYPE | NEW_LICENSE_TYPE |
License key name (for additional keys) | OLD_LICENSE_NAME | NEW_LICENSE_NAME |