18 Oracle Tuxedo Applications Packing and Deployment

This topic contains the following sections:

• Overview
  
• How to Deploy/Undeploy Tuxedo Applications
  

18.1 Overview

This feature provides a centralized control platform to allow users to automatically deploy/undeploy one Tuxedo application (domain) on different remote machines using a set of new commands on the master node of domain. Deployment process typically contains several steps: application packages distribution, Tuxedo system environment setup, Tuxedo configuration, Tuxedo system booting and so on.

• Components
  
• Constraints
  

18.1.1 Components

This feature contains the following main components:

• Application Packages Repository
• Deployment Repository
• New-added Tuxedo commands tmcrdom and tmdeldom
• Enhanced Tuxedo tlisten daemon.

The relationship among these components is illustrated in the following figure:

Figure 18-1 Applications Packaging and Deployment Component Relationship

Application Packages Repository

It is a place in NFS (Network File System). Users need to maintain (add/delete) their Application Packages in this place by themselves. This place can be accessed by all the compute nodes which will be deployed the Tuxedo Application to.

Deployment Repository

It is a place in NFS (Network File System). This feature will maintain all the domains' information generated by this feature itself in this place. This place can be accessed by all the compute nodes which will be deployed the Tuxedo Application to.

New-added Tuxedo Commands

Two new added Tuxedo commands, which are responsible for creating domain, configuring domain, connecting with tlisten to do the deployment tasks and so on.

Enhanced tlisten daemon

This daemon will do the real deployment tasks on every compute node once it receives the Tuxedo deployment command notification.

To use this feature, first, the users need to allocate two big enough disk space or something like this to act as the Application Packages Repository and Deployment Repository on the NFS. And make sure the two places are accessible by all the Tuxedo System such as its new added commands, tlisten and so on. Second, the Tuxedo System must have been installed on every compute node which the Tuxedo Application will be deployed to. Last, you need to start up tlisten on every compute nodes. All the Tuxedo servers' running dependent libraries, such as Data Base client libraries, are not in this feature's deployment scope, it needs the customers themselves to assure their availabilities.

18.1.2 Constraints

This feature doesn't support to deploy machine level ENVFILE (which is specified in UBBCONFIG MACHINES section by ENVFILE parameter), groups level ENVFILE, servers level ENVFILE, servers level RCMD file to other directories than APPDIR.

The JAVA JDK has been installed on the master node on which will run the tmcrdom command.

18.2 How to Deploy/Undeploy Tuxedo Applications

• Introduction to Application Package Organization and Contents
  
• Uploading/Deleting an Application Package
  
• Creating and Deploying a Domain
  
• Undeploying a Domain
  

18.2.1 Introduction to Application Package Organization and Contents

A Tuxedo application (domain), as defined in a TUXCONFIG (UBBCONFIG) configuration file, is the set of machines, groups, servers, and other resources. It can exist on a single machine or cross multiple network-connected machines. For this feature, to deploy the whole Tuxedo application, users need to add their Application Packages to the Application Packages Repository by themselves first. One Application Package is an entity which holds all the binary or non-binary files referenced by one or more groups defined in a UBBCONFIG file. That means, every Application Package is mapped to one or more groups defined in a UBBCONFIG file, and all these groups must belong to the same machine in UBBCONFIG. So a Tuxedo application can consist of one or more application packages. Also every Application Package can be repeatedly deployed to one or more domains.

The application package is a user generated .zip file and can have several tiers in it. For example:

Figure 18-2 Application Package

Every Application Package is required to contain a file named "Properties.xml" in Tier1. This file is a group level's part UBBCONFIG file. It contains some properties in GROUPS, RMS, SERVERS, and SERVICES sections of a complete UBBCONFIG file and is mainly used to describe the relationship and parameters of all the servers within this package's groups. The Properties.xml file will be used to generate the ultimate UBBCONFIG file when decide to deploy this package to a machine using tmcrdom and its content can be modified in the according deployment plan.

All the items in the GROUPS, RMS, SERVERS, SERVICES section of UBBCONFIG are divided into four categories:

Mandatory and Changeable

It is a kind of index value. The user must fill it in the Properties.xml file, but it will be replaced by the value specified in the deployment plan when using tmcrdom command.

