wiki:GeniGet

  1. geni-get
    1. Return codes
    2. Specification Questions
  2. PG implementation
  3. EG implementation
    1. Known Issues
  4. Usage
  5. Output
    1. commands
    2. client_id
    3. control_mac
    4. geni_user
    5. getversion
    6. manifest
    7. slice_email
    8. slice_urn
    9. sliverstatus
    10. status
    11. user_email
    12. user_urn
    13. --version
    14. --client-version
    15. --all

geni-get

A command that runs on and is accessible from inside a GENI compute resource (node) and tells you GENI meta-information about the slice, sliver and experimenter associated with the node. This is a separate tool that may be installed in your disk image. All GENI compute resource providers shall make available a version of this client script that can be installed on their compute resources such that the below functionality works.

Within this specification, client refers to any software or configuration installed on the compute resource (node). server refers to any software or configuration required to support these functions that is not installed within each compute resource, if any.

Return codes

This script shall return an unix error code of 0 for success, and non-zero on any kind of error.

FIXME: Defined error codes for the script?

Specification Questions

  • Define valid error return codes

PG implementation

EG implementation

Please reference the installation documentation at: ​https://geni-orca.renci.org/trac/wiki/NEuca-guest-configuration

Known Issues

  • Slice email for GPO SA slices is incorrect

Usage

The client script shall support the options as described below.

Required options that all scripts must actively support:

  • --all
  • --help
  • --client-version
  • --version

Options that may have no effect for some client implementations but must be valid options:

  • --no-cache
  • --port

Notes

  • client version refers to the version of the geni-get script.
  • no-cache means the script should re-query the server for the latest information. Note that this option may have no effect for some implementations.
  • version refers to the version of this specification, currently 1
  • port may not be relevant for all implementations, but should always be allowed (for consistency)

Sample help output, showing options that must be allowed by the client-side script: 

$ geni-get --help
Usage:
    ./geni-get [options] [command]

Options:
    -a, --all             dump all information available
    -c, --client-version  display client version
    -h, --help            show this message
    -n, --no-cache        disable reading cached results
    -p, --port            specify server port
    -v, --version         display specification version

Try "./geni-get commands" for a list of supported commands.

Output

commands

Return a list of all commands that you can issue in this implementation. The return is a JSON array. Each of the commands listed below should be supported, but additional commands are allowed.

Example: 

$ ./geni-get commands
{
 "client_id":    "Return the experimenter-specified client_id for this node",
 "commands":     "Show all available commands",
 "control_mac":  "Show the MAC address of the control interface on this node",
 "geni_user":    "Show user accounts and public keys installed on this node",
 "getversion":   "Report the output of 'getversion' from the aggregate that allocated this node",
 "manifest":     "Show the manifest RSpec for the local reservation",
 "slice_email":  "Retrieve the e-mail address from the slice certificate that owns this node",
 "slice_urn":    "Show the URN of the slice that owns this node",
 "sliverstatus": "Give the current status of this sliver (AM API v2)",
 "status":       "Give the current status of this sliver (AM API v3)",
 "user_email":   "Show the e-mail address of this sliver's creator",
 "user_urn":     "Show the URN of this sliver's creator"
}

client_id

Return the client_id from the RSpec for this node. This can be used to identify which node this is from your RSpec. The return is a string.

Example: 

$ geni-get client_id
bbn-ig-jbs15

control_mac

Return the MAC address for the control plane interface on this node. The return is a string.

Example: 

$ geni-get control_mac
02bed2ecdc92

geni_user

Return the users and SSH keys installed on this node. Return is in the format of the geni_user argument to the AM API: ​http://groups.geni.net/geni/wiki/GAPI_AM_API_V3/CommonConcepts#geni_users

Note that this return shall include include any changes to the defined users and keys made through later AM API calls (e.g. PeformOperationalAction action geni_update_users), but not calls made directly within the compute node.

Example: 

