CISCO-logo

CISCO ASA REST API App

CISCO-ASA-REST-API-App-pwodwi

Pwodwi Sèvi ak Enstriksyon

Plis paseview

Avèk lage API ASA REST Cisco a, kounye a ou gen yon lòt opsyon ki lejè, fasil pou itilize pou konfigirasyon ak jere Cisco ASA endividyèl yo. ASA REST API se yon koòdone pwogramasyon aplikasyon (API) ki baze sou prensip RESTful. Li ka byen vit telechaje epi aktive sou nenpòt ASA kote API a ap kouri. Cisco Systems, Inc.

www.cisco.com

ASA REST API Demann ak Repons

Apre w fin enstale yon kliyan REST nan navigatè w la, ou ka kontakte ajan REST espesifik ASA a epi itilize metòd HTTP estanda pou jwenn aksè nan enfòmasyon konfigirasyon aktyèl yo epi bay lòt paramèt konfigirasyon.

Atansyon: Lè API REST la aktive sou yon ASA, koneksyon pa lòt pwotokòl jesyon sekirite yo pa bloke. Sa vle di lòt moun ki sèvi ak CLI, ASDM, oswa Manadjè Sekirite ta ka chanje konfigirasyon ASA pandan w ap fè menm bagay la.

Estrikti demann

ASA REST API ba ou aksè pwogramasyon pou jere ASA endividyèl yo atravè yon API Reprezantatif Eta Transfè (REST). API a pèmèt kliyan ekstèn yo fè operasyon CRUD (Kreye, Li, Mizajou, Efase) sou resous ASA. Tout demann API yo voye sou HTTPS bay ASA a, epi yo retounen yon repons.

kote pwopriyete objè yo se:

Pwopriyete Kalite Deskripsyon
mesaj Lis diksyonè Lis erè oswa mesaj avètisman
kòd Fisèl Mesaj detaye ki koresponn ak Erè/Avètisman/Enfo
detay Fisèl Mesaj detaye ki koresponn ak Erè/Avètisman/Enfo

Nòt: Chanjman ki fèt pa apèl REST API yo pa pèsiste nan konfigirasyon demaraj la men yo asiyen sèlman nan konfigirasyon an kouri. Pou sove chanjman nan konfigirasyon demaraj la, ou ka itilize POST yon demann ekri mem API. Pou plis enfòmasyon, al gade nan Write Memory API antre nan atik Konsènan ASA REST API.

Enstale ak konfigirasyon ajan ak kliyan ASA REST API

Nòt: Ajan REST API a se yon aplikasyon ki baze sou Java. Java Runtime Environment (JRE) yo mete nan pake Ajan REST API a.

Plis paseview

Gen plizyè opsyon ki disponib pou konfigirasyon ak jere endividyèl Cisco ASA:

  • Command Line Interface (CLI) - ou voye kòmandman kontwòl dirèkteman nan ASA atravè yon konsole konekte.
  • Adaptive Security Device Manager (ASDM) - yon aplikasyon jesyon "sou bwat" ak yon koòdone itilizatè grafik ke ou ka itilize pou konfigirasyon, jere ak kontwole yon ASA.
  • Manadjè Sekirite Cisco - pandan y ap gen entansyon pou rezo mwayen ak gwo nan anpil aparèy sekirite, aplikasyon grafik sa a ka itilize pou konfigirasyon, jere ak kontwole ASA endividyèl yo.

Avèk lage API ASA REST Cisco a, kounye a ou gen yon lòt opsyon ki lejè, ki fasil pou itilize. Sa a se yon koòdone pwogramasyon aplikasyon (API), ki baze sou prensip "RESTful", ke ou ka byen vit telechaje epi aktive sou nenpòt ASA sou ki API a ap kouri.

Apre w fin enstale yon kliyan REST nan navigatè w la, ou ka kontakte ajan REST espesifik ASA a epi itilize metòd HTTP estanda pou jwenn aksè nan enfòmasyon konfigirasyon aktyèl yo, epi bay lòt paramèt konfigirasyon.

Atansyon: Lè API REST la aktive sou yon ASA, koneksyon pa lòt pwotokòl jesyon sekirite yo pa bloke. Sa vle di lòt moun ki sèvi ak CLI, ASDM, oswa Manadjè Sekirite ta ka chanje konfigirasyon ASA pandan w ap fè menm bagay la.

