Panduan Pengguna Aplikasi CISCO ASA REST API

Isi bersembunyi

1 Aplikasi CISCO ASA REST API

2 Petunjuk Penggunaan Produk

3 Lebihview

4 Permintaan dan Respons ASA REST API

5 Instal dan Konfigurasikan Agen dan Klien ASA REST API

6 Konsol Dokumentasi dan Mengekspor Skrip API

7 Mengaktifkan Debugging REST API di ASA

8 Pesan Syslog terkait ASA REST API

9 Dokumentasi Terkait

10 Dokumen / Sumber Daya

10.1 Referensi

Aplikasi CISCO ASA REST API

Petunjuk Penggunaan Produk

Lebihview

Dengan dirilisnya API REST ASA Cisco, kini Anda memiliki opsi lain yang ringan dan mudah digunakan untuk mengonfigurasi dan mengelola masing-masing ASA Cisco. API REST ASA adalah antarmuka pemrograman aplikasi (API) yang didasarkan pada prinsip RESTful. API ini dapat diunduh dan diaktifkan dengan cepat di ASA mana pun tempat API tersebut berjalan. Cisco Systems, Inc.

www.cisco.com

Permintaan dan Respons ASA REST API

Setelah memasang klien REST di peramban Anda, Anda dapat menghubungi agen REST ASA tertentu dan menggunakan metode HTTP standar untuk mengakses informasi konfigurasi terkini dan mengeluarkan parameter konfigurasi tambahan.

Peringatan: Bila REST API diaktifkan pada ASA, koneksi oleh protokol manajemen keamanan lainnya tidak diblokir. Ini berarti orang lain yang menggunakan CLI, ASDM, atau Security Manager dapat mengubah konfigurasi ASA saat Anda melakukan hal yang sama.

Struktur Permintaan

di mana properti objeknya adalah:

Milik	Jenis	Keterangan
pesan	Daftar Kamus	Daftar pesan kesalahan atau peringatan
kode	Rangkaian	Pesan terperinci yang sesuai dengan Kesalahan/Peringatan/Info
rincian	Rangkaian	Pesan terperinci yang sesuai dengan Kesalahan/Peringatan/Info

Catatan: Perubahan yang dibuat oleh panggilan REST API tidak disimpan ke konfigurasi startup tetapi hanya ditetapkan ke konfigurasi yang sedang berjalan. Untuk menyimpan perubahan ke konfigurasi startup, Anda dapat menggunakan permintaan API POST a write mem. Untuk informasi lebih lanjut, lihat entri Write Memory API di daftar isi Tentang ASA REST API.

Instal dan Konfigurasikan Agen dan Klien ASA REST API

Catatan: Agen REST API adalah aplikasi berbasis Java. Java Runtime Environment (JRE) disertakan dalam paket Agen REST API.

Lebihview

Beberapa opsi tersedia untuk mengonfigurasi dan mengelola Cisco ASA individual:

Antarmuka Baris Perintah (CLI) – Anda mengirim perintah kontrol langsung ke ASA melalui konsol yang terhubung.

Adaptive Security Device Manager (ASDM) – aplikasi manajemen “on-box” dengan antarmuka pengguna grafis yang dapat Anda gunakan untuk mengonfigurasi, mengelola, dan memantau ASA.
Cisco Security Manager – meskipun ditujukan untuk jaringan menengah hingga besar dengan banyak perangkat keamanan, aplikasi grafis ini dapat digunakan untuk mengonfigurasi, mengelola, dan memantau ASA individual.

Dengan dirilisnya API REST ASA Cisco, kini Anda memiliki opsi lain yang ringan dan mudah digunakan. Ini adalah antarmuka pemrograman aplikasi (API), yang didasarkan pada prinsip “RESTful”, yang dapat Anda unduh dan aktifkan dengan cepat di ASA mana pun yang menjalankan API tersebut.

Permintaan dan Respons ASA REST API

API REST ASA memberi Anda akses terprogram untuk mengelola ASA individual melalui API Representational State Transfer (REST). API ini memungkinkan klien eksternal untuk melakukan operasi CRUD (Buat, Baca, Perbarui, Hapus) pada sumber daya ASA; API ini didasarkan pada protokol HTTPS dan metodologi REST. Semua permintaan API dikirim melalui HTTPS ke ASA, dan respons dikembalikan. Bagian ini menyediakanview tentang bagaimana permintaan disusun, dan tanggapan yang diharapkan,

