Coletar o pacote de suporte ISE usando a API ERS

Introdução

Este documento descreve o processo para acionar e fazer o download de um pacote de suporte do ISE através da API ERS usando PostMan como o cliente REST. 

Pré-requisitos

Requisitos

A Cisco recomenda que você tenha conhecimento destes tópicos:

• ISE
• Serviços RESTful externos
• Clientes do REST como Postman, RESTED, Insomnia, etc.

Componentes Utilizados

As informações neste documento são baseadas nestas versões de software:

• Patch 6 do Cisco ISE 3.1
• Postman REST client v10.17.4

As informações neste documento foram criadas a partir de dispositivos em um ambiente de laboratório específico. Todos os dispositivos utilizados neste documento foram iniciados com uma configuração (padrão) inicial. Se a rede estiver ativa, certifique-se de que você entenda o impacto potencial de qualquer comando.

Configurar

Ativar ERS (Porta 9060)

As APIs ERS são APIs REST somente HTTPS que operam nas portas 443 e 9060. A porta 9060 é fechada por padrão, por isso precisa ser aberta primeiro. Um tempo limite do servidor será apresentado se os clientes que tentarem acessar essa porta não ativarem o ERS primeiro. Portanto, o primeiro requisito é ativar o ERS na interface do usuário do administrador do Cisco ISE.

Navegue até Administration > Settings > API Settings e ative o botão de alternância ERS (Read/Write).

Criar ERS Admin

Crie um administrador do Cisco ISE, atribua uma senha e adicione o usuário ao grupo admin como ERS Admin. Você pode deixar o restante da configuração vazio.

Configurar Postman

Faça o download ou use a versão online do Postman.

1. Crie um usuário e um espaço de trabalho clicando em Criar espaço de trabalho na guia Espaços de trabalho.

2. Selecione Espaço de Trabalho em Branco e atribua um nome ao espaço de trabalho. Você pode adicionar uma descrição e torná-la pública. Para este exemplo, Personalis foi selecionado.

Depois de criar o espaço de trabalho, você pode configurar nossas chamadas à API.

Pacote de suporte Trigger 

Para configurar qualquer chamada, primeiro acesse o ISE ERS SDK (Software Developer Kit). Esta ferramenta compila toda a lista de chamadas de API que o ISE pode executar:

1. Vá para https://{ise-ip}/ers/sdk
2. Faça login usando suas credenciais de administrador do ISE.
3. Expandir a documentação da API
4. Role para baixo até encontrar Support Bundle Trigger Configuration e clique nele.
5. Nessa opção, você pode encontrar todas as operações disponíveis que podem ser executadas para essa opção no ISE. Selecione Criar.

6. Agora você pode ver a configuração necessária para executar a chamada de API usando XML ou JSON em qualquer Cliente Rest, bem como um exemplo de resposta esperada. 

7. Voltar ao Postman permite configurar a autenticação básica no ISE. Na guia Authorization, selecione Basic Auth como o tipo de autenticação e adicione as credenciais do usuário do ISE ERS criadas anteriormente no ISE.

8. No Postman vá até a guia Cabeçalhos e configure os cabeçalhos necessários para a chamada de API usando XML ou JSON conforme visto no SDK. Neste exemplo, JSON é usado. A configuração do cabeçalho deve ser semelhante a esta:

9. Vá até o cabeçalho Corpo e selecione bruto. Isso nos permite colar o modelo XML ou JSON necessário para acionar o pacote de suporte. 

10. Cole o modelo XML ou JSON na seção Body alterando os valores conforme necessário:

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. Selecione POST como o método, cole https://{ISE-ip}/ers/config/supportbundle e clique em Send. Se tudo tiver sido configurado corretamente, você deverá ver a mensagem "201 Created" e o resultado vazio. 

Verificar o status do pacote de suporte

Você pode confirmar se o pacote de suporte foi acionado ou concluído com a execução de uma série de chamadas GET. 

1. No SDK em Support Bundle Statustab, selecione Get-All. Você deseja obter a ID para poder executar a próxima chamada GET.  Como visto antes, estes são os cabeçalhos necessários para executar a chamada, bem como a resposta esperada.

