CISCO ASA REST API rakendus

Toote kasutamise juhised

Läbiview

Cisco ASA REST API väljalaskmisega on teil nüüd veel üks kerge ja hõlpsasti kasutatav valik üksikute Cisco ASA-de konfigureerimiseks ja haldamiseks. ASA REST API on rakenduste programmeerimisliides (API), mis põhineb RESTfuli põhimõtetel. Selle saab kiiresti alla laadida ja lubada mis tahes ASA-s, kus API töötab. Cisco Systems, Inc.

www.cisco.com

ASA REST API taotlused ja vastused

Pärast REST-kliendi installimist oma brauserisse saate võtta ühendust konkreetse ASA REST-agendiga ja kasutada standardseid HTTP-meetodeid, et pääseda juurde praegusele konfiguratsiooniteabele ja väljastada täiendavaid konfiguratsiooniparameetreid.

Ettevaatust: Kui REST API on ASA-s lubatud, ei blokeerita teiste turbehaldusprotokollide ühendusi. See tähendab, et teised kasutajad, kes kasutavad CLI-d, ASDM-i või turvahaldurit, võivad teie sama tegemise ajal ASA konfiguratsiooni muuta.

Taotluse struktuur

ASA REST API annab teile programmilise juurdepääsu üksikute ASA-de haldamiseks esindusseisundi ülekande (REST) ​​API kaudu. API võimaldab välistel klientidel teha ASA ressurssidega CRUD (loomine, lugemine, värskendamine, kustutamine) toiminguid. Kõik API päringud saadetakse HTTPS-i kaudu ASA-le ja vastus saadetakse tagasi.

kus objekti omadused on:

Kinnisvara	Tüüp	Kirjeldus
sõnumid	Sõnaraamatute loend	Veateadete või hoiatusteadete loend
kood	String	Üksikasjalik teade, mis vastab jaotisele Vea/Hoiatus/Teave
üksikasjad	String	Üksikasjalik teade, mis vastab jaotisele Vea/Hoiatus/Teave

Märkus. REST API kõnede tehtud muudatusi ei säilitata käivituskonfiguratsioonis, vaid need määratakse ainult töötavale konfiguratsioonile. Käivituskonfiguratsiooni muudatuste salvestamiseks saate kasutada kirjutusmälu API taotlust POST. Lisateabe saamiseks vaadake sisukorras Teave ASA REST API kirjet Write Memory API kirje.

Installige ja konfigureerige ASA REST API agent ja klient

Märkus. REST API agent on Java-põhine rakendus. Java Runtime Environment (JRE) on komplekteeritud REST API agendi paketis.

Läbiview

Üksikute Cisco ASA-de konfigureerimiseks ja haldamiseks on saadaval mitu võimalust.

• Command Line Interface (CLI) – saadate juhtkäsud otse ASA-le ühendatud konsooli kaudu.
• Adaptive Security Device Manager (ASDM) – graafilise kasutajaliidesega "kastis olev" haldusrakendus, mida saate kasutada ASA konfigureerimiseks, haldamiseks ja jälgimiseks.
• Cisco Security Manager – kuigi see graafiline rakendus on mõeldud paljude turvaseadmetega keskmistele ja suurtele võrkudele, saab seda kasutada üksikute ASA-de konfigureerimiseks, haldamiseks ja jälgimiseks.

Cisco ASA REST API väljalaskmisega on teil nüüd veel üks kerge ja hõlpsasti kasutatav valik. See on rakenduste programmeerimisliides (API), mis põhineb "RESTful" põhimõtetel ja mille saate kiiresti alla laadida ja lubada mis tahes ASA-s, millel API töötab.

Pärast REST-kliendi installimist brauserisse saate võtta ühendust konkreetse ASA REST-agendiga ja kasutada standardseid HTTP-meetodeid, et pääseda juurde praegusele konfiguratsiooniteabele ja väljastada täiendavaid konfiguratsiooniparameetreid.

Ettevaatust: Kui REST API on ASA-s lubatud, ei blokeerita teiste turbehaldusprotokollide ühendusi. See tähendab, et teised kasutajad, kes kasutavad CLI-d, ASDM-i või turvahaldurit, võivad teie sama tegemise ajal ASA konfiguratsiooni muuta.

