Pre and Post Domain Modification Scripts

Introduction to Modification Scripts
-----------------------------

Virtualmin provides a method for you to have your own scripts (typically shell scripts, but Perl and Python also work) run before or after a virtual server is created, modified or deleted.

This can be useful if you want to have some setup performed for each new domain that is beyond Virtualmin's built-in capabilities. They can also be used to validate changes made by a user before they happen, such as creation of a domain with settings that are inappropriate for your system.

Virtualmin lets you specify a script to be run before any action is performed, and a separate script to be run after. If the pre-change script fails (by returning a non-zero exit status), whatever action was going to happen will be blocked.

Example Scripts
-------------

Let's imagine you wanted each new virtual server to have a file it is home directory downloaded from some website. A post-creation script to implement this would look like :


#!/bin/sh
if [ "$VIRTUALSERVER_ACTION" = "CREATE_DOMAIN" ]; then
cd $VIRTUALSERVER_HOME
wget -O somefile.tar.gz "http://yourdomain.com/somefile.tar.gz"
chown $VIRTUALSERVER_USER:$VIRTUALSERVER_GROUP somefile.tar.gz
fi

If you had some external database that you wanted each new domain user to have an account in, you could automate this with a script like :


#!/bin/sh
if [ "$VIRTUALSERVER_PARENT" = "" ]; then
if [ "$VIRTUALSERVER_ACTION" = "CREATE_DOMAIN" ]; then
/usr/bin/add-to-database.pl $VIRTUALSERVER_USER $VIRTUALSERVER_PASS
fi
if [ "$VIRTUALSERVER_ACTION" = "DELETE_DOMAIN" ]; then
/usr/bin/remove-from-database.pl $VIRTUALSERVER_USER
fi
fi

Setting Pre and Post Modification Scripts
-----------------------------------

Once you have written a script, you can tell Virtualmin which scripts to run before or after some action is performed as follows :

1. Login as `root` and go to *System Settings* -> *Virtualmin Configuration*.
2. Select the *Actions upon server and user creation* category.
3. In the *Command to run before making changes to a server* field enter the full path to your pre-modification command, if any.
4. In the *Command to run after making changes to a server* field, enter the full path to the post-modification command.
5. Click *Save*.

Make sure the script(s) are executable, or else Virtualmin will not be able to run them.

Variables Available In Scripts
------------------------

Every attribute of a virtual server is available via environment variables, all of which start with the `$VIRTUALSERVER_` prefix. These are the same variables that can be used in email and other templates, as documented on the Template Variable Listing page. However, all script variables have `$VIRTUALSERVER_` at the start, like `$VIRTUALSERVER_DOM` or `$VIRTUALSERVER_PASS`.

The action being performed can be determined by looking at the `$VIRTUALSERVER_ACTION` environment variable, which will be set to one of :

CREATE_DOMAIN A new virtual server is being created
MODIFY_DOMAIN Some attribute of a virtual server is being changed
DELETE_DOMAIN A virtual server has been deleted
DISABLE_DOMAIN The virtual server is being temporarily disabled
ENABLE_DOMAIN The virtual server is being re-enabled
DBNAME_DOMAIN The database login for a virtual server is being changed
DBPASS_DOMAIN The database password for a virtual server is being changed
RESTORE_DOMAIN A virtual server is being restored from a backup