Ця інструкція проведе вас через установку Agave — клієнта валідатора Solana — від підготовки сервера до першого запуску бінарного файлу. Приклади наведені для Ubuntu 24.04 LTS, кластер mainnet-beta, клієнт Agave. Конкретну версію release перевірте на офіційному репозиторії Agave перед початком роботи.

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

Передумови: система, залежності, версія

Перед тим як завантажувати бінарний файл, переконайтеся, що сервер відповідає мінімальним вимогам і має всі необхідні залежності.

Апаратні вимоги (мінімум для синхронізації з нуля):

  • CPU: 12 ядер або більше (бажано з високою базовою частотою).
  • RAM: 128 ГБ (менше — лише з попередньо завантаженим snapshot).
  • Накопичувач: NVMe SSD від 2 ТБ, бажано з підтримкою NVM Express 1.3+.
  • Мережа: 1 Гбіт/с і стабільне з'єднання без жорстких лімітів трафіку.

Операційна система: Ubuntu 24.04 LTS (amd64). Інші дистрибутиви працюватимуть, але команди встановлення залежностей можуть відрізнятися.

Програмні залежності:

  1. Оновіть систему та встановіть базові пакети: 
    sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential pkg-config libssl-dev libudev-dev curl jq
  2. Переконайтеся, що curl та jq доступні: 
    curl --version
jq --version

Що перевірити перед рухом далі: identity-публічний ключ, vote account та authorized voter мають бути підготовлені. Якщо ви ще цього не зробили, зверніться до матеріалу Як перевірити identity, vote account та authorized voter перед запуском.

Завантаження release Agave

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

Крок 1. Визначте актуальну версію. Перейдіть до розділу releases у репозиторії Agave на GitHub і запам'ятайте тег останнього стабільного release (формат: vX.Y.Z). У прикладах нижче замініть vX.Y.Z на реальний тег.

Крок 2. Завантажте архів.

cd ~
curl -L -o agave-release.tar.bz2 https://github.com/anza-xyz/agave/releases/download/vX.Y.Z/agave-vX.Y.Z-x86_64-linux.tar.bz2

Очікуваний результат: у домашній директорії з'являється файл agave-release.tar.bz2 розміром близько 25–40 МБ (залежно від версії). Якщо файл значно менший або завантаження переривається — перевірте мережеве з'єднання та повторіть спробу.

Верифікація бінарного файлу

Пропуск верифікації — найпоширеніша причина встановлення скомпрометованого клієнта. Завжди перевіряйте підпис.

Крок 1. Завантажте файл маніфесту та підпис. На сторінці release знайдіть файли *-manifest.txt та відповідний *-manifest.txt.asc (або аналогічні за назвою). Завантажте їх у ту саму директорію:

curl -L -o agave-manifest.txt https://github.com/anza-xyz/agave/releases/download/vX.Y.Z/agave-vX.Y.Z-manifest.txt
curl -L -o agave-manifest.txt.asc https://github.com/anza-xyz/agave/releases/download/vX.Y.Z/agave-vX.Y.Z-manifest.txt.asc

Крок 2. Імпортуйте публічний ключ підписувача. Використовуйте ключ, який вказаний у документації Agave для поточного циклу release. Перевірте цей ключ у репозиторії — він може змінюватися між циклами:

gpg --keyserver keyserver.ubuntu.com --recv-keys FINGERPRINT_HERE

Крок 3. Перевірте підпис маніфесту:

gpg --verify agave-manifest.txt.asc agave-manifest.txt

Очікуваний результат: у виводі має бути рядок Good signature from .... Якщо ви бачите BAD signature або NO PUBLIC KEY — зупиніться. Не продовжуйте встановлення, поки не з'ясуєте причину.

Крок 4. Перевірте SHA256 архіву:

sha256sum -c agave-manifest.txt --ignore-missing

У виводі має бути agave-release.tar.bz2: OK. Будь-яка невідповідність означає, що файл пошкоджено або підмінено.

Встановлення та перевірка версії

Крок 1. Розпакуйте архів:

mkdir -p ~/agave-release
tar -jxf agave-release.tar.bz2 -C ~/agave-release

Крок 2. Перемістіть бінарні файли у системну директорію.