ASA REST API taotlused ja vastused

ASA REST API annab teile programmilise juurdepääsu üksikute ASA-de haldamiseks esindusoleku ülekande API (REST) ​​API kaudu. API võimaldab välisklientidel teha ASA ressurssidega CRUD (Create, Read, Update, Delete) toiminguid; see põhineb HTTPS-protokollil ja REST-metoodikal. Kõik API päringud saadetakse HTTPS-i kaudu ASA-le ja vastus saadetakse tagasi. See jaotis pakub üleview päringute ülesehituse ja oodatavate vastuste kohta,

Taotluse struktuur

Saadaolevad taotlemismeetodid on:

• GET – hangib andmed määratud objektilt.
• PUT – lisab esitatud teabe määratud objektile; tagastab tõrketeate 404 Ressursi ei leitud, kui objekti pole olemas.
• POST – loob esitatud teabega objekti.
• DELETE – kustutab määratud objekti.
• PATCH – rakendab määratud objektile osalisi muudatusi.

Vastuse struktuur

• Iga päring annab ASA-lt HTTPS-i vastuse standardsete päiste, vastuse sisu ja olekukoodiga.

Vastuse struktuur võib olla järgmine:

• ASUKOHT – vastloodud ressursi ID; for only POST – sisaldab uut ressursi ID-d (URI esitusena).
• CONTENT-TYPE – vastussõnumi sisu kirjeldav meediumitüüp; kirjeldab vastusesõnumi keha esitust ja süntaksit.

Iga vastus sisaldab HTTP-olekut või veakoodi. Saadaolevad koodid jagunevad järgmistesse kategooriatesse:

• 20x – kahesaja seeria kood näitab edukat toimimist, sealhulgas:
  • 200 OK – standardvastus edukatele päringutele.
  • 201 loodud – taotlus täidetud; loodud uus ressurss.
  • 202 Aktsepteeritud – taotlus on vastu võetud, kuid töötlemine pole lõpetatud.
  • 204 Sisu puudub – serveri päring on edukalt töödeldud; sisu ei tagastata.
• 4xx – neljasaja seeria kood näitab kliendipoolset viga, sealhulgas:
  • 400 Bad Request – kehtetud päringuparameetrid, sealhulgas tundmatud parameetrid, puuduvad parameetrid või kehtetud väärtused.
  • 404 Ei leitud – pakutud URL ei ühti olemasoleva ressursiga. Näiteksample, võib HTTP DELETE ebaõnnestuda, kuna ressurss pole saadaval.
  • 405 Method Not Allowed – esitati HTTP-päring, mis pole ressursil lubatud; ntample, POST kirjutuskaitstud ressursil.
• 5xx – viiesaja seeria kood näitab serveripoolset viga.

Vea korral võib tagastusvastus lisaks veakoodile sisaldada veaobjekti, mis sisaldab vea kohta rohkem üksikasju. JSON-i vea/hoiatuse vastuse skeem on järgmine:

kus objekti omadused on:

Kinnisvara	Tüüp	Kirjeldus
sõnumid	Sõnaraamatute loend	Veateadete või hoiatusteadete loend
kood	String	Viga/hoiatus/teabekood
üksikasjad	String	Üksikasjalik teade, mis vastab jaotisele Vea/Hoiatus/Teave

Märkus. ASA konfiguratsioonis REST API kutsete poolt tehtud muudatusi ei säilitata käivituskonfiguratsioonis; see tähendab, et muudatused määratakse ainult jooksvale konfiguratsioonile. Käivituskonfiguratsiooni muudatuste salvestamiseks saate POSTITAda writemem API päringu; Lisateabe saamiseks järgige sisukorras Teave ASA REST API kohta kirjet „Write Memory API”.

Installige ja konfigureerige ASA REST API agent ja klient

