Документация: ПО Факел — разрабатываемая версия

Служба HTTPS и HTTP API

Обзор

Служба HTTPS ПО Факел — веб-сервер маршрутизатора, через который работает программный интерфейс управления HTTP API (раздел service https api). Через API внешние системы управления и сценарии администратора читают и изменяют конфигурацию маршрутизатора, сохраняют и загружают файлы конфигурации, добавляют образы системы, просматривают образы контейнеров, выполняют команды просмотра (show), генерации (generate) и сброса (reset), перезагружают и выключают маршрутизатор. Каждой из этих возможностей соответствует свой путь запроса (/retrieve, /configure, /config-file, /image, /container-image, /show, /generate, /reset, /reboot, /poweroff). Служба доступна на адресах интерфейсов, которыми управляет FVE. Кроме обычного API служба поддерживает интерфейс GraphQL (api graphql).

Служба настраивается в разделе service https:

  • адреса и порт — listen-address и port (по умолчанию 443). Если адреса не заданы, служба принимает подключения на всех адресах IPv4 и IPv6. Если порт занят другой службой, проверка конфигурации завершается ошибкой. Командой vrf службу можно перенести в экземпляр VRF (см. Виртуальная маршрутизация), адреса listen-address при этом должны принадлежать интерфейсам этого VRF;

  • доступ — allow-client address ограничивает адреса и сети клиентов, которым разрешены запросы к путям API (другим клиентам служба отвечает кодом HTTP 403); запросы к остальным путям службы этот параметр не ограничивает; enable-http-redirect включает перенаправление запросов HTTP с порта 80 на HTTPS;

  • шифрование — сертификат службы и сертификат удостоверяющего центра из конфигурации PKI (certificates, см. Инфраструктура открытых ключей), параметры Диффи — Хеллмана для обмена ключами DHE (certificates dh-params), допустимые версии TLS (tls-version). Если сертификат не задан, служба использует встроенный самоподписанный сертификат, и при проверке конфигурации выводится предупреждение: такой сертификат не следует использовать в рабочей сети;

  • размер тела запроса — request-body-size-limit.

Запросы к API подтверждаются ключом. Ключи задаются командами api keys id <id> key. Для GraphQL можно выбрать аутентификацию по ключам или по токену JWT (api graphql authentication type); для токенов задаются время действия и длина секрета. Если раздел api задан, но не задан ни один ключ и аутентификация по токену не выбрана, проверка конфигурации завершается ошибкой. Если для GraphQL выбрана аутентификация по токену, а ключей нет, выводится предупреждение: обычный (не GraphQL) API в этом случае недоступен.

Запрос с неверным ключом служба отклоняет с сообщением Valid API key is required. Описание API (путь /docs) доступно без ключа.

Дополнительные параметры API: cors allow-origin разрешает запросы к интерфейсу GraphQL со страниц других источников (CORS), strict включает строгую проверку путей (например, удаление несуществующего пути конфигурации завершается ошибкой), debug — режим отладки (подробные сведения об ошибках изменения конфигурации в системном журнале), graphql introspection — интроспекцию схемы GraphQL.

В текущей версии ПО Факел через API запросы /configure и /configure-section не выполняются (ответ 502), изменения конфигурации через API не применяются, а при нестандартном порте enable-http-redirect перенаправляет на порт 443 (см. Ограничения).

Список команд

Режим «Конфигурирование»


service https allow-client address <address>

Описание:
Задает адреса или сети клиентов, которым разрешены запросы к путям API службы HTTPS. Другим клиентам служба отвечает на такие запросы кодом HTTP 403; запросы к остальным путям службы параметр не ограничивает.

Синтаксис:

  • set service https allow-client address <address>

  • delete service https allow-client address <address>

  • show service https allow-client address

Аргументы:

  • <address> — адрес или префикс клиента. Формат: IPv4-адрес (x.x.x.x), IPv6-адрес (h:h:h:h:h:h:h:h), IPv4-префикс (x.x.x.x/x) или IPv6-префикс (h:h:h:h:h:h:h:h/x). Можно задать несколько значений.

Режим: «Конфигурирование».

service https api cors allow-origin <allow-origin>

