Use Clearinghouse APIs

How to Leverage the Clearinghouse in Omni

This page covers features available starting in `omni 2.5`.

To determine the version of an existing omni installation run:

$ omni --version
omni: GENI Omni Command Line Aggregate Manager Tool Version 2.5
Copyright (c) 2014 Raytheon BBN Technologies

The common Clearinghouse API (CH API) is supported by:

• omni starting in version 2.5
• the GENI Portal and the GENI Clearinghouse

Tools such as omni and the Portal which support the CH API allow a user to leverage information from the clearinghouse in a number of ways:

• Query projects:
  • listprojects - list all my projects
  • listprojectmembers - list members of my project
• Query and manipulate slice memberships:
  • listslices - list all of my slices
  • listslicemembers - list members of my slice (and the member's public keys)
  • addslicemember - add member to my slice
  • When calling createsliver at a compute aggregate, create accounts loaded with the public key(s) for users in ''one or both'' of the following sets:
    • Members of the slice
    • Users listed in your omni_config
  • removeslicemember - remove a member from my slice
• Query and report reservations to the clearinghouse
  • createsliver/deletesliver / renewsliver now report reservations and deletions to the clearinghouse
  • listslivers / --useSliceAggregates - list/query aggregates and slivers known to contain resources in my slice (advisory information only - query the aggregates to know for sure)
  • --useSliceAggregates allows users to not (or not only) specify aggregates using -a and instead query for aggregates known to have resources in this slice when using the following calls:
    • listresources
    • sliverstatus / status
    • deletesliver / delete
    • renewsliver / renew
    • performoperationalaction (aka poa)
    • readyToLogin script
    • remote-execute script
• Add users to existing slivers

The clearinghouse only returns information in listslivers and via --useSliceAggregates which was reported to it via the CH API. As of February 2014, only omni and the GENI Portal report this information to the GENI clearinghouse.

Upgrading an existing omni_config to use the CH API

1. Update omni to version 2.5 or newer

2. Download your omni-bundle.zip from the portal

3. (Re-)run omni-configure

   • To configure omni to not use the CH API, instead run:

   omni-configure --not-use-chapi
   

Methods which query project membership

listprojects

To find the projects you belong to at the GENI Clearinghouse (and your role in each), run:

omni listprojects

listprojectmembers

To see the members of a project, with their role on the project and email address, run:

omni listprojectmembers myproject

Methods which query or manipulate slices and slice membership

listslices (a.k.a listmyslices)

To find the slices you have at the Clearinghouse, run:

omni listslices

listslicemembers

To find the list of members of your slice and the member's roles, run:

omni listslicemembers myslice

addslicemember (with and without role)

To add a member to a slice, run:

omni addslicemember myslice username

You can optionally specify a role of Admin, Member, or Auditor:

omni addslicemember myslice username admin

removeslicemember

To remove a member from a slice, run:

omni removeslicemember myslice username

listkeys

To find the list of public keys for the member specified by username, run:

omni listkeys username

Note that you must be in the same slice as the member identified by username.

If you query for yourself, you will see also any private SSH keys you have registered at the GENI Clearinghouse.

To determine a username, look at the output of listslicemembers. The username is the last part of the user's URN.

For example, the member with URN of urn:publicid:IDN+ch.geni.net+user+jdoe has username jdoe.

createsliver with slice members

By default, omni-configure will configure omni when used with a Portal account to reserve compute resources with accounts for all of the members of myslice and all users defined in your omni_config:

omni createsliver myslice myrspec -a myagg

To exclude users specified in your omni_config, add the --ignoreConfigUsers option:

omni createsliver myslice myrspec -a myagg --ignoreConfigUsers  

If you are using a Portal account with a default configuration, you may notice that your omni_config has useslicemembers set to True (which is equivalent to always using --useSliceMembers) which will cause slice members to be included by default.

To disable this behavior, do the following:

• In your omni_config (which is usually in ~/.gcf/omni_config), add # to the start of the line defining the value of useslicemember (in the [omni] section) so that it looks like this:

  # useslicemembers = True
  

• Call createsliver as usual:

  omni createsliver myslice myrspec -a myagg
  

Methods which query or report reservations to the clearinghouse

createsliver / deletesliver / renewsliver

createsliver/deletesliver / renewsliver now report reservations and deletions to the clearinghouse.

listslivers

To determine the list of all aggregates and slivers that the clearinghouse knows are reserved in a slice, run:

omni listslivers myslice

Note that this list is not authoritative; a reservation made with a tool that doesn't talk the CH API will not be listed, or your reservation may have succeeded but your tool failed to report the reservation to the clearinghouse. Query the aggregates directly to get authoritative information.

--useSliceAggregates

--useSliceAggregates allows users to not (or not only) specify aggregates using -a and instead (or also) issue the command at aggregates known to have resources in the given slice when using the following calls:

• listresources
• sliverstatus / status
• deletesliver / delete
• renewsliver / renew
• performoperationalaction (aka poa)
• readyToLogin script
• remote-execute script

Add a User to a Slice and existing Slivers

It is possible to add a member to an existing slice (using addslicemember) and then add that member's account and keys to existing slivers (using poa geni_update_users). However, since it is difficult to get the options correct for this sequence of calls, there is a script called addMemberToSliceAndSlivers which does this combination of steps.

poa geni_update_users

To add the slice members to existing slivers, use poa by running:

omni -V 3 poa myslice geni_update_users -a myagg --useSliceMembers

addMemberToSliceAndSlivers.py

To add a new member to a slice and then any existing aggregates, run:

addMemberToSliceAndSlivers.py myslice username