Script packages overview

Script packages can include almost any set of executable files and artifacts that are valid for the target virtual machine environment.

Script packages are added to virtual system pattern topology parts to customize their behavior.

Script packages are simple containers that contain all the required artifacts necessary to run a script. The script package is a directory compressed into a single file that is uploaded to the catalog and then associated with virtual system patterns. The code included in the script package can be as simple as a shell script or as complex as a complete product. The content of a script package is not defined by the product. The script included in the script package defines the required content for that package.

Script packages can contain license agreements that you must accept before you can deploy them as part of a virtual system pattern. For more information about license agreements, see the related links.

During deployment, script packages are transferred to the target virtual machines at a location you specify in the configuration. After they have transferred, they are extracted in that same location. When the virtual machines successfully start and are federated (if applicable), script packages are extracted. The scripts are run using the supplied command line. These files are written to the file system as the root user. If a different user requires access to these files, ensure that you set the correct user properties for the files on the guest operating system.

By default, your scripts are run on the deployed virtual machines using the root user context. You can assume that a different user context for running the script package should contain a shell script that performs the following command: su virtuser -c "./nextShellScript.sh". This command starts a second script that runs in the user context of the virtuser. By running script packages using this method, you ensure that new files, directories, and binary files are created with the appropriate user context.

If you run a script package on demand, by using the Execute now link for the script package that is in the Script Packages section of the virtual system instance page, you are prompted for Product administrator user name and password. These credentials are not used to run the script package. The script package still runs by using the root user context. These credentials are passed to the running script as environment variables with the key names ADMINUSERNAME and ADMINPASSWORD so that they can be used by the script if needed for tasks such as product administration. These environment variables are only valid in the execution environment of the script package. If no credentials are needed for the tasks that are carried out by the script package, such as the Must Gather Logs script, the script completes successfully even when these credentials are left blank.

By default, the application server is started before scripts are run. To run a script, before starting the application server, use the AUTOSTART environment variable. By default, the AUTOSTART value is set to TRUE (AUTOSTART=TRUE) and the servers are started before the scripts are run. You can change the default value to FALSE (AUTOSTART=FALSE) to run a script before the server is started.

Each script execution has an associated script status, which is determined by the exit status code from the primary executable file for the script. An exit status of zero is treated as successful execution and 2 is a warning. Any other exit status is treated as a failure. The specific error code is not logged unless you echo it to stdout or stderr. When you run a script package, the general status of Success, Fail, or Warning is indicated by an icon next to the time and date for that execution of the script. If a script package exits with a nonzero return code, the system sets the role to an error status. Any subsequent script packages are not run.

Scripts run in a prescribed order. If you are running an IBM® WebSphere® Application Server Hypervisor Edition script on multiple virtual machines, for example, then the script runs on the virtual machines in the following order:
  1. Stand-alone Nodes
  2. Deployment Manager
  3. Job Manager (version 7.0.0.x virtual system patterns only)
  4. Administrative Agent (version 7.0.0.x virtual system patterns only)
  5. Custom Nodes
  6. IBM HTTP Server
  7. On demand router

If multiple script packages are included with a virtual system pattern, by default, the scripts are run in the same order they were added to that pattern. You can change the order in which script parts are run in the pattern.

When scripts are run by the product, the system establishes a run time environment on the virtual machine using a Secure Shell (SSH) tunnel. By default, on the included Linux® based virtual machines, this is the bash directory. This includes the definition of a set of environment variables.

Environment variables that are available with the system are provided through the virtual image and after deployment are located in the script_parms.json file, which is stored in Storehouse.
Attention: Before version 2.2.2.0, these values were stored in the virtualimage.properties file. Starting in version 2.2.2.0, these values are written to the script_parms.json file.

Script packages remain on the virtual machine after they are run. As they exist on the virtual machine, you can manually run your scripts from the virtual machine after deployment.

Script package environment variables that you define might or might not also be located in the script_parms.json file, depending on your configuration settings. As a best practice, if you must run your scripts manually, you should avoid depending on script package variables being available in the script_parms.json file, and design your script package to save properties in your own file as needed.

Restriction: In some deployments, you might have a custom script package that is started before the virtual machines are fully initialized. If you are deploying a custom script package that depends on the system initialization process to be fully completed before the script runs, you might need to add some appropriate delay, or sleep time, to your script package before it runs, to allow enough time for the system initialization processes to complete.

If you want the script package to be removed after it has run, you can build the script to delete itself.

Differences between script package execution in virtual system patterns and classic virtual system patterns

In classic virtual system instances, which are deployed from classic virtual system patterns, script packages run in stage 7 (script execution) after the virtual machines are started and activated. As each script runs, a message is posted to the History section of the virtual system details pane in the user interface. When all scripts are finished, the virtual system is ready to use. If a classic virtual system pattern contains add-ons, script packages, and agents, the add-ons are started first, followed by the script packages. If maestro is enabled, then the agent is installed and started as a script package.

In virtual system instances, which are deployed from virtual system patterns, user-defined script packages run after all of the system defined script packages run and the software components on all of the virtual machines are started. One consequence of this difference is that the MustGather system script does not collect the logs for the software components and scripts that run after it is complete. If a virtual system pattern contains add-ons, script packages, and agents, the add-ons are started first, next the agent is installed and started, and then the agent is responsible for starting the script packages.

Some script package capabilities are not supported for classic virtual system patterns. The extended attributes rebootAfterExecution and rolling are not supported for use with classic virtual system patterns.