Системное CLI

Содержание

Системное CLI#

Обзор#

system-cli — утилита командной строки для работы с System API подсистемы управления сетями.

Основные возможности:

работа с подсистемой через консольные команды;
просмотр и применение конфигурации инфраструктуры;
поддержка JWT и OIDC авторизации;
автоматическое сохранение токенов для последующих запросов;
Verbose режимы для отладки (включая генерацию curl-команд);
вывод информации в JSON и текстовом формате.

Установка и первоначальная настройка#

Конфигурационный файл#

Системное CLI использует конфигурационный файл для хранения токена подключения к System API, расположенный по пути ~/.config/system-cli/config.yaml.

Пример вида конфигурационного файла:

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX...."
}

Параметры подключения к системному API#

Системное CLI может брать параметры подключения к системному API из нескольких источников. Источники сортируются по приоритету, и при нахождении параметров в одном из них, поиск в источниках с более низким приоритетом не осуществляется.

Список источников по убыванию приоритета:

Из переменных окружения API_HOST, API_PORT и API_SCHEME.
Из файла .env, расположенного в одной директории с системным CLI.
Из файла .env, расположенного по пути ~/.apos/system-cli/.
Из файла .env, расположенного в CWD (Current Working Directory).
Если ничего вышеперечисленного не найдено, то используются дефолтные значения API_HOST=127.0.0.1, API_PORT=9090 и API_SCHEME=http.

Пример вида файла .env:

API_HOST=127.0.0.1
API_PORT=5000
API_SCHEME=https

Процесс авторизации#

Системное CLI поддерживает два метода авторизации:

JWT-токен;
OIDC-провайдер (интерактивный режим через браузер).

Авторизация через JWT-токен#

Нерекомендуемый способ — его можно использовать только в непродуктивных средах для целей отладки и автоматизации

Получить JWT-токен — JWT-токен должен быть предоставлен администратором системы или получен через внешний механизм аутентификации.

Формат токена — JWT в формате eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Авторизация в system-cli командой:

./system-cli auth --token=../test-token.jwt

Пример успешного ответа:

Авторизация настроена и сохранена успешно

Проверить авторизацию и автоматическое применение токена командой:

./system-cli config-show

Если команда выполнилась без ошибок авторизации, значит авторизация прошла успешно.

Примечание

Сохраненный токен расположен в ~/.config/system-cli/config.json.

Авторизация через OIDC#

При этом методе требуется браузер и интерактивное взаимодействие с пользователем.

Запустить авторизацию командой:

./system-cli auth --issuer https://your-oidc-provider.com --client-id apos

Пример вывода:

Ссылка для авторизации: https://your-oidc-provider.com/oauth2/authorize?client_id=apos&redirect_uri=http://localhost:9876/callback&response_type=code&scope=openid+profile&state=abc123&code_challenge=xyz789&code_challenge_method=S256&nonce=def456

Ожидание ответа сервера на порте 9876
Если доступ невозможен введите строку перенаправления вручную (в формате http://localhost:9876/callback?code=<code>):

В браузере:

скопировать ссылку из вывода команды;
открыть ее в браузере;
войти в систему через OIDC-провайдер;
после успешной аутентификации произойдет перенаправление на http://localhost:9876/callback.

Страница успешной авторизации:

Успешно

Авторизация выполнена успешно.

После успешного редиректа в терминале появится:

токен получен
Авторизация настроена и сохранена успешно

Альтернативный способ (ручной ввод callback URL)#

Если автоматический callback не работает (например, нет доступа к localhost:9876):

После входа через браузер скопировать полный URL из адресной строки:

http://localhost:9876/callback?code=AUTHORIZATION_CODE&state=abc123

Вставить этот URL в терминал, где ожидает system-cli.
Нажать клавишу Enter.

Пример вывода:

Ожидание ответа сервера на порте 9876
Если доступ невозможен введите строку перенаправления вручную: http://localhost:9876/callback?code=AUTH_CODE_HERE&state=abc123
Получена строка: http://localhost:9876/callback?code=AUTH_CODE_HERE&state=abc123
токен получен
Авторизация настроена и сохранена успешно

Опции команды auth#

Пример вывода команды ./system-cli auth --help:

Команда сохраняет параметры подключения к системному API AposCMS.

Пример:
  auth --insecure

Usage:
  system-cli auth [flags]

Flags:
      --client-id string   Идентификатор клиента (default "apos")
  -h, --help               help for auth
      --insecure           Разрешить небезопасные подключения
      --issuer string      Адрес OIDC провайдера (default "https://roox.apos.network/sso/realms/employee/as/oauth2/idp")
      --port int           Порт для подключения (default 9876)
      --token string       Файл с токеном для прямой записи в конфигурацию

Global Flags:
      --disable-validation   Отключить серверную валидацию конфигурации (ОПАСНО)
  -v, --verbose count        Уровень детализации логов.
                                        Уровень 0 (по умолчанию): Логи отключены.
                                        Уровень 1 (-v): Логируется x-request-id для отслеживания запросов.
                                        Уровень 2 (-vv): Логируются все исходящие запросы в виде curl-команд.

Флаг –insecure (подробное описание)#

Флаг --insecure отключает проверку SSL/TLS сертификатов при подключении к OIDC-провайдеру и к API подсистемы.

Примечание

Использование этого флага делает соединение уязвимым к атакам типа Man-in-the-Middle (MITM).

Рекомендуется использовать:

в окружении разработчика с самоподписанными сертификатами;
при тестировании в изолированной сети;
исправление проблем с SSL/TLS.

Запрещено использовать:

в продуктовом окружении;
при работе через публичные сети;
при работе с чувствительными данными.

Пример использования:

Окружении разработчика — авторизация с самоподписанным сертификатом:

./system-cli auth --token /opt/apos/tokens/dev-admin.jwt --insecure

Или с OIDC-провайдером:

./system-cli auth --issuer https://dev-oidc.internal.local --client-id apos --insecure

Безопасная альтернатива для окружения разработчика:

Вместо использования флага --insecure, добавить самоподписанный сертификат в доверенные:

Скачать сертификат:

openssl s_client -connect dev-oidc.internal.local:443 -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM > dev-cert.pem

Добавить в системное хранилище сертификатов:

sudo cp dev-cert.pem /usr/local/share/ca-certificates/dev-oidc.crt
sudo update-ca-certificates

Подключиться без --insecure:

./system-cli auth --issuer https://dev-oidc.internal.local --client-id apos

Переавторизация#

Для смены токена или пользователя Необходимо выполнить команду auth заново:

./system-cli auth --token /opt/apos/tokens/another-admin.jwt

Новая авторизация перезапишет старый токен.

Основные команды#

Получение справки#

Для получения общей справки необходимо использовать команду:

./system-cli --help

Или:

./system-cli -h

Для получения справки по конкретной команде необходимо использовать:

./system-cli [имя_команды] --help

Или:

./system-cli [имя_команды] -h

Пример вызова ./system-cli --help:

CLI используемый для управления внутренними компонентами платформы, конфигурациями и т.д.

Usage:
system-cli [flags]
system-cli [command]

Available Commands:
address-set-create           Создать множество адресов
address-set-delete           Удалить множество адресов
...
<прочие команды>
...
vrouter-route-create         Создать статический маршрут для виртуального маршрутизатора
vrouter-route-delete         Удалить статический маршрут
vrouter-route-list           Получить список статических маршрутов виртуального маршрутизатора
vrouter-route-show           Получить статический маршрут по ID
vrouter-route-update         Обновить статический маршрут
vrouter-show                 Получить информацию о виртуальном маршрутизаторе по ID
vrouter-update               Обновить виртуальный маршрутизатор по ID

Flags:
--disable-validation   Отключить серверную валидацию конфигурации (ОПАСНО)
-h, --help                 help for system-cli
-v, --verbose count        Уровень детализации логов.
Уровень 0 (по умолчанию): Логи отключены.
Уровень 1 (-v): Логируется x-request-id для отслеживания запросов.
Уровень 2 (-vv): Логируются все исходящие запросы в виде curl-команд.
--version              version for system-cli

Use "system-cli [command] --help" for more information about a command.

Примеры вызова конкретной команды ./system-cli vport-list -h:

Выводит список виртуальных портов.

Примеры:
vport-list --tenant-id=3fa85f64-5717-4562-b3fc-2c963f66afa6

vport-list --tenant-id=3fa85f64-5717-4562-b3fc-2c963f66afa6 \
--tenant-id=3fa85f64-5717-4562-b3fc-2c963f66afa7 \
--enabled=true --sort-by=created_at --sort-order=desc

Usage:
system-cli vport-list [flags]

Flags:
--chassis-id string       Идентификатор шасси
--created-by string       Фильтр: кто создал
--created-from string     Создано с (datetime)
--created-to string       Создано по (datetime)
--display-name string     Фильтр по отображаемому имени
--enabled                 Фильтр: только включенные (default true)
-h, --help                    help for vport-list
--is-utility              Флаг служебного порта (по умолчанию false)
--json                    Вывод в формате JSON (default true)
--page int                Номер страницы (default 1)
--per-page int            Размер страницы (default 20)
--purpose string          Предназначение служебного порта
--sort-by string          Поле сортировки (default "created_at")
--sort-order string       Порядок сортировки (asc|desc) (default "desc")
--tenant-id stringArray   Идентификатор одного или нескольких тенантов
--updated-by string       Фильтр: кто обновил
--updated-from string     Обновлено с (datetime)
--updated-to string       Обновлено по (datetime)
--vm-port-id string       Идентификатор порта OVS подключаемого к виртуальному порту
--vnet-id string          Идентификатор виртуальной сети
--vport-id string         Идентификатор вирутального порта
--vrouter-id string       Идентификатор виртуального маршрутизатора

Global Flags:
--disable-validation   Отключить серверную валидацию конфигурации (ОПАСНО)
-v, --verbose count        Уровень детализации логов.
Уровень 0 (по умолчанию): Логи отключены.
Уровень 1 (-v): Логируется x-request-id для отслеживания запросов.
Уровень 2 (-vv): Логируются все исходящие запросы в виде curl-команд.

Команда config-show#

Просмотр текущей конфигурации системы.

Базовое использование:

./system-cli config-show

Пример вывода (JSON):

{
  "configuration": {
    "chassis": [
      {
        "id": "chassis-1",
        "ip": "10.0.0.2",
        "enabled": true
      }
    ],
    "tenants": [
      {
        "id": "tenant-1",
        "display_name": "Main Tenant",
        "vnets": [...]
      }
    ]
  },
  "metadata": {
    "version": 42,
    "requested_at": "2026-03-18T10:00:00Z"
  }
}

Справка (команда ./system-cli config-show --help):

Команда config-show запрашивает текущую конфигурацию системы, включая метаинформацию (версия, хэш, время и пользователь).

Пример:
  config-show

Usage:
  system-cli config-show [flags]

Flags:
  -h, --help   help for config-show
      --json   Вывод в формате JSON (default true)

Global Flags:
      --disable-validation   Отключить серверную валидацию конфигурации (ОПАСНО)
  -v, --verbose count        Уровень детализации логов.
                                        Уровень 0 (по умолчанию): Логи отключены.
                                        Уровень 1 (-v): Логируется x-request-id для отслеживания запросов.
                                        Уровень 2 (-vv): Логируются все исходящие запросы в виде curl-команд.

Команда config-apply#

Применение конфигурации к системе.

Применение из файла:

./system-cli config-apply --input-json="$(cat config-example.json)"

Справка (команда ./system-cli config-apply --help):

Команда config-apply полностью заменяет текущую конфигурацию новой.

Пример JSON:
  config-apply --input-json="$(cat config-example.json)"

Usage:
  system-cli config-apply [flags]

Flags:
  -h, --help                help for config-apply
      --input-json string   Полный JSON тела запроса

Global Flags:
      --disable-validation   Отключить серверную валидацию конфигурации (ОПАСНО)
  -v, --verbose count        Уровень детализации логов.
                                        Уровень 0 (по умолчанию): Логи отключены.
                                        Уровень 1 (-v): Логируется x-request-id для отслеживания запросов.
                                        Уровень 2 (-vv): Логируются все исходящие запросы в виде curl-команд.

Пример успешного применения:

./system-cli config-apply --input production-config.json

Пример вывода выполнения команды:

Конфигурация успешно применена

Глобальные флаги#

Глобальные флаги доступны для всех команд system-cli.

Флаг –verbose / -v#

Управление уровнем детализации вывода для отладки и мониторинга.

Уровень 0 (по умолчанию) — логи отключены#

./system-cli config-show

Выводится только результат команды без дополнительной отладочной информации.

Уровень 1 (-v) — логирование x-request-id#

./system-cli config-show -v

Пример вывода после выполнения команды:

x-request-id: 550e8400-e29b-41d4-a716-446655440000

{
  "configuration": {
    ...
  }
}

Применение:

отслеживание запросов в логах сервера;
корреляция запросов между клиентом и сервером;
отладка распределенных систем.

Использование x-request-id в логах сервера:

На стороне сервера этот ID можно найти в логах:

[2026-03-18 10:00:00] INFO request_id=550e8400-e29b-41d4-a716-446655440000 method=GET path=/api/v1/configuration status=200

Это позволяет легко связать клиентский запрос с серверными логами.

Уровень 2 (-vv) — логирование curl-команд#

./system-cli config-show -vv

Пример вывода после выполнения команды:

curl -X GET 'http://127.0.0.1:4010/api/v1/vports?page=1&per_page=20&sort_by=created_at&sort_order=desc' -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjo.......'

Успешно:
{
  "data": [
    {
      "active": true,
      "addresses": [
        {
          "ip": "192.168.10.1",
          "mac": "55:87:E2:CD:EE:F2",
          "type": "generated_v4"
        }
      ],
      "chassis_id": "d2407ce7-9a09-4c19-a766-239486331a8d",
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": "string",
      "display_name": "string",
      "enabled": true,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "is_utility": false,
      "ovn_version": 0,
      "purpose": "VNF-NGFW",
      "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
      "unknown": false,
      "updated_at": "2019-08-24T14:15:22Z",
      "updated_by": "string",
      "version": -9007199254740991,
      "vm_port_id": "string",
      "vnet_id": "15730f2a-d355-4139-9942-db8cedb3dda9"
    }
  ],
  "pagination": {
    "count": 2,
    "page": 1,
    "per_page": 25,
    "total_count": 2
  }
}

Применение:

отладка API-запросов;
воспроизведение запросов вручную через curl;
документирование API взаимодействий;
обучение работе с API;
создание shell-скриптов для автоматизации.

Пример использования вывода:

Скопировать curl-команду из вывода и выполнить ее отдельно:

# Скопированная команда из вывода -vv
curl -X GET 'http://127.0.0.1:5000/api/v1/configuration' -H 'Authorization: Bearer eyJhbGc...' -H 'Content-Type: application/json'

Это позволяет:

модифицировать запрос для тестирования;
добавлять дополнительные заголовки;
изменять параметры запроса;
Использовать в CI/CD pipeline.

Флаг: –disable-validation#

Отключение серверной валидации конфигурации.

./system-cli config-apply --input config.json --disable-validation

Предупреждение

Этот флаг необходимо использовать с осторожностью.

При использовании флага:

сервер пропускает все проверки корректности конфигурации;
могут быть применены некорректные данные;
возможны конфликты в конфигурации;
система может перейти в нестабильное состояние.

Когда рекомендуется использовать:

отладка проблем с валидацией;
экстренное восстановление системы;
миграция между версиями с изменениями в схеме данных;
только при действительной необходимости.

Запрещено использовать:

в продуктивном окружении;
при автоматизированных процессах;
когда нет уверенности корректности конфигурации.

Пример безопасного использования:

Применить с валидацией:

./system-cli config-apply --input config.json

Если валидация не прошла, изучить ошибки:

# Ошибка: "vnet subnet overlaps with existing vnet"

Исправить конфигурацию и попробовать снова:

./system-cli config-apply --input config.json

Примечание

При необходимости, в крайнем случае, можно использовать флаг --disable-validation (например, для экстренного восстановления)

./system-cli config-apply --input emergency-recovery.json --disable-validation

Примеры использования системного CLI#

Пример 1: Первоначальная настройка системы#

Авторизоваться в системном CLI:

./system-cli auth --token=../test-token.jwt

Просмотреть текущую конфигурацию:

./system-cli config-show

Применить новую конфигурацию:

./system-cli config-apply --input-json="$(cat config-example.json)"

Пример 2: Отладка запросов с verbose режимом#

Получить curl-команду для воспроизведения запроса:

./system-cli config-show -vv

Пример вывода команды:

# curl -X GET 'http://127.0.0.1:5000/api/v1/configuration' # -H 'Authorization: Bearer eyJ...' # -H 'Content-Type: application/json'

Выполнить curl вручную для тестирования:

curl -X GET 'http://127.0.0.1:5000/api/v1/configuration' -H 'Authorization: Bearer eyJ...' -H 'Content-Type: application/json' | jq .

Полная документация по командам#

Полную документацию по командам в формате markdown можно найти в архиве:

Системное CLI.

Версии

Системное CLI

Содержание

Системное CLI#

Обзор#

Установка и первоначальная настройка#

Конфигурационный файл#

Параметры подключения к системному API#

Процесс авторизации#

Авторизация через JWT-токен#

Авторизация через OIDC#

Альтернативный способ (ручной ввод callback URL)#

Опции команды auth#

Флаг –insecure (подробное описание)#

Переавторизация#

Основные команды#

Получение справки#

Команда config-show#

Команда config-apply#

Глобальные флаги#

Флаг –verbose / -v#

Уровень 0 (по умолчанию) — логи отключены#

Уровень 1 (-v) — логирование x-request-id#

Уровень 2 (-vv) — логирование curl-команд#

Флаг: –disable-validation#

Примеры использования системного CLI#

Пример 1: Первоначальная настройка системы#

Пример 2: Отладка запросов с verbose режимом#

Полная документация по командам#