Configuring Checkpoints and Rollback

The rollback feature allows you to take a snapshot, or user checkpoint, of the Cisco NX-OS configuration and then reapply that configuration to your device at any point without having to reload the device. A rollback allows any authorized administrator to apply this checkpoint configuration without requiring expert knowledge of the features configured in the checkpoint.

You can create a checkpoint copy of the current running configuration at any time. Cisco NX-OS saves this checkpoint as an ASCII file which you can use to roll back the running configuration to the checkpoint configuration at a future time. You can create multiple checkpoints to save different versions of your running configuration.

This section contains payload examples to demonstrate how to use the NX-API REST API to configure checkpoints and rollback on the Cisco Nexus 3000 and 9000 Series switches.

Triggering a checkpoint

Triggering a checkpoint

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

{
  "actionLSubj": {
    "attributes": {
      "dn": "sys/action/lsubj-[sys]"
    },
    "children": [
      {
        "topSystemCreateCheckpointLTask": {
          "attributes": {
            "adminSt": "start",
            "name": "checkpt-20160930",
            "description": "End of quarter before upgrade",
            "filename": "",
            "delete": "no",
            "dn": "sys/action/lsubj-[sys]/topSystemCreateCheckpointLTask",
            "freq": "one-shot"
          }
        }
      }
    ]
  }
}

This example creates a checkpoint with a name and description.

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.

topSystemCreateCheckpointLTask Properties

The following table contains information about the topSystemCreateCheckpointLTask 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.

Related Documentation

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

Triggering a checkpoint (with file name)

Triggering a checkpoint (with file name)

{
  "actionLSubj": {
    "attributes": {
      "dn": "sys/action/lsubj-[sys]"
    },
    "children": [
      {
        "topSystemCreateCheckpointLTask": {
          "attributes": {
            "adminSt": "start",
            "name": "",
            "description": "",
            "filename": "bootflash:ckp2",
            "delete": "no",
            "dn": "sys/action/lsubj-[sys]/topSystemCreateCheckpointLTask",
            "freq": "one-shot"
          }
        }
      }
    ]
  }
}

{     
  "imdata": [] 
}

This example creates a checkpoint with a file name.

No information is present in the immediate JSON response. To verify success or failure and to view reasons for a failure, query the response object described below.

CLI Command

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

checkpoint {[<name>] [description <descr>] | file <file_uri>}

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.

topSystemCreateCheckpointLTask Properties

The following table contains information about the topSystemCreateCheckpointLTask 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.

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

Deleting a checkpoint

Deleting a checkpoint

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

{
  "actionLSubj": {
    "attributes": {
      "dn": "sys/action/lsubj-[sys]"
    },
    "children": [
      {
        "topSystemCreateCheckpointLTask": {
          "attributes": {
            "adminSt": "start",
            "name": "checkpt-20160930",
            "description": "",
            "filename": "",
            "delete": "yes",
            "dn": "sys/action/lsubj-[sys]/topSystemCreateCheckpointLTask",
            "freq": "one-shot"
          }
        }
      }
    ]
  }
}

{     
  "imdata": [] 
}

Deletes the checkpoint named "checkpt-20160930"

By including "delete": "yes" in the payload, this example deletes the checkpoint.

CLI Command

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

no checkpoint {[<name>] [description <descr>] | file <file_uri>}

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.

topSystemCreateCheckpointLTask Properties

The following table contains information about the topSystemCreateCheckpointLTask 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.

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

Clearing groups of checkpoints

Clearing groups of checkpoints

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

{
  "actionLSubj": {
    "attributes": {
      "dn": "sys/action/lsubj-[sys]"
    },
    "children": [
      {
        "topSystemClearCheckpointDBLTask": {
          "attributes": {
            "adminSt": "start",
            "mode": "all",
            "dn": "sys/action/lsubj-[sys]/topSystemClearCheckpointDBLTask",
            "freq": "one-shot"
          }
        }
      }
    ]
  }
}

{     
  "imdata": [] 
}

Deletes the checkpoint named "checkpt-20160930"

This example clears all checkpoints in the system.

No information is present in the immediate JSON response. To verify success or failure and to view reasons for a failure, query the response object described below.

CLI Command

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

clear checkpoint database [user|system]

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.

topSystemClearCheckpointDBLTask Properties

The following table contains information about the topSystemClearCheckpointDBLTask 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.

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

Clearing groups of checkpoints

Clearing groups of checkpoints

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

