CISCO ASA REST API App Uzantgvidilo

Enhavo kaŝi

1 CISCO ASA REST API App

2 Produkto Uzanta Instruojn

3 Finiteview

4 ASA REST API Petoj kaj Respondoj

5 Instalu kaj Agordu la Agenton kaj Klienton de ASA REST API

6 La Dokumenta Konzolo kaj Eksportado de API-Skriptoj

7 Ebligante REST-API-Elpurigadon sur la ASA

8 ASA REST API-rilataj Syslog Mesaĝoj

9 Rilata Dokumentaro

10 Dokumentoj/Rimedoj

10.1 Referencoj

CISCO ASA REST API App

Produkto Uzanta Instruojn

Finiteview

Kun la liberigo de ASA REST API de Cisco, vi nun havas alian malpezan, facile uzeblan opcion por agordi kaj administri individuajn Cisco ASA-ojn. La ASA REST API estas aplika programado-interfaco (API) bazita sur RESTful-principoj. Ĝi povas esti rapide elŝutita kaj ebligita ĉe iu ajn ASA, kie la API funkcias. Cisco Systems, Inc.

www.cisco.com

ASA REST API Petoj kaj Respondoj

Post instalo de REST-kliento en via retumilo, vi povas kontakti la specifan REST-agenton de ASA kaj uzi normajn HTTP-metodojn por aliri aktualajn agordajn informojn kaj eldoni pliajn agordajn parametrojn.

Atentu: Kiam la REST API estas ebligita sur ASA, konektoj de aliaj sekurecaj administradprotokoloj ne estas blokitaj. Ĉi tio signifas, ke aliaj uzantaj CLI, ASDM aŭ Sekureca Administranto povus ŝanĝi la ASA-agordon dum vi faras la samon.

Peto Strukturo

La ASA REST API donas al vi programan aliron al administrado de individuaj ASA-oj per Representational State Transfer (REST) API. La API permesas al eksteraj klientoj fari CRUD (Krei, Legi, Ĝisdatigi, Forigi) operaciojn sur ASA-resursoj. Ĉiuj API-petoj estas senditaj per HTTPS al la ASA, kaj respondo estas resendita.

kie la objektopropraĵoj estas:

Proprieto	Tajpu	Priskribo
mesaĝojn	Listo de Vortaroj	Listo de eraraj aŭ avertaj mesaĝoj
kodo	Ŝnuro	Detala mesaĝo responda al Eraro/Averto/Informo
detaloj	Ŝnuro	Detala mesaĝo responda al Eraro/Averto/Informo

Notu: Ŝanĝoj faritaj de REST API-vokoj ne estas daŭraj al la starta agordo sed estas asignitaj nur al la funkcianta agordo. Por konservi ŝanĝojn al la starta agordo, vi povas uzi la peton POST a skribi mem API. Por pliaj informoj, raportu al la enskribo Write Memory API en la enhavtabelo Pri la ASA REST API.

Instalu kaj Agordu la Agenton kaj Klienton de ASA REST API

Notu: La REST API Agento estas Java-bazita aplikaĵo. La Java Runtime Environment (JRE) estas kunmetita en la pakaĵo de REST API Agent.

Finiteview

Pluraj opcioj disponeblas por agordi kaj administri individuajn Cisco ASA-ojn:

Komandlinia Interfaco (CLI) - vi sendas kontrolkomandojn rekte al la ASA per konektita konzolo.

Adaptive Security Device Manager (ASDM) - "sur-skatola" administra aplikaĵo kun grafika uzantinterfaco, kiun vi povas uzi por agordi, administri kaj monitori ASA.
Cisco Security Manager - kvankam destinite por mezaj ĝis grandaj retoj de multaj sekurecaj aparatoj, ĉi tiu grafika aplikaĵo povas esti uzata por agordi, administri kaj monitori individuajn ASAojn.

Kun la liberigo de ASA REST API de Cisco, vi nun havas alian malpezan, facile uzeblan opcion. Ĉi tio estas aplikaĵo-programa interfaco (API), bazita sur "RESTful" principoj, kiun vi povas rapide elŝuti kaj ebligi sur iu ajn ASA sur kiu la API funkcias.

ASA REST API Petoj kaj Respondoj

