CISCO ASA REST API App User Guide

Cuntenuti ammuccià

1 CISCO ASA REST API App

2 Istruzzioni per l'usu di u pruduttu

3 Overview

4 ASA REST API Richieste è Risposte

5 Installa è cunfigurà l'Agente è u Client API REST ASA

6 A Console di Documentazione è Esporta Scripts API

7 Attivazione di u debugging REST API nantu à l'ASA

8 Messaggi Syslog ASA REST API

9 Documentazione Relativa

10 Documenti / Risorse

10.1 Referenze

CISCO ASA REST API App

Istruzzioni per l'usu di u pruduttu

Overview

Cù a liberazione di l'API ASA REST di Cisco, avete avà un'altra opzione ligera è faciule d'utilizà per cunfigurà è gestisce individuali Cisco ASA. L'ASA REST API hè una interfaccia di prugrammazione di l'applicazione (API) basatu annantu à i principii RESTful. Pò esse scaricatu rapidamente è attivatu nantu à qualsiasi ASA induve l'API hè in esecuzione. Cisco Systems, Inc.

www.cisco.com

ASA REST API Richieste è Risposte

Dopu avè installatu un cliente REST in u vostru navigatore, pudete cuntattà l'agente REST di l'ASA specificu è aduprà metudi HTTP standard per accede à l'infurmazioni di cunfigurazione attuale è emette parametri di cunfigurazione supplementari.

Attenzione: Quandu l'API REST hè attivata nantu à un ASA, e cunnessione da altri protokolli di gestione di sicurezza ùn sò micca bluccati. Questu significa chì altri chì utilizanu CLI, ASDM, o Security Manager puderanu cambià a cunfigurazione ASA mentre fate u listessu.

Struttura di dumanda

L'API REST ASA vi dà un accessu programmaticu à a gestione di ASA individuali attraversu una API di Trasferimentu di Statu Rappresentanti (REST). L'API permette à i clienti esterni di fà operazioni CRUD (Create, Read, Update, Delete) nantu à risorse ASA. Tutte e dumande API sò mandate per HTTPS à l'ASA, è una risposta hè tornata.

induve e proprietà di l'ughjettu sò:

Pruprietà	Tipu	Descrizzione
missaghji	Lista di dizionari	Lista di messagi d'errore o avvirtimenti
codice	Stringa	Messaghju detallatu chì currisponde à Errore / Avvisu / Info
dettagli	Stringa	Messaghju detallatu chì currisponde à Errore / Avvisu / Info

Nota: I cambiamenti fatti da e chjama di l'API REST ùn sò micca persistenti à a cunfigurazione di startup, ma sò attribuiti solu à a cunfigurazione in esecuzione. Per salvà i cambiamenti à a cunfigurazione di startup, pudete aduprà u POST una dumanda di scrittura mem API. Per più infurmazione, riferite à l'entrata di l'API di Memoria di Scrittura in a Tavola di cuntenutu di l'API ASA REST.

Installa è cunfigurà l'Agente è u Client API REST ASA

Nota: L'Agente REST API hè una applicazione basata in Java. U Java Runtime Environment (JRE) hè bundle in u pacchettu REST API Agent.

Overview

Ci sò parechje opzioni dispunibuli per cunfigurà è gestisce individuali Cisco ASA:

Command Line Interface (CLI) - mandate cumandamenti di cuntrollu direttamente à l'ASA via una cunsola cunnessa.

Adaptive Security Device Manager (ASDM) - una applicazione di gestione "on-box" cù una interfaccia d'utilizatore grafica chì pudete aduprà per cunfigurà, gestisce è monitorizà un ASA.
Cisco Security Manager - mentre chì hè destinatu à e reti medie à grande di parechji dispositi di sicurità, sta applicazione grafica pò esse aduprata per cunfigurà, gestisce è monitorà l'ASA individuali.

Cù a liberazione di l'API ASA REST di Cisco, avete avà una altra opzione ligera è faciule d'utilizà. Questa hè una interfaccia di prugrammazione di l'applicazione (API), basatu annantu à i principii "RESTful", chì pudete scaricà rapidamente è attivà nantu à qualsiasi ASA nantu à quale l'API hè in esecuzione.