Optional and Unchangeable

If needed, it must be filled by the user in the Properties.xml file. And it will not allow to modify it when assemble the UBBCONFIG. That means, this kind of parameter can only appear in the Properties.xml if needed, and can not appear in the deployment plan.

Mandatory and Unchangeable

It must be filled by the user in the Properties file, and its value will not be modified when assemble the UBBCONFIG.

Forbidden

It can't be filled in the Application Packages' Properties.xml file. The user will fill it in the deployment plan when assemble the UBBCONFIG if needed.

Table 18-1 GROUPS Section Properties

GROUPS Section
Items	Category
GROUPNAME	Mandatory and Changeable
GRPNO = number	Mandatory and Changeable
LMID = string_value1 [,string_value2]	Forbidden
ENVFILE = string_value	Optional and Unchangeable ENVFILE must be a relative path of application package, tmcrdom will add absolute path to it
TMSNAME = string_value	Optional and Unchangeable
MRM = {Y | N}	Optional and Unchangeable
SIGNATURE_REQUIRED = {Y | N}	Optional and Unchangeable
ENCRYPTION_REQUIRED = {Y | N}	Optional and Unchangeable
OPENINFO = string_value	Forbidden
CLOSEINFO = string_value	Forbidden
TMSCOUNT = number	Forbidden
SEC_PRINCIPAL_NAME = string_value	Forbidden
SEC_PRINCIPAL_LOCATION = string_value	Forbidden
SEC_PRINCIPAL_PASSVAR = string_value	Forbidden
REQUEST_VERSION	Forbidden
VERSION_RANGE	Forbidden
VERSION_POLICY	Forbidden

Table 18-2 RMS Section Properties

RMS Section
Item	Category
RMSNAME	Mandatory and Changeable
RMID = number	Mandatory and Changeable
TMSNAME = string_value	Optional and Unchangeable
OPENINFO = string_value	Forbidden
CLOSEINFO = string_value	Forbidden
TMSCOUNT = number	Forbidden
AUTO = {Y | N}	Forbidden
SRVGRP	Forbidden

Table 18-3 SERVERS Section Properties

SERVERS Section
Item	Category
SRVID = number	Mandatory and Changeable
AOUT	Mandatory and Unchangeable. It must be a relative path of application package, tmcrdom will add absolute path to it.
ENVFILE = string_value	Optional and Unchangeable. It must be a relative path of application package, tmcrdom will add absolute path to it.
RCMD = string_value	Optional and Unchangeable. It must be a relative path of application package, tmcrdom will add absolute path to it.
CONV = {Y | N}	Optional and Unchangeable
CLOPT = string_value	Forbidden
SEQUENCE = number	Forbidden
RQADDR = string_value	Forbidden
MIN = number	Forbidden
MAX = number	Forbidden
RQPERM = number	Forbidden
REPLYQ = {Y | N}	Forbidden
RPPERM = number	Forbidden
MAXGEN = number	Forbidden
GRACE = number	Forbidden
RESTART = {Y | N}	Forbidden
SYSTEM_ACCESS = identifier[,identifier]	Forbidden
MAXDISPATCHTHREADS = number	Forbidden
MINDISPATCHTHREADS = number	Forbidden
THREADSTACKSIZE = number	Forbidden
SEC_PRINCIPAL_NAME = string_value	Forbidden
SEC_PRINCIPAL_LOCATION = string_value	Forbidden
SEC_PRINCIPAL_PASSVAR = string_value	Forbidden
SICACHEENTRIESMAX = string_value	Forbidden
CONCURR_STRATEGY=PER_REQUEST	Forbidden
CONCURR_STRATEGY = PER_OBJECT	Forbidden

Table 18-4 SERVICES Section Properties