Описание:
Задает источник (origin), с которого разрешены запросы к интерфейсу GraphQL (CORS): на предварительный запрос с этого источника служба отвечает заголовком access-control-allow-origin.

Синтаксис:

  • set service https api cors allow-origin <allow-origin>

  • delete service https api cors allow-origin <allow-origin>

  • show service https api cors allow-origin

Аргументы:

  • <allow-origin> — источник запросов. Формат: строка. Можно задать несколько значений.

Режим: «Конфигурирование».

service https api debug

Описание:
Включает режим отладки API: если запрос на изменение конфигурации (/configure) завершился ошибкой, в системный журнал (show log) записываются подробные сведения об ошибке. Ответ клиенту в режиме отладки не меняется.

Синтаксис:

  • set service https api debug

  • delete service https api debug

  • show service https api debug

Режим: «Конфигурирование».

service https api graphql authentication expiration <expiration>

Описание:
Задает время действия токена аутентификации GraphQL в секундах. По истечении этого времени запрос с токеном отклоняется с сообщением expired token.

Синтаксис:

  • set service https api graphql authentication expiration <expiration>

  • delete service https api graphql authentication expiration <expiration>

  • show service https api graphql authentication expiration

Аргументы:

  • <expiration> — время действия токена в секундах. Формат: целое число. Диапазон значений: от 60 до 31536000. Значение по умолчанию: 3600.

Режим: «Конфигурирование».

service https api graphql authentication secret-length <secret-length>

Описание:
Задает длину общего секрета для токенов GraphQL в байтах.

Синтаксис:

  • set service https api graphql authentication secret-length <secret-length>

  • delete service https api graphql authentication secret-length <secret-length>

  • show service https api graphql authentication secret-length

Аргументы:

  • <secret-length> — длина секрета в байтах. Формат: целое число. Диапазон значений: от 16 до 65535. Значение по умолчанию: 32.

Режим: «Конфигурирование».

service https api graphql authentication type <type>

Описание:
Задает тип аутентификации для GraphQL API.

Синтаксис:

  • set service https api graphql authentication type <type>

  • delete service https api graphql authentication type <type>

  • show service https api graphql authentication type

Аргументы:

  • <type> — тип аутентификации. Возможные значения: key — аутентификация по ключам API; token — аутентификация по токену JWT. Значение по умолчанию: key.

Режим: «Конфигурирование».

service https api graphql introspection

Описание:
Включает интроспекцию схемы GraphQL.

Синтаксис:

  • set service https api graphql introspection

  • delete service https api graphql introspection

  • show service https api graphql introspection

Режим: «Конфигурирование».

service https api keys id <id>

Описание:
Создает ключ API с идентификатором <id>.
Для каждого ключа необходимо задать значение командой api keys id <id> key, иначе проверка конфигурации завершается ошибкой. Если не задан ни один ключ и для GraphQL не выбрана аутентификация по токену (api graphql authentication type token), проверка конфигурации также завершается ошибкой.

Синтаксис:

  • set service https api keys id <id>

  • delete service https api keys id <id>

  • show service https api keys id

Аргументы:

  • <id> — идентификатор ключа API. Формат: строка.

Режим: «Конфигурирование».

service https api keys id <id> key <key>

Описание:
Задает значение ключа API <id> в открытом виде.

Синтаксис:

  • set service https api keys id <id> key <key>

  • delete service https api keys id <id> key <key>

  • show service https api keys id <id> key

Аргументы:

  • <id> — идентификатор ключа API.

  • <key> — значение ключа. Формат: строка.

Режим: «Конфигурирование».

service https api strict

Описание:
Включает строгую проверку путей в запросах API: например, запрос на удаление несуществующего пути конфигурации завершается ошибкой Cannot delete [<path>]: path/value does not exist.

Синтаксис:

  • set service https api strict

  • delete service https api strict

  • show service https api strict

Режим: «Конфигурирование».

service https certificates ca-certificate <ca-certificate>

Описание:
Задает сертификат удостоверяющего центра из конфигурации PKI (см. Инфраструктура открытых ключей).

Синтаксис:

  • set service https certificates ca-certificate <ca-certificate>

  • delete service https certificates ca-certificate <ca-certificate>

  • show service https certificates ca-certificate

