Home Assistant OS – специализированная операционная система на базе Linux. Применяется (в том числе) как система мониторинга и автоматизации для отображения состояния ИБП, получения уведомлений и выполнения автоматических действий при событиях NUT.

Схема подключения.

 

Установка Home Assistant на Proxmox.

Рассматривается установка в виде отдельной виртуальной машины. Для критичной инфраструктуры это наиболее надежный вариант и более простые настройки.

Альтернатива – можно развернуть в Docker-контейнере. Такой вариант требует меньше ресурсов, однако лишен Supervisor и системы Add-ons, поэтому большинство настроек выполняется вручную.

Home Assistant OS поставляется как готовый виртуальный диск, который можно подключить к виртуальной машине. Скачать последнюю версию KVM можно с официального сайта.

 

Импортируем скаченный диск в Proxmox.

 

Создаем виртуальную машину.

Проходим по мастеру в GUI или выполняем команду в CLI.

Если сеть использует VLAN, то нужно указать ID.

 

Импортируем диск.

 

Выбираем источник, назначение и образ диска.

Через CLI.

Указывать нужно свои параметры хранения.

 

Если диск загружался в Proxmox другим способом, то найти его можно командой:

 

Уточнить название хранилища в Proxmox можно командой:

 

Подключаем импортированный диск.

 

Добавляем EFI-диск.

 

Включаем загрузку с диска.

 

Включаем QEMU Agent.

 

Запускаем ВМ.

 

Через несколько минут открываем в браузере.

и проходим мастер первоначальной настройки.

 

Мастер первоначальной настройки.

 

Создаем пользователя.

 

Мастер короткий. Готово.

 

Настройка доступа по SSH.

Для доступа по SSH устанавливаем приложение Terminal & SSH.

 

В поиске вводим SSH.

 

Устанавливаем и запускаем.

 

Для подключения по SSH используется отдельная учетная запись, настраиваемая в конфигурации аддона.

Вводим пароль, перезапускаем.

Использование SSH-ключей считается предпочтительным методом. Настраивается сложнее.

SSH-аддон и интерфейс Home Assistant используют разные системы пользователей. Пользователь из веб-интерфейса (созданный при  настройке HA) существует только в самом Home Assistant Core и не имеет отношения к SSH-аддону.

 

Так же настраиваем порт. Можно указать стандартный.

Подключение выполняем через Putty, MobaExterm или аналогичные терминалы.

По умолчанию аддон «Terminal & SSH» использует пользователя root.

 

Подключаемся с установленным выше паролем.

 

Проброс USB-порта.

Передача данных между ИБП и ВМ должна осуществляться напрямую через USB-кабель. Для этого необходимо прокинуть USB-порт в виртуальную машину.

Это типовая задача, и решается она проще через интерфейс веб-панели Proxmox.

 

Перезагружаем ВМ.

Через CLI.

Просматриваем список USB-устройств.

 

Пробрасываем порт.

 

Проверяем.

 

Проверяем в HA.

Представленная модель ИБП не является последовательным USB-устройством. Он определяется как USB HID (Human Interface Device), примерно так же, как клавиатура или мышь.

USB передан в Home Assistant.  Но пока никакой драйвер внутри Home Assistant с ним не взаимодействует.

 

Компоненты настройки.

Аддон NUT – взаимодействует с ИБП по USB и предоставляет данные как NUT-сервер.

Интеграция NUT – подключается к этому серверу и создает в Home Assistant объекты (Статус, Входное напряжение, Заряд аккумулятора и т.д.).

Автоматизации Home Assistant – используют эти объекты для отправки уведомлений и выполнения действий.

Выполним настройку всех этих компонентов.

 

Аддон NUT.

При использовании этого аддона, Home Assistant становится NUT-сервером и предоставляет данные другим клиентам. По сравнению с обычным консольным NUT в данном варианте появляются возможности автоматизации без написания shell-скриптов.

Устанавливаем аддон из меню приложений.

 

 

Находим через поиск по названию NUT и устанавливаем.

 

Настройка пользователя NUT.

Создаем учетную запись, используемую клиентами для подключения к серверу NUT и получения данных об ИБП. Придумываем имя пользователя и пароль.