sudo cp ~/agave-release/bin/* /usr/local/bin/

Ризик: якщо в /usr/local/bin/ вже є старі версії бінарних файлів Agave (або agave-validator від попереднього клієнта), вони будуть перезаписані. Якщо вам потрібен відкат, створіть резервну копію перед цим кроком:

sudo mkdir -p /usr/local/bin/backup-agave
sudo cp /usr/local/bin/agave-validator /usr/local/bin/backup-agave/ 2>/dev/null
sudo cp /usr/local/bin/agave-keygen /usr/local/bin/backup-agave/ 2>/dev/null

Крок 3. Перевірте встановлення:

agave-validator --version

Очікуваний результат: вивід містить версію, що збігається з тегом release, який ви завантажили. Наприклад: agave-validator X.Y.Z. Якщо команда не знайдена — перевірте, що /usr/local/bin є у вашому $PATH:

echo $PATH | grep -o '/usr/local/bin'

Створення робочої директорії

Agave потребує чіткої структури директорій для ledger, snapshotів, логів та конфігурації. Рекомендована схема:

sudo mkdir -p /mnt/ledger /mnt/snapshots /var/log/agave
sudo chown -R $(whoami):$(whoami) /mnt/ledger /mnt/snapshots /var/log/agave

Чому саме так:

  • /mnt/ledger — розміщується на найшвидшому NVMe-розділі. Ledger — найбільш інтенсивна зона запису під час синхронізації.
  • /mnt/snapshots — може бути на окремому розділі або тому самому диску, залежно від вашої схеми розміщення даних. Детальніше про те, як ledger взаємодіє зі snapshotами, читайте в матеріалі Як працюють ledger та snapshots у Solana.
  • /var/log/agave — логи валідатора. Окрема директорія дозволяє налаштувати logrotate без впливу на інші сервіси.

Перевірка прав доступу:

ls -ld /mnt/ledger /mnt/snapshots /var/log/agave

Усі три директорії мають належати вашому користувачеві. Запуск валідатора від root не підтримується і створює зайвий ризик безпеки.

Перший запуск: що відбувається

На цьому етапі ви запускаєте валідатор у режимі діагностики, щоб переконатися, що бінарний файл працює, мережа доступна, а конфігурація коректна. Повноцінне підключення до кластера з identity-ключем вимагає попередньої підготовки ключів (див. посилання вище).

Мінімальний тестовий запуск:

agave-validator \
  --ledger /mnt/ledger \
  --snapshot-dir /mnt/snapshots \
  --log /var/log/agave/validator.log \
  --rpc-port 8899 \
  --no-voting \
  --entrypoint entrypoint.mainnet.solana.com:8001

Що відбувається після запуску:

  1. Ініціалізація ledger. Якщо директорія порожня, клієнт створює новий ledger і починає шукати snapshot для прискорення синхронізації.
  2. Запит snapshotів. Валідатор звертається до entrypoint-вузлів і завантажує найсвіжіший доступний snapshot. Це може зайняти від кількох хвилин до години залежно від пропускної здатності.
  3. Синхронізація слотів. Після застосування snapshot клієнт завантажує пропущені блоки від останнього snapshot до поточного слота. У логах це виглядає як швидкозростаючі лічильники слотів.
  4. Підтримка актуальності. Коли відставання (slot skip rate) падає до нуля, валідатор переходить у режим повної синхронізації.

Як спостерігати за процесом:

tail -f /var/log/agave/validator.log | jq -r 'select(.msg) | .msg' 2>/dev/null || tail -f /var/log/agave/validator.log

Як перевірити стан без логів (в іншому терміналі):

curl -s http://127.0.0.1:8899 -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}' | jq

Очікуваний результат: "ok" — валідатор синхронізовано і працює. "behind" — синхронізація триває. Інші відповіді вимагають діагностики.

Зупинка тестового запуску: натисніть Ctrl+C. Ledger і завантажені snapshotи залишаться на диску для наступного запуску.

Типові помилки при встановленні

Нижче наведено помилки, з якими оператори стикаються найчастіше, та способи їх усунення.

1. bash: agave-validator: command not found

Причина: /usr/local/bin відсутній у $PATH, або бінарний файл не скопійовано. Перевірте наявність файлу та шлях:

ls -l /usr/local/bin/agave-validator
echo $PATH

2. Error: No such file or directory (os error 2) при вказівці ledger-директорії

Причина: директорія не існує або немає прав на запис. Створіть її та призначте права, як описано в розділі «Створення робочої директорії».

3. Failed to deserialize snapshot

Причина: snapshot пошкоджено під час завантаження або на диску недостатньо вільного місця. Видаліть вміст /mnt/snapshots та /mnt/ledger і перезапустіть валідатор — він завантажить snapshot заново.

Попередження: видалення вмісту ledger-директорії знищить локальну базу даних. Застосовуйте це лише якщо ви ще не досягли повної синхронізації або готові почати завантаження з нуля.

rm -rf /mnt/snapshots/*
rm -rf /mnt/ledger/*

4. Permission denied при записі логів

Причина: директорія /var/log/agave належить root, а валідатор запущено від іншого користувача. Виправте:

sudo chown -R $(whoami):$(whoami) /var/log/agave

5. Connection refused при зверненні до RPC-порту

Причина: валідатор ще не прослуховує порт (занадто рано звернулися), або порт зайнятий іншим процесом. Перевірте:

ss -tlnp | grep 8899

Якщо порт зайнятий стороннім процесом — зупиніть його або оберіть інший порт через прапорець --rpc-port.

6. Підпис маніфесту не проходить перевірку

Причина: застарілий ключ у локальному ключовому зв'язку GPG, або ви завантажили маніфест не від того release. Очистіть кеш GPG для цього ключа, повторно імпортуйте актуальний fingerprint із репозиторію Agave і спробуйте знову.

Після успішного першого запуску наступний логічний крок — налаштування systemd-сервісу для автоматичного перезапуску, підключення identity-ключа та vote account, а також конфігурація моніторингу. Ці кроки виходять за межі поточної інструкції та описані в наступних розділах операційного довідника.

Джерела