2.1 Calls on objects

legion_configure_profile

Edits information about your user profile, security settings, and fault tolerance settings. It is menu-driven. Hit the <enter> key to return to the previous menu level. When you run this command you'll be given the following options:

  1. Edit Profile
  2. Security
  3. Fault Tolerance

The first option lets you edit your AuthenticationObject to include your e-mail address, name, and company.

The second option changes your security preferences for the message layer. You have the following choices:

  1. Off (No encryption/No digest)
  2. Protected (Digested messages/Encrypted credentials)
  3. Private (Encrypted messages/Encrypted credentials)

These will change the settings for messages passed by your objects. We STRONGLY recommend that you read section 7.0 in the System Administrator Manual before using these options.

The third edits your fault tolerance settings for SKCC objects. The options are:

  1. Edit SKCC Policy (default # backups - per user )
  2. Edit SKCC Policy (default # backups - class-wide, class owner only)
  3. Edit SKCC Vaults (class owner only)

These affect your SKCC objects (BasicFileClass, ContextClass, ImplementationObject, and UserAuthenticationObject are the default SKCC objects). Please see section 6.6 in the Basic User Manual for information on SKCC. Note that these options will affect previous settings. It uses the following commands to edit your settings:

  • legion_skcc_set_class_vaults (page 11)
  • legion_skcc_set_defaults (page 11)
  • legion_set_backup_vaults (page 18)
  • legion_class_vault_list (page 46)

Note that you cannot change settings on objects that you do not own or have permission to edit. If you are not the class owner, you can use the first option to set the default number of backup vaults for your SKCC objects.

legion_exports_interface
     {[-c] <context name> | -l <LOID>}
     {-w <well-known class type> | -f <function signature>}+
     [-debug] [-help]

Creates an interface from the list of <well-known class type> and <function signature> arguments specified in the argument list. Sends this interface to the object specified by <LOID> or <context path> in the form of a call to the object mandatory function named exportsInterface(). Prints to standard output the return value from the call:

1

if the interface of the object contains the entire interface of functions specified by the user

0

if any one or more of the functions are not exported by the object

-1

(without contacting the specified object) if the user creates a malformed argument list

The <well-known class type> argument is a string in the set of well-known strings. The set can be listed with legion_wellknown_class (see page 60).

For this tool's purposes, ClassObject is a well-known class string. CommandLineClass and BootstrapMetaClass are not considered well-known classes because they do not have any special member functions, as shown in the examples below.

$ legion_exports_interface /class/LegionClass \    
   -w ClassObject
1
$

$ legion_exports_interface /class/LegionClass \
    -w CommandLineObject
"CommandLineObject" is not a well known class. Exiting.
-1
$

$ legion_exports_interface /class/LegionClass \
   -w LegionClass -w ClassObject
1
$

$ legion_exports_interface /hosts/BootstrapHost \
   -w UnixHostClass
1
$

$ legion_exports_interface /hosts/BootstrapHost \
  -w ClassObject
0
$

$ legion_exports_interface /class/LegionClass \
   -f "     LegionLOID ping();"
1
$

$ legion_exports_interface /hosts/BootstrapHost \
   -f "     LegionLOID ping();" -w UnixHostClass
1
$

The following options are supported:

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

legion_get_interface 
     {[-c] <class context name> | -l <class LOID>} [-debug] [-help]

Retrieves the interface of a Legion object, named by <class LOID> or <context path>, by calling that object's getInterface() member function. Prints the returned interface to stdout.

The following options are supported:

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

legion_ping
     {[-c] <object context name> | -l <object LOID>} 
     [-timeout <seconds>] [-debug] [-help]

Calls the object-mandatory ping() member function on the object named in <object LOID>. If the command returns, the object exists in an active state and its LOID is displayed.

$ legion_ping foo
Pinging:  1.01.66000000.14000000.000001fc0a72...
Returned: 1.01.66000000.14000000.000001fc0a72...
$

If the object is not accessible by the tool, the command will return an error.

$ legion_ping foo
"foo" does not resolve to a valid loid in my context.

The following optional parameters are available:

-timeout <seconds>

The time-out flag specifies a maximum number of seconds to wait for the ping to complete successfully. If the object does not respond to the ping within that amount of time, legion_ping will exit. Please note that legion_ping failing due to a user-specified time-out does *not* necessarily mean that the object is inactive or otherwise unreachable. There is no default time-out setting.

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

legion_list_attributes 
     {[-c] <object context name> | -l <object LOID>} 
     [-L] [<attribute name>] [-debug] [-help]

Lists an object's attributes from the command line. Optional parameters do the following:

-L

Lists the LOID of each attribute.

<attribute name>

Specify the attribute to be listed (more than one attribute can be listed).

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

A very simple example of this command is below. An object's attributes can include architecture, operating system information, host or vault compatibility, encryption information, etc.

$ legion_list_attributes Foo
Foo:
  (ALL)
Total attributes retrieved 1
        favoritecolors('puce', 'apricot')
$
legion_list_invocations 
     {[-c] <object context name> | -l <object LOID>} [-debug] [-help]

Prints a list of currently pending, started, and recently completed invocations for a given object. The output will include information about each invocation's status, timing, progress, and errors.

The following options are supported:

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

legion_object_info 
     {[-c] <object context name> | -l <object LOID>} 
     [-v] [-debug] [-help]

Prints information about a given object. The output (obtained from the object's class) will include the object's host, vault, owner, Object Address, status, etc. Optional parameters do the following:

-v

Print additional details about the specified object (host machine name and context name, OPA, and vault context name).

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

legion_skcc_set_class_vaults
     <SKCC class context path> 
     {[-a | -d] [-c <vault1 context path> | -l <vault1 LOID>]
        [-a | -d] [-c <vault2 context path> | -l <vault2 LOID>] ...
          [-a | -d] [-c <vaultn context path> | -l <vaultn LOID>]}

Set an allowable set of backup vaults on which to store the specified SKCC class's replicated state. This applies to all of the class's instances.

Backup vaults are used to replicate an object's persistent state: the object's persistent state is replicated and stored in multiple vaults when it is deactivated, so that if its main vault crashes, its state is still available. However, the replication policy synchronizes the object's state when the object deactivates: if the main vault crashes while the object is still active, the backup vaults will not have the object's current state. If the object needs to be reactivated, it will use an out-of-date state.

This overwrites any policies set via legion_class_vault_list (page 46). If you do not use legion_skcc_set_class_vaults, Legion will use the class vault restriction lists as specified with legion_class_vault_list. The specified class must belong to the SKCC metaclass. Current members are BasicFileClass, ContextClass, ImplementationObject, and UserAuthenticationObject.

You can use legion_set_backup_vaults to set vaults for a specific instance (page 18). Note, however, that legion_set_backup_vaults will overwrite the policy set by legion_skcc_set_class_vaults for that instance.

The following parameters must be used:

-l <SKCC class LOID> or
-c <SKCC class context path>

Specify an SKCC class object.

-a

Add the specified vault to the object's list of backup vaults

-d

Delete the specified vault

legion_skcc_set_defaults
     {[-l <SKCC class LOID> | -c <SKCC class context path>}
     <number of default vaults>

Specifies default level of state replication for instances of an SKCC class. Legion will now by default attempt to copy the instances' state on the specified number of vaults. You must be the class's owner to set this default.

The specified class must belong to the SKCC metaclass. You must have previously set up the class's backup vaults with the legion_skcc_set_class_vaults command (page 11). Currently, BasicFileClass, ContextClass, ImplementationObject, and UserAuthenticationObject are SKCC classes.

The following parameters must be used:

-l <SKCC class LOID> or
-c <SKCC class context path>

Specify an SKCC class object.

<number of default vaults>

The maximum number of backup vaults that will hold copies of the SKCC class object's state.

legion_set_worm
     [[-c] <object context path> | -l <object LOID>]

This command tells Legion that the specified object has Write-Once Read-Many (WORM) semantics and can be used for caching and replicating purposes.

It should be used in conjunction with legion_unset_worm (page 12) and legion_set_backup_vaults (page 18).

legion_unset_worm
     {[-c] <instance context path> | -l <instance LOID>}

This command tells Legion that the specified object no long has Write-Once Read-Many (WORM) semantics.

It should be used in conjunction with legion_set_worm (page 12) and legion_set_backup_vaults (page 18).

legion_update_attributes 
     {[-c] <object context path> | -l <object LOID>} 
     [-a <new attribute>] 
     [-d <attribute>] 
     [-r <old attribute> <new attribute>] 
     [-debug] [-help]

Adds, deletes, and replaces an object's attributes. The attribute(s) takes the form "name('val1 ... valn')". The attribute description must not contain any spaces or begin with an uppercase letter.

Optional parameters do the following:

-a <new attribute>

Add an attribute.

-d <attribute>

Delete an attribute.

-r <old attribute> <new attribute>

Replace an attribute.

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

The following example adds the attribute color('red,blue') to object Foo, with the -a flag.

$ legion_update_attributes Foo -a "color('red,blue')"
legion_update_attributes: Added 1 attributes(s) to object
$

Similarly, you can remove attributes, with the -d flag. Note, however, that if you must provide all of an attribute's parameters:

$ legion_update_attributes Foo -d "color('red')"
legion_update_attributes: Warning - Deleted 0 attributes(s)
from object instead of 1 specified

$ legion_update_attributes Foo -d "color('red,blue')"
legion_update_attributes: Deleted 1 attributes(s) from object
$

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

Free JavaScripts provided by The JavaScript Source

legion@Virginia.edu
http://legion.virginia.edu/