Skip to content

Latest commit

 

History

History
404 lines (253 loc) · 21.7 KB

CONFIG.ru.md

File metadata and controls

404 lines (253 loc) · 21.7 KB
Raw

Полное описание конфигурационных файлов

Общие замечания

Конфигурация состоит из двух общих конфигурационных файлов и нескольких файлов, которые описывают объекты мониторинга.

Конфигурационные файлы в xenoeye — это JSON, в котором разрешены комментарии.

Допускаются два типа комментариев: однострочные, начинаются с // и продолжаются до конца строки и многострочные, начинаются с /* и заканчиваются */

При чтении конфигов неизвестные ключи игнорируются

Главный файл конфигурации xenoeye.conf

Файл состоит из таких разделов:

{
	"capture": [
		{"socket": {"listen-on": "*", "port": "2055"}},
		{"pcap" : {"interface": "eth0", "filter": "udp and port 2055"}}
	],

	"sflow-capture": [
		{"pcap": {"interface": "eth0", "filter": "udp and port 6343"}},
		{"socket": {"listen-on": "*", "port": "6343"}}
	]

	"templates": {
		"db": "/var/lib/xenoeye/templates.tkvdb"
	},

	"debug": {
		/* allowed values: "none", "syslog", "/path/to/file.txt" */
		"dump-flows": "none"
	},

	"devices": "/etc/xenoeye/devices.conf",

	"mo-dir": "/var/lib/xenoeye/mo"
}

Секция capture

Каждый элемент из массива описывает поток обработки netflow.

Коллектор может захватывать netflow-пакеты двумя способами: обычным интерфейсом сокетов и с помощью pcap

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

pcap — захват netflow-пакетов с помощью библиотеки libpcap.

Параметр interface - название интерфейса, на котором захватывать netflow и filter - BPF-фильтр.

BPF-фильтр может быть пустым, тогда коллектор будет пытаться парсить все UDP-пакеты на этом интерфейсе.

Рабочий поток захватывает только те пакеты, которые матчатся фильтром.

Секция sflow-capture

Описывает потоки обработки sFlow. Формат такой же, как и в секции capture

Секция templates

В этой секции можно указать файл, в котором хранятся netflow-шаблоны. Шаблоны хранятся на диске, после старта коллектор читает их и может сразу декодировать фловы.

Для того, чтобы различать устройства, используется комбинация IP адреса источника netflow (роутера) плюс ID источника.

Иногда для дублирования потоков netflow используют https://github.com/sleinen/samplicator или аналоги. Если вы собираете данные из нескольких роутеров, то после сампликатора у них в качестве IP адреса источника может быть адрес самого сампликатора.

Секция debug

Коллектор может печатать для отладки содержимое декодированных фловов. В зависимости от значения "dump-flows" он может печатать в syslog + stderr или в файл.

Если выбрана печать в syslog, сообщения дополнительно выводятся в stderr (LOG_PERROR). Facility = LOG_USER, level = LOG_DEBUG.

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

Ключи devices и mo-dir

Указывают на файл с частотой семплирования и каталог с объектами мониторинга (см. ниже)

Ключ geodb

Путь к GeoIP/AS базам, по умолчанию '/var/lib/xenoeye/geoip/'

Установка частоты семплирования devices.conf

Коллектор (по крайней мере сейчас) не читает данные о частоте семплирования из option template. Для установки частоты нужно записать ее в файл devices.conf.

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

[
	{
		"ip": "127.0.0.1",
		"id": 0,
		"sampling-rate": 1
	},
	{
		"ip": "1.2.3.4",
		"sampling-rate": 1000
	}
	/* ... */
]

ip - адрес устройства, id - его идентификатор. Если включить отладочную печать фловов, то IP, ID и частота семплирования устройства будет печататься в конце каждого флова.

По умолчанию частота семплирования равна 1.

Описание объекта мониторинга mo.conf

В каталоге с объектами мониторинга находятся подкаталоги с файлами mo.conf. Эти файлы описывают объекты мониторинга.

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

	"filter": "dst net mynet",

	"debug": {
		"dump-flows": "none"
	},

	"classification": [
		{
			"fields": ["proto", "mfreq(src port,dst port)", "tcp-flags"],
			"top-percents": 90,
			"time": 30,
			"val": "octets desc"
		}
		,
		{
			"id": 3,
			"fields": ["div_r(octets,packets,100)"],
			"top-percents": 90,
			"time": 30,
			"val": "packets desc"
		}
	],

	"mavg": [
		{
			"name": "mavg1",
			"time": "10",
			"dump": "10",
			"fields": ["dst host", "packets"],
			"overlimit": [
					{
						"name": "level1",
						"limits": "limits1.csv",
						"default": [100000],
						"action-script": "/var/lib/xenoeye/scripts/act.sh",
						"back2norm-time": 5,
						"back2norm-script": "/var/lib/xenoeye/scripts/back.sh"
						"ext": ["ext", "other_mo/ext"]
					}
			]
		}
	]

	,

	"fwm": [
		{
			"name": "fw1",
			"fields": ["src host", "packets desc", "octets desc"]
			"time": 15,
			"limit": 5
		},
		{
			"extended": true,
			"name": "ext",
			"fields": ["octets desc", "src host", "dst host", "proto"]
			"time": 5,
			"limit": 100
		}
	]
}

