CISCO-logo

CISCO ASA REST API App

CISCO-ASA-REST-API-App-produk

Produk Gebruik Instruksies

verbyview

Met die vrystelling van Cisco se ASA REST API, het jy nou nog 'n liggewig, maklik om te gebruik opsie vir die opstel en bestuur van individuele Cisco ASA's. Die ASA REST API is 'n toepassingsprogrammeringskoppelvlak (API) gebaseer op RESTful-beginsels. Dit kan vinnig afgelaai en geaktiveer word op enige ASA waar die API loop. Cisco Systems, Inc.

www.cisco.com

ASA REST API-versoeke en -antwoorde

Nadat u 'n REST-kliënt in u blaaier geïnstalleer het, kan u die spesifieke ASA se REST-agent kontak en standaard HTTP-metodes gebruik om toegang tot huidige konfigurasie-inligting te verkry en bykomende konfigurasieparameters uit te reik.

Waarskuwing: Wanneer die REST API op 'n ASA geaktiveer is, word verbindings deur ander sekuriteitsbestuurprotokolle nie geblokkeer nie. Dit beteken dat ander wat CLI, ASDM of Sekuriteitsbestuurder gebruik, die ASA-konfigurasie kan verander terwyl jy dieselfde doen.

Versoekstruktuur

Die ASA REST API gee jou programmatiese toegang tot die bestuur van individuele ASA's deur middel van 'n Representational State Transfer (REST) ​​API. Die API laat eksterne kliënte toe om CRUD (Skep, lees, werk op, verwyder)-bewerkings op ASA-hulpbronne uit te voer. Alle API-versoeke word oor HTTPS na die ASA gestuur, en 'n antwoord word teruggestuur.

waar die voorwerp eienskappe is:

Eiendom Tik Beskrywing
boodskappe Lys van Woordeboeke Lys van fout- of waarskuwingsboodskappe
kode Snaar Gedetailleerde boodskap wat ooreenstem met Fout/Waarskuwing/Inligting
besonderhede Snaar Gedetailleerde boodskap wat ooreenstem met Fout/Waarskuwing/Inligting

Let wel: Veranderinge wat deur REST API-oproepe gemaak word, word nie aan die opstartkonfigurasie volgehou nie, maar word slegs aan die lopende opstelling toegewys. Om veranderinge aan die opstartkonfigurasie te stoor, kan jy die POST a write mem API-versoek gebruik. Vir meer inligting, verwys na die Write Memory API-inskrywing in die Oor die ASA REST API-inhoudsopgawe.

Installeer en konfigureer die ASA REST API-agent en -kliënt

Let wel: Die REST API Agent is 'n Java-gebaseerde toepassing. Die Java Runtime Environment (JRE) is saamgevat in die REST API Agent-pakket.

verbyview

Verskeie opsies is beskikbaar vir die opstel en bestuur van individuele Cisco ASA's:

  • Command Line Interface (CLI) – jy stuur beheeropdragte direk na die ASA via 'n gekoppelde konsole.
  • Adaptive Security Device Manager (ASDM) – 'n "on-box" bestuursprogram met 'n grafiese gebruikerskoppelvlak wat jy kan gebruik om 'n ASA op te stel, te bestuur en te monitor.
  • Cisco Security Manager – hoewel dit bedoel is vir medium tot groot netwerke van baie sekuriteitstoestelle, kan hierdie grafiese toepassing gebruik word om individuele ASA's op te stel, te bestuur en te monitor.

Met die vrystelling van Cisco se ASA REST API, het jy nou nog 'n liggewig, maklik om te gebruik opsie. Dit is 'n toepassingsprogrammeringskoppelvlak (API), gebaseer op "RUSTIGE" beginsels, wat jy vinnig kan aflaai en aktiveer op enige ASA waarop die API loop.

Nadat jy 'n REST-kliënt in jou blaaier geïnstalleer het, kan jy die spesifieke ASA se REST-agent kontak en standaard HTTP-metodes gebruik om toegang tot huidige konfigurasie-inligting te verkry, en bykomende konfigurasieparameters uit te reik.

