Red Hat Training

A Red Hat training course is available for Red Hat JBoss Operations Network

7.7. A Reference of JBoss ON Ant Recipe Elements

7.7.1. rhq:bundle

Contains the definition for the main JBoss ON-related Ant task that is required for any Ant bundle recipe. This element defines basic information about the bundle and is the parent element for all of the specific details about what is in the bundle and how it should be provisioned.
Element Attributes

Attribute Description Optional or Required
name The name given to the bundle. Required
version The version string for this specific bundle. Bundles can have the same name, but each bundle of that name must have a unique version string. These version strings normally conform to an OSGi style of versioning, such as 1.0 or 1.2.FINAL. Required
description A readable description of this specific bundle version. Optional

Example

<rhq:bundle name="example" version="1.0" description="an example bundle">

7.7.2. rhq:input-property

Adds a property to the bundle task that defines a template token that must have its value supplied by a user at the time the bundle is deployed. This is similar to standard Ant properties.

Note

All of the system properties listed in Table 3, “System-Defined Tokens” and the Ant-specific tokens in Table 2, “Variables Defined by JBoss ON” are available to be used as templatized tokens in bundle configuration without having to set a <rhq:input-property> definition.
All input properties set some parameter that must have its value defined by a user when the bundle is provisioned on a resource, and the fields to enter those values are automatically generated in the JBoss ON UI bundle deployment wizard.
Element Attributes

Attribute Description Optional or Required
name The name of the user-defined property. Within the recipe, this property can be referred to by this name, in the format ${property_name}. Required
description A readable description of the property. This is the text string displayed in the JBoss ON bundle UI when the bundle is deployed. Required
type Sets the syntax accepted for the user-defined value. There are several different options:
  • string
  • longString
  • long
  • password
  • file
  • directory
  • boolean
  • integer
  • float
  • double
Required
required Sets whether the property is required or optional for configuration. The default value is false, which means the property is optional. If this argument isn't given, then it is assumed that the property is optional. Optional
defaultValue Gives a value for the property to use if the user does not define a value when the bundle is deployed. Optional

Example

<rhq:input-property
    name="listener.port"
    description="This is where the product will listen for incoming messages"
    required="true"
    defaultValue="8080"
    type="integer"/>

7.7.3. rhq:deployment-unit

Defines the bundle content — such as applications or configuration files — being deployed by the bundle. A deployment unit can be simple text files, archives, or a full software product, including an application server, web server, or database. A deployment unit can have multiple archive and configuration files associated with it.
Only a single deployment unit is provisioned at a time by the provisioning process, so there can be only one <rhq:deployment-unit> element in a bundle recipe.
Element Attributes

Attribute Description Optional or Required
name The name of the application. Required
manageRootDir Sets whether JBoss ON should manage all files in the top root directory (deployment directory) where the bundle is deployed. If false, any unrelated files found in the top deployment directory are ignored and will not be overwritten or removed when future bundle updates are deployed. The default is true.
Any existing content in the root directory is backed up before it is deleted, so it can be restored later. The backup directory is /home/.rhqdeployments/resourceID/backup.
Optional
preinstallTarget An Ant target that is invoked before the deployment unit is installed. Optional
postinstallTarget An Ant target that is invoked after the deployment unit is installed. Optional

Example

<rhq:deployment-unit name="appserver" preinstallTarget="preinstall" postinstallTarget="postinstall">

7.7.4. rhq:archive

Defines any archive file that is associated with deploying the application. An archive can be a ZIP or JAR file. A bundle doesn't require an archive file, so this element is optional.
Element Attributes

Attribute Description Optional or Required
name The filename of the archive file to include in the bundle.

Important

If the archive file is packaged with the Ant recipe file inside the bundle distribution ZIP file, then the name must contain the relative path to the location of the archive file in the ZIP file.
Required
exploded Sets whether the archive's contents will be extracted and stored into the bundle destination directory (true) or whether to store the files in the same relative directory as is given in the name attribute (false). If the files are exploded, they are extracted starting in the deployment directory. Post-install targets can be used to move files after they have been extracted. Optional

Example

<rhq:archive name="file.zip">
    <rhq:replace>
         <rhq:fileset>
               <include name="**/*.properties"/>
         </rhq:fileset>
    </rhq:replace>
</rhq:archive>

7.7.5. rhq:url-archive

Defines remote archive to use, which is accessed through the given URL. This is similar to rhq:archive except that the server accesses the archive over the network rather than including the archive directly in the bundle distribution file.
Element Attributes