La ASA REST API donas al vi programan aliron al administrado de individuaj ASA-oj per Representational State Transfer (REST) API. La API permesas eksterajn klientojn fari CRUD (Krei, Legi, Ĝisdatigi, Forigi) operacioj sur ASA-resursoj; ĝi baziĝas sur la HTTPS-protokolo kaj REST-metodaro. Ĉiuj API-petoj estas senditaj per HTTPS al la ASA, kaj respondo estas resendita. Ĉi tiu sekcio provizas superview pri kiel petoj estas strukturitaj, kaj la atendataj respondoj,

Peto Strukturo

Disponeblaj petaj metodoj estas:

GET - Prenas datumojn de la specifita objekto.
PUT - Aldonas la provizitajn informojn al la specifita objekto; resendas eraron 404 Resource Not Found se la objekto ne ekzistas.

POST - Kreas la objekton kun la provizitaj informoj.
DELETE - Forigas la specifitan objekton.

PATCH - Aplikas partajn modifojn al la specifita objekto.

Responda Strukturo

Ĉiu peto produktas HTTPS-respondon de la ASA kun la normaj titoloj, respondenhavo kaj statuskodo.

La respondstrukturo povas esti:

LOKO - Novkreita rimeda ID; por POST nur—tenas la novan rimedan ID (kiel URI-reprezenton).
ENHAVO-TIPO - Media tipo priskribanta la respondmesaĝon korpon; priskribas la reprezentadon kaj sintakson de la respondmesaĝokorpo.

Ĉiu respondo inkluzivas HTTP-statuson aŭ erarkodon. Disponeblaj kodoj apartenas al ĉi tiuj kategorioj:

20x - Ducenta seriokodo indikas sukcesan operacion, inkluzive de:
- 200 OK - Norma respondo por sukcesaj petoj.
- 201 Kreita - Peto kompletigita; nova rimedo kreita.
- 202 Akceptita – Peto akceptita, sed prilaborado ne finiĝis.
- 204 Neniu enhavo – Servilo sukcese procesis peton; neniu enhavo estas resendita.
4xx - Kvarcent seriokodo indikas klientflankan eraron, inkluzive de:
- 400 Malbona Peto - Nevalidaj demandaj parametroj, inkluzive de nerekonitaj parametroj, mankantaj parametroj aŭ nevalidaj valoroj.
- 404 Ne Trovita - La provizita URL ne kongruas kun ekzistanta rimedo. Por ekzample, HTTP DELETE povas malsukcesi ĉar la rimedo ne estas disponebla.
- 405 Metodo ne Permesita - HTTP-peto estis prezentita, kiu ne estas permesita sur la rimedo; por ekzample, POST sur nurlegebla rimedo.
5xx - Kvin-cent-seria kodo indikas servilflankan eraron.

Kaze de eraro, krom la erarkodo, la resendo respondo povas inkluzivi erarobjekton enhavantan pli da detaloj pri la eraro. La JSON-erara/averta respondskemo estas jena:

kie la objektopropraĵoj estas:

Proprieto	Tajpu	Priskribo
mesaĝojn	Listo de Vortaroj	Listo de eraraj aŭ avertaj mesaĝoj
kodo	Ŝnuro	Eraro/Averto/Informkodo
detaloj	Ŝnuro	Detala mesaĝo responda al Eraro/Averto/Informo

Notu: Ŝanĝoj al la ASA-agordo farita per REST API-vokoj ne estas persistitaj al la starta agordo; tio estas, ŝanĝoj estas atribuitaj nur al la kuranta agordo. Por konservi ŝanĝojn al la starta agordo, vi povas AFIŝi peton de writemem API; por pliaj informoj, sekvu la eniron "Write Memory API" en la enhavtabelo Pri la ASA REST API.

Instalu kaj Agordu la Agenton kaj Klienton de ASA REST API

La REST API Agento estas publikigita individue kun aliaj ASA-bildoj cisco.com. Por fizikaj ASAoj, la REST API-pakaĵo devas esti elŝutita al la fulmo de la aparato kaj instalita per la komando "rest-api image". La REST API Agento tiam estas ebligita per la komando "rest-api agent".
Kun virtuala ASA (ASAv), la REST API-bildo devas esti elŝutita al la sekcio "boot:". Vi tiam devas elsendi la komandon "rest-api image", sekvitan de la komando "rest-api agent", por aliri kaj ebligi la REST-API-Agenteton.
Por informoj pri REST API-programaro kaj aparataro postuloj kaj kongruo, vidu la Cisco ASA-Kongruo-matrico.

