Апликација CISCO ASA REST API
Инструкции за користење на производот
Во текот наview
Со објавувањето на Cisco's ASA REST API, сега имате уште една лесна, лесна за употреба опција за конфигурирање и управување со поединечни Cisco ASA. ASA REST API е апликативен програмски интерфејс (API) базиран на RESTful принципи. Може брзо да се преземе и да се овозможи на која било ASA каде што работи API. Cisco Systems, Inc.
Барања и одговори на ASA REST API
Откако ќе инсталирате REST клиент во вашиот прелистувач, можете да контактирате со специфичниот REST агент на ASA и да користите стандардни HTTP методи за да пристапите до тековните информации за конфигурација и да издадете дополнителни параметри за конфигурација.
Внимание: Кога REST API е овозможен на ASA, врските со други протоколи за управување со безбедноста не се блокирани. Ова значи дека другите кои користат CLI, ASDM или Security Manager може да ја менуваат конфигурацијата на ASA додека вие го правите истото.
Структура на барање
ASA REST API ви дава програмски пристап за управување со поединечни ASA преку Representational State Transfer API (REST). API им овозможува на надворешните клиенти да вршат операции CRUD (Креирај, читај, ажурирај, бришење) на ресурсите на ASA. Сите барања за API се испраќаат преку HTTPS до ASA и одговорот се враќа.
каде својствата на објектот се:
| Имотот | Тип | Опис |
|---|---|---|
| пораки | Список на речници | Список на пораки за грешка или предупредување |
| код | Низа | Детална порака што одговара на Грешка/Предупредување/Инфо |
| детали | Низа | Детална порака што одговара на Грешка/Предупредување/Инфо |
Забелешка: Промените направени од повиците REST API не се опстојуваат на конфигурацијата за стартување, туку се доделуваат само на конфигурацијата што работи. За да ги зачувате промените во конфигурацијата за стартување, можете да го користите барањето POST a write mem API. За повеќе информации, погледнете го записот Write Memory API во табелата со содржини За ASA REST API.
Инсталирајте и конфигурирајте го агентот и клиентот на ASA REST API
Забелешка: Агентот REST API е апликација базирана на Java. Java Runtime Environment (JRE) е во комплет во пакетот REST API Agent.
Во текот наview
Достапни се неколку опции за конфигурирање и управување со поединечни Cisco ASA:
- Интерфејс на командната линија (CLI) – испраќате контролни команди директно до ASA преку поврзана конзола.
- Управувач со приспособливи безбедносни уреди (ASDM) – апликација за управување со „вклучена кутија“ со графички кориснички интерфејс што можете да ја користите за конфигурирање, управување и следење на ASA.
- Cisco Security Manager – иако е наменета за средни до големи мрежи на многу безбедносни уреди, оваа графичка апликација може да се користи за конфигурирање, управување и следење на поединечни ASA.
Со објавувањето на ASA REST API на Cisco, сега имате уште една лесна, лесна за употреба опција. Ова е апликативен програмски интерфејс (API), заснован на принципите „RESTful“, кој можете брзо да го преземете и овозможите на која било ASA на која работи API.
Откако ќе инсталирате клиент REST во вашиот прелистувач, можете да контактирате со специфичниот REST агент на ASA и да користите стандардни HTTP методи за да пристапите до тековните конфигурациски информации и да издадете дополнителни параметри за конфигурација.
Внимание: Кога REST API е овозможен на ASA, врските со други протоколи за управување со безбедноста не се блокирани. Ова значи дека другите кои користат CLI, ASDM или Security Manager може да ја менуваат конфигурацијата на ASA додека вие го правите истото.
Барања и одговори на ASA REST API
ASA REST API ви дава програмски пристап за управување со поединечни ASA преку API за пренос на репрезентативна држава (REST). API им овозможува на надворешните клиенти да вршат операции CRUD (Креирај, читај, ажурирај, бришење) на ресурсите на ASA; се заснова на протоколот HTTPS и методологијата REST. Сите барања за API се испраќаат преку HTTPS до ASA и одговорот се враќа. Овој дел обезбедува надview за тоа како се структурирани барањата и очекуваните одговори,
Структура на барање
Достапни методи за барање се:
- GET – Превзема податоци од наведениот објект.
- PUT – Ги додава доставените информации на наведениот објект; враќа грешка 404 Resource Not Found ако објектот не постои.
- POST – Го креира објектот со доставените информации.
- DELETE – Го брише наведениот објект.
- PATCH – Применува делумни модификации на наведениот објект.
Структура на одговор
- Секое барање произведува HTTPS одговор од ASA со стандардни заглавија, содржина на одговор и код за статус.
Структурата на одговор може да биде:
- ЛОКАЦИЈА – Новосоздаден ID на ресурс; само за POST - го држи новиот ID на ресурс (како URI репрезентација).
- СОДРЖИНА-ТИП – Тип на медиум што го опишува телото на пораката за одговор; ја опишува претставата и синтаксата на телото на пораката за одговор.
Секој одговор вклучува статус на HTTP или код за грешка. Достапните кодови спаѓаат во овие категории:
- 20x – Код од двесте серии означува успешно работење, вклучувајќи:
- 200 OK – Стандарден одговор за успешни барања.
- 201 Создаден – Барањето е завршено; создаден нов ресурс.
- 202 Прифатено – Барањето е прифатено, но обработката не е завршена.
- 204 Без содржина – Серверот успешно го обработи барањето; ниедна содржина не се враќа.
- 4xx - Шифра од четиристотини серии означува грешка од страна на клиентот, вклучувајќи:
- 400 Bad Request – Невалидни параметри за барање, вклучувајќи непрепознаени параметри, параметри што недостасуваат или неважечки вредности.
- 404 Не е пронајдено – Обезбеденото URL не се совпаѓа со постоечки ресурс. За прampтака, HTTP DELETE може да не успее бидејќи ресурсот е недостапен.
- 405 Методот не е дозволен – Беше претставено барање за HTTP што не е дозволено на ресурсот; за прample, ПОСТ на ресурс само за читање.
- 5xx – Шифра од петстотини серии укажува на грешка на серверот.
Во случај на грешка, покрај кодот за грешка, одговорот за враќање може да вклучува и објект за грешка кој содржи повеќе детали за грешката. Шемата за одговор на грешка/предупредување JSON е како што следува:
каде својствата на објектот се:
| Имотот | Тип | Опис |
| пораки | Список на речници | Список на пораки за грешка или предупредување |
| код | Низа | Грешка/Предупредување/Инфо код |
| детали | Низа | Детална порака што одговара на Грешка/Предупредување/Инфо |
Забелешка: Промените на конфигурацијата ASA направени од повиците REST API не се опстојуваат на конфигурацијата за стартување; односно промените се доделуваат само на конфигурацијата која работи. За да ги зачувате промените во конфигурацијата за стартување, можете да ПОСТАВИТЕ барање за API за writemem; за повеќе информации, следете го записот „Write Memory API“ во табелата со содржини За ASA REST API.
Инсталирајте и конфигурирајте го агентот и клиентот на ASA REST API
- Агентот REST API се објавува поединечно со други слики на ASA cisco.com. За физички ASA, пакетот REST API мора да се преземе на блицот на уредот и да се инсталира со помош на командата „rest-api image“. Агентот REST API потоа е овозможен со помош на командата „rest-api agent“.
- Со виртуелна ASA (ASAv), сликата REST API мора да се преземе во партицијата „boot:“. Потоа мора да ја издадете командата „rest-api image“, проследена со командата „rest-api agent“, за да пристапите и да го овозможите REST API Agent.
- За информации за REST API софтверот и хардверските барања и компатибилноста, видете ја матрицата за компатибилност на Cisco ASA.
- Можете да го преземете соодветниот REST API пакет за вашиот ASA или ASAv од software.cisco.com/download/home. Пронајдете го специфичниот модел на Адаптивни безбедносни уреди (ASA) и потоа изберете Приклучок за REST API за приспособливи безбедносни уреди.
Забелешка: Агентот REST API е апликација базирана на Java. Java Runtime Environment (JRE) е во комплет во пакетот REST API Agent.
Упатства за употреба
Важно Мора да го вклучите насловот User-Agent: REST API Agent во сите повици на API и постоечки скрипти. Користете -H „Корисник-агент: REST API Agent“ за CURL команда. Во режимот со повеќе контексти, командите REST API Agent се достапни само во системски контекст.
Максимална поддржана големина на конфигурација
ASA Rest API е „on-board“ апликација која работи во физичката ASA и како таква има ограничување на меморијата доделена на неа. Максималната поддржана големина на конфигурацијата за извршување се зголеми во текот на циклусот на издавање на приближно 2 MB на неодамнешните платформи како што се 5555 и 5585. ASA Rest API исто така има ограничувања на меморијата на виртуелните ASA платформи. Вкупната меморија на ASAv5 може да биде 1.5 GB, додека на ASAv10 е 2 GB. Ограничувањата на Rest API се 450 KB и 500 KB за ASAv5 и ASAv10, соодветно.
Затоа, имајте предвид дека големите активни конфигурации можат да создадат исклучоци во различни ситуации со интензивна меморија, како што се голем број истовремени барања или големи количини на барања. Во овие ситуации, повиците на Rest API GET/PUT/POST може да почнат да не успеваат со 500 – пораки за внатрешна грешка на серверот, а Rest API Agent ќе се рестартира автоматски секој пат. Решението за оваа ситуација е или преместување на платформи ASA/FPR или ASAV со повисока меморија или намалување на големината на конфигурацијата која работи.
Преземете и инсталирајте го REST API агентот
Користејќи го CLI, следете ги овие чекори за да го преземете и инсталирате агентот ASA REST API на одредена ASA:
- Чекор 1: На саканиот ASA, издадете ја копијата disk0: команда за преземање на тековниот пакет ASA REST API од cisco.com на флеш меморијата на ASA.
- За прampле: копирајте tftp://10.7.0.80/asa-restapi-111-lfbff-k8.SPA диск0:
- Чекор 2: Издадете го дискот со слика rest-api0:/ команда за проверка и инсталирање на пакетот.
- За прampле: rest-api слика диск0:/asa-restapi-111-lfbff-k8.SPA
Инсталаторот ќе изврши проверки на компатибилност и валидација, а потоа ќе го инсталира пакетот. ASA нема да се рестартира.
Овозможете го агентот REST API
Следете ги овие чекори за да го овозможите агентот ASA REST API на одредена ASA:
- Чекор 1: Проверете дали е инсталирана правилната слика на софтверот на ASA.
- Консултирајте се со делот REST API на матрицата за компатибилност на ASA (https://www.cisco.com/c/en/us/td/docs/security/asa/compatibility/asamatrx.html#pgfId-131643) за да се одреди која слика ASA е потребна.
- Чекор 2: Користејќи го CLI, проверете дали HTTP-серверот е овозможен на ASA и дека клиентите на API можат да се поврзат со интерфејсот за управување.
- За прampле: овозможи http сервер
- http 0.0.0.0 0.0.0.0
- Чекор 3: Користејќи го CLI, дефинирајте HTTP автентикација за API-врските. За прample: ааа автентикација http конзола ЛОКАЛНО
- Чекор 4: Користејќи го CLI, креирајте статична рута на ASA за сообраќај на API. За прample: рута 0.0.0.0 0.0.0.0 1
- Чекор 5: Користејќи го CLI, овозможете го агентот ASA REST API на ASA. За прample: rest-api агент
REST API автентикација
Постојат два начини за автентикација: Основна автентикација на HTTP, која пренесува корисничко име и лозинка во секое барање, или автентикација базирана на токени со безбеден транспорт на HTTPS, кој поминува претходно креиран токен со секое барање. Во секој случај, автентикацијата ќе се изврши за секое барање. Погледнете го делот „Token_Authentication_API“ во водичот За ASA REST API v7.14(x) за дополнителни информации за автентикацијата базирана на токени.
Забелешка: На ASA се препорачува употреба на сертификати издадени од органот за сертификати (CA), така што клиентите REST API можат да ги потврдат сертификатите на серверот ASA кога воспоставуваат SSL врски.
Овластување на командата
Ако овластувањето на командата е конфигурирано да користи надворешен AAA сервер (на прampле, ааа команда за овластување ), тогаш корисникот со име enable_1 мора да постои на тој сервер со целосни командни привилегии. Ако овластувањето на командата е конфигурирано да ја користи ЛОКАЛНАта база на податоци на ASA (ааа команда за авторизација LOCAL), тогаш сите корисници на REST API мора да бидат регистрирани во LOCAL базата на податоци со нивоа на привилегии соодветни за нивните улоги:
- Нивото на привилегија 3 или поголемо е потребно за да се повикаат барањата за следење.
- Нивото на привилегија 5 или поголемо е потребно за повикување GET барања.
- Нивото на привилегија 15 е неопходно за повикување на операциите PUT/POST/DELETE.
Конфигурирајте го вашиот REST API клиент
Следете ги овие чекори за да инсталирате и конфигурирате REST API клиент на вашиот локален прелистувач:
- Чекор 1: Набавете и инсталирајте REST API клиент за вашиот прелистувач.
- За Chrome, инсталирајте го клиентот REST од Google. За Firefox, инсталирајте го додатокот RESTClient. Internet Explorer не е поддржан.
- Чекор 2: Започнете го следното барање користејќи го вашиот прелистувач: https: /api/објекти/мрежни објекти
- Ако добиете одговор без грешка, сте стигнале до агентот REST API што функционира на ASA.
- Ако имате проблеми со барањето за агент, можете да овозможите прикажување на информации за дебагирање на конзолата CLI, како што е опишано во Овозможување на REST API дебагирање на ASA.
- Чекор 3: Изборно, можете да ја тестирате вашата врска со ASA со извршување на операција POST.
За прampле: Обезбедете основни акредитиви за овластување ( ), или токен за автентикација (видете Автентикација на токени за дополнителни информации).
- Адреса за целно барање: https://<asa management ipaddress>/api/objects/networkobjects
- Тип на содржина на телото: апликација/json
Необработено тело на операцијата:
Сега можете да го користите ASA REST API за конфигурирање и следење на ASA. Погледнете ја документацијата API за описите на повиците и на прampлес.
За целосно враќање на резервната конфигурација
Враќањето на целосна резервна конфигурација на ASA со користење на REST API ќе ја превчита ASA. За да го избегнете ова, користете ја следнава команда за да ја вратите резервната конфигурација:
- {
- „команди“:[„copy /noconfirm disk0:/fileиме> running-config“]
- }
- Кадеfilename> е backup.cfg или кое било име што сте го користеле при правењето резервна копија на конфигурацијата.
Конзола за документација и извоз на скрипти на API
Можете исто така да ја користите конзолата за документација REST API на интернет (наведена како „Док UI“), достапна на host:port/doc/ како „песок“ за учење и испробување на повиците на API директно на ASA. Понатаму, можете да го користите копчето Export Operation во Doc UI за да го зачувате прикажаниот метод на прampкако скрипта JavaScript, Python или Perl file на вашиот локален домаќин. Потоа можете да ја примените оваа скрипта на вашиот ASA и да ја уредувате за примена на други ASA и други мрежни уреди. Ова значеше првенствено како едукативна и алатка за подигање.
JavaScript
- Користење на JavaScript file бара инсталација на node.js, која може да се најде на http://nodejs.org/.
- Со користење на node.js, можете да извршите JavaScript file, обично напишана за прелистувач, како скрипта од командната линија. Едноставно следете ги инструкциите за инсталација, а потоа извршете ја вашата скрипта со node script.js.
Пајтон
- Скриптите на Python бараат да инсталирате Python, достапен од https://www.python.org/.
- Откако ќе го инсталирате Python, можете да ја извршите вашата скрипта со лозинка за корисничко име python script.py.
Перл
Користењето на скриптите Perl бара дополнително поставување - потребни ви се пет компоненти: самиот Perl и четири библиотеки Perl:
- Пакет Perl, пронајден на http://www.perl.org/
- Пакет::CPAN, пронајден на http://search.cpan.org/~andk/Bundle-CPAN-1.861/CPAN.pm
- ОДМОР::Клиент, пронајден на http://search.cpan.org/~mcrawfor/REST-Client-88/lib/REST/Client.pm
- MIME::Base64, пронајден во http://perldoc.perl.org/MIME/Base64.html
- JSON, пронајден на http://search.cpan.org/~makamaka/JSON-2.90/lib/JSON.pm
Еве еден поранешенampза подигање на Perl на Macintosh:
- $ sudo perl -MCPAN е школка
- cpan> инсталирај пакет::CPAN
- cpan> инсталирај REST:: Клиент
- cpan> инсталирај MIME::Base64
- cpan> инсталирај JSON
По инсталирањето на зависностите, можете да ја извршите вашата скрипта користејќи лозинка за корисничко име perl script.pl.
Овозможување на REST API дебагирање на ASA
Ако имате проблеми со конфигурирање или поврзување со REST API на ASA, можете да ја користите следнава команда CLI за да овозможите прикажување на пораките за дебагирање на вашата конзола. Користете ја формата без наредбата за да ги оневозможите пораките за отстранување грешки.
отстранување грешки rest-api [агент | cli | клиент | демон | процес | token-auth] [грешка | настан] нема одмор-апи за отстранување грешки
Опис на синтаксата
- агент: (Изборно) Овозможете информации за отстранување грешки на агентот REST API.
- cli: (Изборно) Овозможете пораки за отстранување грешки за REST API CLI комуникации Daemon-to-Agent.
- клиент: (Изборно) Овозможете информации за отстранување грешки за рутирање на пораки помеѓу клиентот REST API и REST API агентот.
- демон: (Изборно) Овозможете дебагирање пораки за REST API комуникации Daemon-to-Agent.
- процес: (Незадолжително) Овозможете REST API Agent процесот на започнување/стопирање на информации за дебагирање.
- токен-автоматизам: (Изборно) Информации за отстранување грешки за автентикација на токен REST API.
- грешка: (Незадолжително) Користете го овој клучен збор за да ги ограничите пораките за отстранување грешки само на грешки пријавени од API.
- настан: (Изборно) Користете го овој клучен збор за да ги ограничите пораките за отстранување грешки само на настани што се евидентирани од API.
Упатства за употреба
Ако не наведете специфичен клучен збор за компонента (односно, ако едноставно ја издадете командата debug rest-api), пораките за отстранување грешки се прикажуваат за сите типови на компоненти. Ако не го наведете клучниот збор за настан или грешка, се прикажуваат и пораките за настан и грешка за наведената компонента. За прample, Debug rest-api daemon настан ќе прикажува само пораки за отстранување грешки на настани за API комуникации Daemon-to-Agent.
Поврзани команди
Команда /Опис
- дебагирање на HTTP; Користете ја оваа команда за да view детални информации за сообраќајот на HTTP.
Пораките со системски дневник поврзани со ASA REST API се опишани во овој дел.
342001
- Порака за грешка: %ASA-7-342001: REST API Agent започна успешно.
- Објаснување: Агентот REST API мора успешно да се стартува пред клиентот REST API да може да го конфигурира ASA.
- Препорачано дејство: Никој.
342002
- Порака за грешка: %ASA-3-342002: REST API агентот не успеа, причина: причина
- Објаснување: Агентот REST API може да не успее да започне или да падне од различни причини, а причината е наведена.
- причина - Причината за неуспехот на REST API
Препорачано дејство: Дејствата преземени за да се реши проблемот варираат во зависност од причината што е најавена. За прampле, агентот REST API паѓа кога процесот на Java ќе снема меморија. Ако се случи ова, треба да го рестартирате REST API агентот. Ако рестартирањето не е успешно, контактирајте со Cisco TAC за да ја идентификувате исправката на основната причина.
342003
- Порака за грешка: %ASA-3-342003: Примено е известување за неуспех на агентот REST API. Агентот ќе се рестартира автоматски.
- Објаснување: Примено е известување за неуспех од REST API агентот и се прави обид за рестартирање на агентот.
- Препорачано дејство: Никој.
342004
- Порака за грешка: %ASA-3-342004: Неуспешно автоматско рестартирање на REST API агентот по 5 неуспешни обиди. Користете ги командите „no rest-api agent“ и „rest-api agent“ за рачно рестартирање на агентот.
- Објаснување: Агентот REST API не успеа да започне по многу обиди.
- Препорачано дејство: Видете го syslog %ASA-3-342002 (ако е најавен) за подобро да ја разберете причината зад неуспехот. Обидете се да го оневозможите REST API Agent со внесување на командата no rest-api agent и повторно овозможете го REST API Agent користејќи ја командата rest-api агент.
Користете ја следнава врска за да најдете повеќе информации за ASA и неговата конфигурација и управување:
- Навигација низ документацијата на серијата Cisco ASA: http://www.cisco.com/go/asadocs
- Користете ја следнава врска до view список на карактеристики на ASA кои не се поддржани на ASAv: http://www.cisco.com/c/en/us/td/docs/security/asa/asa92/configuration/general/asa-general-cli/introasav.html#pgfId-1156883
Овој документ треба да се користи заедно со документите достапни од делот „Поврзана документација“.
Cisco и логото на Cisco се заштитни знаци или регистрирани заштитни знаци на Cisco и/или неговите филијали во САД и други земји. На view листа на заштитни знаци на Cisco, одете на ова URL: www.cisco.com/go/trademarks. Споменатите трговски марки од трети страни се сопственост на нивните соодветни сопственици. Употребата на зборот партнер не подразбира партнерски однос помеѓу Cisco и која било друга компанија. (1721R)
Сите адреси на Интернет протокол (IP) и телефонски броеви што се користат во овој документ не се наменети да бидат вистински адреси и телефонски броеви. Секој поранешенamples, излезот на приказот на командите, дијаграмите за мрежна топологија и другите фигури вклучени во документот се прикажани само за илустративни цели.
Секое користење на вистински IP адреси или телефонски броеви во илустративна содржина е ненамерно и случајно.
Cisco Systems, Inc.
© 2014-2018 Cisco Systems, Inc. Сите права се задржани.
Документи / ресурси
 |
Апликација CISCO ASA REST API [pdf] Упатство за корисникот Апликација ASA REST API, ASA, REST API апликација, API апликација, апликација |