Ключ filter

Правило на BPF-подобном языке, которое описывает этот объект мониторинга. В правиле могут быть использованы любые netflow-поля или функции, которые известны системе.

Допускается пустой фильтр, в этом случае в объект мониторинга попадут все фловы.

Синтаксис фильтра:

filter = IP_ADDR_FIELD_NAME <IPv4/IPv6 ADDR>    /* одиночный адрес */

filter = IP_ADDR_FIELD_NAME <ADDR_LIST_FILE>    /* файл со списком адресов */

filter = INT_FIELD_NAME INT_VAL                 /* одиночное значение */

filter = INT_FIELD_NAME INT_VAL_MIN-INT_VAL_MAX /* диапазон значений */

filter = FIELD_NAME V1 or V2 or V3 ...          /* перечисление нескольких возможных значений */


filter = NOT <expr>  /* инверсия выражения */

filter = <expr1> AND <expr2> AND <expr3> ...    /* несколько условий, которые должны выполняться одновременно */

filter = <expr1> OR <expr2> OR <expr3> ...      /* несколько условий, должно выполняться хотя бы одно */

filter = <expr1> AND (<expr2> OP <expr3>)       /* приоритет AND выше чем у OR, скобки могут изменять приоритет */

Часть полей может иметь префикс src или dst (например, src as или dst host). Если префикс не указан, то будет использоваться как dst так и src.

У полей IPv6 есть суффикс 6 - host6/net6.

Примеры:

dst net my-net - трафик с IP назначения из списка my-net

net bogon-net - фильтр отберет фловы у которых или IPV4_SRC_ADDR или IPV4_DST_ADDR принадлежат bogon-сетям

src net6 bogon-net and dst net6 bogon-net - трафик у которого одновременно и src IPv6 и dst IPv6 принадлежат bogon-сетям

dst as 12345 and not (dst host 1.2.3.4 or 2.3.4.5 or 3.4.5.6) - фловы у которых dst автономная система 12345, исключая несколько адресов

Текущий список доступных netflow-полей: filter.def

См. также Как добавить в коллектор новое Netflow-поле"

Поля dns-name, dns-ips и sni используются только для sFlow.

Текущий список доступных функций:

  • continent(ip) - двухбуквенный код континента в нижнем регистре (eu, as, ...)

  • country_code(ip) - двухбуквенный код страны в нижнем регистре (es, ru, cn, ...)

  • country(ip) - полное название страны

  • state(ip) - штат (область)

  • city(ip) - город

  • zip(ip) - индекс

  • lat(ip) - широта

  • long(ip) - долгота

  • asn(ip) - номер автономной системы

  • asd(ip) - текстовое описание автономной системы

  • min(port1, port2) - выбирает минимальное значение из port1 и port2

  • mfreq(port1, port2) - выбирает более часто используемый порт

  • div(aggr1, aggr2) - обычное деление, используется для определения среднего размера пакета

  • divr(aggr1, aggr2, N) - деление c округлением

  • divl(aggr1, aggr2, N) - деление c округлением вниз к целой степени N

Секция debug

Допускаются те же значения, что и в секции debug главного конфигурационного файла.

Но, в отличие от общей отладки, будут печататься только фловы, которые принадлежат данному объекту монторинга

Секция fwm

Массив, описывающий несколько временны́х окон фиксированного размера.

Описание ключей:

name: имя окна. Из этого имени формируется название таблицы в PostgreSQL, в которую будут экспортироваться данные. Название таблицы = каталог объекта мониторинга + _ + имя окна.

fields: массив netflow-полей и функций, которые будут экспортироваться. Используются те же поля, что и в фильтре. При экспорте записи будут отсортированы по полям, от меньших значений к большим. Для того чтобы изменить порядок, нужно побавить desc после названия поля.

Например, если записать поля так: fields = ["src host", "octets"]

То коллектор будет сортировать результат по порядку src IP (от меньших к большим)

А если записать так: fields = ["octets desc", "src host"]

То результат будет отсортирован по количеству байт от больших значений к меньшим.

Порядок сортировки имеет смысл когда используется ключ limit. С помощью порядка можно экспортировать не все IP, а только top самых значимых. Остальные будут просуммированы и экспортируются отдельной строкой.