{
  "actionLSubj": {
    "attributes": {
      "dn": "sys/action/lsubj-[sys]"
    },
    "children": [
      {
        "topSystemClearCheckpointDBLTask": {
          "attributes": {
            "adminSt": "start",
            "mode": "all",
            "dn": "sys/action/lsubj-[sys]/topSystemClearCheckpointDBLTask",
            "freq": "one-shot"
          }
        }
      }
    ]
  }
}

{     
  "imdata": [] 
}

Deletes the checkpoint named "checkpt-20160930"

This example clears all checkpoints in the system.

No information is present in the immediate JSON response. To verify success or failure and to view reasons for a failure, query the response object described below.

CLI Command

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

clear checkpoint database [user|system]

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.

topSystemClearCheckpointDBLTask Properties

The following table contains information about the topSystemClearCheckpointDBLTask 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.

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

Triggering a rollback

Triggering a rollback

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

{
  "actionLSubj": {
    "attributes": {
      "dn": "sys/action/lsubj-[sys]"
    },
    "children": [
      {
        "topSystemRollbackLTask": {
          "attributes": {
            "adminSt": "start",
            "name": "checkpt-20160930",
            "uri": "",
            "dn": "sys/action/lsubj-[sys]/topSystemRollbackLTask",
            "freq": "one-shot"
          }
        }
      }
    ]
  }
}

This example rolls back to a checkpoint with a name.

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.

topSystemRollbackLTask Properties

The following table contains information about the topSystemRollbackLTask 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.

Related Documentation

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

Triggering a rollback (bootflash)

Triggering a rollback (bootflash)

{
  "actionLSubj": {
    "attributes": {
      "dn": "sys/action/lsubj-[sys]"
    },
    "children": [
      {
        "topSystemRollbackLTask": {
          "attributes": {
            "adminSt": "start",
            "name": "",
            "uri": "bootflash:ckp2",
            "dn": "sys/action/lsubj-[sys]/topSystemRollbackLTask",
            "freq": "one-shot"
          }
        }
      }
    ]
  }
}

{     
  "imdata": [] 
}

This example rolls back to a checkpoint file in bootflash.

No information is present in the immediate JSON response. To verify success or failure and to view reasons for a failure, query the response object described below.

CLI Command

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

rollback running-config {checkpoint <checkpoint_name> | file <file_uri>} [best-effort | stop-at-first-failure | atomic] [verbose]

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.

topSystemRollbackLTask Properties

The following table contains information about the topSystemRollbackLTask 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.

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

Triggering a rollback (bootflash)

Triggering a rollback (bootflash)

{
  "actionLSubj": {
    "attributes": {
      "dn": "sys/action/lsubj-[sys]"
    },
    "children": [
      {
        "topSystemRollbackLTask": {
          "attributes": {
            "adminSt": "start",
            "name": "",
            "uri": "bootflash:ckp2",
            "dn": "sys/action/lsubj-[sys]/topSystemRollbackLTask",
            "freq": "one-shot"
          }
        }
      }
    ]
  }
}

{     
  "imdata": [] 
}

This example rolls back to a checkpoint file in bootflash.

No information is present in the immediate JSON response. To verify success or failure and to view reasons for a failure, query the response object described below.

CLI Command

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

rollback running-config {checkpoint <checkpoint_name> | file <file_uri>} [best-effort | stop-at-first-failure | atomic] [verbose]

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.

topSystemRollbackLTask Properties

The following table contains information about the topSystemRollbackLTask 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.

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

Limitations on Configuring Checkpoints and Rollbacks with NX-API

1. When sending a checkpoint payload, provide the complete attribute list. Any attribute that is not required should be sent empty.
2. When posting a task for creating a checkpoint to a name, the “file” attribute must be empty in the payload.
3. When posting a task for creating a checkpoint to a file, only the “file” attribute should contain text, except for the “delete” attribute, which must contain “no”. The remaining attributes must be empty.
4. When deleting a checkpoint, the payload must contain only the “name” attribute with the checkpoint name to be deleted, except for the “delete” attribute, which must contain “yes”. The remaining attributes must be empty.
5. A payload must be provided as described above for all tasks.
6. A maximum of 10 user-triggered checkpoints can be created on the device. Any user command to create an additional checkpoint is ignored. To add a new checkpoint when the limit has been reached, you must first delete one of the existing checkpoints.
7. You can modify the "description" attribute with a new checkpoint request whose payload contains the same “name” attribute. Because you cannot overwrite a previously saved checkpoint, only the description will be changed.
8. You must allow 5 to 10 seconds between consecutive REST requests.
9. You cannot start a checkpoint filename with the word system.