$ ./geni-get geni_user
[{"urn":"urn:publicid:IDN+ch.geni.net+user+ahelsing","keys":["ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAwhxWkZuS20ow0MnVeSiiRar55Qgy1GA74HIxgiMSPiqQEL3fjufyO/g6FK7R659oNQRbvLlrN5zpaDQ4MBk/JLTt6NO+9IUsB6HlI2P5q8bVyRpUf6E3SJh2iZWQCLDheyBk1+SjJsmH8ovjrWpfZuABIHYaH2gc3hy0igXiaYeYAF8jH8G+cmDcjd2+lQDwi7PhyOxM5Ai4u+kw16su1HFXBNkDZ0e7+YtPVElDC4TCBmt0O98gPVjcIsD1pDgSbdsTZe6zqLBgujrPQhC72eADtoi3WCMiyo+GPEPeYRrZo4H9vSt2pdIg9E73wJPgCu/LcAql2FJh/glsIqpIhw== ahelsing@hotcocoa2"]},{"urn":"urn:publicid:IDN+ch.geni.net+user+sedwards","keys":["ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAwhxWkZuS20ow0MnVeSiiRar55Qgy1GA74HIxgiMSPiqQEL3fjufyO/g6FK7R659oNQRbvLlrN5zpaDQ4MBk/JLTt6NO+9IUsB6HlI2P5q8bVyRpUf6E3SJh2iZWQCLDheyBk1+SjJsmH8ovjrWpfZuABIHYaH2gc3hy0igXiaYeYAF8jH8G+cmDcjd2+lQDwi7PhyOxM5Ai4u+kw16su1HFXBNkDZ0e7+YtPVElDC4TCBmt0O98gPVjcIsD1pDgSbdsTZe6zqLBgujrPQhC72eADtoi3WCMiyo+GPEPeYRrZo4H9vSt2pdIg9E73wJPgCu/LcAql2FJh/glsIqpIhw== ahelsing@hotcocoa2"]},{"urn":"urn:publicid:IDN+ch.geni.net+user+tmitchel","keys":["ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAwhxWkZuS20ow0MnVeSiiRar55Qgy1GA74HIxgiMSPiqQEL3fjufyO/g6FK7R659oNQRbvLlrN5zpaDQ4MBk/JLTt6NO+9IUsB6HlI2P5q8bVyRpUf6E3SJh2iZWQCLDheyBk1+SjJsmH8ovjrWpfZuABIHYaH2gc3hy0igXiaYeYAF8jH8G+cmDcjd2+lQDwi7PhyOxM5Ai4u+kw16su1HFXBNkDZ0e7+YtPVElDC4TCBmt0O98gPVjcIsD1pDgSbdsTZe6zqLBgujrPQhC72eADtoi3WCMiyo+GPEPeYRrZo4H9vSt2pdIg9E73wJPgCu/LcAql2FJh/glsIqpIhw== ahelsing@hotcocoa2","ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAwhxWkZuS20ow0MnVeSiiRar55Qgy1GA74HIxgiMSPiqQEL3fjufyO/g6FK7R659oNQRbvLlrN5zpaDQ4MBk/JLTt6NO+9IUsB6HlI2P5q8bVyRpUf6E3SJh2iZWQCLDheyBk1+SjJsmH8ovjrWpfZuABIHYaH2gc3hy0igXiaYeYAF8jH8G+cmDcjd2+lQDwi7PhyOxM5Ai4u+kw16su1HFXBNkDZ0e7+YtPVElDC4TCBmt0O98gPVjcIsD1pDgSbdsTZe6zqLBgujrPQhC72eADtoi3WCMiyo+GPEPeYRrZo4H9vSt2pdIg9E73wJPgCu/LcAql2FJh/glsIqpIhw== ahelsing@hotcocoa2"]}]

Or in prettier layout: 

