Aplikacija CISCO ASA REST API

Navodila za uporabo izdelka

konecview

Z izdajo API-ja Cisco ASA REST imate zdaj še eno lahko možnost, ki je enostavna za uporabo, za konfiguriranje in upravljanje posameznih Cisco ASA. ASA REST API je aplikacijski programski vmesnik (API), ki temelji na načelih RESTful. Lahko ga hitro prenesete in omogočite na katerem koli ASA, kjer se izvaja API. Cisco Systems, Inc.

www.cisco.com

Zahteve in odgovori ASA REST API

Po namestitvi odjemalca REST v vaš brskalnik se lahko obrnete na agenta REST določenega ASA in uporabite standardne metode HTTP za dostop do trenutnih konfiguracijskih informacij in izdajanje dodatnih konfiguracijskih parametrov.

Pozor: Ko je REST API omogočen na ASA, povezave drugih protokolov za upravljanje varnosti niso blokirane. To pomeni, da lahko drugi, ki uporabljajo CLI, ASDM ali Security Manager, spreminjajo konfiguracijo ASA, medtem ko vi počnete isto.

Struktura zahteve

API ASA REST vam omogoča programski dostop do upravljanja posameznih ASA prek API-ja za prenos reprezentativnega stanja (REST). API omogoča zunanjim odjemalcem izvajanje operacij CRUD (ustvari, preberi, posodobi, izbriši) na virih ASA. Vse zahteve API-ja so poslane prek HTTPS v ASA in vrnjen je odgovor.

kjer so lastnosti predmeta:

Lastnina	Vrsta	Opis
sporočila	Seznam slovarjev	Seznam sporočil o napakah ali opozorilih
kodo	Niz	Podrobno sporočilo, ki ustreza Napaka/Opozorilo/Informacije
podrobnosti	Niz	Podrobno sporočilo, ki ustreza Napaka/Opozorilo/Informacije

Opomba: Spremembe, narejene s klici API-ja REST, se ne ohranijo v zagonski konfiguraciji, ampak so dodeljene samo tekoči konfiguraciji. Če želite shraniti spremembe zagonske konfiguracije, lahko uporabite zahtevo POST a write mem API. Za več informacij glejte vnos API-ja za pisanje v pomnilnik v kazalu O API-ju ASA REST.

Namestite in konfigurirajte agenta in odjemalca ASA REST API

Opomba: Agent REST API je aplikacija, ki temelji na Javi. Java Runtime Environment (JRE) je vključeno v paket REST API Agent.

konecview

Na voljo je več možnosti za konfiguriranje in upravljanje posameznih Cisco ASA:

• Vmesnik ukazne vrstice (CLI) – upravljalne ukaze pošiljate neposredno v ASA prek povezane konzole.
• Adaptive Security Device Manager (ASDM) – aplikacija za upravljanje "on-box" z grafičnim uporabniškim vmesnikom, ki jo lahko uporabite za konfiguracijo, upravljanje in spremljanje ASA.
• Cisco Security Manager – čeprav je namenjen srednjim do velikim omrežjem s številnimi varnostnimi napravami, je to grafično aplikacijo mogoče uporabiti za konfiguracijo, upravljanje in spremljanje posameznih ASA.

Z izdajo API-ja Cisco ASA REST imate zdaj še eno lahko možnost, ki je enostavna za uporabo. To je vmesnik za programiranje aplikacij (API), ki temelji na načelih "RESTful", ki ga lahko hitro prenesete in omogočite na katerem koli ASA, na katerem se izvaja API.

Po namestitvi odjemalca REST v vaš brskalnik se lahko obrnete na agenta REST določenega ASA in uporabite standardne metode HTTP za dostop do trenutnih konfiguracijskih informacij in izdajo dodatnih konfiguracijskih parametrov.

Pozor: Ko je REST API omogočen na ASA, povezave drugih protokolov za upravljanje varnosti niso blokirane. To pomeni, da lahko drugi, ki uporabljajo CLI, ASDM ali Security Manager, spreminjajo konfiguracijo ASA, medtem ko vi počnete isto.

Zahteve in odgovori ASA REST API

