Установка на Linux¶

На Linux агент ставят в двух ролях:

частный агент («Частный (инфраструктура)») на сервере, виртуальной машине или плате вроде Raspberry Pi – службой systemd, ниже;
пользовательское устройство – рабочая станция сотрудника под Linux, в конце страницы.

Для роутера с OpenWrt – отдельная инструкция: Роутеры.

Частный агент службой systemd¶

Что понадобится¶

Linux с systemd 235 или новее: Debian 10+, Ubuntu 18.04+, RHEL/Rocky/Alma 8+, Raspberry Pi OS. Архитектура – x86_64 (amd64), 64-битный ARM (arm64) или 32-битный ARMv7 (arm, например Raspberry Pi 2).
Права root (sudo).
Три файла в одном каталоге на машине:
- сборка агента netelum-agent-<версия>-linux-<архитектура> – ссылка на неё стоит первым шагом на вкладке «macOS / Linux» окна «Добавить агента»; если ссылки нет, сборку даёт поддержка Netelum;
- установщик службы install-service.sh и юнит netelum-agent.service – их тоже даёт поддержка Netelum.
Токен агента – шаг 1. Окно установки – семь суток.
Адреса платформы. Ниже в примерах https://netelum.example.com, подставьте адрес своей платформы: https://netelum.example.com/agent/manager и https://netelum.example.com/agent/collector.

Шаг 1. Завести агента и получить токен¶

Настройки → Агенты → «+ Добавить агента», тип «Частный (инфраструктура)», имя – как агент будет называться в списке и в тестах. Окно покажет токен – один раз, его надо скопировать сразу и передать безопасным каналом.

Токен действует год, но запустить агента с ним надо до срока установки – у частного агента это семь суток, точное время окно пишет под токеном. Не успели – в раскрытии строки агента, блок «Токен», кнопка «Выдать новый» выписывает новый, см. Токены агентов.

Вкладка «macOS / Linux» в окне

На вкладке – ссылка на сборку и две команды: сохранить токен в файл и запустить агента (netelum-agent daemon …) прямо в терминале. Так удобно проверить агента за минуту, но он работает, пока открыт терминал. Для постоянной работы ставьте службу по шагу 2 – с тем же токеном.

Шаг 2. Запустить установщик¶

На машине, из каталога с тремя файлами:

chmod +x install-service.sh
sudo ./install-service.sh \
  --manager https://netelum.example.com/agent/manager \
  --collector https://netelum.example.com/agent/collector \
  --agent-name <имя из шага 1>

Установщик попросит вставить токен – вставить и нажать Enter. Токен на экране не показывается, в ответ установщик пишет его длину. В командную строку и в историю оболочки токен не попадает: флага --token у установщика нет вовсе.

Без интерактивного ввода (Ansible и т. п.) токен передаётся файлом: --token-file <путь>. Файл после установки можно удалить – установщик сохраняет свою копию.

Токен раскладывает Ansible

Агент сам меняет свой токен раз в 90 дней. Если файл токена на машинах поддерживает Ansible или другая система, она вернёт старый токен, и платформа примет это за кражу. В этом случае выключите автосмену, см. Токены агентов.

Если агент должен быть второй стороной теста «агент – агент», добавьте --a2a-listen <адрес>:<порт> – адрес, по которому до этой машины дойдёт другой агент, и порт не ниже 1024.

Установщик:

кладёт агента в /usr/local/bin/netelum-agent;
заводит системного пользователя netelum без входа в систему – агент работает от него, а не от root;
сохраняет токен в /var/lib/netelum/token с правами 600 на этого пользователя – в каталог, куда службе можно писать: агент сам меняет токен по команде платформы; адреса и имя – в /etc/netelum/agent.env;
ставит службу netelum-agent, включает её в загрузку и запускает;
через пять секунд проверяет, что агент работает, а не упал на старте.

Ответ при успехе – строка агент установлен и запущен: netelum-agent (версия …).