$ ./geni-get geni_user | python -mjson.tool | sed -e's/  / /g'
[
  {
    "keys": [
      "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAwhxWkZuS20ow0MnVeSiiRar55Qgy1GA74HIxgiMSPiqQEL3fjufyO/g6FK7R659oNQRbvLlrN5zpaDQ4MBk/JLTt6NO+9IUsB6HlI2P5q8bVyRpUf6E3SJh2iZWQCLDheyBk1+SjJsmH8ovjrWpfZuABIHYaH2gc3hy0igXiaYeYAF8jH8G+cmDcjd2+lQDwi7PhyOxM5Ai4u+kw16su1HFXBNkDZ0e7+YtPVElDC4TCBmt0O98gPVjcIsD1pDgSbdsTZe6zqLBgujrPQhC72eADtoi3WCMiyo+GPEPeYRrZo4H9vSt2pdIg9E73wJPgCu/LcAql2FJh/glsIqpIhw== ahelsing@hotcocoa2"
    ], 
    "urn": "urn:publicid:IDN+ch.geni.net+user+ahelsing"
  }, 
  {
    "keys": [
      "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAwhxWkZuS20ow0MnVeSiiRar55Qgy1GA74HIxgiMSPiqQEL3fjufyO/g6FK7R659oNQRbvLlrN5zpaDQ4MBk/JLTt6NO+9IUsB6HlI2P5q8bVyRpUf6E3SJh2iZWQCLDheyBk1+SjJsmH8ovjrWpfZuABIHYaH2gc3hy0igXiaYeYAF8jH8G+cmDcjd2+lQDwi7PhyOxM5Ai4u+kw16su1HFXBNkDZ0e7+YtPVElDC4TCBmt0O98gPVjcIsD1pDgSbdsTZe6zqLBgujrPQhC72eADtoi3WCMiyo+GPEPeYRrZo4H9vSt2pdIg9E73wJPgCu/LcAql2FJh/glsIqpIhw== ahelsing@hotcocoa2"
    ], 
    "urn": "urn:publicid:IDN+ch.geni.net+user+sedwards"
  }, 
  {
    "keys": [
      "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAwhxWkZuS20ow0MnVeSiiRar55Qgy1GA74HIxgiMSPiqQEL3fjufyO/g6FK7R659oNQRbvLlrN5zpaDQ4MBk/JLTt6NO+9IUsB6HlI2P5q8bVyRpUf6E3SJh2iZWQCLDheyBk1+SjJsmH8ovjrWpfZuABIHYaH2gc3hy0igXiaYeYAF8jH8G+cmDcjd2+lQDwi7PhyOxM5Ai4u+kw16su1HFXBNkDZ0e7+YtPVElDC4TCBmt0O98gPVjcIsD1pDgSbdsTZe6zqLBgujrPQhC72eADtoi3WCMiyo+GPEPeYRrZo4H9vSt2pdIg9E73wJPgCu/LcAql2FJh/glsIqpIhw== ahelsing@hotcocoa2", 
      "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAwhxWkZuS20ow0MnVeSiiRar55Qgy1GA74HIxgiMSPiqQEL3fjufyO/g6FK7R659oNQRbvLlrN5zpaDQ4MBk/JLTt6NO+9IUsB6HlI2P5q8bVyRpUf6E3SJh2iZWQCLDheyBk1+SjJsmH8ovjrWpfZuABIHYaH2gc3hy0igXiaYeYAF8jH8G+cmDcjd2+lQDwi7PhyOxM5Ai4u+kw16su1HFXBNkDZ0e7+YtPVElDC4TCBmt0O98gPVjcIsD1pDgSbdsTZe6zqLBgujrPQhC72eADtoi3WCMiyo+GPEPeYRrZo4H9vSt2pdIg9E73wJPgCu/LcAql2FJh/glsIqpIhw== ahelsing@hotcocoa2"
    ], 
    "urn": "urn:publicid:IDN+ch.geni.net+user+tmitchel"
  }
]

getversion

Return the return from the GENI AM API getversion command for the latest AM API revision supported, in JSON format. Note that not every element from the AM API getversion call is required to be returned here, but all are allowed and more are encouraged.

Returned fields shall include all of the fields that this aggregate supports from this list: geni_am_type, geni_single_allocation, geni_allocate, geni_credential_types, geni_am_code_version, geni_urn, geni_api_versions, plus any others specific to this aggregate or defined by later versions of the AM API.

Example: 

$ ./geni-get getversion
{"code_tag":"7cb7effce5627a210abf6f01acf7b61ecc2bac39","urn":"urn:publicid:IDN+emulab.net+authority+cm","url":"https://www.emulab.net:12369/protogeni/xmlrpc/am","geni_am_type":"protogeni","geni_single_allocation":true,"geni_allocate":"geni_disjoint","geni_credential_types":{"geni_type":"geni_sfa","geni_version":"2","geni_type":"geni_sfa","geni_version":"3"}}

manifest

Return the manifest RSpec for the slice, in standard GENI RSpec XML format. This manifest shall describe all resources reserved in this slice at this aggregate, not just the current compute resource.

Example: 

$ ./geni-get manifest
<rspec xmlns="http://www.geni.net/resources/rspec/3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.geni.net/resources/rspec/3 http://www.geni.net/resources/rspec/3/manifest.xsd" type="manifest">
  <node client_id="request1" exclusive="false" component_id="urn:publicid:IDN+emulab.net+node+pc480" component_manager_id="urn:publicid:IDN+emulab.net+authority+cm" sliver_id="urn:publicid:IDN+emulab.net+sliver+158594">
    <sliver_type name="emulab-openvz"/>
  <rs:vnode xmlns:rs="http://www.protogeni.net/resources/rspec/ext/emulab/1" name="pcvm480-3"/><host name="request1.ahtest.ch-geni-net.emulab.net"/><services><login authentication="ssh-keys" hostname="pc480.emulab.net" port="36410" username="ahelsing"/><login authentication="ssh-keys" hostname="pc480.emulab.net" port="36410" username="tmitchel"/><login authentication="ssh-keys" hostname="pc480.emulab.net" port="36410" username="sedwards"/></services></node>