ASA REST API Demann ak Repons

ASA REST API ba ou aksè pwogramasyon pou jere ASA endividyèl yo atravè yon API Representational State Transfer (REST). API a pèmèt kliyan ekstèn yo fè operasyon CRUD (Kreye, Li, Mizajou, Efase) sou resous ASA; li baze sou pwotokòl HTTPS ak metodoloji REST. Tout demann API yo voye sou HTTPS bay ASA a, epi yo retounen yon repons. Seksyon sa a bay yon souview sou fason demann yo estriktire, ak repons yo espere,

Estrikti demann

Metòd demann ki disponib yo se:

  • GET - Rekipere done ki soti nan objè a espesifye.
  • PUT - Ajoute enfòmasyon yo bay nan objè a espesifye; retounen yon erè 404 Resous Not Found si objè a pa egziste.
  • POST - Kreye objè a ak enfòmasyon yo bay la.
  • DELETE - Efase objè a espesifye.
  • PATCH - Aplike modifikasyon pasyèl nan objè a espesifye.

Estrikti Repons

  • Chak demann pwodui yon repons HTTPS soti nan ASA a ak tèt estanda yo, kontni repons, ak kòd estati.

Estrikti repons lan ka:

  • KOTE – ID resous ki fèk kreye; pou POST sèlman—kenbe nouvo ID resous la (kòm yon reprezantasyon URI).
  • CONTENT-TYPE – Kalite medya ki dekri kò mesaj repons lan; dekri reprezantasyon ak sentaks kò mesaj repons lan.

Chak repons gen ladan yon estati HTTP oswa yon kòd erè. Kòd ki disponib yo tonbe nan kategori sa yo:

  • 20x - Yon kòd de san seri endike operasyon siksè, ki gen ladan:
    • 200 OK – Repons estanda pou demann ki gen siksè.
    • 201 Kreye – Demann ranpli; nouvo resous ki te kreye.
    • 202 Aksepte – Demann aksepte, men pwosesis la pa fini.
    • 204 Pa gen kontni – Sèvè a te trete demann avèk siksè; pa gen okenn kontni ke yo te retounen.
  • 4xx - Yon kòd seri katsan (XNUMX) endike yon erè bò kliyan, tankou:
    • 400 Move demann - Paramèt rechèch ki pa valab, ki gen ladan paramèt ki pa rekonèt, paramèt ki manke, oswa valè ki pa valab.
    • 404 Pa jwenn – Yo bay la URL pa matche ak yon resous ki egziste deja. Pou egzanpampLè sa a, yon HTTP DELETE ka echwe paske resous la pa disponib.
    • 405 Metòd pa pèmèt – Yo te prezante yon demann HTTP ki pa pèmèt sou resous la; pou egzanpample, yon POST sou yon resous li sèlman.
  • 5xx - Yon kòd senksan seri endike yon erè bò sèvè.

Nan ka yon erè, anplis kòd erè a, repons retounen an ka gen ladan yon objè erè ki gen plis detay sou erè a. Erè JSON/chema repons avètisman an se jan sa a:

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

kote pwopriyete objè yo se:

Pwopriyete Kalite Deskripsyon
mesaj Lis diksyonè Lis erè oswa mesaj avètisman
kòd Fisèl Erè/Avètisman/Kod Enfòmasyon
detay Fisèl Mesaj detaye ki koresponn ak Erè/Avètisman/Enfo

Nòt: Chanjman nan konfigirasyon ASA ki fèt pa apèl REST API yo pa pèsiste nan konfigirasyon demaraj la; se sa ki, chanjman yo asiyen sèlman nan konfigirasyon an kouri. Pou sove chanjman nan konfigirasyon demaraj la, ou ka POST yon demann API writemem; pou plis enfòmasyon, swiv "Write Memory API" nan atik Konsènan ASA REST API.