• REST API agent avaldatakse eraldi koos teiste ASA piltidega cisco.com. Füüsiliste ASA-de puhul tuleb REST API pakett alla laadida seadme välkmällu ja installida käsuga "rest-api image". Seejärel lubatakse REST API agent käsuga "rest-api agent".
• Virtuaalse ASA (ASAv) korral tuleb REST API pilt alla laadida partitsioonile „boot:”. Seejärel peate REST API agendile juurdepääsuks ja lubamiseks väljastama käsu „rest-api image”, millele järgneb käsk „rest-api agent”.
• REST API tarkvara- ja riistvaranõuete ning ühilduvuse kohta teabe saamiseks vaadake Cisco ASA ühilduvusmaatriksit.
• Saate oma ASA või ASAv jaoks sobiva REST API paketi alla laadida aadressilt software.cisco.com/download/home. Otsige üles konkreetne Adaptive Security Appliance (ASA) mudel ja seejärel valige Adaptive Security Appliance REST API Plugin.

Märkus. REST API agent on Java-põhine rakendus. Java Runtime Environment (JRE) on komplekteeritud REST API agendi paketis.

Kasutusjuhised

Tähtis Peate kõikidesse API kutsetesse ja olemasolevatesse skriptidesse lisama päise User-Agent: REST API Agent. Kasutage -H 'User-Agent: REST API Agent' C jaoksURL käsk. Mitme konteksti režiimis on REST API agendi käsud saadaval ainult süsteemi kontekstis.

Maksimaalne toetatud konfiguratsiooni suurus

ASA Rest API on pardal olev rakendus, mis töötab füüsilises ASA-s ja seetõttu on sellele eraldatud mälu piirang. Maksimaalne toetatud jooksva konfiguratsiooni suurus on väljalasketsükli jooksul suurenenud umbes 2 MB-ni viimastel platvormidel, nagu 5555 ja 5585. ASA Rest API-l on ka virtuaalsetel ASA platvormidel mälupiirangud. ASAv5 kogumälu võib olla 1.5 GB, ASAv10 puhul aga 2 GB. Rest API piirangud on ASAv450 ja ASAv500 puhul vastavalt 5 KB ja 10 KB.

Seetõttu pidage meeles, et suured töötavad konfiguratsioonid võivad tekitada erandeid erinevates mälumahukates olukordades, nagu suur hulk samaaegseid päringuid või suured päringumahud. Sellistes olukordades võivad Rest API GET/PUT/POST kõned ebaõnnestuda 500 – sisemise serveri veateadetega ja Rest API agent taaskäivitub iga kord automaatselt. Selle olukorra lahendused on kas liikuda suurema mälumahuga ASA/FPR või ASAV platvormidele või vähendada töötava konfiguratsiooni suurust.

Laadige alla ja installige REST API agent

CLI-d kasutades järgige neid samme, et laadida alla ja installida ASA REST API agent konkreetsele ASA-le.

• 1. samm: Väljastage soovitud ASA koopia disk0: käsk praeguse ASA REST API paketi allalaadimiseks cisco.com ASA välkmällu.
  • Näiteksample: kopeeri tftp://10.7.0.80/asa-restapi-111-lfbff-k8.SPA disk0:
• 2. samm: Väljasta rest-api kujutise disk0:/ käsk paketi kontrollimiseks ja installimiseks.
  • Näiteksample: rest-api kujutise disk0:/asa-restapi-111-lfbff-k8.SPA

Installer teostab ühilduvus- ja valideerimiskontrollid ning seejärel installib paketi. ASA ei taaskäivitu.

Lubage REST API agent

ASA REST API agendi lubamiseks konkreetsel ASA-l järgige neid samme.

