Як налаштувати systemd service для валідатора

systemd — єдиний надійний спосіб запуску валідатора Solana на продакшн-серверах. Цей посібник містить готовий unit-файл, пояснення кожної директиви та процедури управління сервісом, перевірені на Ubuntu 24.04 LTS з клієнтом Agave validator.

Операційні вимоги для «Як налаштувати systemd service для валідатора» перевірено 2 серпня 2026 року. Для production використовуйте тільки реліз Agave, рекомендований для конкретного кластера, і звіряйте параметри з agave-validator --help . Офіційні вимоги Anza на цю дату орієнтують операторів на Ubuntu 24.04, щонайменше 12 ядер/24 потоки, 256 ГБ RAM, окремі швидкі NVMe та симетричний канал від 2 Гбіт/с; це рекомендації, а не гарантія достатньої продуктивності.

Чому systemd — стандартний спосіб запуску

Валідатор Solana — це довгоживучий процес, який повинен працювати безперервно, автоматично перезапускатися після збоїв та підніматися разом із сервером. systemd забезпечує це нативно на всіх сучасних дистрибутивах Linux.

Альтернативи — screen, tmux, nohup, crontab із @reboot — не дають контролю над життєвим циклом процесу. Вони не вміють:

• відстежувати стан процесу через cgroups;
• обмежувати споживання пам'яті на рівні ядра;
• передавати сигнали watchdog для детектації зависань;
• структуровано логувати з метаданими (PID, timestamps, cgroup);
• керувати залежностями між сервісами (мережа, диски, монтування).

Для інфраструктурного оператора systemd — це не перевага, а вимога. Без нього неможливо побудувати відтворюване середовище та інтегрувати валідатор у стандартні процедури моніторингу й аварійного відновлення.

Створення unit-файлу: ключові директиви

Середовище перевірки: Ubuntu 24.04 LTS, клієнт Agave validator (перевірте актуальну версію у вашому середовищі командою agave-validator --version), кластер mainnet-beta.

Передумови: бінарний файл валідатора вже встановлений у /home/solana/.local/share/solana/install/active_release/bin/, каталог ledger існує, ключі валідатора та identity на місці.

Створіть файл /etc/systemd/system/agave-validator.service:

Попередження: перед створенням або редагуванням unit-файлу переконайтеся, що валідатор зупинений. Якщо він працює через screen або tmux, спочатку завершіть його коректно (Ctrl+C), щоб уникнути дублювання процесів та конфліктів доступу до ledger.

Очікуваний результат: файл створено, синтаксис коректний.

Перевірка:

1. systemd-analyze verify /etc/systemd/system/agave-validator.service — має повернути порожній результат без помилок.
2. systemd-analyze cat-config agave-validator.service — відобразить фактичний конфіг із усіма drop-in замінами.

RestartPolicy, watchdog, ліміти пам'яті

Політика перезапуску

Restart=on-failure — єдиний безпечний варіант для валідатора. Він перезапускає процес лише якщо той завершився з ненульовим кодом виходу або був убитий сигналом. Restart=always у цьому контексті небезпечний: якщо ви зупинили сервіс через systemctl stop, а потім процес завершився з кодом 0, always все одно підніме його знову.

RestartSec=10 дає час системі звільнити ресурси (порти, файлові дескриптори, mmap-області) перед повторним запуском. Занадто малий інтервал (1–2 секунди) може призвести до помилки прив'язки порту (address already in use).

Watchdog

WatchdogSec=60 інструктує systemd стежити за тим, щоб процес надсилав keepalive-сигнали. Проте Agave validator наразі не реалізує інтеграцію з systemd watchdog нативно. Тому ця директива в поточній конфігурації не активна — вона не завдає шкоди, але й не дає додаткового захисту. Якщо клієнт додасть підтримку sd_notify у майбутніх версіях, watchdog почне працювати автоматично без зміни unit-файлу. Перевірте актуальний статус у реліз-нотах клієнта.

Ліміти пам'яті

Для валідатора Solana не рекомендується встановлювати жорсткий ліміт через MemoryMax. Процес активно використовує mmap для роботи з ledger та accounts, і примусове завершення через OOM killer від systemd призведе до некоректного від'єднання від мережі та втрати слотів.

Замість цього налаштуйте обмінну область (swap) та параметри ядра:

• vm.swappiness=1 у /etc/sysctl.d/99-solana.conf — мінімізує використання swap, але залишає його як страховий буфер.
• Фізична пам'ять сервера має значно перевищувати робоче навантаження (перевірте актуальні вимоги у документації клієнта).

Якщо ви все ж вирішите встановити MemoryMax, почніть з м'якого ліміту MemoryHigh на рівні 90% фізичної пам'яті — він не вбиває процес, а лише сповільнює алокацію, даючи вам час реагувати через моніторинг.

Управління сервісом: start, stop, restart, status

Після створення unit-файлу виконайте первинне завантаження:

1. sudo systemctl daemon-reload — systemd перечитує всі unit-файли.
2. sudo systemctl enable agave-validator.service — реєструє сервіс для автозапуску.

Основні команди управління:

Ризик зупинки: systemctl stop завершує валідатор негайно. Це означає втрату консенсусної участі, пропущені слоти та потенційне зниження stake-ваги. Зупиняйте валідатор лише за планом: під час оновлення, зміни конфігурації або обслуговування інфраструктури. Не зупиняйте сервіс для рутинних перевірок — використовуйте status та journalctl.

Перевірка після запуску:

• sudo systemctl status agave-validator — має показати active (running).
• sudo systemctl show agave-validator --property=MainPID — повертає PID головного процесу, має бути ненульовим.

Логування через journald

Оскільки StandardOutput та StandardError направлені в journal, усі логи валідатора потрапляють у journald із автоматичними метаданими: timestamp, PID, cgroup, UID.

Основні команди для роботи з логами:

• sudo journalctl -u agave-validator — усі логи сервісу, від найстаріших до найновіших.
• sudo journalctl -u agave-validator -f — режим слідкування (tail -f), корисно при першому запуску.
• sudo journalctl -u agave-validator --since "2025-01-15 10:00:00" — логи від конкретного часу (замініть на актуальну дату).
• sudo journalctl -u agave-validator --no-pager — вивід без пейджера, зручно для скриптів.
• sudo journalctl -u agave-validator -o json-pretty — структурований JSON-вивід для парсингу.

Типові маркери в логах для діагностики:

• "Starting validator" — процес ініціалізовано.
• "Ledger load complete" — ledger завантажено, валідатор переходить до синхронізації.
• "Voted" — валідатор бере участь у консенсусі.
• "slot skipped" — пропущений слот, може вказувати на проблеми з мережею або навантаженням.

Обмеження журналу: за замовчуванням journald зберігає логи у volatile-пам'яті (/run/log/journal) або на диску (/var/log/journal) із лімітами, що залежать від розміру файлової системи. Для валідатора, який генерує значний обсяг логів, перевірте та за потреби налаштуйте у /etc/systemd/journald.conf:

• SystemMaxUse=4G — максимальний обсяг на диску.
• SystemMaxFileSize=512M — максимальний розмір одного файлу журналу.
• MaxRetentionSec=30day — час зберігання.

Після зміни конфігурації journald виконайте: sudo systemctl restart systemd-journald.

Автозапуск після перезавантаження

Автозапуск забезпечується двома кроками, обидва обов'язкові:

1. systemctl enable — створює символічне посилання з /etc/systemd/system/multi-user.target.wants/agave-validator.service на сам unit-файл. Це інструкція systemd: "при вході в multi-user.target — запусти цей сервіс".
2. WantedBy=multi-user.target у секції [Install] unit-файлу — вказує, до якої саме цілі прив'язуватися при enable.

Перевірка:

• sudo systemctl is-enabled agave-validator — має повернути enabled.
• ls -l /etc/systemd/system/multi-user.target.wants/agave-validator.service — має показати символічне посилання.

Тестування автозапуску без реального перезавантаження:

1. sudo systemctl stop agave-validator
2. sudo systemctl isolate multi-user.target — симулює перехід у ціль, сервіс має піднятися автоматично.
3. sudo systemctl status agave-validator — перевірте стан.

Попередження: systemctl isolate зупиняє всі сервіси, які не є залежностями multi-user.target. На віддаленому сервері це може розірвати SSH-сесію. Виконуйте цю перевірку лише через консольний доступ (IPMI, iLO, out-of-band management) або з використанням nohup/tmux для самої SSH-сесії.

Відключення автозапуску: sudo systemctl disable agave-validator — видаляє символічне посилання, але не зупиняє сервіс у поточній сесії.

Перевірка стабільності сервісу

Стабільність — це не просто "active (running)". Це відсутність перезапусків, передбачуване споживання ресурсів та передбачуваний час відповіді.

1. Історія перезапусків:

• sudo systemctl show agave-validator --property=NRestarts — кількість перезапусків у поточній сесії boot. Нуль — норма.
• sudo journalctl -u agave-validator | grep -c "Started Solana Validator" — кількість запусків за всю історію журналів. Якщо ця цифра зростає між оновленнями — є проблема.

2. Час безперервної роботи:

• sudo systemctl show agave-validator --property=ActiveEnterTimestamp — час останнього переходу в стан active.
• ps -o etime= -p $(sudo systemctl show agave-validator --property=MainPID --value) — uptime процесу в читабельному форматі.

3. Споживання пам'яті:

• sudo systemctl status agave-validator — рядок Memory показує поточне споживання з cgroup.
• sudo systemd-cgtop — моніторинг споживання ресурсів по cgroups у реальному часі.

4. Перевірка після оновлення:

Після оновлення бінарного файлу валідатора виконайте послідовність:

1. sudo systemctl daemon-reload — на випадок, якщо змінилися параметри середовища.
2. sudo systemctl restart agave-validator.
3. sudo systemctl status agave-validator — перевірте, що PID змінився (ознака фактичного перезапуску).
4. sudo journalctl -u agave-validator -f --since "1 min ago" — слідкуйте за логами перших хвилин: ініціалізація, завантаження ledger, перші голосування.
5. Через 5 хвилин: sudo systemctl show agave-validator --property=NRestarts — має бути 0.

Критерій стабільності: валідатор працює без перезапусків щонайменше 24 години після останнього втручання, NRestarts дорівнює 0, споживання пам'яті не має стійкого висхідного тренду (ознака витоку).

Наступний логічний крок у налаштуванні інфраструктури — детальна робота з прапорцями командного рядка та параметрами конфігураційного файлу валідатора, що розглядається в окремому матеріалі про конфігураційний файл валідатора.

Джерела

• Anza: Agave Validator Requirements
• Anza: Setup an Agave Validator
• Anza: Validator Security Best Practices
• Anza Agave: Releases
• Anza: Install the Solana CLI
• Solana Documentation: Staking
• Solana Documentation: Stake Accounts