CISCO ASA REST API forrit notendahandbók

Innihald fela sig

1 CISCO ASA REST API app

2 Notkunarleiðbeiningar fyrir vöru

3 Yfirview

4 ASA REST API beiðnir og svör

5 Settu upp og stilltu ASA REST API umboðsmann og viðskiptavin

6 Documentation Console og útflutningur API forskriftir

7 Virkjar REST API kembiforrit á ASA

8 ASA REST API tengd Syslog skilaboð

9 Tengd skjöl

10 Skjöl / auðlindir

10.1 Heimildir

CISCO ASA REST API app

Notkunarleiðbeiningar fyrir vöru

Yfirview

Með útgáfu Cisco ASA REST API hefurðu nú annan léttan, auðveldan í notkun valmöguleika til að stilla og stjórna einstökum Cisco ASA. ASA REST API er forritunarviðmót (API) sem byggir á RESTful meginreglum. Það er hægt að hlaða því niður og virkja fljótt á hvaða ASA sem er þar sem API er í gangi. Cisco Systems, Inc.

www.cisco.com

ASA REST API beiðnir og svör

Eftir að REST biðlari hefur verið settur upp í vafranum þínum geturðu haft samband við REST umboðsmann viðkomandi ASA og notað staðlaðar HTTP aðferðir til að fá aðgang að núverandi stillingarupplýsingum og gefa út viðbótarstillingarfæribreytur.

Varúð: Þegar REST API er virkt á ASA er tengingum með öðrum öryggisstjórnunarsamskiptareglum ekki lokað. Þetta þýðir að aðrir sem nota CLI, ASDM eða öryggisstjóra gætu verið að breyta ASA uppsetningunni á meðan þú ert að gera það sama.

Uppbygging beiðni

þar sem eiginleikar hlutarins eru:

Eign	Tegund	Lýsing
skilaboð	Listi yfir orðabækur	Listi yfir villu- eða viðvörunarskilaboð
kóða	Strengur	Ítarleg skilaboð sem samsvara Villa/viðvörun/upplýsingum
smáatriði	Strengur	Ítarleg skilaboð sem samsvara Villa/viðvörun/upplýsingum

Athugið: Breytingar sem gerðar eru með REST API símtölum eru ekki viðvarandi í ræsingarstillingunum heldur er aðeins úthlutað til ræsandi stillingar. Til að vista breytingar á ræsingarstillingunni geturðu notað POST a write mem API beiðni. Fyrir frekari upplýsingar, sjáðu Write Memory API færsluna í Um ASA REST API efnisyfirlitinu.

Settu upp og stilltu ASA REST API umboðsmann og viðskiptavin

Athugið: REST API Agent er Java-undirstaða forrit. Java Runtime Environment (JRE) er búnt í REST API Agent pakkanum.

Yfirview

Nokkrir valkostir eru í boði til að stilla og stjórna einstökum Cisco ASA:

Command Line Interface (CLI) – þú sendir stjórnskipanir beint til ASA í gegnum tengda stjórnborð.

Adaptive Security Device Manager (ASDM) – „on-box“ stjórnunarforrit með grafísku notendaviðmóti sem þú getur notað til að stilla, stjórna og fylgjast með ASA.
Cisco Öryggisstjóri – þó hann sé ætlaður fyrir meðalstór til stór netkerfi margra öryggistækja, er hægt að nota þetta grafíska forrit til að stilla, stjórna og fylgjast með einstökum ASA.

Með útgáfu Cisco's ASA REST API hefurðu nú annan léttan, auðveldan í notkun. Þetta er forritunarviðmót (API), byggt á „RESTful“ meginreglum, sem þú getur fljótt halað niður og virkjað á hvaða ASA sem API er í gangi á.

ASA REST API beiðnir og svör

ASA REST API veitir þér forritunarlegan aðgang að stjórnun einstakra ASA í gegnum Representational State Transfer (REST) API. API gerir ytri viðskiptavinum kleift að framkvæma CRUD (Create, Read, Update, Delete) aðgerðir á ASA auðlindum; það er byggt á HTTPS samskiptareglum og REST aðferðafræði. Allar API beiðnir eru sendar í gegnum HTTPS til ASA og svar er skilað. Þessi hluti veitir yfirview hvernig beiðnir eru byggðar upp og væntanleg svör,

Uppbygging beiðni

Tiltækar beiðniaðferðir eru:

GET – Sækir gögn úr tilgreindum hlut.
PUT – Bætir tilgreindum upplýsingum við tilgreindan hlut; skilar villu 404 Resource Not Found ef hluturinn er ekki til.

POST – Býr til hlutinn með tilgreindum upplýsingum.
DELETE – Eyðir tilgreindum hlut.

PATCH – Bætir hlutabreytingum á tilgreindan hlut.

Viðbragðsuppbygging

Hver beiðni framleiðir HTTPS svar frá ASA með stöðluðum hausum, svarinnihaldi og stöðukóða.

Svarskipan getur verið:

STAÐSETNING - Auðkenni nýstofnaðs auðlindar; eingöngu fyrir POST—geymir nýja auðkenni tilfangs (sem URI framsetning).
CONTENT-TYPE – Gerð miðils sem lýsir meginmáli svarskilaboða; lýsir framsetningu og setningafræði meginmáls svarskilaboða.

Hvert svar inniheldur HTTP stöðu eða villukóða. Tiltækir kóðar falla í þessa flokka:

20x - Tvö hundruð röð kóða gefur til kynna árangursríka aðgerð, þar á meðal:
- 200 OK – Staðlað svar fyrir árangursríkar beiðnir.
- 201 Búið til – Beiðni lokið; nýtt úrræði búið til.
- 202 Samþykkt – Beiðni samþykkt, en afgreiðslu ekki lokið.
- 204 Ekkert efni – þjónn tókst að vinna úr beiðni; engu efni er skilað.
4xx - Fjögur hundruð röð kóði gefur til kynna villu viðskiptavinarhliðar, þar á meðal:
- 400 Slæm beiðni – Ógildar færibreytur fyrirspurnar, þar á meðal óþekktar færibreytur, færibreytur sem vantar eða ógild gildi.
- 404 Fannst ekki – Meðfylgjandi URL passar ekki við núverandi auðlind. Til dæmisample, HTTP DELETE gæti mistekist vegna þess að tilföngin eru ekki tiltæk.
- 405 Aðferð ekki leyfð – HTTP beiðni var sett fram sem er ekki leyfð á auðlindinni; tdample, POST á skrifvarinn auðlind.
5xx – Fimm hundruð röð kóða gefur til kynna villu á netþjóni.

Ef um villu er að ræða, auk villukóðans, getur skilasvarið innihaldið villuhlut sem inniheldur frekari upplýsingar um villuna. JSON villu/viðvörunarsvörunarskema er sem hér segir:

þar sem eiginleikar hlutarins eru:

Eign	Tegund	Lýsing
skilaboð	Listi yfir orðabækur	Listi yfir villu- eða viðvörunarskilaboð
kóða	Strengur	Villa/viðvörun/upplýsingakóði
smáatriði	Strengur	Ítarleg skilaboð sem samsvara Villa/viðvörun/upplýsingum

Athugið: Breytingar á ASA stillingum sem gerðar eru með REST API símtölum eru ekki viðvarandi í ræsingarstillingunni; það er, breytingar eru eingöngu úthlutaðar til hlaupandi stillingar. Til að vista breytingar á ræsingarstillingunni geturðu POST A Writemem API beiðni; til að fá frekari upplýsingar, fylgdu „Write Memory API“ færslunni í Um ASA REST API efnisyfirlitinu.

Settu upp og stilltu ASA REST API umboðsmann og viðskiptavin

REST API umboðsmaðurinn er birtur fyrir sig með öðrum ASA myndum á cisco.com. Fyrir líkamlega ASA verður að hlaða niður REST API pakkanum á flass tækisins og setja upp með því að nota „rest-api image“ skipunina. REST API Agent er síðan virkjaður með því að nota „rest-api agent“ skipunina.
Með sýndar ASA (ASAv) verður að hlaða niður REST API myndinni á „boot:“ skiptinguna. Þú verður síðan að gefa út „rest-api image“ skipunina, á eftir „rest-api agent“ skipuninni, til að fá aðgang að og virkja REST API umboðsmanninn.
Fyrir upplýsingar um REST API hugbúnað og vélbúnaðarkröfur og eindrægni, sjá Cisco ASA samhæfingarfylki.

Þú getur halað niður viðeigandi REST API pakka fyrir ASA eða ASAv frá software.cisco.com/download/home. Finndu tiltekna líkan Adaptive Security Appliances (ASA) og veldu síðan Adaptive Security Appliance REST API Plugin.

Athugið: REST API Agent er Java-undirstaða forrit. Java Runtime Environment (JRE) er búnt í REST API Agent pakkanum.

Notkunarleiðbeiningar

Mikilvægt Þú verður að hafa hausinn User-Agent: REST API Agent í öllum API símtölum og núverandi forskriftum. Notaðu -H 'User-Agent: REST API Agent' fyrir CURL skipun. Í fjölsamhengisham eru REST API Agent skipanirnar aðeins tiltækar í kerfissamhenginu.

Hámarks studd stillingarstærð

ASA Rest API er „innbyggður“ forrit sem keyrir inni í líkamlegu ASA og hefur sem slíkt takmörkun á minni sem því er úthlutað. Hámarks studd hlaupandi stillingarstærð hefur aukist á útgáfuferlinu í um það bil 2 MB á nýlegum kerfum eins og 5555 og 5585. ASA Rest API hefur einnig minnistakmarkanir á sýndar ASA kerfum. Heildarminni á ASAv5 getur verið 1.5 GB, en á ASAv10 er það 2 GB. Rest API mörkin eru 450 KB og 500 KB fyrir ASAv5 og ASAv10, í sömu röð.

Þess vegna skaltu hafa í huga að stórar stillingar í gangi geta framkallað undantekningar í ýmsum minnisfrekum aðstæðum eins og miklum fjölda samhliða beiðna eða mikið magn beiðna. Við þessar aðstæður geta Rest API GET/PUT/POST símtöl byrjað að mistakast með 500 - Innri miðlara villuskilaboðum, og Rest API umboðsmaðurinn mun endurræsa sjálfkrafa í hvert skipti. Lausnirnar við þessu ástandi eru annaðhvort að færa yfir í ASA/FPR eða ASAV palla með hærra minni eða minnka stærð hlaupandi stillingar.

Sæktu og settu upp REST API Agent

Notaðu CLI, fylgdu þessum skrefum til að hlaða niður og setja upp ASA REST API umboðsmanninn á tilteknu ASA:

Skref 1: Gefðu út afritið á viðkomandi ASA disk0: skipun til að hlaða niður núverandi ASA REST API pakka frá cisco.com í flassminni ASA.
- Til dæmisample: afrita tftp://10.7.0.80/asa-restapi-111-lfbff-k8.SPA diskur0:
Skref 2: Gefðu út rest-api mynd disk0:/ skipun til að staðfesta og setja upp pakkann.
- Til dæmisample: rest-api mynd disk0:/asa-restapi-111-lfbff-k8.SPA

Uppsetningarforritið mun framkvæma eindrægni og staðfestingarpróf og setja síðan upp pakkann. ASA mun ekki endurræsa.

Virkjaðu REST API umboðsmanninn

Fylgdu þessum skrefum til að virkja ASA REST API umboðsmanninn á tilteknu ASA:

Skref 1: Gakktu úr skugga um að rétt hugbúnaðarmynd sé uppsett á ASA.
- Skoðaðu REST API hlutann í ASA samhæfingarfylki (https://www.cisco.com/c/en/us/td/docs/security/asa/compatibility/asamatrx.html#pgfId-131643) til að ákvarða hvaða ASA mynd er nauðsynleg.

Skref 2: Með því að nota CLI skaltu ganga úr skugga um að HTTP þjónninn sé virkur á ASA og að API viðskiptavinir geti tengst við stjórnunarviðmótinu.
- Til dæmisample: http server virkja
- http 0.0.0.0 0.0.0.0

Skref 3: Notaðu CLI til að skilgreina HTTP auðkenningu fyrir API tengingarnar. Til dæmisample: aaa auðkenning http console LOCAL
Skref 4: Notaðu CLI til að búa til kyrrstæða leið á ASA fyrir API umferð. Til dæmisample: leið 0.0.0.0 0.0.0.0 1
Skref 5: Með því að nota CLI, virkjaðu ASA REST API umboðsmanninn á ASA. Til dæmisample: rest-api umboðsmaður

REST API auðkenning

Það eru tvær leiðir til að auðkenna: Grunn HTTP auðkenning, sem sendir notandanafn og lykilorð í hverri beiðni, eða auðkenni byggða á auðkenningu með öruggum HTTPS flutningi, sem sendir áður búið til tákn með hverri beiðni. Hvort heldur sem er, auðkenning verður framkvæmd fyrir hverja beiðni. Sjá kaflann „Token_Authentication_API“ í Um ASA REST API v7.14(x) handbókinni fyrir frekari upplýsingar um auðkenningu sem byggir á auðkenni.

Athugið: Mælt er með því að nota Certificate Authority (CA) útgefin vottorð á ASA, svo REST API biðlarar geti staðfest ASA netþjónsvottorð þegar komið er á SSL tengingum.

Stjórnarheimild

Ef stjórnunarheimild er stillt til að nota ytri AAA netþjón (tdample, aaa heimildarskipun ), þá verður notandi sem heitir enable_1 að vera til á þeim þjóni með fullkomin stjórnunarréttindi. Ef stjórnunarheimild er stillt til að nota LOCAL gagnagrunn ASA (aaa heimildarskipun LOCAL), þá verða allir REST API notendur að vera skráðir í LOCAL gagnagrunninn með forréttindastigum sem eru viðeigandi fyrir hlutverk þeirra:

Forréttindastig 3 eða hærra er nauðsynlegt til að kalla fram vöktunarbeiðnir.

Forréttindastig 5 eða hærra er krafist til að kalla fram GET beiðnir.
Forréttindastig 15 er nauðsynlegt til að kalla fram PUT/POS/DELETE aðgerðir.

Stilltu REST API viðskiptavininn þinn

Fylgdu þessum skrefum til að setja upp og stilla REST API biðlara á staðbundnum hýsingarvafra þínum:

Skref 1: Fáðu og settu upp REST API biðlara fyrir vafrann þinn.
- Fyrir Chrome skaltu setja upp REST biðlarann frá Google. Fyrir Firefox skaltu setja upp RESTClient viðbótina. Internet Explorer er ekki stutt.

Skref 2: Byrjaðu eftirfarandi beiðni með því að nota vafrann þinn: https: /api/objects/networkobjects
- Ef þú færð svar án villu hefurðu náð í REST API umboðsmanninn sem starfar á ASA.
- Ef þú átt í vandræðum með umboðsbeiðnina geturðu virkjað birtingu villuleitarupplýsinga á CLI stjórnborðinu, eins og lýst er í Virkja REST API kembiforrit á ASA.

Skref 3: Valfrjálst geturðu prófað tenginguna þína við ASA með því að framkvæma POST aðgerð.

Til dæmisample: Gefðu upp grunnheimildarskilríki ( ), eða auðkenningartákn (sjá Auðkenningu fyrir frekari upplýsingar).

Heimilisbeiðni miða: https://<asa management ipaddress>/api/objects/networkobjects

Tegund líkamsefnis: forrit/json

Hrár meginmál aðgerðarinnar:

Þú getur nú notað ASA REST API til að stilla og fylgjast með ASA. Skoðaðu API skjölin fyrir símtalslýsingar og tdamples.

Um að endurheimta öryggisafrit að fullu

Að endurheimta fulla öryggisafritun á ASA með því að nota REST API mun endurhlaða ASA. Til að forðast þetta, notaðu eftirfarandi skipun til að endurheimta öryggisafrit:

{
- „skipanir“:[“copy /noconfirm disk0:/filenafn> running-config“]
}
- Hvarfilename> er backup.cfg eða hvaða nafn sem þú notaðir þegar þú tók öryggisafrit af stillingunum.

Documentation Console og útflutningur API forskriftir

Þú getur líka notað REST API á netinu skjalaborðið (kallað „Doc UI“), fáanlegt á host:port/doc/ sem „sandbox“ til að læra um og prófa API símtölin beint á ASA. Ennfremur geturðu notað Export Operation hnappinn í Doc UI til að vista sýndu aðferðina tdample sem JavaScript, Python eða Perl handrit file til gestgjafans á staðnum. Þú getur síðan notað þetta handrit á ASA og breytt því til notkunar á öðrum ASA og öðrum nettækjum. Þetta þýddi fyrst og fremst sem fræðslu- og stígvélatól.

JavaScript

Að nota JavaScript file krefst uppsetningar á node.js, sem er að finna á http://nodejs.org/.
Með því að nota node.js geturðu keyrt JavaScript file, venjulega skrifað fyrir vafra, eins og skipanalínuskrift. Fylgdu einfaldlega uppsetningarleiðbeiningunum og keyrðu síðan skriftuna þína með hnút script.js.

Python

Python forskriftirnar krefjast þess að þú setjir upp Python, fáanlegt frá https://www.python.org/.
Þegar þú hefur sett upp Python geturðu keyrt skriftuna þína með python script.py notandanafn lykilorði.

Perl

Að nota Perl forskriftirnar krefst einhverrar viðbótaruppsetningar - þú þarft fimm hluti: Perl sjálft og fjögur Perl bókasöfn:

Perl pakki, fannst á http://www.perl.org/
Knippi::CPAN, að finna á http://search.cpan.org/~andk/Bundle-CPAN-1.861/CPAN.pm

Hvíld::Viðskiptavinur, finna á http://search.cpan.org/~mcrawfor/REST-Client-88/lib/REST/Client.pm
MIME::Base64, fannst á http://perldoc.perl.org/MIME/Base64.html
JSON, fannst á http://search.cpan.org/~makamaka/JSON-2.90/lib/JSON.pm

Hér er fyrrverandiampLeið af því að ræsa Perl á Macintosh:

$ sudo perl -MCPAN og skel
cpan> setja upp búnt::CPAN

cpan> settu upp REST:: Viðskiptavinur
cpan> setja upp MIME::Base64
cpan> settu upp JSON

Eftir að þú hefur sett upp ósjálfstæðin geturðu keyrt forskriftina þína með því að nota perl script.pl notendanafn lykilorð.

Virkjar REST API kembiforrit á ASA

Ef þú átt í vandræðum með að stilla eða tengjast REST API á ASA geturðu notað eftirfarandi CLI skipun til að virkja birtingu villuleitarskilaboða á stjórnborðinu þínu. Notaðu nei form skipunarinnar til að slökkva á villuskilaboðunum.
kemba rest-api [umboðsmaður | cli | viðskiptavinur | púkinn | ferli | token-auth] [villa | atburður] engin kemba rest-api

Lýsing á setningafræði

umboðsmaður: (Valfrjálst) Virkja REST API Agent villuleitarupplýsingar.
cli: (Valfrjálst) Virkja villuleitarskilaboð fyrir REST API CLI Púka-til-umboðssamskipti.
viðskiptavinur: (Valfrjálst) Virkja villuleitarupplýsingar fyrir skilaboðaleiðingu milli REST API biðlarans og REST API umboðsmannsins.

púkinn: (Valfrjálst) Virkja villuleitarskilaboð fyrir REST API Púka-til-umboðssamskipti.
ferli: (Valfrjálst) Virkja REST API Agent ferli hefja/stöðva villuleitarupplýsingar.
tákn-auth: (Valfrjálst) REST API auðkenningarupplýsingar um villuleit.

villa: (Valfrjálst) Notaðu þetta lykilorð til að takmarka villuskilaboð við villur sem eru skráðar af API.
viðburður: (Valfrjálst) Notaðu þetta lykilorð til að takmarka villuskilaboð við aðeins atburði sem eru skráðir af API.

Notkunarleiðbeiningar

Ef þú gefur ekki upp tiltekið leitarorð íhluta (þ.e. ef þú gefur einfaldlega út skipunina debug rest-api), birtast villuskilaboð fyrir allar íhlutagerðir. Ef þú gefur hvorki upp atburðar- eða villulykilorðið, birtast bæði atburðar- og villuboð fyrir tilgreindan íhlut. Til dæmisample, kemba rest-api púkinn atburður mun aðeins sýna viðburða villuskilaboð fyrir samskipti API púka til umboðsmanns.

Tengdar skipanir

Skipun / Lýsing

kemba HTTP; Notaðu þessa skipun til að view nákvæmar upplýsingar um HTTP umferð.

ASA REST API tengd Syslog skilaboð

ASA REST API tengdum kerfisskrárskilaboðum er lýst í þessum hluta.

342001

Villuboð: %ASA-7-342001: REST API umboðsmaður byrjaði með góðum árangri.
- Skýring: REST API umboðsmaðurinn verður að vera ræstur áður en REST API viðskiptavinur getur stillt ASA.
- Mælt með aðgerðum: Engin.

342002

Villuboð: %ASA-3-342002: REST API umboðsmaður mistókst, ástæða: ástæða
- Skýring: REST API umboðsmaðurinn gæti mistekist að ræsa eða hrun af ýmsum ástæðum og ástæðan er tilgreind.
- ástæða — Orsök REST API bilunarinnar

Mælt með aðgerðum: Aðgerðir sem gerðar eru til að leysa vandamálið eru mismunandi eftir ástæðunni sem skráð er. Til dæmisample, REST API Agent hrynur þegar Java ferlið klárast. Ef þetta gerist þarftu að endurræsa REST API Agent. Ef endurræsingin tekst ekki, hafðu samband við Cisco TAC til að bera kennsl á undirrót lagfæringuna.

342003

Villuboð: %ASA-3-342003: Tilkynning um bilun í REST API umboðsmanni móttekin. Umboðsmaður verður endurræstur sjálfkrafa.
- Skýring: Bilunartilkynning frá REST API umboðsmanni hefur borist og verið er að reyna að endurræsa umboðsmanninn.
- Mælt með aðgerðum: Engin.

342004

Villuboð: %ASA-3-342004: Mistókst að endurræsa REST API umboðsmanninn sjálfkrafa eftir 5 misheppnaðar tilraunir. Notaðu 'no rest-api agent' og 'rest-api agent' skipanirnar til að endurræsa umboðsmanninn handvirkt.
- Skýring: REST API umboðsmaðurinn hefur ekki getað ræst eftir margar tilraunir.
- Mælt með aðgerðum: Sjáðu syslog %ASA-3-342002 (ef skráð er) til að skilja betur ástæðuna á bak við bilunina. Reyndu að slökkva á REST API Agent með því að slá inn no rest-api agent skipunina og virkjaðu REST API Agent aftur með því að nota rest-api agent skipunina.

Tengd skjöl

Notaðu eftirfarandi hlekk til að finna frekari upplýsingar um ASA og uppsetningu þess og stjórnun:

Vafra um Cisco ASA Series Documentation: http://www.cisco.com/go/asadocs
Notaðu eftirfarandi tengil til að view listi yfir ASA eiginleika sem ekki eru studdir á ASAv: http://www.cisco.com/c/en/us/td/docs/security/asa/asa92/configuration/general/asa-general-cli/introasav.html#pgfId-1156883

Þetta skjal á að nota í tengslum við skjölin sem eru fáanleg í hlutanum „Tengd skjöl“.
Cisco og Cisco lógóið eru vörumerki eða skráð vörumerki Cisco og/eða hlutdeildarfélaga þess í Bandaríkjunum og öðrum löndum. Til view lista yfir Cisco vörumerki, farðu í þetta URL: www.cisco.com/go/trademarks. Vörumerki þriðja aðila sem nefnd eru eru eign viðkomandi eigenda. Notkun orðsins samstarfsaðili felur ekki í sér samstarfstengsl milli Cisco og nokkurs annars fyrirtækis. (1721R)
Öll Internet Protocol (IP) vistföng og símanúmer sem notuð eru í þessu skjali eru ekki ætluð sem raunveruleg heimilisföng og símanúmer. Hvaða fyrrverandiamples, úttak skipanaskjás, skýringarmyndir um staðfræði netkerfisins og aðrar tölur sem eru í skjalinu eru aðeins sýndar til skýringar.
Öll notkun raunverulegra IP tölur eða símanúmera í lýsandi efni er óviljandi og tilviljun.

Cisco Systems, Inc.

www.cisco.com

Skjöl / auðlindir

CISCO ASA REST API app [pdfNotendahandbók
ASA REST API app, ASA, REST API app, API app, app

Heimildir

Notendahandbók