Waarskuwing: Wanneer die REST API op 'n ASA geaktiveer is, word verbindings deur ander sekuriteitsbestuurprotokolle nie geblokkeer nie. Dit beteken dat ander wat CLI, ASDM of Sekuriteitsbestuurder gebruik, die ASA-konfigurasie kan verander terwyl jy dieselfde doen.

ASA REST API-versoeke en -antwoorde

Die ASA REST API gee jou programmatiese toegang tot die bestuur van individuele ASA's deur middel van 'n Representational State Transfer (REST) ​​API. Die API laat eksterne kliënte toe om CRUD (Skep, lees, werk op, verwyder) bewerkings op ASA-hulpbronne uit te voer; dit is gebaseer op die HTTPS-protokol en REST-metodologie. Alle API-versoeke word oor HTTPS na die ASA gestuur, en 'n antwoord word teruggestuur. Hierdie afdeling bied 'n oorview van hoe versoeke gestruktureer is, en die verwagte antwoorde,

Versoekstruktuur

Beskikbare versoekmetodes is:

  • GET – Haal data van die gespesifiseerde voorwerp af.
  • PUT – Voeg die verskafde inligting by die gespesifiseerde voorwerp; gee 'n 404 Resource Not Found-fout terug as die objek nie bestaan ​​nie.
  • POST – Skep die voorwerp met die verskafde inligting.
  • DELETE – Vee die gespesifiseerde voorwerp uit.
  • PATCH – Pas gedeeltelike wysigings toe op die gespesifiseerde voorwerp.

Reaksiestruktuur

  • Elke versoek produseer 'n HTTPS-antwoord van die ASA met die standaardopskrifte, reaksie-inhoud en statuskode.