username – имя пользователя, которым клиент (например, интеграция Home Assistant NUT) подключается к серверу NUT.

password – пароль пользователя.

device – имя ИБП, заданное в настройках аддона.

driver – драйвер NUT для обмена данными с ИБП. Для большинства совместимых USB-ИБП используется nutdrv_qx.

primary – предоставляет клиенту права основного (primary) клиента NUT. Home Assistant подключается именно с этой учетной записью и получает доступ к состоянию ИБП.

 

В последствии, созданные учетные данные затем будут использованы в настройке интеграции NUT.

 

Просмотр настройки в CLI.

Сначала определим идентификатор (slug) установленного дополнения.

В списке будет отображаться идентификатор дополнения, например: a0d7b954_nut.

 

Затем используем его для просмотра полной конфигурации.

 

Только options.

instcmds:  -all означает разрешить этому пользователю выполнять любые instant-команды, которые поддерживает драйвер. То есть all здесь = все команды.

shutdown_host: false – NUT не будет выключать сам Home Assistant OS.

shutdown_host: true – при критическом разряде батареи NUT выключит Home Assistant OS.

При первоначальных тестах рекомендуется отключить (false) эту настройку, после ввода в работу включить.

Настройки Add-on не хранятся в обычном YAML-файле, который можно открыть через nano. Они находятся в базе данных Supervisor и их редактирование доступно только через GUI.

Нажимаем сохранить, и далее программа предложит запустить аддон. Или запускаем вручную на кнопку.

 

Если запуск не происходит, нужно посмотреть логи и устранить причину. Например, в данном случае не подошел пароль Pass-135. Нужно вводить более сложный безопасный пароль.

driver is now connected – означает, что драйвер полностью подключился к ИБП.

 

Интеграция для аддона NUT.

Интеграция NUT – это компонент Home Assistant, который подключается к NUT-серверу (например, аддону NUT или отдельному серверу NUT) по сетевому протоколу и получает информацию об ИБП. На основании полученных данных в Home Assistant создаются объекты (сенсоры), которые можно использовать в автоматизациях, уведомлениях и сценариях.

 

Добавляем интеграцию NUT.

 

Заполняем конфигурацию.

a0d7b954_nut – внутреннее имя аддона NUT в сети Home Assistant. Используется при подключении интеграции к аддону, установленному на том же экземпляре Home Assistant.

localhost (127.0.0.1) в Home Assistant Core указывает на контейнер Home Assistant Core. NUT Add-on работает в отдельном контейнере. Контейнеры взаимодействуют между собой по внутренней сети Supervisor, используя имена контейнеров, например a0d7b954_nut. Поэтому если в параметрах подключения указать  localhost или 127.0.0.1, то подключение может завершиться ошибкой.

Если NUT-сервер установлен на другом устройстве (например, на Proxmox), вместо a0d7b954_nut необходимо указать его IP-адрес или DNS-имя.

Порт: 3493 – стандартный TCP-порт NUT.

Имя пользователя и пароль созданные выше.

Подтверждаем.

 

В списке появится новое устройство. Можно посмотреть данные, которые начинают поступать от ИБП.

Интеграция может работать без установки аддона только в режиме мониторинга ИБП. В этом случае интеграция аналогична роли клиента NUT, через которого можно просматривать состояние ИБП без возможности управления.

 

Оповещение по email.

Добавляем интеграцию SMTP.

Настройки >> Устройства и службы >> Добавить интеграцию >> SMTP.

 

 

Заполняем поля, подтверждаем.

Sender email: ваш_ящик@yandex.ru – адрес электронной почты, от имени которого будут отправляться уведомления.

Sender name: Home Assistant – имя отправителя, отображаемое в почтовом клиенте получателя.

Host: smtp.yandex.ru – адрес SMTP-сервера почтового провайдера.

Port: 465 – порт SMTP-сервера для защищенного соединения SSL/TLS.

Connection security: TLS – тип защищенного соединения с SMTP-сервером.

Username: ваш_ящик@yandex.ru – имя пользователя для аутентификации на SMTP-сервере.

Password: xxx – пароль приложения Яндекса

Verify SSL certificate: Да – проверка SSL-сертификата SMTP-сервера.

 

