Отчеты

С помощью конфигурационного файла report.conf можно настроить отчеты, которые создают SQL-запросы для просмотра таблиц в базе данных AxelNAC. Эти отчеты будут отображаться в разделе Отчеты веб-интерфейса AxelNAC.

AxelNAC поставляется с несколькими отчетами, оптимизированными для наиболее распространенных производственных случаев использования в файле reports.conf.defaults. Этот файл не должен модифицироваться, но его можно использовать для создания рабочих примеров.

к сведению

Неправильно сформированные отчеты могут потреблять значительные ресурсы сервера. Все запросы должны быть оптимизированы, чтобы избежать сбоев в работе службы. Использование type=sql (режим сценария/пакета) позволяет повысить контроль над запросами и транзакциями.

совет

Репликация Master/Slave может быть использована для разгрузки выполнения запросов в базу данных, которая доступна только для чтения и не является активным членом кластера. Это гарантирует, что отчетность не ухудшит работу производственной среды и предоставит дополнительные ресурсы для генерации отчетов.

Атрибуты конфигурации

Для конфигурирования отчета необходимо отредактировать файл /usr/local/pf/conf/report.conf и добавить в него раздел, определяющий отчет. Затем запустить команду /usr/local/pf/bin/pfcmd configreload hard.

В веб-интерфейсе структурированное меню строится путем разбиения и разделения всех идентификаторов разделов двойным двоеточием «::». Идентификаторы без этого разделителя отображаются на верхнем уровне. Допускается использование не более двух наборов двойных двоеточий для максимальной глубины меню в три уровня.

Все идентификаторы должны быть уникальными, и любой идентификатор, частично повторно используемый другим одноуровневым элементом, сделает его недоступным. (Например: [A::B]) потеряет свое место в качестве отчета и станет родительской категорией для [A::B::*], если она также определена. Либо переименуйте первую категорию, включив в нее 3-ю часть, либо переименуйте вторую, используя другую 1-ю или 2-ю часть:

[ВЕРХНЯЯ КАТЕГОРИЯ::ПОДКАТЕГОРИЯ::ОТЧЕТ]

Для определения отчета доступны следующие атрибуты (звездочкой * отмечены обязательные атрибуты):

• type*: Тип отчета. Используйте type=abstract для использования SQL Abstract и type=sql для использования режима MySQL script/batch. Каждый из этих типов имеет свои дополнительные атрибуты, которые более подробно описаны в следующих разделах;
• description*: Описание, содержащее более подробную информацию об отчете. Используется в качестве заголовка для всех графиков;
• charts: Список графиков, разделенный запятыми. Каждый график отображается в отдельной вкладке над данными таблицы. Количество графиков, которые можно задать, не ограничено. Более подробно графики описаны ниже;
• columns*: Список столбцов или псевдонимов, которые отображаются в таблице из SQL-запроса (например: node.mac, Node MAC), разделенный запятыми. Столбцы таблицы отображаются в соответствующем порядке. Их можно переименовать и присвоить им более удобные имена. При этом следует иметь в виду, что эти псевдонимы должны использоваться во всех остальных атрибутах;
• date_limit: Интервал AxelNAC, определяющий максимальный диапазон дат между start_date и end_date. Пользователь, который указывает диапазон дат для формирования отчета, не сможет диапазон, превышающий этот предел. Это делается для того, чтобы запрос MySQL не потреблял слишком много ресурсов при больших наборах данных. Продолжительность определяется как date_limit=[unit][interval] (например, date_limit=1D), где unit — целое положительное число, а interval — один из следующих символов:
  • s: секунда(ы);
  • m: минута(ы);
  • h: час(ы);
  • D: день (дни);
  • W: неделя(и);
  • M: месяц(ы);
  • Y: год(ы).
• formatting: Разделенный запятыми список форматоров для столбцов или псевдонимов. Каждый столбец определяется после двоеточия и внутренней функции AxelNAC, которая используется для форматирования значения столбца и каждой строки (например, formatting=vendor:oui_to_vendor). Это используется для форматирования столбцов результатов запроса с помощью функции доступа к внутренней памяти AxelNAC. Поддерживаемые форматоры:
  • oui_to_vendor: форматирование MAC OUI для вендора.
