wiki:GeniGet

Version 12 (modified by Aaron Helsinger, 10 years ago) (diff)

--

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 must be installed in your disk image. All GENI compute resource providers should 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.

FIXME: Return error code for the script?

PG implementation

Known Issues

  • Slice email for GPO SA slices is incorrect
  • Description of client-id command is wrong: It is not a client specified sliver ID
  • Descriptions of commands is a little unclear: which AM? Specify that commands show output relative to current node. Etc.

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 be no-ops 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 the server side of this geni-get implementation (if any)
  • 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 server 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 list. 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

FIXME: Includes updates from later poa actions?

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.

FIXME: Which selected fields are returned here? If this is a full getversion return, then which AM API version# is used? The one you used to make the reservation?

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.

FIXME: For only this node? For only this AM?

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 struct.

FIXME: For just the current resource (plus an overall status)? Or for all resources at this AM?

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

FIXME: For only the current sliver? Or for all resources at this AM? If only for this sliver, then the status should also include a slice-overall status.

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 the server side of this implementation. If there is no server side, return an empty string.

FIXME: A string? An int? Float?

Example:

+$ geni-get version
1 

--client-version

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

FIXME: A string? A float?

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"}