How To Specify Aggregates

How to Specify Aggregates in Omni

Aggregates are typically specified using the -a option to a variety of commands in omni.

For example, to get the version of a single aggregate, you would run the following command:

omni.py -a <aggregate> getversion

There are two ways to specify an aggregate using the -a option. <aggregate> can either be:

• the full url of the aggregate or
• it can be an aggregate nickname.

Omni determines which aggregates to run a command against using the following algorithm:

1. all aggregates specified using the -a option on the command line (more than one -a is allowed)
2. if no -a is specified, omni falls back to using all aggregates specified using aggregates in the [omni] section of the omni_config
3. if neither of the above is specified, omni falls back to using all aggregates known to the clearinghouse as determined by a call to omni.py listaggregates

---

`createsliver` can only be run against a single aggregate at a time.

---

Starting in `omni 2.5`, instead of or in addition to specifying `-a`, try using --useSliceAggregates to act at all aggregates known to the clearinghouse to contain resources in the given slice.

Aggregate URL

Aggregate URLs can be determined by using the output of:

omni.py listaggregates

For example, to call getversion at the GPO InstaGENI rack, do:

omni.py -a https://www.instageni.gpolab.bbn.com:12369/protogeni/xmlrpc/am/2.0 getversion

Aggregate Nicknames

Aggregate nicknames are a short string specified in the omni_config (or the agg_nick_cache) that substitute for the full url of the aggregate. Aggregate nicknames are similar to RSpec nicknames.

Aggregate Nicknames can be determined by using the output of:

omni.py nicknames

For example, to call getversion at the GPO InstaGENI rack, do:

omni.py -a ig-gpo getversion

User-specified aggregate nicknames

Users can specify aggregate nicknames in the [aggregate_nicknames] section of their omni_config (which is usually located in ~/.gcf/omni_config).

The default [aggregate_nicknames] section looks like the following (although in the original the boston line is commented out):

#------AM nicknames
# Put your custom aggregate nicknames here.
# To see all available nicknames try: omni.py nicknames
# Format :
# Nickname=URN, URL
# URN is optional
[aggregate_nicknames]
boston=urn:publicid:IDN+instageni.gpolab.bbn.com+authority+cm,https://boss.instageni.gpolab.bbn.com:12369/protogeni/xmlrpc/am/2.0

Using the boston nickname in the above, would allow you to do:

omni.py -a boston getversion

If there is a conflict, nicknames specified in the `omni_config` take precedence over nicknames specified elsewhere (i.e. in the `agg_nick_cache`). In particular, omni should work seamlessly for users using an `omni_config` generated for use with versions of `omni` prior to 2.4.

In Detail: Default aggregate nicknames and the agg_nick_cache

Starting in omni 2.4, default aggregate nicknames have been split out of the omni_config into a separate file called agg_nick_cache that Omni downloads when used (but at most daily) from the master branch.

These default aggregate nicknames are very useful as they specify nicknames for each production GENI aggregate. Since the cache is updated daily, experimenters will get access to nicknames for new GENI racks and aggregates as they come online, without waiting for a new release of Omni. (No action is needed by experimenters and old nicknames will still work.)

By default, omni.py stores a local copy of agg_nick_cache in ~/.gcf/agg_nick_cache. If that file is more than a day old, it will download a new copy of the file. If that file doesn't exist and omni can't download an updated copy, it will fall back to a file distributed with gcf called agg_nick_cache.base. Since the agg_nick_cache is frequently and automatically overwritten, users should not modify the agg_nick_cache by hand.

To control when or whether the agg_nick_cache is updated, use the command line options listed under omni.py -h in the section called "Aggregate Nickname Cache".