Configuring Multiple CORBA Domains


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Documentation \| Using the BEA Tuxedo Domains Component \| Local Topics \| Previous Topic \| Next Topic \| Contents

You use the following three configuration files to configure multiple domains:

The main configuration UBBCONFIG file
The domain configuration (DMCONFIG) file, and
The FactoryFinder domain configuration file (factory_finder.ini).

The Configuration File

You must specify the following parameters in the UBBCONFIG file to configure multiple domains:

Domain name
Gateway group
Gateway service

Domain Name

Though not required for single domains (that is, standalone domains), a domain that is connected to another domain must have a DOMAIN ID. You specify this parameter in the RESOURCES section of the UBBCONFIG file, as follows:

DOMAIN ID = <domain-name>

The <domain-name> must be 1 to13 characters long. For example:

DOMAIN ID = headquarters

<domain-name> is the name that will be referenced in the DM_REMOTE_SERVICES and DM_LOCAL_SERVICES sections of the related DMCONFIG file. In that file, the <domain-name> will be referenced as:

"//<domain-name>"

The quotes are part of the reference. The slashes (//) mean that the name applies to BEA Tuxedo CORBA domains, rather than to BEA Tuxedo ATMI domains. For example:

"//headquarters"

Note: Every domain in an enterprise must have a unique <domain-name>.

Gateway Group and Service

As with every other system service, there must be a group and a service name specified for a gateway. For example, the GROUPS section might contain:

LGWGRP GRPNO=4 LMID=LDOM

In this example, LGWGRP is a name chosen by a user (perhaps an abbreviation for "Local Gateway Group").

The service name for a domain gateway is GWTDOMAIN and must be associated, like every other group, with a server group and a server ID. You specify the service name in the SERVERS section associated with the server group name chosen. For example:

GWTDOMAIN SRVGRP=LGWGRP SRVID=1

This tells the BEA Tuxedo CORBA server that a domain gateway is to be used and that additional information is found in the DMCONFIG file.

The Domain Configuration (DMCONFIG) File

There is one DMCONFIG file per domain. It describes the relationship between the local domain (the domain in which the DMCONFIG file resides) and remote domains (any other domains). The DMCONFIG file contains domain information for the core BEA Tuxedo domains and for BEA Tuxedo CORBA domains.

The sections below concentrate on the information that applies to BEA Tuxedo CORBA domains. In other documentation for the DMCONFIG file, the communication between local and remote domains is based on BEA Tuxedo ATMI services, a concept not used in BEA Tuxedo CORBA environments. For BEA Tuxedo CORBA environments, the "service" name is the name of another BEA Tuxedo domain that can service BEA Tuxedo CORBA requests.

The DMCONFIG file consists of up to eight parts, but one part, DM_ROUTING, does not apply to BEA Tuxedo CORBA environments. The other seven parts refer to BEA Tuxedo CORBA environments, but many of the BEA Tuxedo ATMI parameters are not used. Those seven parts are: DM_RESOURCES, DM_LOCAL_DOMAINS, DM_REMOTE_DOMAINS, DM_LOCAL_SERVICES, DM_REMOTE_SERVICES, DM_ACCESS_CONTROL, and DM_TDOMAIN.

The following sections refer to the sample DMCONFIG file shown in Listing 3-1.

Sample DMCONFIG File

#
# BEA Tuxedo CORBA DOMAIN CONFIGURATION FILE
#
*DM_RESOURCES
VERSION=Experimental8.9

*DM_LOCAL_DOMAINS
LDOM GWGRP=LGWGRP TYPE=TDOMAIN DOMAINID="MUTT"

*DM_REMOTE_DOMAINS
TDOM1 TYPE=TDOMAIN DOMAINID="JEFF"

*DM_TDOMAIN
LDOM NWADDR="//MUTT:2507"
TDOM1 NWADDR="//JEFF:3186"

*DM_LOCAL_SERVICES
"//MUTT"

*DM_REMOTE_SERVICES
"//JEFF" RDOM=TDOM1

DM_RESOURCES

The DM_RESOURCES section can contain a single field, VERSION. It is not checked by software; it is provided simply as a place where users can enter a string that may have some documentation value to the application.

*DM_RESOURCES
VERSION=Experimental8.9

DM_LOCAL_DOMAINS

The DM_LOCAL_DOMAINS section specifies some attributes for gateways into the local domain from the outside. The section must have an entry for each gateway group defined in the UBBCONFIG fle that will provide access to the local domain from other domains. Each entry specifies the parameters required for the domain gateway processes running in that group.

Entries have the form:

LDOM required-parameters [optional-parameters]

where LDOM is an identifier used to refer to the gateway to the local domain. LDOM must be unique among all LDOM and RDOM entries across the enterprise (that is, among the set of domains connected to each other). Note that LDOM is not the same name as the <domain-name> or the gateway group that is specified in the UBBCONFIG file. Rather, LDOM is a name used only within the DMCONFIG file to provide an extra level of insulation from potential changes in the UBBCONFIG file (changes in UBBCONFIG will affect only this one part of DMCONFIG).

The following are required parameters:

GWGRP = identifier

This parameter specifies the name of a gateway server group (the name provided in the UBBCONFIG file) representing this local domain.

TYPE = TDOMAIN

The TYPE parameter is required to specify the use of domains for BEA Tuxedo CORBA environments.

DOMAINID = string

The DOMAINID parameter is used to identify the local domain for the purposes of security. The gateway server group in GWGRP uses this string during any security checks. It has no required relationship to the <domain-name> found in the RESOURCES section of the UBBCONFIG file. DOMAINID must be unique across both local and remote domains. The value of string can be a sequence of characters (for example, "BA.CENTRAL01"), or a sequence of hexadecimal digits preceded by 0x (for example, "0x0002FF98C0000B9D6"). DOMAINID must be 32 octets or fewer in length. If the value is a string, it must be 32 characters or fewer (counting the trailing null).

For example, the lines

*DM_LOCAL_DOMAINS
LDOM GWGRP=LGWGRP TYPE=TDOMAIN DOMAINID="MUTT"

identify LDOM as an access point to the local domain. It is associated with the service group LGWGRP (as specified in the UBBCONFIG file). If the gateway is ever involved in a domain-to-domain security check, it goes by the name MUTT.

Optional parameters describe resources and limits used in the operation of domain gateways. For a description of these parameters, refer the dmconfig(5) reference page in the File Formats, Data Descriptions, MIBs, and System Processes Reference.

DM_REMOTE_DOMAINS

The DM_REMOTE_DOMAINS section specifies some attributes for gateways to remote domains. The section has an entry for each UBBCONFIG file-defined gateway group that will send requests to remote domains. Each entry specifies the parameters required for the domain gateway processes running in that group.

Entries have the form:

RDOM required-parameters

where RDOM is an identifier used to refer to the gateway providing access to the remote domain. RDOM must be unique among all LDOM and RDOM entries across the enterprise (that is, among the set of domains connected to each other). Note that RDOM is not the same name as the <domain-name> or the gateway group that is specified in the UBBCONFIG file. Rather, RDOM is a name used only within the DMCONFIG to provide an extra level of insulation from potential changes in UBBCONFIG (changes in UBBCONFIG will affect only this one part of DMCONFIG).

The required parameters are:

TYPE = TDOMAIN

The TYPE parameter is required to specify the use of domains for BEA Tuxedo CORBA environments.

DOMAINID = string

The DOMAINID parameter is used to identify the remote domain for the purposes of security. The gateway uses this string during any security checks. DOMAINID has no required relationship to the <domain-name> found in the RESOURCES section of the UBBCONFIG file. DOMAINID must be unique across both local and remote domains. The value of string can be a sequence of characters (for example, "BA.CENTRAL01"), or a sequence of hexadecimal digits preceded by "0x" (for example, "0x0002FF98C0000B9D6"). DOMAINID must be 32 octets or fewer in length. If the value is a string, it must be 32 characters or fewer (counting the trailing null).

Entries associated with a remote domain can be specified more than once. The first one specified is considered to be the primary address, which means it is the first one tried when a connection is being attempted to a remote domain. If a network connection cannot be established using the NWADDR of the primary entry, the NWADDR associated with the secondary entry is used. (NWADDR is the physical address; see the DM_TDOMAIN section.)

For example, the lines

*DM_REMOTE_DOMAINS
TDOM1 TYPE=TDOMAIN DOMAINID="JEFF"

identify TDOM1 as the access point name of a gateway. If the gateway is ever involved in a domain-to-domain security check with a partner gateway, the gateway expects that partner to go by the name JEFF.

DM_TDOMAIN

The DM_TDOMAIN section defines the network addressing information for gateways implementing BEA Tuxedo CORBA domains. There should be one entry for each domain gateway that accepts requests from remote domains, and one entry for each domain gateway that sends requests to remote domains.

The format of each entry is:

DOM required-parameters [optional-parameters]

where DOM is an identifier value used to identify either a local domain access point (LDOM in the DM_LOCAL_DOMAINS section) or a remote domain access point (RDOM in the DM_REMOTE_DOMAINS section).

The following parameter is required:

NWADDR = string

This parameter specifies the network address associated with a local domain or a remote domain. If the association is with a local domain, the NWADDR is used to accept connections from other domains. If the association is with a remote domain, the NWADDR is used to initiate a connection. This parameter specifies the network address to be used by the process as its listening address. The listening address for a domain gateway is the means by which it is contacted by other gateway processes participating in the application. If string has the form "0xhex-digits" or "\\xhex-digits", it must contain an even number of valid hex digits. These forms are translated internally into a character array containing TCP/IP addresses. The addresses may also be in either of the following two forms:

"//hostname:port_number"

"//#.#.#.#:port_number"

In the first of these formats, hostname is resolved to a TCP/IP host address at the time the address is bound, using the locally configured name resolution facilities accessed via gethostbyname(3c). The "#.#.#.#" is the dotted decimal format, where each # represents a decimal number in the range 0 to 255.

Port_number is a decimal number in the range 0 to 65535 (the hexadecimal representations of the string specified). For example:

*DM_TDOMAIN
LDOM NWADDR="//MUTT:2507"
TDOM1 NWADDR="//JEFF:3186"

Continuing the example from above, the first entry specifies a gateway with the domain access name of LDOM (meaning that it corresponds to the local gateway group LGWGRP, specified in UBBCONFIG). Since LDOM was defined in DM_LOCAL_DOMAINS, that means the gateway is configured to accept requests from other domains. It listens on the address "//MUTT:2507". Similarly, the second entry is for the domain access name TDOM1, which appears in DM_REMOTE_DOMAINS, transferring requests to a remote domain. In this case, the gateway associated with TDOM1 sends requests to the address "//JEFF:3186".

For a description of the optional parameters, refer to the dmconfig(5) reference page in the File Formats, Data Descriptions, MIBs, and System Processes Reference.

DM_REMOTE_SERVICES

The DM_REMOTE_SERVICES section specifies additional attributes for gateways to remote domains. The format of each entry is:

service RDOM=<rdom-name>
[LDOM=<ldom-name>]
[TRAN_TIME=...]

where service is of the form:

"//<domain-name>"

This <domain-name> is the name that occurs RESOURCES section of the UBBCONFIG file as <domain-name>. Each entry specifies an rdom-name and, optionally, an ldom-name. The gateway uses the attributes for those entries for establishing a gateway pair for BEA Tuxedo CORBA domain communication. Gateways operate in pairs. At boot time, the local domain uses attributes of rdom-name (the address specified in the DM_TDOMAIN section) to establish a connection to a gateway in the other domain. If security is used, the other attributes of rdom-name and ldom-name are used for mutual authentication. At run time, when BEA Tuxedo determines that a request must travel to domain <domain-name>. It uses the gateway specified by rdom-name to send the request to another domain.

Most often, <domain-name> is the name of the domain specified in the address of the rdom-name. In that situation, when the request ends up at the other end of the gateway, it is served in that domain. For example:

*DM_REMOTE_SERVICES
"//JEFF" RDOM=TDOM1

In this case, the domain name JEFF is located at the address "//JEFF:3186". That address might or might not have a UBBCONFIG file that specifies its domain name as JEFF. If it does, the request can be serviced immediately.

It is possible to have entries that send requests for the specified domain-name to an intermediary domain that acts as a pass-through for routing purposes.

The remaining optional parameter, TRANTIME = integer, specifies the default timeout value, in seconds, for a transaction automatically started for the associated service. The value must be greater than or equal to 0 (zero) and less than 2147483648. The default is 30 seconds. A value of 0 (zero) implies the maximum timeout value for the machine.

DM_LOCAL_SERVICES

The DM_LOCAL_SERVICES section specifies additional attributes for gateways that accept requests into the local domain from the outside.

Lines within this section have the form:

service [LDOM=<ldom-name>]
[ACL=...]

where service is of the form:

"//<domain-name>"

This <domain-name> is the name that occurs in the RESOURCES section of the UBBCONFIG file as <domain-name>. Most likely this is the name of the domain in which the gateway resides, meaning that this (local) domain accepts BEA Tuxedo CORBA environment requests from other domains. It is also possible (but not necessary, except for purposes of security) to have an entry that accepts requests for a different domain name in the case where the local domain acts as a pass-through for routing purposes.

Notice that exported services inherit the properties specified for the service in an entry in the SERVICES section of the TUXCONFIG file, or their defaults. Some of the properties that may be inherited are LOAD, PRIO, AUTOTRAN, ROUTING, BUFTYPE, and TRANTIME.

The optional parameter, ACL = identifier, specifies the name of the access control list (ACL) to be used by the local domain to restrict requests made to this service by remote domains. The name of the ACL is defined in the DM_ACCESS_CONTROL section. If this parameter is not specified, access control is not performed for requests to this service.

For example, the lines:

*DM_LOCAL_SERVICES
"//MUTT"

state that this domain accepts requests destined for the domain with name MUTT.

DM_ACCESS_CONTROL

The DM_ACCESS_CONTROL section specifies the access control lists used by a local domain. Lines in this section are of the form:

ACL_NAME required parameters

where ACL_NAME is an (identifier) name used to identify a particular access control list; it must be 15 characters or less in length.

The only required parameter is:

ACLIST = identifier [,identifier]

where an ACLIST is composed of one or more remote domain names (RDOM) separated by commas. The wildcard character (*) can be used to specify that all the remote domains defined in the DM_REMOTE_DOMAINS section can access a local domain.

Note: The factory_finder.ini and DMCONFIG files must be coordinated; that is, if the factory_finder.ini file declares another domain to have accessible factories, there must be a way in DMCONFIG to get to that domain.

The factory_finder.ini File

Administrators are required to identify any factory objects that can be used in the current (local) /Domain, but that are resident in a different (remote) /Domain. You identify these factories in a FactoryFinder domain configuration file, also referred to as the factory_finder.ini file. This is an ASCII file that can be created and updated using a text editor.

The factory_finder.ini file can be used to identify remote CORBA factories that can be used in the local domain.

The format of the factory_finder.ini file is modeled after the syntax used to describe /Domains, and is shown below:

*DM_REMOTE_FACTORIES
    "local_factory_id.factory_kind"
    DOMAINID="domain_id" 
    RNAME="remote_factory_id.factory_kind"
        ...

*DM_LOCAL_FACTORIES
    "factory_id.factory_kind"
    ...

Sample syntax for CORBA factory objects is as follows:

*DM_REMOTE_FACTORIES
    "AccountFactory.FactoryKind"
    "DOMAINID="MyAccountFactoryDomain"
    RNAME="MyAccountFactory.FactoryKind

where: AccountFactory is the name used to register the factory in the local domain's FactoryFinder, MyAccountFactoryDomain is the name of the remote domain, MyAccountFactory is the name used to register the factory in the remote domain's FactoryFinder.

The Master NameManager reads the factory_finder.ini file when the process is started. The reason for starting the Master NameManager affects which portions of the factory_finder.ini file are processed. If the Master NameManager is being started as part of booting an application, the initialization mode, the entire contents of the file is processed. As a result, the information in the DM_REMOTE_FACTORIES section results in entries being added for the factory objects being imported.

On the other hand, if the Master NameManager is being restarted as a result of a process failure, only the DM_LOCAL_FACTORIES section of the file is read. This section of the factory_finder.ini file must be re-read to reload the information that is used to restrict the exportation of certain factory objects into another domain.

Note: Since the Master NameManager reads the factory_finder.ini file only when the process is started, there is no way to update the Master NameManager (for example, when a new domain with factory objects to be imported needs to be added) without shutting down the Master NameManager.

A factory_finder.ini file applies to the domain in which it resides. It contains two sections: the DM_REMOTE_FACTORIES section and the DM_LOCAL_FACTORIES section. Either section can be absent or contain nothing.

The following sections provide more information on how to use the DM_REMOTE_FACTORIES section and the DM_LOCAL_FACTORIES section.

DM_REMOTE_FACTORIES

The DM_REMOTE_FACTORIES section provides information about the factory objects that are available in remote domains and that are imported so that applications in the local domain can use them. Identifiers for remote factory objects are listed in this section. The identifier, under which the object is registered, including a kind value of "FactoryInterface", must be listed in this section. For example, the entry for a remote factory object to be registered by the TP Framework with the identifier Teller in domain "Norwest" would be specified as:

*DM_REMOTE_FACTORIES
"Teller.FactoryInterface"
DOMAINID="Norwest"
RNAME="BankTeller.FactoryInterface"

If the RNAME is not specified, the factory_kind must be specified in the factory name and the factory name must be enclosed in quotation marks; otherwise, the NameManager is not able to locate the appropriate factory. An entry that does not contain a factory_kind value is not defaulted with a value of "FactoryInterface". The following example shows a factory object to be registered with the identifier Teller in domain "Norwest". Note the absence of the RNAME specification, the specification of the factory_kind value, and the quotation marks around the factory name.

*DM_REMOTE_FACTORIES
"Teller.FactoryInterface"
DOMAINID="Norwest"

Because the identities of factories in a multidomain configuration may collide, the factory identifier and the RNAME parameters allow you to specify alternative identities, or "aliases," in the local domain for remote factories. Listing 3-2 shows two examples of a remote factory that is registered by the TP Framework with the identifier BankTeller in domain "Norwest". In both examples, the factory is made available in local domain with an alias of Teller.

Assigning an Alias to a Remote Factory

#EXAMPLE 1:

*DM_REMOTE_FACTORIES
Teller
DOMAINID="Norwest"
RNAME="BankTeller.FactoryInterface"

#EXAMPLE 2:

*DM_REMOTE_FACTORIES
"Teller.FactoryInterface"
DOMAINID="Norwest"
RNAME="BankTeller.FactoryInterface"

You can also assign multiple aliases to the same remote factory. In the example shown in Listing 3-3, the remote factory will be registered in the local domain with two aliases: Teller and BankTeller.

Assigning Multiple Aliases to a Remote Factory

*DM_REMOTE_FACTORIES
"Teller.FactoryInterface"
DOMAINID="Norwest"
RNAME="BankTeller.FactoryInterface"
"BankTeller.FactoryInterface"
DOMAINID="Norwest"
RNAME="BankTeller.FactoryInterface"

Usage Note: In multidomain configurations, factory object identifiers must be unique across domains in the enterprise.

In a multidomain configuration, two different domains must not have factory objects with the same factory_id.factory_kind identifier, for example: "Teller.FactoryInterface".

If the same identifier, or name, is used in two domains, the software's behavior varies depending on whether BEA WebLogic Enterprise was used to configure the CORBA domain environment:

In releases prior to BEA WebLogic Enterprise 5.1, the software allows the first server in a domain to register the factory without issuing an error message. If two factories with the same name are registered in a domain, the Master NameManager fails.
In BEA WebLogic Enterprise release 5.1 or later and BEA Tuxedo release 8.0 or later, the software generates an error and writes it to the ULOG.

Note: In a single domain configuration, a BEA Tuxedo CORBA environment supports multiple factories objects with the same name. This type of configuration is allowed so as to achieve load-balancing.

There are two ways to ensure that your identifiers, or names, are unique across domains and thus avoid this problem:

Use unique identifiers throughout the enterprise. This may mean keeping a master list of all identifiers.
In the factory_finder.ini file, use the RNAME parameter so that an alias is used by the local NameManager. (This also means that local clients will have to be modified to use the alias to access the remote factory object.) Listing 3-2 shows an example of a factory_finder.ini file that uses the RNAME parameter to create an alias.

DM_LOCAL_FACTORIES

The DM_LOCAL_FACTORIES section specifies factory objects in the local domain that are available to be exported to other domains. This section can be used in the following ways:

If the DM_LOCAL_FACTORIES section does not exist in a factory_finder.ini, or exists but is empty, all factory objects in the local domain are available to remote domains. This allows administrators an easy means to make local factory objects available to remote domains without having to provide an entry for every factory object in the local domain.
If the DM_LOCAL_FACTORIES section exists in a factory_finder.ini file but contains the reserved keyword "NONE", none of the factory objects in the local domain are available to remote domains. This allows administrators to restrict access without having to provide an entry for every factory object in the local domain.

The identifier, or name, under which the factory object is registered, including a kind value of "FactoryInterface", must be listed in this section. For example, the entry for a factory object to be registered by the TP Framework with the identifier Teller would be specified as:

*DM_LOCAL_FACTORIES
"Teller.FactoryInterface"

The factory_kind must be specified for the NameManager to locate the appropriate factory object. An entry that does not contain a factory_kind value is not defaulted with a value of "FactoryInterface". This allows for the use of the CORBA NamingService.

The factory_finder.ini file specifies that the process of finding a factory can be exported to a remote domain by including a section beginning with "*DM_REMOTE_FACTORIES". In other words, including this section means that the local domain can find factories in a remote domain.

An entry into the file for domain A might be:

*DM_REMOTE_FACTORIES
fA.FactoryInterface DOMAINID=B

This means that a request in Domain A to find a factory with the identifier fA can be satisfied by the FactoryFinder in domain B. Of course, the UBBCONFIG and DMCONFIG files for the two domains must also be set up so that there are connected domain gateways between the two domains.)

