CISCO ASA REST API App Pandhuan pangguna

Isine ndhelikake

1 CISCO ASA REST API App

2 Product Nggunakake Instructions

3 Swaraview

4 Panjaluk lan Tanggapan ASA REST API

5 Instal lan Konfigurasi Agen lan Klien ASA REST API

6 Konsol Dokumentasi lan Ekspor Skrip API

7 Ngaktifake REST API Debugging ing ASA

8 Pesen Syslog sing gegandhengan karo ASA REST API

9 Dokumentasi sing gegandhengan

10 Dokumen / Sumber Daya

10.1 Referensi

CISCO ASA REST API App

Product Nggunakake Instructions

Swaraview

Kanthi release saka Cisco ASA REST API, sampeyan saiki duwe liyane entheng, gampang kanggo nggunakake pilihan kanggo konfigurasi lan ngatur Cisco ASA individu. ASA REST API minangka antarmuka pemrograman aplikasi (API) adhedhasar prinsip RESTful. Bisa diundhuh lan diaktifake kanthi cepet ing sembarang ASA ing ngendi API kasebut mlaku. Cisco Systems, Inc.

www.cisco.com

Panjaluk lan Tanggapan ASA REST API

Sawise nginstal klien REST ing browser sampeyan, sampeyan bisa ngubungi agen REST ASA tartamtu lan nggunakake metode HTTP standar kanggo ngakses informasi konfigurasi saiki lan ngetokake parameter konfigurasi tambahan.

Ati-ati: Nalika REST API diaktifake ing ASA, sambungan dening protokol manajemen keamanan liyane ora diblokir. Iki tegese wong liya sing nggunakake CLI, ASDM, utawa Manajer Keamanan bisa ngganti konfigurasi ASA nalika sampeyan nindakake perkara sing padha.

Struktur Panjaluk

ing ngendi sifat obyek kasebut:

Properti	Jinis	Katrangan
pesen	Dhaptar Kamus	Dhaptar pesen kesalahan utawa bebaya
kode	String	Pesen rinci sing cocog karo Kesalahan / Pènget / Info
rincian	String	Pesen rinci sing cocog karo Kesalahan / Pènget / Info

Cathetan: Owah-owahan sing digawe dening REST API telpon ora tetep kanggo konfigurasi wiwitan nanging diutus mung kanggo konfigurasi mlaku. Kanggo nyimpen owah-owahan ing konfigurasi wiwitan, sampeyan bisa nggunakake POST a nulis request API mem. Kanggo informasi luwih lengkap, waca entri Tulis Memori API ing Babagan tabel isi ASA REST API.

Instal lan Konfigurasi Agen lan Klien ASA REST API

Cathetan: Agen API REST minangka aplikasi basis Java. Java Runtime Environment (JRE) dibundel ing paket REST API Agent.

Swaraview

Sawetara opsi kasedhiya kanggo ngatur lan ngatur ASA Cisco individu:

Command Line Interface (CLI) - sampeyan ngirim printah kontrol langsung menyang ASA liwat console disambungake.

Adaptive Security Device Manager (ASDM) - aplikasi manajemen "on-box" kanthi antarmuka pangguna grafis sing bisa digunakake kanggo ngatur, ngatur lan ngawasi ASA.
Cisco Security Manager - nalika dimaksudaké kanggo medium kanggo jaringan gedhe saka akeh piranti keamanan, aplikasi grafis iki bisa digunakake kanggo ngatur, ngatur lan ngawasi ASA individu.

Kanthi release saka Cisco ASA REST API, sampeyan saiki duwe liyane entheng, gampang kanggo nggunakake pilihan. Iki minangka antarmuka pemrograman aplikasi (API), adhedhasar prinsip "RESTful", sing bisa didownload kanthi cepet lan aktif ing ASA apa wae sing API kasebut mlaku.

Sawise nginstal klien REST ing browser sampeyan, sampeyan bisa ngubungi agen REST ASA tartamtu lan nggunakake metode HTTP standar kanggo ngakses informasi konfigurasi saiki, lan ngetokake parameter konfigurasi tambahan.

Panjaluk lan Tanggapan ASA REST API