После сохранения интеграция попросит добавить первого получателя (Recipient). Это может быть тот же самый адрес электронной почты.

При необходимости можно зайти в настройки SMTP и добавить еще получателей.

 

Проверка.

Проверку отправки выполняем через инструменты разработчика.

 

В действиях выбираем «Отправить сообщение уведомления». Выбираем получателя.

 

Вводим сообщение и заголовок. Нажимаем кнопку «Выполнить действие».

 

При корректной настройке SMTP сообщение будет отправлено на указанный адрес электронной почты.

 

Оповещение при пропадании электропитания.

Переходим в «Автоматизации и сцены».

 

Создаем новую автоматизацию.

 

Добавляем триггер.

 

Выбираем тип триггера – «Состояние».

 

Меняем тип триггера на «Данные о состоянии».

В поле «На» указываем значение OB (On Battery). Автоматизация будет срабатывать при переходе ИБП на питание от аккумулятора.

 

 

Настраиваем действие.

 

Добавляем действие типа «Отправить сообщение уведомления».

 

Выбираем настроенного получателя и заполняем тему и текст сообщения. В текст можно добавить текущие дату и время.

В Home Assistant используется шаблонизатор Jinja2, который позволяет динамически формировать текст уведомлений, автоматизаций и сценариев. Специальная конструкция, заключается в двойные фигурные скобки.

Например.

 

Для проверки отключаем питание ИБП от сети 220 В. После перехода ИБП в состояние OB на указанный адрес электронной почты должно поступить уведомление.

 

Контролировать выполнение автоматизации можно в трассировке.

 

 

​

 

Отключение Proxmox по событию.

Последовательность действий.

В ИБП наступает статус LB (низкий уровень заряда) >> Статус поступает в интеграцию >> Автоматизация отправляет письмо о том, что начинается завершение работы. >> Отправка команды shutdown в Proxmox. >> Proxmox завершает работу ВМ HA и затем выключается сам.

 

Доступ в Proxmox через API-токен.

Подключение в Proxmox через токен это наиболее простой и надежный способ.

Создадим пользователя, токен и права для него. После этого добавим в Home Assistant службу Proxmox с указанием созданного токена.

 

Пользователь.

Создание отдельного пользователя для API-токена позволяет предоставить Home Assistant только необходимые разрешения для управления Proxmox, не используя учетную запись root. Такой подход повышает безопасность системы и соответствует принципу минимально необходимых привилегий.

 

Вводим логин, пароль, realm.

Realm – источник аутентификации пользователя. Определяет, где хранится учетная запись и каким способом выполняется вход в Proxmox.

Proxmox VE authentication server (PVE) – локальная база пользователей Proxmox. Рекомендуется для создания служебных учетных записей и API-токенов.

 

Роль.

Создаем отдельную роль, с правами только управлять электропитанием.

 

Выбираем последовательно в поле Privileges две роли: Sys.Audit и Sys.PowerMgmt.

 

Разрешения для пользователя.

 

 

Токен.

API-токен – специальный ключ доступа, создаваемый для учетной записи Proxmox. Он позволяет внешним приложениям (например, Home Assistant) безопасно выполнять запросы к API от имени пользователя, не используя его пароль. Права API-токена определяются назначенными ему разрешениями (ACL).

 

ha-api@pve – пользователь, которому принадлежит токен.

shutdown – имя (ID) токена, задаваемое при его создании.

Privilege Separation – режим разделения прав между пользователем и его API-токенами. Если включен, API-токен не наследует права пользователя и должен получать собственные разрешения (ACL). Если отключен, токен автоматически использует все права своего владельца.

Privilege Separation рекомендуется оставить включенной. В этом случае API-токен получает только явно назначенные ему разрешения, что соответствует принципу минимально необходимых привилегий и повышает безопасность системы.

Даже если пользователь ha-api в будущем получит дополнительные права, токен продолжит обладать только теми разрешениями, которые были назначены непосредственно ему.

При включенной опции Privilege Separation права должны быть назначены и пользователю, и API-токену. Если права есть только у токена, эффективные разрешения будут пустыми.

 