• has_date_range: [enabled|disabled]. Отображает диапазон дат и обеспечивает привязку к датам start_date и end_date. За ограничение максимального диапазона дат отвечает параметр date_limit;
• has_limit: [enabled|disabled]. Отображает выбор максимального диапазона и обеспечивает привязку лимита (limit);
• node_fields: Список полей (столбцов или псевдонимов), которые будут доступны по щелчку мыши в таблице отчета и связаны с конкретным узлом — только если пользователь отчета имеет роль администратора Node — View. Все поля должны быть действительными идентификаторами узлов AxelNAC (mac);
• person_fields: Список полей (столбцов или псевдонимов), которые будут доступны по щелчку мыши в таблице отчета и связаны с конкретным пользователем — только если пользователь отчета имеет роль администратора User — View. Все поля должны быть действительным идентификатором пользователя AxelNAC (pid)`;
• role_fields: Список полей (столбцов или псевдонимов), которые будут доступны по щелчку мыши из таблицы отчета и связаны с конкретной ролью. Все поля должны быть действительным идентификатором роли AxelNAC (category_id).

к сведению

Атрибуты конфигурации могут опционально использовать ссылку на имя столбца (columnName) в простых запросах для одной таблицы (например: attribute=columnA,columnB). Если нужны объединения с «2+» таблицами, атрибуты должны использовать ссылку tableName.columnName (например, attribute=tableA.columnA,tableB.columnB). При использовании ссылки на таблицу можно использовать псевдонимы (например, attribute=tableA.Alias A,tableB.Alias B).

SQL Abstract

При type=abstract AxelNAC использует Perl SQL::Abstract::More для автоматического построения SQL-запроса. При использовании type=abstract доступны следующие атрибуты (звездочкой * отмечены обязательные атрибуты):

• base_conditions: Список условий, применяемых к SQL-запросу, разделенный запятыми. Условия должны соответствовать следующему формату: field:operator:value (например: auth_log.source:=:sms, auth_log.status:!=:completed);
• base_conditions_operator: [all|any]. Логический SQL-оператор (AND|OR соответственно), используемый с base_conditions;
• base_table*: Базовая SQL-таблица, используемая в SQL-запросе;
• date_field*: Поле таблицы (столбец), используемое для фильтрации по диапазону дат. Столбец также будет использоваться для сортировки по умолчанию, если явно не определен order_fields;
• group_field: Поле (столбец), по значению которого следует группировать результаты запроса. Если это поле пустое или опущено, группировка не проводится;
• Joins: Таблица(ы), столбцы и псевдонимы, используемые для объединения с base_table. См. пример ниже и документацию. Этот атрибут поддерживает многострочные блоки (heredoc), см. ниже;
• order_fields: Список полей (столбцов), используемых для упорядочивания SQL запроса, разделенный запятыми. Поле должно иметь префикс -, если сортировка должна проводиться по убыванию поля (например, node.regdate,locationlog.start_time, +iplog.start_time);
• searches: Список полей (столбцов), разделенный запятыми, по которым проводится поиск и которые предоставляются пользователю отчета. Это позволяет пользователю включать дополнительные критерии для запроса. Каждый элемент определяется как type:Friendly Name:tableName.columnName (например, searches=string:Owner:person.pid,string:Node:node.mac). В настоящее время поддерживается только тип string:
  • type: Определяет тип поиска. в настоящее время поддерживается только string;
  • Display Name: Указанное пользователем название поля;
  • field: SQL-имя поля для поиска

к сведению

Заключайте имена таблиц и столбцов в кавычки "`", чтобы избежать проблем с присвоением имен существующим и будущим зарезервированным словам MySQL.

Примеры

Вид таблицы auth_log:

[auth_log]
description=Authentication report
# The table to search from
base_table=auth_log
# The columns to select
columns=auth_log.*
# The date field that should be used for date ranges
date_field=attempted_at
# The mac field is a node in the database
node_fields=mac
# Allow searching on the PID displayed as Username
searches=string:Username:auth_log.pid

В этом простом примере вы можете выбрать все содержимое таблицы auth_log и использовать диапазон дат в поле attempted_at, а также проводить поиск по полю pid при просмотре отчета.

Вид открытых событий безопасности:

[open_security_events]
description=Open security events
# The table to search from
base_table=security_event
# The columns to select
columns=security_event.security_event_id as "Security event ID",
security_event.mac as "MAC Address", class.description as "Security event
description", node.computername as "Hostname", node.pid as "Username",
node.notes as "Notes", locationlog.switch_ip as "Last switch IP",
security_event.start_date as "Opened on"
# Left join node, locationlog on the MAC address and class on the security
event ID
joins=<<EOT
=>{security_event.mac=node.mac} node|node
=>{security_event.mac=locationlog.mac} locationlog|locationlog
=>{security_event.security_event_id=class.security_event_id} class|class
EOT
date_field=start_date
# filter on open locationlog entries or null locationlog entries via the
end_date fielв
base_conditions_operator=any base_conditions=locationlog.end_time:=:0000-00-00,locationlog.end_time:IS: # The MAC Address field represents a node node_fields=MAC Address # The Username field represents a user person_fields=Username

