The domain server is a critical part of the XNMS infrastructure, holding the configuration and settings for up to hundreds of units over dozens of roles. With a domain server, a single configuration file change can result in the spontaneous update of each unit the domain oversees the next time it visits the region.

Glossary


  • Domain. The hierarchy to which the unit belongs. A unit may only belong to one domain at a time.
  • XNMS. Xanadu Network Management Service, the protocol used to interface between domain servers and units.
  • hierarchy. The Companion implementation of the XNMS client software.
  • AT/XNMS. The ATOS version of this server, which additionally defines combat-friendly zones and chassis configurations. (Not yet available.)
  • Candidate. A unit that has petitioned to join the domain.
  • Role. A category of unit as defined by the domain server. Every unit in the same role will have the same settings.
  • Manager. A user (unit or person) that will receive level 1 access on all units within a given role.
  • Administrator A user (unit or person) that will receive level 2 (owner) access on all units in the domain. The owner of the domain object is automatically an administrator.
  • Synchronization. The process of updating the unit's configuration to match that on the server.
  • Home region. the region (SL sim) where the domain server resides.
  • Pending. A unit that needs to synchronize. Units will be marked as pending if global settings change in the configuration file, or if their role changes. Units that are pending will automatically synchronize whenever they join the domain server's home region.
  • User access levels. See relevant table in the Companion manual.

    • Setup


    Install the domain server in an appropriate facility, edit the included _domain file, and then drop it into the server. The domain configuration file has the following fields:

    name <name>
    The name of the domain. This is what units will see when searching for a domain to connect to. To join a domain, units must type @domain set <name>. Once connected, the domain server's UUID is recorded, so it cannot be moved or usurped without requiring a re-installation on the unit.

    organization <name>
    The name of the domain's organization. The unit's authority field will be set to match.

    candidates private
    Disables joining the candidate role by unauthorized units.

    candidates group <id>
    Allows joining the candidate role by members of the Linden group indicated by UUID <id>.

    candidates public
    Allows joining the candidate role by any unit.

    admin <id>
    Specifies an administrator. Additional text on this line is ignored, so you can safely put the name of the user after it for convenience, e.g. admin d69ca06e-aa22-49e4-86e1-42677e26f3f5 rhet0rica

    role <role name>
    Specifies the start of a role. Certain fields specified after this one will then apply only to that role. They are described in the next section. To define multiple roles, append them successively.

    role none (new in 2.0)
    Removes the role restriction from subsequent commands; useful for remove manager. (See below.)

    ban <id> (new in 2.0)
    Forbids the user <id> from joining the domain. If this is input over the command line (see further down this document), then <id> will also be removed from the domain completely.

    Role setup


    policy-file <name>
    Indicates the name of a command script to run on units after they synchronize. This is a list of system commands, similar to an Arabesque or Navigation action script, although as the commands are executed asynchronously, features such as waiting and flow control do not work. Changes to this file will mark the unit as pending (see Glossary, above).

    member <id>
    Specifies that a unit is part of the indicated role. A unit may only belong to one role at a time. As with the 'admin' field, text after the key is ignored, so you can safely include the unit's name after the key for mnemonic purposes.

    manager <id>
    Specifies a person or unit to be given level 1 (manager) access to the role. As with the 'admin' field, text after the key is ignored, so you can safely include the manager's name after the key for mnemonic purposes.

    flags <flags>
    A series of keywords separated by spaces: USERS_POOL, LOCK_USERS, MANAGE_SELF, and NO_SELF.

  • USERS_POOL Other members of the group will automatically be given level 0 access on their siblings.
  • LOCK_USERS: The unit's user list cannot be changed locally and must be changed through the domain. The unit must leave the domain to re-enable user control. WARNING: This disables the 'keychain reset' command.
  • MANAGE_SELF: The unit is granted level 1 access over itself.
  • NO_SELF: The unit is not added to its user list at all. Takes priority over MANAGE_SELF.

    • By default, a unit is granted level 0 access over itself.

    prefix <name>
    Changes the unit's prefix to <name>. This will revert to the value set in the unit's OEM table if it leaves the domain.

    Removal commands


    remove manager <id> (new in 2.0)
    Removes the specified key from the current role, or all roles if no role has been specified; clear the current role with role none (above).

    remove admin <id> (new in 2.0)
    Removes the specified key from the admins list. The owner of the domain server cannot be removed.

    remove member <id> (new in 2.0)
    Removes the specified key from the domain as a user.

    remove ban <id> (new in 2.0)
    Unbans the specified key.

    remove role <name> (new in 2.0)
    Removes the specified role from the domain. All members of the role will become candidates. The 'candidates' and 'exec' roles cannot be removed.

    Command-line control


    As of version 2.0, any of the above commands can be sent directly over channel 4040 by a registered administrator of the server, or an object belonging to an administrator. These commands are also supported using the Facet HUD, in which case response messages will be sent on channel 0 directly to the administrator.

    Command-line control also offers two extra directives:

    query <key>
    Returns <role> <key> as a response. Administrators will be reported as having the role 'exec', managers with no role of their own will be 'manager', banned users will be 'banned', and unknown users will be 'none'. (Future versions may make manager reporting more informative.)

    dump
    Returns a raw dump of most of the data structures in XNMS; useful for updating the schema file, though significant reformatting will be required. The users table is of particular importance; it lists each avatar's key, the index of the role it belongs to (starting from exec = 0), and a flag indicating whether or not the avatar needs to be synchronized (-2 = up-to-date, -3 = update required).

    To add a role, or to modify an existing role, first name that role using the role command (described under 'Setup', above) and then type other commands as you would in the configuration file, e.g. member to define a unit as part of the selected role. The member command will automatically remove the unit from its previous role if it had one and schedule members of both roles for resynchronization if those roles have USERS_POOL enabled.

    Candidates


    When a candidate joins the domain, it is automatically added to a role named 'candidate'. This role can be altered like any other by adding "role candidate" to the configuration file followed by role setup fields (see above). In version 1.0, there is no way to move a unit from the candidate role except by adding it to another role in the domain configuration file. Version 2.0 introduces command line control; see below.

    Example


    Sample _domain file


    # the name of the domain (no spaces)
    name NanoSec

    # name of the organization
    organization Nanite Systems Security Division

    # candidates must be one of: 'private', 'group <id>', or 'public'
    candidates group cf29ace4-6117-ab55-0f9c-3ba9006322a4

    # domain admins (in addition to the server object's owner)
    admin d45552db-1a7d-4a57-b97d-c435474bd39d Tam

    # roles
    role chief
    policy-file nanosec-default
    flags USERS_POOL LOCK_USERS MANAGE_SELF
    prefix chief
    member 75b4c7a9-6cb1-4b9a-a291-11fe2907db06 LY-N13L

    role officer
    policy-file nanosec-default
    flags USERS_POOL LOCK_USERS
    prefix officer
    member 30db3b4f-c0c5-4816-9a9e-ae8b769d616c erth3
    member 9091b2e3-6f09-474c-9255-c8b2560d763c Twist
    member 23a0a303-cb23-4c7c-b4d4-499bcd88f432 ekh3ssa
    member e5667c23-fe15-4f4a-af89-d56273f33dc9 Tai
    manager 75b4c7a9-6cb1-4b9a-a291-11fe2907db06 LY-N13L

    role candidate
    policy-file nanosec-default
    flags USERS_POOL LOCK_USERS
    prefix trainee
    manager 75b4c7a9-6cb1-4b9a-a291-11fe2907db06 LY-N13L

    Sample policy file


    color 0.5 0.5 1.0
    policy apparel lock
    xanadu connect xexample:0
    xanadu update example-package
    xanadu disconnect

    A list of valid system commands can be obtained by using the help command on a controller. These commands are executed directly by the system and are not processed by Arabesque, so features like waiting, flow control, and variable substitution are not available.

    Support


    For additional support, contact rhet0rica on Tuesdays and Wednesdays, or support@nanite-systems.com the rest of the week.