Тип статьи	Инструкция
Компетенции	Администратор
Необходимые права	root
Версия платформы	2.19.1/2.20
Статус	БЕТА
Сложность	легко
Полезные ссылки	https://certbot.eff.org/docs/using.html?highlight=hook#renewing-certificates
Дополнительные сведения	Ubuntu 18.04/20.04, certbot 0.27.0/0.40.0, без внешнего proxy-сервера

При устаревании инструкции используйте описанные в ней подходы и более свежие знания в документации актуальной версии платформы и certbot. Вы также всегда можете написать на support@visiology.su с запросом о помощи или замечанием по инструкции.

Введение

Данная инструкция поможет настроить на сервере с платформой автоматический перевыпуск сертификата с помощью certbot.

У данного метода есть свои подводные камни (о них ниже), но он достаточно прост в реализации.

1. Вводные данные

Настройка происходит на виртуальной машине Ubuntu Server 20.04 x64.

Железо типовое и соответствует системным требованиям платформы для целей тестирования (см. статью системные требования).

Нет никаких дополнительных усложняющих факторов в виде настроенных VPN, работающих прокси серверов или файрволлов. Имеем простую подсеть вида 192.168.0.0/24, стандартные докер подсети и полностью типовую настройку работы платформы 2.20 на HTTP на одном сервере.

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

2. Установка certbot

Выполняем следующие команды:

sudo apt update
sudo apt install certbot

Далее необходимо создать аккаунт ACME:

sudo certbot register --email email@server.com

Вместо email@server.com вписываем свой email. В процессе регистрации будет задано 2 вопроса. Первый – это согласие на использование сервиса Let’s Encrypt :

certbot register --email muba4@yandex.ru
Saving debug log to /var/log/letsencrypt/letsencrypt.log

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Please read the Terms of Service at
https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf. You must
agree in order to register with the ACME server at
https://acme-v02.api.letsencrypt.org/directory
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(A)gree/(C)ancel: A

И второй это согласие на новостную рассылку:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Would you be willing to share your email address with the Electronic Frontier
Foundation, a founding partner of the Let's Encrypt project and the non-profit
organization that develops Certbot? We'd like to send you email about our work
encrypting the web, EFF news, campaigns, and ways to support digital freedom.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Y)es/(N)o: Y

На этом установка закончена.

3. Pre-hook и Post-hook скрипты

Т.к. мы будем использовать certbot standalone веб-сервер для аутентификации, необходимо освободить 80 порт, чтобы let’sencrypt мог проверить, что домен принадлежит именно нам. 80 порт у нас занят nginx'ом (это компонент proxy платформы). Это тот самый подводный камень, о котором мы писали во введении. Решить эту проблему просто: остановкой контейнера proxy через pre-hook скрипт.

Сами скрипты ниже:

preScript.sh:

docker service scale visiology_proxy=0
sleep 15

В этом скрипте мы останавливаем контейнер proxy для освобождения 80 порта и ждем 15 секунд, пока порт полностью не освободится.

Для платформ 2.30 и выше используем такой вариант скрипта:

docker service scale visiology_reverse-proxy=0
sleep 15

postScript.sh:

sudo cp -f -H /etc/letsencrypt/live/<domainName>/fullchain.pem /docker-volume/proxy/
sudo cp -f -H /etc/letsencrypt/live/<domainName>/privkey.pem /docker-volume/proxy/
sudo chmod 777 /docker-volume/proxy/fullchain.pem
sudo chmod 777 /docker-volume/proxy/privkey.pem
sudo docker service scale visiology_proxy=1

1 и 2 строка. Копирование сертификата (с полной цепочкой) и приватного ключа из папки источника (куда certbot по умолчанию кладет сгенерированные сертификаты) в папку /docker-volume/proxy/. <domainName> - изменить на свое имя домена;
3 и 4 строка. В нашем случае пришлось дать права на сертификат и ключ, т.к. nginx ругался на отсутствие доступа к файлам;
5 строка. Запускаем контейнер proxy.

Для платформ 2.30 и выше используем такой вариант скрипта:

sudo cp -f -H /etc/letsencrypt/live/example.visiology.su/privkey.pem /docker-volume/proxy/
sudo cp -f -H /etc/letsencrypt/live/example.visiology.su/privkey.pem /var/lib/visiology/certs/privatekey.key
sudo cp -f -H /etc/letsencrypt/live/example.visiology.su/fullchain.pem /docker-volume/proxy/
sudo cp -f -H /etc/letsencrypt/live/example.visiology.su/fullchain.pem /var/lib/visiology/certs/certificate.crt
sudo chmod 777 /docker-volume/proxy/fullchain.pem
sudo chmod 777 /docker-volume/proxy/privkey.pem
sudo chmod 777 /var/lib/visiology/certs/certificate.crt
sudo chmod 777 /var/lib/visiology/certs/privatekey.key
sudo docker service scale visiology_reverse-proxy=1

