Файловый коллектор
Назначение
Файловый коллектор предназначен для сбора событий из текстовых файлов журналов
с локальной машины коллектора или с удалённого узла по протоколу SFTP.
Для каждой новой строки отслеживаемого файла формируется событие безопасности
с сохранением исходного текста в поле Raw.
Коллектор применяется в следующих сценариях:
- Источник событий записывает журналы только в локальные файлы и не поддерживает отправку по Syslog.
- Требуется собирать журналы прикладного программного обеспечения, веб-серверов, СУБД, контейнерных платформ.
- Необходимо обработать единовременно выгруженный файл журналов.
В качестве пути источника принимаются как полные имена файлов, так и шаблоны
с подстановочными символами (*, ?, **). Это позволяет одним источником
охватить все файлы каталога, все файлы заданного расширения или все файлы
во вложенных каталогах.
Установка коллектора
Предварительные условия:
- наличие лицензии (разрешения) на использование Файлового коллектора (см. «О программе»);
- сетевая доступность сервера KOMRAD с узла, на который устанавливается коллектор;
- для сбора с удалённых узлов — поддержка протокола SFTP на источнике и учётная запись с правом чтения собираемых файлов.
Порядок установки:
-
Перенести deb-пакет
komrad-file-collector*.debиз дистрибутива KOMRAD на узел, где будет работать коллектор. -
Установить пакет:
sudo dpkg -i ./komrad-file-collector*.deb -
Открыть файл конфигурации:
sudo nano /etc/echelon/komrad/komrad-file-collector.yaml -
Указать адрес шины событий KOMRAD в параметре
bus.servers:bus:servers:- nats://<IP_KOMRAD>:3490 -
Сохранить файл и перезапустить службу коллектора:
sudo systemctl restart komrad-file-collector.service -
После запуска коллектор отобразится в списке коллекторов в веб-интерфейсе.
Конфигурация
### schema: komrad/komrad-file-collector/4.1.33
# Идентификатор предприятия
tenant_id: 75
# Идентификатор установки
setup_id: komrad-production
# Метка безопасности, аналог Oracle Security Label
sl: 715
bus:
servers:
- nats://10.0.5.197:3490
user: komrad
password: pass
user-credentials: ""
tls:
disable: false
ServerName: ""
TrustedCA: /var/lib/echelon/komrad/certs/ca.pem
Cert: /var/lib/echelon/komrad/certs/client.pem
CertKey: /var/lib/echelon/komrad/certs/client-key.pem
system-pool: false
min-version: "1.3"
client-auth: require-and-verify-client-cert
tuning:
# Время ожидания при установке соединения.
connect-timeout: 10s
# Максимальное количество попыток повторного подключения.
max-reconnects: 1000000
# Максимальное время ожидания ответа.
max-wait: 0s
# Период отправки клиентских команд ping.
ping-interval: 2m
# Максимальное количество запросов ping без ответа сервера,
# после которого соединение закрывается.
max-pings-outstanding: 2
# Максимальное количество одновременных асинхронных публикаций.
publish-async-max-pending: 0
# Интервал между попытками переподключения.
reconnect-interval: 5s
# Время ожидания между попытками повторного подключения.
reconnect-wait: 1s
# Переходить в состояние повторного подключения,
# если первичное подключение не удалось.
retry-on-failed-connect: false
# Таймаут между попытками перезапуска коллектора при неустойчивой связи
# с центральным сервером KOMRAD.
restart-timeout: 1s
# local_ip: 10.0.0.1
# Настройки пакетной отправки событий. Накопление событий в пакеты
# повышает пропускную способность. Увеличение `timeout` до 3s и `limit`
# до 20000 позволяет достигать 100 000 EPS.
batching:
# Предельный интервал накопления пакетов. По умолчанию — 1 секунда.
timeout: 1s
# Предельное количество событий в пакете. По умолчанию — 100.
limit: 1000
# Настройки write-ahead-log (WAL). При разрыве связи с сетью события
# записываются на диск в сжатом виде, после восстановления соединения
# отправляются в шину событий KOMRAD.
# Объём свободного пространства на узле коллектора необходимо контролировать.
wal:
# Путь до каталога WAL. Если не указан, используется каталог по умолчанию:
# Windows: C:\Program Files\Echelon\komrad\<name>-collector\.wal
# Linux: /var/lib/echelon/komrad/<name>-collector/.wal
# При установке нескольких одинаковых коллекторов на один хост необходимо
# указывать разные пути; пути не должны быть вложенными друг в друга.
path: /var/lib/echelon/komrad/komrad-file-collector/.wal
# Режим оптимизации работы с памятью. Изменять только по рекомендации
# службы поддержки.
no-copy: true
# Размер одного сегмента WAL. По умолчанию — 4 МБ. Изменять только
# по рекомендации службы поддержки.
segment-size: 4MB
# Максимальная длина WAL. Значение 0 означает отсутствие ограничения.
max-length: 0
# Настройки вывода логов приложения. Поддерживается одновременный вывод
# в несколько целей: файл, системный журнал ОС, консоль, syslog.
#
# Пример вывода в консоль для режима отладки:
# - filename: stdout
# format: color
# filter: ""
# levels: [all]
#
# Пример вывода в файл с ротацией (старые файлы не удаляются автоматически,
# использование диска необходимо контролировать):
# - filename: "/var/log/echelon/komrad/service.log"
# format: json
# filter: ""
# levels: [info, error, warn, panic, fatal]
#
# Пример отправки критических сообщений в журнал Windows. Уровни info,
# warn, debug, error в windowseventlog включать не рекомендуется
# (отрицательно влияет на быстродействие и доступность узла):
# - filename: windowseventlog
# format: json
# levels: [panic, fatal]
log:
- filename: systemd/journal
format: json
filter: ""
levels:
- info
- error
- panic
- fatal
- warn
# Настройки дискового хранилища конфигурационных данных коллектора.
storage:
# Путь до каталога хранилища. Если не указан, используется каталог
# по умолчанию:
# Windows: C:\Program Files\Echelon\komrad\<name>-collector\.storage
# Linux: /var/lib/echelon/komrad/<name>-collector/.storage
# При установке нескольких одинаковых коллекторов на один хост необходимо
# указывать разные пути; пути не должны быть вложенными друг в друга.
path: /var/lib/echelon/komrad/komrad-file-collector/.storage
compress: false
# Включить синхронную запись каждого результата на диск.
# По умолчанию отключено.
sync-writes: false
# Путь к базе данных GeoIP.
geo-ip:
path: /var/lib/echelon/komrad/komrad-file-collector/geoip/db.mmdb
# Проверка корректности базы GeoIP при инициализации. Длительность —
# от 20 секунд до 2 минут в зависимости от ресурсов и размера базы.
# По умолчанию отключена.
verify-on-start: false
# Отключение записи исходного текста события в поле Raw.
# Большинство требований регулятора требуют сохранять исходный текст
# события. Сохранение увеличивает размер БД в 2–10 раз.
# Для коллекторов Файловый и Syslog отключение записи в Raw невозможно:
# исходный текст события является единственным источником данных.
disable-raw-field: false
# Использовать при работе только в локальном автономном режиме.
offline: false
plugins: []
events_file: ""
Подключение источника событий
Расположение в веб-интерфейсе: Управление ⇒ Настройки коллекторов ⇒ Файловый коллектор.
Параметры подключения
- Открыть карточку файлового коллектора.
- На вкладке «Источники» нажать «Добавить» — откроется форма создания нового источника.
- На вкладке «Подключение» указать:
- Название — имя узла-источника.
- Описание — произвольное описание.
- Протокол —
SFTPдля удалённого узла илиЛокальная машинадля сбора с того же узла, где работает коллектор. - Актив — IP-адрес источника (только для SFTP).
- Авторизация — порт, логин и пароль учётной записи. Поддерживается
авторизация по приватному ключу (сертификату); копию ключа необходимо
поместить в каталог
$HOME/.sshпользователя, от имени которого запущен коллектор.
Учётная запись, используемая для подключения, должна иметь право чтения собираемых файлов на стороне источника.
Сбор файлов и папок
На вкладке «Сбор событий» добавляются пути к собираемым файлам. Поле Путь принимает как полное имя файла, так и шаблон с подстановочными символами — коллектор раскрывает шаблон при каждом обходе каталога и подхватывает файлы, появившиеся после запуска источника.
Поддерживаемые подстановочные символы:
| Символ | Назначение |
|---|---|
* | Любая последовательность символов в пределах сегмента |
? | Один любой символ |
[…] | Один символ из указанного набора |
** | Рекурсивный обход вложенных каталогов |
Примеры:
/var/log/syslog # один конкретный файл
/var/log/*.log # все файлы с расширением .log в каталоге
/var/log/auditd-*.log # файлы по префиксу имени
/var/log/**/*.log # рекурсивный обход вложенных каталогов
/var/log/app-?.log # app-1.log, app-2.log, app-x.log и т.п.
Рекурсивный обход (**) выполняется на глубину до 8 уровней. Раскрытие
шаблона ** включено по умолчанию через параметр recursiveGlob: true
в дополнительных параметрах сбора.
Когда один шаблон захватывает больше файлов, чем требуется, дополнительная
фильтрация выполняется регулярными выражениями в параметрах
includeFiles и excludeFiles (см. раздел «Дополнительные параметры
сбора»). Например, для отбора файлов
по расширению:
{
"fileWatcher": {
"scanner": {
"includeFiles": ["\\.log$", "\\.txt$"],
"excludeFiles": ["\\.gz$", "\\.tmp$"]
}
}
}
Дополнительно для каждого пути в карточке источника задаются:
- Включить сбор — флаг активации пути; неактивные пути игнорируются.
- Игнорировать файлы старше — пропускать файлы, время последнего изменения которых раньше указанной длительности или абсолютной метки времени. Применяется к первому запуску — ранее необработанные старые файлы не будут прочитаны.
После сохранения настроек источника коллектор необходимо запустить (или перезапустить, если он уже был запущен). События, поступающие от источника, отображаются в разделе События ⇒ События в реальном времени.
При использовании шаблонов следует избегать перекрывающихся путей в разных источниках одного коллектора — один и тот же файл будет прочитан дважды, события продублируются.
Дополнительные параметры сбора
Расширенные параметры задаются JSON-документом на отдельной вкладке
карточки источника. Документ соответствует proto-схеме FilestreamConfig
(echelon.komrad.collector.v2.FilestreamConfig): имена полей
в camelCase, значения перечислений — строковые константы вида
ENCODING_*, LINE_TERMINATOR_*, PARSER_KIND_*, MULTILINE_TYPE_*,
длительности — строки ISO-8601 ("5s", "10s", "0s").
Полный пример со значениями по умолчанию:
{
"id": "",
"reader": {
"encoding": "ENCODING_UNSPECIFIED",
"excludeLines": [],
"includeLines": [],
"lineTerminator": "LINE_TERMINATOR_AUTO",
"parsers": {
"parsers": [
{
"kind": "PARSER_KIND_MULTILINE",
"multiline": {
"match": "after",
"pattern": "",
"flushPattern": "",
"countLines": 1,
"type": "MULTILINE_TYPE_COUNT_MODE",
"negate": false,
"skipNewLine": false,
"maxLines": null,
"timeout": null
}
}
]
}
},
"close": {
"onStateChange": {
"checkInterval": "5s",
"inactive": "10s",
"removed": true,
"renamed": false
},
"reader": {
"afterInterval": "0s",
"onEof": false
}
},
"fileWatcher": {
"scanner": {
"symlinks": null,
"recursiveGlob": true,
"excludeFiles": [],
"includeFiles": []
}
},
"alertFileChanges": true
}
Кнопка «Проверить» на вкладке выполняет валидацию JSON-документа без сохранения. Кнопка «Сохранить» применяет конфигурацию к источнику.
Идентификатор (id)
| Параметр | Тип | По умолчанию | Назначение |
|---|---|---|---|
id | string | "" | Внутренний идентификатор конфигурации потока. Заполняется автоматически и сохраняется между сеансами для сопоставления состояний отслеживаемых файлов. |
Чтение файла (reader)
| Параметр | Тип | По умолчанию | Назначение |
|---|---|---|---|
encoding | enum | ENCODING_UNSPECIFIED | Кодировка файла. Допустимые значения: ENCODING_UNSPECIFIED (UTF-8), ENCODING_PLAIN, ENCODING_UTF8, ENCODING_GBK, ENCODING_ISO8859_1, ENCODING_ISO8859_5, ENCODING_KOI8R, ENCODING_CP866, ENCODING_MACINTOSH, ENCODING_WINDOWS1250, ENCODING_WINDOWS1251, ENCODING_WINDOWS1256, ENCODING_UTF16BOM. |
excludeLines | string[] | [] | Регулярные выражения. Строки, соответствующие любому выражению, отбрасываются до отправки в шину событий. |
includeLines | string[] | [] | Регулярные выражения. При непустом списке сохраняются только строки, соответствующие хотя бы одному выражению. Если заданы оба списка, includeLines применяется первым. |
lineTerminator | enum | LINE_TERMINATOR_AUTO | Разделитель строк. Допустимые значения: LINE_TERMINATOR_AUTO, LINE_TERMINATOR_LINE_FEED, LINE_TERMINATOR_VERTICAL_TAB, LINE_TERMINATOR_FORM_FEED, LINE_TERMINATOR_CARRIAGE_RETURN, LINE_TERMINATOR_CARRIAGE_RETURN_LINE_FEED, LINE_TERMINATOR_NEXT_LINE, LINE_TERMINATOR_LINE_SEPARATOR, LINE_TERMINATOR_PARAGRAPH_SEPARATOR, LINE_TERMINATOR_NULL_TERMINATOR. |
parsers | object | см. ниже | Цепочка парсеров, применяемых к прочитанным строкам. |
Парсеры (reader.parsers.parsers[])
reader.parsers.parsers — упорядоченный массив парсеров. Каждый элемент
описывается типом (kind) и блоком конфигурации соответствующего типа.
Поддерживаемые типы:
Значение kind | Назначение |
|---|---|
PARSER_KIND_MULTILINE | Объединение нескольких строк в одно событие. Настраивается полем multiline (см. ниже). |
PARSER_KIND_NDJSON | Разбор построчного JSON. Каждая строка интерпретируется как JSON-документ. |
PARSER_KIND_CONTAINER | Разбор журналов контейнеров (Docker, CRI). |
В текущей версии proto-схемы UI-редактор передаёт настройки только
для парсера multiline. Параметры ndjson и container принимаются
со значениями по умолчанию.
multiline — объединение многострочных событий
| Параметр | Тип | По умолчанию | Назначение |
|---|---|---|---|
type | enum | MULTILINE_TYPE_COUNT_MODE | Режим объединения: MULTILINE_TYPE_PATTERN_MODE — по регулярному выражению, MULTILINE_TYPE_COUNT_MODE — по количеству строк, MULTILINE_TYPE_WHILE_PATTERN_MODE — пока строки соответствуют шаблону. |
pattern | string | "" | Регулярное выражение для режимов PATTERN_MODE и WHILE_PATTERN_MODE. |
negate | bool | false | Инвертирование результата проверки pattern. |
match | string | after | Стратегия объединения строк: after — относительно последнего совпадения, before — относительно следующего совпадения. |
countLines | int32 | 1 | Количество строк, объединяемых в одно событие (для COUNT_MODE). |
maxLines | int32 | null | null | Верхний предел числа строк в одном событии. |
timeout | duration | null | null | Таймаут ожидания строк, после которого накопленные строки отправляются как событие. Формат — строка ISO-8601 ("5s"). |
flushPattern | string | "" | Регулярное выражение, завершающее многострочное событие. При совпадении накопленные строки отправляются немедленно. |
skipNewLine | bool | false | Объединять строки без разделителя \n. |
Завершение работы обработчика (close)
| Параметр | Тип | По умолчанию | Назначение |
|---|---|---|---|
close.onStateChange.checkInterval | duration | "5s" | Периодичность проверки состояния файла (изменение размера, переименование, удаление). |
close.onStateChange.inactive | duration | "10s" | Таймаут закрытия дескриптора при отсутствии изменений файла. |
close.onStateChange.removed | bool | true | Закрывать обработчик при удалении файла. |
close.onStateChange.renamed | bool | false | Закрывать обработчик при переименовании файла. |
close.reader.afterInterval | duration | "0s" | Таймаут закрытия обработчика с момента его запуска. "0s" — отключено. |
close.reader.onEof | bool | false | Закрывать обработчик при достижении конца файла. Возможна потеря данных, если файл будет дописан после закрытия. |
Обнаружение новых файлов (fileWatcher.scanner)
| Параметр | Тип | По умолчанию | Назначение |
|---|---|---|---|
fileWatcher.scanner.symlinks | bool | null | null | Обрабатывать символические ссылки наряду с обычными файлами. |
fileWatcher.scanner.recursiveGlob | bool | null | true | Раскрывать шаблон ** в путях для рекурсивного обхода вложенных каталогов. Глубина — до 8 уровней. |
fileWatcher.scanner.excludeFiles | string[] | [] | Регулярные выражения. Файлы, имя которых соответствует хотя бы одному выражению, игнорируются. |
fileWatcher.scanner.includeFiles | string[] | [] | Регулярные выражения. При непустом списке обрабатываются только файлы, имя которых соответствует хотя бы одному выражению. Удобно для отбора по расширению: ["\\.log$"]. |
Уведомления об изменении файлов (alertFileChanges)
| Параметр | Тип | По умолчанию | Назначение |
|---|---|---|---|
alertFileChanges | bool | true | Формировать события при создании, перемещении и удалении файлов в отслеживаемом каталоге. |
Параметры идентификации файлов (fileIdentity), ротации, лимита
обработчиков, очистки реестра и метаданных событий не вынесены в текущую
proto-схему FilestreamConfig и используют значения по умолчанию из
backend-конфигурации коллектора.
Примеры конфигурации источников
Ниже приведены типовые конфигурации источников для распространённых сценариев сбора. В каждом примере указано значение поля Путь на вкладке «Сбор событий» и JSON-документ для вкладки «Дополнительные параметры сбора». Поля, не упомянутые в примере, остаются со значениями по умолчанию.
Сценарий 1. Системные журналы Linux из одного каталога
Сбор журналов аутентификации и системных событий с локальной машины коллектора. Файлы записываются построчно в UTF-8, специальной обработки не требуют.
Поле Путь:
/var/log/auth.log
/var/log/syslog
Дополнительные параметры — значения по умолчанию.
Сценарий 2. Рекурсивный сбор журналов микросервисов
Несколько прикладных служб записывают журналы в подкаталоги общего
каталога (/var/log/apps/<service>/...). Состав каталогов меняется
по мере масштабирования служб, новые файлы должны подхватываться
автоматически. В каталогах присутствуют сжатые архивы и нумерованные
ротированные файлы (app.log.1, app.log.2.gz), которые собирать
не нужно.
Поле Путь:
/var/log/apps/**/*.log
Дополнительные параметры:
{
"fileWatcher": {
"scanner": {
"recursiveGlob": true,
"includeFiles": ["\\.log$"],
"excludeFiles": ["\\.gz$", "\\.\\d+$"]
}
}
}
recursiveGlob: true раскрывает ** на глубину до 8 уровней.
includeFiles оставляет только активные .log-файлы, excludeFiles
отбрасывает архивы (*.gz) и нумерованные ротированные файлы
(*.1, *.2, …).
Сценарий 3. Журналы nginx с ротацией logrotate
nginx ротирует журналы доступа через logrotate: активный файл
переименовывается в access.log.1, создаётся новый пустой access.log,
старые архивы пакуются в gzip. Коллектор должен закрыть обработчик
переименованного файла, открыть новый и не читать архивные копии
повторно.
Поле Путь:
/var/log/nginx/access.log
/var/log/nginx/error.log
Дополнительные параметры:
{
"close": {
"onStateChange": {
"renamed": true,
"removed": true,
"inactive": "30s"
}
},
"fileWatcher": {
"scanner": {
"excludeFiles": ["\\.\\d+$", "\\.gz$"]
}
}
}
renamed: true закрывает обработчик при переименовании активного файла
во время ротации. inactive: "30s" освобождает дескриптор файла,
в который не пишут более 30 секунд — это уменьшает количество открытых
файлов при большом числе виртуальных хостов.
Сценарий 4. Многострочные stack trace Java-приложения
Журнал Java-приложения содержит многострочные стек трейсы. Каждая запись
начинается со строки с меткой времени вида 2026-05-27 10:30:15,
последующие строки трейса начинаются с пробельных символов и относятся
к той же записи.
Поле Путь:
/opt/myapp/logs/application.log
Дополнительные параметры:
{
"reader": {
"parsers": {
"parsers": [
{
"kind": "PARSER_KIND_MULTILINE",
"multiline": {
"type": "MULTILINE_TYPE_PATTERN_MODE",
"pattern": "^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}",
"negate": true,
"match": "after",
"timeout": "5s",
"maxLines": 500
}
}
]
}
}
}
Регулярное выражение распознаёт строки, начинающиеся с метки времени.
negate: true инвертирует проверку: строки, не соответствующие шаблону
(продолжения трейса), присоединяются к предыдущему событию по правилу
match: after. timeout: "5s" гарантирует отправку события, если новые
строки не поступают, maxLines: 500 ограничивает размер одного события
во избежание неконтролируемого роста при некорректных журналах.
Сценарий 5. Журналы Windows-сервиса по SFTP в кодировке Windows-1251
Сбор журналов прикладного сервиса с удалённого узла Windows через SFTP.
Файлы сохранены в кодировке Windows-1251 (кириллица) и используют
разделитель строк CRLF (\r\n). Имена файлов содержат дату
и обновляются ежедневно.
Параметры подключения: протокол SFTP, IP-адрес узла Windows, учётная
запись с правом чтения каталога журналов.
Поле Путь:
C:/ProgramData/MyService/logs/*.log
Дополнительные параметры:
{
"reader": {
"encoding": "ENCODING_WINDOWS1251",
"lineTerminator": "LINE_TERMINATOR_CARRIAGE_RETURN_LINE_FEED"
},
"close": {
"onStateChange": {
"inactive": "5m"
}
}
}
ENCODING_WINDOWS1251 корректно декодирует кириллические символы;
без этого параметра коллектор по умолчанию интерпретирует ввод
как UTF-8 и кириллица отображается заменителями. inactive: "5m"
повышает порог простоя — журналы по SFTP обновляются реже, чем
локальные файлы, и преждевременное закрытие дескриптора приводит
к лишним SFTP-сессиям.
Сценарий 6. JSON-журналы контейнеров Docker
Docker записывает журналы каждого контейнера в отдельный JSON-файл
в каталоге /var/lib/docker/containers/<container-id>/<container-id>-json.log.
Каждая строка файла — это JSON-документ вида
{"log": "...", "stream": "stdout", "time": "..."}. Коллектор должен
извлечь поле log в качестве текста события и метку времени time
вместо времени чтения строки. Для каждого нового контейнера появляется
новый подкаталог, который должен подхватываться автоматически.
Поле Путь:
/var/lib/docker/containers/*/*-json.log
Дополнительные параметры:
{
"reader": {
"parsers": {
"parsers": [
{
"kind": "PARSER_KIND_CONTAINER"
}
]
}
}
}
Парсер PARSER_KIND_CONTAINER автоматически распознаёт формат
(docker, json_file, cri) и принимает оба потока — stdout
и stderr. Дополнительная настройка из UI не требуется: формат
и поток выбираются автоматически.
Каталог /var/lib/docker/containers/ по умолчанию доступен только
пользователю root или членам группы docker. Учётная запись, от имени
которой запущена служба komrad-file-collector, должна быть включена
в группу docker либо иметь явные права на чтение этого каталога.
При использовании платформы Kubernetes (containerd, CRI-O) подходит
тот же сценарий с путём /var/log/pods/**/*.log — парсер распознает
CRI-формат автоматически.
Удаление
Файловый коллектор удаляется командой:
sudo dpkg -P komrad-file-collector