SERVICES Section
Item	Category
SVCNM	Forbidden
BUFTYPE = "type1[:subtype1[,subtype2 . . . ]] [;type2[:subtype3[, . . . ]]] . . ."	Forbidden
SIGNATURE_REQUIRED = {Y | N}	Forbidden
ENCRYPTION_REQUIRED = {Y | N}	Forbidden
LOAD = number	Forbidden
PRIO = number	Forbidden
BUFTYPECONV = {XML2FML | XML2FML32}	Optional and Unchangeable
BLOCKTIME numeric_value	Forbidden
SVCTIMEOUT = number	Forbidden
SESSIONROLE	Forbidden
AFFINITYSCOPE	Forbidden
AFFINITYSTRICT	Forbidden
AUTOTRAN = {Y | N}	Forbidden
ROUTING = string_value	Forbidden
TRANTIME = number	Forbidden

In the Properties.xml file, users must assure all the parameters' references are valid. For example, the GROUP which is indicated by SRVGRP in the SERVICES section must have already been defined in this Properties.xml file's GROUPS section or it will report error when system generates the UBBCONFIG.

Besides the items of the GROUPS, RMS, SERVERS, SERVICES section of UBBCONFIG in Properties.xml, this file also contains some package global attributes at the beginning:

Table 18-5 Description Information of the Package

Item	Category
PackageName	The global unique application package name, for example, APP1.zip.
TuxedoVersion	The Tuxedo version this package is built on. This item is checked when assembling Tuxedo domain to decide if the package is suitable for certain Tuxedo installation.
SupportedOS	The Operation System this package can be deployed to. This information is compared with the corresponding item in Machine list entry when deploying the package. The possible values are Linux, SunOS, AIX, and HP-UX.
TuxedoWordSize	The Tuxedo word size this package is built on. The value can be 32 or 64 (bit). This information is compared with the corresponding item in Machine list entry when deploying the package.
MachineArch	The machine architecture this package can apply to. The possible values are: x86_64, SUNW, powerpc, and IA64. This information is compared with the corresponding item in Machine list when deploying the package.
LibPath	The path where the library locates in the package, if there is a library in it.

Actually the values of these package global attributes will not be checked by Tuxedo tmcrdom/tmdeldom commands. The reason to keep these values in the Properties.xml is that, the contents requirement of the Application Package are the same with the similar Tuxedo EM function. So we suggest you to fill these values as the table described, then when you want to use the Tuxedo EM deploy/undeploy function, you can use these packages directly without any change.

For more information, please refer to Properties.xml Schema.

18.2.2 Uploading/Deleting an Application Package

User can add/delete the Application Packages to/from the Application Package Repository freely by themselves. That means it's the users' duty to maintain the Application Packages Repository.

18.2.3 Creating and Deploying a Domain

Users need to use tmcrdom to create and deploy the domain. This command must be run on the master node of the domain which will be created by this command.

Before running this command, the customer need to export their JAVA_HOME and JVMLIBS environment.

The command syntax is:

tmcrdom -d "domain_name" -f "deployment_plan"

Where:

• "domain_name" will be checked. If the domain has already existed in the Deployment Repository, it will report error, or it will create this domain in the repository.
• "deployment_plan" is a text file. This feature assumes that it has already been created by the customer before invoking this command. It contains the deployment information needed by this domain. It can be specified in the command as an absolute path or relative path on the master node. Its format is similar to UBBCONFIG.

Note:

In some scenarios, although tmcrdom execution fails, it actually has created a domain in the Deployment Repository, thus if you create the domain again you will receive an error message saying the domain already exists. To solve this, you need to delete the domain using the tmdeldom command with -f option before you can create the domain.

• deployment_plan
  

18.2.3.1 deployment_plan

A deployment_plan file is made up of nine possible specification sections. Allowable section names are:

• RESOUCES Section
  
• MACHINES Section
  
• GROUPS Section
  
• RMS Section
  
• NETGROUPS Section
  
• NETWORK Section
  
• SERVERS Section
  
• ROUTING
  
• SERVICES Section
  

18.2.3.1.1 RESOUCES Section

Required parameters are:

IPCKEY numeric_value

Refer to the same parameter in UBBCONFIG.

MASTER string_value1[,string_value2]

Refer to the same parameter in UBBCONFIG.

MODEL {SHM | MP}

Refer to the same parameter in UBBCONFIG.

APPREPOSITORY string_value

It specifies the repository path which the Application Packages will be put on. This parameter is required. The place which is specified by this parameter must be NFS accessible. The string length can't be larger than 256. It must be an absolute path.