Struktur Permintaan

Metode permintaan yang tersedia adalah:

GET – Mengambil data dari objek yang ditentukan.
PUT – Menambahkan informasi yang diberikan ke objek yang ditentukan; mengembalikan kesalahan 404 Resource Not Found jika objek tersebut tidak ada.

POST – Membuat objek dengan informasi yang diberikan.
HAPUS – Menghapus objek yang ditentukan.

PATCH – Menerapkan modifikasi parsial pada objek yang ditentukan.

Struktur Respons

Setiap permintaan menghasilkan respons HTTPS dari ASA dengan header standar, konten respons, dan kode status.

Struktur responsnya bisa berupa:

LOKASI – ID sumber daya yang baru dibuat; hanya untuk POST—menampung ID sumber daya baru (sebagai representasi URI).
JENIS KONTEN – Jenis media yang menjelaskan isi pesan respons; menjelaskan representasi dan sintaksis isi pesan respons.

Setiap respons menyertakan status HTTP atau kode kesalahan. Kode yang tersedia terbagi dalam kategori berikut:

20x – Kode seri dua ratus menunjukkan operasi yang berhasil, termasuk:
- 200 OK – Respons standar untuk permintaan yang berhasil.
- 201 Dibuat – Permintaan selesai; sumber daya baru dibuat.
- 202 Diterima – Permintaan diterima, tetapi pemrosesan belum selesai.
- 204 Tidak Ada Konten – Server berhasil memproses permintaan; tidak ada konten yang dikembalikan.
4xx – Kode seri empat ratus menunjukkan kesalahan sisi klien, termasuk:
- 400 Permintaan Buruk – Parameter kueri tidak valid, termasuk parameter yang tidak dikenal, parameter yang hilang, atau nilai yang tidak valid.
- 404 Tidak Ditemukan – Disediakan URL tidak cocok dengan sumber daya yang ada. Misalnyaample, HTTP DELETE mungkin gagal karena sumber daya tidak tersedia.
- 405 Metode Tidak Diizinkan – Permintaan HTTP yang diajukan tidak diizinkan pada sumber daya; misalnyaample, POST pada sumber daya hanya-baca.
5xx – Kode seri lima ratus menunjukkan kesalahan sisi server.

Jika terjadi kesalahan, selain kode kesalahan, respons yang dikembalikan dapat menyertakan objek kesalahan yang berisi detail lebih lanjut tentang kesalahan tersebut. Skema respons kesalahan/peringatan JSON adalah sebagai berikut:

di mana properti objeknya adalah:

Milik	Jenis	Keterangan
pesan	Daftar Kamus	Daftar pesan kesalahan atau peringatan
kode	Rangkaian	Kode kesalahan/peringatan/info
rincian	Rangkaian	Pesan terperinci yang sesuai dengan Kesalahan/Peringatan/Info

Catatan: Perubahan pada konfigurasi ASA yang dibuat oleh panggilan REST API tidak disimpan ke konfigurasi startup; artinya, perubahan hanya ditetapkan ke konfigurasi yang sedang berjalan. Untuk menyimpan perubahan pada konfigurasi startup, Anda dapat melakukan POST permintaan API writemem; untuk informasi lebih lanjut, ikuti entri “Write Memory API” di daftar isi Tentang REST API ASA.

Instal dan Konfigurasikan Agen dan Klien ASA REST API

Agen REST API diterbitkan secara individual dengan gambar ASA lainnya di cisco.com. Untuk ASA fisik, paket REST API harus diunduh ke flash perangkat dan diinstal menggunakan perintah “rest-api image”. Agen REST API kemudian diaktifkan menggunakan perintah “rest-api agent”.
Dengan ASA virtual (ASAv), citra REST API harus diunduh ke partisi “boot:”. Anda kemudian harus mengeluarkan perintah “rest-api image”, diikuti oleh perintah “rest-api agent”, untuk mengakses dan mengaktifkan Agen REST API.
Untuk informasi tentang persyaratan dan kompatibilitas perangkat lunak dan perangkat keras REST API, lihat matriks Kompatibilitas Cisco ASA.

