Как установить SSL-сертификат на Unifi Cloud Key

Это руководство содержит пошаговые инструкции о том, как установить SSL-сертификат на UniFi Cloud Key. Cloud Key запускает приложение UniFi Network на основе Java keystore, поэтому установка выполняется через SSH: вы собираете пакет PKCS#12 из вашего сертификата, приватного ключа и цепочки CA, затем импортируете его в keystore Cloud Key с помощью утилиты Java keytool и перезапускаете службу UniFi.

Создание кода CSR на UniFi Cloud Key

Запрос на подпись сертификата (CSR) — это блок закодированного текста, содержащий ваши контактные данные, такие как домен и организация. Каждый заявитель должен сгенерировать CSR и отправить его в удостоверяющий центр (CA) для проверки, прежде чем сертификат может быть выпущен. Для Cloud Key общее имя (common name) в CSR должно быть именем хоста, которое вы используете для доступа к контроллеру, например unifi.yoursite.com.

У вас есть два варианта:

• Использовать наш генератор CSR для автоматического создания CSR.
• Следовать нашему пошаговому руководству о том, как сгенерировать CSR на UniFi Cloud Key.

Вы можете открыть файл CSR в любом текстовом редакторе, например Notepad, и вставить его в процессе заказа сертификата у вашего поставщика SSL. Сохраните соответствующий приватный ключ в надежном месте: он снова понадобится вам на шаге 3 для создания пакета PKCS#12. После того как CA проверит ваш запрос и отправит по электронной почте файлы SSL, продолжайте установку, описанную ниже.

Установка SSL-сертификата на UniFi Cloud Key

Cloud Key предоставляет HTTPS из Java keystore, расположенного по пути /usr/lib/unifi/data/keystore. По умолчанию этот keystore содержит самоподписанный сертификат под псевдонимом (alias) unifi, защищённый паролем aircontrolenterprise. Чтобы установить собственный сертификат, вы заменяете эту запись: собираете свои файлы в архив PKCS#12, импортируете его под тот же псевдоним, а затем перезапускаете службу UniFi. Работа выполняется через SSH, поэтому сначала подключитесь к Cloud Key (по умолчанию пользователь SSH — root на Gen1, или учётная запись администратора, которую вы задали во время подключения на Gen2).

Шаг 1: Подготовьте файлы SSL

Проверьте свою почту и загрузите ZIP-архив, содержащий ваш сертификат. Распакуйте его. В зависимости от вашего поставщика SSL у вас должны быть некоторые или все из следующих файлов:

• Основной SSL-сертификат (сертификат вашего сервера).
• Промежуточный SSL-сертификат.
• Корневой SSL-сертификат.
• CA bundle — единый файл, который уже содержит корневой и промежуточный сертификаты.

Вам также понадобится приватный ключ, который вы сгенерировали вместе с CSR. Если вы использовали наш генератор CSR, ключ был предложен для скачивания в тот момент.

Шаг 2: Скопируйте файлы SSL на Cloud Key

Загрузите свои файлы на Cloud Key через SCP или SFTP и поместите их в каталог /etc/ssl/private/. Используйте следующие имена, чтобы они соответствовали командам из следующих шагов:

• Основной сертификат как /etc/ssl/private/cloudkey.crt
• Приватный ключ как /etc/ssl/private/cloudkey.key
• CA bundle (корневой и промежуточный) как /etc/ssl/private/yourcaname.crt

Примечание: каждый файл PEM должен заканчиваться символом новой строки после последней строки. Последняя строка сертификата — это ровно пять дефисов, слова END CERTIFICATE, затем пять дефисов (——END CERTIFICATE——); убедитесь, что после неё стоит разрыв строки. Отсутствие завершающего перевода строки является частой причиной ошибок импорта.

Шаг 3: Соберите сертификат в файл PKCS#12

Объедините приватный ключ, основной сертификат и CA bundle в единый файл PKCS#12. Псевдоним должен быть unifi, поскольку именно этот псевдоним ожидает keystore UniFi. Замените enteryourpassword на пароль по вашему выбору и запомните его: тот же пароль вы передадите keytool на шаге 4 как исходный (source) пароль.

openssl pkcs12 -export -in /etc/ssl/private/cloudkey.crt -inkey /etc/ssl/private/cloudkey.key -out /etc/ssl/private/cloudkey.p12 -name unifi -CAfile /etc/ssl/private/yourcaname.crt -caname root -password pass:enteryourpassword