An alternate form of the entry is:

CDE.FactoryInterface DOMAINID=B RNAME=fA.FactoryInterface

This means that a request in Domain A to find a factory with the identifier "CDE" will be satisfied by the FactoryFinder in domain B using the ID fA. This is sometimes called an alias.

Note: The factory ID must have ".FactoryInterface" at the end. For simplicity, when talking about test configurations, we will leave that off, but it should appear in the file.

For more information about the factory_finder.ini file, see the description of the factory_finder.ini file in the File Formats, Data Descriptions, MIBs, and System Processes Reference.

Local Factories

A domain can specify which of its factories can be accessed by other domains. This is specified in a section beginning with *DM_LOCAL_FACTORIES. If the factory_finder.ini file does not exist, or if it exists and this section does not appear, or is empty, all local factories can be accessed by remote domains. If the section exists and contains the keyword None, none of the local factories are exportable; that is, none are allowed to be found by a remote FactoryFinder. If the section exists, it can contain a list of factories available to remote domains. For example,

*DM_LOCAL_FACTORIES
fA.FactoryInterface
fB.FactoryInterface

This specifies that factories fA and fB are findable from other domains. All factories other than factories explicitly listed are not findable. Unlike remote factories, there is no provision for an alias with local factories.

Note: The factory_finder.ini and DMCONFIG files must be coordinated, that is, if the factory_finder.ini file declares another domain to have accessible factories, there must be a way in DMCONFIG to get to that domain.