Управление конфигурациями Logstash

Описание

Роль управления конфигурациями Logstash не включает перезагрузку сервиса Logstash, не изменяет параметры в файле jvm.options, в том числе не редактирует размер heap.

Роль конфигурирует следующие файлы:

• logstash.yml
• pipelines.yml
• конфигурационные файлы пайплайнов

При изменении в конфигурационных файлах создаются резервные копии. Также осуществляется поиск резервных копий и производится удаление бэкапов файлов старше 1 дня.

При отключении пайплайна на хосте конфигурационный файл переименовывается с расширением .bkp и не удаляется.

Параметры роли

Значения по умолчанию указаны относительно рекомендаций Smart Monitor.

var_logstash_pipelines_list

Объект (YAML) с описанием параметров пайплайнов Logstash. Обычно используется для группы хостов (влияет на приоритеты и последовательность объединения параметров). Поддерживает объединение с параметрами, начинающимися на var_logstash_pipelines_list_, например: var_logstash_pipelines_list_syslog var_logstash_pipelines_list_win_log

host_var_logstash_pipelines_list

Объект (YAML) с описанием параметров пайплайнов Logstash. Обычно используется для описания параметров хоста (влияет на приоритеты и последовательность объединения параметров). Поддерживает объединение с параметрами, начинающимися на host_var_logstash_pipelines_list_, например: host_var_logstash_pipelines_list_syslog host_var_logstash_pipelines_list_win_log

var_logstash_files

Объект (YAML) с основными параметрами Logstash

Переменная	Значение по умолчанию	Описание
var_logstash_files.path_conf	директория расположения конфигурации Logstash, по умолчанию	/app/logstash/config
var_logstash_files.path_log	директория нахождения логов Logstash, по умолчанию	/app/logs/logstash/logstash-plain.log
var_logstash_files.dir_subcfg	названия директории расположения файлов конфигураций пайплайнов, обычно	conf.d
var_logstash_files.owner	имя владельца файлов, по умолчанию	"logstash"
var_logstash_files.group	имя группы владельцев файлов, по умолчанию	"logstash"
var_logstash_files.mode	привилегии на создаваемые файлы, по умолчанию	"0644"
var_logstash_files.folder_mode	привилегии на создаваемые директории, по умолчанию	"0755"

Параметры файла logstash.yml

Далее следуют параметры (объекты YAML), относящиеся к глобальным параметрам Logstash и прописываются в файле logstash.yml. Разделено на 5 объектов только для группировки части параметров по "общим признакам" и соответствующим комментарием в файле logstash.yml.

var_logstash_node_settings

Объект (YAML) с параметрами, относящиеся к текущему узлу, обычно включает следующие параметры:

Переменная	Значение по умолчанию	Описание
node.name	имя узла, значение по умолчанию	smosed-logstash
config.reload.automatic	перезагружать ли автоматически конфигурацию Logstash pipeline	false
config.reload.interval	время проверки изменения конфигураций для автоматического применения конфигурации	3s

var_logstash_path_settings

Объект (YAML) с параметрами, относящиеся к текущему узлу и указанию директорий, обычно включает следующие параметры:

Переменная	Значение по умолчанию	Описание
path.data	директория расположения данных	/app/data/logstash
path.logs	директория расположения логов	/app/logs/logstash

var_logstash_pipeline_settings

Объект (YAML) с параметрами, относящиеся к глобальным параметрам pipeline, обычно включает следующие параметры:

Переменная	Значение по умолчанию	Описание
pipeline.ordered	управление порядком событий пайплайна	auto
pipeline.separate_logs	сохранение логов пайплайнов в отдельные файлы	true

var_logstash_queue_settings

Объект (YAML) с параметрами, относящиеся к параметрам работы с очередями, обычно включает следующие параметры:

Переменная	Значение по умолчанию	Описание
queue.type	тип буфера для хранения буфера событий	memory
queue.page_capacity	размер страницы при файловом типе буфера событий	64mb
queue.max_events	количество необработанных событий в очереди для включения буфера файлового типа	0
queue.max_bytes	максимальное значение буфера файлового типа в байтах	1024mb
queue.checkpoint.acks	максимальное количество событий с подтверждением перед форсированием при файловом типе очереди	1024
queue.checkpoint.writes	максимальное количество записанных событий перед форсированием при файловом типе очереди	1024
queue.checkpoint.interval	интервал в миллисекундах принудительной установки контрольной точки при файловом типе очереди	1000

var_logstash_dead_letter_queue_settings

Объект (YAML) с параметрами, относящиеся к параметрам работы с очередью недоставленных сообщений, обычно включает следующие параметры:

Переменная	Значение по умолчанию	Описание
dead_letter_queue.enable	включает очередь для недоставленных сообщений	false
dead_letter_queue.max_bytes	размер очереди недоставленных сообщений в байтах	1024mb
dead_letter_queue.flush_interval	период записи очереди в файл в миллисекундах	5000

Глобальные параметры Logstash

Глобальные параметры Logstash располагаются в файле <PATH_TO_LOGSTASH_CONFIG>/logstash.yml, для удобства визуально разбиты на 5 групп:

• настройки узла (var_logstash_node_settings)
• настройки директорий (var_logstash_path_settings)
• настройки пайплайнов (var_logstash_pipeline_settings)
• настройки очередей (var_logstash_queue_settings)
• настройки очередей недоставленных сообщений (var_logstash_dead_letter_queue_settings)

Если планируется изменить какой-нибудь параметр в группе, то нужно будет указать все из значения по умолчанию и изменить необходимые. Указывать параметры нужно по правилам YAML. Некоторые параметры имеют значения по умолчанию в логике Logstash, подробнее можно прочитать в официальной документации.

Например:

var_logstash_queue_settings:
  queue.type: persistent
  queue.page_capacity: 64mb
  queue.max_events: 0
  queue.max_bytes: 1024mb
  queue.checkpoint.ack s: 1024
  queue.checkpoint.writes: 1024
  queue.checkpoint.interval: 1000

Будет использован другой тип очереди с перечисленными параметрами. Если не указать ни одной переменной группы, то настройка logstash.yml будет игнорироваться.

Рекомендация по структуре файлов

Согласно правилам Ansible можно вынести параметры для группы хостов в директорию group_vars и для определённых хостов в директорию host_vars. Внутри этих директорий может быть файл с одноименным именем группы или хоста соответственно.

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

Например, есть файл инвентаризации hosts, в нём есть описание группы _example_, а также __example_. Во втором случае все параметры указаны в одном файле, в первом - разбиты на файлы в одноименной директории. В примере для хостов не используются директории, только файлы с параметрами, относящиеся к определённому хосту.

.
├── group_vars
│   ├── __example_
│   └── _example_
│       ├── connect
│       ├── logstash_base
│       ├── pipeline__default
│       ├── pipeline_apache
│       ├── pipeline_cisco_ios
│       └── pipeline_os
├── host_vars
│   ├── test1
│   ├── test2
│   ├── test3
│   └── test4
└── hosts

Обратите внимание!

Мы рекомендуем указывать дополнительные параметры для групп и хостов в директориях и разбивать параметры на файлы

Настройки каждого пайплайна рекомендуется выносить в отдельный файл, как приведено выше в примере. Называть файлы рекомендуется с ключевого слова pipeline_, далее должно следовать имя пайплайна (id в pipelines.yml).

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

Описать определённый пайплайн можно в параметрах (подробнее в следующем разделе) или создать шаблон в формате JINJA2 в директории templates/conf.d, например, в примере ниже при указании пайплайна wineventlog будет использован шаблон файла wineventlog.conf.j2. Так же здесь присутствует шаблон для пайплайна test, для всех остальных пайплайнов будет использован шаблон default_pipeline.j2.

.
└── templates
    ├── conf.d
    │   ├── common
    │   ├── default_pipeline.j2
    │   ├── test.conf.j2
    │   └── wineventlog.conf.j2
    ├── logstash.yml.j2
    └── pipelines.yml.j2

Пример содержимого файла шаблона пайплайна:

input {
{%      include 'common/input.j2' %}
}

filter {
  json{
    source => "message"
  }

  date {
    match => [ "timestamp" , "ISO8601"]
  }

  mutate{
    remove_field => ["path"]
  }
}

output {
{%      include 'common/output.j2' %}
}

В данном примере блоки input и output будут заполняться из параметров, описанных в конфигурациях, а блок filter будет игнорироваться и использован из данного шаблона.

Настройка пайплайнов

Существует несколько уровней конфигурации пайплайнов, приведены в порядке уменьшения приоритета:

• на уровне хоста у определённого пайплайна
• на уровне хоста default
• на уровне группы у определённого пайплайна
• на уровне группы default

Обратите внимание!

При запуске плейбука, все объекты (параметры) объединяются в указанном приоритете, если в параметре был список - то он полностью заменяется списком более приоритетного уровня.

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

• var_logstash_pipelines_list - используется в группах хостов
• host_var_logstash_pipelines_list - используется в хостах

При разделении параметров групп и хостов на файлы согласно нашей рекомендации вышеуказанные объекты заменяются на множество объектов, к их имени добавляется _<id_pipeline>, где <id_pipeline> должен быть заменён на уникальный id, например: var_logstash_pipelines_list_test var_logstash_pipelines_list_apache host_var_logstash_pipelines_list_win_log