API ASA REST vam omogoča programski dostop do upravljanja posameznih ASA prek API-ja REST (Representational State Transfer). API omogoča zunanjim odjemalcem izvajanje operacij CRUD (ustvari, preberi, posodobi, izbriši) na virih ASA; temelji na protokolu HTTPS in metodologiji REST. Vse zahteve API-ja so poslane prek HTTPS v ASA in vrnjen je odgovor. Ta razdelek ponuja overview kako so zahteve strukturirane in pričakovani odgovori,

Struktura zahteve

Razpoložljivi načini zahtevka so:

• GET – Pridobi podatke iz navedenega predmeta.
• PUT – doda posredovane informacije podanemu objektu; vrne napako 404 Resource Not Found, če predmet ne obstaja.
• POST – Ustvari predmet s podanimi informacijami.
• DELETE – izbriše navedeni predmet.
• PATCH – Uporabi delne spremembe podanega predmeta.

Struktura odziva

• Vsaka zahteva ustvari odgovor HTTPS iz ASA s standardnimi glavami, vsebino odgovora in statusno kodo.

Struktura odziva je lahko:

• LOKACIJA – ID na novo ustvarjenega vira; samo za POST—vsebuje ID novega vira (kot predstavitev URI).
• CONTENT-TYPE – vrsta medija, ki opisuje telo odgovora; opisuje predstavitev in sintakso telesa odgovora.

Vsak odgovor vključuje status HTTP ali kodo napake. Razpoložljive kode spadajo v te kategorije:

• 20x – Koda serije dvesto pomeni uspešno operacijo, vključno z:
  • 200 OK – standardni odgovor za uspešne zahteve.
  • 201 Ustvarjeno – Zahteva dokončana; ustvarjen nov vir.
  • 202 Sprejeto – Zahteva sprejeta, vendar obdelava ni končana.
  • 204 Ni vsebine – strežnik je uspešno obdelal zahtevo; nobena vsebina se ne vrača.
• 4xx – Koda serije štiristo pomeni napako na strani odjemalca, vključno z:
  • 400 Napačna zahteva – Neveljavni parametri poizvedbe, vključno z neprepoznanimi parametri, manjkajočimi parametri ali neveljavnimi vrednostmi.
  • 404 Ni najdeno – podano URL se ne ujema z obstoječim virom. Na primerample, lahko HTTP DELETE ne uspe, ker vir ni na voljo.
  • 405 Metoda ni dovoljena – Predstavljena je bila zahteva HTTP, ki v viru ni dovoljena; nprample, OBJAVA na viru samo za branje.
• 5xx – Koda serije petsto pomeni napako na strani strežnika.

V primeru napake lahko povratni odgovor poleg kode napake vključuje objekt napake, ki vsebuje več podrobnosti o napaki. Shema odziva na napako/opozorilo JSON je naslednja:

kjer so lastnosti predmeta:

Lastnina	Vrsta	Opis
sporočila	Seznam slovarjev	Seznam sporočil o napakah ali opozorilih
kodo	Niz	Koda napake/opozorila/informacije
podrobnosti	Niz	Podrobno sporočilo, ki ustreza Napaka/Opozorilo/Informacije

Opomba: Spremembe konfiguracije ASA, narejene s klici API-ja REST, se ne ohranijo v konfiguraciji zagona; to pomeni, da so spremembe dodeljene samo tekoči konfiguraciji. Če želite shraniti spremembe zagonske konfiguracije, lahko OBJAVITE zahtevo API writemem; za več informacij sledite vnosu »Write Memory API« v kazalu O ASA REST API.

Namestite in konfigurirajte agenta in odjemalca ASA REST API

• Agent REST API je objavljen posamično z drugimi slikami ASA cisco.com. Za fizične ASA je treba paket REST API prenesti na bliskovni pogon naprave in namestiti z ukazom »rest-api image«. Agent REST API je nato omogočen z ukazom »rest-api agent«.
• Z virtualnim ASA (ASAv) je treba sliko REST API prenesti na particijo »boot:«. Nato morate izdati ukaz »rest-api image«, ki mu sledi ukaz »rest-api agent«, da dostopate in omogočite agenta REST API.
• Za informacije o zahtevah in združljivosti programske in strojne opreme REST API si oglejte matriko združljivosti Cisco ASA.
• Ustrezen paket REST API za vaš ASA ali ASAv lahko prenesete iz software.cisco.com/download/home. Poiščite določen model Adaptive Security Appliances (ASA) in nato izberite Adaptive Security Appliance REST API Plugin.

