Параметры Control Plane
Control Plane настраивается переменными окружения процесса qf-cp. В Helm-чарте
секреты задаются в secrets, остальные значения — в env. Пустому значению
соответствует значение по умолчанию из таблицы.
Обязательные и секреты
| Ключ | Дефолт | Назначение |
|---|---|---|
QF_DB_DSN | — | Строка подключения к PostgreSQL. Обязательна — без неё CP не стартует. |
QF_MASTER_KEY_FILE | — | Путь к файлу с master key, например к tmpfs-секрету с правами 0600. Имеет приоритет над QF_MASTER_KEY. |
QF_MASTER_KEY | — | Master key в переменной окружения: 32 байта в hex (openssl rand -hex 32). Ключ шифрует файлы ca.key и bundle-signing.key в QF_PKI_DIR. Один из двух источников master key обязателен. При потере ключа закрытые ключи PKI нельзя расшифровать. |
QF_JWT_SECRET | — | HS256-секрет подписи refresh-токенов (≥32 байт). Обязателен при replicaCount > 1: без него каждый под генерирует эфемерный секрет при старте → сессии инвалидируются на рестарте, кросс-под-аутентификация падает. |
QF_JWT_PRIVATE_KEY | — | RSA-приватный ключ (PEM, PKCS#8 или PKCS#1) подписи RS256 access-токенов оператора. Публичный ключ отдаётся по /.well-known/jwks.json, чтобы токены проверялись без владения ключом подписи. Эфемерный при отсутствии (access-токены инвалидируются на рестарте). Обязателен при replicaCount > 1. |
QF_ADMIN_USERNAME | — | Bootstrap-администратор: логин, создаётся при первом старте пустой БД. |
QF_ADMIN_PASSWORD | — | Bootstrap-администратор: пароль. |
QF_ADMIN_EMAIL | — | Bootstrap-администратор: email (опционально; также ключ привязки при OIDC). |
Сеть и адреса
| Ключ | Дефолт | Назначение |
|---|---|---|
QF_HTTP_ADDR | :8080 | Listen-адрес REST API + UI (за TLS-прокси). |
QF_GRPC_ADDR | :8443 | Listen-адрес gRPC (mTLS стационарный стрим агентов). |
QF_ENROLL_ADDR | :8444 | Listen-адрес gRPC enrollment (первичный bootstrap, без mTLS). |
QF_CP_HOST | localhost | Внешнее имя или IP Control Plane для SAN серверного сертификата. В рабочей среде указывается адрес, доступный агентам. |
QF_CP_ENDPOINT | localhost:8444 | Внешний enrollment-адрес, который Control Plane возвращает агентам в EnrollResponse. |
QF_TRUSTED_PROXIES | — | CIDR доверенных reverse-прокси (через запятую). Нужен, когда REST за прокси, чтобы CP видел реальный client-IP, а не адрес прокси. Также задаёт список доверенных балансировщиков для QF_AGENT_PROXY_PROTOCOL. Невалидный CIDR пропускается с warning. |
QF_AGENT_PROXY_PROTOCOL | false | Разрешает PROXY protocol на agent-listener :8443 и :8444. Нужен за L4-балансировщиком, который меняет исходный IP агента: Control Plane использует этот IP для CIDR-групп. PROXY-заголовок принимается только от адресов из QF_TRUSTED_PROXIES. Балансировщик должен передавать TCP без завершения mTLS и отправлять PROXY-заголовок. |
PKI
| Ключ | Дефолт | Назначение |
|---|---|---|
QF_PKI_DIR | /etc/qf/pki | Каталог хранения CA-серта/ключа и ключа подписи бандлов. При replicaCount > 1 — на RWX-томе. |
Наблюдаемость
| Ключ | Дефолт | Назначение |
|---|---|---|
QF_LOG_LEVEL | info | Уровень slog: debug/info/warn/error. |
QF_METRICS_TOKEN | — | Bearer-токен для /metrics. Пусто → эндпоинт не монтируется (404); задан → скрейпер шлёт токен, промах = 401. Метрики несут host-лейблы (весь инвентарь) — эндпоинт default-closed. |
Тюнинг доставки и heartbeat
| Ключ | Дефолт | Назначение |
|---|---|---|
QF_LIVENESS_INTERVAL | 15s | Интервал публикации состояния хостов для UI. |
QF_UI_POLL_INTERVAL | 5s | Интервал чтения состояния хостов из БД для UI. Некорректное значение заменяется значением по умолчанию с предупреждением в журнале. |
QF_STATUS_STALE_SECONDS | 90 | Окно свежести heartbeat (сек): хост без heartbeat дольше → stale, снова свежий → active. |
QF_STATUS_PENDING_SECONDS | 120 | Задержка (сек) до pending: живой хост, не подтвердивший новую конфигурацию дольше этого окна. |
QF_STATUS_DEGRADED_SECONDS | 300 | Задержка (сек) до эскалации pending/stale → degraded. Должна превышать QF_STATUS_PENDING_SECONDS. |
QF_HEARTBEAT_FLUSH_INTERVAL_MS | 10000 | Интервал записи пачки heartbeat в БД, в миллисекундах. |
QF_HEARTBEAT_BATCH_MAX | 5000 | Размер пачки heartbeat, при котором запись начинается до истечения интервала. |
QF_INGEST_SHARDS | 1 | Число независимых очередей приёма rule-событий. События одного хоста попадают в одну очередь. |
QF_INGEST_LOG_WORKERS | 4 | Число обработчиков rule-событий на очередь. Общее число равно QF_INGEST_SHARDS × QF_INGEST_LOG_WORKERS и не должно превышать QF_INGEST_POOL_MAX. Значение меньше 1 или некорректное значение заменяется значением по умолчанию. |
QF_INGEST_POOL_MAX | 8 | Максимум соединений в отдельном пуле записи телеметрии. Сумма для всех реплик — реплики × (24 + 12 + QF_INGEST_POOL_MAX) — должна укладываться в max_connections PostgreSQL. |
QF_INGEST_MAX_BATCH | 2000 | Максимальный размер пачки для PostgreSQL COPY. Значение меньше 1 или некорректное значение заменяется значением по умолчанию. |
QF_INGEST_CHAN_BUF | 10000 | Размер каждой очереди. При переполнении новое событие теряется и учитывается в метрике потерь. Увеличение помогает при кратких всплесках, но не при постоянной перегрузке. |
SIEM-форвардер
Экспорт событий во внешний SIEM. Выключен, пока не задан QF_FORWARDER_DSN.
| Ключ | Дефолт | Назначение |
|---|---|---|
QF_FORWARDER_DSN | — | DSN приёмника. Пустое значение выключает передачу. Форматы и схемы описаны в руководстве по SIEM. |
QF_FORWARDER_MODE | tee | tee сохраняет rule-события в PostgreSQL и отправляет копию; exclusive только отправляет их. System- и audit-события сохраняются в обоих режимах. |
QF_FORWARDER_SPOOL | — | Путь к дисковому буферу на 100 МиБ для недоступного приёмника. Пустое значение выключает буфер. |
OIDC SSO
Внешний вход через OIDC-провайдера. Включается, только когда заданы все три:
QF_OIDC_ISSUER, QF_OIDC_CLIENT_ID, QF_OIDC_CLIENT_SECRET (иначе OIDC выключен).
| Ключ | Дефолт | Назначение |
|---|---|---|
QF_OIDC_ISSUER | — | URL OIDC-провайдера (issuer). |
QF_OIDC_CLIENT_ID | — | Client ID приложения. |
QF_OIDC_CLIENT_SECRET | — | Client secret приложения. |
QF_OIDC_REDIRECT_URL | /auth/oidc/callback | Redirect URL. Дефолт подставляется, когда OIDC включён, а значение пусто. |
QF_OIDC_ROLE_CLAIM | groups | Claim ID-токена, несущий группы/роли пользователя из IdP. Значение — строка или массив строк. |
QF_OIDC_GROUP_ROLE_MAP | — | Соответствие групп IdP ролям qf: группа1:роль1,группа2:роль2. Допустимы admin, editor и auditor; некорректные пары игнорируются. При пустом значении новый пользователь получает auditor, а существующий сохраняет роль. При заданном значении роль пересчитывается при каждом входе; используется наиболее привилегированная совпавшая роль, а без совпадений — auditor. Роль bootstrap-администратора из QF_ADMIN_EMAIL не понижается. Claim с группами задаёт QF_OIDC_ROLE_CLAIM. |
См. также
- install.md — установка Control Plane (Helm / systemd) + агента.
- install-airgapped.md — CP в закрытом контуре: секреты, PKI, RWX-том.
- ops-runbook.md — резервное копирование, ротация ключей и диагностика.
- agent-config.md — параметры стороны агента.