Аргументы:

  • <ca-certificate> — имя сертификата удостоверяющего центра в конфигурации PKI. Формат: строка.

Режим: «Конфигурирование».

service https certificates certificate <certificate>

Описание:
Задает сертификат службы HTTPS из конфигурации PKI (см. Инфраструктура открытых ключей).
Если сертификат не задан, служба использует встроенный самоподписанный сертификат, а при проверке конфигурации выводится предупреждение.

Синтаксис:

  • set service https certificates certificate <certificate>

  • delete service https certificates certificate <certificate>

  • show service https certificates certificate

Аргументы:

  • <certificate> — имя сертификата в конфигурации PKI. Формат: строка.

Режим: «Конфигурирование».

service https certificates dh-params <dh-params>

Описание:
Задает параметры Диффи — Хеллмана из конфигурации PKI (pki dh, см. Инфраструктура открытых ключей). С этими параметрами служба принимает подключения TLS 1.2 с обменом ключами DHE (наборы шифров DHE-RSA, нужен сертификат RSA). Без них такие подключения отклоняются, и для обмена ключами используется только ECDHE.

Синтаксис:

  • set service https certificates dh-params <dh-params>

  • delete service https certificates dh-params <dh-params>

  • show service https certificates dh-params

Аргументы:

  • <dh-params> — имя параметров Диффи — Хеллмана в конфигурации PKI. Формат: строка.

Режим: «Конфигурирование».

service https enable-http-redirect

Описание:
Включает перенаправление запросов HTTP на HTTPS.

Синтаксис:

  • set service https enable-http-redirect

  • delete service https enable-http-redirect

  • show service https enable-http-redirect

Режим: «Конфигурирование».

service https listen-address <listen-address>

Описание:
Задает локальные IP-адреса, на которых служба HTTPS принимает подключения.

Синтаксис:

  • set service https listen-address <listen-address>

  • delete service https listen-address <listen-address>

  • show service https listen-address

Аргументы:

  • <listen-address> — локальный IP-адрес. Формат: IPv4-адрес (x.x.x.x) или IPv6-адрес (h:h:h:h:h:h:h:h). Можно задать несколько значений.

Режим: «Конфигурирование».

service https port <port>

Описание:
Задает номер порта TCP, на котором служба HTTPS принимает подключения.
Если порт занят другой службой, проверка конфигурации завершается ошибкой.

Синтаксис:

  • set service https port <port>

  • delete service https port <port>

  • show service https port

Аргументы:

  • <port> — номер порта. Формат: целое число. Диапазон значений: от 1 до 65535. Значение по умолчанию: 443.

Режим: «Конфигурирование».

service https request-body-size-limit <request-body-size-limit>

Описание:
Задает максимальный размер тела запроса в мегабайтах. На запрос большего размера служба отвечает кодом HTTP 413.

Синтаксис:

  • set service https request-body-size-limit <request-body-size-limit>

  • delete service https request-body-size-limit <request-body-size-limit>

  • show service https request-body-size-limit

Аргументы:

  • <request-body-size-limit> — размер тела запроса в мегабайтах. Формат: целое число. Диапазон значений: от 1 до 256. Значение по умолчанию: 1.

Режим: «Конфигурирование».

service https tls-version <tls-version>

Описание:
Задает допустимые версии протокола TLS. Подключение по другой версии служба не принимает.

Синтаксис:

  • set service https tls-version <tls-version>

  • delete service https tls-version <tls-version>

  • show service https tls-version

Аргументы:

  • <tls-version> — версия TLS. Возможные значения: 1.2 — TLS 1.2; 1.3 — TLS 1.3. Значение по умолчанию: 1.2 1.3. Можно задать несколько значений.

Режим: «Конфигурирование».

service https vrf <vrf>

Описание:
Задает экземпляр VRF, в котором работает служба HTTPS: служба принимает подключения на адресах интерфейсов этого VRF. Адрес из другого VRF в listen-address служба занять не может и не запускается.

Синтаксис:

  • set service https vrf <vrf>

  • delete service https vrf <vrf>

  • show service https vrf

Аргументы:

  • <vrf> — имя экземпляра VRF. Формат: строка.

Режим: «Конфигурирование».