Anda dapat mengunduh paket REST API yang sesuai untuk ASA atau ASAv Anda dari perangkat lunak.cisco.com/download/homeTemukan model Adaptive Security Appliances (ASA) tertentu, lalu pilih Plugin REST API Adaptive Security Appliance.

Catatan: Agen REST API adalah aplikasi berbasis Java. Java Runtime Environment (JRE) disertakan dalam paket Agen REST API.

Pedoman Penggunaan

Penting Anda harus menyertakan header User-Agent: REST API Agent di semua panggilan API dan skrip yang ada. Gunakan -H 'User-Agent: REST API Agent' untuk CURL perintah. Dalam mode multikonteks, perintah Agen REST API hanya tersedia dalam konteks Sistem.

Ukuran Konfigurasi Maksimum yang Didukung

ASA Rest API adalah aplikasi "on-board" yang berjalan di dalam ASA fisik, dan karenanya memiliki batasan pada memori yang dialokasikan untuknya. Ukuran konfigurasi berjalan maksimum yang didukung telah meningkat selama siklus rilis menjadi sekitar 2 MB pada platform terkini seperti 5555 dan 5585. ASA Rest API juga memiliki batasan memori pada platform ASA virtual. Total memori pada ASAv5 dapat mencapai 1.5 GB, sedangkan pada ASAv10 adalah 2 GB. Batasan Rest API adalah 450 KB dan 500 KB untuk ASAv5 dan ASAv10.

Oleh karena itu, perlu diketahui bahwa konfigurasi berjalan yang besar dapat menghasilkan pengecualian dalam berbagai situasi yang membutuhkan banyak memori seperti sejumlah besar permintaan bersamaan, atau volume permintaan yang besar. Dalam situasi ini, panggilan Rest API GET/PUT/POST mungkin mulai gagal dengan pesan 500 – Internal Server Error, dan Agen Rest API akan memulai ulang secara otomatis setiap saat. Solusi untuk situasi ini adalah dengan beralih ke platform ASA/FPR atau ASAV dengan memori yang lebih tinggi, atau mengurangi ukuran konfigurasi yang berjalan.

Unduh dan Instal Agen REST API

Dengan menggunakan CLI, ikuti langkah-langkah berikut untuk mengunduh dan menginstal agen ASA REST API pada ASA tertentu:

Langkah 1: Pada ASA yang diinginkan, terbitkan salinannya disk0: perintah untuk mengunduh paket ASA REST API saat ini dari cisco.com ke memori flash ASA.
- Misalnyaampsaya: salin tftp://10.7.0.80/asa-restapi-111-lfbff-k8.SPA disk0:
Langkah 2: Terbitkan image rest-api disk0:/ perintah untuk memverifikasi dan menginstal paket.
- Misalnyaampsaya: gambar rest-api disk0:/asa-restapi-111-lfbff-k8.SPA

Penginstal akan melakukan pemeriksaan kompatibilitas dan validasi, lalu menginstal paket tersebut. ASA tidak akan melakukan boot ulang.

Aktifkan Agen REST API

Ikuti langkah-langkah berikut untuk mengaktifkan Agen ASA REST API pada ASA tertentu:

Langkah 1: Pastikan citra perangkat lunak yang benar terinstal pada ASA.
- Konsultasikan bagian REST API dari Matriks Kompatibilitas ASA (https://www.cisco.com/c/en/us/td/docs/security/asa/compatibility/asamatrx.html#pgfId-131643) untuk menentukan gambar ASA mana yang diperlukan.

Langkah 2: Menggunakan CLI, pastikan server HTTP diaktifkan pada ASA, dan klien API dapat terhubung ke antarmuka manajemen.
- Misalnyaampsaya: server http diaktifkan
- http://0.0.0.0 0.0.0.0

Langkah 3: Menggunakan CLI, tentukan autentikasi HTTP untuk koneksi API. Misalnyaample: aaa otentikasi http konsol LOKAL
Langkah 4: Menggunakan CLI, buat rute statis pada ASA untuk lalu lintas API. Misalnyaample: rute 0.0.0.0 0.0.0.0 1
Langkah 5: Menggunakan CLI, aktifkan Agen ASA REST API di ASA. Misalnyaample: agen rest-api

Otentikasi REST API

Ada dua cara untuk melakukan autentikasi: Autentikasi HTTP dasar, yang meneruskan nama pengguna dan kata sandi di setiap permintaan, atau autentikasi berbasis token dengan transportasi HTTPS aman, yang meneruskan token yang dibuat sebelumnya di setiap permintaan. Apa pun cara yang dipilih, autentikasi akan dilakukan untuk setiap permintaan. Lihat bagian, “Token_Authentication_API” di panduan Tentang ASA REST API v7.14(x) untuk informasi tambahan tentang autentikasi berbasis token.

Catatan: Penggunaan sertifikat yang dikeluarkan Otoritas Sertifikat (CA) direkomendasikan pada ASA, sehingga klien REST API dapat memvalidasi sertifikat server ASA saat membuat koneksi SSL.

Otorisasi Perintah

Jika otorisasi perintah dikonfigurasi untuk menggunakan server AAA eksternal (misalnyaample, perintah otorisasi aaa ), maka pengguna bernama enable_1 harus ada di server tersebut dengan hak istimewa perintah penuh. Jika otorisasi perintah dikonfigurasi untuk menggunakan basis data LOCAL ASA (perintah otorisasi aaa LOCAL), maka semua pengguna REST API harus terdaftar di basis data LOCAL dengan tingkat hak istimewa yang sesuai untuk peran mereka:

Tingkat hak istimewa 3 atau lebih tinggi diperlukan untuk menjalankan permintaan pemantauan.

Tingkat hak istimewa 5 atau lebih tinggi diperlukan untuk menjalankan permintaan GET.
Tingkat hak istimewa 15 diperlukan untuk menjalankan operasi PUT/POST/DELETE.

Konfigurasikan Klien REST API Anda

Ikuti langkah-langkah berikut untuk menginstal dan mengonfigurasi klien REST API di browser host lokal Anda:

Langkah 1: Dapatkan dan instal klien REST API untuk peramban Anda.
- Untuk Chrome, instal klien REST dari Google. Untuk Firefox, instal add-on RESTClient. Internet Explorer tidak didukung.

Langkah 2: Mulailah permintaan berikut menggunakan browser Anda: https: /api/objek/objekjaringan
- Jika Anda menerima respons tanpa kesalahan, Anda telah mencapai agen REST API yang berfungsi di ASA.
- Jika Anda mengalami masalah dengan permintaan agen, Anda dapat mengaktifkan tampilan informasi debugging pada konsol CLI, seperti yang dijelaskan dalam Mengaktifkan Debugging REST API pada ASA.

Langkah 3: Secara opsional, Anda dapat menguji koneksi Anda ke ASA dengan melakukan operasi POST.

Misalnyaampsaya: Berikan kredensial otorisasi dasar ( ), atau token autentikasi (lihat Autentikasi Token untuk informasi tambahan).

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

Jenis isi tubuh: aplikasi / json

Tubuh mentah dari operasi:

Anda sekarang dapat menggunakan ASA REST API untuk mengonfigurasi dan memantau ASA. Lihat dokumentasi API untuk deskripsi panggilan dan contohampsedikit.

Tentang Memulihkan Konfigurasi Cadangan Secara Penuh

Memulihkan konfigurasi cadangan penuh pada ASA menggunakan REST API akan memuat ulang ASA. Untuk menghindari hal ini, gunakan perintah berikut untuk memulihkan konfigurasi cadangan:

{
- “perintah”:[“salin /noconfirm disk0:/filenama> konfigurasi-berjalan”]
}
- Di manafilenama> adalah backup.cfg atau nama apa pun yang Anda gunakan saat mencadangkan konfigurasi.

Konsol Dokumentasi dan Mengekspor Skrip API

Anda juga dapat menggunakan konsol dokumentasi daring REST API (disebut sebagai “UI Dokumen”), tersedia di host:port/doc/ sebagai “kotak pasir” untuk mempelajari dan mencoba panggilan API secara langsung di ASA. Lebih jauh, Anda dapat menggunakan tombol Operasi Ekspor di UI Dokumen untuk menyimpan metode yang ditampilkanample sebagai skrip JavaScript, Python, atau Perl file ke host lokal Anda. Anda kemudian dapat menerapkan skrip ini ke ASA Anda, dan mengeditnya untuk aplikasi pada ASA lain dan perangkat jaringan lainnya. Ini dimaksudkan terutama sebagai alat pendidikan dan bootstrapping.

Bahasa Indonesia: JavaScript

Menggunakan JavaScript file membutuhkan instalasi node.js, yang dapat ditemukan di http://nodejs.org/.
Dengan menggunakan node.js, Anda dapat menjalankan JavaScript file, biasanya ditulis untuk browser, seperti skrip baris perintah. Cukup ikuti petunjuk instalasi, lalu jalankan skrip Anda dengan node script.js.

Ular piton

Skrip Python mengharuskan Anda menginstal Python, tersedia dari https://www.python.org/.
Setelah Anda menginstal Python, Anda dapat menjalankan skrip Anda dengan nama pengguna dan kata sandi python script.py.

Bahasa Inggris Perl

Penggunaan skrip Perl memerlukan beberapa pengaturan tambahan—Anda memerlukan lima komponen: Perl itu sendiri, dan empat pustaka Perl:

Paket Perl, ditemukan di http://www.perl.org/
Bundel::CPAN, ditemukan di http://search.cpan.org/~andk/Bundle-CPAN-1.861/CPAN.pm

ISTIRAHAT::Klien, ditemukan di http://search.cpan.org/~mcrawfor/REST-Client-88/lib/REST/Client.pm
PANTOMIM::Base64, ditemukan di http://perldoc.perl.org/MIME/Base64.html
JSON, ditemukan di http://search.cpan.org/~makamaka/JSON-2.90/lib/JSON.pm

Ini adalah mantanampcontoh bootstrapping Perl pada Macintosh:

$ sudo perl -MCPAN dan shell
cpan> instal Bundel::CPAN

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

Setelah menginstal dependensi, Anda dapat menjalankan skrip Anda menggunakan nama pengguna dan kata sandi perl script.pl.

Mengaktifkan Debugging REST API di ASA

Jika Anda mengalami masalah saat mengonfigurasi atau menghubungkan ke REST API di ASA, Anda dapat menggunakan perintah CLI berikut untuk mengaktifkan tampilan pesan debugging di konsol Anda. Gunakan bentuk no dari perintah tersebut untuk menonaktifkan pesan debug.
debug rest-api [agen | cli | klien | daemon | proses | token-auth] [kesalahan | acara] tidak ada debug rest-api

Deskripsi Sintaks

agen: (Opsional) Aktifkan informasi debugging Agen REST API.
kli: (Opsional) Aktifkan pesan debugging untuk komunikasi Daemon-ke-Agen REST API CLI.
klien: (Opsional) Aktifkan informasi debugging untuk Perutean Pesan antara Klien REST API dan Agen REST API.

setan: (Opsional) Aktifkan pesan debugging untuk komunikasi Daemon-ke-Agen REST API.
proses: (Opsional) Aktifkan informasi debugging mulai/hentikan proses Agen REST API.
token-otentikasi: (Opsional) Informasi debugging autentikasi token REST API.

kesalahan: (Opsional) Gunakan kata kunci ini untuk membatasi pesan debug hanya pada kesalahan yang dicatat oleh API.
peristiwa: (Opsional) Gunakan kata kunci ini untuk membatasi pesan debug hanya pada peristiwa yang dicatat oleh API.

Pedoman Penggunaan

Jika Anda tidak memberikan kata kunci komponen tertentu (yaitu, jika Anda hanya mengeluarkan perintah debug rest-api), pesan debug akan ditampilkan untuk semua jenis komponen. Jika Anda tidak memberikan kata kunci event atau error, pesan event dan error akan ditampilkan untuk komponen yang ditentukan. Misalnyaample, debug rest-api daemon event hanya akan menampilkan pesan debug event untuk komunikasi API Daemon-ke-Agen.

Perintah Terkait

Perintah /Deskripsi

men-debug HTTP; Gunakan perintah ini untuk view informasi terperinci tentang lalu lintas HTTP.

Pesan Syslog terkait ASA REST API

Pesan log sistem terkait ASA REST API dijelaskan dalam bagian ini.

342001

Pesan Kesalahan: %ASA-7-342001: Agen REST API berhasil dimulai.
- Penjelasan: Agen REST API harus berhasil dimulai sebelum Klien REST API dapat mengonfigurasi ASA.
- Tindakan yang direkomendasikan: Tidak ada.

342002

Pesan Kesalahan: %ASA-3-342002: Agen API REST gagal, alasan: alasan
- Penjelasan: Agen REST API dapat gagal memulai atau mogok karena berbagai alasan, dan alasannya ditentukan.
- alasan—Penyebab kegagalan REST API

Tindakan yang direkomendasikan: Tindakan yang diambil untuk mengatasi masalah bervariasi tergantung pada alasan yang dicatat. Misalnyaample, Agen REST API mogok saat proses Java kehabisan memori. Jika ini terjadi, Anda perlu memulai ulang Agen REST API. Jika memulai ulang tidak berhasil, hubungi Cisco TAC untuk mengidentifikasi perbaikan akar penyebabnya.

342003

Pesan Kesalahan: %ASA-3-342003: Pemberitahuan kegagalan Agen REST API diterima. Agen akan dimulai ulang secara otomatis.
- Penjelasan: Pemberitahuan kegagalan dari Agen REST API telah diterima dan upaya memulai ulang Agen sedang dicoba.
- Tindakan yang direkomendasikan: Tidak ada.

342004

Pesan Kesalahan: %ASA-3-342004: Gagal memulai ulang Agen REST API secara otomatis setelah 5 kali percobaan yang gagal. Gunakan perintah 'no rest-api agent' dan 'rest-api agent' untuk memulai ulang Agen secara manual.
- Penjelasan: Agen REST API gagal dimulai setelah berkali-kali mencoba.
- Tindakan yang direkomendasikan: Lihat syslog %ASA-3-342002 (jika dicatat) untuk lebih memahami alasan di balik kegagalan tersebut. Cobalah untuk menonaktifkan Agen REST API dengan memasukkan perintah no rest-api agent dan aktifkan kembali Agen REST API menggunakan perintah rest-api agent.

Dokumentasi Terkait

Gunakan tautan berikut untuk menemukan informasi lebih lanjut tentang ASA, serta konfigurasi dan pengelolaannya:

Menavigasi Dokumentasi Seri Cisco ASA: http://www.cisco.com/go/asadocs
Gunakan tautan berikut untuk view daftar fitur ASA yang tidak didukung pada ASAv: http://www.cisco.com/c/en/us/td/docs/security/asa/asa92/configuration/general/asa-general-cli/introasav.html#pgfId-1156883

Dokumen ini akan digunakan bersama dengan dokumen-dokumen yang tersedia di bagian “Dokumentasi Terkait”.
Cisco dan logo Cisco adalah merek dagang atau merek dagang terdaftar dari Cisco dan/atau afiliasinya di AS dan negara-negara lain. view daftar merek dagang Cisco, kunjungi ini URL: Www.cisco.com/go/trademarksMerek dagang pihak ketiga yang disebutkan adalah milik pemiliknya masing-masing. Penggunaan kata mitra tidak menyiratkan hubungan kemitraan antara Cisco dan perusahaan lain mana pun. (1721R)
Alamat Protokol Internet (IP) dan nomor telepon apa pun yang digunakan dalam dokumen ini tidak dimaksudkan sebagai alamat dan nomor telepon sebenarnya.ampFile, keluaran tampilan perintah, diagram topologi jaringan, dan gambar lain yang disertakan dalam dokumen ditampilkan hanya untuk tujuan ilustrasi.
Segala penggunaan alamat IP atau nomor telepon sebenarnya dalam konten ilustrasi tidak disengaja dan kebetulan.

Cisco Systems, Inc.

www.cisco.com

Dokumen / Sumber Daya

Aplikasi CISCO ASA REST API [Bahasa Indonesia:] Panduan Pengguna
Aplikasi ASA REST API, ASA, Aplikasi REST API, Aplikasi API, Aplikasi

Referensi

Panduan Pengguna