• 1. samm: Veenduge, et ASA-sse oleks installitud õige tarkvara kujutis.
  • Tutvuge ASA ühilduvusmaatriksi REST API jaotisega (https://www.cisco.com/c/en/us/td/docs/security/asa/compatibility/asamatrx.html#pgfId-131643), et määrata, millist ASA-pilti on vaja.
• 2. samm: CLI-d kasutades veenduge, et HTTP-server oleks ASA-s lubatud ja et API kliendid saaksid luua ühenduse haldusliidesega.
  • Näiteksample: http-serveri lubamine
  • http 0.0.0.0 0.0.0.0
• 3. samm: Määrake API ühenduste jaoks HTTP autentimine CLI abil. Näiteksample: aaa autentimine http konsool LOCAL
• 4. samm: Kasutades CLI-d, looge ASA-s API liikluse jaoks staatiline marsruut. Näiteksample: marsruut 0.0.0.0 0.0.0.0 1
• 5. samm: CLI-d kasutades lubage ASA-s ASA REST API agent. Näiteksample: rest-api agent

REST API autentimine

Autentimiseks on kaks võimalust: põhiline HTTP-autentimine, mis edastab igas päringus kasutajanime ja parooli, või Tokenipõhine autentimine turvalise HTTPS-i transpordiga, mis edastab iga päringuga eelnevalt loodud loa. Mõlemal juhul teostatakse iga päringu puhul autentimine. Tokenipõhise autentimise kohta lisateabe saamiseks vaadake jaotist „Token_Authentication_API” juhendis Teave ASA REST API v7.14(x) kohta.

Märkus. ASA-s on soovitatav kasutada sertifitseerimisasutuse (CA) väljastatud sertifikaate, et REST API kliendid saaksid SSL-ühenduste loomisel ASA serveri sertifikaate kinnitada.

Käskude autoriseerimine

Kui käsu autoriseerimine on konfigureeritud kasutama välist AAA-serverit (ntample, aaa autoriseerimiskäsk ), siis peab selles serveris olema täielike käsuõigustega kasutaja nimega enable_1. Kui käsu autoriseerimine on konfigureeritud kasutama ASA LOCAL andmebaasi (aaa autoriseerimiskäsk LOCAL), peavad kõik REST API kasutajad olema registreeritud LOCAL andmebaasis nende rollidele sobivate privileegide tasemetega:

• Järelevalvetaotluste käivitamiseks on nõutav õigustase 3 või kõrgem.
• GET-päringute käivitamiseks on nõutav õigustase 5 või kõrgem.
• PUT/POST/DELETE operatsioonide kutsumiseks on vajalik õigustase 15.

Seadistage oma REST API klient

REST API kliendi installimiseks ja konfigureerimiseks oma kohaliku hosti brauseris järgige neid samme.

• 1. samm: Hankige ja installige oma brauseri jaoks REST API klient.
  • Chrome'i jaoks installige Google'i klient REST. Firefoxi jaoks installige lisandmoodul RESTClient. Internet Explorerit ei toetata.
• 2. samm: Esitage oma brauseri abil järgmine päring: https: /api/objektid/võrguobjektid
  • Kui saate veavaba vastuse, olete jõudnud ASA-s töötava REST API agendini.
  • Kui teil on agenditaotlusega probleeme, saate lubada silumisteabe kuvamise CLI-konsoolis, nagu on kirjeldatud jaotises REST API silumise lubamine ASA-s.
• 3. samm: Soovi korral saate testida ühendust ASA-ga, sooritades POST-toimingu.

Näiteksample: Esitage põhilised autoriseerimismandaadid ( ) või autentimisluba (lisateabe saamiseks vaadake jaotist Token Authentication).

• Taotluse sihtaadress: https://<asa management ipaddress>/api/objects/networkobjects
• Keha sisu tüüp: rakendus/json

Operatsiooni põhiosa:

Nüüd saate ASA konfigureerimiseks ja jälgimiseks kasutada ASA REST API-t. Vaadake kõnede kirjeldusi ja nt. API dokumentatsiooniampvähem.

Teave varukonfiguratsiooni täieliku taastamise kohta

ASA täieliku varukonfiguratsiooni taastamine REST API abil laadib ASA uuesti. Selle vältimiseks kasutage varukonfiguratsiooni taastamiseks järgmist käsku:

• {
  • "käsud":["copy /noconfirm disk0:/filename> running-config”]
• }
  • Kusfilenimi> on backup.cfg või mis tahes nimi, mida kasutasite konfiguratsiooni varundamiseks.

Dokumentatsioonikonsool ja API skriptide eksportimine

Samuti saate kasutada REST API siduvat dokumentatsioonikonsooli (edaspidi "Doki kasutajaliides"), mis on saadaval aadressil host:port/doc/ kui "liivakasti" API-kutsete tundmaõppimiseks ja nende proovimiseks otse ASA-s. Lisaks saate kuvatava meetodi salvestamiseks kasutada dokumendi kasutajaliidese nuppu Ekspordi toimingample JavaScripti, Pythoni või Perli skriptina file oma kohalikule hostile. Seejärel saate selle skripti oma ASA-le rakendada ja seda muudes ASA-des ja muudes võrguseadmetes kasutamiseks redigeerida. See tähendas eelkõige hariva ja alglaadimisvahendina.

JavaScript

• JavaScripti kasutamine file nõuab faili node.js installimist, mille leiate aadressilt http://nodejs.org/.
• Node.js-i abil saate käivitada JavaScripti file, mis on tavaliselt kirjutatud brauseri jaoks, nagu käsurea skript. Järgige lihtsalt installijuhiseid ja seejärel käivitage skript sõlmega script.js.

Python

• Pythoni skriptid nõuavad Pythoni installimist, mis on saadaval aadressilt https://www.python.org/.
• Kui olete Pythoni installinud, saate oma skripti käitada pythoni script.py kasutajanime parooliga.

Perl

Perli skriptide kasutamine nõuab täiendavat seadistamist – vajate viit komponenti: Perli ennast ja nelja Perli teeki:

• Perli pakett, leitud aadressil http://www.perl.org/
• Komplekt::CPAN, leitud aadressil http://search.cpan.org/~andk/Bundle-CPAN-1.861/CPAN.pm
• PUHASTA::Klient, leitud aadressil http://search.cpan.org/~mcrawfor/REST-Client-88/lib/REST/Client.pm
• MIME::Base64, leitud aadressil http://perldoc.perl.org/MIME/Base64.html
• JSON, leitud aadressil http://search.cpan.org/~makamaka/JSON-2.90/lib/JSON.pm

Siin on endineampPerli alglaadimine Macintoshis:

• $ sudo perl -MCPAN ja kest
• cpan> install Bundle::CPAN
• cpan> installige REST:: Klient
• cpan> installige MIME::Base64
• cpan> installige JSON

Pärast sõltuvuste installimist saate oma skripti käitada, kasutades perl script.pl kasutajanime parooli.

REST API silumise lubamine ASA-s

Kui teil on probleeme ASA-s REST API konfigureerimise või sellega ühenduse loomisega, saate kasutada järgmist CLI-käsku, et lubada oma konsoolil silumissõnumite kuvamine. Silumissõnumite keelamiseks kasutage käsu vormi nr.
siluda rest-api [agent | klii | klient | deemon | protsess | token-auth] [viga | sündmus] no silumise rest-api

Süntaksi kirjeldus

• agent: (Valikuline) Lubage REST API agendi silumise teave.
• kliki: (Valikuline) Lubage REST API CLI deemoni ja agendi vahelise suhtluse silumissõnumid.
• klient: (Valikuline) Lubage REST API kliendi ja REST API agendi vahelise sõnumi marsruutimise silumisteave.
• deemon: (Valikuline) Lubage REST API deemoni ja agendi vahelise suhtluse silumissõnumid.
• protsess: (Valikuline) Lubage REST API agendi protsessi silumise käivitamise/peatamise teave.
• token-auth: (Valikuline) REST API loa autentimise silumise teave.
• viga: (Valikuline) Kasutage seda märksõna silumissõnumite piiramiseks ainult API poolt logitud vigadega.
• sündmus: (Valikuline) Kasutage seda märksõna silumissõnumite piiramiseks ainult API poolt logitud sündmustega.

Kasutusjuhised

Kui te ei anna konkreetset komponendi märksõna (st kui annate lihtsalt käsu debug rest-api), kuvatakse kõigi komponenditüüpide silumissõnumid. Kui te ei esita sündmuse ega vea märksõna, kuvatakse määratud komponendi kohta nii sündmuse kui ka veateated. Näiteksample, debug rest-api deemoni sündmus näitab ainult sündmuste silumissõnumeid API deemoni ja agendi vahelise suhtluse jaoks.

Seotud käsud

Käsk/kirjeldus

• siluda HTTP-d; Kasutage seda käsku view üksikasjalik teave HTTP-liikluse kohta.

ASA REST API-ga seotud Syslogi sõnumid

Selles jaotises kirjeldatakse ASA REST API-ga seotud süsteemilogisõnumeid.

342001

• Veateade: %ASA-7-342001: REST API agent käivitati edukalt.
  • Selgitus: REST API agent peab olema edukalt käivitatud, enne kui REST API klient saab ASA konfigureerida.
  • Soovitatav toiming: Mitte ühtegi.

342002

• Veateade: %ASA-3-342002: REST API agent nurjus, põhjus: põhjus
  • Selgitus: REST API agent ei pruugi erinevatel põhjustel käivituda või jookseb kokku ja põhjus on täpsustatud.
  • põhjus – REST API tõrke põhjus

Soovitatav toiming: Probleemi lahendamiseks tehtavad toimingud sõltuvad logitud põhjusest. Näiteksample, REST API agent jookseb kokku, kui Java protsessi mälu saab otsa. Kui see juhtub, peate taaskäivitama REST API agendi. Kui taaskäivitamine ei õnnestu, võtke algpõhjuse parandamiseks ühendust Cisco TACiga.

342003

• Veateade: %ASA-3-342003: REST API agendi tõrketeade on vastu võetud. Agent taaskäivitatakse automaatselt.
  • Selgitus: REST API agendilt on vastu võetud tõrketeade ja agenti üritatakse taaskäivitada.
  • Soovitatav toiming: Mitte ühtegi.

342004

• Veateade: %ASA-3-342004: REST API agendi automaatne taaskäivitamine ebaõnnestus pärast 5 ebaõnnestunud katset. Kasutage agendi käsitsi taaskäivitamiseks käske „no rest-api agent” ja „rest-api agent”.
  • Selgitus: REST API agendil ei õnnestunud pärast mitmeid katseid käivituda.
  • Soovitatav toiming: Rikke põhjuse paremaks mõistmiseks vaadake syslogi %ASA-3-342002 (kui see on sisse logitud). Proovige keelata REST API agent, sisestades käsu no rest-api agent, ja lubage REST API agent uuesti käsuga rest-api agent.

Seotud dokumentatsioon

Kasutage järgmist linki, et leida lisateavet ASA ning selle konfiguratsiooni ja halduse kohta.

• Cisco ASA seeria dokumentatsioonis navigeerimine: http://www.cisco.com/go/asadocs
• Kasutage järgmist linki view ASA funktsioonide loend, mida ASAv ei toeta: http://www.cisco.com/c/en/us/td/docs/security/asa/asa92/configuration/general/asa-general-cli/introasav.html#pgfId-1156883

Seda dokumenti tuleb kasutada koos dokumentidega, mis on saadaval jaotises „Seotud dokumentatsioon”.
Cisco ja Cisco logo on Cisco ja/või tema sidusettevõtete kaubamärgid või registreeritud kaubamärgid USA-s ja teistes riikides. To view Cisco kaubamärkide loend, avage see URL: www.cisco.com/go/trademarks. Mainitud kolmandate isikute kaubamärgid on nende vastavate omanike omand. Sõna partner kasutamine ei tähenda partnerlussuhet Cisco ja ühegi teise ettevõtte vahel. (1721R)
Käesolevas dokumendis kasutatud Interneti-protokolli (IP) aadressid ja telefoninumbrid ei ole mõeldud tegelikeks aadressideks ja telefoninumbriteks. Igasugune eksamples, käsu kuva väljund, võrgu topoloogia diagrammid ja muud dokumendis sisalduvad joonised on näidatud ainult illustratiivsel eesmärgil.
Tegelike IP-aadresside või telefoninumbrite kasutamine illustratiivses sisus on tahtmatu ja juhuslik.

Cisco Systems, Inc.

• www.cisco.com

© 2014–2018 Cisco Systems, Inc. Kõik õigused kaitstud.

Dokumendid / Ressursid

CISCO ASA REST API rakendus [pdfKasutusjuhend ASA REST API rakendus, ASA, REST API rakendus, API rakendus, rakendus

Viited

• Kasutusjuhend