-
Language:
English
-
Language:
English
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:
| 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.
| 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"/>