How the system behavior changes depending on user actions, events

ISPsystem software products allow you to perform custom operations during certain events and influence the request handling procedure (e.g. implement additional data validation or authentication).

You will need to perform the following operations:

• Write a script (an event handler)
• Register your script handler

Let's consider an example of how to create/delete a user account in Samba after this user has been created/deleted in ISPmanager

1) Create the /usr/local/mgr5/addon/samba.pl file handler

#!/usr/bin/perl
use CGI;
my $Q = new CGI;
$func = $Q->param("func");
$elid = $Q->param("elid");
if ($func eq "user.add") {  
    if ($Q->param("sok") && $elid eq "") {
    # user is created    
        $name = $Q->param("name");    
        $password = $Q->param("passwd");
        system("(echo \"$password\"; echo \"$password\") | smbpasswd -a $name");  
    }
} elsif ($func eq "user.delete") {
     # users are deleted
     @all_users = split(", ", $elid);
     for (@all_users) {
       system("smbpasswd -x $_");
     }
}
print "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<doc/>\n";

2) Set permissions for the file handler chmod 750 /usr/local/mgr5/addon/samba.pl chown 0:0 /usr/local/mgr5/addon/samba.pl

3) Create a file to describe our plug-in /usr/local/mgr5/etc/xml/ispmgr_mod_samba.xml

<?xml version="1.0" encoding="UTF-8"?>
<mgrdata>
 <handler name="samba.pl" type="cgi">
   <event after="yes" name="user.add" postdata="yes"/>
   <event after="yes" name="user.delete" postdata="yes"/>
 </handler>
</mgrdata>

4) Restart ISPmanager

/usr/local/mgr5/sbin/mgrctl -m ispmgr exit

5) If everything has been configured correctly, in /usr/local/mgr5/var/ispmgr.log you will see something like that

action EXTINFO Register event 'samba.pl' for action 'user.edit'
action EXTINFO Register event 'samba.pl' for action 'user.delete'

6) If the CGI library is not installed you can execute the following command to install it (on CentOS): 

yum install perl-CGI

Otherwise, increase the logging level by adding the line into the /usr/local/mgr5/etc/debug.conf file

 *.external 9

and restart ISPmanager. Entries with the external prefix will be added into the log file

external WARNING Addon 'addon/samba.pl' is not executable

Let's consider the above steps in more details

Plug-in description

The above example we run the script while executing certain functions of the control panel. Let's consider the following block

   <handler name="samba.pl" type="cgi">
     <event after="yes" name="user.edit" postdata="yes"/>
     <event after="yes" name="user.delete" postdata="yes"/>
   </handler>

the handler tag describes our event handler (script), samba.pl is the name of the script. All the scripts must locate in the /usr/local/mgr5/addon directory

type="cgi" indicates that a method, which is used for common CGI-scripts to send data to the script.

The event tags define the functions that will be excuted when running our script. The after="yes" attribute indicates that our script will run after the main function has been executed. You can find internal names of required functions in the article List of functions and parameters.

Handler

As we use one and the same handler for multiple functions, we need to know, which function initiated the script, so we use the func parameter

$func = $Q->param("func");

depending on its value, we execute different blocks.

user.edit - create a user. Actually, this function is called to get user data, save modified parameters, and create a new user. How to define the action that is currently running:

• the sok parameter is empty or not present - user data are requested, a username is specified in the elid parameter.
• the sok parameter is not empty (usually, yes or ok; the panel doesn't check its value) and the elid parameter is not empty - the user edit function is called, the name of the user is specified in the elid parameter.
• the sok parameter is not empty, the elid parameter is empty - the user creation function is called. We check this action in the entry

 if ($Q->param("sok") && $elid eq "") {

The above scheme with sok and elid parameters is valid for creation/modification of other objects.

Then we receive the parameter values and execute the external function, which will perform the required operations.

user.delete - delete a user. This is a group operation (multiple users can be deleted at the same time), that;s why the elid parameter can contain several names separated by ", " (comma and space). An array of users to be deleted will be created.

@all_users = split(", ", $elid);

execute the external function to delete each user from the password base in Samba.

The handler sends an XML to stdout. If the result is not required (like in our example), an empty valid XML can be returned.

 print "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<doc/>\n";