Секрет (Token Secret) отображается только один раз при создании токена и используется вместе с его именем для аутентификации запросов к API.

Сохраняем Token Secret где-то у себя в компьютере.

 

Разрешения для токена.

 

Токен не может иметь больше прав, чем его пользователь при включенной опции Privilege Separation. Поэтому мы задали одинаковые разрешения для токена и пользователя.

 

Просмотр настройки в CLI.

 

Проверка.

(нужно указать свой токен)

 

Должен вернуться JSON со статусом узла.

 

Настройка подключения к Proxmox в HA.

Добавляем интеграцию.

Настройки >> Устройства и службы >> Добавить интеграцию >> Proxmox.

 

 

Вводим параметры подключения.

Authentication method – Proxmox VE authentication server (PVE). Определяет источник аутентификации пользователя. Используется локальная база пользователей Proxmox (@pve).

Хост IP-адрес или DNS-имя сервера Proxmox VE, к которому будет подключаться Home Assistant.

Имя пользователя: ha-api – имя ранее созданного пользователя Proxmox без указания Realm.

Порт: 8006 – порт веб-интерфейса и API Proxmox VE.

Use an API token –включаем данный параметр для аутентификации с помощью API-токена вместо пароля пользователя.

Проверять сертификат SSL – проверяет подлинность SSL-сертификата сервера Proxmox. Если используется самоподписанный сертификат (стандартная установка Proxmox), проверку обычно отключают. При использовании сертификата от доверенного центра сертификации рекомендуется оставить проверку включенной.

 

Проверяем.

Заходим в созданную интеграцию и нажимаем кнопку Shut Down.

 

ВМ и Proxmox выполняют завершение работы.

 

Автоматизация завершения работы.

Добавляем новую автоматизацию завершения работы при статусе LB.

 

 

Выбираем данные о состоянии.

В поле «На» указываем значение LB (Low Battery).

 

Создаем три действия.

Действие №1 – отправка уведомления.

 

 

Указываем получателя и текст сообщения.

Тема

⚠ Завершение работы Proxmox.

Сообщение

 

Действие №2 – задержка.

Добавляем действие «Задержка» и установите время 20 секунд. Это позволяет гарантировать отправку сообщения до начала завершения работы ВМ Home Assistant и Proxmox.

 

Находим задержку в поиске.

 

Выставляем значение, например 20сек.

Сохраняем.

 

Действие №3 – нажатие кнопки «Shut down».

Добавляем действие.

 

Находим и выбираем кнопку Proxmox.

 

 

Результат настройки.

В Home Assistant действия выполняются сверху вниз в том порядке, в котором они расположены в автоматизации. Никаких дополнительных настроек для последовательного выполнения не требуется.

Если нужно изменить порядок, используется кнопка перетягивания действия вверх/вниз в редакторе автоматизации.

 

Всю полученную конструкцию можно посмотреть в текстовом редакторе через меню … (три точки >> Текстовый редактор).

 

 

Проверка.

В редакторе автоматизации нажимаем «Выполнить». Это проверит последовательность действий, но сразу выключит Proxmox (это следует учитывать).

 

Контролировать выполнение можно в трассировке.

Перед использованием рекомендуется проверить, какое значение передает реальный ИБП при разряде аккумулятора. Некоторые модели формируют статус LB, другие – OB LB. Если сенсор возвращает OB LB, рекомендуется использовать шаблонную проверку на наличие LB, а не точное сравнение со значением LB. Или подождать разряда АКБ чтоб увидеть точный статус.

 

Итог.

Использование Home Assistant в качестве системы мониторинга ИБП обеспечивает значительно более удобное управление по сравнению с работой напрямую через NUT. Большинство настроек выполняется через графический интерфейс, без редактирования конфигурационных файлов и использования командной строки. Кроме того, Home Assistant позволяет легко создавать автоматизации, отправлять уведомления, интегрировать различные устройства и централизованно контролировать состояние инфраструктуры. В дальнейшем это упрощает сопровождение системы.

При этом необходимо учитывать и мириться с тем, что Home Assistant работает в отдельной виртуальной машине, которая завершает работу вместе с гипервизором Proxmox VE на котором она же и установлена. Можно использовать докер или что-то еще, но это уже другая история.