DEPREPOSITORY string_value

It specifies the repository path which all the domain deployment information will be put. This parameter is required. The place which is specified by this parameter must be NFS accessible. The string length can't be larger than 256. It must be an absolute path.

All other parameters are same as RESOURCES section parameters in UBBCONFIG.

See Also:

For more information on the UBBCONFIG refer to Section 5 - File Formats, Data Descriptions, MIBs, and System Processes Reference

18.2.3.1.2 MACHINES Section

It's same as the UBBCONFIG's MACHINES section. It must be included in the deployment plan. Its contents will be used as the MACHINES section in the ultimate UBBCONFIG.

Besides these, this feature introduce some new parameters:

CONFIGSCRIPT = string_value[0..256]

It specifies the configuration script which will be run on each compute node before booting the Tuxedo System. It must be an absolute path on the master node. The tmcrdom command will copy this script to the deployment repository specified by DEPREPOSITORY and deploy it to the destination machine later. After deployed to the destination machine, it will be run under the destination machine's APPDIR.

BOOTSCRIPT = string_value[0..256]

It specifies the booting script which will be run on the mater node to boot the Tuxedo System. It must be an absolute path on the master node. The tmcrdom command will copy this script to the deployment repository specified by DEPREPOSITORY and deploy it to the destination machine later. After deployed to the destination machine, it will be run under the destination machine's APPDIR.

SHUTDOWNSCRIPT = string_value[0..256]

It specifies the shutdown script which will be run on the mater node to shutdown the Tuxedo System. It must be an absolute path on the master node. The tmcrdom command will copy this script to the deployment repository specified by DEPREPOSITORY and deploy it to the destination machine later. After deployed to the destination machine, it will be run under the destination machine's APPDIR.

UNCONFIGSCRIPT = string_value[0.. 256]

It specifies the unconfigure script which will be run on each compute node after the Tuxedo System is shutdown. It must be an absolute path on the master node. The tmcrdom command will copy this script to the deployment repository specified by DEPREPOSITORY and deploy it to the destination machine later. After deployed to the destination machine, it will be run under the destination machine's APPDIR.

For every machine, machine address, LMID, TUXCONFIG, TUXDIR and APPDIR are required. For master machine, CONFIGSCRIPT, BOOTSCRIPT and SHUTDOWNSCRIPT are required. For slave machine, BOOTSCRIPT and SHUTDOWNSCRIPT are forbidden.

Note:

The scripts specified by CONFIGSCRIPT, BOOTSCRIPT, SHUTDOWNSCRIPT, and UNCONFIGSCRIPT must be able to be found by tmcrdom on the master machine where the command runs.

18.2.3.1.3 GROUPS Section

Required parameters are:

GROUPNAME

Refer to the same parameter in UBBCONFIG. This group name will be used in the ultimate UBBCONFIG.

LMID = string_value1 [,string_value2]

Refer to the same parameter in UBBCONFIG.

GRPNO = number

Refer to the same parameter in UBBCONFIG. This group number will be used in the ultimate UBBCONFIG.

Optional parameters are:

• OPENINFO = string_value
• CLOSEINFO = string_value
• TMSCOUNT = number
• SEC_PRINCIPAL_NAME = string_value [0..511]
• SEC_PRINCIPAL_LOCATION = string_value [0..1023]
• SEC_PRINCIPAL_PASSVAR = string_value [0..31]
• REQUEST_VERSION = { numeric_value| * }
• VERSION_RANGE = string_value
• VERSION_POLICY = string_value { PROPAGATE }

For information about above parameters, refer to the same parameters in UBBCONFIG.

These parameters below are new for the Optional parameters:

PAKNAME = string_value[0..256]

It associates this group with one Application Package. That means, this Application Package will be deployed to the machine which is specified by this group's LMID parameter. If PAKNAME parameter is specified, the GROUPS parameters which can be specified in the properties.xml file like:ENVFILE, TMSNAME, MRM, SIGNATURE_REQUIRED, ENCRYPTION_REQUIRED can't appear in this group definition in the deployment plan, their values will come from the Application Package's properties.xml file. If PAKNAME is not specified, this group is a normal one. Then all the parameters in this group will be the same with the UBBCONFIG. We recommend the customers to use this normal group to hold their Tuxedo System level servers, for example, GWADM.

