Enabling the Guest Shell 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:

https://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-installation-and-configuration-guides-list.html/

Enabling the Guest Shell Using the Default Package

Enabling the Guest Shell Using the Default Package

POST http://<IP_Address>/api/mo/sys/action.json

{
"actionLSubj": {
  "attributes": {
    "dn": "sys/action/lsubj-[sys]"
  }
  "children" : [{
    "guestshellGuestShellEnableLTask": {
      "attributes": {
        "adminSt": "start",
        "dn": "sys/action/lsubj-[sys]/guestshellGuestShellEnableLTask",
        "freq": "one-shot",
        "package": "DME_UNSET_PROPERTY_MARKER",
        "descr": ""
}}}]}}

Note: This example was added in Release 9.3(3).

If the Guest Shell is present but disabled on the system, enable the Guest Shell by posting a guestshellGuestShellEnableLTask action without specifying the “package” attribute. Use this same format for the guestshellGuestShellEnableLTask when the Guest Shell is not present and you are creating the Guest Shell using the default Guest Shell rootfs package 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 enable

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]}
guestshellGuestShellEnableLTask	sys/action/lsubj-{[oDn]}/guestshellGuestShellEnableLTask

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.

guestshellGuestShellEnableLTask Properties

The following table contains information about the guestshellGuestShellEnableLTask 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: 0 - unknown 1 - start 2 - stop 3 - suspend DEFAULT: unknown(0)
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: 0ull - one-shot DEFAULT: 0
package	infra:GuestshellPackageURI string:Basic	NO COMMENTS	RANGE: Min: "256" Max: "4096" (EXCLUDE) DEFAULT: ""--Empty string as default URI
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:

http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

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:

https://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-programming-reference-guides-list.html

Querying the Result of the Guest Shell Enable Result (Example 1)

Querying the Result of the Guest Shell Enable Result (Example 1)

GET http://<IP_Address>/api/mo/sys/action/lsubj-[sys]/guestshellGuestShellEnableRslt.json

