Skip Headers

Oracle® VM Template Builder Installation and User's Guide Release 2.1 Part Number E14391-01 |
Home | Book List | Contents | Index | Contact Us

Previous | Next
| View PDF

# 7 Creating Template Scripts

You can create application software configuration and clean up scripts to package with Oracle VM Template Builder templates. Oracle VM Template Builder includes a function library in all templates and provides some standard configuration on templates. The default configuration and function library are a useful starting point for developing application specific scripts.

This Chapter discusses the guest virtual machine configuration processes that occur when a guest virtual machine created from a template starts up, and how to enable application specific configuration with template scripts. This Chapter contains:

- Configuring the Guest Virtual Machine at Start Up

- Template Configuration Settings

- Template Configuration Scripts

- Template Clean Up Scripts

- Testing Template Scripts

- Configuration Script Function Library

## 7.1 Configuring the Guest Virtual Machine at Start Up

The ovm-template-config RPM (included with Oracle VM Template Builder) includes a guest virtual machine configuration script, /usr/sbin/oraclevm-template.sh. This script configures a guest virtual machine's operating system if no application-specific scripts are found. If an application-specific script is found, the oraclevm-template script calls that script to perform the operating system and application software configuration. If an application software script is required, the template developer should develop it and package it into the template.

The process of starting a guest virtual machine created from a template, and the subsequent configuration options is shown in Figure 7-1, "Guest virtual machine start up and configuration process".

Figure 7-1 Guest virtual machine start up and configuration process

Description of "Figure 7-1 Guest virtual machine start up and configuration process"

When a guest virtual machine created from a template is started up, the following script is automatically run:

/etc/rc.d/init.d/oraclevm-template

If it is the first time the guest virtual machine is started, the init.d script calls the following script to perform the configuration:

/usr/sbin/oraclevm-template --config

If it is not the first time the guest virtual machine is started, this script is not called. This way the configuration is performed only once. The RUN_TEMPLATE_CONF parameter in the template configuration file, /etc/sysconfig/oraclevm-template, controls whether the configuration script is run. See Section 7.2, "Template Configuration Settings" for information on the template configuration settings.

The `/usr/sbin/oraclevm-template --config` script either starts an interactive session on the guest virtual machine to configure the operating system, or calls any application software-specific configuration scripts you include with the template. You can run this script on the guest virtual machine at any time. You must be the root user to run this script. See "oraclevm-template" in Appendix A, "Command Line Tools" for more information on the oraclevm-template script options.

The template configuration script configures the operating system, not the software installed on it. You can create application software-specific scripts to include in the template, and the template configuration script can call and run these scripts. The template configuration script:

- Regenerates the up2date UUID

- Regenerates the SSH host key

- If an application software configuration script is included, calls and runs this script

- If no application software configuration script is included, calls `/usr/sbin/oraclevm-template --config` to set up the network to use either DHCP or a static IP address

See Section 7.3, "Template Configuration Scripts" for information creating application software configuration scripts.

You can also create a script to perform any post installation configuration, and to clean up logs, temporary files and cache. See Section 7.4, "Template Clean Up Scripts" for information on clean up scripts.

## 7.2 Template Configuration Settings

There are two important parameters that control the configuration of a guest virtual machine created from a template:

- RUN_TEMPLATE_CONF: Controls whether it is the first time the guest virtual machine is started up, and whether to configure the guest virtual machine.

- TEMPLATE_CONFIG_SCRIPT: Sets the location of any application software script, if required.

These configuration options are set in the template configuration file:

/etc/sysconfig/oraclevm-template

Note:

You should not edit this file yourself. This file is updated by Oracle VM Template Builder and by the oraclevm-template command-line interface.

There is also a third parameter in the template configuration file, TEMPLATE_CLEANUP_SCRIPT. This sets the location of any application software clean up script, if required. This parameter is not called during start up of a guest virtual machine created from a template, but can be called from the guest's command line to perform any clean up actions you might need.

### 7.2.1 RUN_TEMPLATE_CONF

The RUN_TEMPLATE_CONF parameter is the most important, as it controls whether to perform the guest virtual machine configuration. This parameter is set automatically to YES when you create a template, and then set to NO after a guest virtual machine created from the template is first started up. Setting this parameter to YES runs the configuration script and is the default when the template is created. Setting this parameter to NO skips the configuration script.

### 7.2.2 TEMPLATE_CONFIG_SCRIPT

The TEMPLATE_CONFIG_SCRIPT parameter sets the location of the application software configuration script.

This parameter is automatically set in the configuration file when you create a template using the location you set in the Template configuration script field on the Additional Packages screen. If you do not enter a script location in the template creation wizard, Oracle VM Template Builder uses the default value:

/u01/oraclevm-template.sh

The default location for the application software script is not the system disk, but a separate (second) disk (/u01). If you do not include a separate disk, and do not enter a location on the system disk, this parameter is ignored.

Note:

There is no default script provided in this location. It must be provided by the template developer, if required. If you do not provide a script in this location, then no application specific configuration is performed.

### 7.2.3 TEMPLATE_CLEANUP_SCRIPT

The TEMPLATE_CLEANUP_SCRIPT parameter sets the location of the template clean up script. This parameter is not required for template deployment, but may be useful to edit or clean up the guest virtual machine after a guest has been configured.

