User Hooks

warning

When running Lua scripts, administrator gets the access to all file system within the Dr.Web Server folder and some system commands on a computer with Dr.Web Server installed.

To forbid the access to the user hooks, disable the Edit Dr.Web Server configuration and repository configuration permission for the correspondent administrator (see Administrators and Administrative groups).

User hooks, implemented as a Lua scripts, are meant for automation of the administrator work enabling quicker performance of certain tasks of Dr.Web Server.

info

User hooks are located in the following subfolder of the Dr.Web Server installation folder:

for Windows OS: var\extensions

for FreeBSD OS: /var/drwcs/extensions

for Linux OS: /var/opt/drwcs/extensions

After the Dr.Web Server installation, pre-installed user hooks are located in this folder.

It is recommended to edit user hooks via the Control Center.

warning

Before updating Dr.Web Server, save user procedures and scripts. Please note that when upgrading to a newer version of Dr.Web Server, user procedures and scripts that worked in the previous version may not work. If a problem occurs, contact technical support.

To configure user hooks execution

1.Select the Administration item in the main menu of the Control Center.

2.In the opened window, select the User hooks item in the control menu. User hooks settings window will be opened.

info

A detailed description of user procedures and their parameters is given in Appendices, Appendix M. User Hooks.

Hooks Tree

Hooks hierarchical list displays the tree view, nodes of which are hook groups and user hooks included into them.

Initially, hooks tree contains the following pre-installed groups:

Examples of the hooks—contains templates of all available user hooks. On the base of these templates you can create your own user hooks. You cannot edit or execute the hook templates.

IBM Syslog—contains templates of user hooks used in integration with IBM Tivoli system. Events corresponding to the enabled hooks, are written in the Syslog format.

All events are written into one file on the following path:

for Windows OS:
var\export\tivoli\syslog\drwcs_syslog.log

for FreeBSD OS:
/var/drwcs/export/tivoli/syslog/drwcs_syslog.log

for Linux OS:
/var/opt/drwcs/export/tivoli/syslog/drwcs_syslog.log

IBM W7Log—contains templates of user hooks used in integration with IBM Tivoli system. Events corresponding to the enabled hooks, are written in the IBM W7Log XML format.

For each event, the separate file is created on the following path:

for Windows OS:
var\export\tivoli\w7log\<event_name>_<unix_timestamp>

for FreeBSD OS:
/var/drwcs/export/tivoli/w7log/<event_name>_<unix_timestamp>

for Linux OS:
/var/opt/drwcs/export/tivoli/w7log/<event_name>_<unix_timestamp>

The icon of the tree element depends on the type and status of this element (see table below).

Icons of elements in the hooks tree

Icon

Description

Hooks groups

icon-hook-group-enabled

Hooks group for which hook execution is enabled.

icon-hook-group-disabled

Hooks group for which hook execution is disabled.

Hooks

icon-hook-enabled

Hook is enabled to execute.

icon-hook-disabled

Hook is disabled to execute.

Hooks Tree Managing

To manage objects in the hooks tree, use the following elements of the toolbar:

icon-add-object—drop-down list for adding an element to the hooks tree:

icon-hook-add Add hook—add a new user hook.

icon-add-group Add hooks group—add a new user group for placing hooks in it.

icon-general-remove-object Remove selected objects—remove user hook or hooks group which is selected in the hook tree.

icon-hook-enable Enable hook execution—the same action is performed in the hooks editor if you set the Enable hook execution flag. See also Hooks activating.

icon-hook-disable Disable hook execution—the same action is performed in the hooks editor if you clear the Enable hook execution flag. See also Hooks activating.

Hooks Groups Managing

To create a new group

1.On the toolbar, select icon-add-objecticon-add-group Add hooks group.

2.In the opened window, specify the following parameters:

Set the Enable hook execution flag to activate hooks which will be included into this group. See also Hooks activating.

In the Group name field, specify an arbitrary name for the creating group.

3.Click Save.

To change the order of groups using

1.In the hooks tree, drag and drop the hooks group and place it in the necessary order relative to the other groups.

2.The order of hooks usage is automatically changed after changing groups order: the first will be performed the hooks from the groups that are placed higher in the hooks tree.

To move a hook to the other group

1.In the hooks tree, select a hook you want to move.

2.On the opened properties pane, in the Parent group drop-down list, select the group into which you want to move the hook.

3.Click Save.

Hooks Managing

To create a new hook

1.On the toolbar, select icon-add-objecticon-hook-add Add hook.

2.In the opened window, specify the following parameters:

Set the Enable hook execution flag to activate the creating hook. See also Hooks activating.

In the Parent group drop-down list, select the group into which you want to place the creating hook. Further, you can move the hook into other group—see above.

In the Hook drop-down list, select the hook type. The hook type defines an action for which the hook will be called.

In the Hook text field, enter the Lua script which will be executed when the hook called.
The Information on hook subsection contains an action for which the hook will be called; information whether the Dr.Web Server database is available or not for this hook; and also contains the lists of input parameters and returned values for this type of hook.

3.Click Save.

To edit a hook

1.In the hooks tree, select a hook you want to edit.

2.In the right part of the window, the properties pane for this procedure automatically opens. You can edit all parameters which are specified on creating the hook except the Hook parameter. This parameter defines an action for which the hook will be called, and cannot be edited after the hook has been created.

3.Click Save.

Hooks Activation

Activation of hooks and hooks groups defines whether the hooks will be executed on corresponding event or not.

To activate a hook or a group of hooks

1.In the hooks tree, select a hook or a hooks group you want to activate.

2.Perform one of the following actions:

On the toolbar, click icon-hook-enable Enable hook execution.

In the right part of the window on the properties pane of the selected object, set the Enable hook execution flag if it is cleared. Click Save.

Hooks activation features

To execute a hook on corresponding event, the following is necessary:

a)the hook itself must be activated;

b)the group that contains the hook must be activated.

info

If a hooks group is disabled, its hooks will not be executed even if they are activated.

On group activating, only whose hooks will be executed that are directly activated.