Для дефолтных настроек зарезервированы следующие объекты: var_logstash_pipelines_list_default host_var_logstash_pipelines_list_default

Обратите внимание!

Объекты рекомендуются размещать в соответствующих файлах с именем pipeline_<id_pipeline>.

Внутри соответствующего объекта должен быть объект с именем <id_pipeline>. Например, для описания default должен быть создан файл pipeline__default, внутри него должны быть следующие объекты:

var_logstash_pipelines_list_default:
  default:

Для пайплайна apache должен быть создан файл pipeline_apache, внутри которого будут объекты:

var_logstash_pipelines_list_apache:
  apache:

Внутри объектов могут быть следующие объекты:

• copy_files
• configs
• input
• filter
• output

Объект default

Объект default используется для указания одинаковых параметров для всех пайплайнов. Совпадающие параметры или объекты плагинов по имени будут заменены данными из более приоритетных. Внутри объекта можно указать сразу все общие параметры для разных плагинов, при описании плагинов блоков input, output параметры из default будут применяться только при указании соответствующего плагина.

Например:

input:
  file:
    add_field:
      '[logstash][fil1]': 'fsdbfhsdbfgdfsfgbdfbg'
      '[logstash][fil2]': 'fsdbfhsdbfgdfsfgbdfb2'
      '[logstash][fil3]': 3423
    codec:
      cef:
        ecs_compatibility: 'disabled'
  relp:
    codec: 'cef {}'

В данном примере указаны плагины блока input file и relp, везде в пайпланах, где будет указан один из этих плагинов будут добавлены соответствующих параметры.

Объект copy_files

Объект создан специально для случае, когда нужно скопировать определённые файлы как есть на сервер. Имеет следующий синтаксис:

copy_files:
  - source: 'vbtest/apache.sql'
    destination: '/app/logstash/config/conf.d/apache/'
  - source: 'vbtest/apache2.sql'
    destination: '/app/logstash/config/conf.d/apache/'

Директории создаются автоматически если не были созданы.

Объект configs

В этом объекте описываются параметры для пайплайна, которые прописываются в файле pipelines.yml. Параметры указываются согласно синтаксису YAML, используются параметры из документации Logstash.

Пример:

configs:
  pipeline:
    workers: 5
    batch:
      size: 125
  modules: |
    - name: MODULE_NAME1
      var.PLUGIN_TYPE1.PLUGIN_NAME1.KEY1: VALUE
      var.PLUGIN_TYPE1.PLUGIN_NAME1.KEY2: VALUE
      var.PLUGIN_TYPE2.PLUGIN_NAME2.KEY1: VALUE
      var.PLUGIN_TYPE3.PLUGIN_NAME3.KEY1: VALUE
    - name: MODULE_NAME2
      var.PLUGIN_TYPE1.PLUGIN_NAME1.KEY1: VALUE
      var.PLUGIN_TYPE1.PLUGIN_NAME1.KEY2: VALUE

Результатом будет:

- pipeline.id: apache
  path.config: '/app/logstash/config/conf.d/apache.conf'
  pipeline.workers: 5
  pipeline.batch.size: 125
  modules:
    - name: MODULE_NAME1
      var.PLUGIN_TYPE1.PLUGIN_NAME1.KEY1: VALUE
      var.PLUGIN_TYPE1.PLUGIN_NAME1.KEY2: VALUE
      var.PLUGIN_TYPE2.PLUGIN_NAME2.KEY1: VALUE
      var.PLUGIN_TYPE3.PLUGIN_NAME3.KEY1: VALUE
    - name: MODULE_NAME2
      var.PLUGIN_TYPE1.PLUGIN_NAME1.KEY1: VALUE
      var.PLUGIN_TYPE1.PLUGIN_NAME1.KEY2: VALUE

Объект input

В этом объекте могут быть следующие объекты:

• clear_text
• LDAPSearch
• exec
• kafka
• snmp
• udp
• file
• opensearch
• syslog
• beats
• elasticsearch
• jdbc
• relp
• tcp

clear_text специальный объект, подробнее описан в объекте filter.

Для остальных объектов можно использовать параметры одноименных плагинов из документации ElasticSearch Logstash input plugin.

Если в пайплайне используется один input plugin, то можно указывать параметры плагина в синтаксисе YAML, например:

input:
  file:
    path: '/app/generator/data/generated/apc_snmp_generated.log'
    start_position: 'beginning'
    sincedb_path: '/dev/null'

Если в пайплайне используется несколько одинаковых input plugin, то можно указать списком, например:

input:
  relp:
    - id: 'cef_erpv1'
      port: 10343
      codec: 'cef { reverse_mapping => false }'
    - id: 'cef_kredan'
      port: 10804
      codec:
        json:
          ecs_compatibility: 'v8'
    - id: 'cef_sasid'
      port: 11655

Дополнительные параметры из объекта default.relp будут добавлены в каждый плагин из примера выше.

Объект filter

Для объекта может быть только параметр clear_text. Текст внутри параметра будет добавлен как есть. Пример:

clear_text: |
  grok {
    match => { "message" => "%{IP_OR_HOST:clientip} %{DATA:ident}" }
  }
  date {
    match => [ "timestamp" , "dd/MMM/yyyy:HH:mm:ss Z" ]
  }
  mutate{
    remove_field => ["path"]
  }

Стоит обратить внимание на вертикальную черту "|", а также на отступы внутри параметра clear_text согласно правилам YAML.

Объект output

В этом объекте могут быть следующие объекты:

• clear_text
• http
• stdout
• udp
• elasticsearch
• opensearch
• tcp

Можно указать несколько разных плагинов, например:

input:
  file:
    path: ['/app/generator/data/generated/apache_generated.log', '/var/log/test.log']
    check_archive_validity: true
    start_position: 'beginning'
    exclude:
      - test1
      - test2
    sincedb_path: '/dev/null'
    add_field:
      '[logstash][fil1]': 'yyyyy'
      '[logstash][fil5]': 1923
  kafka:
    topics: ['top1', 'top2']

В примере выше будет два плагина file и kafka с описанными параметрами.

Объект codec

Некоторые плагины имеют параметр codec, его можно указать строкой:

input:
  relp:
    - id: 'cef_erpv1'
      port: 10343
      codec: 'cef { reverse_mapping => false }'

Можно указывать параметры как внутри объекта:

input:
  relp:
    id: 'cef_erpv1'
    codec:
      json:
        ecs_compatibility: 'v8'

Указание параметров codec как объекты возможно только для следующих объектов:

• cef
• csv
• json
• json_lines
• plain

Примеры

Конфигурационные файлы роли Ansible

Файл pipeline__default:

var_logstash_pipelines_list_default:
  default:
    output:
      opensearch:
        hosts:
          - 'https://172.16.0.174:9200'
          - 'https://172.16.0.175:9200'
        index_region: 'testregion'
        user: 'logstash'
        password: '{ES_PWD}'
        ssl: true
        cacert: '/app/logstash/config/ca-cert.pem'
        ilm_enabled: false
    input:
      relp:
        codec: 'cef {}'

Файл pipeline_test:

var_logstash_pipelines_list_test:
  test:
    output:
      opensearch:
    input:
      file:
        path: '/app/generator/data/generated/cisco_ios_generated.log'
        start_position: 'beginning'
        sincedb_path: '/dev/null'
    filter:
      clear_text: |
        grok {
          match => ["message", "%{DATA:timestamp} %{IPV4:ip} %{INT:number}:"]
        }

Файл pipeline_test2:

var_logstash_pipelines_list_test2:
  test2:
    output:
      opensearch:
        hosts:
          - 'https://172.16.0.174:9200'
        user: 'admin'
    input:
      relp:
        id: 'cef_erpv1'
        port: 10343

Результаты после выполнения плейбука Ansible

Файл pipelines.yml:

- pipeline.id: test
  path.config: '/app/logstash/config/conf.d/test.conf'

- pipeline.id: test2
  path.config: '/app/logstash/config/conf.d/test2.conf'

Файл conf.d/test.conf

input {
    file {
        path => "/app/generator/data/generated/cisco_ios_generated.log"
        sincedb_path => "/dev/null"
        start_position => "beginning"

    }
}

filter {
    grok {
      match => ["message", "%{DATA:timestamp} %{IPV4:ip} %{INT:number}:"]
    }
}

output {
    opensearch {
        cacert => "/app/logstash/config/ca-cert.pem"
        hosts => ["https://172.16.0.174:9200", "https://172.16.0.175:9200"]
        ilm_enabled => "false"
        index => "test_testregion"
        password => "{ES_PWD}"
        ssl => true
        user => "logstash"

    }
}

Файл conf.d/test2.conf

input {
    relp {
        port => 10343
        codec => cef {}
        id => "cef_erpv1"

    }
}


output {
    opensearch {
        cacert => "/app/logstash/config/ca-cert.pem"
        hosts => ["https://172.16.0.174:9200"]
        ilm_enabled => "false"
        index => "test2_testregion"
        password => "{ES_PWD}"
        ssl => true
        user => "admin"

    }
}