ASA REST API menehi akses program kanggo ngatur ASA individu liwat Representational State Transfer (REST) API. API ngidini klien eksternal nindakake operasi CRUD (Gawe, Maca, Nganyari, Busak) ing sumber daya ASA; iku adhedhasar protokol HTTPS lan metodologi REST. Kabeh panjalukan API dikirim liwat HTTPS menyang ASA, lan respon dibalekake. Bagian iki menehi liwatview babagan carane panjalukan disusun, lan tanggapan sing dikarepake,

Struktur Panjaluk

Cara panyuwunan sing kasedhiya yaiku:

GET - Njupuk data saka obyek sing ditemtokake.
PUT - Nambah informasi sing diwenehake menyang obyek sing ditemtokake; ngasilake kesalahan 404 Resource Not Found yen obyek ora ana.

POST - Nggawe obyek kanthi informasi sing diwenehake.
DELETE - Mbusak obyek sing ditemtokake.

PATCH - Aplikasi modifikasi parsial kanggo obyek kasebut.

Struktur Tanggapan

Saben panjalukan ngasilake respon HTTPS saka ASA kanthi header standar, isi respon, lan kode status.

Struktur respon bisa dadi:

LOKASI - ID sumber sing mentas digawe; mung kanggo POST-nyekel ID sumber anyar (minangka perwakilan URI).
KONTEN-JENIS - Jinis media sing nggambarake isi pesen respon; nggambarake representasi lan sintaksis saka isi pesen respon.

Saben respon kalebu status HTTP utawa kode kesalahan. Kode sing kasedhiya kalebu ing kategori iki:

20x - Kode seri rong atus nuduhake operasi sing sukses, kalebu:
- 200 OK - Tanggepan standar kanggo panjaluk sing sukses.
- 201 Digawe - Panjaluk rampung; sumber anyar digawe.
- 202 Ditampa - Panjaluk ditampa, nanging proses ora rampung.
- 204 Ora Ana Isi – Server kasil diproses panjalukan; ora ana isi sing bali.
4xx - Kode seri patang atus nuduhake kesalahan sisih klien, kalebu:
- 400 Bad Request – Paramèter pitakon ora sah, kalebu paramèter sing ora dingerteni, paramèter sing ilang, utawa nilai sing ora sah.
- 404 Ora Ditemokake - Sing kasedhiya URL ora cocog karo sumber daya sing ana. Kanggo exampNanging, HTTP DELETE bisa gagal amarga sumber daya ora kasedhiya.
- Cara 405 Ora Diidini - Panjaluk HTTP diwenehake sing ora diidini ing sumber; kanggo example, POST ing sumber mung diwaca.
5xx - Kode seri limang atus nuduhake kesalahan sisih server.

Yen ana kesalahan, saliyane kode kesalahan, respon bali bisa uga kalebu obyek kesalahan sing ngemot rincian liyane babagan kesalahan kasebut. Skema tanggapan kesalahan / peringatan JSON kaya ing ngisor iki:

ing ngendi sifat obyek kasebut:

Properti	Jinis	Katrangan
pesen	Dhaptar Kamus	Dhaptar pesen kesalahan utawa bebaya
kode	String	Error/Warning/Kode info
rincian	String	Pesen rinci sing cocog karo Kesalahan / Pènget / Info

Cathetan: Owah-owahan ing konfigurasi ASA digawe dening REST API telpon ora tetep kanggo konfigurasi wiwitan; iku, owah-owahan diutus mung kanggo konfigurasi mlaku. Kanggo nyimpen owah-owahan ing konfigurasi wiwitan, sampeyan bisa POST request API writemem; kanggo informasi luwih lengkap, tindakake "Tulis memori API" entri ing About tabel isi API REST ASA.

Instal lan Konfigurasi Agen lan Klien ASA REST API

Agen API REST diterbitake kanthi individu karo gambar ASA liyane ing cisco.com. Kanggo ASA fisik, paket REST API kudu diundhuh menyang lampu kilat piranti lan diinstal nggunakake printah "gambar rest-api". Agen API REST banjur diaktifake nggunakake printah "agen rest-api".
Kanthi ASA virtual (ASAv), gambar REST API kudu diundhuh menyang partisi "boot:". Sampeyan banjur kudu ngetokake printah "gambar rest-api", banjur printah "agen rest-api", kanggo ngakses lan ngaktifake Agen API REST.
Kanggo informasi babagan software REST API lan syarat hardware lan kompatibilitas, ndeleng Cisco ASA Compatibility matriks.