Если сборка не подходит машине (например, arm64 на 32-битной плате), установщик скажет об этом сразу и ничего не тронет.

Шаг 3. Проверить¶

Через минуту агент появится на Настройки → Агенты, вкладка «Частные», со статусом «онлайн». На самой машине:

systemctl status netelum-agent
sudo tail -20 /var/log/netelum/agent.log

Обновление¶

Частный агент на Linux сам не обновляется: в колонке «Версия» у него нет кнопки «Обновить», а в раскрытии строки – «обновляется вручную», см. Обновления агентов.

Скачайте новую сборку в каталог с установщиком (старую оттуда уберите) и запустите установщик с теми же адресами и тем же токеном – новый выписывать не нужно. Токен берите из файла на машине, а не из старой записи: агент мог сменить его сам. У установки до октября 2026 года файл лежит в /etc/netelum/token – укажите его, установщик перенесёт токен на новое место:

sudo ./install-service.sh \
  --manager https://netelum.example.com/agent/manager \
  --collector https://netelum.example.com/agent/collector \
  --agent-name <имя> \
  --token-file /var/lib/netelum/token

Служба останавливается, файлы подменяются, служба поднимается; в ответе – переустановлен и новая версия.

«токен не сменён» у старой установки

Если в блоке «Токен» написано, что агенту не записать файл токена, – это установка до октября 2026 года, где файл лежит в /etc/netelum. Переустановите агента командой выше с --token-file /etc/netelum/token: файл переедет туда, куда службе можно писать.

Подробный лог на время разбора¶

sudo -u netelum netelum-agent verbose -for 2h -log-file /var/log/netelum/agent.log

Именно sudo -u netelum, а не просто sudo: файл-флаг, созданный root'ом, агент прочитать не может – подробный режим включится, но на два часа по умолчанию, а не на заказанный срок. Архив диагностики для поддержки – sudo netelum-agent diag -log-file /var/log/netelum/agent.log.

Удаление¶

sudo ./install-service.sh --uninstall

Служба останавливается и снимается, юнит и токен удаляются. Лог, настройки, бинарник и пользователь остаются – по ним разбирают, почему агента снимали. Удалить и их: sudo ./install-service.sh --uninstall --purge. Запись агента на платформе удаляет или отправляет в архив администратор на Настройки → Агенты, см. Парк агентов.

Если на машине уже работает агент¶

Самодельный юнит или контейнер с агентом надо остановить до установки: два агента с одним токеном будут отчитываться наперебой. Установщик ставит службу netelum-agent и чужие юниты не трогает.

Пользовательское устройство на Linux¶

Для рабочей станции сотрудника под Linux окно «Добавить агента» с типом «Пользовательское устройство» показывает вкладку «Linux» в три шага:

«Скачайте сборку агента» – ссылка на netelum-agent-<версия>-linux-<архитектура>. Если ссылки нет, окно просит взять сборку у администратора аккаунта: обратитесь в поддержку Netelum.

«Сохраните токен в файл – вставьте его в терминал и нажмите Enter» – та же команда, что на Mac (см. Установка на Mac):

mkdir -p ~/.netelum && umask 077 && printf 'Вставьте токен и нажмите Enter: ' && { IFS= read -rs T || [ -n "$T" ]; } && printf '%s' "$T" > ~/.netelum/agent.token && echo && echo "Токен сохранён, длина ${#T}" && unset T

«Запустите агента»:

netelum-agent endpoint \
  -manager https://netelum.example.com/agent/manager \
  -collector https://netelum.example.com/agent/collector \
  -token-file ~/.netelum/agent.token

Файл токена создаётся с правами 600 – агент отвергает более широкие. Окно установки токена – час.

Пока без установщика

Для пользовательского устройства на Linux установщика и автозапуска нет: агент работает, пока запущен из терминала. Скачанный файл перед запуском нужно сделать исполняемым (chmod +x) и вызывать по своему имени или положить в PATH как netelum-agent. Сам агент на Linux не обновляется – новую сборку ставят вручную.