Collect ISE Support Bundle Using ERS API

Introduction

This document describes the process for triggering and downloading an ISE Support Bundle via ERS API using PostMan as the REST Client. 

Prerequisites

Requirements

Cisco recommends that you have knowledge of these topics:

• ISE
• External RESTful Services
• REST clients like Postman, RESTED, Insomnia, and so on.

Components Used

The information in this document is based on these software versions:

• Cisco ISE 3.1 patch 6
• Postman REST client v10.17.4

Note: The procedure is similar or identical for other ISE versions and REST Clients. You can use these steps on all 2.x and 3.x ISE Software Releases unless stated otherwise.

The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, ensure that you understand the potential impact of any command.

Configure

Enable ERS (Port 9060)

ERS APIs are HTTPS-only REST APIs that operate over port 443 and port 9060. Port 9060 is closed by default, so it needs to be opened first. A timeout from the server is presented if clients trying to access this port do not enable ERS first. Therefore, the first requirement is to enable ERS from the Cisco ISE admin UI.

Navigate to Administration > Settings > API Settings and enable the ERS (Read/Write) toggle button.

Note: The ERS APIs support TLS 1.1 and TLS 1.2. ERS APIs do not support TLS 1.0 regardless of enabling TLS 1.0 in the Security Settings window of the Cisco ISE GUI (Administration > System > Settings > Security Settings). Enabling TLS 1.0 in the Security Settings window is related to the EAP protocol only and does not impact ERS APIs.

Create ERS Admin

Create a Cisco ISE Administrator, assign a password, and add the user to the admin group as ERS Admin. You can leave the rest of the configuration empty.

Set up Postman

Download or use the the online version of Postman.

1. Create a user and create a workspace by clicking Create Workspace under the Workspaces tab.

2. Select Blank Workspace and assign a name to the workspace. You can add a description and make it public. For this example Personalis selected.

Once you have created the workspace, you can now configure our API calls.

Trigger Support Bundle 

To configure any call, lets first access the ISE ERS SDK (Software Developer Kit). This tool compiles the whole list of API calls ISE can perform:

1. Go to https://{ise-ip}/ers/sdk
2. Login using your ISE Admin credentials.
3. Expand the API Documentation
4. Scroll down until you find Support Bundle Trigger Configuration and click on it.
5. Under this option you can now find all the available operations you can perform for this option on ISE. Select Create.

6. You can now see the configuration required to perform the API call using XML or JSON on any Rest Client as well as an expected response example. 

7.Back to Postman lets configure basic authentication to ISE. Under the Authorization tab, select Basic Auth as the authentication type and add the ISE ERS User credentials previously created on ISE.

Note: The password are shown as clear text unless variables are configured on Postman

8. In Postman move to the Headers tab and configure the needed headers for the API call using either XML or JSON as seen in the SDK. In this example JSON is used. The header configuration must look like this:

9. Move to the Body header and select raw. This allows us to paste the XML or JSON template needed for triggering the Support Bundle. 

10. Paste the XML or JSON template in the Body section changing the values as needed:

XML:

<?xml version="1.0" encoding="UTF-8"?> <ns0:supportbundle xmlns:ns0="supportbundle.ers.ise.cisco.com" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:ns1="ers.ise.cisco.com" xmlns:ers="ers.ise.cisco.com" description="Support Bundle Generation" name="supportBundle"> <hostName>Node hostname the SB is being collected from </hostName> <supportBundleIncludeOptions> <fromDate>mm/dd/yyyy</fromDate> <includeConfigDB>true|false</includeConfigDB> <includeCoreFiles>true|false</includeCoreFiles> <includeDebugLogs>true|false</includeDebugLogs> <includeLocalLogs>true|false</includeLocalLogs> <includeSystemLogs>true|false</includeSystemLogs> <mntLogs>true|false</mntLogs> <policyXml>true|false</policyXml> <toDate>mm/dd/yyyy</toDate> </supportBundleIncludeOptions> </ns0:supportbundle>

JSON:

{ "SupportBundle": { "name": "supportBundle", "description": "Support Bundle Generation", "hostName": "node hostname the SB is being collected from", "supportBundleIncludeOptions": { "includeConfigDB": true|false, "includeDebugLogs": true|false, "includeLocalLogs": true|false, "includeCoreFiles": true|false, "mntLogs": true|false, "includeSystemLogs": true|false, "policyXml": true|false, "fromDate": "mm/dd/yyyy", "toDate": "mm/dd/yyyy" } } }