time: размер окна (время в секундах). Коллектор будет генерировать файл для экспорта в СУБД для этой таблицы с таким интервалом. По умолчанию time = 30.

limit: сколько экспортировать записей за один раз. Если записей больше чем это значение, то будут экспортированы только первые и остаток одной строкой. По умолчанию экспортируются все записи.

extended: помечает, что это окно неактивно при старте и будет активизировано только при превышении порога скользящим средним. По умолчанию false.

Секция mavg

Массив, описывающий несколько скользящих средних. Скользящие средние для одного объекта мониторинга могут отличаться друг от друга набором полей и размером окна. Чем больше окно, тем плавнее изменяется скользящее среднее.

Описание ключей:

name: имя, используется при запуске скриптов (передается как один из параметров)

time: размер (в секундах) окна скользящего среднего. По умолчанию 5 секунд

dump: время (в секундах) между дампами значений скользящих средних. По умолчанию 0 (дамп запрещен). Если вы хотите видеть текущие значения скользящих средних, выставьте этот параметр

fields: массив netflow-полей и функций, по которым коллектор будет следить за скользящим средним. Поля такие же, как и в секции fwm

mem-m: размер памяти (в мегабайтах) для . По умолчанию 256M

overlimit: массив, описывающий превышение порогов

Описание ключей элементов overlimit

name: имя, используется при запуске скриптов (передается как один из параметров)

limits: файл с порогами (см. ниже), опциональный параметр

default: порог по умолчанию (если адреса или набора полей нет в файле limits)

action-script: путь к скрипту, который запустится при превышении порога.

back2norm-time: время, которое система ждет после того как трафик опустился ниже порога. Скользящее среднее может очень быстро пробивать порог сверху и снизу, чтобы не дергать постоянно скрипты существует этот параметр

back2norm-script: путь к скрипту, который запустится когда трафик вернется в норму

ext: массив элементов расширенной статистики. После пробития порога эти элементы активируются, таблицы начинают заполняться данными. Допускается активация элементов из других объектов мониторинга, например при пробитии порога ingress-трафика можно включить расширенную статистику и на egress-трафике.

Секция classification

Массив, описывающий классификацию трафика для этого объекта мониторинга

Описание ключей:

fields: список netflow-полей или функций, по которым будет классифицироваться трафик.

time: время в секундах, за которое накапливается статистика для классификации. Классификация происходит постоянно, каждые time секунд

top-percents: процент трафика из выборки, который будет классифицироваться

val: значение, по которому будет сортироваться выборка перед классификацией. "octets desc" или "packets desc" - по байтам или пакетам

id: номер класса. После классификации к каждому флову будет добавлено виртуальное поле с именем класса. Эти поля с именами называются class0, class1, ..., разные для каждой секции. Если нужно изменить цифру в названии, это можно сделать изменением этого ключа. Например, если выставить "id": 3, имена классов будут записываться в поле class3. Всего допускается до 5 классификаторов на один объект мониторинга

Эти виртуальные поля с именами классов можно использовать в секциях fwm и mavg, так же как и остальные netflow-поля.

База с результатами классификации хранится в файловой системе, в виде файлов и каталогов. Для переименования класса нужно отредактировать файл /var/lib/xenoeye/clsf/<название объекта мониторинга>/<номер классификатора>/<клаcc>/name Можно назвать одним именем несколько классов. Файлы с названиями классов перечитываются каждые time секунд.

Файлы с порогами

Пороги записываются в CSV-формате, поля должны быть в том же порядке, что и в ключе fields.

Если "fields": ["src host", "octets"], то файл с порогами должен выглядеть так:

1.2.3.4,1000000
1.2.3.5,2000000

Будьте внимательны, 1000000 и 2000000 - это октеты (байты) в секунду.

Можно выставить пороги не просто по IP адресам, а по уникальной комбинации netflow-полей.

Например, если "fields": ["src host", "proto", "packets"], то строки должны быть в таком формате:

# порог по ICMP
1.2.3.4,1,100000
# UDP
1.2.3.4,17,200000
# TCP
1.2.3.4,6,300000
# Для другого адреса выставляем порог только по TCP
1.2.3.5,6,200000

Если адреса или комбинации полей нет в этом файле, то порогом считается значение default.

В файле допускаются пустые строки и строки с комментариями (начинаются с #)

IP-списки

Если вам нужно использовать в фильтрах много IP-сетей, имеет смысл хранить их в отдельных файлах.

Формат файла простой: сеть на строку, также допускаются пустые строки и строки с комментариями (начинаются с #)

В одном файле можно записывать и IPv4, и IPv6 сети, чтобы потом использовать в разных фильтрах.

"filter": "dst net my-net" — будут использоваться IPv4 сети из списка

"filter": "dst net6 my-net" — IPv6