Attribute Description Optional or Required
url Gives the URL to the location of the archive file. The archive is downloaded and installed in the deployment directory.

Note

For the bundle to be successfully deployed, the URL must be accessible to all agent machines where this bundle is to be deployed. If an agent cannot access the URL, it cannot pull down the archive and thus cannot deploy it on the machine.
Required
exploded If true, the archive's contents will be extracted and stored into the bundle destination directory; if false, the zip file will be compressed and stored in the top level destination directory.

Note

If the files are exploded, they are extracted starting in the deployment directory. Post-install targets can be used to move files after they have been extracted.
Optional

Example

<rhq:url-archive url="http://server.example.com/apps/files/archive.zip">
    <rhq:replace>
         <rhq:fileset>
               <include name="**/*.properties"/>
         </rhq:fileset>
    </rhq:replace>
</rhq:url-archive>

7.7.6. rhq:file

Contains the information to identify and process configuration files for the application which have token values that must be realized. Normally, configuration files are copied directly from the bundle package into the deployment directory. The <rhq:file> element calls out files that require processing before they should be copied to the destination. The attributes on the <rhq:file> element set the name of the raw file in the bundle distribution ZIP file and the name of the target file that it should be copied to.
Raw files can be included with the archive files that contain properties or configuration for the application. These configuration files can be templatized with user-defined or system-defined tokens, like those listed in Section 7.5, “Using Templatized Configuration Files”. Any templatized files that are included in the bundle distribution file that are templatized must be listed in the Ant recipe so that they are processed and the tokens are realized.
Element Attributes

Attribute Description Optional or Required
name The name of the raw configuration file.

Important

If the configuration file is packaged with the Ant recipe file inside the bundle distribution ZIP file, then the name must contain the relative path to the location of the file within the ZIP file.
Required
destinationFile The full path and filename for the file on the destination resource. Relative paths must be relative to the final deployment directory (defined in the rhq.deploy.dir parameter when the bundle is deployed). It is also possible to use absolute paths, as long as both the directory and the filename are specified.

Note

If the destinationDir attribute is used, the destinationFile attribute cannot be used.
Required, unless destinationDir is used
destinationDir The directory where this file is to be copied. If this is a relative path, it is relative to the deployment directory given by the user when the bundle is deployed. If this is an absolute path, that is the location on the filesystem where the file will be copied.
This attribute sets the directory for the file to be copied to. The actual file name is set in the name attribute.
If the destinationFile attribute is used, the destinationDir attribute cannot be used.
Required, unless destinationFile is used
replace Indicates whether the file is templatized and requires additional processing to realize the token values. Required

Example

<rhq:file name="test-v2.properties" destinationFile="subdir/test.properties" replace="true"/>

If neither the destinationDir nor the destinationFile attribute is used, then the raw file is placed in the same location under the deployment directory as its location in the bundle distribution.

7.7.7. rhq:url-file

As with rhq:file, contains the information to identify and process configuration files for the application which have token values that must be realized. This option specifies a remote file which is downloaded from the given URL, rather than being included in the bundle archive.
Element Attributes

Attribute Description Optional or Required
url Gives the URL to the templatized file. The file is downloaded and installed in the deployment directory.

Note

For the bundle to be successfully deployed, the URL must be accessible to all agent machines where this bundle is to be deployed. If an agent cannot access the URL, it cannot pull down the archive and thus cannot deploy it on the machine.
Required
destinationFile The full path and filename for the file on the destination resource. Relative paths must be relative to the final deployment directory (defined in the rhq.deploy.dir parameter when the bundle is deployed). It is also possible to use absolute paths, as long as both the directory and the filename are specified.

Note

If the destinationDir attribute is used, the destinationFile attribute cannot be used.
This attribute must give both the path name and the file name.
Required, unless destinationDir is used
destinationDir The directory where this file is to be copied. If this is a relative path, it is relative to the deployment directory given by the user when the bundle is deployed. If this is an absolute path, that is the location on the filesystem where the file will be copied.
This attribute sets the directory for the file to be copied to. The actual file name is set in the name attribute.
If the destinationFile attribute is used, the destinationDir attribute cannot be used.
Required, unless destinationFile is used
replace Indicates whether the file is templatized and requires additional processing to realize the token values. Required

Example

<rhq:url-file url="http://server.example.com/apps/files/test.conf" destinationFile="subdir/test.properties" replace="true"/>

