17.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: a domain contains all features necessary for running any Legion application and 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.

17.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). The domain identifier is a variable-length field of bytes. It is embedded into all of the domain's Legion object identifiers (LOIDs) as the second field. For example, the domain below has a one-byte domain-id, c8:


A different domain has a four-byte domain-id, 35d82a07:


All class objects in a domain will use the same domain identifier when assigning new objects LOIDs. You can specify the identifier if legion_setup_state is run interactively (with the -i flag). Otherwise Legion will select a four-byte domain-id. Once the domain-id has been assigned, it 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).

17.2 Domains and binding services

To locate an object in another domain you must 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's binding (i.e., the LOID and Object Address of the domain's metaclass) you can find the domain's binding services.

You can use the legion_print_config tool to display your current domain's LegionClass binding.

$ 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.

17.3 Joining domains

Legion domains can be combined together to form larger systems with legion_combine_domains. 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 multidomain system as well.

To perform this operation, the tool makes the domains' LegionClass objects aware of one another. In practice, this involves determining the bindings of all of the involved LegionClass objects and broadcasting the complete binding set to all of the LegionClass objects. Once this operation has been performed, the binding trees of the different domains will be connected. In effect, the set of joined LegionClass objects represent a distributed class-map. Binding traffic that reaches LegionClass in your current domain but is related to another domain will be forwarded to the LegionClass object in the appropriate domain. Binding caches and the class-of operations involved in the binding process will minimize the need for interdomain binding-related traffic between LegionClass objects). As in earlier versions of the system, the global (now distributed) class-map in Legion is protected from contention by heavy caching.

To do its job, legion_combine_domains needs to have information about each domain that it will be linking. If Legion security is turned on in any of the involved domains it will also need security credentials for each secure domain in order to authorize it to link external domains. This domain information is stored in the form of a domain cookie. A domain cookie is simply a file holding the needed binding information and security credentials for a single Legion domain. The legion_generate_domain_cookie command creates a cookie file and legion_print_domain_cookie displays it.

17.4 Related commands

There are four commands related to Legion domains. The legion_list_domains command lists the set of domains currently connected to your domain, legion_combine_domains connects domains, legion_generate_domain_cookie generates a domain cookie for a domain, and legion_print_domain_cookie displays the cookie.

17.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.

17.4.2 Generating cookies

As the name suggests, the legion_generate_domain_cookie command generates a cookie file for your current Legion domain. Usage is:

legion_generate_domain_cookie [-help]
   [-o <cookie output filename>]

The cookie contains binding information for your domain's LegionClass, security credentials, and information about your domain's context space. By default, the new cookie file will be named LegionDomainCookie.<domain-id>. Use the -o flag to specify a different name.

If security has been turned on, you must be logged in as /users/admin in your current domain in order to ensure that the proper credentials are generated and saved in the cookie file.

17.4.3 Displaying cookies

The legion_print_domain_cookie command will display the contents of a Legion domain cookie file. By default, the command will display the contents of LegionDomainCookie.<domain-id>. Use the -i flag to specify a different cookie filename.

17.4.4 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]
    <list of domain cookie files>

Before you run legion_combine_domain, you must obtain a copy of the domain cookie files from all of the domains involved (i.e., if you wish to join a multidomain system you must have copies of all of the domains' cookie files).

In this example, two domains are connected together.

$ legion_combine_domains LegionDomainCookie.35d82a07 \ 	
Created 2 new domain interconnections

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.

Directory of Legion 1.6.4 Manuals
[Home] [General] [Documentation] [Software]
[Testbeds] [Et Cetera] [Map/Search]

Free JavaScripts provided by The JavaScript Source