service.xml reference

When you package your own emergency fixes, you must include a service.xml file that specifies information about the emergency fix and deployment requirements.

Overview

When you create a customized emergency fix to run a maintenance package or script against existing virtual system instances, classic virtual system instances, and virtual application instances, you must include a special XML file that provides specific information about the emergency fix to IBM® Cloud Pak Software. The file must be named service.xml, and must be in the root directory of the emergency fix archive.

The service.xml file format

The following example shows the overall format of the service.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<rmsd:Service xmlns="<xmlschema_url>" 
  xmlns:xsi="<xmlschema_instance_url>"
  xmlns:rmsd="<service_description>"
  xsi:schemaLocation="<schema_location>">
  <rmsd:ImagePrereqs>
    <rmsd:prereq name="<image_name>" version="<image_version>"/>
  </rmsd:ImagePrereqs>
  <rmsd:Packages>
    <rmsd:Package name="<package_name>" type="ifix"  target="APPLICATION">
      <rmsd:EnvVariables>
        <rmsd:EnvVariable key="<var1_name>"
                          defaultValue="<default1_value>"
                          type="<var1_type>">
        </rmsd:EnvVariable>
        <rmsd:EnvVariable key="<var2_name>"
                          defaultValue="<default2_value>"
                          type="<var2_type>">
        </rmsd:EnvVariable>
      </rmsd:EnvVariables>
      <rmsd:Command name="<script command>">
        <rmsd:Arguments>
           <rmsd:Argument><arg1></rmsd:Argument>
           <rmsd:Argument><arg2></rmsd:Argument>
        </rmsd:Arguments>
        <rmsd:Log><log_directory></rmsd:Log>
        <rmsd:Location><script_location></rmsd:Location>
        <rmsd:Timeout><timeout_value_ms></rmsd:Timeout>
      </rmsd:Command>
    </rmsd:Package>
  </rmsd:Packages>
</rmsd:Service>
The rmsd:Service section defines the overall XML file, including URL pointers to the schema information:
  • xmlns="<xmlschema_url>"
  • xmlns:xsi="<xmlschema_instance_url>"
  • xmlns:rmsd="<service_description>"
  • xsi:schemaLocation="<schema_location>" (Optional)

Each additional section of the service.xml file describes information about the emergency fix and deployment requirements, and is included in the service.xml file depending on the target for the emergency fix.

The ImagePrereqs section

For emergency fixes that apply to a virtual image, specify prerequisites in the rmsd:ImagePrereqs section. These prerequisites include the operating system base images. You can specify multiple virtual images. If this information is not specified in service.xml, you must select the applicable images and versions in the Images list in Applicable To field of the catalog emergency fix panel.

For each image, specify the following attributes:
name
The name of the virtual image to which this emergency fix applies.
version
The version of the virtual image to which this emergency fix applies.
A typical rmsd:ImagePrereqs section is similar to the following example:
<rmsd:ImagePrereqs>
  <rmsd:prereq name="WebSphere Application Server 7.0.0.3" version="7.0.0.3"/>
</rmsd:ImagePrereqs>

The PluginPrereqs section

For fixes that can be applied to particular role in a virtual application plug-in, you must specify the plug-in name and version in the rmsd:PluginPrereqs section. If this information is not specified in service.xml, you must select the applicable plug-in and version in the Plugins list in Applicable To field of the catalog emergency fix panel.

For each image, specify the following attributes:
pluginname
The name of the plug-in to which this emergency fix applies.
pluginvrmf
The version of the plug-in to which this emergency fix applies.
A typical rmsd:PluginPrereqs section is similar to the following example:
<rmsd:PluginPrereqs>
  <rmsd:prereq pluginname="caching" pluginvrmf="2.0.0.3" /> 
</rmsd:PluginPrereqs>

Ensure that the values for these plug-in attributes exactly match the name and version of the plug-in to which the fix applies.

The MiddlewarePrereqs section

For fixes that can be applied to particular middleware, you must specify the middleware name and version in the rmsd:MiddlewarePrereqs section. If this information is not specified in service.xml, you must select the applicable middleware and version in the Middlewares list in Applicable to section of the emergency fix page in the catalog.