Opomba: Agent REST API je aplikacija, ki temelji na Javi. Java Runtime Environment (JRE) je vključeno v paket REST API Agent.

Navodila za uporabo

Pomembno V vse klice API-ja in obstoječe skripte morate vključiti glavo User-Agent: REST API Agent. Uporabite -H 'User-Agent: REST API Agent' za CURL ukaz. V večkontekstnem načinu so ukazi agenta REST API na voljo samo v sistemskem kontekstu.

Največja podprta velikost konfiguracije

ASA Rest API je "on-board" aplikacija, ki se izvaja znotraj fizičnega ASA in ima kot taka omejitev glede pomnilnika, ki ji je dodeljen. Največja podprta velikost tekoče konfiguracije se je v ciklu izdaje povečala na približno 2 MB na novejših platformah, kot sta 5555 in 5585. API ASA Rest ima tudi pomnilniške omejitve na virtualnih platformah ASA. Skupni pomnilnik na ASAv5 je lahko 1.5 GB, na ASAv10 pa 2 GB. Omejitve Rest API so 450 KB oziroma 500 KB za ASAv5 oziroma ASAv10.

Zato se zavedajte, da lahko velike tekoče konfiguracije povzročijo izjeme v različnih pomnilniško intenzivnih situacijah, kot je veliko število sočasnih zahtev ali velike količine zahtev. V teh situacijah lahko klici Rest API GET/PUT/POST začnejo odpovedovati s 500 – sporočili o notranji napaki strežnika, agent Rest API pa se bo vsakič samodejno znova zagnal. Rešitve te situacije so bodisi prehod na platforme ASA/FPR ali ASAV z večjim pomnilnikom ali zmanjšanje velikosti tekoče konfiguracije.

Prenesite in namestite agenta REST API

Z uporabo CLI sledite tem korakom za prenos in namestitev agenta ASA REST API na določen ASA:

• 1. korak: Na želenem ASA izdajte kopijo disk0: ukaz za prenos trenutnega paketa API-ja ASA REST cisco.com na bliskovni pomnilnik ASA.
  • Na primerample: kopiraj tftp://10.7.0.80/asa-restapi-111-lfbff-k8.SPA disk0:
• 2. korak: Izdajte rest-api sliko disk0:/ ukaz za preverjanje in namestitev paketa.
  • Na primerample: rest-api image disk0:/asa-restapi-111-lfbff-k8.SPA

Namestitveni program bo izvedel preverjanja združljivosti in preverjanja veljavnosti ter nato namestil paket. ASA se ne bo znova zagnal.

Omogočite agenta REST API

Sledite tem korakom, da omogočite ASA REST API Agent na določenem ASA:

• 1. korak: Zagotovite, da je na ASA nameščena pravilna slika programske opreme.
  • Oglejte si razdelek REST API v matriki združljivosti ASA (https://www.cisco.com/c/en/us/td/docs/security/asa/compatibility/asamatrx.html#pgfId-131643), da ugotovite, katera slika ASA je potrebna.
• 2. korak: Z uporabo CLI zagotovite, da je strežnik HTTP omogočen na ASA in da se odjemalci API lahko povežejo z vmesnikom za upravljanje.
  • Na primerample: http strežnik omogoči
  • http 0.0.0.0 0.0.0.0
• 3. korak: Z uporabo CLI definirajte avtentikacijo HTTP za povezave API. Na primerample: aaa avtentikacija http konzola LOKALNO
• 4. korak: Z uporabo CLI ustvarite statično pot na ASA za promet API. Na primerample: pot 0.0.0.0 0.0.0.0 1
• 5. korak: Z uporabo CLI omogočite ASA REST API Agent na ASA. Na primerample: rest-api agent

Preverjanje pristnosti REST API

Obstajata dva načina za preverjanje pristnosti: osnovno preverjanje pristnosti HTTP, ki posreduje uporabniško ime in geslo v vsaki zahtevi, ali preverjanje pristnosti na podlagi žetonov z varnim prenosom HTTPS, ki posreduje predhodno ustvarjen žeton z vsako zahtevo. V vsakem primeru bo avtentikacija izvedena za vsako zahtevo. Glejte razdelek »Token_Authentication_API« v vodniku O API-ju ASA REST v7.14(x) za dodatne informacije o preverjanju pristnosti na podlagi žetonov.

Opomba: Na ASA je priporočljiva uporaba potrdil, ki jih izda overitelj potrdil (CA), tako da lahko odjemalci REST API preverijo potrdila strežnika ASA, ko vzpostavljajo povezave SSL.

Pooblastilo ukaza

Če je avtorizacija ukazov konfigurirana za uporabo zunanjega strežnika AAA (nprample, aaa avtorizacijski ukaz ), potem mora uporabnik z imenom enable_1 obstajati na tem strežniku s polnimi ukaznimi privilegiji. Če je avtorizacija ukaza konfigurirana za uporabo LOKALNE baze podatkov ASA (aaa avtorizacijski ukaz LOCAL), morajo biti vsi uporabniki API-ja REST registrirani v LOKALNI bazi podatkov z ravnmi privilegijev, ki ustrezajo njihovim vlogam:

• Za priklic zahtev za spremljanje je potrebna raven privilegijev 3 ali višja.
• Za priklic zahtev GET je potrebna raven privilegijev 5 ali višja.
• Raven privilegijev 15 je potrebna za priklic operacij PUT/POST/DELETE.

Konfigurirajte odjemalca REST API

Za namestitev in konfiguracijo odjemalca REST API v brskalniku lokalnega gostitelja sledite tem korakom:

• 1. korak: Pridobite in namestite odjemalca REST API za vaš brskalnik.
  • Za Chrome namestite odjemalca REST iz Googla. Za Firefox namestite dodatek RESTClient. Internet Explorer ni podprt.
• 2. korak: Z brskalnikom sprožite naslednjo zahtevo: https: /api/objects/networkobjects
  • Če prejmete odgovor brez napake, ste dosegli agenta REST API, ki deluje na ASA.
  • Če imate težave z zahtevo agenta, lahko omogočite prikaz informacij o odpravljanju napak na konzoli CLI, kot je opisano v Omogočanje razhroščevanja REST API na ASA.
• 3. korak: Po želji lahko svojo povezavo z ASA preizkusite tako, da izvedete operacijo POST.

Na primerample: Navedite osnovne avtorizacijske poverilnice ( ) ali žeton za preverjanje pristnosti (za dodatne informacije glejte Preverjanje pristnosti žetona).

• Naslov ciljne zahteve: https://<asa management ipaddress>/api/objects/networkobjects
• Vrsta vsebine telesa: aplikacija/json

Surovo telo operacije:

Zdaj lahko uporabite API ASA REST za konfiguriranje in spremljanje ASA. Glejte dokumentacijo API za opise klicev in npramples.

O popolni obnovitvi varnostne kopije konfiguracije

Obnovitev celotne konfiguracije varnostne kopije na ASA z uporabo API-ja REST bo znova naložila ASA. Da bi se temu izognili, uporabite naslednji ukaz za obnovitev varnostne kopije konfiguracije:

• {
  • “ukazi”:[“kopiraj /noconfirm disk0:/filename> running-config”]
• }
  • Kjefileime> je backup.cfg ali katero koli ime, ki ste ga uporabili pri varnostnem kopiranju konfiguracije.

Konzola za dokumentacijo in izvozni skripti API-ja

Uporabite lahko tudi spletno dokumentacijsko konzolo REST API (imenovano »Doc UI«), ki je na voljo na naslovu host:port/doc/ kot »peskovnik« za učenje in preizkušanje klicev API neposredno na ASA. Poleg tega lahko uporabite gumb Export Operation v uporabniškem vmesniku dokumenta, da shranite prikazano metodo, nprample kot skript JavaScript, Python ali Perl file lokalnemu gostitelju. Ta skript lahko nato uporabite za svoj ASA in ga uredite za uporabo na drugih ASA in drugih omrežnih napravah. To je pomenilo predvsem kot izobraževalno in zagonsko orodje.

JavaScript

• Uporaba JavaScripta file zahteva namestitev node.js, ki ga najdete na http://nodejs.org/.
• Z uporabo node.js lahko izvedete JavaScript file, ki je običajno napisan za brskalnik, kot je skript ukazne vrstice. Preprosto sledite navodilom za namestitev in nato zaženite skript z vozliščem script.js.

Python

• Za skripte Python morate namestiti Python, ki je na voljo na https://www.python.org/.
• Ko namestite Python, lahko zaženete svoj skript z uporabniškim imenom python script.py geslom.

Perl

Uporaba skriptov Perl zahteva nekaj dodatnih nastavitev – potrebujete pet komponent: sam Perl in štiri knjižnice Perl:

• Paket Perl, najden na http://www.perl.org/
• Paket::CPAN, najdete na http://search.cpan.org/~andk/Bundle-CPAN-1.861/CPAN.pm
• POČITEK::Stranka, najdena na http://search.cpan.org/~mcrawfor/REST-Client-88/lib/REST/Client.pm
• MIME::Base64, najdeno na http://perldoc.perl.org/MIME/Base64.html
• JSON, najden na http://search.cpan.org/~makamaka/JSON-2.90/lib/JSON.pm

Tukaj je bivšiampdatoteka zagonskega Perla v sistemu Macintosh:

• $ sudo perl -MCPAN e lupina
• cpan> namestite paket ::CPAN
• cpan> namestite REST :: Stranka
• cpan> namestite MIME::Osnova64
• cpan> namestite JSON

Po namestitvi odvisnosti lahko zaženete svoj skript z uporabniškim imenom perl script.pl geslom.

Omogočanje odpravljanja napak REST API na ASA

Če imate težave pri konfiguriranju ali povezovanju z API-jem REST na ASA, lahko uporabite naslednji ukaz CLI, da omogočite prikaz sporočil o odpravljanju napak na vaši konzoli. Če želite onemogočiti sporočila o odpravljanju napak, uporabite ukaz no.
razhroščevanje rest-api [agent | cli | stranka | demon | proces | token-auth] [napaka | dogodek] brez odpravljanja napak rest-api

Opis sintakse

• agent: (Izbirno) Omogočite informacije o odpravljanju napak agenta REST API.
• cli: (Izbirno) Omogočite sporočila o odpravljanju napak za komunikacije REST API CLI Daemon-to-Agent.
• stranka: (Izbirno) Omogočite informacije o odpravljanju napak za usmerjanje sporočil med odjemalcem REST API in agentom REST API.
• demon: (Izbirno) Omogočite sporočila o odpravljanju napak za komunikacije REST API Daemon-to-Agent.
• postopek: (Izbirno) Omogočite informacije o zagonu/ustavitvi postopka odpravljanja napak agenta REST API.
• token-auth: (Izbirno) Informacije o odpravljanju napak pri preverjanju pristnosti API-ja REST.
• napaka: (Izbirno) S to ključno besedo omejite sporočila o odpravljanju napak samo na napake, ki jih zabeleži API.
• dogodek: (Izbirno) S to ključno besedo omejite sporočila o odpravljanju napak samo na dogodke, ki jih zabeleži API.

Navodila za uporabo

Če ne podate določene ključne besede komponente (to je, če preprosto izdate ukaz debug rest-api), so sporočila o odpravljanju napak prikazana za vse vrste komponent. Če ne podate ključne besede dogodek ali napaka, se za podano komponento prikažeta sporočila o dogodku in napaki. Na primerample, dogodek debug rest-api daemon bo prikazal samo sporočila o odpravljanju napak dogodkov za komunikacije API Daemon-to-Agent.

Povezani ukazi

Ukaz/Opis

• razhroščevanje HTTP; Uporabite ta ukaz za view podrobne informacije o prometu HTTP.

Sporočila sistemskega dnevnika, povezana z API-jem ASA REST

Sporočila sistemskega dnevnika, povezana z API-jem ASA REST, so opisana v tem razdelku.

342001

• Sporočilo o napaki: %ASA-7-342001: Agent REST API se je uspešno zagnal.
  • Pojasnilo: Agent REST API mora biti uspešno zagnan, preden lahko odjemalec REST API konfigurira ASA.
  • Priporočeno dejanje: Noben.

342002

• Sporočilo o napaki: %ASA-3-342002: Agent REST API ni uspel, razlog: razlog
  • Pojasnilo: Agent REST API se lahko ne zažene ali se zruši zaradi različnih razlogov, razlog pa je naveden.
  • razlog—vzrok za napako API-ja REST

Priporočeno dejanje: Ukrepi za rešitev težave se razlikujejo glede na prijavljeni razlog. Na primerample, se agent REST API zruši, ko procesu Java zmanjka pomnilnika. Če se to zgodi, morate znova zagnati agenta REST API. Če ponovni zagon ni uspešen, se obrnite na Cisco TAC, da ugotovite vzrok popravka.

342003

• Sporočilo o napaki: %ASA-3-342003: Prejeto obvestilo o napaki agenta REST API. Agent se bo samodejno znova zagnal.
  • Pojasnilo: Prejeto je bilo obvestilo o napaki agenta REST API in izvaja se poskus ponovnega zagona agenta.
  • Priporočeno dejanje: Noben.

342004

• Sporočilo o napaki: %ASA-3-342004: Samodejni ponovni zagon agenta REST API ni uspel po 5 neuspešnih poskusih. Uporabite ukaza 'no rest-api agent' in 'rest-api agent' za ročni ponovni zagon agenta.
  • Pojasnilo: Agent REST API se ni uspel zagnati po številnih poskusih.
  • Priporočeno dejanje: Oglejte si sistemski dnevnik %ASA-3-342002 (če je zabeležen), da boste bolje razumeli razlog za napako. Poskusite onemogočiti agenta REST API tako, da vnesete ukaz no rest-api agent in znova omogočite agenta REST API z ukazom rest-api agent.

Povezana dokumentacija

Za več informacij o ASA ter njegovi konfiguraciji in upravljanju uporabite naslednjo povezavo:

• Krmarjenje po dokumentaciji serije Cisco ASA: http://www.cisco.com/go/asadocs
• Uporabite naslednjo povezavo do view seznam funkcij ASA, ki jih ASAv ne podpira: http://www.cisco.com/c/en/us/td/docs/security/asa/asa92/configuration/general/asa-general-cli/introasav.html#pgfId-1156883

Ta dokument je treba uporabljati skupaj z dokumenti, ki so na voljo v razdelku »Povezana dokumentacija«.
Cisco in logotip Cisco sta blagovni znamki ali registrirani blagovni znamki družbe Cisco in/ali njenih podružnic v ZDA in drugih državah. Za view seznam blagovnih znamk Cisco, pojdite na to URL: www.cisco.com/go/trademarks. Omenjene blagovne znamke tretjih oseb so last njihovih lastnikov. Uporaba besede partner ne pomeni partnerskega odnosa med Ciscom in katerim koli drugim podjetjem. (1721R)
Naslovi internetnega protokola (IP) in telefonske številke, uporabljeni v tem dokumentu, niso dejanski naslovi in ​​telefonske številke. Vsak bivšiampdatoteke, izhodni prikaz ukazov, diagrami omrežne topologije in druge slike, vključene v dokument, so prikazane samo v ilustrativne namene.
Kakršna koli uporaba dejanskih naslovov IP ali telefonskih številk v ilustrativni vsebini je nenamerna in naključna.

Cisco Systems, Inc.

• www.cisco.com

© 2014-2018 Cisco Systems, Inc. Vse pravice pridržane.

Dokumenti / Viri

Aplikacija CISCO ASA REST API [pdf] Uporabniški priročnik Aplikacija ASA REST API, ASA, aplikacija REST API, aplikacija API, aplikacija

Reference

• Uporabniški priročnik