Конфигурации фильтров являются общими для всех экземпляров плагинов. Набор используемых фильтров и порядок их вызова определяется списком plugins → base → < → plugin_instance_name>call_stack конфигурации конкретного экземпляра плагина.
Если ключа, значение которого формирует фильтр, нет, он будет добавлен. Если ключ уже существует, его значение будет заменено новым.
Спецификации фильтров
В конфигурации любого настроенного фильтра, в секции specs, могут быть описаны его спецификации — примеры входных данных и результатов их обработки фильтром. Агент HARD при запуске тестирует все активные, то есть участвующие хотя бы в одном стэке обработки запросов, фильтры, для которых задана спецификация. На вход фильтра подаются данные, указанные в секции input спецификации, а результат обработки сравнивается с заданным в секции expected. Если обнаруживается несоответствие, генерируется ошибка с указанием наименования проблемной спецификации (ключ name) и отличий вывода фильтра от ожидаемого значения. Запуск агента при возникновении ошибки прекращается.
plugins:
filters:
set_value_before:
fix_duplicated_acct-session-id_attribute:
condition: ' $context.has_tag?("accounting")
and $request.RAD_REQUEST.try("Acct-Session-Id", "").to_s() != $request.RAD_REQUEST.try("Acct-Session-Id", "")'
destination: $request.RAD_REQUEST.Acct-Session-Id
value_expression: $request.RAD_REQUEST.Acct-Session-Id[0]
specs:
- name: fix_duplicated_acct-session-id_attribute
input:
tags: [accounting]
request:
RAD_REQUEST:
Acct-Session-Id:
- '5746ECB0-00000027'
- '5746ECB0-00000027'
expected:
tags: [accounting]
request:
RAD_REQUEST:
Acct-Session-Id: '5746ECB0-00000027'
- name: pass_through_correct_acct-session-id_attribute
input:
tags: [accounting]
request:
RAD_REQUEST:
Acct-Session-Id: '5746ECB0-00000027'
expected:
tags: [accounting]
request:
RAD_REQUEST:
Acct-Session-Id: '5746ECB0-00000027'
Если в таком фильтре, в ключе condition, заменить оператор != на ==, то фильтр не изменит входные данные — результат работы фильтра не совпадёт с ожидаемым и возникнет ошибка:
25.11.2016 18:01:17.291 13384/Worker#1 MainThread ERROR Failed filter spec "fix_duplicate_acct-session-id_attribute" with diff
--- a
+++ b
{
'RAD_REQUEST': {
-'Acct-Session-Id': ['5746ECB0-00000027', '5746ECB0-00000027'],
+'Acct-Session-Id': '5746ECB0-00000027',
},
}
Универсальные фильтры
case_before, case_after
Установка значений в зависимости от выполнения одного или нескольких условий.
| Параметр | Описание |
|---|---|
tags | Наименование тега, которым должен быть промаркирован запрос для выполнения фильтра. В данном параметре может быть указан список наименований тегов — в таком случае фильтр будет выполнен только если запрос промаркирован всеми указанными тегами. Параметр condition игнорируется, если задан tags. |
condition | Условие применения фильтра. Фильтр выполняется, если вычисляемое выражение из данного ключа вернуло истину, либо не задано (и не используется tags). |
case | Список пар ключей Последним элементом списка может быть |
check_attr_before
Выполнение некоторого действия с запросом.
| Параметр | Описание |
|---|---|
tags | Наименование тега, которым должен быть промаркирован запрос для выполнения фильтра. В данном параметре может быть указан список наименований тегов — в таком случае фильтр будет выполнен только если запрос промаркирован всеми указанными тегами. Параметр condition игнорируется, если задан tags. |
condition | Условие применения фильтра. Фильтр выполняется, если вычисляемое выражение из данного ключа вернуло истину, либо не задано (и не используется tags). |
action → type | Тип действия. Единственный поддерживаемый на данный момент — досрочное прекращение обработки запроса halt_processing. |
action → tag | Тег, которым запрос необходимо промаркировать. Может быть указано несколько тегов в виде списка — запрос будет промаркирован каждым из них. |
action → arguments | Параметры выполняемого действия. В случае halt_processing — шаблон ответа на запрос, который будет отправлен. Структура шаблона аналогична таковым в ключах plugins → base → <plugin_instance_name> → actions → <action_name> → reply конфигурации плагина. |
delete_attrs_before, delete_attrs_after
Удаление атрибутов по наименованию или по шаблону значения.
| Параметр | Описание |
|---|---|
tags | Наименование тега, которым должен быть промаркирован запрос для выполнения фильтра. В данном параметре может быть указан список наименований тегов — в таком случае фильтр будет выполнен только если запрос промаркирован всеми указанными тегами. Параметр condition игнорируется, если задан tags. |
condition | Условие применения фильтра. Фильтр выполняется, если вычисляемое выражение из данного ключа вернуло истину, либо не задано (и не используется tags). |
| Список полных наименований атрибутов, которые необходимо удалить. |
attribute_patterns | Пары <dict>: <pattern>. Из словаря <dict> удаляются все атрибуты, наименование которых удовлетворяет регулярному выражению <pattern>. |
divide_before, divide_after
Массовое деление значений атрибутов.
| Параметр | Описание |
|---|---|
tags | Наименование тега, которым должен быть промаркирован запрос для выполнения фильтра. В данном параметре может быть указан список наименований тегов — в таком случае фильтр будет выполнен только если запрос промаркирован всеми указанными тегами. Параметр condition игнорируется, если задан tags. |
condition | Условие применения фильтра. Фильтр выполняется, если вычисляемое выражение из данного ключа вернуло истину, либо не задано (и не используется tags). |
factors | Пары <attr_name>: <divider>, где <attr_name> — полное наименование атрибута, значение которого должно быть разделено на <divider>. Делимое и частное дополнительно приводятся к целому числу отбрасыванием дробной части. Если указанный в <attr_name> атрибут отсутствует, результатом операции над ним станет пустое значение. |
format_before, format_after
Формирование строкового значения на основе шаблона.
| Параметр | Описание |
|---|---|
tags | Наименование тега, которым должен быть промаркирован запрос для выполнения фильтра. В данном параметре может быть указан список наименований тегов — в таком случае фильтр будет выполнен только если запрос промаркирован всеми указанными тегами. Параметр condition игнорируется, если задан tags. |
condition | Условие применения фильтра. Фильтр выполняется, если вычисляемое выражение из данного ключа вернуло истину, либо не задано (и не используется tags). |
destination | Полное наименование атрибута, в который необходимо записать результат. |
values | Пары ключ-значение, где ключ — наименование подстановки, а значение — полное наименование соответствующего ей атрибута. |
template | Строка-шаблон, содержащая подстановки в формате #{<subst_expression>}, где < — выражение, вычисляемое с использованием подстановок-переменных из values. |
delete_values | Флаг (true или false), определяющий, нужно ли по окончании удалять атрибуты, перечисленные в values. По умолчанию атрибуты не удаляются. |
map_before, map_after
Преобразование списка значений с предварительной фильтрацией его элементов.
| Параметр | Описание |
|---|---|
tags | Наименование тега, которым должен быть промаркирован запрос для выполнения фильтра. В данном параметре может быть указан список наименований тегов — в таком случае фильтр будет выполнен только если запрос промаркирован всеми указанными тегами. Параметр condition игнорируется, если задан tags. |
condition | Условие применения фильтра. Фильтр выполняется, если вычисляемое выражение из данного ключа вернуло истину, либо не задано (и не используется tags). |
destination | Полное наименование атрибута, в который необходимо записать результат. |
value_expression | Вычисляемое выражение, возвращающее список значений, который необходимо преобразовать. Если параметр не задан, используется параметр value. |
| Список значений, который необходимо преобразовать. Используется при отсутствии параметра value_expression. |
filter_expression | Вычисляемое для каждого элемента входного списка выражение, определяющее, нужно ли данный элемент преобразовывать и включать в результат. В выражении может использоваться переменная $value, которая соответствует проверяемому элементу списка. Если параметр не задан, преобразование выполняется над всеми элементами входного списка. |
transform_expression | Вычисляемое для каждого прошедшего filter_expression элемента входного списка выражение, выполняющее необходимое преобразование. Переменная $value, в данном выражении представляет элемент входного списка. Если параметр не задан, выполняется тождественное преобразование. |
match_before, match_after
Разбор входного значения-строки по шаблону.
| Параметр | Описание |
|---|---|
tags | Наименование тега, которым должен быть промаркирован запрос для выполнения фильтра. В данном параметре может быть указан список наименований тегов — в таком случае фильтр будет выполнен только если запрос промаркирован всеми указанными тегами. Параметр condition игнорируется, если задан tags. |
condition | Условие применения фильтра. Фильтр выполняется, если вычисляемое выражение из данного ключа вернуло истину, либо не задано (и не используется tags). |
destination | Полное наименование атрибута-словаря, в который необходимо записать результат. |
value_expression | Вычисляемое выражение, возвращающее строку, из которой необходимо извлечь данные. |
matcher | Шаблон разбора — регулярное выражение с именованными группами. Результат разбора — записанные в destination пары <key>: <value>, где <key> — наименование группы, а <value> — соответствующая данной группе часть входной строки. |
transformations | Пары <key>: <transformation>, определяющие дополнительные преобразования извлечённых из входной строки значений. Здесь <key> — наименование группы из параметра matcher, а <transformation> — преобразование в виде вычисляемого относительно переменной $value выражения. Переменная $value в этих выражениях соответствует исходному значению, полученному при разборе входной строки. Если параметр не задан, преобразования не выполняются. |
multiply_before, multiply_after
Массовое умножение значений атрибутов.
| Параметр | Описание |
|---|---|
tags | Наименование тега, которым должен быть промаркирован запрос для выполнения фильтра. В данном параметре может быть указан список наименований тегов — в таком случае фильтр будет выполнен только если запрос промаркирован всеми указанными тегами. Параметр condition игнорируется, если задан tags. |
condition | Условие применения фильтра. Фильтр выполняется, если вычисляемое выражение из данного ключа вернуло истину, либо не задано (и не используется tags). |
factors | Пары <attr_name>: <multiplier>, где <attr_name> — полное наименование атрибута, значение которого должно быть умножено на <. Множимое и произведение дополнительно приводятся к целому числу отбрасыванием дробной части. Если указанный в <attr_name> атрибут отсутствует, результатом операции над ним станет пустое значение. |
reduce_before, reduce_after
Свёртка списка значений с предварительной фильтрацией его элементов.
| Параметр | Описание |
|---|---|
tags | Наименование тега, которым должен быть промаркирован запрос для выполнения фильтра. В данном параметре может быть указан список наименований тегов — в таком случае фильтр будет выполнен только если запрос промаркирован всеми указанными тегами. Параметр condition игнорируется, если задан tags. |
condition | Условие применения фильтра. Фильтр выполняется, если вычисляемое выражение из данного ключа вернуло истину, либо не задано (и не используется tags). |
destination | Полное наименование атрибута, в который необходимо записать результат. |
value_expression | Вычисляемое выражение, возвращающее список значений, который необходимо свернуть. |
filter_expression | Вычисляемое для каждого элемента входного списка выражение, определяющее, нужно ли данный элемент включать в свёртку. В выражении может использоваться переменная $value, которая соответствует проверяемому элементу списка. Если параметр не задан, свёртка выполняется по всем элементам входного списка. |
initial_expression | Вычисляемое выражение, определяющее начальное значение свёртки. Если параметр не задан, он полагается равным пустому значению. |
reduce_expression | Вычисляемое для каждого прошедшего filter_expression элемента входного списка выражение, определяющее комбинирующую функцию. Переменная $value, в данном выражении представляет элемент входного списка, а переменная $accumulator — текущее значение свёртки. |
set_tag_before, set_tag_after
Маркировка запроса тегом (добавление тега в список $context.tags).
| Параметр | Описание |
|---|---|
tags | Наименование тега, которым должен быть промаркирован запрос для выполнения фильтра. В данном параметре может быть указан список наименований тегов — в таком случае фильтр будет выполнен только если запрос промаркирован всеми указанными тегами. Параметр condition игнорируется, если задан tags. |
condition | Условие применения фильтра. Фильтр выполняется, если вычисляемое выражение из данного ключа вернуло истину, либо не задано (и не используется tags). |
value | Наименование тега, которым необходимо промаркировать запрос. |
value_expression | Вычисляемое выражение, возвращающее строку — наименование тега, которым должен быть промаркирован запрос. Используется, если не задан параметр value. |
set_value_before, set_value_after
Установка значения одного атрибута.
| Параметр | Описание |
|---|---|
tags | Наименование тега, которым должен быть промаркирован запрос для выполнения фильтра. В данном параметре может быть указан список наименований тегов — в таком случае фильтр будет выполнен только если запрос промаркирован всеми указанными тегами. Параметр condition игнорируется, если задан tags. |
condition | Условие применения фильтра. Фильтр выполняется, если вычисляемое выражение из данного ключа вернуло истину, либо не задано (и не используется tags). |
destination | Полное наименование атрибута, в который необходимо записать результат. |
value | Значение, которое необходимо записать в destination. |
value_expression | Выражение, результат вычисления которого должен быть записан в destination. Используется, если не задан параметр value. |
split_before, split_after
Разбор строки по разделителю.
| Параметр | Описание |
|---|---|
tags | Наименование тега, которым должен быть промаркирован запрос для выполнения фильтра. В данном параметре может быть указан список наименований тегов — в таком случае фильтр будет выполнен только если запрос промаркирован всеми указанными тегами. Параметр condition игнорируется, если задан tags. |
condition | Условие применения фильтра. Фильтр выполняется, если вычисляемое выражение из данного ключа вернуло истину, либо не задано (и не используется tags). |
value_expression | Полное наименование атрибута, строковое значение которого необходимо разобрать. |
delimiter | Строка-разделитель. |
destination | Список полных наименований атрибутов, в которые необходимо записать полученные в результате разбора значения. Первое значение сохраняется в первый атрибут, второе — во второй и т. д. Если отдельные значения сохранять не нужно, для них следует указать пустую строку вместо наименования атрибута. Вместо списка может быть указана одна строка — полное наименование атрибута, в который будут списком сохранены все полученные при разборе значения. |
delete_values | Флаг (true или false), определяющий, нужно ли по окончании удалить атрибут, указанный в value_expression. По умолчанию атрибут не удаляется. |
Специальные фильтры
encode_dhcp_options_after
Преобразование DHCP-опций в двоичный формат в соответствии с RFC 2132. Аналог одноименного фильтра второй версии агента.
| Параметр | Описание |
|---|---|
tags | Наименование тега, которым должен быть промаркирован запрос для выполнения фильтра. В данном параметре может быть указан список наименований тегов — в таком случае фильтр будет выполнен только если запрос промаркирован всеми указанными тегами. Параметр condition игнорируется, если задан tags. |
condition | Условие применения фильтра. Фильтр выполняется, если вычисляемое выражение из данного ключа вернуло истину, либо не задано (и не используется tags). |
destination | Полное наименование атрибута, в который необходимо записать результат. |
value | Список вычисляемых выражений, каждое из которых соответствует отдельной DHCP-опции. Выражение должно возвращать строку в формате <option_name>:<option_value>, где <option_name> — наименование DHCP-опции, а <option_value> — её значение. Список разрешенных опций можно получить в описании Python-библиотеки pydhcplib. |
render_reply_after
Выбор шаблона ответа и формирование по нему ответа на запрос. При наличии такого фильтра в стэке обработки запроса, ядро плагина не формирует ответ, а только подбирает профили оборудования. Это позволяет провести дополнительные вычисления и проверки с помощью after-фильтров и уже на основании их результатов формировать ответ.
| Параметр | Описание |
|---|---|
tags | Наименование тега, которым должен быть промаркирован запрос для выполнения фильтра. В данном параметре может быть указан список наименований тегов — в таком случае фильтр будет выполнен только если запрос промаркирован всеми указанными тегами. Параметр condition игнорируется, если задан tags. |
condition | Условие применения фильтра. Фильтр выполняется, если вычисляемое выражение из данного ключа вернуло истину, либо не задано (и не используется tags). |
reject_on_error
Отправка Access-Reject при возникновении ошибки во время обработки запроса. Данный фильтр не имеет никаких параметров — он должен присутствовать только в стэке обработки запроса конфигурации ядра плагина, причём в вершине этого стэка (первым в списке).