12.0 Legion domains

Legion version 1.3 and forward support the concept of linking together discrete Legion systems. Previously, each was an isolated entity: objects running in one system could not communicate with objects running in another system. In current versions, each Legion system constitutes its own domain: every domain contains all features necessary for running any Legion application, so that a domain can be run autonomously. However, multiple domains can be combined to form a larger virtual machine. Objects created in one of these domains can communicate with and use the services of other objects in connected domains.

12.1 Naming Legion domains

A domain is automatically assigned system-level a domain identifier when it is first created, i.e. when a new Legion system is configured with the legion_setup_state command. By default, a four-byte random domain identifier is selected and assigned, although the domain identifier is a variable-length field of bytes. It is embedded into all Legion object identifiers (LOIDs) as the second field. For example, in the following LOID the domain identifier is c8.


In a LOID from a different domain, the domain identifier is 35d82a07.


All class objects in a domain will use the same domain identifier when assigning new objects LOIDs. If legion_setup_state is run interactively (with the -i flag) you can specify the identifier (note, though, that once chosen the domain identifier cannot be changed).

You must have root user privileges in your current domain in order to connect with other domains (i.e, you must be logged in as /users/admin).

12.2 Domains and binding services

In order to locate an object in a given domain, you need to contact the domain's binding services, which can then track down the object's LOID and location. However, if you know the domain's LegionClass (the metaclass of each Legion system) object's binding (its LOID and Object Address [OA]) you can find the domain's binding services. The legion_print_config tool will display the binding. For example:

$ legion_print_config
 - LegionClass Configuration -
LOID = 1.35e09dfb.01..000001fc0b347...
OA   = [ : 6384 : 903989954 ]

The LegionClass's binding is found in a file called LegionClass.config in each domain's $LEGION_OPR directory. The LegionClass.config file is a LegionBuffer, however, and to mask the data format of the file's contents the file is accompanied by a file called LegionClass.config._LegionStorage _MetaData_. If the metadata file is not present the LegionClass.config file may be unreadable.

12.3 Joining domains

Legion domains can be combined together to form larger systems with the legion_combine_domains command. This tool connects your current domain (i.e., the one in which you execute the command) to a specified target domain. If other domains have already been connected to either your current domain or to the target domain, they will be part of the new, larger system as well.

When this command is executed, it determines the bindings of all LegionClass objects involved, makes up a list, and send a copy of the list to each one. The domains' binding trees are then connected so that binding requests for another domain can be forwarded by one domain's LegionClass to the appropriate domain's LegionClass object (although binding caches and the class-of operations involved in the binding process will minimize the need for interdomain binding-related traffic between LegionClass objects).

In effect, a set of joined LegionClass objects represent a distributed class map. As in earlier versions, the global (now distributed) Legion class map is protected from contention by heavy caching.

12.4 Related commands

There are two commands related to Legion domains: legion_list_domains and legion_combine_domains. The former lists the set of domains currently connected to your domain and the latter will connect a new domain to your domain.

12.4.1 Listing currently connected domains

You can use the legion_list_domains command to view a list of those domains connected to your current domain. The output will list your current domain's binding and any domains linked to your current domain.

$ legion_list_domains
Current Legion domain root:
Type 302 binding:[ 1.35d82a07.01..000001fc0
   d6df : [ : 19870 : 903621581 ] ]
Linked external Legion domain roots (1):
Type 302 binding:[ 1.c8.01..000001fc0a533f0
   35487150edf8256d78002bb04454da7eae82697 :
   [ : 16022 : 903624927 ] ]

This output shows that there are two domains and lists each domain's binding (its LegionClass object's LOID and OA). The current domain is listed first. Note that the domains' identifier can be seen in the second field of the two LegionClass LOIDs: the first is 35d82a07 and the second is c8.

If you are in a single domain system, the output will simply list your current domain's binding.

$ legion_list_domains
Current Legion domain root:
Type 302 binding:[ 1.35d82a07.01..000001fc0
   d6df : [ : 19870 : 903621581 ] ]
No linked external Legion domains.
12.4.2 Connecting domains

The legion_combine_domains tool connects Legion domains together into a single, larger Legion system. Once joined, objects in connected domains can communicate with each other as easily as objects in a single domain communicate with each other. Usage of this command is:

legion_combine_domains [-help] [-v]
[-C <target domain context path>]
<OPR Directory for target domain>

Before you run legion_combine_domain, you must place a copy of the target domain's LegionClass object binding file (LegionClass.config) and related metadata file (LegionClass.config._LegionStorage_MetaData_), both located in the target's $LEGION_OPR directory (see Domains and binding services, above), in a directory in your local file system. This local path name is used as the <OPR Directory for target domain> parameter. The command uses the two configuration files to get the target domain's LegionClass object's binding.

Note, however, that the context spaces of connected domains will not be connected unless specified: this will complicate user naming of extra-domain objects. You can use the -C flag when combining domains to link context spaces. To use this option, please note, you must put a copy of the target domain's legion_context_env.sh file (also found in the $LEGION_OPR directory) in the local target domain configuration directory (i.e., the local directory holding the target domain's LegionClass configuration files). The legion_context_env.sh file is used to determine the LOID of the target domain's root context.

This option specifies a context path in your local domain's context space that can be used as the "root" context for the target's context space. The target domain's context space is not changed or moved by this option: the local domain context space is connected to the target domain's context space at the point named in the -C option. The two context spaces remain independent.

In this example, the target domain net2 is connected to the current domain and its context space is connected to the current domain's context space.

$ legion_combine_domains -C /home/net2 -v ~/OPR-net2
    Current Legion domain root:
    Type 302 binding:[ 1.35d82a07.01..000001fc0c0e21f5
       9a4ba9ecf995c8ddb20b16d6df : [ : 
       19870 : 903621581 ] ]
    Combined list of Legion 2 domain roots:
    Type 302 binding:[ 1.c8.01..000001fc0a533f08413082
       02bb04454da7eae82697 : [ : 16022 : 
       903624927 ] ]
    Type 302 binding:[ 1.35d82a07.01..000001fc0c0e21f5
       4ba9ecf995c8ddb20b16d6df : [ : 
       19870 : 903621581 ] ]
    Created 2 new domain interconnections.

The output first shows the current domain's LegionClass binding, then the list of the two LegionClass bindings, listing the newly added domain first. If other domains had been previously connected to the current or the target domain they would listed in the output as well. Note that the number of interconnections includes connecting the new domain to each previously linked domain: if you added another domain to this group you'd make four new interconnections.

Linking net2's context space to the current domain's context space creates the context path /home/net2. Depending on security and access privileges, you can view net2's context space with context-related commands.

Back to System Administrator Manual Table of Contents

Directory of Legion 1.5 Manuals