Скрипт preScript.sh можно положить в папку /etc/letsencrypt/renewal-hooks/pre, а postScript.sh в папку /etc/letsencrypt/renewal-hooks/post. Скрипты, которые лежат в этих папках запускаются каждый раз при запуске команды certbot renew (перевыпуск сертификата). При выполнении других команд они не запускаются. Т.е. при выпуске сертификата командой certbot certonly данные скрипты не сработают и нам надо будет ручками останавливать сервис прокси и затем копировать сертификаты. Поэтому мы поступим по-другому.

Мы положим наши скрипты в папку /etc/letsencrypt/ и затем вызовем их оттуда при выпуске сертификата. Тогда они отработают и ручками нам уже ничего делать не надо. К тому же будет создан конфиг в папке /etc/letsencrypt/renewal/, который будет содержать информацию о наших скриптах и в будущем при запуске команды certbot renew они будут срабатывать.

Сделаем скрипты исполняемыми и изменим права:

cd /etc/letsencrypt/
sudo chmod 777 ./preScript.sh
sudo chmod 777 ./postScript.sh
sudo chmod +x ./preScript.sh
sudo chmod +x ./postScript.sh

4. Выпуск сертификата

Теперь можно приступить непосредственно к выпуску сертификата. Выполняем следующую команду:

sudo certbot certonly --standalone -d <domainName> --pre-hook /etc/letsencrypt/preScript.sh --post-hook /etc/letsencrypt/postScript.sh

<domainName> изменить на своё.

В результате выполнения данной команды будет сделано следующее:

1. Запущен pre-hook скрипт, который остановит докер контейтнер proxy и освободит 80 порт.

2. Выпущены сертификаты и ключ (/etc/letsencrypt/live/<domainName>/):
- privkey.pem - приватный ключ для сертификата;
- cert.pem - только сертификат сервера;
- chain.pem - все сертификаты, которые необходимо предоставить браузеру, кроме сертификата сервера, т.е. только корневой (root) и промежуточные (intermediate) сертификаты;
- fullchain.pem - все сертификаты, включая сертификат сервера. Это объединение chain.pem и cert.pem. Именно этот файл нам и нужен.
Также будет создан конфиг для перевыпуска сертификата, он лежит в папке /etc/letsencrypt/renewal/ , он будет включать в себя информацию о pre-hook и post-hook скриптах, которые мы указали в команде при выпуске сертификата.

3. Запущен post-hook скрипт, который скопирует сертификат и ключ в папку /docker-volume/proxy/, выдаст права на них и запустит докер контейнер proxy.

Задача о перевыпуске сертификата создается в кроне автоматически (/etc/cron.d/certbot) при установке certbot. Она запускается дважды в сутки и перевыпускает те сертификаты, срок действия которых истекает в течение тридцати дней. Если необходимо четко указать время для проверки истекающих сертификатов, то изменить расписание можно в файле /etc/cron.d/certbot. При перевыпуске будут учтены конфиги, которые лежат в папке /etc/letsencrypt/renewal/.

5. Переключение и настройка HTTPS

После того как мы выпустили сертификат, необходимо настроить платформу для работы через HTTPS. Это можно сделать, следуя стандартной инструкции по переключению платформы в режим работы по HTTPS. Но есть некоторые отличия, они описаны в заметке ниже до ссылки.

Уточнения к инструкции по настройке HTTPS

Пункты 5 и 6 не делаем совсем. Файл с паролем нам не нужен, а сертификат и ключ в папку /docker-volume/proxy скопировал скрипт postScript.sh в предыдущем шаге данной инструкции.
В 7 мы указываем путь и имя до сертификата, ключа и файла с паролем. Файл с паролем нам не нужен, эту строчку можно оставить закомментированной. А путь и имя до сертификата и ключа написать так, как указано ниже:

ssl_certificate     /mnt/volume/fullchain.pem;
ssl_certificate_key /mnt/volume/privkey.pem;

Настройка платформы для работы через HTTPS - Случай 2. Сертификат, подписанный доверенным центром сертификации

Готово. После перезапуска платформы с ключом "--https on", она начинает работать через одноимённый протокол используя наш Let'sEncrypt сертификат, который будет автоматически перевыпускаться (с запусков prehook и posthook скриптов) при истечении срока годности.

Браузер не поддерживается