Creating a script for the VM

Scripts allow you to set up virtual machines automatically: install software applications, modify configuration files, and perform other operations. You can:

select a script when creating a virtual machine. It will be executed right after the operating system is installed;
start a script on the existing virtual machine.

Scripts from the ISPsystem repository are available per default.

On a Linux OS, you can run Shell scripts in bash and sh, and on a Windows OS, you can run Powershell scripts.

You can set parameters for the script. Their values will need to be entered or selected from the list when running the script. Variables can be used as parameters to be entered manually. Then, when the script is run, the value of the variable will be displayed in the parameter input field.

Script restrictions

Command shell

The platform supports execution of Shell scripts only in bash and sh. If another shell is specified in the first line of the script (for example, #!/bin/dash), the script will terminate with an error. If the first line does not contain shell information, the script will run in the default shell (in most Linux systems it's bash).

Passing a password to the script

The value of the built-in PASS variable, which contains the root password, cannot be changed when running the script. Use your own variable or parameter to pass the password to the script.

VM reboot

If the script contains a reboot command, the script will be interrupted when the command is executed. The script will not continue running after the reboot.

OS Linux update

If a Shell script contains an OS update command, block the QEMU Guest Agent software update. This software provides execution of commands on VMs and information exchange between VMs and the cluster node. Updating the QEMU Guest Agent software can affect the platform's interaction with the VM.

Command for Red Hat-based OS

yum -y update --exclude=qemu-guest-agent

Command for Debian-based OS

apt-mark hold qemu-guest-agent && apt-get update && apt-get -yy upgrade && apt-mark unhold qemu-guest-agent

If the update is run by external scripts:

Before the update commands, add lines to your script:

for Red Hat-based OS:

yum -y install yum-plugin-versionlock
yum versionlock qemu-guest-agent

for Debian-based OS:

apt-mark hold qemu-guest-agent || :
apt-get update
apt-get -yy dist-upgrade

After the update commands, add lines to your script:
- for Red Hat-based OS:
```
yum versionlock delete qemu-guest-agent
```
- for Debian-based OS:
```
apt-mark unhold qemu-guest-agent || :
```

Creating a script

To create your own script:

Go to Scripts section → For virtual machines tab → Create a script button.
Enter a script Name.
Select a script Owner. Only its owner can edit the script.
Select who will have the Access to the image:
- Owner;
- All.
If necessary, enable the Hide script contents option. Then only the owner of the script and platform administrators will be able to view the script code and create copies of it.
Specify a Description. It is displayed in the script list.
Specify Filters to run the script. The script is available to run on a VM if the conditions of all filters match. The OS tags filter is mandatory, the others are optional. Read more in Filters for running scripts.
To add more filters, click Add filter button. To delete a filter, click the icon.
If necessary, specify the requested script parameters:
1. Click Add parameter button.
2. Specify the parameter Name and Description. If you use a variable name as a parameter, its description will be added automatically.
3. For a mandatory parameter, enable the Required option.
4. To add more parameters to the script, click Add one more parameter to script button.
5. You can specify parameter values that will be offered when the script is run. To do this, click Add button:
  1. Specify Parameter value and Describe value.
  2. To add more parameters, click Add one more value button. In the right part of the window you can see how the parameter selection form will look like.
  3. Click Add button.
Select a Script type:
- Shell — for Linux family OS;
- Powershell — for Windows OS.
Enter the Script in the editor window. To expand the editor window to the full screen, press . To return to the window mode, press . The editor has an auto-complete feature. For example, if you need to insert in a script the name of an external variable, start typing and the editor will suggest endings.
External variables and parameters are specified in the script in the format ($NAME), where NAME is the name of the variable. For example, to write the VM IP address to a file, you can use the command echo ($IP) >> /tmp/ip.txt.
To send an email to the user after running the script:
1. Click Add button in the Email notification section.
2. Enter the email Subject.
3. Specify the content of the email in HTML format in the Content field. In this field, you can use the same variables and parameters that you used in the script. Read more about creating email templates in Email templates in scripts.
4. Click Preview to preview the email.
5. By default, you are offered to set up an English email template — Email for EN. If you need an email template in Russian, click Add email for RU button. If you no longer need any of the templates, click Delete the email for RU/Delete the email for EN button.
Click Create button.

Operations with scripts

To manage scripts, go to the Scripts section → For virtual machines tab → select script → menu. Possible actions:

Copy — create a copy of the script;
Edit (for custom scripts only) — change script settings;
Informantion (for ISPsystem scripts only) — change the access settings of a script
Delete (for custom scripts only).

To run scripts on a VM, go to the Virtual machines section → select VM → menu → Run script → select scripts → enter script parameters → select the order of script execution in the Start priority column → Run scripts. Read more in the article Running scripts on the VM.

To interrupt execution of the script, go to the Virtual machines section → select VM → in the Status column click the icon next to the "Executing the script" message → Abort button. You can also interrupt script execution in the VM's task list: Virtual Machines section→ select VM → Parameters button → Tasks section → click the icon in the "Execution of the script" task → Abort button.

Useful tips