Die reaksiestruktuur kan wees:

  • LIGGING – Nuutgeskepte hulpbron-ID; slegs vir POST—hou die nuwe hulpbron-ID (as 'n URI-voorstelling).
  • INHOUD-TIPE – Mediatipe wat die reaksieboodskapliggaam beskryf; beskryf die voorstelling en sintaksis van die reaksieboodskapliggaam.

Elke antwoord bevat 'n HTTP-status of foutkode. Beskikbare kodes val in hierdie kategorieë:

  • 20x – 'n Tweehonderd-reekskode dui suksesvolle operasie aan, insluitend:
    • 200 OK – Standaardantwoord vir suksesvolle versoeke.
    • 201 Geskep – Versoek voltooi; nuwe hulpbron geskep.
    • 202 Aanvaar – Versoek is aanvaar, maar verwerking nie voltooi nie.
    • 204 Geen inhoud – Bediener het versoek suksesvol verwerk; geen inhoud word teruggestuur nie.
  • 4xx – 'n Vierhonderd reeks kode dui op 'n kliënt-kant fout, insluitend:
    • 400 Slegte versoek – Ongeldige navraagparameters, insluitend onherkende parameters, ontbrekende parameters of ongeldige waardes.
    • 404 Nie gevind nie – Die verskaf URL pas nie by 'n bestaande hulpbron nie. Byvoorbeeldample, 'n HTTP DELETE kan misluk omdat die hulpbron nie beskikbaar is nie.
    • 405 Metode nie toegelaat nie – 'n HTTP-versoek is aangebied wat nie op die hulpbron toegelaat word nie; byvoorbeeldample, 'n POST op 'n leesalleen-hulpbron.
  • 5xx – 'n Vyfhonderd-reekskode dui op 'n fout aan die bedienerkant.

In die geval van 'n fout, bykomend tot die foutkode, kan die terugsending 'n foutvoorwerp insluit wat meer besonderhede oor die fout bevat. Die JSON fout/waarskuwing reaksie skema is soos volg:

CISCO-ASA-REST-API-App-fig-1

waar die voorwerp eienskappe is:

Eiendom Tik Beskrywing
boodskappe Lys van Woordeboeke Lys van fout- of waarskuwingsboodskappe
kode Snaar Fout/waarskuwing/inligtingskode
besonderhede Snaar Gedetailleerde boodskap wat ooreenstem met Fout/Waarskuwing/Inligting

Let wel: Veranderinge aan die ASA-konfigurasie wat deur REST API-oproepe gemaak is, word nie in die opstartkonfigurasie volgehou nie; dit wil sê, veranderinge word slegs aan die lopende konfigurasie toegewys. Om veranderinge aan die opstartkonfigurasie te stoor, kan jy 'n writemem API-versoek POST; vir meer inligting, volg die "Write Memory API" inskrywing in die Oor die ASA REST API inhoudsopgawe.

Installeer en konfigureer die ASA REST API-agent en -kliënt

  • Die REST API Agent word individueel gepubliseer met ander ASA beelde op cisco.com. Vir fisiese ASA's moet die REST API-pakket na die toestel se flits afgelaai word en geïnstalleer word deur die "rest-api image"-opdrag te gebruik. Die REST API Agent word dan geaktiveer met die "rest-api agent" opdrag.
  • Met 'n virtuele ASA (ASAv), moet die REST API-beeld na die "boot:"-partisie afgelaai word. Jy moet dan die "rest-api image"-opdrag uitreik, gevolg deur die "rest-api agent"-opdrag, om toegang tot die REST API-agent te verkry en dit te aktiveer.
  • Vir inligting oor REST API sagteware en hardeware vereistes en verenigbaarheid, sien die Cisco ASA Verenigbaarheid matriks.
  • Jy kan die toepaslike REST API-pakket vir jou ASA of ASAv aflaai vanaf software.cisco.com/download/home. Vind die spesifieke Adaptive Security Appliances (ASA)-model en kies dan Adaptive Security Appliance REST API-inprop.

Let wel: Die REST API Agent is 'n Java-gebaseerde toepassing. Die Java Runtime Environment (JRE) is saamgevat in die REST API Agent-pakket.

Gebruiksriglyne

Belangrik Jy moet die opskrif User-Agent: REST API Agent by alle API-oproepe en bestaande skrifte insluit. Gebruik -H 'User-Agent: REST API Agent' vir die CURL bevel. In multi-konteksmodus is die REST API Agent-opdragte slegs in die stelselkonteks beskikbaar.

Maksimum ondersteunde konfigurasiegrootte

Die ASA Rest API is 'n "aan boord" toepassing wat binne die fisiese ASA loop, en het as sodanig 'n beperking op die geheue wat daaraan toegewys is. Maksimum ondersteunde lopende konfigurasiegrootte het oor die vrystellingsiklus toegeneem tot ongeveer 2 MB op onlangse platforms soos die 5555 en 5585. Die ASA Rest API het ook geheuebeperkings op die virtuele ASA-platforms. Totale geheue op die ASAv5 kan 1.5 GB wees, terwyl dit op die ASAv10 2 GB is. Die Rest API-limiete is onderskeidelik 450 KB en 500 KB vir die ASAv5 en ASAv10.

Wees dus bewus daarvan dat groot lopende konfigurasies uitsonderings kan produseer in verskeie geheue-intensiewe situasies soos 'n groot aantal gelyktydige versoeke, of groot versoekvolumes. In hierdie situasies kan Rest API GET/PUT/POST oproepe begin misluk met 500 – Interne Bediener Foutboodskappe, en die Rest API Agent sal outomaties elke keer herbegin. Die oplossings vir hierdie situasie is om óf na ASA/FPR- of ASAV-platforms met hoër geheue te skuif, óf die grootte van die lopende konfigurasie te verminder.

Laai die REST API Agent af en installeer dit

Deur die CLI te gebruik, volg hierdie stappe om die ASA REST API-agent op 'n spesifieke ASA af te laai en te installeer:

  • Stap 1: Op die verlangde ASA, reik die kopie uit disk0: opdrag om die huidige ASA REST API-pakket van af te laai cisco.com na die ASA se flitsgeheue.
    • Byvoorbeeldample: kopieer tftp://10.7.0.80/asa-restapi-111-lfbff-k8.SPA skyf0:
  • Stap 2: Reik die res-api-beeldskyf0 uit:/ opdrag om die pakket te verifieer en te installeer.
    • Byvoorbeeldample: rest-api-beeldskyf0:/asa-restapi-111-lfbff-k8.SPA

Die installeerder sal verenigbaarheids- en valideringskontroles uitvoer en dan die pakket installeer. Die ASA sal nie herlaai nie.

Aktiveer die REST API Agent

Volg hierdie stappe om die ASA REST API Agent op 'n spesifieke ASA te aktiveer:

  • Stap 1: Maak seker dat die korrekte sagtewarebeeld op die ASA geïnstalleer is.
  • Stap 2: Deur die CLI te gebruik, maak seker dat die HTTP-bediener op die ASA geaktiveer is, en dat API-kliënte aan die bestuurskoppelvlak kan koppel.
    • Byvoorbeeldample: http-bediener aktiveer
    • http 0.0.0.0 0.0.0.0
  • Stap 3: Definieer HTTP-verifikasie vir die API-verbindings deur die CLI te gebruik. Byvoorbeeldample: aaa verifikasie http konsole PLAASLIK
  • Stap 4: Met behulp van die CLI, skep 'n statiese roete op die ASA vir API-verkeer. Byvoorbeeldample: roete 0.0.0.0 0.0.0.0 1
  • Stap 5: Deur die CLI te gebruik, aktiveer die ASA REST API Agent op die ASA. Byvoorbeeldample: rus-api agent

REST API-verifikasie

Daar is twee maniere om te verifieer: Basiese HTTP-verifikasie, wat 'n gebruikersnaam en wagwoord in elke versoek deurgee, of Token-gebaseerde verifikasie met veilige HTTPS-vervoer, wat 'n voorheen geskepte teken met elke versoek deurgee. Hoe dit ook al sy, stawing sal vir elke versoek uitgevoer word. Sien die afdeling, "Token_Authentication_API" in die About the ASA REST API v7.14(x) gids vir bykomende inligting oor Token-gebaseerde verifikasie.

Let wel: Gebruik van Sertifikaat-owerheid (CA)-uitgereikte sertifikate word aanbeveel op ASA, sodat REST API-kliënte die ASA-bedienersertifikate kan bekragtig wanneer SSL-verbindings tot stand gebring word.

Bevelmagtiging

As opdragmagtiging opgestel is om 'n eksterne AAA-bediener te gebruik (bvample, aaa magtiging bevel ), dan moet 'n gebruiker met die naam enable_1 op daardie bediener met volle opdragvoorregte bestaan. As opdragmagtiging opgestel is om die ASA se PLAASLIKE databasis (aaa magtigingsopdrag LOCAL) te gebruik, moet alle REST API-gebruikers in die PLAASLIKE databasis geregistreer wees met voorregtevlakke wat geskik is vir hul rolle:

  • Voorregvlak 3 of hoër word vereis om moniteringversoeke op te roep.
  • Voorregvlak 5 of hoër word vereis om AOO-versoeke aan te roep.
  • Voorregvlak 15 is nodig om PUT/POS/DELETE-bewerkings aan te roep.

Stel jou REST API-kliënt op

Volg hierdie stappe om 'n REST API-kliënt op jou plaaslike gasheerblaaier te installeer en op te stel:

  • Stap 1: Verkry en installeer 'n REST API-kliënt vir jou blaaier.
    • Vir Chrome, installeer die REST-kliënt vanaf Google. Vir Firefox, installeer die RESTClient-byvoeging. Internet Explorer word nie ondersteun nie.
  • Stap 2: Begin die volgende versoek met jou blaaier: https: /api/objects/networkobjects
    • As jy 'n nie-foutreaksie ontvang, het jy die REST API-agent bereik wat op die ASA funksioneer.
    • As jy probleme ondervind met die agentversoek, kan jy die vertoon van ontfoutingsinligting op die CLI-konsole aktiveer, soos beskryf in Aktivering van REST API-ontfouting op die ASA.
  • Stap 3: Opsioneel kan jy jou verbinding met die ASA toets deur 'n POST-bewerking uit te voer.

Byvoorbeeldample: Verskaf basiese magtiging geloofsbriewe ( ), of 'n verifikasietoken (sien Tokenstawing vir bykomende inligting).

  • Doelversoekadres: https://<asa management ipaddress>/api/objects/networkobjects
  • Liggaam inhoud tipe: toepassing/json

Rou liggaam van die operasie:

CISCO-ASA-REST-API-App-fig-2

Jy kan nou die ASA REST API gebruik om die ASA op te stel en te monitor. Verwys na die API-dokumentasie vir oproepbeskrywings en bvamples.

Oor die volledig herstel van 'n rugsteunkonfigurasie

Die herstel van 'n volledige rugsteunkonfigurasie op die ASA deur die REST API te gebruik, sal die ASA herlaai. Om dit te vermy, gebruik die volgende opdrag om 'n rugsteunkonfigurasie te herstel:

  • {
    • “commands”:[“copy /noconfirm disk0:/filenaam> running-config”]
  • }
    • Waarfilename> is backup.cfg of watter naam jy ook al gebruik het toe jy die konfigurasie gerugsteun het.

Die dokumentasiekonsole en uitvoer van API-skrifte

Jy kan ook die REST API aanlyn dokumentasie konsole (na verwys as die "Doc UI"), beskikbaar by host:port/doc/ as 'n "sandbox" gebruik om die API-oproepe direk op die ASA te leer en te probeer. Verder kan jy die Uitvoerbewerking-knoppie in die Doc UI gebruik om die vertoonde metode te stoor, bvample as 'n JavaScript-, Python- of Perl-skrip file aan jou plaaslike gasheer. Jy kan dan hierdie skrif op jou ASA toepas, en dit redigeer vir toepassing op ander ASA's en ander netwerktoestelle. Dit is hoofsaaklik bedoel as 'n opvoedkundige en selflaai-instrument.

JavaScript

  • Gebruik 'n JavaScript file vereis installering van node.js, wat gevind kan word by http://nodejs.org/.
  • Deur node.js te gebruik, kan jy 'n JavaScript uitvoer file, tipies geskryf vir 'n blaaier, soos 'n opdragreëlskrif. Volg eenvoudig die installasie-instruksies, en voer dan jou script met node script.js uit.

Python

  • Die Python-skrifte vereis dat jy Python installeer, beskikbaar vanaf https://www.python.org/.
  • Sodra jy Python geïnstalleer het, kan jy jou script laat loop met python script.py gebruikersnaam wagwoord.

Perl

Die gebruik van die Perl-skrifte vereis 'n paar bykomende opstelling - jy benodig vyf komponente: Perl self en vier Perl-biblioteke:

Hier is 'n example van selflaai van Perl op 'n Macintosh:

  • $ sudo perl -MCPAN en dop
  • cpan> installeer bundel::CPAN
  • cpan> installeer REST:: Kliënt
  • cpan> installeer MIME:: basis64
  • cpan> installeer JSON

Nadat u die afhanklikhede geïnstalleer het, kan u u skrip laat loop deur perl script.pl-gebruikersnaamwagwoord te gebruik.

Aktiveer REST API-ontfouting op die ASA

As jy probleme ondervind om te konfigureer of aan die REST API op die ASA te koppel, kan jy die volgende CLI-opdrag gebruik om vertoning van ontfoutingsboodskappe op jou konsole moontlik te maak. Gebruik die geen vorm van die opdrag om die ontfoutingsboodskappe te deaktiveer.
ontfout res-api [agent | cli | kliënt | daemon | proses | token-auth] [fout | gebeurtenis] geen debug res-api nie

Sintaksisbeskrywing

  • agent: (Opsioneel) Aktiveer REST API Agent-ontfoutingsinligting.
  • cli: (Opsioneel) Aktiveer ontfoutingsboodskappe vir REST API CLI Daemon-to-Agent-kommunikasie.
  • kliënt: (Opsioneel) Aktiveer ontfoutingsinligting vir Boodskaproetering tussen die REST API-kliënt en die REST API-agent.
  • daemoon: (Opsioneel) Aktiveer ontfoutingsboodskappe vir REST API Daemon-to-Agent-kommunikasie.
  • proses: (Opsioneel) Aktiveer REST API Agent proses begin/stop ontfouting inligting.
  • teken-bekragtiging: (Opsioneel) REST API-token-verifikasie ontfoutingsinligting.
  • fout: (Opsioneel) Gebruik hierdie sleutelwoord om ontfoutboodskappe te beperk tot slegs foute wat deur die API aangeteken is.
  • gebeurtenis: (Opsioneel) Gebruik hierdie sleutelwoord om ontfoutingsboodskappe te beperk tot slegs gebeurtenisse wat deur die API aangeteken is.

Gebruiksriglyne

As jy nie 'n spesifieke komponent sleutelwoord verskaf nie (dit wil sê as jy bloot die opdrag debug rest-api uitreik), word ontfoutingsboodskappe vir alle komponenttipes vertoon. As jy nie die gebeurtenis- of foutsleutelwoord verskaf nie, word beide gebeurtenis- en foutboodskappe vir die gespesifiseerde komponent vertoon. Byvoorbeeldample, debug rest-api daemon event sal net event debug boodskappe wys vir API Daemon-to-Agent kommunikasie.

Verwante opdragte

Opdrag / Beskrywing

  • ontfout HTTP; Gebruik hierdie opdrag om view gedetailleerde inligting oor HTTP-verkeer.

ASA REST API-verwante Syslog-boodskappe

Die ASA REST API-verwante stelsellogboodskappe word in hierdie afdeling beskryf.

342001

  • Foutboodskap: %ASA-7-342001: REST API Agent het suksesvol begin.
    • Verduideliking: Die REST API-agent moet suksesvol begin word voordat 'n REST API-kliënt die ASA kan opstel.
    • Aanbevole aksie: Geen.

342002

  • Foutboodskap: %ASA-3-342002: REST API Agent het misluk, rede: rede
    • Verduideliking: Die REST API-agent kan om verskeie redes nie begin of ineenstort nie, en die rede word gespesifiseer.
    • rede—Die oorsaak vir die REST API-mislukking

Aanbevole aksie: Die aksies wat geneem word om die probleem op te los, wissel na gelang van die rede wat aangeteken is. Byvoorbeeldample, die REST API Agent crash wanneer die Java-proses se geheue opraak. As dit gebeur, moet jy die REST API Agent herbegin. As die herbegin nie suksesvol is nie, kontak die Cisco TAC om die hoofoorsaakoplossing te identifiseer.

342003

  • Foutboodskap: %ASA-3-342003: REST API Agent mislukking kennisgewing ontvang. Agent sal outomaties herbegin word.
    • Verduideliking: 'n Mislukkingskennisgewing van die REST API Agent is ontvang en 'n herbegin van die Agent word gepoog.
    • Aanbevole aksie: Geen.

342004

  • Foutboodskap: %ASA-3-342004: Kon nie die REST API-agent outomaties herbegin na 5 onsuksesvolle pogings nie. Gebruik die 'no rest-api agent' en 'rest-api agent' opdragte om die Agent handmatig te herbegin.
    • Verduideliking: Die REST API-agent kon na baie pogings nie begin nie.
    • Aanbevole aksie: Sien syslog %ASA-3-342002 (indien aangeteken) om die rede agter die mislukking beter te verstaan. Probeer om die REST API Agent te deaktiveer deur die no rest-api agent opdrag in te voer en die REST API Agent te heraktiveer deur die rest-api agent opdrag te gebruik.

Verwante dokumentasie

Gebruik die volgende skakel om meer inligting oor die ASA, en sy opstelling en bestuur te kry:

Hierdie dokument moet gebruik word saam met die dokumente wat beskikbaar is in die "Verwante Dokumentasie" afdeling.
Cisco en die Cisco-logo is handelsmerke of geregistreerde handelsmerke van Cisco en/of sy affiliasies in die VSA en ander lande. Om view 'n lys van Cisco handelsmerke, gaan na hierdie URL: www.cisco.com/go/trademarks. Derdeparty-handelsmerke wat genoem word, is die eiendom van hul onderskeie eienaars. Die gebruik van die woord vennoot impliseer nie 'n vennootskapsverhouding tussen Cisco en enige ander maatskappy nie. (1721R)
Enige internetprotokol (IP) adresse en telefoonnommers wat in hierdie dokument gebruik word, is nie bedoel om werklike adresse en telefoonnommers te wees nie. Enige examplese, opdragvertoonuitset, netwerktopologiediagramme en ander figure wat in die dokument ingesluit is, word slegs vir illustratiewe doeleindes getoon.
Enige gebruik van werklike IP-adresse of telefoonnommers in illustratiewe inhoud is onopsetlik en toevallig.

Cisco Systems, Inc.

© 2014-2018 Cisco Systems, Inc. Alle regte voorbehou.

Dokumente / Hulpbronne

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

Verwysings

Los 'n opmerking

Jou e-posadres sal nie gepubliseer word nie. Vereiste velde is gemerk *