</rspec>

slice_email

Return the email address of the slice (from the slice certificate) as a string.

NB: Does not work for slices from the GENI GPO Clearinghouse / Portal

Example: 

$ geni-get slice_email
slice-jbs15@example.com

slice_urn

Return the URN of the slice that owns the current compute resource as a string.

Example: 

$ geni-get slice_urn
urn:publicid:IDN+ch.geni.net:JBS+slice+jbs15

sliverstatus

Return the AM API v2 return from sliverstatus for this slice (see ​http://groups.geni.net/geni/wiki/GAPI_AM_API_V2#SliverStatus), a JSON array. This status shall be for all slivers in this slice at this aggregate.

Example: 

$ geni-get sliverstatus
{"geni_urn":"urn:publicid:IDN+emulab.net+sliver+158595","geni_status":"unknown","geni_resources":[{"geni_urn":"urn:publicid:IDN+emulab.net+sliver+158594","geni_status":"ready","geni_error":""}]}

status

Return the AM API v3 status return. Only supported if the AM supports AM API v3. See ​http://groups.geni.net/geni/wiki/GAPI_AM_API_V3#Status. This status shall be for all slivers in this slice at this aggregate.

Example: 

$ ./geni-get status
{"geni_urn":"urn:publicid:IDN+ch.geni.net:ahscaletest+slice+ahtest",geni_slivers":[{"geni_urn":"urn:publicid:IDN+emulab.net+sliver+158594","geni_expires":"2013-11-08 13:34:26","geni_allocation_status":"geni_provisioned","geni_operational_status":"geni_ready","geni_error":""}]}

user_email

Return the email address of the user who reserved the node (from the user certificate) as a string.

Example: 

+$ geni-get user_email
jbs@bbn.com

user_urn

Return the URN of the user who reserved the node, from the user certificate as a string.

Example: 

+$ geni-get user_urn
urn:publicid:IDN+ch.geni.net+user+jbs

--version

Return the version of this specification being implemented as an int.

This document description version 1.

Example: 

+$ geni-get version
1

--client-version

Return the version of this script (geni-get) as a string.

Example: 

$ ./geni-get --client-version
1.1

--all

Return all available information, in JSON format. 

$ ./geni-get --all
{"client_id":"request1","control_mac":"02670abd86aa","geni_user":[{"urn":"urn:publicid:IDN+ch.geni.net+user+ahelsing","keys":["ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAwhxWkZuS20ow0MnVeSiiRar55Qgy1GA74HIxgiMSPiqQEL3fjufyO/g6FK7R659oNQRbvLlrN5zpaDQ4MBk/JLTt6NO+9IUsB6HlI2P5q8bVyRpUf6E3SJh2iZWQCLDheyBk1+SjJsmH8ovjrWpfZuABIHYaH2gc3hy0igXiaYeYAF8jH8G+cmDcjd2+lQDwi7PhyOxM5Ai4u+kw16su1HFXBNkDZ0e7+YtPVElDC4TCBmt0O98gPVjcIsD1pDgSbdsTZe6zqLBgujrPQhC72eADtoi3WCMiyo+GPEPeYRrZo4H9vSt2pdIg9E73wJPgCu/LcAql2FJh/glsIqpIhw== ahelsing@hotcocoa2"]},{"urn":"urn:publicid:IDN+ch.geni.net+user+sedwards","keys":["ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAwhxWkZuS20ow0MnVeSiiRar55Qgy1GA74HIxgiMSPiqQEL3fjufyO/g6FK7R659oNQRbvLlrN5zpaDQ4MBk/JLTt6NO+9IUsB6HlI2P5q8bVyRpUf6E3SJh2iZWQCLDheyBk1+SjJsmH8ovjrWpfZuABIHYaH2gc3hy0igXiaYeYAF8jH8G+cmDcjd2+lQDwi7PhyOxM5Ai4u+kw16su1HFXBNkDZ0e7+YtPVElDC4TCBmt0O98gPVjcIsD1pDgSbdsTZe6zqLBgujrPQhC72eADtoi3WCMiyo+GPEPeYRrZo4H9vSt2pdIg9E73wJPgCu/LcAql2FJh/glsIqpIhw== ahelsing@hotcocoa2"]},{"urn":"urn:publicid:IDN+ch.geni.net+user+tmitchel","keys":["ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAwhxWkZuS20ow0MnVeSiiRar55Qgy1GA74HIxgiMSPiqQEL3fjufyO/g6FK7R659oNQRbvLlrN5zpaDQ4MBk/JLTt6NO+9IUsB6HlI2P5q8bVyRpUf6E3SJh2iZWQCLDheyBk1+SjJsmH8ovjrWpfZuABIHYaH2gc3hy0igXiaYeYAF8jH8G+cmDcjd2+lQDwi7PhyOxM5Ai4u+kw16su1HFXBNkDZ0e7+YtPVElDC4TCBmt0O98gPVjcIsD1pDgSbdsTZe6zqLBgujrPQhC72eADtoi3WCMiyo+GPEPeYRrZo4H9vSt2pdIg9E73wJPgCu/LcAql2FJh/glsIqpIhw== ahelsing@hotcocoa2","ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAwhxWkZuS20ow0MnVeSiiRar55Qgy1GA74HIxgiMSPiqQEL3fjufyO/g6FK7R659oNQRbvLlrN5zpaDQ4MBk/JLTt6NO+9IUsB6HlI2P5q8bVyRpUf6E3SJh2iZWQCLDheyBk1+SjJsmH8ovjrWpfZuABIHYaH2gc3hy0igXiaYeYAF8jH8G+cmDcjd2+lQDwi7PhyOxM5Ai4u+kw16su1HFXBNkDZ0e7+YtPVElDC4TCBmt0O98gPVjcIsD1pDgSbdsTZe6zqLBgujrPQhC72eADtoi3WCMiyo+GPEPeYRrZo4H9vSt2pdIg9E73wJPgCu/LcAql2FJh/glsIqpIhw== ahelsing@hotcocoa2"]}],"getversion":{"code_tag":"7cb7effce5627a210abf6f01acf7b61ecc2bac39","urn":"urn:publicid:IDN+emulab.net+authority+cm","url":"https://www.emulab.net:12369/protogeni/xmlrpc/am","geni_am_type":"protogeni","geni_single_allocation":true,"geni_allocate":"geni_disjoint","geni_credential_types":{"geni_type":"geni_sfa","geni_version":"2","geni_type":"geni_sfa","geni_version":"3"}},"manifest":"<rspec xmlns=\"http://www.geni.net/resources/rspec/3\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:schemaLocation=\"http://www.geni.net/resources/rspec/3 http://www.geni.net/resources/rspec/3/manifest.xsd\" type=\"manifest\">
  <node client_id=\"request1\" exclusive=\"false\" component_id=\"urn:publicid:IDN+emulab.net+node+pc480\" component_manager_id=\"urn:publicid:IDN+emulab.net+authority+cm\" sliver_id=\"urn:publicid:IDN+emulab.net+sliver+158594\">
    <sliver_type name=\"emulab-openvz\"/>
  <rs:vnode xmlns:rs=\"http://www.protogeni.net/resources/rspec/ext/emulab/1\" name=\"pcvm480-3\"/><host name=\"request1.ahtest.ch-geni-net.emulab.net\"/><services><login authentication=\"ssh-keys\" hostname=\"pc480.emulab.net\" port=\"36410\" username=\"ahelsing\"/><login authentication=\"ssh-keys\" hostname=\"pc480.emulab.net\" port=\"36410\" username=\"tmitchel\"/><login authentication=\"ssh-keys\" hostname=\"pc480.emulab.net\" port=\"36410\" username=\"sedwards\"/></services></node>
</rspec>","slice_urn":"urn:publicid:IDN+ch.geni.net:ahscaletest+slice+ahtest","sliverstatus":{"geni_urn":"urn:publicid:IDN+emulab.net+sliver+158595","geni_status":"unknown","geni_resources":[{"geni_urn":"urn:publicid:IDN+emulab.net+sliver+158594","geni_status":"ready","geni_error":""}]},"status":{"geni_urn":"urn:publicid:IDN+ch.geni.net:ahscaletest+slice+ahtest",geni_slivers":[{"geni_urn":"urn:publicid:IDN+emulab.net+sliver+158594","geni_expires":"2013-11-08 13:34:26","geni_allocation_status":"geni_provisioned","geni_operational_status":"geni_ready","geni_error":""}]},"user_email":"ahelsing@geni.net","user_urn":"urn:publicid:IDN+ch.geni.net+user+ahelsing","version":"1"}
Last modified 11 years ago Last modified on 03/16/14 15:03:35