Events (VDSmanager)
From ISPWiki
VDSmanager events mechanism is an additional control panel plug-in. It enables to add users' CGI-programs and scripts that start automatically once a VDSmanager function is executed. For example, you need a certain action to be performed once you have created a virtual dedicated server, such as send a welcome e-mail. Locate the script in /usr/local/ispmgr/event directory with permissions 700 and root as the owner. The name of a script should match one of the VDSmanager event, such as vds.edit.new. Use the eventlist function to get the list of the available events. For example, you can use the following shell command:
wget -O - -q "http://127.0.0.1/manager/vdsmgr?out=text&func=eventlist"
The user's CGI-program have the same input as the control panel. The corresponding set of parameters can be found in VDSmanager API.
Use the REMOTE_USER environment variable to locate a user who called the VDSmanager function, which caused execution of your CGI-program. Make sure that the user has been authorized.
To avoid errors in the user CGI-programs, these programs are executed in a separate process, and VDSmanager does not wait for their execution results.
You cannot call VDSmanager functions from the CGI-programs for the deadlocks prevention reasons.
Example
For example, you want to add a new filed for entering a welcome message into the form for a new virtual server creation. To do that, you need to create an XML-document that will describe the field:
<?xml version="1.0" encoding="UTF-8"?> <mgrdata> <metadata name="vds.edit"> <form> <field name="email" id="email" hidden="yes"> <input type="text" name="email"/> </field> </form> <jscript> if (document.frm.elid.value == \'\') fr_hs_fields([], [\'email\']); </jscript> </metadata> <lang name="en"> <messages name="vds.edit"> <msg name="email">E-Mail</msg> <msg name="hint_email">Used for sending welcome email</msg> </messages> </lang> </mgrdata>
Locate the file in /usr/local/ispmgr/etc and name it "vdsmgr_mod_name.xml". Please note, that if the XML-document contains errors, the control panel will not start!
<metadata name="vds.edit"> means that we are going to modify virtual dedicated server parameters form (the same form for creating, viewing and changing parameters).
<field name="email" id="email" hidden="yes"> means that we are going to add a hidden by default field "email".
<input type="text" name="email"/> means that we need to add a control element such as "text" called "email".
Below is the JavaScript specifying that the action should be performed, if the "elid" parameter is missing when the form is called. It is possible only if the form is used for a site creation. Hence, we can see the "email" field only when creating a new object. In this code snippet the control panel built-in JavaScript function fr_hs_fields is used. It is used to manage visibility of the form fields. The first parameter is an array of the field names to be hidden, the second one is an array of the field names to be shown. As our "email" field is hidden by default we need to add it to the second array for the field to be displayed while creating a new virtual private server.
<lang name="en"> means that we want to add messages in English (en). <messages name="vds.edit">, means we want to add messages for vds.edit. module.
Description messages. The "name" attribute for the message corresponding to the field title must match the filed name, i.e. "email". The "name" attribute of the field hint must begin with the prefix "hint_".
Write a CGI-program (script) that will send the message while creating a new virtual private server. Call it vds.edit.new.
#!/usr/bin/perl use CGI qw/:standard/; = new CGI; = (email); = (name); open(M, "|/usr/sbin/sendmail") or die("unable open sendmail"); print M "From: info\@example.com\n"; print M "To: \n"; print M "Subject: New VDS\n"; print M "Content-type: text/plain\n\n"; print M "Your VDS is ready!\n"; print M "... some welcome text ...\n\n"; close (M);
As you can see, the field values (email and domain) are transferred as CGI-script parameters. It is possible to use standard ways to address them.
Locate this script into the /usr/local/ispmgr/event directory and set permissions 700. Then restart the control panel to apply the changes:
killall vdsmgr