Enstale ak konfigirasyon ajan ak kliyan ASA REST API

  • Ajan REST API pibliye endividyèlman ak lòt imaj ASA sou li cisco.com. Pou ASA fizik, yo dwe telechaje pake REST API a sou flash aparèy la epi enstale yo lè l sèvi avèk kòmandman "rest-api image". Lè sa a, Ajan REST API a aktive lè l sèvi avèk kòmandman "res-api agent".
  • Avèk yon ASA vityèl (ASAv), yo dwe telechaje imaj REST API a nan patisyon "boot:". Lè sa a, ou dwe bay kòmandman "res-api image" ki te swiv pa kòmand "reste-api ajan" pou jwenn aksè ak pèmèt Ajan REST API a.
  • Pou enfòmasyon sou lojisyèl REST API ak kondisyon pyès ki nan konpitè ak konpatibilite, gade Matrice konpatibilite Cisco ASA.
  • Ou ka telechaje pake API REST ki apwopriye a pou ASA oswa ASAv ou software.cisco.com/download/home. Chèche espesifik Adaptive Security Appliances (ASA) modèl la epi chwazi Adaptive Security Appliance REST API Plugin.

Nòt: Ajan REST API a se yon aplikasyon ki baze sou Java. Java Runtime Environment (JRE) yo mete nan pake Ajan REST API a.

Gid pou Itilizasyon

Enpòtan Ou dwe mete header Itilizatè-Ajan: REST API Agent nan tout apèl API ak scripts ki egziste deja. Sèvi ak -H 'Itilizatè-Ajan: REST API Agent' pou CURL kòmandman. Nan mòd milti-kontèks, kòmandman Ajan REST API yo disponib sèlman nan kontèks Sistèm.

Gwosè Konfigirasyon Maksimòm Sipòte

ASA Rest API a se yon aplikasyon "abò" ki kouri andedan ASA fizik la, e kòm sa li gen yon limit sou memwa ki afekte li. Gwosè maksimòm konfigirasyon kouri sipòte ogmante sou sik lage a apeprè 2 MB sou platfòm ki sot pase yo tankou 5555 ak 5585. ASA Rest API tou gen kontrent memwa sou platfòm vityèl ASA yo. Memwa total sou ASAv5 a ka 1.5 GB, pandan y ap sou ASAv10 li se 2 GB. Limit API Rest yo se 450 KB ak 500 KB pou ASAv5 ak ASAv10, respektivman.

Se poutèt sa, ou dwe konnen ke konfigirasyon gwo kouri ka pwodwi eksepsyon nan divès sitiyasyon memwa-entansif tankou yon gwo kantite demann konkouran, oswa volim demann gwo. Nan sitiyasyon sa yo, apèl Rest API GET/PUT/POST ka kòmanse echwe ak 500 - Mesaj Erè Sèvè Entèn yo, epi Ajan Rest API a ap rekòmanse otomatikman chak fwa. Solisyon yo nan sitiyasyon sa a se swa deplase nan pi wo memwa ASA/FPR oswa ASAV platfòm, oswa redwi gwosè a nan konfigirasyon an kouri.

Telechaje ak Enstale Ajan API REST la

Sèvi ak CLI a, swiv etap sa yo pou telechaje ak enstale ajan ASA REST API sou yon ASA espesifik:

  • Etap 1: Sou ASA vle a, bay kopi a disk0: kòmand pou telechaje pake aktyèl ASA REST API soti nan cisco.com nan memwa flash ASA a.
    • Pou egzanpample: kopi tftp://10.7.0.80/asa-restapi-111-lfbff-k8.SPA disk0:
  • Etap 2: Mete disk imaj rès-api a:/ lòd pou verifye ak enstale pake a.
    • Pou egzanpample: rest-api imaj disk0:/asa-restapi-111-lfbff-k8.SPA

Enstalatè a pral fè chèk konpatibilite ak validation, ak Lè sa a, enstale pake a. ASA a pa pral rdemare.

Aktive Ajan API REST la