11. Select POST as the method, paste https://{ISE-ip}/ers/config/supportbundle and click Send. If everything was correctly configured, you must see a “201 Created” message and the result empty. 

Check Support Bundle Status

You can confirm if the Support Bundle triggered or completed by running a series of GET calls. 

Note: The Support Bundle must take 5-20 minutes to complete depending on the amount of information collected from the logs.

1. On the SDK under theSupport Bundle Statustab selectGet-All. You want to get the ID so you can run the next GET call.  As seen before, here are the headers required to perform the call as well as the expected response.

2. Move to the Headers tab and configure the needed headers for the API call as seen in the SDK. In this example JSON is used. The header configuration must look like the following:

3. Select GET as the method, paste https://{ISE-ip}/ers/config/supportbundlestatus and click Send. If everything was correctly configured, you must see a “200 OK” message and the result with information related to the last Support Bundle triggered. This call does not let us know if the Support Bundle completed successfuly or not. From this call collect the ID so you can use it on the next GET call. 

4. Once the ID is collected, go to the SDK,under theSupport Bundle Statustab and selectGet-By-Id.  As seen before, here are the headers required to perform the call as well as the expected response.

5. Move to the Headers tab and configure the needed headers for the API call as seen in the SDK. In this example JSON is used. The header configuration must look like this:

6. Select GET as the method, paste https://{ISE-ip}/ers/config/supportbundlestatus/{id} and the ID collected from step 3, finally click Send. If everything was correctly configured, you must see a “200 OK” message and the result with information related to the completion or not of the last Support Bundle triggered. Make note of the fileName from this call since you need for the PUT call.

Download Support Bundle

Once you confirm the Support Bundle is in the completed state. You can proceed to download it. 

1. On the SDK under theSupport Bundle Downloadtab selectDownload SupportBundle. As seen before, here are the headers required to perform the call, the XML and JSON templates, as well as the expected response.

2. Move to the Headers tab and configure the needed headers for the API call as seen in the SDK. In this example JSON is used. The header configuration must look like this:

3. Move to the Body header and select raw. This allows us to paste the XML or JSON template needed for downloading the Support Bundle. 

4. Paste the XML or JSON template in the Body section changing the values as needed. The file name would be the name of the file collected from step 6 (ise-support-bundle-pk-ise3-1test-external-09-26-2023-01-26.tar.gpg):

XML

<?xml version="1.0" encoding="UTF-8"?> <ns0:supportbundle xmlns:ns0="supportbundle.ers.ise.cisco.com" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:ns1="ers.ise.cisco.com" xmlns:ers="ers.ise.cisco.com"> <fileName>Support bundle file name to be picked for download</fileName> </ns0:supportbundle>

JSON:

{ "ErsSupportBundleDownload" : { "fileName" : "Support bundle file name to be picked for download" } }

5. Select PUT as the method, paste https://{ISE-ip}/ers/config/supportbundledownload and click Send. If everything was correctly configured, you must see a “200 OK” message and the file donwloaded. 

Verify

 If you are able to access the API service GUI page, for example, https://{iseip}:{port}/api/swagger-ui/index.html or https://{iseip}:9060/ers/sdk, it means the API service is working as expected.

Troubleshoot

• All REST operations are audited and the logs are logged in the system logs.
• To troubleshoot issues that are related to the Open APIs, set the Log Level for the apiservice component to DEBUG in the Debug Log Configuration window.
• To troubleshoot issues relating to the ERS APIs, set the Log Level for the ers component to DEBUG in the Debug Log Configuration window. To view this window, navigate to the Cisco ISE GUI, click the Menu icon and choose Operations > Troubleshoot > Debug Wizard > Debug Log Configuration.
• You can download the logs from the Download Logs window. To view this window, navigate to the Cisco ISE GUI, click the Menu icon and choose Operations > Troubleshoot > Download Logs.
• You can choose to download either a support bundle from the Support Bundle tab by clicking the Download button under the tab, or download the api-service debug logs from the Debug Logs tab by clicking the Log File value for the api-service debug log.