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 withvirtual system patterns. The code included in the script package can be as simple as a script package 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.

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.

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.

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