Установка агента Netelum на Mac¶

Пошаговая инструкция для тех, кто ставит агента на свой Mac.

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

Mac на macOS 12 или новее, Apple Silicon или Intel – пакет один на обе.
Права администратора на этом Mac (sudo).
Файл пакета netelum-agent-<версия>-darwin-universal.pkg (около 16 МБ). Администратор аккаунта скачивает его на странице Настройки → Агенты – в окне «Добавить агента» сразу после создания, на вкладке «macOS»: ссылка «Скачать для macOS» стоит первым шагом. Это тот же файл, которым обновляются уже стоящие агенты. Пакет подписан и нотаризован, macOS его не блокирует. Браузер для проверок страниц в пакете не лежит: агент скачает его с платформы сам после регистрации (~100 МБ, один раз), ничего делать не нужно.
Токен агента – его выдаёт администратор аккаунта, см. шаг 1. Окно установки – час, поэтому выдавать его, когда человек уже сидит у Mac'а.
Адреса платформы – их сообщает администратор. Ниже в примерах https://netelum.example.com, подставьте адрес своей платформы: https://netelum.example.com/agent/manager и https://netelum.example.com/agent/collector.

Шаг 1. Администратор заводит устройство и выдаёт токен¶

Окно установки – час

Выдавайте токен, когда человек уже у Mac'а: запустить агента с новым токеном нужно в течение часа.

На платформе: Настройки → Агенты → «Добавить агента», тип – «Пользовательское устройство» (он и выбран по умолчанию; пакет запускает агента именно так, подкомандой endpoint), имя – имя машины или человека, можно оставить пустым: подхватится из системы. После «Создать» окно показывает токен – один раз, скопировать его сразу и передать владельцу Mac'а безопасным каналом. На вкладке «macOS» того же окна – ссылка «Скачать для macOS» и готовые команды для шагов 2, 3 и 5 с адресами вашей платформы.

Токен действует год, но запустить агента с ним надо до срока установки – у пользовательского устройства это час, точное время окно пишет под токеном. Не успели – на Настройки → Агенты, вкладка «Пользовательские», раскройте строку устройства: в блоке «Токен» кнопка «Выдать новый» выписывает новый, с тем же часом (см. Токены агентов). Семь суток – окно «Частного (инфраструктура)» агента на сервере, к этой инструкции оно не относится.

Много Mac'ов сразу

Для парка через Jamf, Intune или другую MDM шаги 1, 2 и 5 не нужны: вместо токена на каждую машину – один ключ регистрации, см. Ключи регистрации.

Шаг 2. Сохранить токен в файл¶

На Mac, в Терминале, выполнить команду – она же стоит вторым шагом на вкладке «macOS»:

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

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

Следующая команда – только после ответа

Пока нет строки «Токен сохранён», команда ещё ждёт токен: всё, что вы вставите в это время, попадёт в файл токена, и агент с таким файлом не зарегистрируется. Если строки нет, нажмите Enter. Если длина в ответе явно больше длины токена, повторите шаг – файл перезапишется.

Сначала команда, потом токен

Команду копируют и запускают первой, токен – вторым. Так скопированная команда не затирает токен в буфере обмена.

Файл получает права 600, читает его только владелец. Токен не передаётся аргументом команды и не попадает в историю Терминала: аргументы видны всем через ps.

Шаг 3. Установить пакет¶

Двойной клик по .pkg и «Далее» до конца – или в Терминале:

sudo installer -pkg ~/Downloads/netelum-agent-26.09.0310-darwin-universal.pkg -target /

Установщик кладёт агента в /usr/local/netelum/ и не запускает его: агент ещё не знает, куда докладывать.

Шаг 4. Разрешить доступ к имени сети Wi-Fi¶

Через пару секунд после установки появится системное окно «Netelum Agent хочет использовать вашу геопозицию» – нажать «Разрешить».

