Перейти к основному содержимому

qf — Руководство оператора

Версия 0.9.60 · Повседневная работа с qf через веб-интерфейс

Это руководство — для операторов, которые управляют политиками, хостами и наблюдают за трафиком через Web UI. Установка и настройка инфраструктуры — в install.md. Скриншоты выполнены на демо-данных; имена хостов и адреса обезличены.

Концептуальная глубина по темам — в соседних гайдах: правила и политики — policy-management.md, селекторы — selector.md, object groups и группы хостов — fleet-management.md, статусы хостов — host-statuses.md. Здесь описан путь по интерфейсу по шагам, без повторения теории.

1. Вход и обзор (Dashboard)​

Открыть https://<cp-host>/app/ и войти (логин/пароль или SSO). После входа — Dashboard: сводка по флоту (хосты по статусам), последние события и активность.

Dashboard

Слева — навигация: Hosts, Policies, Object Groups, Host Groups, Verdicts, Flows, Audit Log, Tokens, Users. Переключатель темы и меню пользователя — справа сверху.

2. Энролмент нового хоста​

Хост подключается к флоту по энролмент-токену. Лейблы, которые получит хост, задаются прямо в токене — отдельной настройки на хосте не нужно.

Шаги​

  1. Tokens → New token.
  2. Тип bulk (для массового энролла) или single_host.
  3. Задать Label key/value — например role=web. Эти лейблы получит каждый хост, энролленный токеном (определяют, какие политики к нему применятся).
  4. TTL и Max uses — срок и лимит использований.
  5. Create.

Создание токена

  1. UI покажет токен один раз и готовый agent.conf — скопируйте.

На целевом хосте — два поля в /etc/qf/agent.conf:

QF_ENDPOINT=cp.example.com
QF_ENROLL_TOKEN=<скопированный-токен>

Запустить агент:

sudo systemctl enable --now qf-agent

Хост сам вытянет CA и сертификат, определит сетевой интерфейс и появится в Hosts со статусом Active и лейблами из токена.

Список токенов

Вкладка API Tokens — отдельные токены для CI/автоматизации (роли admin/editor/auditor).

3. Обзор хостов и статус​

Hosts — список флота: статус, лейблы, IP, версия агента, поколение (gen), последний heartbeat. Фильтр по hostname/лейблу и по статусам сверху.

Hosts

Статусы: Active (на связи, конфиг подтверждён), Pending (применяет изменения), Degraded (долго не подтверждает), Stale (нет heartbeat).

Клик по хосту → детальная страница:

Детали хоста

  • Agent info — версия, ядро, поколения (desired/confirmed), heartbeat.
  • Datapath & capabilities — режим attach (TCX/classic), лимит правил (2048; eBPF-фичи bpf_loop+ringbuf, mainline ≥5.17 или бэкпорт), ОС, CPU, наличие Cilium, ip_forward.
  • Interfaces — интерфейсы, адреса, какой приаттачен.
  • Вкладки: Policies, Ruleset (эффективные правила), Verdicts, Flows, Counters, Groups.

4. Создание политики​

Политика = к каким хостам (selector) применить набор правил.

Шаги​

  1. Policies → New policy.
  2. Имя, описание, приоритет (меньше число = выше при first-match).
  3. Host selector — по лейблам (например role=web). Применится ко всем хостам с этим лейблом, включая унаследованные от групп.
  4. Add rule — для каждого правила:
    • Direction: ingress / egress.
    • Action: allow / deny / log.
    • Match: протокол, порты (одиночные 443 и диапазоны 8080-8090), CIDR, или ссылка на object group; опционально TCP-флаги и conntrack-state.
    • Log + rate-limit — логировать срабатывания.
  5. Preview impact — посмотреть, какие хосты и правила затронутся, без применения.
  6. Save policy.

Редактор политики

⚠️ Не создавайте deny без match (deny-all) — отрежет весь трафик. Не блокируйте порт 22. Default-action = ALLOW: фильтрует только то, что вы явно запретили.

Политика с пустым (match-all) селектором требует подтверждения вводом её имени — защита от случайного применения на весь флот.

Список политик:

Policies

Версии и откат​

Вкладка History на странице политики хранит снапшоты каждого сохранения. Любую версию можно revert — политика откатывается, изменения каскадно доезжают до хостов.

5. Группы хостов​

Группа задаёт общие лейблы для своих членов — удобно для «всех web-серверов».

  1. Host Groups → New group.
  2. Имя, лейблы (role=web, env=prod), приоритет.
  3. Добавить членов (хосты).

Host Groups

Лейблы группы наследуются хостами; прямые лейблы хоста перекрывают групповые. Меняете лейбл группы — политики пересчитываются на всех её хостах. Политика с селектором role=web автоматически покрывает всех членов группы с этим лейблом.

6. Object Groups (переиспользуемые наборы)​

Чтобы не дублировать списки IP/портов в правилах:

  1. Object Groups → New.
  2. Тип:
    • ipset — список CIDR/IP (203.0.113.0/24).
    • portset — порты и диапазоны (443, 8080-8090).
    • hostset — селектор → динамически резолвится в IP подходящих хостов.
  3. В правиле политики сослаться на набор (поля *_set_id).

Object Groups

Правка набора каскадно обновляет все политики, где он используется. Набор, на который ссылается правило, нельзя удалить (защита от «висячих» ссылок).

7. Наблюдаемость​

Flows — какие соединения идут​

Flows (при включённом flow-логировании на хосте) — реальные соединения: src/dst, протокол, байты. Поиск по порту, сортировка, фильтрация.

Flow Explorer

Включить на хосте: на странице хоста переключатель Flow events.

Verdicts — сработавшие правила​

Verdicts — срабатывания log-правил (в т.ч. deny): время, правило, направление, src/dst, порт. Здесь разбираются блокировки: видно, какое правило и какой трафик заблокировало.

Verdicts

Counters​

Вкладка Counters на хосте — счётчики попаданий по каждому правилу (пакеты/байты). Глобальные pass/drop и заполнение карт видны в метриках хоста (heartbeat).

8. Разбор инцидента (deny)​

Типовой сценарий «почему не идёт трафик»:

  1. Hosts → хост → Ruleset — посмотреть эффективные правила (что реально применено).
  2. Verdicts — найти deny-события по порту/адресу: какое правило сработало.
  3. Counters — подтвердить рост счётчика этого правила.
  4. Если правило лишнее — поправить политику; если порядок — проверить приоритеты (first-match).

9. Audit Log​

Audit Log — кто, что и когда менял: все мутации (политики, группы, токены, хосты) с before/after и именем актора. Служит для разбора изменений и комплаенса.

Audit Log

10. Быстрые правила безопасной работы​

  • Default ALLOW — фильтруется только явный deny; забыть правило = трафик пройдёт, а не упадёт.
  • Никогда deny без match и deny на порт 22.
  • Preview impact перед сохранением политики с широким селектором.
  • Сначала log-правило (понаблюдать в Verdicts), потом deny.
  • Токены показываются один раз — хранить безопасно, отзывать при утечке.
  • При большом числе правил следить за лимитом хоста (Datapath & capabilities): 2048.

Документ соответствует qf 0.9.60 (pre-GA). Интерфейс может меняться до 1.0.