Swiv etap sa yo pou pèmèt ASA REST API Agent sou yon ASA espesifik:

  • Etap 1: Asire ke imaj lojisyèl kòrèk la enstale sou ASA la.
  • Etap 2: Sèvi ak CLI a, asire sèvè HTTP a aktive sou ASA a, epi kliyan API yo ka konekte ak koòdone jesyon an.
    • Pou egzanpample: http sèvè pèmèt
    • http 0.0.0.0 0.0.0.0
  • Etap 3: Sèvi ak CLI a, defini otantifikasyon HTTP pou koneksyon API yo. Pou egzanpample: aaa otantifikasyon http konsole LOCAL
  • Etap 4: Sèvi ak CLI a, kreye yon wout estatik sou ASA a pou trafik API. Pou egzanpample: wout 0.0.0.0 0.0.0.0 1
  • Etap 5: Sèvi ak CLI a, pèmèt ASA REST API Agent sou ASA la. Pou egzanpample: rès-api ajan

Otantifikasyon API REST

Gen de fason pou otantifye: Otantifikasyon debaz HTTP, ki pase yon non itilizatè ak modpas nan chak demann, oswa otantifikasyon ki baze sou Token ak transpò HTTPS an sekirite, ki pase yon siy ki te kreye anvan ak chak demann. Nenpòt fason, otantifikasyon yo pral fèt pou chak demann. Gade seksyon "Token_Authentication_API" nan gid sou ASA REST API v7.14(x) pou plis enfòmasyon sou otantifikasyon ki baze sou Token.

Nòt: Yo rekòmande pou sèvi ak sètifika Otorite Sètifika (CA) ki bay sou ASA, kidonk kliyan REST API yo ka valide sètifika sèvè ASA yo lè yo etabli koneksyon SSL.

Otorizasyon kòmand

Si otorizasyon kòmand yo configuré pou itilize yon sèvè AAA ekstèn (pa egzanpample, aaa lòd otorizasyon ), Lè sa a, yon itilizatè ki rele enable_1 dwe egziste sou sèvè sa a ak tout privilèj kòmand. Si otorizasyon kòmand yo configuré pou itilize baz done LOCAL ASA a (aaa otorizasyon kòmand LOCAL), lè sa a tout itilizatè REST API yo dwe anrejistre nan baz done LOCAL ak nivo privilèj ki apwopriye pou wòl yo:

  • Nivo privilèj 3 oswa plis obligatwa pou envoke demann siveyans.
  • Nivo privilèj 5 oswa plis obligatwa pou envoke demann GET.
  • Nivo privilèj 15 nesesè pou envoke operasyon PUT/POST/DELETE.

Konfigirasyon Kliyan REST API ou a

Swiv etap sa yo pou enstale ak konfigirasyon yon kliyan REST API sou navigatè lokal ou a:

  • Etap 1: Jwenn ak enstale yon kliyan REST API pou navigatè w la.
    • Pou Chrome, enstale kliyan REST nan Google. Pou Firefox, enstale sipleman RESTClient la. Internet Explorer pa sipòte.
  • Etap 2: Kòmanse demann sa a lè l sèvi avèk navigatè ou a: https: /api/objects/networkobjects
    • Si w resevwa yon repons ki pa gen erè, ou jwenn ajan REST API k ap fonksyone sou ASA.
    • Si w gen pwoblèm ak demann ajan an, ou ka pèmèt ekspozisyon enfòmasyon debogaj sou konsole CLI a, jan sa dekri nan Pèmèt REST API debogaj sou ASA la.
  • Etap 3: Opsyonèlman, ou ka teste koneksyon ou a ASA a lè w fè yon operasyon POST.

Pou egzanpample: Bay kalifikasyon otorizasyon debaz yo ( ), oswa yon siy otantifikasyon (gade Otantifikasyon siy pou plis enfòmasyon).

  • Adrès demann sib: https://<asa management ipaddress>/api/objects/networkobjects
  • Kalite kontni kò: aplikasyon/json

Kò anvan tout koreksyon nan operasyon an:

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

Kounye a ou ka itilize API ASA REST pou konfigirasyon ak kontwole ASA. Gade dokiman API a pou deskripsyon apèl yo ak egzanpamples.

Konsènan Retabli Konplètman yon Konfigirasyon Back-up

Retabli yon konfigirasyon backup konplè sou ASA lè l sèvi avèk API REST la pral rechaje ASA la. Pou evite sa a, sèvi ak lòd sa a pou retabli yon konfigirasyon back-up:

  • {
    • "kòmand":["kopi /noconfirm disk0:/filenon> running-config"]
  • }
    • Ki kotefilename> se backup.cfg oswa kèlkeswa non ou te itilize lè fè bak konfigirasyon an.

