Upgrading the Guest Shell Rootfs and Querying the Result
This section contains payload examples to demonstrate how to use the NX-API REST API to control the state of the Guest Shell on the Cisco Nexus 3000 and 9000 Series switches.
For more information about the Guest Shell, see the Cisco Nexus 9000 Series NX-OS Programmability Guide:
Upgrading the Guest Shell Rootfs
Upgrading the Guest Shell Rootfs
POST http://<IP_address>/api/mo/sys/action.json
{
"actionLSubj": {
"attributes": {
"dn": "sys/action/lsubj-[sys]"
}
"children" : [{
"guestshellGuestShellUpgradeLTask": {
"attributes": {
"adminSt": "start",
"dn": "sys/action/lsubj-[sys]/guestshellGuestShellUpgradeLTask",
"freq": "one-shot",
"package" : "",
"descr": ""
}}]}}
Note: This example was added in Release 9.3(3).
To replace the rootfs of an existing instance of the Guest Shell, you can either destroy the Guest Shell and use the enable action, or perform a single step by posting a guestshellGuestShellUpgradeLTask action action. In this example, the Guest Shell is upgraded to use the default rootfs that is embedded in the system image.
CLI Commands
The CLI command is equivalent to the payload example displayed in the pane on the right.
guestshell upgrade package <upgrade_uri>
Verifying a DME Configuration
The following table contains the distinguished name (DN) for each managed object (MO) in the DME payload. Issue a GET request using the DN to verify the configuration was posted or to get information about the configured properties of a particular object.
MO | DN |
---|---|
actionLSubj | sys/action/lsubj-{[oDn]} |
guestshellGuestShellUpgradeLTask | sys/action/lsubj-{[oDn]}/guestshellGuestShellUpgradeLTask |
actionLSubj Properties
The following table contains information about the actionLSubj properties in the DME payload. For more information about the properties and MOs, see the NX-API DME Model Reference linked in the Related Documentation section below.
Property Name | Data Type | Description | Values |
---|---|---|---|
dn | reference:BinRef | A tag or metadata is a non-hierarchical keyword or term assigned to the fabric module. |
guestshellGuestShellUpgradeLTask Properties
The following table contains information about the guestshellGuestShellUpgradeLTask properties in the DME payload. For more information about the properties and MOs, see the NX-API DME Model Reference linked in the Related Documentation section below.
Property Name | Data Type | Description | Values |
---|---|---|---|
adminSt | action:AdminSt scalar:Enum8 | The administrative state of the object or policy. | SELECTION:
|
dn | reference:BinRef | A tag or metadata is a non-hierarchical keyword or term assigned to the fabric module. | |
freq | action:Freq scalar:Time | Frequency at which tasks are executed | SELECTION:
|
package | infra:GuestshellPackageURI string:Basic | NO COMMENTS | RANGE:
Min: "256"
Max: "4096" (EXCLUDE) |
descr | action:Descr string:Basic | RANGE: Min: "0" Max: "128" | |
descr | action:Descr string:Basic | RANGE: Min: "0" Max: "128" |
Related Documentation
For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference:
See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload:
https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/
For information about using the payloads, see the Cisco Nexus 9000 Series NX-OS Programmability Guide:
Querying the Result of Upgrading the Guest Shell Rootfs (Example 1)
Querying the Result of Upgrading the Guest Shell Rootfs (Example 1)
GET http://<IP_Address>/api/mo/sys/action/lsubj-[sys]/guestshellGuestShellUpgradeRslt.json
{
"totalCount": "1",
"imdata": [
{
"guestshellGuestShellUpgradeRslt": {
"attributes": {
"ack": "no",
"childAction": "",
"descr": "",
"dn": "sys/action/lsubj-[sys]/guestshellGuestShellUpgradeRslt",
"endTs": "never",
"modTs": "never",
"operSt": "processing",
"peerClassId": "guestshellGuestShellUpgradeLTask",
"qual": "",
"rSz": "100",
"rTm": "00:00:00:00.000",
"startTs": "2019-10-19T18:06:01.364+00:00",
"status": "",
"type": "clear"
}
}
}
]
}
Note: This example was added in Release 9.3(3).
The endTs
of “never”
and operSt
of “processing”
indicates that the upgrade request is being processed, but it has yet to finish.
Repeating the request for the upgrade result after some time shows an operSt
attribute of “completed”
and the time in which the request finished in the endTs
attribute as shown in example 2.
Verifying a DME Configuration
The following table contains the distinguished name (DN) for each managed object (MO) in the DME payload. Issue a GET request using the DN to verify the configuration was posted or to get information about the configured properties of a particular object.
MO | DN |
---|---|
guestshellGuestShellUpgradeRslt | sys/action/lsubj-{[oDn]}/guestshellGuestShellUpgradeRslt |
guestshellGuestShellUpgradeRslt Properties
The following table contains information about the guestshellGuestShellUpgradeRslt properties in the DME payload. For more information about the properties and MOs, see the NX-API DME Model Reference linked in the Related Documentation section below.
Property Name | Data Type | Description | Values |
---|---|---|---|
ack | scalar:Bool | The acknowledgement status of the fault. If a fault is acknowledged and cleared, it is immediately deleted. If a fault is not acknowledged and cleared, it is deleted after the retention interval. | SELECTION:
|
childAction | mo:ModificationChildAction scalar:Bitmask32 | Delete or ignore. For internal use only. | SELECTION:
|
descr | action:Descr string:Basic | RANGE: Min: "0" Max: "128" | |
dn | reference:BinRef | A tag or metadata is a non-hierarchical keyword or term assigned to the fabric module. | |
endTs | mo:TStamp scalar:Date | The date and time when the task ended. | SELECTION:
|
modTs | mo:TStamp scalar:Date | The time when this object was last modified. | SELECTION:
|
operSt | action:OperSt scalar:Enum8 | The runtime state of the object or policy. | SELECTION:
|
peerClassId | mo:MoClassId | The BGP neighbor. | DEFAULT: guestshellGuestShellSyncLTask |
qual | action:Qual string:Basic | The qualifier for the component status. | RANGE: Min: "0" Max: "512" |
rSz | action:RetentionSize scalar:Uint16 | The retention size of the task results. | RANGE:
Min: 1
Max: 1024 |
rTm | action:RetentionTime scalar:Time | The retention time of the task results. | |
startTs | mo:TStamp scalar:Date | The date and time when the task began. | SELECTION:
|
status | mo:ModificationStatus scalar:Bitmask32 | The upgrade status. This property is for internal use only. | SELECTION:
|
type | action:Type scalar:Enum8 | The specific type of the object or component. | SELECTION:
|
Related Documentation
For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference:
See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload:
https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/
For information about using the payloads, see the Cisco Nexus 9000 Series NX-OS Programmability Guide:
Querying the Result of Upgrading the Guest Shell Rootfs (Example 2)
Querying the Result of Upgrading the Guest Shell Rootfs (Example 2)
GET http://<IP_Address>/api/mo/sys/action/lsubj-[sys]/guestshellGuestShellUpgradeRslt.json
{
"totalCount": "1",
"imdata": [
{
"guestshellGuestShellUpgradeRslt": {
"attributes": {
"ack": "no",
"childAction": "",
"descr": "Guestshell activated successfully",
"dn": "sys/action/lsubj-[sys]/guestshellGuestShellUpgradeRslt",
"endTs": "2019-10-19T18:07:09.458+00:00",
"modTs": "never",
"operSt": "completed",
"peerClassId": "guestshellGuestShellUpgradeLTask",
"qual": "",
"rSz": "100",
"rTm": "00:00:00:00.000",
"startTs": "2019-10-19T18:06:01.364+00:00",
"status": "",
"type": "clear"
}
}
}
]
}
Note: This example was added in Release 9.3(3).
In this example, the Guest Shell was in the activated state when the upgrade request was posted and it returned to the activated state as indicated in the descr
attribute.
Verifying a DME Configuration
The following table contains the distinguished name (DN) for each managed object (MO) in the DME payload. Issue a GET request using the DN to verify the configuration was posted or to get information about the configured properties of a particular object.
MO | DN |
---|---|
guestshellGuestShellUpgradeRslt | sys/action/lsubj-{[oDn]}/guestshellGuestShellUpgradeRslt |
guestshellGuestShellUpgradeRslt Properties
The following table contains information about the guestshellGuestShellUpgradeRslt properties in the DME payload. For more information about the properties and MOs, see the NX-API DME Model Reference linked in the Related Documentation section below.
Property Name | Data Type | Description | Values |
---|---|---|---|
ack | scalar:Bool | The acknowledgement status of the fault. If a fault is acknowledged and cleared, it is immediately deleted. If a fault is not acknowledged and cleared, it is deleted after the retention interval. | SELECTION:
|
childAction | mo:ModificationChildAction scalar:Bitmask32 | Delete or ignore. For internal use only. | SELECTION:
|
descr | action:Descr string:Basic | RANGE: Min: "0" Max: "128" | |
dn | reference:BinRef | A tag or metadata is a non-hierarchical keyword or term assigned to the fabric module. | |
endTs | mo:TStamp scalar:Date | The date and time when the task ended. | SELECTION:
|
modTs | mo:TStamp scalar:Date | The time when this object was last modified. | SELECTION:
|
operSt | action:OperSt scalar:Enum8 | The runtime state of the object or policy. | SELECTION:
|
peerClassId | mo:MoClassId | The BGP neighbor. | DEFAULT: guestshellGuestShellSyncLTask |
qual | action:Qual string:Basic | The qualifier for the component status. | RANGE: Min: "0" Max: "512" |
rSz | action:RetentionSize scalar:Uint16 | The retention size of the task results. | RANGE:
Min: 1
Max: 1024 |
rTm | action:RetentionTime scalar:Time | The retention time of the task results. | |
startTs | mo:TStamp scalar:Date | The date and time when the task began. | SELECTION:
|
status | mo:ModificationStatus scalar:Bitmask32 | The upgrade status. This property is for internal use only. | SELECTION:
|
type | action:Type scalar:Enum8 | The specific type of the object or component. | SELECTION:
|
Related Documentation
For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference:
See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload:
https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/
For information about using the payloads, see the Cisco Nexus 9000 Series NX-OS Programmability Guide: