Параметры qf-agent
Все параметры агента задаются в /etc/qf/agent.conf в формате KEY=VALUE.
Пустые строки и комментарии после # игнорируются. Переменные окружения с тем же
именем переопределяют значения файла.
Для первого подключения нужны QF_ENDPOINT, QF_ENROLL_TOKEN и один способ
проверить CA сервера: QF_ENROLL_CA, QF_ENROLL_CA_FINGERPRINT или
QF_ENROLL_CA_FETCH=true. Последний вариант безопасен только при публично доверенном
TLS-сертификате REST API. После первого подключения агент использует сохранённый
<QF_PKI_DIR>/ca.crt. Остальные параметры имеют значения по умолчанию или выводятся
из окружения хоста.
Ansible-роль qf-agent формирует файл из переменных qf_* в defaults/main.yml.
Переопределения задаются в group_vars, host_vars или через -e.
Подключение и энролмент
| Ключ | Дефолт | Назначение |
|---|---|---|
QF_ENDPOINT | localhost:8443 | Адрес CP (host или host:port). Из него выводятся адреса gRPC (:31443 или :port), enrollment (:31444 или :port+1) и REST (https://host). |
QF_IFACES | — | Имена интерфейсов через запятую или пробел, например eth0,eth1. В многоинтерфейсном режиме агент подключается к каждому из них и применяет отдельную область политики. Если список пуст, используется QF_IFACE. См. «Многоинтерфейсные хосты». |
QF_IFACE | авто | Один интерфейс для подключения BPF, если QF_IFACES пуст. Если не задан и он, агент определяет интерфейс по маршруту по умолчанию. |
QF_PKI_DIR | /etc/qf | Каталог с agent.crt/agent.key/ca.crt/bundle-signing.pub. |
QF_LOG_LEVEL | info | Уровень slog: debug/info/warn/error. |
QF_ENROLL_TOKEN | — | Bootstrap-токен для первого подключения. После успешного подключения значение удаляется из файла, но остаётся в памяти процесса для аварийного повторного enrollment при уже истёкшем сертификате. Обычное продление сертификата происходит автоматически и токена не требует. |
QF_ENROLL_CA | — | Путь к CA в PEM для проверки TLS enrollment-сервера. Имеет наивысший приоритет. Если значение пустое, используется сохранённый <QF_PKI_DIR>/ca.crt; только при отсутствии обоих применяются fingerprint или fetch. |
QF_ENROLL_CA_FETCH | false | Разрешает получить CA через REST /pki/ca.crt, когда нет явного или сохранённого CA и fingerprint. Подходит только для REST API с сертификатом от доверенного системного центра сертификации. С внутренним CA первый ответ нельзя проверить. |
QF_ENROLL_CA_FINGERPRINT | — | SHA-256 сертификата CA в DER, в hex. Когда явного и сохранённого CA нет, агент получает CA через REST и принимает его только при совпадении отпечатка. Отпечаток передаётся через отдельный доверенный канал, а не с того же Control Plane. |
Поведение datapath
| Ключ | Дефолт | Назначение |
|---|---|---|
QF_FAIL_CLOSED | false | Действие датапаса, пока нет применённого bundle и валидного last-good cache. false (fail-open) пропускает трафик; true (fail-closed) режет его до первого валидного bundle. При наличии cache он применяется до подключения к CP. |
QF_DROP_IPV6 | true | При true datapath отбрасывает весь IPv6. При false правила CIDR, ipset и stateful conntrack обрабатывают IPv6 наравне с IPv4. До отключения флага на dual-stack-хосте нужны разрешения для ICMPv6 ND/RA, иначе хост может потерять сетевую связность. |
QF_DROP_FRAGMENTS | false | При true отбрасывает IPv4- и IPv6-фрагменты. При значении по умолчанию фрагменты проходят без оценки L4-правил, потому что datapath на TC-хуке не собирает их заново. Включение может нарушить крупные UDP-, DNS- и NFS-передачи. Параметр действует локально на агенте и не переопределяется политикой. |
QF_DENY_UNKNOWN_PROTO | false | При true направляет пакеты с неподдерживаемым L4-протоколом, например SCTP, GRE или ESP, в default action хоста. Если default action равен ALLOW, такие пакеты проходят. При false они проходят без оценки правил. Параметр действует локально на агенте. |
QF_MASK_MAC | false | В Hello слать только OUI-префикс MAC (privacy для регулируемых сред). |
QF_CONNTRACK_MAX | 65536 | Размер conntrack LRU (max_entries). Изменение требует перезапуска агента; несовместимый размер закреплённой карты приводит к её пересозданию и потере состояний соединений. Значение увеличивают при вытеснении записей на нагруженном шлюзе и уменьшают при ограниченной памяти. |
QF_CONNTRACK_LOOSE | false | Режим conntrack loose. При true агент подхватывает активные mid-flow TCP-соединения (пакеты без SYN) и создает для них conntrack-записи на лету. |
QF_CONNTRACK_SKIP_UNRULED | false | Не трекать трафик, не совпавший ни с одним правилом (уходит в default action). true экономит слоты conntrack-LRU на высоко-объёмных default-allow потоках. Не влияет на потоки с явным правилом (для них — per-rule notrack). |
QF_CONNTRACK_TIMEOUT_TCP_EST | 7200 | Таймаут (в секундах) простоя для TCP-сессий в состоянии ESTABLISHED. |
QF_CONNTRACK_TIMEOUT_TCP_XION | 120 | Таймаут (в секундах) простоя для TCP-сессий в переходных/закрытых состояниях (SYN_SENT, FIN_WAIT, LAST_ACK, CLOSED). |
QF_CONNTRACK_TIMEOUT_UDP | 120 | Таймаут (в секундах) простоя для UDP-сессий. |
QF_CONNTRACK_TIMEOUT_ICMP | 30 | Таймаут (в секундах) простоя для ICMP/ICMPv6-сессий. |
Last-good cache и рестарт
Последний успешно применённый подписанный bundle хранится по фиксированному пути
/var/lib/qf/policy.blob. На старте агент проверяет его подпись ключом
bundle-signing.pub и применяет к датапасу до первой попытки подключения к CP.
Поэтому рестарт при недоступном CP сохраняет явные правила из last-good cache.
Успешный live apply атомарно заменяет cache. Watchdog при разрыве stream дольше
60 секунд откатывает datapath и кэш на предыдущее поколение. Ошибка записи кэша
делает apply неуспешным: агент восстанавливает предыдущее поколение, а CP может
повторить доставку. Если не удался сам watchdog rollback, поколение остаётся pending:
агент повторяет откат с bounded backoff, в том числе после reconnect, и отправляет CP
system-событие bundle_rollback_failed. Одно повторное подключение не подтверждает
поколение: попытки отката продолжаются до восстановления last-good. В конфигурации
fail-open отсутствие кэша или неверная подпись оставляют хост без сохранённой политики
до получения корректного bundle; причина записывается в journal.
Многоинтерфейсные хосты
QF_IFACES вводит хост в многоинтерфейсный режим: агент привязывается к каждому
перечисленному NIC (одна identity, одна gRPC-сессия, один подписанный бандл) и
энфорсит per-interface-scoped политику. Набор — список ИМЁН через запятую/пробел
в agent.conf (или per-host qf_ifaces в Ansible-inventory); пусто → QF_IFACE
→ автодетект default-route.
- Набор задаётся явно. Авто-attach ко всем интерфейсам ОС не делается: loopback/veth/bridge/CNI не отличить от реальных NIC общим правилом.
- Имена NIC — стабильные. Конфигурация по именам, агент резолвит их в ifindex
в рантайме; имя должно переживать перезагрузку (udev/systemd
ens*/enp*). NIC, отсутствующий на момент apply, приводит к отклонению бандла и удержанию last-good.
Область политики по интерфейсам, порядок раскатки (capability-gate), поведение conntrack и телеметрии, апгрейд и откат — multi-interface-policy.md.
См. также
- install.md — установка агента, матрица ядро→datapath.
- host-enrollment.md — механика токенов и CA-доверия.
- ops-runbook.md — эксплуатационные процедуры.