This parameter is automatically set in the configuration file when you create a template using the location you set in the Template clean up script field on the Additional Packages screen. If you do not enter a script location in the template creation wizard, Oracle VM Template Builder uses the default value:

/u01/template-cleanup.sh

The default location for the clean up script is not the system disk, but a separate (second) disk (/u01). If you do not include a separate disk, and do not enter a location on the system disk, this parameter is ignored.

Note:

There is no default script provided in this location. It must be provided by the template developer, if required. If you do not provide a script in this location, then no application specific clean up is performed.

## 7.3 Template Configuration Scripts

You can create your own scripts to configure the software applications in a guest virtual machine created by a template. These scripts can perform any software configuration, such as setting environment variables, creating users, running other scripts, editing system files, starting services, and so on. You can include the script in a template with the template creation wizard.

Application software configuration scripts must be packaged as part of an RPM and added to the template by the template developer. The RPM can be added to the template in the Additional Packages screen in the template creation wizard. The RPM is then installed when the operating system is created in the guest virtual machine created from the template. To make sure the script is run when the guest virtual machine is first started, you should include the full path to the configuration script in the Template configuration script field on the Additional Packages screen. This is the location of the script when it is installed by the RPM on the guest virtual machine created from the template.

Note:

Creating and packaging an RPM is beyond the scope of this book.

A log is created in the guest virtual machine created by the template to output any errors or messages when these scripts are run. The log is located at:

/var/log/oraclevm-template.log

There are some template script functions that you can call from an existing function library located on Oracle VM Template Builder guest virtual machine.

Section 7.6, "Configuration Script Function Library" lists the functions you can call in your configuration scripts. Examples of calling and using the functions are included in Appendix B, "Template Script Examples".

## 7.4 Template Clean Up Scripts

You can create your own script to clean up the operating system and applications in a guest virtual machine created from a template. A clean up script may be useful to reset the guest virtual machine to its original state (before running any configuration script), so you can run the configuration script again. This might be useful in a template testing scenario. You may also want to remove any temporary files, or clear any cache.

Clean up scripts must also be packaged as part of an RPM and added to the template by the template developer. The RPM can be added to the template in the Additional Packages screen in the template creation wizard. The RPM is then installed when the operating system is created in the guest virtual machine created from the template. You should include the full path to the clean up script in the Template clean up script field on the Additional Packages screen. This is the location of the script when it is installed by the RPM on the guest virtual machine created from the template.

The clean up script is not automatically run when a guest virtual machine is created from a template. You must manually run your clean up script in the guest virtual machine using the command:

    # /usr/sbin/oraclevm-template --cleanup

## 7.5 Testing Template Scripts

It is often useful to test your template configuration scripts as you develop them. To do this, you should deploy the template and start the guest virtual machine. The first time the guest is started the template configuration script is run. To run the configuration script again, you must set the template configuration file to enable the script to run (that is, set RUN_TEMPLATE_CONF to YES):

    # /usr/sbin/oraclevm-template --enable

You can then run the template configuration script using:

    # /usr/sbin/oraclevm-template --config

To perform any operating system or application software clean up, such as resetting variables, removing temporary files or cache, you can use a clean up script. This script is also configured in the template configuration file. You can run the clean up script using:

    # /usr/sbin/oraclevm-template --cleanup

The clean up script is not run automatically when the guest virtual machine is started. It must always be run manually.

The full list of parameters for the template configuration script included in "oraclevm-template" in Appendix A, "Command Line Tools".

## 7.6 Configuration Script Function Library

There are some functions available in the configuration script function library installed on all guest virtual machines created from templates. You can call these functions in your configuration and clean up scripts. The function library is located at:

/usr/lib/oraclevm-template/functions

This section lists the functions you can call in your application software and clean up scripts. Examples of scripts using these functions are given in Appendix B, "Template Script Examples".

ovm_configure_network [dhcp [hostname]] | [static] | [ip_address netmask gateway dns_server hostname]

  Sets the guest virtual machine network configuration options.

  Setting this parameter to dhcp configures the guest virtual machine to use DHCP. You can set a host name with the hostname parameter, for example:

      ovm_configure_network "dhcp"

  or

      ovm_configure_network "dhcp" "myhost.example.com"

  Setting this parameter to static configures the guest virtual machine to use a static IP address. You are prompted to enter the static IP information during the initial guest start up, for example:

      ovm_configure_network "static"

  To set a static IP address, enter the ip_address, netmask, gateway, dns_server, and hostname.

      ovm_configure_network "192.168.2.100" "255.255.255.0" "192.168.2.1" "192.168.2.1" "myhost.example.com"

  If you do not enter any parameters, you are prompted to use either DHCP or enter a static IP address when the guest virtual machine starts up for the first time.

ovm_cleanup_os

  Cleans up the guest's operating system and resets the network to use DHCP. For a full list of the actions performed by this function, see the --cleanup option in the oraclevm-template command in Appendix A, "Command Line Tools".

ovm_disable_firewall

  Disables the firewall on the guest virtual machine.

press_anykey

  Pauses execution of the script and waits for the user the press any key before continuing.

ovm_error message

  Echoes message to the screen and writes it to the log file.

ovm_info message

  Echoes message to the screen and writes it to the log file.

ovm_warn message

  Echoes message to the screen and writes it to the log file.