Konsole dokimantasyon an ak ekspòte Scripts API

Ou kapab tou itilize REST API konsole dokimantasyon sou entènèt la (ki refere kòm "Doc UI"), ki disponib nan host:port/doc/ kòm yon "sandbox" pou aprann sou epi eseye apèl API yo dirèkteman sou ASA. Anplis de sa, ou ka itilize bouton Operasyon ekspòtasyon an nan Doc UI pou sove metòd ki parèt eksample kòm yon script JavaScript, Python, oswa Perl file bay lame lokal ou a. Lè sa a, ou ka aplike script sa a nan ASA ou a, epi modifye li pou aplikasyon sou lòt ASA ak lòt aparèy rezo. Sa vle di prensipalman kòm yon zouti edikasyon ak bootstrapping.

JavaScript

  • Sèvi ak yon JavaScript file mande pou enstalasyon node.js, ki ka jwenn nan http://nodejs.org/.
  • Sèvi ak node.js, ou ka egzekite yon JavaScript file, tipikman ekri pou yon navigatè, tankou yon script liy kòmand. Senpleman swiv enstriksyon enstalasyon yo, ak Lè sa a, kouri script ou a ak node script.js.

Piton

  • Scripts Python yo mande pou ou enstale Python, ki disponib nan https://www.python.org/.
  • Yon fwa ou te enstale Python, ou ka kouri script ou a ak modpas non itilizatè script.py python.

Perl

Sèvi ak scripts Perl yo mande pou kèk konfigirasyon adisyonèl—ou bezwen senk eleman: Perl tèt li, ak kat bibliyotèk Perl:

Isit la se yon ansyenampchiyè pou demaraj Perl sou yon Macintosh:

  • $ sudo perl -MCPAN e shell
  • cpan> enstale Bundle::CPAN
  • cpan> enstale REST:: Kliyan
  • cpan> enstale MIME::Base64
  • cpan> enstale JSON

Apre enstale depandans yo, ou ka kouri script ou a lè l sèvi avèk modpas non itilizatè perl script.pl.

Pèmèt REST API debogaj sou ASA la

Si w gen pwoblèm pou konfigirasyon oswa konekte ak REST API sou ASA a, ou ka itilize kòmandman CLI sa a pou pèmèt ekspozisyon mesaj debogaj sou konsole w la. Sèvi ak okenn fòm lòd la pou enfim mesaj debug yo.
debug rest-api [ajan | cli | kliyan | demon | pwosesis | token-auth] [erè | evènman] pa gen debug rest-api

Deskripsyon sentaks

  • ajan: (Si ou vle) Pèmèt enfòmasyon debogaj ajan REST API.
  • cli: (Si ou vle) Pèmèt mesaj debogaj pou kominikasyon REST API CLI Daemon-to-Agent.
  • kliyan: (Si ou vle) Pèmèt enfòmasyon debogaj pou routage Mesaj ant Kliyan REST API a ak Ajan REST API a.
  • demon: (Si ou vle) Pèmèt mesaj debogaj pou kominikasyon REST API Daemon-to-Agent.
  • pwosesis: (Si ou vle) Pèmèt REST API Ajan pwosesis kòmanse/sispann enfòmasyon debogaj.
  • token-auth: (Si ou vle) REST API token otantifikasyon enfòmasyon debogaj.
  • erè: (Si ou vle) Sèvi ak mo kle sa a pou limite mesaj debug pou sèlman erè API anrejistre.
  • evènman: (Si ou vle) Sèvi ak mo kle sa a pou limite mesaj debug sèlman nan evènman API a anrejistre.

Gid pou Itilizasyon

Si ou pa bay yon mo kle eleman espesifik (ki se, si ou tou senpleman bay lòd debug rest-api a), mesaj debug yo parèt pou tout kalite eleman. Si ou pa bay mo kle evènman an oswa erè, tou de mesaj evènman ak erè yo parèt pou eleman espesifye a. Pou egzanpample, evènman debug rest-api daemon pral montre sèlman mesaj debug evènman pou kominikasyon API Daemon-to-Agent.

