docs: add documentation for vector-accel-ppp setup process
This commit is contained in:
parent
06233065cb
commit
30d8512146
1 changed files with 332 additions and 0 deletions
332
vector-accel-ppp-setup.md
Normal file
332
vector-accel-ppp-setup.md
Normal file
|
|
@ -0,0 +1,332 @@
|
|||
# Vector: перетрансляція логів у Graylog (Debian)
|
||||
|
||||
Інструкція з встановлення та налаштування агента [Vector](https://vector.dev)
|
||||
для збору логів з окремих файлів (сервіси на кшталт `accel-ppp`, які не
|
||||
пишуть у syslog, а тільки у власний лог-файл) і пересилання їх на
|
||||
централізований Graylog по UDP. Використовується там, де сервіс не вміє
|
||||
писати напряму в syslog, або де потрібен більш гнучкий контроль над
|
||||
форматом і тегуванням повідомлень, ніж дає стандартний `rsyslog`.
|
||||
|
||||
## Зміст
|
||||
|
||||
- [Огляд архітектури](#огляд-архітектури)
|
||||
- [Передумови](#передумови)
|
||||
- [Крок 1. Встановлення Vector](#крок-1-встановлення-vector)
|
||||
- [Крок 2. Базова конфігурація (приклад: accel-ppp)](#крок-2-базова-конфігурація-приклад-accel-ppp)
|
||||
- [Крок 3. Права доступу (запуск від root)](#крок-3-права-доступу-запуск-від-root)
|
||||
- [Крок 4. Запуск та перевірка роботи](#крок-4-запуск-та-перевірка-роботи)
|
||||
- [Крок 5. Додавання інших джерел логів](#крок-5-додавання-інших-джерел-логів)
|
||||
- [Крок 6. Прибирання старих правил rsyslog](#крок-6-прибирання-старих-правил-rsyslog)
|
||||
- [Діагностика проблем](#діагностика-проблем)
|
||||
- [Довідка: структура конфігурації](#довідка-структура-конфігурації)
|
||||
|
||||
## Огляд архітектури
|
||||
|
||||
```
|
||||
/var/log/accel-ppp/accel-ppp.log ──┐
|
||||
/var/log/freeradius/radius.log ────┼──▶ Vector ──▶ UDP:5140 ──▶ Graylog
|
||||
/var/log/<інший файл>.log ──────────┘ (read + tag + forward) (Servers Syslog input)
|
||||
```
|
||||
|
||||
Кожен лог-файл — це окреме **джерело** (`source`) у Vector. Кожне джерело
|
||||
проходить через своє **перетворення** (`transform`), яке додає тег і
|
||||
метадані. Усі перетворення збираються в одне **призначення** (`sink`),
|
||||
яке одним UDP-потоком шле все на Graylog. Додавання нового файлу логів
|
||||
= один новий `source` + один новий `transform` + один рядок у списку
|
||||
`inputs` існуючого sink — сам sink і адреса Graylog не міняються.
|
||||
|
||||
## Передумови
|
||||
|
||||
- [ ] Операційна система: Debian Linux (11/12)
|
||||
- [ ] Сервіс, що пише лог у файл (наприклад `accel-ppp`, `freeradius`)
|
||||
- [ ] Доступ до сервера під root або користувачем із sudo
|
||||
- [ ] Адреса Graylog-сервера: `10.254.254.202:5140` (UDP, вхід "Servers
|
||||
Syslog (RADIUS-accel-ppp)")
|
||||
- [ ] Порт 5140/udp відкритий між цим сервером і Graylog (перевірте
|
||||
firewall/маршрутизацію заздалегідь — Vector мовчки "губить" пакети,
|
||||
якщо порт недоступний, без явної помилки)
|
||||
|
||||
## Крок 1. Встановлення Vector
|
||||
|
||||
1. Додайте офіційний репозиторій Vector і встановіть його:
|
||||
|
||||
```bash
|
||||
bash -c "$(curl -sSfL https://setup.vector.dev)"
|
||||
sudo apt update
|
||||
sudo apt install vector -y
|
||||
```
|
||||
|
||||
2. Перевірте, що встановилось коректно:
|
||||
|
||||
```bash
|
||||
vector --version
|
||||
```
|
||||
|
||||
## Крок 2. Базова конфігурація (приклад: accel-ppp)
|
||||
|
||||
1. Створіть конфігураційний файл:
|
||||
|
||||
```bash
|
||||
sudo nano /etc/vector/vector.yaml
|
||||
```
|
||||
|
||||
2. Вставте базову конфігурацію. Це робочий приклад для `accel-ppp` —
|
||||
використовуйте його як шаблон і довідку, коли додаватимете інші
|
||||
джерела в кроці 5:
|
||||
|
||||
```yaml
|
||||
# ==========================================
|
||||
# 1. ДЖЕРЕЛА (Sources) — які файли читати
|
||||
# ==========================================
|
||||
sources:
|
||||
accel_ppp_log:
|
||||
type: "file"
|
||||
include:
|
||||
- "/var/log/accel-ppp/accel-ppp.log"
|
||||
read_from: "beginning"
|
||||
|
||||
# ==========================================
|
||||
# 2. ПЕРЕТВОРЕННЯ (Transforms) — форматування та тегування
|
||||
# ==========================================
|
||||
transforms:
|
||||
format_for_graylog:
|
||||
type: "remap"
|
||||
inputs:
|
||||
- "accel_ppp_log"
|
||||
source: |
|
||||
.message = encode_key_value({
|
||||
"timestamp": to_string!(.timestamp),
|
||||
"host": get_hostname!(),
|
||||
"tag": "accel-remote-only",
|
||||
"message": .message
|
||||
})
|
||||
|
||||
# ==========================================
|
||||
# 3. ПРИЗНАЧЕННЯ (Sinks) — куди відправляти
|
||||
# ==========================================
|
||||
sinks:
|
||||
graylog_out:
|
||||
type: "socket"
|
||||
inputs:
|
||||
- "format_for_graylog"
|
||||
address: "udp://10.254.254.202:5140"
|
||||
mode: "udp"
|
||||
encoding:
|
||||
codec: "text"
|
||||
```
|
||||
|
||||
3. Збережіть файл (`Ctrl+O`, `Enter`) і вийдіть (`Ctrl+X`).
|
||||
|
||||
4. Перевірте синтаксис перед запуском:
|
||||
|
||||
```bash
|
||||
vector validate /etc/vector/vector.yaml
|
||||
```
|
||||
|
||||
Якщо є помилка — `vector validate` вкаже точний рядок і причину; не
|
||||
запускайте службу, поки ця команда не відповість без помилок.
|
||||
|
||||
## Крок 3. Права доступу (запуск від root)
|
||||
|
||||
Лог-файли на кшталт `accel-ppp.log` часто мають права `600` (читає лише
|
||||
власник, зазвичай root), тож стандартний користувач `vector` не зможе їх
|
||||
прочитати. Найпростіше рішення — запускати службу від `root`.
|
||||
|
||||
> Альтернатива, якщо не хочете давати `vector` права root: додайте
|
||||
> користувача `vector` у групу-власника файлу (`usermod -aG <група>
|
||||
> vector`) і виставте на файл права `640`. Це вужче за обсягом, але
|
||||
> вимагає стежити за правами при кожному новому джерелі логів. Для
|
||||
> простоти цей гайд іде шляхом `root`.
|
||||
|
||||
1. Відкрийте редактор перевизначення systemd-юніта:
|
||||
|
||||
```bash
|
||||
sudo systemctl edit vector
|
||||
```
|
||||
|
||||
2. У порожні рядки вгорі файлу вставте:
|
||||
|
||||
```ini
|
||||
[Service]
|
||||
User=root
|
||||
Group=root
|
||||
```
|
||||
|
||||
3. Збережіть і закрийте (`Ctrl+O`, `Enter`, `Ctrl+X`).
|
||||
|
||||
## Крок 4. Запуск та перевірка роботи
|
||||
|
||||
1. Перечитайте конфігурацію systemd і запустіть Vector з автозавантаженням:
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now vector
|
||||
```
|
||||
|
||||
2. Перевірте статус і логи в реальному часі:
|
||||
|
||||
```bash
|
||||
sudo systemctl status vector
|
||||
sudo journalctl -u vector -f
|
||||
```
|
||||
|
||||
Успішний результат — рядок виду:
|
||||
```
|
||||
INFO source{...}: Found new file to watch. file=/var/log/accel-ppp/accel-ppp.log
|
||||
```
|
||||
без жодних `Permission denied`.
|
||||
|
||||
3. Згенеруйте тестовий рядок у файлі логу і перевірте, що він долетів до
|
||||
Graylog (System → Inputs → відповідний input → "Received messages",
|
||||
або Search з широким часовим діапазоном):
|
||||
|
||||
```bash
|
||||
echo "vector test line $(date)" | sudo tee -a /var/log/accel-ppp/accel-ppp.log
|
||||
```
|
||||
|
||||
## Крок 5. Додавання інших джерел логів
|
||||
|
||||
Щоб додати ще один лог-файл (наприклад, FreeRADIUS, або будь-який інший
|
||||
сервіс, що пише у файл), потрібні три зміни в `/etc/vector/vector.yaml`:
|
||||
новий `source`, новий `transform`, і додати назву цього transform у
|
||||
список `inputs` існуючого `sink`. Сам `sink` (адреса Graylog) лишається
|
||||
один — усі джерела йдуть через нього.
|
||||
|
||||
### Шаблон
|
||||
|
||||
```yaml
|
||||
sources:
|
||||
<унікальна_назва_джерела>:
|
||||
type: "file"
|
||||
include:
|
||||
- "<повний шлях до файлу логів>"
|
||||
read_from: "beginning"
|
||||
|
||||
transforms:
|
||||
<унікальна_назва_transform>:
|
||||
type: "remap"
|
||||
inputs:
|
||||
- "<унікальна_назва_джерела>"
|
||||
source: |
|
||||
.message = encode_key_value({
|
||||
"timestamp": to_string!(.timestamp),
|
||||
"host": get_hostname!(),
|
||||
"tag": "<унікальний_тег_для_пошуку_в_graylog>",
|
||||
"message": .message
|
||||
})
|
||||
```
|
||||
|
||||
Потім допишіть `<унікальна_назва_transform>` у список `inputs` sink'у
|
||||
`graylog_out` (він уже є в конфізі з кроку 2):
|
||||
|
||||
```yaml
|
||||
sinks:
|
||||
graylog_out:
|
||||
type: "socket"
|
||||
inputs:
|
||||
- "format_for_graylog" # вже було (accel-ppp)
|
||||
- "<унікальна_назва_transform>" # новий рядок
|
||||
address: "udp://10.254.254.202:5140"
|
||||
mode: "udp"
|
||||
encoding:
|
||||
codec: "text"
|
||||
```
|
||||
|
||||
**Правила іменування**, щоб уникнути конфліктів при кількох джерелах:
|
||||
- назва `source` і `transform` мають бути унікальними в межах усього
|
||||
конфігураційного файлу (не тільки в межах одного сервісу);
|
||||
- `tag` — це те, за чим ви шукатимете в Graylog (`tag:radius-server` тощо),
|
||||
тож робіть його осмисленим і не повторюваним для різних сервісів.
|
||||
|
||||
### Готовий приклад: додавання логу FreeRADIUS
|
||||
|
||||
```yaml
|
||||
sources:
|
||||
# ... accel_ppp_log вже є ...
|
||||
freeradius_log:
|
||||
type: "file"
|
||||
include:
|
||||
- "/var/log/freeradius/radius.log"
|
||||
read_from: "beginning"
|
||||
|
||||
transforms:
|
||||
# ... format_for_graylog вже є ...
|
||||
format_freeradius_for_graylog:
|
||||
type: "remap"
|
||||
inputs:
|
||||
- "freeradius_log"
|
||||
source: |
|
||||
.message = encode_key_value({
|
||||
"timestamp": to_string!(.timestamp),
|
||||
"host": get_hostname!(),
|
||||
"tag": "radius-server",
|
||||
"message": .message
|
||||
})
|
||||
|
||||
sinks:
|
||||
graylog_out:
|
||||
type: "socket"
|
||||
inputs:
|
||||
- "format_for_graylog"
|
||||
- "format_freeradius_for_graylog"
|
||||
address: "udp://10.254.254.202:5140"
|
||||
mode: "udp"
|
||||
encoding:
|
||||
codec: "text"
|
||||
```
|
||||
|
||||
Після будь-якої зміни конфігурації:
|
||||
|
||||
```bash
|
||||
vector validate /etc/vector/vector.yaml # спершу перевірити синтаксис
|
||||
sudo systemctl restart vector # застосувати
|
||||
sudo journalctl -u vector -f # переконатись, що нове джерело підхопилось
|
||||
```
|
||||
|
||||
> Якщо новий лог-файл має інші права доступу/власника — переконайтесь,
|
||||
> що користувач, від якого запущено Vector (за кроком 3 — `root`), може
|
||||
> його прочитати, інакше повторите проблему з кроку 3 для нового файлу.
|
||||
|
||||
## Крок 6. Прибирання старих правил rsyslog
|
||||
|
||||
Якщо раніше для відправки логів цього файлу використовувався `rsyslog`
|
||||
(наприклад, через модуль `imfile`), після переходу на Vector варто
|
||||
прибрати дублюючі правила, щоб те саме повідомлення не потрапляло в
|
||||
Graylog двічі з різними форматами.
|
||||
|
||||
1. Відкрийте конфігурацію rsyslog (`/etc/rsyslog.conf` або файли у
|
||||
`/etc/rsyslog.d/`).
|
||||
2. Знайдіть і видаліть/закоментуйте правила з модулем `imfile`, тегом,
|
||||
що відповідає файлу (наприклад `accel-remote-only`), і командою
|
||||
видалення повідомлення (`~`, щоб воно не йшло далі за замовчуванням).
|
||||
3. Перезапустіть rsyslog:
|
||||
|
||||
```bash
|
||||
sudo systemctl restart rsyslog
|
||||
```
|
||||
|
||||
## Діагностика проблем
|
||||
|
||||
| Симптом | Ймовірна причина | Що перевірити |
|
||||
|---|---|---|
|
||||
| `Permission denied` у `journalctl -u vector` | Vector не має прав читати лог-файл | Крок 3 виконано? `ls -la <файл>` — хто власник і які права |
|
||||
| Служба запущена, файл читається, але в Graylog нічого немає | Порт 5140 недоступний з цього сервера (firewall/маршрутизація) | `nc -u -zv 10.254.254.202 5140` з цього сервера; `tcpdump -i eth0 udp port 5140` на стороні Graylog |
|
||||
| `vector validate` видає помилку | Помилка синтаксису YAML або VRL у `transform` | Читайте повідомлення про помилку — воно вказує точний рядок; перевірте відступи (YAML чутливий до пробілів) |
|
||||
| Повідомлення доходять, але без полів `vendor`/`event_type` у Graylog | Pipeline rules у Graylog ще не мають правила під формат саме цього тегу/сервісу | Дайте кілька реальних рядків логу — можна додати нове pipeline rule за тим самим принципом, що й для accel-ppp/RADIUS |
|
||||
| Дублікати повідомлень у Graylog | Старе правило `rsyslog` досі активне паралельно з Vector | Виконайте крок 6 |
|
||||
| Vector запускається, але не бачить оновлень файлу | Файл ротується (logrotate) інакше, ніж очікує Vector | Перевірте `include`/`ignore_older_secs`; за потреби додайте `fingerprint` налаштування у `source`, щоб Vector коректно стежив за файлом після ротації |
|
||||
|
||||
## Довідка: структура конфігурації
|
||||
|
||||
- **`sources`** — звідки Vector бере дані. Тип `file` = читає (і "хвостить")
|
||||
вказаний файл, `read_from: "beginning"` = при першому запуску прочитати
|
||||
файл з початку (а не тільки нові рядки).
|
||||
- **`transforms`** (тип `remap`) — обробка даних мовою VRL (Vector Remap
|
||||
Language). У цьому гайді використовується `encode_key_value()`, щоб
|
||||
зібрати повідомлення у вигляді `timestamp=... host=... tag=... message=...`
|
||||
— простий, передбачуваний текстовий формат, який легко парсити правилами
|
||||
в Graylog.
|
||||
- **`sinks`** (тип `socket`, `mode: "udp"`) — куди й як відправляти
|
||||
результат. Один sink може приймати від багатьох transforms одночасно
|
||||
(список `inputs`) — саме так додаються нові джерела логів без створення
|
||||
нового sink чи нової адреси.
|
||||
Loading…
Add table
Reference in a new issue