If neither the destinationDir nor the destinationFile attribute is used, then the raw file is placed in the same location under the deployment directory as its location in the bundle distribution.

7.7.8. rhq:audit

Sets custom audit trail messages to use during the provisioning process. This is useful with complex recipes that perform some additional custom tasks. As the tasks are processed, the rhq:audit configuration sends information to the server about the additional processing steps and their results.
Element Attributes

Attribute Description Optional or Required
status The status of the processing. The possible values are SUCCESS, WARN, and FAILURE. The default is SUCCESS. Optional
action The name of the processing step. Required
info A short summary of what the action is doing, such as the name of the target of the action or an affected filename. Optional
message A brief text string which provides additional information about the action. Optional

Example

<rhq:audit status="SUCCESS" action="Preinstall Notice" info="Preinstalling to ${rhq.deploy.dir}" message="Another optional message">
	Some additional, optional details regarding
	the deployment of ${rhq.deploy.dir}
</rhq:audit>

7.7.9. rhq:replace

Lists templatized files, in children <rhq:fileset> elements, contained in the archive which need to have token values realized when the archive is deployed.
Any file which uses a token that must be replaced with a real value is a templatized file. When the provisioning process runs, the token value is substituted with the defined value. This element lists all of the files which are templatized; the only files which are processed by the provisioning system for token substitution are the ones listed in the <rhq:replace> element.
Example

<rhq:archive name="file.zip">
    <rhq:replace>
        <rhq:fileset>
            <include name="**/*.properties"/>
        </rhq:fileset>
    </rhq:replace>
</rhq:archive>

7.7.10. rhq:ignore

Lists files in the deployment directory which should not be deleted when a new bundle is deployed. This only applies to upgrade operations, not to the initial deployment of a bundle.
Once an application is deployed, instance-specific files — like data files or logs — can be created and should be retained if the application is ever upgraded. This element, much like <rhq:replace>, contains a list of files or directories in the instance to save.

Note

If a file is ignored in the recipe, then the file is not deleted when the bundle is deployed. However, if a file of the same name exists in the bundle, then the local file is overwritten.
Do not attempt to ignore files that are packaged in the bundle. Only files generated by the applications, such as log and data files, should be ignored by the provisioning process since they should be preserved for the upgraded instance.

Important

It is possible to deploy one bundle to a subdirectory of another bundle (such as Bundle A is deployed to /opt/myapp and Bundle B to /opt/myapp/webapp1).
In that case, set the recipe in Bundle A to ignore the directory to which Bundle B will be deployed. This prevents updates or reversions for Bundle A from overwriting the configuration from Bundle B.
Example

<rhq:ignore>
    <rhq:fileset>
        <include name="logs/*.log"/>
    </rhq:fileset>
</rhq:ignore>

7.7.11. rhq:fileset

Provides a list of files.
Two JBoss ON elements — <rhq:replace> and <rhq:ignore> — define file lists in either the archive file or the deployment directory. This element contains the list of files.
Child Element

Child Element Description
<include name=filename /> The filename of the file. For <rhq:replace>, this is a file within the archive (JAR or ZIP) file which is templatized and must have its token values realized. For <rhq:ignore>, this is a file in the application's deployment directory which should be ignored and preserved when the bundle is upgraded.

Example

<rhq:replace>
     <rhq:fileset>
         <include name="**/*.properties"/>
     </rhq:fileset>
</rhq:replace>

7.7.12. rhq:system-service

Points to a script file to launch as part of the provisioning process. This is usually an init file or similar file that can be used by the deployed application to set the application up as a system service.
Element Attributes

Attribute Description Optional or Required
name The name of the script. Required
scriptFile The filename of the script. If the script file is packaged with the Ant recipe file inside the bundle distribution ZIP file, then the scriptFile must contain the relative path to the location of the file in the ZIP file. Required
configFile The name of any configuration or properties file used by the script. If the configuration file is packaged with the Ant recipe file inside the bundle distribution ZIP file, then the configFile must contain the relative path to the location of the file in the ZIP file. Optional
overwriteScript Sets whether to overwrite any existing init file to configure the application as a system service. Optional
startLevels Sets the run level for the application service. Optional
startPriority Sets the start order or priority for the application service. Optional
stopPriority Sets the stop order or priority for the application service. Optional

Example

<rhq:system-service name="example-bundle-init" scriptFile="example-init-script"
      configFile="example-init-config" overwriteScript="true"
      startLevels="3,4,5" startPriority="80" stopPriority="20"/>