{
    "totalCount": "1",
    "imdata": [
        {
            "guestshellGuestShellEnableRslt": {
                "attributes": {
                    "ack": "no",
                    "childAction": "",
                    "descr": "",
                    "dn": "sys/action/lsubj-[sys]/guestshellGuestShellEnableRslt",
                    "endTs": "never",
                    "modTs": "never",
                    "operSt": "processing",
                    "peerClassId": "guestshellGuestShellEnableLTask",
                   "qual": "",
                    "rSz": "100",
                    "rTm": "00:00:00:00.000",
                    "startTs": "2019-10-19T10:14:15.238+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 enable request is being processed, but it has yet to finish.

Repeating the request for the enable result after some time shows an operSt attribute of “completed” and the time in which the enable request finished in the endTs attribute as shown in example 2.

MO	DN
guestshellGuestShellEnableRslt	sys/action/lsubj-{[oDn]}/guestshellGuestShellEnableRslt

guestshellGuestShellEnableRslt Properties

The following table contains information about the guestshellGuestShellEnableRslt 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: false - no true - yes DEFAULT: no(false)
childAction	mo:ModificationChildAction scalar:Bitmask32	Delete or ignore. For internal use only.	SELECTION: 16384u - deleteAll 4096u - ignore 8192u - deleteNonPresent DEFAULT: 0
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: 0ull - never DEFAULT: never(0ull)
modTs	mo:TStamp scalar:Date	The time when this object was last modified.	SELECTION: 0ull - never DEFAULT: never(0ull)
operSt	action:OperSt scalar:Enum8	The runtime state of the object or policy.	SELECTION: 0 - scheduled 1 - processing 2 - completed 3 - cancelled 4 - failed 5 - indeterminate 6 - suspended 7 - crashsuspect DEFAULT: scheduled(0)
peerClassId	mo:MoClassId	The BGP neighbor.	DEFAULT: guestshellGuestShellEnableLTask
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 DEFAULT: 100
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: 0ull - never DEFAULT: never(0ull)
status	mo:ModificationStatus scalar:Bitmask32	The upgrade status. This property is for internal use only.	SELECTION: 16u - replaced 2u - created 4u - modified 8u - deleted DEFAULT: 0
type	action:Type scalar:Enum8	The specific type of the object or component.	SELECTION: 1 - clear 2 - reset 3 - reload 4 - locate 5 - install 6 - test 7 - collect 8 - interface-in-service DEFAULT: clear(1)

Related Documentation

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference:

http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

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:

https://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-programming-reference-guides-list.html

Querying the Result of the Guest Shell Enable Result (Example 2)

Querying the Result of the Guest Shell Enable Result (Example 2)

GET http://<IP_Address>/api/mo/sys/action/lsubj-[sys]/guestshellGuestShellEnableRslt.json

{
    "totalCount": "1",
    "imdata": [
        {
            "guestshellGuestShellEnableRslt": {
                "attributes": {
                    "ack": "no",
                    "childAction": "",
                    "descr": "Guestshell activated successfully",
                    "dn": "sys/action/lsubj-[sys]/guestshellGuestShellEnableRslt",
                    "endTs": "2019-10-19T10:15:08.467+00:00",
                    "modTs": "never",
                    "operSt": "completed",
                    "peerClassId": "guestshellGuestShellEnableLTask",
                    "qual": "",
                    "rSz": "100",
                    "rTm": "00:00:00:00.000",
                    "startTs": "2019-10-19T10:14:15.238+00:00",
                    "status": "",
                    "type": "clear"
                }
            }
        }
    ]
}

Note: This example was added in Release 9.3(3).

When the operSt contains an attribute of “completed”, performing a GET request on the status will indicate that the Guest Shell is "activated" (see Querying the Guest Shell Status).

MO	DN
guestshellGuestShellEnableRslt	sys/action/lsubj-{[oDn]}/guestshellGuestShellEnableRslt

guestshellGuestShellEnableRslt Properties

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: false - no true - yes DEFAULT: no(false)
childAction	mo:ModificationChildAction scalar:Bitmask32	Delete or ignore. For internal use only.	SELECTION: 16384u - deleteAll 4096u - ignore 8192u - deleteNonPresent DEFAULT: 0
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: 0ull - never DEFAULT: never(0ull)
modTs	mo:TStamp scalar:Date	The time when this object was last modified.	SELECTION: 0ull - never DEFAULT: never(0ull)
operSt	action:OperSt scalar:Enum8	The runtime state of the object or policy.	SELECTION: 0 - scheduled 1 - processing 2 - completed 3 - cancelled 4 - failed 5 - indeterminate 6 - suspended 7 - crashsuspect DEFAULT: scheduled(0)
peerClassId	mo:MoClassId	The BGP neighbor.	DEFAULT: guestshellGuestShellEnableLTask
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 DEFAULT: 100
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: 0ull - never DEFAULT: never(0ull)
status	mo:ModificationStatus scalar:Bitmask32	The upgrade status. This property is for internal use only.	SELECTION: 16u - replaced 2u - created 4u - modified 8u - deleted DEFAULT: 0
type	action:Type scalar:Enum8	The specific type of the object or component.	SELECTION: 1 - clear 2 - reset 3 - reload 4 - locate 5 - install 6 - test 7 - collect 8 - interface-in-service DEFAULT: clear(1)

Related Documentation

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference:

http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

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:

https://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-programming-reference-guides-list.html

Querying the Guest Shell Status

Querying the Guest Shell Status

GET http://<IP_Address>/api/mo/sys/guestshell/status.json

{
    "totalCount": "1",
    "imdata": [
        {
            "guestshellStatus": {
                "attributes": {
                    "dn": "sys/guestshell/status",
                    "lastActionStatus": "Successfully activated virtual service",
                    "operState": "activated"
                }
            }
        }
    ]
}

Note: This example was added in Release 9.3(3).

MO	DN
guestshellStatus	sys/guestshell/status

guestshellStatus Properties

The following table contains information about the guestshellStatus 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.
lastActionStatus	string:Basic	Status/result of last action performed on the Guest Shell	A sequence of characters
operState	guestshell:GuestShellOperState (scalar:Enum8)	Operational state of the Guest Shell	SELECTION: 0 - unknown 1 - initializing 2 - provisioned 3 - configured 4 - installing 5 - installed 6 - install-failed 7 - install-verify-failed 8 - activating 9 - activated 10 - activate-failed 11 - deactivated 12 - deactivating 13 - restarting 14 - not-installed 15 - error DEFAULT: unknown

Related Documentation

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference:

http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

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:

https://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-programming-reference-guides-list.html

Enabling the Guest Shell Using a Specified Package

Enabling the Guest Shell Using a Specified Package

POST http://<IP_Address>/api/mo/sys/action.json

{
"actionLSubj": {
  "attributes": {
    "dn": "sys/action/lsubj-[sys]"
  }
  "children" : [{
    "guestshellGuestShellEnableLTask": {
      "attributes": {
        "adminSt": "start",
        "dn": "sys/action/lsubj-[sys]/guestshellGuestShellEnableLTask",
        "freq": "one-shot",
        "package" : "usb1:gs2_3_0.ext4",
        "descr": ""
      }
    }
}]
}

Note: This example was added in Release 9.3(3).

Use the package attribute with guestshellGuestShellEnableLTask when the Guest Shell is not present on the system and you are creating the Guest Shell using a rootfs other than the one embedded in the system image. In this example, a previously exported Guest Shell rootfs package that is on the USB1: media of the system is specified. To enable with an exported rootfs, the virtual-service signing level must first be configured to allow unsigned packages (For more information, see Configuring the Virtual Service Signing Policy to Allow Unsigned Packages).

CLI Commands

The CLI command is equivalent to the payload example displayed in the pane on the right.

guestshell enable [{package <enable_uri>}]

MO	DN
actionLSubj	sys/action/lsubj-{[oDn]}
guestshellGuestShellEnableLTask	sys/action/lsubj-{[oDn]}/guestshellGuestShellEnableLTask

actionLSubj Properties

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.

guestshellGuestShellEnableLTask Properties

Property Name	Data Type	Description	Values
adminSt	action:AdminSt scalar:Enum8	The administrative state of the object or policy.	SELECTION: 0 - unknown 1 - start 2 - stop 3 - suspend DEFAULT: unknown(0)
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: 0ull - one-shot DEFAULT: 0
package	infra:GuestshellPackageURI string:Basic	NO COMMENTS	RANGE: Min: "256" Max: "4096" (EXCLUDE) DEFAULT: ""--Empty string as default URI
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:

http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

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:

https://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-programming-reference-guides-list.html