Kòmandman ki gen rapò

Kòmand / Deskripsyon

  • debug HTTP; Sèvi ak lòd sa a pou view enfòmasyon detaye sou trafik HTTP.

Mesaj Syslog ki gen rapò ak API ASA REST

ASA REST API ki gen rapò ak sistèm-log mesaj yo dekri nan seksyon sa a.

342001

  • Mesaj erè: ASA-7-342001: Ajan REST API te kòmanse avèk siksè.
    • Eksplikasyon: Ajan REST API dwe kòmanse avèk siksè anvan yon Kliyan REST API ka konfigirasyon ASA.
    • Aksyon Rekòmande: Okenn.

342002

  • Mesaj erè: %ASA-3-342002: Ajan REST API echwe, rezon: rezon
    • Eksplikasyon: Ajan REST API a ka echwe pou kòmanse oswa aksidan pou plizyè rezon, epi rezon ki fè yo espesifye.
    • rezon—Koz echèk API REST la

Aksyon Rekòmande: Aksyon yo pran pou rezoud pwoblèm nan varye selon rezon ki fè yo konekte. Pou egzanpampLè sa a, Ajan API REST la fè aksidan lè pwosesis Java a fini nan memwa. Si sa rive, ou bezwen rekòmanse Ajan REST API a. Si rekòmanse a pa reyisi, kontakte Cisco TAC pou idantifye kòz rasin lan.

342003

  • Mesaj erè: %ASA-3-342003: Ajan REST API resevwa notifikasyon echèk. Ajan an pral rekòmanse otomatikman.
    • Eksplikasyon: Yo te resevwa yon notifikasyon echèk nan men Ajan REST API a epi yo te eseye rekòmanse Ajan an.
    • Aksyon Rekòmande: Okenn.

342004

  • Mesaj erè: %ASA-3-342004: Echwe pou otomatikman rekòmanse Ajan REST API a apre 5 tantativ san siksè. Sèvi ak kòmandman 'pa gen okenn ajan rès-api' ak 'ajan rès-api' pou rekòmanse Ajan an manyèlman.
    • Eksplikasyon: Ajan REST API a echwe pou kòmanse apre anpil tantativ.
    • Aksyon Rekòmande: Gade syslog %ASA-3-342002 (si konekte) pou pi byen konprann rezon ki fè echèk la. Eseye enfim Ajan REST API a lè w antre kòmandman pa ajan rest-api a epi re-aktive Ajan REST API a lè l sèvi avèk kòmand ajan rest-api a.

Dokiman ki gen rapò

Sèvi ak lyen sa a pou jwenn plis enfòmasyon sou ASA, ak konfigirasyon ak jesyon li yo:

Dokiman sa a dwe itilize ansanm ak dokiman ki disponib nan seksyon "Dokimantasyon ki gen rapò".
Cisco ak logo Cisco a se mak komèsyal oswa mak anrejistre Cisco ak/oswa afilye li yo nan peyi Etazini ak lòt peyi yo. Pou view yon lis mak Cisco, ale nan sa a URL: www.cisco.com/go/trademarks. Mak twazyèm pati mansyone yo se pwopriyete pwopriyetè respektif yo. Itilizasyon mo patnè a pa vle di yon relasyon patenarya ant Cisco ak nenpòt lòt konpayi. (1721R)
Nenpòt adrès Pwotokòl Entènèt (IP) ak nimewo telefòn yo itilize nan dokiman sa a pa fèt pou adrès ak nimewo telefòn aktyèl yo. Nenpòt ansyenamples, pwodiksyon ekspozisyon lòd, dyagram topoloji rezo a, ak lòt figi ki enkli nan dokiman an yo montre pou rezon ilistrasyon sèlman.
Nenpòt itilizasyon adrès IP aktyèl oswa nimewo telefòn nan kontni ilistrasyon se envolontè ak koensidans.

Cisco Systems, Inc.

© 2014-2018 Cisco Systems, Inc. Tout dwa rezève.

Dokiman / Resous

CISCO ASA REST API App [pdfGid Itilizatè
ASA REST API App, ASA, REST API App, API App, App

Referans

Kite yon kòmantè

Adrès imel ou p ap pibliye. Jaden obligatwa yo make *