Зачем: macOS считает имя сети Wi-Fi и адрес точки доступа геоданными. Без разрешения агент видит качество связи, но не видит, к какой именно точке подключён Mac, и не может отличить плохую точку от плохого устройства. Координаты не запрашиваются и никуда не отправляются.

Если окно закрыли или пропустили: Системные настройки → Конфиденциальность и безопасность → Службы геолокации → Netelum Agent → включить. Разрешение спрашивается один раз и сохраняется при обновлениях.

Шаг 5. Зарегистрировать агента¶

sudo /usr/local/netelum/enroll.sh \
  --manager   https://netelum.example.com/agent/manager \
  --collector https://netelum.example.com/agent/collector \
  --token-file ~/.netelum/agent.token

Ожидаемый ответ:

агент зарегистрирован и запущен: net.netelum.agent (pid 12345)
  лог:      /var/log/netelum/agent.log
  статус:   sudo launchctl print system/net.netelum.agent
  удаление: sudo /usr/local/netelum/uninstall.sh

После этого файл ~/.netelum/agent.token можно удалить: копия лежит в /usr/local/netelum/token и доступна только root. Дальше агент меняет токен в этом файле сам, см. Токены агентов.

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

sudo /usr/local/netelum/netelum-agent hostnet | grep -E 'ssid|bssid|identity'
sudo tail -5 /var/log/netelum/agent.log

Ожидается имя сети, адрес точки и "identity": "ok". На платформе в Настройки → Агенты устройство должно быть онлайн через минуту, а в Опыт → Точки доступа появиться под своей точкой.

Что видит сотрудник¶

В строке состояния – значок Netelum. В его меню сотруднику нужен один пункт: «Сообщить о проблеме…». Он открывает окно с одним необязательным полем; «Отправить» помечает эту минуту и передаёт жалобу агенту, пароль не спрашивается. Поддержка увидит жалобу в карточке устройства через минуту, а через две платформа сохранит по ней слепок момента (см. гайд пользователя, Слепки). Остальные пункты меню – для администратора: лог, диагностика, запуск и остановка агента.

Обновление¶

Новую версию ставят тем же способом – пакетом поверх. Регистрация и разрешение геолокации сохраняются, ничего заново вводить не нужно. Администратор может также нажать «Обновить» в строке устройства на Настройки → Агенты, и агент обновится сам, ход видно в раскрытии строки (см. Обновления агентов). Обновление на медленном канале не страшно: агент качает пакет кусками и после обрыва продолжает с места. Браузер при обновлении агента не перекачивается – только если релиз сменил его версию, и тогда агент принесёт новый сам (строки browser: в /var/log/netelum/agent.log).

Удаление¶

sudo /usr/local/netelum/uninstall.sh

Снимает агента и хелпер Wi-Fi, удаляет файлы и токен. Логи в /var/log/netelum остаются, разрешение геолокации в системных настройках тоже – оно пригодится при следующей установке.

Если что-то не так¶

Что видно	Что это значит	Что делать
`identity: denied`	разрешение геолокации не дано	шаг 4, включить в Системных настройках
`identity: no-session`	никто не залогинен на Mac или хелпер не запущен	войти в систему; посмотреть `~/Library/Logs/Netelum/wifi-helper.log`
`identity: unsupported`	агент поставлен без хелпера (старым скриптом)	поставить пакет поверх
секции `wifi` нет вовсе	Mac подключён по кабелю или Wi-Fi выключен	это нормально
в `agent.log` ответы `401`	токен неверный или отозван	«Выдать новый» в блоке «Токен» и повторить шаги 2 и 5
в `agent.log` ошибки соединения	нет доступа к платформе по HTTPS	проверить сеть, VPN, прокси

Логи: агент – /var/log/netelum/agent.log (нужен sudo), хелпер Wi-Fi – ~/Library/Logs/Netelum/wifi-helper.log, установщик – /var/log/install.log.