Vi povas elŝuti la taŭgan REST API-pakaĵon por via ASA aŭ ASAv de software.cisco.com/download/home. Trovu la specifan modelon de Adaptive Security Appliances (ASA) kaj tiam elektu Adaptive Security Appliance REST API Plugin.

Notu: La REST API Agento estas Java-bazita aplikaĵo. La Java Runtime Environment (JRE) estas kunmetita en la pakaĵo de REST API Agent.

Gvidlinioj pri Uzado

Grava Vi devas inkluzivi la kaplinion Uzanto-Agente: REST API Agento en ĉiuj API-vokoj kaj ekzistantaj skriptoj. Uzu -H 'Uzanto-Agente: REST API Agento' por la CURL komando. En plurkunteksta reĝimo, la komandoj de REST API Agent disponeblas nur en la Sistema kunteksto.

Maksimuma Subtenita Agorda Grandeco

La ASA Rest API estas "surŝipa" aplikaĵo funkcianta ene de la fizika ASA, kaj kiel tia havas limigon pri la memoro asignita al ĝi. Maksimuma subtenata funkcia agorda grandeco pliiĝis dum la eldonciklo al proksimume 2 MB sur lastatempaj platformoj kiel ekzemple la 5555 kaj 5585. La ASA Rest API ankaŭ havas memorlimojn sur la virtualaj ASA-platformoj. Totala memoro sur la ASAv5 povas esti 1.5 GB, dum sur la ASAv10 ĝi estas 2 GB. La Rest API-limoj estas 450 KB kaj 500 KB por la ASAv5 kaj ASAv10, respektive.

Tial, konsciu, ke grandaj kurantaj agordoj povas produkti esceptojn en diversaj memor-intensaj situacioj kiel granda nombro da samtempaj petoj aŭ grandaj petaj volumoj. En ĉi tiuj situacioj, Rest API GET/PUT/POST-vokoj povas komenci malsukcesi kun 500 - Internal Server Error-mesaĝoj, kaj la Rest API Agento rekomencos aŭtomate ĉiufoje. La solvoj al ĉi tiu situacio estas aŭ moviĝi al pli alta memoro ASA/FPR aŭ ASAV-platformoj, aŭ redukti la grandecon de la kuranta agordo.

Elŝutu kaj Instalu la REST-API-Agenteton

Uzante la CLI, sekvu ĉi tiujn paŝojn por elŝuti kaj instali la ASA REST API-agenton sur specifa ASA:

Paŝo 1: Sur la dezirata ASA, eldonu la kopion disk0: komando por elŝuti la nunan ASA REST API-pakaĵon de cisco.com al la fulmmemoro de la ASA.
- Por ekzample: kopiu tftp://10.7.0.80/asa-restapi-111-lfbff-k8.SPA disk0:
Paŝo 2: Eldonu la rest-api-bildan disk0:/ komando por kontroli kaj instali la pakaĵon.
- Por ekzample: rest-api bildo disk0:/asa-restapi-111-lfbff-k8.SPA

La instalilo faros kongruecon kaj validigajn kontrolojn, kaj poste instalos la pakaĵon. La ASA ne rekomencos.

Ebligu la REST-API-Agenton

Sekvu ĉi tiujn paŝojn por ebligi la ASA REST API Agenton sur specifa ASA:

Paŝo 1: Certigu, ke la ĝusta programara bildo estas instalita sur la ASA.
- Konsultu la sekcion de REST API de la ASA-Kongrua Matrico (https://www.cisco.com/c/en/us/td/docs/security/asa/compatibility/asamatrx.html#pgfId-131643) por determini kiu ASA-bildo estas postulata.

Paŝo 2: Uzante la CLI, certigu, ke la HTTP-servilo estas ebligita sur la ASA, kaj ke API-klientoj povas konektiĝi al la administrada interfaco.
- Por ekzample: ebligu http-servilon
- http 0.0.0.0 0.0.0.0

Paŝo 3: Uzante la CLI, difinu HTTP-aŭtentikigon por la API-konektoj. Por ekzample: aaa aŭtentigo http konzolo LOKA
Paŝo 4: Uzante la CLI, kreu senmovan itineron sur la ASA por API-trafiko. Por ekzample: vojo 0.0.0.0 0.0.0.0 1
Paŝo 5: Uzante la CLI, ebligu la ASA REST API Agenton sur la ASA. Por ekzample: rest-api agento

REST API-Aŭtentikigo

Estas du manieroj aŭtentikigi: Baza HTTP-aŭtentikigo, kiu pasas uzantnomon kaj pasvorton en ĉiu peto, aŭ Token-bazita aŭtentikigado kun sekura HTTPS-transporto, kiu pasas antaŭe kreitan ĵetonon kun ĉiu peto. Ĉiuokaze, aŭtentikigo estos farita por ĉiu peto. Vidu la sekcion, "Token_Authentication_API" en la gvidilo Pri la ASA REST API v7.14(x) por pliaj informoj pri Token-bazita aŭtentigo.

Notu: Uzo de atestiloj eldonitaj de Atestila Aŭtoritato (CA) estas rekomendita ĉe ASA, do REST API-klientoj povas validigi la ASA-servilatestilojn dum establado de SSL-konektoj.

Komanda Rajtigo

Se komanda rajtigo estas agordita por uzi eksteran AAA-servilon (ekzample, aaa rajtigo komando ), tiam uzanto nomita enable_1 devas ekzisti sur tiu servilo kun plenaj komandprivilegioj. Se komanda rajtigo estas agordita por uzi la LOKAN datumbazon de ASA (aaa rajtiga komando LOKA), tiam ĉiuj REST API-uzantoj devas esti registritaj en la LOKA datumbazo kun privilegiaj niveloj konvenaj por siaj roloj:

Privilegia nivelo 3 aŭ pli alta estas postulata por alvoki monitorajn petojn.

Privilegia nivelo 5 aŭ pli alta estas postulata por alvoki GET-petojn.
Privilegia nivelo 15 estas necesa por alvoki operaciojn PUT/POST/DELETE.

Agordu Vian REST-API-Klienton

Sekvu ĉi tiujn paŝojn por instali kaj agordi REST-API-klienton en via loka gastiga retumilo:

Paŝo 1: Akiru kaj instalu REST-API-klienton por via retumilo.
- Por Chrome, instalu la REST-klienton de Google. Por Firefox, instalu la aldonaĵon RESTClient. Interreta Esplorilo ne estas subtenata.

Paŝo 2: Komencu la sekvan peton per via retumilo: https: /api/objects/networkobjects
- Se vi ricevas ne-eraran respondon, vi atingis la REST-API-agenton funkciantan sur la ASA.
- Se vi havas problemojn kun la agentpeto, vi povas ebligi montradon de sencimigaj informoj sur la CLI-konzolo, kiel priskribite en Ebligo de REST API-Elpurigado sur la ASA.

Paŝo 3: Laŭvole, vi povas testi vian konekton al la ASA farante POST-operacion.

Por ekzample: Provizu bazajn rajtigajn akreditaĵojn ( ), aŭ aŭtentikigĵetono (vidu Token Authentication por pliaj informoj).

Cel-peta adreso: https://<asa management ipaddress>/api/objects/networkobjects

Tipo de korpenhavo: aplikaĵo/json

Kruda korpo de la operacio:

Vi nun povas uzi la ASA REST API por agordi kaj kontroli la ASA. Referu la API-dokumentadon por alvokaj priskriboj kaj ekzamples.

Pri Plene Restarigo de Rezerva Agordo

Restarigi plenan rezervan agordon sur la ASA uzante la REST API reŝargos la ASA. Por eviti tion, uzu la sekvan komandon por restarigi rezervan agordon:

{
- "komandoj":["kopiu /nokonfirm disk0:/filenomo> running-config"]
}
- Kiefilename> estas backup.cfg aŭ kia ajn nomo vi uzis dum sekurkopio de la agordo.

La Dokumenta Konzolo kaj Eksportado de API-Skriptoj

Vi ankaŭ povas uzi la interreta dokumentado-konzolo de REST API (referita kiel la "Doc UI"), disponebla ĉe gastiganto:port/doc/ kiel "sandbox" por lerni kaj provi la API-vokojn rekte sur la ASA. Plue, vi povas uzi la butonon Eksporta Operacio en la Doc UI por konservi la montritan metodon ekzample kiel JavaScript, Python aŭ Perl-skripto file al via loka gastiganto. Vi povas tiam apliki ĉi tiun skripton al via ASA, kaj redakti ĝin por aplikiĝo sur aliaj ASA-oj kaj aliaj retaj aparatoj. Ĉi tio signifis ĉefe kiel eduka kaj startiga ilo.

JavaScript

Uzante JavaScript file postulas instaladon de node.js, kiu troviĝas ĉe http://nodejs.org/.
Uzante node.js, vi povas ekzekuti JavaScript file, kutime skribita por retumilo, kiel komandlinia skripto. Simple sekvu la instalajn instrukciojn, kaj poste rulu vian skripton per nodo script.js.

Python

La Python-skriptoj postulas, ke vi instalu Python, disponeblan de https://www.python.org/.
Post kiam vi instalis Python, vi povas ruli vian skripton per python script.py uzantnomo pasvorto.

Perl

Uzado de la Perl-skriptoj postulas iom da plia agordo—vi bezonas kvin komponantojn: Perl mem, kaj kvar Perl-bibliotekoj:

Perl-pakaĵo, trovita ĉe http://www.perl.org/
Pakaĵo::CPAN, trovita ĉe http://search.cpan.org/~andk/Bundle-CPAN-1.861/CPAN.pm

RIPOZO::Kliento, trovita ĉe http://search.cpan.org/~mcrawfor/REST-Client-88/lib/REST/Client.pm
MIME::Base64, trovita ĉe http://perldoc.perl.org/MIME/Base64.html
JSON, trovita ĉe http://search.cpan.org/~makamaka/JSON-2.90/lib/JSON.pm

Jen eksampdosiero de ekfunkciigo de Perl sur Makintoŝo:

$ sudo perl -MCPAN e shell
cpan> instali pakaĵon::CPAN

cpan> instalu REST:: Kliento
cpan> instalu MIME::Bazo64
cpan> instali JSON

Post instalo de la dependecoj, vi povas ruli vian skripton per perl script.pl uzantnomo pasvorto.

Ebligante REST-API-Elpurigadon sur la ASA

Se vi havas problemojn por agordi aŭ konektiĝi al la REST API ĉe la ASA, vi povas uzi la jenan CLI-komandon por ebligi montradon de sencimigaj mesaĝoj en via konzolo. Uzu la neniun formon de la komando por malŝalti la sencimigajn mesaĝojn.
sencimigi rest-api [agento | cli | kliento | demono | procezo | token-auth] [eraro | evento] no debug rest-api

Sintakso Priskribo

agento: (Laŭvola) Ebligu informojn pri elpurigado de REST API Agent.
cli: (Laŭvola) Ebligu sencimigajn mesaĝojn por REST API CLI Daemon-to-Agent-komunikadoj.
kliento: (Laŭvola) Ebligu sencimigan informon por Mesaĝ-vojigo inter la REST API-Kliento kaj la REST API-Agente.

demono: (Laŭvola) Ebligu sencimigajn mesaĝojn por komunikadoj de Daemon-al-Agent de REST API.
procezo: (Laŭvola) Ebligu REST API Agent-procezon komenci/ĉesigi sencimigan informon.
token-auth: (Laŭvola) REST-API-ĵeton-aŭtentikig-informoj pri sencimigo.

eraro: (Laŭvola) Uzu ĉi tiun ŝlosilvorton por limigi sencimigajn mesaĝojn al nur eraroj registritaj de la API.
evento: (Laŭvola) Uzu ĉi tiun ŝlosilvorton por limigi sencimigajn mesaĝojn al nur eventoj registritaj de la API.

Gvidlinioj pri Uzado

Se vi ne provizas specifan komponan ŝlosilvorton (t.e., se vi simple eldonas la komandon debug rest-api), sencimigaj mesaĝoj estas montrataj por ĉiuj komponentaj tipoj. Se vi ne provizas nek la eventon aŭ eraran ŝlosilvorton, ambaŭ eventoj kaj erarmesaĝoj estas montrataj por la specifita komponanto. Por ekzample, debug rest-api daemon-okazaĵo montros nur evento-sencimigajn mesaĝojn por API Daemon-to-Agent-komunikadoj.

Rilataj Komandoj

Komando/Priskribo

sencimigi HTTP; Uzu ĉi tiun komandon por view detalaj informoj pri HTTP-trafiko.

ASA REST API-rilataj Syslog Mesaĝoj

La ASA REST API-rilataj sistemregistraj mesaĝoj estas priskribitaj en ĉi tiu sekcio.

342001

Erara Mesaĝo: %ASA-7-342001: REST API Agento sukcese komenciĝis.
- Klarigo: La REST API-Agente devas esti sukcese komencita antaŭ ol REST API-Kliento povas agordi la ASA.
- Rekomendita Ago: Neniu.

342002

Erara Mesaĝo: %ASA-3-342002: REST API Agento malsukcesis, kialo: kialo
- Klarigo: La REST API Agento povus malsukcesi komenci aŭ kraŝi pro diversaj kialoj, kaj la kialo estas specifita.
- kialo—La kaŭzo de la malsukceso de REST API

Rekomendita Ago: La agoj faritaj por solvi la problemon varias depende de la kialo ensalutinta. Por ekzample, la REST API Agento kraŝas kiam la Java procezo elĉerpigas memoron. Se ĉi tio okazas, vi devas rekomenci la REST-API-Agenton. Se la rekomenco ne sukcesas, kontaktu la Cisco TAC por identigi la radikan kaŭzon solvon.

342003

Erara Mesaĝo: %ASA-3-342003: REST API Agento fiasko sciigo ricevita. Agento estos rekomencita aŭtomate.
- Klarigo: Malsukcesa sciigo de la REST API Agento estis ricevita kaj rekomenco de la Agento estas provata.
- Rekomendita Ago: Neniu.

342004

Erara Mesaĝo: %ASA-3-342004: Malsukcesis aŭtomate rekomenci la REST-API-Agenton post 5 malsukcesaj provoj. Uzu la komandojn 'ne rest-api agent' kaj 'rest-api agent' por permane rekomenci la Agenton.
- Klarigo: La REST API Agento malsukcesis komenci post multaj provoj.
- Rekomendita Ago: Vidu syslog %ASA-3-342002 (se ensalutinta) por pli bone kompreni la kialon de la malsukceso. Provu malŝalti la REST-API-Agenton per enigo de la komando de no rest-api agento kaj reŝalti la REST-API-Agenton per la komando de rest-api-agento.

Rilata Dokumentaro

Uzu la sekvan ligon por trovi pliajn informojn pri la ASA, kaj ĝia agordo kaj administrado:

Navigante la Cisco ASA Series Dokumentojn: http://www.cisco.com/go/asadocs
Uzu la sekvan ligilon al view listo de ASA-ecoj ne subtenataj sur la ASAv: http://www.cisco.com/c/en/us/td/docs/security/asa/asa92/configuration/general/asa-general-cli/introasav.html#pgfId-1156883

Ĉi tiu dokumento estas uzota kune kun la dokumentoj haveblaj de la sekcio "Rilata Dokumentado".
Cisco kaj la Cisco-emblemo estas varmarkoj aŭ registritaj varmarkoj de Cisco kaj/aŭ ĝiaj filioj en Usono kaj aliaj landoj. Al view listo de Cisco-varmarkoj, iru al ĉi tio URL: www.cisco.com/go/trademarks. Triaj varmarkoj menciitaj estas la posedaĵo de siaj respektivaj posedantoj. La uzo de la vorto partnero ne implicas partneran rilaton inter Cisco kaj iu ajn alia kompanio. (1721R)
Ajnaj adresoj kaj telefonnumeroj de Interreta Protokolo (IP) uzataj en ĉi tiu dokumento ne intencas esti realaj adresoj kaj telefonnumeroj. Ajna eksamples, komanda montra eligo, retaj topologiaj diagramoj kaj aliaj figuroj inkluzivitaj en la dokumento estas montritaj nur por ilustraj celoj.
Ĉiu uzo de realaj IP-adresoj aŭ telefonnumeroj en ilustra enhavo estas neintencita kaj hazarda.

Cisco Systems, Inc.

www.cisco.com

Dokumentoj/Rimedoj

CISCO ASA REST API App [pdf] Uzantogvidilo
ASA REST API App, ASA, REST API App, API App, App

Referencoj

Uzanto Manlibro