Эта команда создаёт файл /etc/ssl/private/cloudkey.p12, содержащий ключ, ваш сертификат и цепочку — всё под псевдонимом unifi.

Шаг 4: Импортируйте файл PKCS#12 в keystore Cloud Key

Импортируйте файл PKCS#12 в существующий keystore по пути /usr/lib/unifi/data/keystore. Целевой keystore уже использует пароль aircontrolenterprise, поэтому пароли целевого хранилища и ключа должны оставаться aircontrolenterprise. Исходный пароль — тот, который вы установили для файла PKCS#12 на шаге 3.

keytool -importkeystore -deststorepass aircontrolenterprise -destkeypass aircontrolenterprise -destkeystore /usr/lib/unifi/data/keystore -srckeystore /etc/ssl/private/cloudkey.p12 -srcstoretype PKCS12 -srcstorepass enteryourpassword -alias unifi

Если keytool сообщает, что псевдоним unifi уже существует, это относится к стандартной самоподписанной записи. Подтвердите перезапись, когда система спросит, или сначала удалите старую запись с помощью команды ниже, а затем повторно выполните импорт:

keytool -delete -alias unifi -keystore /usr/lib/unifi/data/keystore -storepass aircontrolenterprise

Важно: не меняйте пароль keystore на собственное значение. Служба UniFi жёстко запрограммирована открывать keystore с паролем aircontrolenterprise; если вы измените его, контроллер не сможет прочитать сертификат, и HTTPS не будет работать.

Шаг 5: Настройте права доступа и удалите временные файлы

Ужесточите права владения и доступа к файлам в каталоге /etc/ssl/private/, чтобы приватный ключ был недоступен для чтения всем пользователям, а затем удалите промежуточные файлы, которые больше не нужны. Выполните эти команды по очереди:

chown root:ssl-cert /etc/ssl/private/*
chmod 640 /etc/ssl/private/*
rm /etc/ssl/private/cloudkey.p12

Теперь сертификат находится внутри keystore, поэтому файл PKCS#12 больше не нужен. Если вы также загружали CSR или файл CA только для этого процесса, их также можно удалить:

rm /etc/ssl/private/cloudkey.csr
rm /etc/ssl/private/yourcaname.crt

Совет: перед перезапуском вы можете сделать резервную копию keystore, чтобы иметь возможность откатиться при необходимости. Находясь внутри каталога /usr/lib/unifi/data/, архивируйте его командой tar -cvf keystore-backup.tar keystore.

Шаг 6: Приведите имя хоста контроллера в соответствие с сертификатом

Чтобы браузеры доверяли сертификату без предупреждения о несоответствии имени, установите имя хоста или IP-адрес контроллера в соответствии с именем в сертификате. В приложении UniFi Network перейдите в Settings > System (в старых версиях: Settings > Controller) и укажите в поле Controller Hostname/IP общее имя (common name) вашего сертификата, например unifi.yoursite.com. Убедитесь, что это имя хоста разрешается на Cloud Key в вашей системе DNS.

Шаг 7: Перезапустите службу UniFi

Новый сертификат считывается только при запуске службы UniFi, поэтому перезапустите её, чтобы загрузить сертификат:

service unifi restart

На более новых версиях прошивки Cloud Key, использующих systemd, эквивалентная команда выглядит так:

systemctl restart unifi

Подождите минуту, пока служба снова запустится, затем обновите страницу контроллера в браузере. Поздравляем, ваш SSL-сертификат теперь установлен на вашем UniFi Cloud Key.

Проверка установки SSL

После установки сертификата проверьте конфигурацию на наличие ошибок или уязвимостей, таких как отсутствующий промежуточный сертификат или недоверенная цепочка. Используйте наш SSL Checker для мгновенного сканирования и получения отчёта. Поскольку контроллер UniFi обычно прослушивает порт 8443, укажите в проверке полный адрес, например unifi.yoursite.com:8443. Вы также можете подтвердить результат из командной строки:

echo | openssl s_client -connect unifi.yoursite.com:8443 -servername unifi.yoursite.com 2>/dev/null | openssl x509 -noout -issuer -dates

Эта команда выводит издателя сертификата и сроки его действия, чтобы вы могли убедиться, что Cloud Key использует ваш сертификат, а не старый самоподписанный.

Часто задаваемые вопросы