The chapter describes how Domains is defined in a configuration file. The chapter covers the following topics:
What This Chapter Is About
Domains integrates with an existing BEA TUXEDO application by adding new group and server information to the configuration file. In a manner similar to the UBBCONFIG and TUXCONFIG files of BEA TUXEDO, the configuration is defined in a text file known as the DMCONFIG file, and then loaded into a binary file called BDMCONFIG. Configuration can be done dynamically by using subcommands of the dmadmin command.
The architecture of the DMCONFIG file follows closely the architecture of the UBBCONFIG file. There is an ASCII file (the DMCONFIG file) that is compiled into a binary configuration file, BDMCONFIG. There is one BDMCONFIG file per BEA TUXEDO application wishing to add the Domains functionality. The BDMCONFIG file can be contained within the same You must add the following entries to the * Overview of a Domains Configuration
VTOC (set of BEA TUXEDO devices) as an existing TUXCONFIG file without requiring application shutdown.
The BEA TUXEDO Configuration File
SERVERS section of the TUXCONFIG file to enable Domains:
DMADM (the Domains administrative server)
GWADM (the Gateway administrative server)
Each All domain configuration information is stored in a binary file, the BDMCONFIG file.
The DMCONFIG file is created and edited with any text editor by the application administrator. The compiled BDMCONFIG can be updated while the system is running by using the dmadmin(1) command.
There must be one BDMCONFIG file per BEA TUXEDO application wishing to add the Domains functionality.
System access to the BDMCONFIG file is provided through the Domains administrative server, DMADM(5). When a gateway group is booted, the gateway administrative server, GWADM(5), requests from the DMADM server a copy of the configuration required by that group. The GWADM server and the DMADM server also ensure that run-time changes to the configuration are reflected in the corresponding Domains gateway groups.
The dmconfig(5) reference page spells out the complete detail of the DMCONFIG file; this section touches on some of the highlights.
The DMCONFIG file is organized into the following sections:
GWADM and GWTDOMAIN pair must run in the same BEA TUXEDO group. You can add pairs of GWADM/GWTDOMAIN, as long as each pair is in a different BEA TUXEDO group. You must define a single instance of DMADM, which can be in any group on a machine containing the highest version of BEA TUXEDO for the domain.
The Domains Configuration File
DMCONFIG Sections
DM_LOCAL_DOMAINS
DM_REMOTE_DOMAINS
DM_LOCAL_SERVICES
LDOM in the *DM_LOCAL_DOMAINS section. Specification of services can also be used to restrict access to local services from remote domains; that is, only services specified are available to the remote domain.
DM_REMOTE_SERVICES
LDOM parameter) that provides access to the remote services.
DM_ROUTING
DM_ACCESS_CONTROL
DM_LOCAL_SERVICES section, ACL = list_name, can be used to restrict access to a particular local service to the listed set of remote domains.
DM_<dmtype>
dmtype can be OSITP, SNAX, or TDOMAIN. This guide focuses only on TDOMAIN. Consult BEA Connect documentation for information about OSITP and SNAX. Each domain type must be specified in a section of its own.
DM_TDOMAIN section entries associated with a remote domain can be specified more than once, with different network addresses, to implement the mirrored gateway facility. (See dmconfig(5) for a description and an example of a mirrored gateway.)
The architecture of the DMCONFIG file is compatible with the architecture of the UBBCONFIG file.
In /TDOMAIN, the binary version of the DMCONFIG file contains an extra section: *DM_PASSWORDS. The *DM_PASSWORDS section contains the passwords used by local and remote domains during the authentication procedure. The passwords are added by the Domains administrator using the dmadmin(1) command.
The command dmloadcf(1) parses the syntax of the DMCONFIG file, and loads the domain configuration into a BDMCONFIG binary file. The command uses the environment variable BDMCONFIG to point to the BEA TUXEDO file system where the configuration should be stored. The BDMCONFIG file can be stored on the same device as the TUXCONFIG file.
Figure 2-1 Relationships Between Configuration Commands and Files
The dmloadcf(1) command, through its -c option, also provides an estimate of the IPC resources needed for each local domain specified in the configuration.
As shown in Figure 2-1, the dmloadcf command uses the $TUXDIR/udataobj/DMTYPE file. It checks the DMTYPE file to verify that the domain types specified in the configuration file are valid. Each Domains instantiation has a domain type. The type is used as a tag in the file $TUXDIR/udataobj/DMTYPE. Each line in this file has the format:
dmtype:access_module_lib:comm_libs:tm_typesw_lib:gw_typesw_lib
As supplied for the initial release, the file has the following entry for /TDOMAIN:
TDOMAIN:-lgwt:-lnwi -lnws -lnwi::
The dmunloadcf(1) command is required to unload a binary version of a Domains configuration into an ASCII file.
The native BEA TUXEDO system provides authentication of clients, servers, and administrative programs. The default security mechanism provided with BEA TUXEDO is an authentication scheme that uses one password per BEA TUXEDO application. Clients are required to present this password to be authenticated and allowed to join the application. Servers are authenticated to be running as the user identified as the application administrator. Access Control Lists can be set up whereby access to services is controlled by means of lists that are automatically checked when the service is requested. The BEA TUXEDO system also provides an optional mechanism based on a server that performs per-user authentication. There are also hooks for connecting third-party vendors' authentication modules.
The BEA TUXEDO application password is administered with the following programs: tmloadcf(1) prompts for the password when the SECURITY option is enabled in the TUXCONFIG file; the password is automatically propagated with the TUXCONFIG file to the other machines by the tagent mechanism; and the password can be dynamically updated with the tmadmin command.
Because the very concept of Domains implies the possibility of domains existing under diverse ownership, the native BEA TUXEDO application password scheme does not provide sufficient security. It has, therefore, been part of the Domains design to enhance security through the following constructs:
DM_LOCAL_SERVICES section of the DMCONFIG file.
This feature is specified as a part of the Domains generic framework but its implementation is dependent upon each domain type. The /TDOMAIN instantiation uses this feature to enforce security between BEA TUXEDO applications.
Domain passwords are implemented in a special section (called *DM_PASSWORDS) of the BDMCONFIG file. Except for a declaration of the intent to invoke password security, the password specification is not part of the /TDOMAIN configuration process; the *DM_PASSWORDS section that ends up in the BDMCONFIG file is not part of the ASCII DMCONFIG file; the *DM_PASSWORDS section is defined and updated by the Domains administrator through the dmadmin(1) command. Each entry contains the password used by a remote domain to access a particular local domain and the password required by the local domain, in turn, to access the remote domain.
Domains gateways can be made to authenticate incoming connections requested by remote domains. The authentication mechanism is optional and compatible with the BEA TUXEDO mechanism specified in the TUXCONFIG file.
Application administrators can define when security should be enforced for incoming connections from remote domains. The SECURITY keyword of the *DM_LOCAL_DOMAINS section specifies the level of security allowed by a particular local domain. There are three basic security levels:
DM_PASSWORDS section of the BDMCONFIG file. This level is specified with the DM_PW option.
Domains password security to some extent reflects the SECURITY option specified in the *RESOURCES section of the TUXCONFIG file; that is, if APP_PW is defined in the TUXCONFIG file, then local domains cannot be defined with the NONE option; they must be defined with either the APP_PW option or the DM_PW option.
Even if the SECURITY option is not set in TUXCONFIG, the Domains configuration can still require the Domains gateways to enforce security at the APP_PW or DM_PW level.
If the DM_PW option is selected, then each remote domain must have a password defined in the *DM_PASSWORDS section of the BDMCONFIG file; in other words, incoming connections from remote domains without a password are rejected by Domains gateways.
The *DM_PASSWORDS table contains an entry for each remote domain as follows:
LDOM
RDOM
LPWD
RPWD
Note: Passwords are stored encrypted.
The SECURITY parameter in the *DM_LOCAL_DOMAINS section of the DMCONFIG file specifies the security type of a local domain.
The security protocol is used only when a remote domain first connects to a given local domain. If the security types are incompatible between the domains or if the passwords do not match, the connection establishment will fail.
If SECURITY is set to NONE for a local domain, it implies that any connections coming in will not be authenticated. Bear in mind that by setting SECURITY to NONE, a local domain can still connect to remote domains that have SECURITY set to DM_PW, but before the connection is established with a domain that has SECURITY of DM_PW, you would have to define passwords on both sides by running dmadmin(1) or by using the /AdminAPI.
If the SECURITY in UBBCONFIG is set to APP_PW or higher, then SECURITY in DMCONFIG can be NONE, APP_PW, or DM_PW. Since you can define multiple views of a domain in one DMCONFIG file, each of those views can have a different type of security mechanism.
Note that if SECURITY is set to APP_PW in DMCONFIG, then SECURITY in UBBCONFIG must be set to APP_PW or higher.
Listing 2-1 through Listing 2-3 show some common variations.
Listing 2-1 /T Security NONE, Domains Security DM_PW
On the initiator side, the pertinent attributes in UBBCONFIG and DMCONFIG look like this:
UBBCONFIG
SECURITY=NONE
DMCONFIG
*DM_LOCAL_DOMAINS
DOM1
DOMAINID=DOM1
SECURITY=DM_PW
*DM_REMOTE_DOMAINS
DOM2 DOMAINID="DOM2"
On the responder side, the pertinent attributes in UBBCONFIG and DMCONFIG look like this:
UBBCONFIG
SECURITY=NONE
DMCONFIG
*DM_LOCAL_DOMAINS
DOM2
DOMAINID=DOM2
SECURITY=DM_PW
*DM_REMOTE_DOMAINS
DOM1 DOMAINID="DOM1"
After the TUXCONFIG and BDMCONFIG files have been made, boot the applications on DOM1 and DOM2.
On DOM1:
dmadmin
passwd DOM1 DOM2
Enter Local Domain Password:foo1
Reenter Local Domain Password:foo1
Enter Remote Domain Password:foo2
Reenter Remote Domain Password:foo2
On DOM2:
dmadmin
passwd DOM2 DOM1
Enter Local Domain Password:foo2
Reenter Local Domain Password:foo2
Enter Remote Domain Password:foo1
Reenter Remote Domain Password:foo1
Once the passwords have been created on both domains, the connection can be established and services can be invoked on the remote domain.
Listing 2-2 /T Security NONE, Domains Security NONE
DOM1: SECURITY in UBBCONFIG set to NONE
SECURITY in DMCONFIG set to NONE
DOM2: SECURITY in UBBCONFIG set to NONE
SECURITY in DMCONFIG set to DM_PW
In this example, DOM1 is not enforcing any security but DOM2 is enforcing DM_PW security.
On the initiator side, the pertinent attributes in UBBCONFIG and DMCONFIG look like this:
UBBCONFIG
SECURITY=NONE
DMCONFIG
*DM_LOCAL_DOMAINS
DOM1
DOMAINID=DOM1
SECURITY=NONE
*DM_REMOTE_DOMAINS
DOM2 DOMAINID="DOM2"
On the responder side, the pertinent attributes in UBBCONFIG and DMCONFIG look like this:
UBBCONFIG
SECURITY=NONE
DMCONFIG
*DM_LOCAL_DOMAINS
DOM2
DOMAINID=DOM2
SECURITY=DM_PW
*DM_REMOTE_DOMAINS
DOM1 DOMAINID="DOM1"
After the TUXCONFIG and BDMCONFIG files have been made, boot the applications on DOM1 and DOM2.
On DOM1:
dmadmin
passwd DOM1 DOM2
Enter Local Domain Password:foo1
Reenter Local Domain Password:foo1
Enter Remote Domain Password:foo2
Reenter Remote Domain Password:foo2
On DOM2:
dmadmin
passwd DOM2 DOM1
Enter Local Domain Password:foo2
Reenter Local Domain Password:foo2
Enter Remote Domain Password:foo1
Reenter Remote Domain Password:foo1
Once the passwords have been created on both domains, the connection can be established and services can be invoked on the remote domain.
Listing 2-3 /T Security APP_PW, Domains Security APP_PW
DOM1: SECURITY in UBBCONFIG set to APP_PW
SECURITY in DMCONFIG set to APP_PW
DOM2: SECURITY in UBBCONFIG set to APP_PW
SECURITY in DMCONFIG set to APP_PW
In this example, both DOM1 and DOM2 are enforcing APP_PW security.
On the initiator side, the pertinent attributes in UBBCONFIG and DMCONFIG look like this:
UBBCONFIG
SECURITY=APP_PW
DMCONFIG
*DM_LOCAL_DOMAINS
DOM1
DOMAINID=DOM1
SECURITY=APP_PW
*DM_REMOTE_DOMAINS
DOM2 DOMAINID="DOM2"
On the responder side, the pertinent attributes in UBBCONFIG and DMCONFIG look like this:
UBBCONFIG
SECURITY=APP_PW
DMCONFIG
*DM_LOCAL_DOMAINS
DOM2
DOMAINID=DOM2
SECURITY=APP_PW
*DM_REMOTE_DOMAINS
DOM1 DOMAINID="DOM1"
After the TUXCONFIG and BDMCONFIG files have been made, boot the applications on DOM1 and DOM2.
There are three policies that you can use to establish connections between domains: ON_STARTUP, ON_DEMAND, and INCOMING_ONLY. The following section describes each of these policies and how to configure them.
You can specify the conditions under which a local domain gateway tries to establish a connection to a remote domain. You specify these conditions by assigning a value to the CONNECTION_POLICY parameter in the domains configuration file. You can select any of the following connection policies:
ON_STARTUP)
ON_DEMAND)
INCOMING_ONLY)
For connection policies of A policy of The following diagram shows how connections are attempted and made by a gateway for which the connection policy is
A connection policy of The following diagram shows how connections are attempted and made by a gateway for which the connection policy is
A connection policy of To use this policy, enter the following line in your Domains configuration file.
You can also establish the connection manually using the The following diagram shows how connections are attempted and made by a gateway for which the connection policy is
The Connection Retry Interval enables failed attempts at connections to remote domains to be retried automatically if the connection policy is If the connection policy is To configure the connection retry interval, you set the following parameter in the ON_STARTUP and INCOMING_ONLY, Dynamic Status is invoked. Dynamic Status is a capability of BEA TUXEDO Domains that provides a system-determined status of remote services.
Connect at Boot Time (ON_STARTUP Policy)
ON_STARTUP means that a domain gateway attempts to establish a connection with its remote domains at gateway server initialization time. By default, this connection policy retries failed connections every 60 seconds, but you can specify a different value for this interval (using the RETRY_INTERVAL parameter).
CONNECTION_POLICY=ON_STARTUP
ON_STARTUP (This policy invokes Dynamic Status.)
Figure 2-2 Connections Made with an ON_STARTUP Policy
Connect When a Client Program Requests a Remote Service (ON_DEMAND Policy)
ON_DEMAND means that a connection is attempted only when requested by either a client request to a remote service or an administrative "connect" command. The default setting for CONNECTION_POLICY is ON_DEMAND. Connection retry processing is not allowed when the connection policy is ON_DEMAND.
CONNECTION_POLICY=ON_DEMANDON_DEMAND. (This policy does not invoke Dynamic Status.)
Figure 2-3 Connections Made with an ON_DEMAND Policy (when a client requests a remote service)
Accept Incoming Connections but Do Not Initiate a Connection (INCOMING_ONLY Policy)
INCOMING_ONLY means that a domain gateway does not try to establish a connection to remote domains upon starting. Connection retry processing is not allowed when the connection policy is INCOMING_ONLY.
CONNECTION_POLICY=INCOMING_ONLYdmadmin connect command.
INCOMING_ONLY. (This policy invokes Dynamic Status.)
Figure 2-4 Connections Made with an INCOMING_ONLY Policy (accept incoming connections)
Configuring the Connection Retry Interval (for ON_STARTUP Only)
ON_STARTUP. As an administrator, you can control the frequency of automatic connection attempts. To do so, specify the length (in seconds) of the interval during which the gateway should wait before trying to establish a connection again. You can specify the retry interval by setting the RETRY_INTERVAL parameter in the Domains configuration file:
RETRY_INTERVAL=[number_of_seconds]ON_STARTUP and you do not specify a value for the RETRY_INTERVAL parameter, a default of 60 is used.
DM_LOCAL_DOMAINS section of the domains configuration file:
RETRY_INTERVAL=[seconds]-To specify the number of seconds after which an attempt is made to connect or reconnect to a remote domain. Depending on the result of the connection attempt, the remote services are marked either available or unavailable. (The minimum value is 0; the maximum value is 2147483647.)
The You indicate the number of times that a domain gateway tries to establish connections to remote domains before quitting by assigning a value to the RETRY_INTERVAL parameter is valid only when the connection policy is ON_STARTUP. For the other connection policies (ON_DEMAND and INCOMING_ONLY), retry processing is disabled.
Configuring the Maximum Retry Number
MAXRETRY parameter: (The minimum value is 0; the default and maximum value is MAXLONG.)
MAXRETRY=0, the automatic connection retry processing is turned off. The server does not attempt to connect to the remote gateways automatically.
The MAXRETRY parameter is valid only when the connection policy is ON_STARTUP. For the other connection policies (ON_DEMAND and INCOMING_ONLY), retry processing is disabled. The RETRY_INTERVAL is rounded up to a multiple of SCANUNIT.
The gateway process ( Dynamic Status provides a system-determined status of remote services. When Dynamic Status is in effect, the status of a remote service depends on the status of the network connection between the local and remote gateways. The remote services are considered available whenever a connection to the remote domain is available. When a network connection to a remote domain is not available, services in that domain are considered unavailable. This capability of the TDOMAIN Gateways is known as the Dynamic Status feature. This policy is invoked when the connection policy is For each service, the gateway not only keeps track of the remote domains from which the service is imported, but also which of those remote domains are available (that is, connections are up), yielding intelligent load balancing of requests to remote domains. If all remote domains for which the service is imported become unreachable, the service is suspended in the Bulletin Board.
For example, a service is imported from two remote domains. This is accomplished by listing two entries, as in the following example, in the When connections to both
Note:
When the connection policy is The connection policy you have set up between your domains determines the availability or suspension of services. The following table describes how each connection policy affects the Dynamic Status capability.
The Dynamic Status Capability
GWTDOMAIN) advertises those services that are imported from one or more remote domains in the Bulletin Board. These services typically remain advertised regardless of whether the remote service is reachable. The Dynamic Status behavior provides intelligence to detect the availability of remote services and to react accordingly.
ON_STARTUP or INCOMING_ONLY.
DM_REMOTE_SERVICES section:
RSVC RDOM=R1
RSVCRDOM=R2R1 and R2 are up, the gateway load balances the requests. If the connection to R1 goes down, the gateway sends all requests for services RSVC to R2. If both connections go down, the gateway suspends RSVC in the Bulletin Board. Subsequent requests for RSVC will either be routed to a local service or another gateway, or will fail with TPEVENT.
ON_DEMAND, advertisement of remote services begins whenever the gateway is started up and remains advertised.
How Connection Policies Affect the Dynamic Status Capability
As the administrator, you can control the number of connections you want to establish between domains. You can also beak the connections between local and remote domains. This section explains how to perform these tasks.
To establish a connection between a local gateway and a remote domain, run the By default, connections are established between the local domain you have specified and all remote domains configured for the local gateway. If you want to establish a connection to only one remote domain, you specify that domain on the command line with the If a connection attempt fails, you have configured the domain to retry a connection, repeated attempts to connect (via automatic connection retry processing) are made.
To break a connection between a local gateway and a remote domain, (making sure that the gateway will not try to reestablish the connection through automatic connection retry processing), run the By default, all remote domains configured for the local gateway are disconnected. If you want to end the connection to only one remote domain, specify that domain on the command line with the Automatic connection retry processing is stopped by this command, regardless of whether there are any active connections when the command is run.
Using the The following example shows a There are two types of failover:
Controlling the Connections Between Domains
Establishing Connections Between Domains
dmadmin command with the connect (co) subcommand, as follows.
dmadmin co -d local_domain_name-R option.
dmadmin co -d local_domain_name -R remote_domain_name Breaking Connections Between Domains
dmadmin command with the disconnect (dco) subcommand, as follows.
dmadmin dco -d local_domain_name-R option as follows.
dmadmin dco -d local_domain_name -R remote_domain_name Reporting on Connection Status
printdomain command, you can report on connection status and the connections being retried. The connect command reports whether the connection attempt was successfully initiated. The printdomain command prints information about the specified local domain, including a list of connected remote domains, a list of remote domains being retried.
dmadmin session in which the printdomain command is issued (in its abbreviated form, pd) for a local domain called LDOM.
$ dmadmin
dmadmin - Copyright (c) 1996 BEA Systems, Inc.
Portions * Copyright 1986-1997 RSA Data Security, Inc.
All Rights Reserved.
Distributed under license by BEA Systems, Inc.
TUXEDO is a registered trademark.pd -d LDOM
Local domain :LDOM
Connected domains:
Domainid: RDOM1
Disconnected domains being retried:
Domainid: RDOM2 dco -d LDOM -R RDOM1
Operation completed successfully. Use printdomain(pd) to obtain results. dco -d LDOM -R RDOM2
Operation completed successfully. Use printdomain(pd) to obtain results. co -d LDOM -R RDOM3
Operation completed successfully. Use printdomain(pd) to obtain results.pd -d LDOM
Local domain :LDOM
Connected domains:
Domainid: RDOM3 Configuring Failover and Failback
If you want failover and failback functionality in your domain, you must configure your Domains configuration file to support this functionality.
For details about the Domains configuration file, see Link-level failover provides fail over to alternate network links when a failure is detected with a primary link. To use link-level failover, the primary and alternate gateway must reside on different remote domains (that is; gateway mirroring). Currently, link-level failover does not support alternate links to the same gateway. The two gateways cannot reside on the same remote domain. You specify link-level failover in the The first entry refers to the primary network link for remote domain Link-level failback is a manual procedure. When the primary link is restored, the administrator must bring down the alternate link manually. This may cause requests that are in progress to fail, and new traffic to be resumed over the primary link.
Note:
For more detailed information on gateway mirroring, see the Domains-level failover provides failover to alternate remote domains when a failure is detected with a primary remote domain. It also provides failback to the primary remote domain when it is restored. This level of failover/failback depends on Dynamic Status. The domain must be configured with a You must specify
Note:
A remote domain is available if a network connection to it exists; a remote domain is unavailable if a network connection to it does not exist.
To support failover, you must specify the following in your Domains configuration file:
DMCONFIG(5) in the BEA TUXEDO Reference Manual.
Link-Level Failover
DM_TDOMAINS section of the Domains configuration file as follows:
*DM_TDOMAINS
RDOM1 NWADDR=//addr1:0
RDOM1 NWADDR=//addr1:1RDOM1; the second entry refers to the alternate link.
DMCONFIG(5) reference page in the BEA TUXEDO Reference Manual.
Domains-level Failover and Failback
CONNECTION_POLICY of ON_STARTUP or INCOMING_ONLY to enable Domains-level failover/failback. Domains-level failover/failback defines a remote domain as being available when a network connection to the remote domain exists, and unavailable when a network connection to the remote domain does not exist.
Prerequisite to Using Domains-level Failover and Failback
ON_STARTUP or INCOMING_ONLY as the value of the CONNECTION_POLICY parameter to use Domains-level failback. (A connection policy of ON_DEMAND is unsuitable for Domains-level failback as it assumes that the remote domain is always available. If you do not specify ON_STARTUP or INCOMING_ONLY as your connection policy, your servers cannot fail over to the alternate remote domains that you have specified with the RDOM parameter.)
Configuring Domains to Support Failover
RDOM parameter in the DM_REMOTE_SERVICES section. You can also specify alternate remote domains, as follows.
Suppose the If a value for the Failback occurs when the network connection to the primary remote domain is reestablished. This can occur because of the following reasons:
Example
TOUPPER and TOUPPER2 services are available from three remote domains: R1 (the primary remote domain), R2, and R3. You include the following entry in your Domains configuration file.
*DM_REMOTE_SERVICES
DEFAULT: RDOM=R1,R2, R3
TOUPPER
TOUPPER2RDOM parameter and a routing criteria are not specified in your configuration file, then the local domain assumes that any remote domain of the same type accepts requests for a particular service.
Configuring Domains to Support Failback
ON_STARTUP only)
dmadmin connect command
Note:
For automatic retries, connection retry must be on (that is, MAXRETRY>0)