В приведенном примере видно, что таблица security_event остается присоединенной к таблицам class, node и locationlog. Использование этого подхода обеспечит слежение за перечислением всех событий безопасности даже на удаленных узлах. Затем добавляются базовые условия для фильтрации устаревших записей в журнале locationlog, а также для включения устройств без записей этого журнала. Удаление этих условий приведет к появлению дубликатов записей, поскольку в отчете будут отражены все архивные записи журнала.

SQL

При type=sql AxelNAC использует режим MySQL script/batch для построения SQL-запроса вручную, включая выполнение нескольких операторов. Это обеспечивает полный контроль над запросами, а также возможность управления SQL-сессией и SQL транзакцией. Такой режим предпочтителен в тех случаях, когда требуется оптимизация SQL для выполнения сложных запросов, или для тех, кому удобнее работать с «сырым» (неабстрактным) SQL.

sql=SELECT * FROM sponsors;

Многострочный блок (heredoc) необходим при выполнении нескольких операторов. Каждое утверждение должно завершаться точкой с запятой ";".

внимание

Выполнение SQL завершается при первой ошибке и возвращает результирующий набор последнего успешного оператора.

При использовании type=sql доступны следующие атрибуты:

• Bindings: Список упорядоченных привязок, передаваемых SQL-скрипту через запятую (например, bindings=tenant_id,start_date,end_date,cursor,limit);
• cursor_type: [none|field_multi_field|offset] Добавляет привязку кýрсора к SQL-скрипту, реализующему пагинацию результатов. Кýрсор автоматически обрабатывается в интерфейсе администрирования, но его использование в SQL требует особого внимания. Если значение опущено, то по умолчанию используется значение none. Более подробная информация о кýрсорах приведена ниже. Существует три типа курсоров:
  • cursor_type=field: Использование для кýрсора одного поля (столбец или псевдоним);
  • cursor_type=multi_field: Использование для кýрсора нескольких полей (столбцов или псевдонимов);
  • cursor_type=offset: Использование для кýрсора целочисленного смещения;
  • cursor_type=none: Кýрсор не используется.
• cursor_default: Кýрсор по умолчанию, используемый для условного запроса результатов для первой страницы. На последующих страницах он заменяется результатами из N+1 строки предыдущей страницы. То есть кýрсор для страницы 2 (с default_limit=25) будет содержать значение из столбца 26-й строки предыдущей страницы;
• cursor_field: Список полей (колонок), используемых для пагинации, разделенный запятыми;
• default_limit: Ограничение по умолчанию, передаваемое в привязку SQL-скрипта. Если has_limit=enabled, пользователь может отменить значение по умолчанию с помощью выбора вручную;
• Sql: Либо один запрос к MySQL, либо многострочный блок операторов в рамках heredoc.

Bindings

Атрибут bindings определяет упорядоченный список столбцов (или псевдонимов) через запятую, которые становятся доступными SQL-скрипту. Количество используемых привязок не ограничено, и одна привязка может повторяться несколько раз. Доступны следующие варианты атрибута:

• tenant_id: Идентификатор клиента с заданной областью сессии отчетов;
• start_date, **end_date:**Время начала и конца отсчета. Имеет формат "YYYY-MM-DD HH:mm:ss". Для указания местного формата дат и времени используйте функции даты MySQL;
• Cursor: На первой странице — это значение cursor_default. На последующих страницах это значение берется из столбца cursor_field последней строки результата предыдущей страницы. При использовании типа кýрсора cursor_type=multi_field сам кýрсор разбивается на привязки cursor.0, cursor.1 и т. д;
• Limit: Используется default_limit, если он не переопределен пользователем.

Bindings используются в SQL с помощью оператора "?" в том же порядке, в котором они определены.

[single binding]
type=sql
bindings=limit
sql=SELECT * FROM table LIMIT ?;
default_limit=100
has_limit=enabled
Если в sql привязка нужна более одного раза, ее можно определить несколько раз или один раз и использовать для переменной SET MySQL.
[many bindings]
type=sql
bindings=start_date,end_date,tenant_id,start_date,end_date,limit
sql= << EOT
  SELECT
  *
  FROM tableA
  JOIN tableB ON tableA.id = tableB.id
  AND date BETWEEN ? AND ?
  WHERE tenant_id = ?
  AND date BETWEEN ? AND ?
  LIMIT ?;
EOT
default_limit=100
has_date_range=enabled
has_limit=enabled

Разбивка по страницам

Для разбиения отчетов на страницы используются атрибуты cursor_type, cursor_default, cursor_field, bindings и sql. В разбивке могут быть задействованы от одного до нескольких столбцов. Для правильного использования кýрсора необходимо обратить особое внимание на порядок следования конечного набора результатов. Слишком малое количество страниц или бесконечные циклы по последующим страницам являются признаками несоответствия порядка кýрсора и/или результатов запроса.