2. Vá até a guia Cabeçalhos e configure os cabeçalhos necessários para a chamada de API conforme visto no SDK. Neste exemplo, JSON é usado. A configuração do cabeçalho deve ser semelhante a esta:

3. Selecione GET como o método, cole https://{ISE-ip}/ers/config/supportbundlestatus e clique em Enviar. Se tudo tiver sido configurado corretamente, você deverá ver uma mensagem "200 OK" e o resultado com informações relacionadas ao último pacote de suporte disparado. Esta chamada não nos permite saber se o pacote de suporte foi concluído com êxito ou não. Nessa chamada, colete a ID para que você possa usá-la na próxima chamada GET. 

4. Uma vez coletada a ID, vá para o SDK, na guia Status do Pacote de Suporte e selecione Get-By-Id. Como visto antes, aqui estão os cabeçalhos necessários para executar a chamada, bem como a resposta esperada.

5. Vá até a guia Cabeçalhos e configure os cabeçalhos necessários para a chamada de API conforme visto no SDK. Neste exemplo, JSON é usado. A configuração do cabeçalho deve ser semelhante a esta:

6. Selecione GET como o método, cole https://{ISE-ip}/ers/config/supportbundlestatus/{id} e a ID coletada da etapa 3 e, finalmente, clique em Enviar. Se tudo tiver sido configurado corretamente, você deverá ver uma mensagem "200 OK" e o resultado com informações relacionadas à conclusão ou não do último pacote de suporte disparado. Anote o fileName dessa chamada, já que você precisa da chamada PUT.

Download do pacote de suporte

Após confirmar que o pacote de suporte está no estado concluído. Você pode continuar o download. 

1. No SDK, na guia Download do pacote de suporte, selecione Download do pacote de suporte. Como visto antes, aqui estão os cabeçalhos necessários para executar a chamada, os modelos XML e JSON, bem como a resposta esperada.

2. Vá até a guia Cabeçalhos e configure os cabeçalhos necessários para a chamada de API conforme visto no SDK. Neste exemplo, JSON é usado. A configuração do cabeçalho deve ser semelhante a esta:

3. Vá até o cabeçalho Body e selecione raw. Isso nos permite colar o modelo XML ou JSON necessário para baixar o pacote de suporte. 

4. Cole o modelo XML ou JSON na seção Corpo alterando os valores conforme necessário. O nome do arquivo seria o nome do arquivo coletado da etapa 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. Selecione PUT como o método, cole https://{ISE-ip}/ers/config/supportbundledownload e clique em Enviar. Se tudo tiver sido configurado corretamente, você deverá ver uma mensagem "200 OK" e o arquivo deverá ser baixado. 

Verificar

 Se você puder acessar a página da GUI do serviço de API, por exemplo, https://{iseip}:{port}/api/swagger-ui/index.html ou https://{iseip}:9060/ers/sdk, isso significa que o serviço de API está funcionando conforme esperado.

Troubleshooting

• Todas as operações REST são auditadas e os registros são registrados nos registros do sistema.
• Para solucionar problemas relacionados às APIs abertas, defina o Nível de Log do componente apiservice como DEBUG na janela Configuração do Log de Depuração.
• Para solucionar problemas relacionados às APIs ERS, defina o Nível de Log do componente ers como DEBUG na janela Debug Log Configuration. Para visualizar essa janela, navegue até a GUI do Cisco ISE, clique no ícone Menu e escolha Operations > Troubleshoot > Debug Wizard > Debug Log Configuration.
• Você pode fazer o download dos logs na janela Download Logs. Para visualizar essa janela, navegue até a GUI do Cisco ISE, clique no ícone Menu e escolha Operations > Troubleshoot > Download Logs.
• Você pode optar por fazer download de um pacote de suporte na guia Pacote de suporte clicando no botão Download na guia, ou fazer download dos logs de depuração do api-service na guia Logs de depuração clicando no valor do Arquivo de log para o log de depuração do api-service.