Dopu avè installatu un cliente REST in u vostru navigatore, pudete cuntattà l'agente REST specificu di l'ASA è aduprà metudi HTTP standard per accede à l'infurmazioni di cunfigurazione attuale, è emette parametri di cunfigurazione supplementari.

ASA REST API Richieste è Risposte

L'ASA REST API vi dà un accessu programmaticu à a gestione di l'ASA individuali attraversu una API di Trasferimentu di Statu Rappresentanti (REST). L'API permette à i clienti esterni di fà operazioni CRUD (Create, Read, Update, Delete) nantu à risorse ASA; hè basatu annantu à u protocolu HTTPS è a metodulugia REST. Tutte e dumande API sò mandate per HTTPS à l'ASA, è una risposta hè tornata. Questa sezione furnisce un sopraview di cume sò strutturate e richieste, è e risposte previste,

Struttura di dumanda

I metudi di dumanda dispunibuli sò:

GET - Recupera dati da l'ughjettu specificatu.
PUT - Aghjunghje l'infurmazioni furnite à l'ughjettu specificatu; torna un errore 404 Resource Not Found se l'ughjettu ùn esiste micca.

POST - Crea l'ughjettu cù l'infurmazioni furnite.
DELETE - Elimina l'ughjettu specificatu.

PATCH - Applica mudificazioni parziali à l'ughjettu specificatu.

Struttura di Risposta

Ogni dumanda produce una risposta HTTPS da l'ASA cù l'intestazione standard, u cuntenutu di risposta è u codice di statutu.

A struttura di risposta pò esse:

LOCATION - ID di risorsa di novu creatu; solu per POST - cuntene u novu ID di risorsa (cum'è una rappresentanza URI).
CONTENT-TYPE - Tipu di media chì descrive u corpu di u messagiu di risposta; descrive a rapprisintazioni è a sintassi di u corpu di missaghju di risposta.

Ogni risposta include un statu HTTP o codice d'errore. I codici dispunibili entranu in queste categurie:

20x - Un codice di dui centu serie indica una operazione successu, cumprese:
- 200 OK - Risposta standard per richieste di successu.
- 201 Creatu - A dumanda cumpleta; nova risorsa creatu.
- 202 Acceptatu - A dumanda accettata, ma u prucessu ùn hè micca cumpletu.
- 204 Nisun cuntenutu - U servitore hà trattatu bè a dumanda; nisun cuntenutu hè tornatu.
4xx - Un codice di quattru centu serie indica un errore di u cliente, cumprese:
- 400 Bad Request - Paràmetri di dumanda invalidi, cumpresi paràmetri micca ricunnisciuti, paràmetri mancanti, o valori invalidi.
- 404 Not Found - U furnitu URL ùn currisponde à una risorsa esistente. Per esample, un HTTP DELETE pò falla perchè a risorsa ùn hè micca dispunibule.
- 405 Metudu micca permessu - Una dumanda HTTP hè stata presentata chì ùn hè micca permessa nantu à a risorsa; per example, un POST nantu à una risorsa di sola lettura.
5xx - Un codice di cinque centu serie indica un errore di u servitore.

In u casu di un errore, in più di u codice d'errore, a risposta di ritornu pò include un oggettu d'errore chì cuntene più dettagli nantu à l'errore. U schema di risposta d'errore / avvistu JSON hè u seguente:

induve e proprietà di l'ughjettu sò:

Pruprietà	Tipu	Descrizzione
missaghji	Lista di dizionari	Lista di messagi d'errore o avvirtimenti
codice	Stringa	Errore / Avvisu / Codice Info
dettagli	Stringa	Messaghju detallatu chì currisponde à Errore / Avvisu / Info

Nota: I cambiamenti à a cunfigurazione ASA fatta da e chjama di l'API REST ùn sò micca persiste in a cunfigurazione di startup; vale à dì, i cambiamenti sò attribuiti solu à a cunfigurazione in esecuzione. Per salvà cambiamenti à a cunfigurazione di startup, pudete POST una dumanda API writemem; per più infurmazione, seguite l'entrata "Scrivi l'API di Memoria" in a Tavola di cuntenutu di l'API ASA REST.

Installa è cunfigurà l'Agente è u Client API REST ASA

L'Agente REST API hè publicatu individualmente cù altre imagine ASA cisco.com. Per l'ASA fisichi, u pacchettu REST API deve esse scaricatu à u flash di u dispusitivu è installatu cù u cumandimu "rest-api image". L'Agente REST API hè dopu attivatu cù u cumandimu "rest-api agent".
Cù un ASA virtuale (ASAv), l'imaghjini di l'API REST deve esse scaricata à a partizione "boot:". Dopu duvete emette u cumandimu "rest-api image", seguitu da u cumandimu "rest-api agent", per accede è attivà l'Agente REST API.
Per infurmazione nantu à u software REST API è i requisiti hardware è a cumpatibilità, vede a matrice di compatibilità Cisco ASA.

Pudete scaricà u pacchettu API REST appropritatu per u vostru ASA o ASAv da software.cisco.com/download/home. Truvate u mudellu specificu di l'Appliance di Sicurezza Adattativa (ASA) è dopu sceglite u Plugin API REST di Appliance di Sicurezza Adattativa.

Nota: L'Agente REST API hè una applicazione basata in Java. U Java Runtime Environment (JRE) hè bundle in u pacchettu REST API Agent.

Linee d'usu

Impurtante Duvete include l'intestazione User-Agent: REST API Agent in tutte e chjama API è script esistenti. Aduprate -H 'User-Agent: REST API Agent' per u CURL cumanda. In modu multi-cuntestu, i cumandamenti di l'Agente REST API sò dispunibuli solu in u cuntestu di u Sistema.

Dimensione massima di cunfigurazione supportata

L'ASA Rest API hè una applicazione "a bordu" chì funziona in l'ASA fisicu, è per quessa hà una limitazione di a memoria attribuita. A dimensione massima di cunfigurazione di esecuzione supportata hè aumentata annantu à u ciculu di liberazione à circa 2 MB nantu à e piattaforme recenti cum'è 5555 è 5585. L'ASA Rest API hà ancu limitazioni di memoria nantu à e plataformi ASA virtuale. A memoria tutale nantu à l'ASAv5 pò esse 1.5 GB, mentre chì in l'ASAv10 hè 2 GB. I limiti Rest API sò 450 KB è 500 KB per ASAv5 è ASAv10, rispettivamente.

Dunque, esse cuscenti chì e grandi cunfigurazioni in esecuzione ponu pruducia eccezzioni in diverse situazioni intensive di memoria, cum'è un gran numaru di richieste simultanee, o volumi di richieste grandi. In queste situazioni, e chjama di Rest API GET / PUT / POST ponu cumincià à fallimentu cù 500 - Messaggi d'errore di u Servitore Internu, è l'Agente Rest API riavviarà automaticamente ogni volta. I rimedii à sta situazione sò sia si move in piattaforme ASA / FPR o ASAV di memoria più alta, o riduce a dimensione di a cunfigurazione in esecuzione.

Scaricate è installate l'agente API REST

Utilizendu a CLI, seguite questi passi per scaricà è installà l'agente ASA REST API in un ASA specificu:

Passu 1: Nantu à l'ASA desiderata, emette a copia disk0: cumanda per scaricà l'attuale pacchettu API ASA REST da cisco.com à a memoria flash di l'ASA.
- Per esampLe: copia tftp://10.7.0.80/asa-restapi-111-lfbff-k8.SPA disk0:
Passu 2: Emette u rest-api image disk0:/ cumanda per verificà è stallà u pacchettu.
- Per esampLe: rest-api image disk0:/asa-restapi-111-lfbff-k8.SPA

L'installatore farà cuntrolli di cumpatibilità è validazione, è dopu installà u pacchettu. L'ASA ùn riavviarà micca.

Habilita l'agente API REST

Segui questi passi per attivà l'Agente API REST ASA nantu à un ASA specificu:

Passu 1: Assicuratevi chì l'imaghjini di u software currettu hè stallatu nantu à l'ASA.
- Cunsultate a sezione REST API di a Matrice di Compatibilità ASA (https://www.cisco.com/c/en/us/td/docs/security/asa/compatibility/asamatrx.html#pgfId-131643) per stabilisce quale imagine ASA hè necessaria.

Passu 2: Utilizendu a CLI, assicuratevi chì u servitore HTTP hè attivatu nantu à l'ASA, è chì i clienti API ponu cunnette à l'interfaccia di gestione.
- Per esampLe: Http server attivatu
- http 0.0.0.0 0.0.0.0

Passu 3: Utilizendu a CLI, definisce l'autentificazione HTTP per e cunnessione API. Per esample: aaa autenticazione http console LOCAL
Passu 4: Utilizendu a CLI, crea una strada statica nantu à l'ASA per u trafficu API. Per esample: rotta 0.0.0.0 0.0.0.0 1
Passu 5: Utilizendu a CLI, attivate l'ASA REST API Agent in l'ASA. Per esample : agent rest-api

Autenticazione API REST

Ci hè dui modi per autentificà: l'autentificazione HTTP basica, chì passa un nome d'utilizatore è una password in ogni dumanda, o l'autentificazione basata in Token cù trasportu HTTPS sicuru, chì passa un token creatu prima cù ogni dumanda. In ogni modu, l'autentificazione serà realizatu per ogni dumanda. Vede a sezione "Token_Authentication_API" in a Guida di ASA REST API v7.14(x) per infurmazioni supplementari nantu à l'autentificazione basata in Token.

Nota: L'usu di certificati emessi da l'Autorità di Certificazione (CA) hè cunsigliatu nantu à ASA, cusì i clienti REST API ponu cunvalidà i certificati di u servitore ASA quandu stabiliscenu cunnessione SSL.

Autorizazione di cumandamentu

Se l'autorizazione di cumanda hè cunfigurata per utilizà un servitore AAA esternu (per esample, aaa cumanda d'autorizazione ), allora un utilizatore chjamatu enable_1 deve esse in quellu servitore cù privilegi di cumandamentu cumpletu. Se l'autorizazione di cumanda hè cunfigurata per utilizà a basa di dati LOCAL di l'ASA (cumandamentu d'autorizazione aaa LOCAL), allora tutti l'utilizatori di l'API REST anu da esse registrati in a basa di dati LOCAL cù livelli di privilegi adattati per i so roli:

U livellu di privilegiu 3 o più altu hè necessariu per invucà e dumande di monitoraghju.

U livellu di privilegiu 5 o più altu hè necessariu per invucà e richieste GET.
U livellu di privilegiu 15 hè necessariu per invucà operazioni PUT/POST/DELETE.

Configurate u vostru Client API REST

Segui questi passi per installà è cunfigurà un cliente API REST in u vostru navigatore d'ospiti locale:

Passu 1: Acquisite è installate un cliente API REST per u vostru navigatore.
- Per Chrome, installate u cliente REST da Google. Per Firefox, installate l'add-on RESTClient. Internet Explorer ùn hè micca supportatu.

Passu 2: Inizià a seguente dumanda cù u vostru navigatore: https: /api/objects/networkobjects
- Se riceve una risposta senza errore, avete ghjuntu à l'agente REST API chì funziona in l'ASA.
- Sè avete prublemi cù a dumanda di l'agente, pudete attivà a visualizazione di l'infurmazioni di debugging in a cunsola CLI, cum'è descritta in Abilitazione di debugging REST API in ASA.

Passu 3: Opcionalmente, pudete pruvà a vostra cunnessione à l'ASA eseguendu una operazione POST.

Per esampLe: Fornite e credenziali d'autorizazione di basa ( ), o un token di autentificazione (vede Autenticazione di Token per infurmazioni supplementari).

Indirizzu di dumanda di destinazione: https://<asa management ipaddress>/api/objects/networkobjects

Tipu di cuntenutu di corpu: applicazione/json

Corpu crudu di l'operazione:

Pudete avà aduprà l'API REST ASA per cunfigurà è monitorizà l'ASA. Consultate a documentazione di l'API per e descrizioni di chjama è examples.

A propositu di Ripristina cumplettamente una Configurazione di Back-up

Ripristina una cunfigurazione di salvezza completa nantu à l'ASA utilizendu l'API REST ricaricarà l'ASA. Per evità questu, utilizate u cumandimu seguitu per restaurà una cunfigurazione di salvezza:

{
- "cumandamenti": ["copia / noconfirm disk0:/filenome> running-config"]
}
- Induvefilename> hè backup.cfg o qualsiasi nome chì avete utilizatu durante a copia di salvezza di a cunfigurazione.

A Console di Documentazione è Esporta Scripts API

Pudete ancu aduprà a cunsola di documentazione in linea REST API (riferita cum'è "Doc UI"), dispunibule in host:port/doc/ cum'è "sandbox" per amparà è pruvà l'API chjamate direttamente nantu à l'ASA. In più, pudete aduprà u buttone di l'operazione d'esportazione in u Doc UI per salvà u metudu mostratu example cum'è un script JavaScript, Python o Perl file à u vostru host locale. Pudete tandu applicà stu script à u vostru ASA, è edità per l'applicazione in altri ASA è altri dispositi di rete. Questu significava principalmente cum'è un strumentu educativu è di bootstrapping.

JavaScript

Utilizà un JavaScript file richiede l'installazione di node.js, chì si pò truvà à http://nodejs.org/.
Utilizendu node.js, pudete eseguisce un JavaScript file, tipicamente scrittu per un navigatore, cum'è un script di linea di cumanda. Simply seguitate l'istruzzioni di stallazione, è poi eseguite u vostru script cù u node script.js.

Python

I script di Python necessitanu di installà Python, dispunibule da https://www.python.org/.
Una volta chì avete installatu Python, pudete eseguisce u vostru script cù python script.py username password.

Perl

L'usu di i script Perl richiede una configurazione supplementaria - avete bisognu di cinque cumpunenti: Perl stessu, è quattru biblioteche Perl:

Pacchettu Perl, trovu à http://www.perl.org/
Bundle::CPAN, trovu à http://search.cpan.org/~andk/Bundle-CPAN-1.861/CPAN.pm

REST::Cliente, trovu à http://search.cpan.org/~mcrawfor/REST-Client-88/lib/REST/Client.pm
MIME::Base64, trovu à http://perldoc.perl.org/MIME/Base64.html
JSON, trovu à http://search.cpan.org/~makamaka/JSON-2.90/lib/JSON.pm

Eccu un example di bootstrapping Perl su un Macintosh:

$ sudo perl -MCPAN è shell
cpan> install Bundle::CPAN

cpan> stallà REST:: Cliente
cpan> installà MIME::Base 64
cpan> installate JSON

Dopu a stallazione di e dependenzii, pudete eseguisce u vostru script usendu perl script.pl username password.

Attivazione di u debugging REST API nantu à l'ASA

Sè avete prublemi per cunfigurà o cunnette à l'API REST nantu à l'ASA, pudete aduprà u cumandimu CLI seguente per attivà a visualizazione di i missaghji di debugging in a vostra cunsola. Aduprà a forma senza u cumandamentu per disattivà i missaghji di debug.
debug rest-api [agent | cli | cliente | demone | prucessu | token-auth] [errore | event] senza debug rest-api

Descrizzione di sintassi

agente: (Opcional) Abilita l'infurmazione di debugging di l'Agente API REST.
cli: (Opzionale) Abilita i missaghji di debugging per e cumunicazioni Daemon-to-Agent CLI REST API.
cliente: (Opcional) Abilita l'infurmazioni di debugging per l'instradamentu di u Messaghju trà u Cliente API REST è l'Agente API REST.

demone: (Opcional) Abilita i missaghji di debugging per e cumunicazioni Daemon-to-Agent API REST.
prucessu: (Facoltativu) Abilita l'Agente REST API di u prucessu di avvià / ferma l'infurmazioni di debugging.
token-auth: (Facoltativo) REST API token authentication information debugging.

errore: (Opcional) Aduprate sta keyword per limità i missaghji di debug à solu errori registrati da l'API.
avvenimentu: (Opcional) Aduprate sta keyword per limità i missaghji di debug à solu avvenimenti registrati da l'API.

Linee d'usu

Se ùn furnite micca una chjave di cumpunente specifica (vale à dì, sè solu emette u cumandamentu debug rest-api), i missaghji di debug sò visualizati per tutti i tipi di cumpunenti. Se ùn furnite micca a chjave di l'avvenimentu o di l'errore, i missaghji di l'avvenimentu è di l'errore sò visualizati per u cumpunente specificatu. Per esample, debug rest-api daemon event mostrarà solu i missaghji di debug di l'avvenimentu per e cumunicazioni API Daemon-to-Agent.

Comandamenti Related

Cumanda / Descrizzione

debug HTTP; Aduprate stu cumandamentu per view infurmazione dettagliata nantu à u trafficu HTTP.

Messaggi Syslog ASA REST API

I missaghji di log di sistema di l'API ASA REST sò descritti in questa sezione.

342001

Missaghju d'errore: %ASA-7-342001: L'agente API REST hà iniziatu cù successu.
- Spiegazione: L'Agente API REST deve esse avviatu bè prima chì un Client API REST pò cunfigurà l'ASA.
- Azzione consigliata: Nimu.

342002

Missaghju d'errore: %ASA-3-342002: L'agente API REST hà fiascatu, mutivu: mutivu
- Spiegazione: L'Agente REST API puderia fallu di inizià o crash per diversi motivi, è u mutivu hè specificatu.
- ragione - A causa di u fallimentu di l'API REST

Azzione consigliata: L'azzioni pigliate per risolve u prublema varienu secondu u mutivu registratu. Per esample, l'Agente di l'API REST si crash quandu u prucessu Java si esaurisce a memoria. Se questu accade, avete bisognu di riavvia l'Agente API REST. Se u riavviu ùn hè micca successu, cuntattate u Cisco TAC per identificà a correzione di a causa principale.

342003

Missaghju d'errore: %ASA-3-342003: Notificazione di fallimentu di l'agente REST API ricevuta. L'agente serà riavviatu automaticamente.
- Spiegazione: Una notificazione di fallimentu da l'Agente REST API hè stata ricevuta è un riavviu di l'Agente hè statu pruvatu.
- Azzione consigliata: Nimu.

342004

Missaghju d'errore: %ASA-3-342004: Riavvia automaticamente l'Agente API REST dopu à 5 tentativi falluti. Aduprate i cumandamenti "senza agent rest-api" è "agent rest-api" per riavvia manualmente l'Agente.
- Spiegazione: L'Agente API REST ùn hà micca riesciutu à inizià dopu parechji tentativi.
- Azzione consigliata: Vede syslog %ASA-3-342002 (se registratu) per capisce megliu u mutivu di u fallimentu. Pruvate di disattivà l'Agente API REST inserendu u cumandamentu di l'agente senza rest-api è riattivate l'Agente API REST utilizendu u cumandamentu di l'agente rest-api.

Documentazione Relativa

Aduprate u ligame seguente per truvà più infurmazione nantu à l'ASA, è a so cunfigurazione è a gestione:

Navigazione in a documentazione di a serie Cisco ASA: http://www.cisco.com/go/asadocs
Aduprate u ligame seguente per view una lista di funzioni ASA chì ùn sò micca supportate nantu à l'ASAv: http://www.cisco.com/c/en/us/td/docs/security/asa/asa92/configuration/general/asa-general-cli/introasav.html#pgfId-1156883

Stu documentu deve esse usatu in cunghjunzione cù i ducumenti dispunibuli da a sezione "Documentazione Relativa".
Cisco è u logu Cisco sò marchi o marchi registrati di Cisco è/o i so affiliati in i Stati Uniti è in altri paesi. À view una lista di marchi Cisco, andate à questu URL: www.cisco.com/go/trademarks. I marchi di terze parti citati sò a pruprietà di i so rispettivi pruprietarii. L'usu di a parolla partner ùn implica micca una relazione di partenariatu trà Cisco è qualsiasi altra cumpagnia. (1721R)
Ogni indirizzi di Protocol Internet (IP) è numeri di telefunu utilizati in stu documentu ùn sò micca destinati à esse indirizzi è numeri di telefunu reali. Ogni examples, l'output di visualizazione di cumandamenti, i diagrammi di topologia di a rete, è altre figure incluse in u documentu sò mostrati solu per scopi illustrativi.
Ogni usu di l'indirizzi IP attuali o numeri di telefunu in u cuntenutu illustratu ùn hè micca intenzionale è coincidente.

Cisco Systems, Inc.

www.cisco.com

Documenti / Risorse

CISCO ASA REST API App [pdfGuida di l'utente
ASA REST API App, ASA, REST API App, API App, App

Referenze

Manuale d'usu