Sampeyan bisa ngundhuh paket REST API cocok kanggo ASA utawa ASAv saka software.cisco.com/download/home. Goleki model Adaptive Security Appliances (ASA) tartamtu banjur pilih Adaptive Security Appliance REST API Plugin.

Cathetan: Agen API REST minangka aplikasi basis Java. Java Runtime Environment (JRE) dibundel ing paket REST API Agent.

Pedoman Panggunaan

Penting Sampeyan kudu nyakup header User-Agent: REST API Agent ing kabeh panggilan API lan skrip sing ana. Gunakake -H 'User-Agent: REST API Agent' kanggo CURL dhawuh. Ing mode multi-konteks, perintah REST API Agen mung kasedhiya ing konteks Sistem.

Ukuran Konfigurasi sing Didhukung Maksimum

ASA Rest API minangka aplikasi "on-board" sing mlaku ing ASA fisik, lan kanthi mangkono nduweni watesan ing memori sing diwenehake. Ukuran konfigurasi mlaku maksimal sing didhukung wis tambah sajrone siklus rilis nganti kira-kira 2 MB ing platform anyar kayata 5555 lan 5585. ASA Rest API uga duwe watesan memori ing platform ASA virtual. Total memori ing ASAv5 bisa 1.5 GB, nalika ing ASAv10 iku 2 GB. Watesan Rest API yaiku 450 KB lan 500 KB kanggo ASAv5 lan ASAv10.

Mulane, weruh sing konfigurasi mlaku gedhe bisa gawé pangecualian ing macem-macem kahanan memori-intensif kayata nomer akeh panjalukan bebarengan, utawa volume request gedhe. Ing kahanan kasebut, Panggilan API GET / PUT / POST bisa uga wiwit gagal karo 500 - pesen Kesalahan Server Internal, lan Agen API Rest bakal diwiwiti maneh kanthi otomatis saben wektu. Solusi kanggo kahanan iki yaiku pindhah menyang platform ASA / FPR utawa ASAV memori sing luwih dhuwur, utawa nyuda ukuran konfigurasi sing mlaku.

Ngundhuh lan Instal Agen API REST

Nggunakake CLI, tindakake langkah iki kanggo ngundhuh lan nginstal agen ASA REST API ing ASA tartamtu:

Langkah 1: Ing ASA sing dikarepake, ngetokake salinan kasebut disk0: printah kanggo ngundhuh paket ASA REST API saiki saka cisco.com menyang memori lampu kilat ASA.
- Kanggo example: copy tftp://10.7.0.80/asa-restapi-111-lfbff-k8.SPA disk0:
Langkah 2: Nerbitake disk gambar rest-api0:/ printah kanggo verifikasi lan nginstal paket.
- Kanggo example: rest-api image disk0:/asa-restapi-111-lfbff-k8.SPA

Pemasang bakal nindakake mriksa kompatibilitas lan validasi, banjur nginstal paket kasebut. ASA ora bakal urip maneh.

Aktifake Agen API REST

Tindakake langkah iki kanggo ngaktifake Agen API REST ASA ing ASA tartamtu:

Langkah 1: Priksa manawa gambar piranti lunak sing bener wis diinstal ing ASA.
- Hubungi bagean REST API saka Matriks Kompatibilitas ASA (https://www.cisco.com/c/en/us/td/docs/security/asa/compatibility/asamatrx.html#pgfId-131643) kanggo nemtokake gambar ASA sing dibutuhake.

Langkah 2: Nggunakake CLI, priksa manawa server HTTP diaktifake ing ASA, lan klien API bisa nyambung menyang antarmuka manajemen.
- Kanggo example: http server ngaktifake
- http 0.0.0.0 0.0.0.0

Langkah 3: Nggunakake CLI, nemtokake otentikasi HTTP kanggo sambungan API. Kanggo example: aaa bukti asli http console LOCAL
Langkah 4: Nggunakake CLI, nggawe rute statis ing ASA kanggo lalu lintas API. Kanggo example: dalan 0.0.0.0 0.0.0.0 1
Langkah 5: Nggunakake CLI, aktifake ASA REST API Agen ing ASA. Kanggo example: agen rest-api

REST API Authentication

Ana rong cara kanggo otentikasi: Otentikasi HTTP dhasar, sing ngliwati jeneng pangguna lan sandhi ing saben panyuwunan, utawa otentikasi berbasis Token kanthi transportasi HTTPS sing aman, sing ngliwati token sing digawe sadurunge karo saben panyuwunan. Apa wae, otentikasi bakal ditindakake kanggo saben panyuwunan. Waca bagean, "Token_Authentication_API" ing About ASA REST API v7.14 (x) guide kanggo informasi tambahan babagan otentikasi basis Token.

Cathetan: Gunakake Certificate Authority (CA) -sertifikat ditanggepi dianjurake ing ASA, supaya REST klien API bisa ngesyahke sertifikat server ASA nalika nggawe sambungan SSL.

Izin Komando

Yen wewenang printah dikonfigurasi nggunakake server AAA eksternal (kanggo example, printah wewenang aaa ), banjur pangguna sing jenenge enable_1 kudu ana ing server kasebut kanthi hak istimewa printah lengkap. Yen wewenang printah dikonfigurasi kanggo nggunakake basis data LOKAL ASA (komando wewenang aaa LOCAL), mula kabeh pangguna REST API kudu didaftar ing basis data LOKAL kanthi tingkat hak istimewa sing cocog kanggo perane:

Tingkat hak istimewa 3 utawa luwih dibutuhake kanggo njaluk panjaluk pemantauan.

Tingkat hak istimewa 5 utawa luwih dibutuhake kanggo njaluk panjaluk GET.
Tingkat hak istimewa 15 perlu kanggo nindakake operasi PUT/POST/DELETE.

Konfigurasi Klien REST API Panjenengan

Tindakake langkah iki kanggo nginstal lan ngatur klien API REST ing browser host lokal sampeyan:

Langkah 1: Entuk lan nginstal klien API REST kanggo browser sampeyan.
- Kanggo Chrome, instal klien REST saka Google. Kanggo Firefox, instal add-on RESTClient. Internet Explorer ora didhukung.

Langkah 2: Miwiti panjalukan ing ngisor iki nggunakake browser sampeyan: https: /api/objects/networkobjects
- Yen sampeyan nampa respon non-error, sampeyan wis tekan REST API agen fungsi ing ASA.
- Yen sampeyan duwe masalah karo panjalukan agen, sampeyan bisa ngaktifake tampilan informasi debugging ing console CLI, kaya sing diterangake ing Ngaktifake REST API Debugging ing ASA.

Langkah 3: Opsional, sampeyan bisa nyoba sambungan menyang ASA kanthi nindakake operasi POST.

Kanggo example: Nyedhiyakake kredensial wewenang dhasar ( ), utawa token otentikasi (pirsani Otentikasi Token kanggo informasi tambahan).

Alamat panyuwunan target: https://<asa management ipaddress>/api/objects/networkobjects

Jinis isi awak: aplikasi/json

Badan mentahan operasi:

Sampeyan saiki bisa nggunakake ASA REST API kanggo ngatur lan ngawasi ASA. Deleng dokumentasi API kanggo katrangan telpon lan examples.

Babagan Mulihake Konfigurasi Back-up kanthi Lengkap

Mulihake konfigurasi serep lengkap ing ASA nggunakake REST API bakal mbukak maneh ASA. Kanggo ngindhari iki, gunakake printah ing ngisor iki kanggo mulihake konfigurasi serep:

{
- "commands":["copy /noconfirm disk0:/filejeneng> running-config"]
}
- ngendifilejeneng> iku backup.cfg utawa jeneng apa wae sing digunakake nalika nggawe serep konfigurasi.

Konsol Dokumentasi lan Ekspor Skrip API

Sampeyan uga bisa nggunakake konsol dokumentasi on-line API REST (disebut minangka "UI Doc"), kasedhiya ing host: port / doc / minangka "kotak wedhi" kanggo sinau lan nyoba telpon API langsung ing ASA. Salajengipun, sampeyan bisa nggunakake tombol Operasi Ekspor ing UI Doc kanggo nyimpen cara ditampilake example minangka skrip JavaScript, Python, utawa Perl file menyang host lokal sampeyan. Sampeyan banjur bisa aplikasi script iki kanggo ASA, lan ngowahi kanggo aplikasi ing ASA liyane lan piranti jaringan liyane. Iki tegese utamane minangka alat pendidikan lan bootstrap.

JavaScript

Nggunakake JavaScript file mbutuhake instalasi node.js, kang bisa ditemokaké ing http://nodejs.org/.
Nggunakake node.js, sampeyan bisa nglakokake JavaScript file, biasane ditulis kanggo browser, kaya skrip baris perintah. Mung tindakake pandhuan instalasi, banjur mbukak script karo simpul script.js.

Python

Skrip Python mbutuhake sampeyan nginstal Python, kasedhiya saka https://www.python.org/.
Sawise sampeyan wis nginstal Python, sampeyan bisa mbukak script nganggo python script.py sandi jeneng panganggo.

Perl

Nggunakake skrip Perl mbutuhake sawetara set-up tambahan-sampeyan butuh limang komponen: Perl dhewe, lan papat perpustakaan Perl:

paket Perl, ditemokaké ing http://www.perl.org/
Paket::CPAN, ditemokake ing http://search.cpan.org/~andk/Bundle-CPAN-1.861/CPAN.pm

ngaso::Klien, ditemokake ing http://search.cpan.org/~mcrawfor/REST-Client-88/lib/REST/Client.pm
MIME::Base64, ditemokaké ing http://perldoc.perl.org/MIME/Base64.html
JSON, ditemokake ing http://search.cpan.org/~makamaka/JSON-2.90/lib/JSON.pm

Iki mantanampCara bootstrap Perl ing Macintosh:

$ sudo perl -MCPAN lan cangkang
cpan> instal Paket::CPAN

cpan> instal REST:: Klien
cpan> instal MIME::Basa64
cpan> instal JSON

Sawise nginstal dependensi, sampeyan bisa mbukak script nggunakake perl script.pl sandi jeneng panganggo.

Ngaktifake REST API Debugging ing ASA

Yen sampeyan duwe masalah ing konfigurasi utawa nyambungake menyang REST API ing ASA, sampeyan bisa nggunakake printah CLI ing ngisor iki kanggo ngaktifake tampilan pesen debugging ing console. Gunakake printah ora ana kanggo mateni pesen debug.
debug rest-api [agen | cli | klien | daemon | proses | token-auth] [kesalahan | acara] ora debug rest-api

Deskripsi Sintaksis

agen: (Opsional) Aktifake informasi debugging Agen API REST.
cli: (Opsional) Aktifake pesen debugging kanggo komunikasi REST API CLI Daemon-to-Agent.
klien: (Opsional) Aktifake informasi debugging kanggo nuntun pesen antarane Klien API REST lan Agen API REST.

daemon: (Opsional) Aktifake pesen debugging kanggo komunikasi REST API Daemon-to-Agent.
proses: (Opsional) Aktifake REST API Agent proses miwiti / mungkasi informasi debugging.
token-auth: (Opsional) Informasi debugging otentikasi token REST API.

kesalahan: (Opsional) Gunakake tembung kunci iki kanggo matesi pesen debug mung kesalahan sing dicathet dening API.
acara: (Opsional) Gunakake tembung kunci iki kanggo matesi pesen debug mung acara sing dicathet dening API.

Pedoman Panggunaan

Yen sampeyan ora nyedhiyakake tembung kunci komponen tartamtu (yaiku, yen sampeyan mung ngetokake perintah debug rest-api), pesen debug ditampilake kanggo kabeh jinis komponen. Yen sampeyan ora nyedhiyakake tembung kunci acara utawa kesalahan, pesen acara lan kesalahan ditampilake kanggo komponen kasebut. Kanggo exampNanging, debug acara daemon rest-api mung bakal nuduhake pesen debug acara kanggo komunikasi API Daemon-kanggo-Agen.

Prentah sing gegandhengan

Prentah / Katrangan

debug HTTP; Gunakake printah iki kanggo view informasi rinci babagan lalu lintas HTTP.

Pesen Syslog sing gegandhengan karo ASA REST API

Pesen log sistem sing gegandhengan karo ASA REST API diterangake ing bagean iki.

342001

Pesen kesalahan: %ASA-7-342001: REST API Agen diwiwiti kanthi sukses.
- Katerangan: Agen API REST kudu diwiwiti kanthi sukses sadurunge Klien API REST bisa ngatur ASA.
- Tindakan sing Disaranake: ora ana.

342002

Pesen kesalahan: %ASA-3-342002: REST API Agen gagal, alesan: alesan
- Katerangan: Agen API REST bisa gagal miwiti utawa nabrak amarga macem-macem alasan, lan alesan kasebut ditemtokake.
- alesan-Panyebab kanggo Gagal REST API

Tindakan sing Disaranake: Tindakan sing ditindakake kanggo ngatasi masalah kasebut beda-beda gumantung saka alesan sing dicathet. Kanggo example, REST API Agen tubrukan nalika proses Jawa entek memori. Yen kedadeyan kasebut, sampeyan kudu miwiti maneh Agen API REST. Yen miwiti maneh ora sukses, hubungi Cisco TAC kanggo ngenali sabab ROOT fix.

342003

Pesen kesalahan: %ASA-3-342003: Kabar Gagal Agen API REST ditampa. Agen bakal diwiwiti maneh kanthi otomatis.
- Katerangan: Kabar kegagalan saka Agen API REST wis ditampa lan miwiti maneh Agen lagi dicoba.
- Tindakan sing Disaranake: ora ana.

342004

Pesen kesalahan: %ASA-3-342004: Gagal miwiti maneh Agen API REST kanthi otomatis sawise 5 upaya ora kasil. Gunakake perintah 'no rest-api agent' lan 'rest-api agent' kanggo miwiti maneh Agen kanthi manual.
- Katerangan: Agen API REST wis gagal diwiwiti sawise akeh upaya.
- Tindakan sing Disaranake: Waca syslog% ASA-3-342002 (yen mlebu) kanggo luwih ngerti alesan konco Gagal. Coba mateni REST API Agent kanthi ngetik perintah no rest-api agent lan aktifake maneh REST API Agent nggunakake perintah rest-api agent.

Dokumentasi sing gegandhengan

Gunakake link ing ngisor iki kanggo nemokake informasi luwih lengkap babagan ASA, lan konfigurasi lan manajemen:

Navigasi Dokumentasi Seri Cisco ASA: http://www.cisco.com/go/asadocs
Gunakake link ing ngisor iki kanggo view dhaptar fitur ASA sing ora didhukung ing ASAv: http://www.cisco.com/c/en/us/td/docs/security/asa/asa92/configuration/general/asa-general-cli/introasav.html#pgfId-1156883

Dokumen iki kudu digunakake bebarengan karo dokumen sing kasedhiya saka bagean "Dokumentasi sing Gegandhengan".
Cisco lan logo Cisco iku merek dagang utawa merek dagang kadhaptar saka Cisco lan / utawa afiliasi ing AS lan negara liyane. Kanggo view dhaftar merek dagang Cisco, menyang iki URL: www.cisco.com/go/trademarks. Merek dagang pihak katelu sing kasebut minangka properti saka pamilike. Panganggone tembung partner ora ateges hubungan kemitraan antarane Cisco lan perusahaan liyane. (1721R)
Sembarang alamat Internet Protocol (IP) lan nomer telpon sing digunakake ing dokumen iki ora dimaksudake minangka alamat lan nomer telpon sing nyata. Mantan waeamples, output tampilan printah, diagram topologi jaringan, lan tokoh liyane sing kalebu ing dokumen ditampilake mung kanggo ilustrasi.
Sembarang panggunaan alamat IP utawa nomer telpon sing nyata ing konten ilustrasi ora disengaja lan ora sengaja.

Cisco Systems, Inc.

www.cisco.com

Dokumen / Sumber Daya

CISCO ASA REST API App [pdf] Pandhuan pangguna
Aplikasi ASA REST API, ASA, Aplikasi API REST, Aplikasi API, Aplikasi

Referensi

Manual pangguna