For each image, specify the following attributes:
middlewarename
The name of the middleware to which this emergency fix applies.
middlewareversion
The version of the middleware to which this emergency fix applies.
Example:
<rmsd:MiddlewarePrereqs>
  <rmsd:prereq middlewarename="DB2" middlewareversion="10.1.0.2"/>
</rmsd:MiddlewarePrereqs>

The Package section

Information about the emergency fix itself is specified in the rmsd:Package section.

The following attributes are supported for an emergency fix applied to either a virtual system or a virtual application:
Package
The name, type, and target of the archive file:
name
The name of the package, for example name="IFPK12345"
type
The type of package. The only supported value is type="ifix".
filename
The name of the uploaded compressed file containing the service.xml file.
target
The target of the package. The only supported value is target="APPLICATION".
Example:
<rmsd:Package name="IFPK12345" type="ifix" filename="<file_name>.zip" target="APPLICATION">
Command name
The command line to run your script, for example:
<rmsd:Command name="/bin/sh /tmp/update/installAppService.sh">
Arguments
This attribute is nested inside the Command attribute and specifies one or more arguments that are passed to the script when it is run. Example:
<rmsd:Arguments>
  <rmsd:Argument><arg1></rmsd:Argument>
  <rmsd:Argument><arg2></rmsd:Argument>
</rmsd:Arguments>
Location
This attribute is nested inside the Command attribute and specifies where on the virtual machine the script is extracted. Example:
<rmsd:Location>/tmp/update</rmsd:Location>
The following additional attributes are supported for an emergency fix applied only to a virtual system:
EnvVariables
The list of additional environment variables that are specific to the package in the emergency fix. Default values can be specified. If the you use the emergency fix with a classic virtual system instance, you can modify their values when the emergency fix is applied. You cannot modify the values when the emergency fix is applied to virtual system instances. When the script runs, the EnvVariables are configured as key and value pairs and stored as environment variables. Each EnvVariable consists of a variable name, an optional default value, and a type designation. Specify your EnvVariable list in the following format:
<rmsd:EnvVariables>
  <rmsd:EnvVariable key="<var1_name>"
                    defaultValue="<default1_value>"
                    type="<var1_type>">
  </rmsd:EnvVariable>
  <rmsd:EnvVariable key="<var2_name>"
                    defaultValue="<default2_value>"
                    type="<var2_type>">
  </rmsd:EnvVariable>
</rmsd:EnvVariables>
You should not specify more than 100 environment variables in this list, and each value can have a maximum of 1024 characters. The following parameters are supported in this format:
key
The name of the environment variable. If the variable is a password variable, you must include the text string PASSWORD in the variable name to prevent its value from being written to the logs in clear text.
defaultValue
The initial default value for the variable. This parameter is optional, and if specified, it must match the type (integer, string, and other types). Do not include this parameter if the type is password.
type
The type of value. Supported types include:
  • integer (Example: 980)
  • string (Example: INV2)
  • password (in this case an initial default value is not specified)
  • enum:<val1>,<val2>,..,<valn> (Example: enum:A,B,C)
  • boolean (Example: true or false)
The following example shows the various supported types of environment variables:
<rmsd:EnvVariables>
  <rmsd:EnvVariable key="ENV1" defaultValue="980" type="integer">
  </rmsd:EnvVariable>
  <rmsd:EnvVariable key="ENV2" defaultValue="INV2" type="string">
  </rmsd:EnvVariable>
  <rmsd:EnvVariable key="ENV3PASSWORD" type="password">
  </rmsd:EnvVariable>
  <rmsd:EnvVariable key="ENV4" defaultValue="A" type="enum:A,B,C">
  </rmsd:EnvVariable>
  <rmsd:EnvVariable key="ENV5" defaultValue="false" type="boolean">
  </rmsd:EnvVariable>
