= 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 =
* https://www.emulab.net/downloads/geni-get.tar.gz
* https://www.emulab.net/downloads/geni-get_1.0_all.deb
* https://www.emulab.net/downloads/geni-get-1.0-1.fc15.noarch.rpm
== 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
}}}
== 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":"
","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"}
}}}
{{{
#!comment
To do:
- write up in spec format with examples
- no methods return nothing by spec
- non zero exit code on unknown command
- document --status command for APIv3 status (similar to but not identical to sliverstatus)
- document --commands for JSON list of commands this implementation understands
- update example of sliverstatus output
- note known issue that slice email for GPO SA slices is incorrect at PG
}}}