К binding limit всегда добавляется +1, так как AxelNAC всегда использует дополнительную строку для определения кýрсора для следующей страницы. В связи с этим все условные операторы должны быть инклюзивными (например: неэффективные операторы — <, >; эффективные операторы — <=, >=). Если значение столбца не уникально, то во избежание бесконечных циклов вместо этого следует использовать cursor_type=multi_field.

Примеры одноколоночного кýрсора:

[все узлы в порядке возрастания]
type=sql
sql= <<EOT
SELECT mac FROM node WHERE mac >= ? ORDER BY mac LIMIT ?;
EOT bindings=cursor,limit
cursor_type=field
cursor_field=mac
default_cursor=00:00:00:00:00:00:00

[все узлы в порядке убывания]
type=sql
sql= <<EOT
SELECT mac FROM node WHERE mac <= ? ORDER BY mac DESC LIMIT ?; EOT
columns=mac
bindings=cursor,limit
cursor_type=field
cursor_field=mac
default_cursor=ff:ff:ff:ff:ff:ff:ff

Пример многоколоночного кýрсора:

[все журналы ip4log]
type=sql
sql= <<EOT
SELECT
    ip4log.ip,
    ip4log.start_time,
    node.mac
  FROM ip4log
  INNER JOIN node
    ON ip4log.mac = node.mac WHERE ip4log.start_time >= ?
    AND node.mac >= ?
  ORDER BY ip4log.start_time, node.mac
  LIMIT ?;
EOT
columns=mac
bindings=cursor.0,cursor.1,limit
cursor_type=multi_field cursor_field=start_time,mac default_cursor=0000-00-00 00:00:00:00,00:00:00:00:00:00:00

Графики

Графики задаются в виде списка, разделенного запятыми, с помощью атрибута chart.

Для разделения имени графика может использоваться необязательный символ "@". Для разделения типа графика и полей используется вертикальная полоса "|". Внутри полей двоеточие ":" используется для разделения каждого из полей (если необходимы несколько полей).

Общий синтаксис выглядит следующим образом:

charts=[pie,bar,parallel,scatter] [@ Имя графика] | field1 [:fieldN:...]

Существует четыре типа графиков:

• Pie: Круговая диаграмма с двумя измерениями. Должна содержать два поля (charts=pie|field1:field2):
  • field0: метка размеров;
  • field1: значение размерности.
• Bar: Гистограмма с двумя измерениями. Должна содержать два поля (charts=bar|field1:field2):
  • field0: метка размеров;
  • field1: значение размерности.
• Parallel: Параллельная диаграмма категории с 2+ измерениями. Должна содержать 3+ поля (charts=parallel|field1:field2:field3[...:fieldN]):
  • fieldN: метка N-мерности из 2+ полей. Для каждого поля создается категория и сохраняется порядок. Палитра применяется к последнему полю (крайнему справа);
  • fieldLast: последнее поле всегда содержит значение размерности.
• Scatter: Линейный график на основе даты/времени с 1+ измерениями. Столбец даты/времени всегда задается в первом поле, и запрос должен возвращать его в формате "YYYY-MM-DD HH:mm:ss":
  • если задано только одно поле (charts=scatter|field1), то для каждой строки подразумевается значение 1;
  • если заданы два поля (charts=scatter|field1:field2), то в качестве значения размерности используется второе поле. Результаты запроса автоматически агрегируются для получения размерностей по нескольким срокам (год/месяц/неделя/день/час/минута);
  • при задании 3+ полей (charts=scatter|field1:field2:field3[...:fieldN]) автоматическое агрегирование отключается, а для каждого поля используется своя размерность.

к сведению

Для обеспечения визуальной преемственности во всех графиках используется одна и та же цветовая палитра.

Heredoc

Атрибуты joins и sql поддерживают многострочные блочные операторы. При этом сохраняются все символы пробелов. Все многострочные операторы — это чистый SQL, поэтому в качестве примечания можно использовать префикс --.

attribute= <<EOT
  -- multi-line
  -- block
  -- statement
EOT

Устранение неисправностей

Если запрос API возвращает ошибку или пустой ответ, обратитесь к журналу axlenac.log, чтобы получить полное сообщение об ошибке MySQL. Сценарии SQL являются транзакционными. После выполнения сценария все созданные переменные, хранимые процедуры или временные таблицы уничтожаются. Все полученные блокировки снимаются. Чтобы изменения вступили в силу, достаточно выполнить следующую команду:

/usr/local/pf/bin/pfcmd configreload

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