</rmsd:EnvVariables>
Log
This attribute is nested inside the Command attribute and specifies the location where any log information from your script is sent. Example:
<rmsd:Log>$WAS_INSTALL_ROOT/UpdateInstaller/logs</rmsd:Log>
Timeout
This attribute is nested inside the Command attribute and specifies the amount of time in milliseconds that is allowed before the script is timed out. Example:
<rmsd:Timeout>600000</rmsd:Timeout>
You can specify multiple Package sections inside a Packages section. A typical Package section for a virtual system emergency fix is similar to the following example:
<rmsd:Packages>
  <rmsd:Package name="IFPK12345" type="ifix" filename="<file_name>.zip" target="APPLICATION">
    <rmsd:EnvVariables>
      <rmsd:EnvVariable key="ENV1" defaultValue="980" type="integer">
      </rmsd:EnvVariable>
      <rmsd:EnvVariable key="ENV2" defaultValue="INV2" type="string">
      </rmsd:EnvVariable>
      <rmsd:EnvVariable key="ENV3PASSWORD" type="password">
      </rmsd:EnvVariable>
      <rmsd:EnvVariable key="ENV4" defaultValue="A" type="enum:A,B,C">
      </rmsd:EnvVariable>
      <rmsd:EnvVariable key="ENV5" defaultValue="false" type="boolean">
      </rmsd:EnvVariable>
    </rmsd:EnvVariables>
    <rmsd:Command name="/bin/sh /tmp/update/installAppService.sh">
      <rmsd:Arguments>
        <rmsd:Argument>installArg1</rmsd:Argument>
          <rmsd:Argument>installArg2</rmsd:Argument>
          <rmsd:Argument>installArg3</rmsd:Argument>
        </rmsd:Arguments>
      <rmsd:Log>$WAS_INSTALL_ROOT/UpdateInstaller/logs</rmsd:Log> 
      <rmsd:Location>/tmp/update</rmsd:Location>
      <rmsd:Timeout>600000</rmsd:Timeout>
    </rmsd:Command>
  </rmsd:Package>
</rmsd:Packages>
This example shows a similar Packages section for a virtual application emergency fix, with no environment variables or command arguments defined:
<rmsd:Packages>
  <rmsd:Package name="SpecialFix" type="ifix" filename="<file_name>.zip" target="APPLICATION">
    <rmsd:Command name="/bin/sh /tmp/update/ThisIs_eFix.sh">  
       <rmsd:Location>/tmp/update</rmsd:Location>
    </rmsd:Command>
  </rmsd:Package>
</rmsd:Packages>

Examples

The following service.xml example file shows an emergency fix for a virtual system:
<?xml version="1.0" encoding="UTF-8"?>
<rmsd:Service xmlns="<xmlschema_url>" 
  xmlns:xsi="<xmlschema_instance_url>"
  xmlns:rmsd="<service_description>"
  xsi:schemaLocation="<schema_location>">
  <rmsd:ImagePrereqs>
    <rmsd:prereq name="WebSphere Application Server 7.0.0.3" version="7.0.0.3"/>
  </rmsd:ImagePrereqs>
  <rmsd:Packages>
    <rmsd:Package name="IFPK12345" type="ifix"  target="APPLICATION">
      <rmsd:EnvVariables>
        <rmsd:EnvVariable key="WAS_USER" defaultValue="Administrator" type="string">
        </rmsd:EnvVariable>
        <rmsd:EnvVariable key="WAS_PASSWORD" type="password">
        </rmsd:EnvVariable>
      </rmsd:EnvVariables>
      <rmsd:Command name="/bin/sh /tmp/update/installAppService.sh">
        <rmsd:Log>$WAS_INSTALL_ROOT/UpdateInstaller/logs</rmsd:Log> 
        <rmsd:Location>/tmp/update</rmsd:Location>
        <rmsd:Timeout>600000</rmsd:Timeout>
      </rmsd:Command>
    </rmsd:Package>
  </rmsd:Packages>
</rmsd:Service>
The following service.xml example file shows an emergency fix for a virtual application plug-in:
<?xml version="1.0" encoding="UTF-8" ?> 
  <rmsd:Service xmlns="<xmlschema_url>"
   xmlns:xsi="<xmlschema_instance_url>"
   xmlns:rmsd="<service_description>"
   xsi:schemaLocation="<schema_location>">
  <rmsd:PluginPrereqs>
    <rmsd:prereq pluginname="caching" pluginvrmf="2.0.0.3" /> 
  </rmsd:PluginPrereqs>
  <rmsd:Packages>
    <rmsd:Package name="SpecialFix" type="ifix" target="APPLICATION">
      <rmsd:Command name="/bin/sh /tmp/update/ThisIs_eFix.sh">  
         <rmsd:Location>/tmp/update</rmsd:Location>   
      </rmsd:Command>
    </rmsd:Package>
  </rmsd:Packages>
</rmsd:Service>