If PAKNAME is specified, PAKGRPNAME and PAKINSTANCE must also be specified for this group entry.

PAKGRPNAME= string_value [1..30]

It specifies the logical name of the group in the Application Package, and the Application Package's name is specified by PAKNAME parameter. It cannot contain an asterisk (*), comma, or colon. If a non-empty value is specified, PAKNAME and PAKINSTANCE must also be specified for this group entry. Two group entries with the same PAKNAME and PAKINSTANCE cannot have the same PAKGRPNAME. That means two group entries cannot be associated with one same group entry in one Application Package.

It specifies the logical name of the group in the Application Package, and the Application Package's name is specified by PAKNAME parameter. It cannot contain an asterisk (*), comma, or colon. If a non-empty value is specified, PAKNAME and PAKINSTANCE must also be specified for this group entry. Two group entries with the same PAKNAME and PAKINSTANCE cannot have the same PAKGRPNAME. That means two group entries cannot be associated with one same group entry in one Application Package.

PAKINSTANCE = number [1...30000]

It specifies the index for the same Application Package. This is for the situation that one Application Package being deployed to the same domain for more than once. This number must be greater than 0 and less than 30000. If PAKINSTANCE is specified, PAKNAME and PAKGRPNAME must also be specified.

If PAKNAME is not specified, the parameters below are the same as the parameters in UBBCONFIG:

• ENVFILE = string_value[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
• TMSNAME = string_value[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
• MRM = {Y | N}
• SIGNATURE_REQUIRED = {Y | N}
• ENCRYPTION_REQUIRED = {Y | N}

See Also:

For more information on the UBBCONFIG refer to Section 5 - File Formats, Data Descriptions, MIBs, and System Processes Reference

18.2.3.1.4 RMS Section

If one rms entry belongs to a group which is not associated with any Application Package, all the parameters are same as those in UBBCONFIG.

If not:

Required parameters are:

RMSNAME

Refer to the same parameter in UBBCONFIG. This rms entry name will be used in the ultimate UBBCONFIG.

SRVGRP = string_value

Refer to the same parameter in UBBCONFIG. All the entries in this RMS section which belong to this group must be associated with one Application Package group's all rms entries, or it will report error. The according group in the Application Package is specified by the group's PAKGRPNAME in the deployment plan.

RMID = number

Refer to the same parameter in UBBCONFIG.

PAKRMID = number

This specifies the RMID appears in the Application Package. It must be between 1 and 31 inclusive. The rms entries belong to the same group cannot have the same PAKRMID.

If one RMS entry belong to a group which has PAKNAME defined, it must specify PAKRMID parameter in the deployment plan, or it will report error.

Optional parameters are:

• TMSCOUNT = number
• OPENINFO = string_value
• CLOSEINFO = string_value
• AUTO = {Y | N}

For information about above parameters, refer to the same parameters in UBBCONFIG.

TMSNAME = string_value[0..256] can't be specified in the deployment plan. It will be from the properties.xml file.

See Also:

For more information on the UBBCONFIG refer to Section 5 - File Formats, Data Descriptions, MIBs, and System Processes Reference

18.2.3.1.5 NETGROUPS Section

Same as NETGROUPS section in UBBCONFIG. It must be included in the deployment plan if customer needs it in the ultimate generated UBBCONFIG. Its contents will be used as the NETGROUPS section in the ultimate UBBCONFIG.

18.2.3.1.6 NETWORK Section

Same as NETWORK section in UBBCONFIG. It must be included in the deployment plan. Its contents will be used as the NETWORK section in the ultimate UBBCONFIG.

18.2.3.1.7 SERVERS Section

If one server belongs to a group which is not associated with any Application Package, then all the parameters are the same with UBBCONFIG.

If not:

Required parameters are:

AOUT

It must be the same with the aout in the corresponding Application Package's properties.xml.

SRVGRP = string_value

Refer to the same parameters in UBBCONFIG.

SRVID = number

Refer to the same parameters in UBBCONFIG. This value will be used in the ultimate UBBCONFIG.

PAKSRVID = number

It specifies the SRVID in the Application Package's properties file. Every server in the Application Package's properties file must be associated with one entry in this section in the deployment plan.

If one server belongs to a group which has PAKNAME defined, then PAKSRVID must be specified for this server. And two servers belong to the same group can not have the same PAKSRVID. If one server belongs to a normal group which has no PAKNAME defined, then it can not define PAKSRVID parameter.

Optional parameters listed below are same as those in UBBCONFIG:

• CLOPT = string_value
• SEQUENCE = number
• MIN = number
• MAX = number
• RQADDR = string_value
• RQPERM = number
• REPLYQ = {Y | N}
• RPPERM = number
• MAXGEN = number
• GRACE = number
• RESTART = {Y | N}
• SYSTEM_ACCESS = identifier[,identifier]
• MAXDISPATCHTHREADS = number
• MINDISPATCHTHREADS = number
• THREADSTACKSIZE = number
• SEC_PRINCIPAL_NAME = string_value [0..511]
• SEC_PRINCIPAL_LOCATION = string_value [0..1023]
• SEC_PRINCIPAL_PASSVAR = string_value [0..31]
• SICACHEENTRIESMAX = string_value
• CONCURR_STRATEGY=PER_REQUEST
• CONCURR_STRATEGY = PER_OBJECT

The parameters listed below cannot appear in this section, the ultimate UBBCONFIG will keep the properties.xml file value.

• ENVFILE = string_value[0..256]
• RCMD = string_value[0..256]
• CONV = {Y | N}

See Also:

For more information on the UBBCONFIG refer to Section 5 - File Formats, Data Descriptions, MIBs, and System Processes Reference

18.2.3.1.8 ROUTING

It's same as UBBCONFIG's ROUTING section. It must be included in the deployment plan if customer needs it in the ultimate generated UBBCONFIG. Its contents will be used as the ROUTING section in the ultimate UBBCONFIG.

18.2.3.1.9 SERVICES Section

If one service belongs to a group which is not associated with any Application Package, then all the parameters are same as those in UBBCONFIG.

If not:

Required parameters are:

SVCNM

It must be the same with the SVCNM in the corresponding Application Package's properties.xml. All the services in the properties.xml file must have an associated entry in this section.

SRVGRP = string_value

Refer to the same parameters in UBBCONFIG

Optional parameters listed below are same as those in UBBCONFIG:

• LOAD = number
• PRIO = number
• ROUTING = string_value
• BLOCKTIME numeric_value
• SVCTIMEOUT = number
• SESSIONROLE
• AFFINITYSCOPE
• AFFINITYSTRICT
• AUTOTRAN = {Y | N}
• TRANTIME = number

The parameters listed below can't appear in this section, the ultimate UBBCONFIG retains the properties.xml file value:

• BUFTYPE = "type1[:subtype1[,subtype2 . . . ]] [;type2[:subtype3[, . . . ]]] . . . "
• SIGNATURE_REQUIRED = {Y | N}
• ENCRYPTION_REQUIRED = {Y | N}
• BUFTYPECONV = {XML2FML | XML2FML32}

This command generates one domain's all information including UBBCONFIG and save it to the Deployment Repository.

This command configures every compute node according to the configure script including creating the TLOG device and so on.

This command boots up the whole Tuxedo System.

See Also:

For more information on the UBBCONFIG refer to Section 5 - File Formats, Data Descriptions, MIBs, and System Processes Reference

18.2.4 Undeploying a Domain

Users can use tmdeldom to shut down and undeploy the domain. This command must be run on the master node of the domain.

The command syntax is:

tmdeldom -d "domain_name" -r "deprepository" -f

The command functions are:

• Shut down the whole domain
• Unconfigure every node if needed.
• Undeploy the whole domain and delete it also from the Deployment Repository.

The parameter domain_name is the domain's name which is specified in the previous tmcrdom command. The deprepository is the Deployment Repository which is specified by the DEPREPOSITORY parameter in the previous deployment plan. Without "-f", once any step of tmdeldom fail, the command will not continue to execute.

If -f is specified, even if step 1, 2, or 3 is failed, this command will also delete the domain information in the repository.