Перейти к основному содержимому

Справочник по конфигурации

Поведение clmBot управляется файлом конфигурации config.yaml в каталоге установки. Этот файл автоматически создаётся при выполнении login, discover-certificate или add-server, его также можно редактировать вручную.

По умолчанию clmBot считывает config.yaml из текущего каталога, также можно указать путь к файлу конфигурации через глобальный параметр -c:

./clm-bot-linux-amd64 -c /opt/clm-bot/config.yaml update-certificate

Общая структура​

app:
base_url: https://<云端地址>
ignore_ssl: false
access_key: YOUR_ACCESS_KEY
access_secret: YOUR_ACCESS_SECRET

servers:
- id: nginx_pem
sub_code: <证书订阅号>
format:
pem:
cert_path: /etc/nginx/ssl/example.com.crt
ca_path: /etc/nginx/ssl/example.com.ca.crt
key_path: /etc/nginx/ssl/example.com.key
before_script: |
...
after_script: |
nginx -t && nginx -s reload

app:подключение и настройка​

ПолеОписание
base_urlАдрес облачного API, заполняется согласно информации о поставке, обычно изменений не требуется
ignore_sslСледует ли игнорировать проверку HTTPS-сертификата. Включайте только в контролируемой среде с самоподписанными сертификатами
access_keyAccessKey, выданный облаком
access_secretAccessSecret, выданный облаком. После первого сохранения открытого текста программой он автоматически преобразуется в зашифрованное значение с префиксом ENC1+

servers:список точек установки​

Каждая запись servers[] соответствует одной точке установки сертификата:

ПолеОписание
idИдентификатор точки установки, рекомендуется использовать осмысленное с точки зрения бизнеса имя
sub_codeНомер подписки на сертификат, соответствует подписке на сертификат в административной панели, clmBot получает по нему актуальный сертификат
formatФормат сертификата и путь к файлу, можно указать только один из вариантов: pem, pfx, jks, iis, exchange
before_scriptСкрипт, выполняемый перед обновлением; если скрипт завершится с ошибкой, обновление на данном узле установки будет прервано
after_scriptСкрипт, выполняемый после обновления; обычно используется для перезагрузки служб промежуточного ПО

format: формат сертификата​

pem​

Подходит для сценариев использования PEM-файлов, например nginx, Apache HTTP Server, Tomcat:

ПолеОписание
cert_pathПуть к файлу сертификата сайта. При обновлении записывается листовой сертификат; если ca_path пусто, одновременно записывается полная цепочка сертификатов
ca_pathПуть к файлу цепочки CA, может быть пустым
key_pathПуть к файлу закрытого ключа

pfx​

Подходит для сервисов, которым требуется единый файл пакета сертификатов (PKCS#12):

ПолеОписание
pathПуть к PFX-файлу
key_passПароль закрытого ключа PFX; можно оставить пустым, если целевой сервис не требует пароль

jks​

Подходит для сценариев Java keystore, например Tomcat:

ПолеОписание
pathПуть к JKS-файлу
aliasПсевдоним записи сертификата. Если пусто, может быть определён автоматически только когда в keystore есть единственная запись
key_passПароль закрытого ключа записи
store_passПароль keystore

iis​

Подходит для привязки Windows IIS HTTPS:

ПолеОписание
nameИмя сайта IIS, можно посмотреть в диспетчере IIS
addrIP привязки HTTPS, * означает все IP
portПорт привязки HTTPS
domainДомен привязки HTTPS, можно оставить пустым при отсутствии домена SNI

Точка установки IIS автоматически выполняет импорт сертификата и обновление привязки с помощью встроенного скрипта clmBot, обычно настройка скрипта не требуется.

exchange​

Подходит для сертификата службы Windows Exchange:

ПолеОписание
servicesСписок имен служб Exchange, для которых необходимо активировать новый сертификат, например ["IIS", "SMTP", "POP", "IMAP"]

Примечания по выполнению скрипта​

before_script и after_script выполняются при обновлении сертификата в следующем порядке:

  1. Попытка создать резервную копию локального файла сертификата (создается резервная копия .bak с меткой времени); при ошибке резервного копирования ошибка записывается в журнал и выполнение продолжается.
  2. Выполнение before_script; при ошибке обновление текущей точки установки прерывается.
  3. Запись нового сертификата.
  4. Выполнение after_script согласно конфигурации; скрипт отвечает за перезагрузку или перезапуск служб промежуточного ПО.

Когда локальный сертификат уже обновлён, весь процесс обновления (включая скрипт) будет пропущен; для принудительного выполнения after_script можно использовать параметр --force-after.

На Linux скрипт выполняется через bash, на Windows — через powershell.exe -NoProfile -ExecutionPolicy Bypass.

Переменные шаблона скрипта​

При написании before_script / after_script можно использовать следующие переменные шаблона. clmBot заменит их фактическими значениями перед выполнением.

Общие переменные:

ПеременнаяОписание
{{ .ID }}Точка установки id
{{ .SUB_CODE }}Номер подписки на сертификат
{{ .OS_TYPE }}Тип операционной системы (windows / linux / darwin)
{{ .IS_WINDOWS }}Является ли Windows (true / false)
{{ .IS_LINUX }}Является ли Linux (true / false)
{{ .TIMESTAMP }}Текущая метка времени (секунды)
{{ .DATETIME }}Текущие дата и время (формат 2006-01-02 15:04:05)
{{ .DATE }}Текущая дата (формат 2006-01-02)
{{ .LATEST }}Сертификат уже актуален (true / false). При использовании вместе с --force-after можно в скрипте определить пропуск последующих операций

Переменные, предоставляемые по формату сертификата:

ФорматПеременнаяОписание
pem{{ .PEM_CERT_PATH }}Путь к файлу сертификата сайта
pem{{ .PEM_CA_PATH }}Путь к файлу цепочки CA
pem{{ .PEM_KEY_PATH }}Путь к файлу закрытого ключа
pfx{{ .PFX_PATH }}Путь к PFX-файлу
pfx{{ .PFX_KEY_PASS }}Пароль закрытого ключа PFX
jks{{ .JKS_PATH }}Путь к файлу JKS
jks{{ .JKS_ALIAS }}Псевдоним записи сертификата
jks{{ .JKS_KEY_PASS }}Пароль закрытого ключа записи
jks{{ .JKS_STORE_PASS }}Пароль keystore
iis{{ .IIS_SITE_NAME }}Имя сайта IIS
iis{{ .IIS_IPADDR }}IP-адрес привязки HTTPS
iis{{ .IIS_PORT }}Порт привязки HTTPS
iis{{ .IIS_DOMAIN }}Домен привязки HTTPS
exchange{{ .EXCHANGE_SERVICES }}Список имён служб Exchange (через запятую)

Рекомендации по безопасности​

  • config.yaml содержит учётные данные для доступа и путь к закрытому ключу, поэтому ограничьте права доступа к файлу так, чтобы чтение и запись были доступны только учётной записи, под которой выполняется запуск (например, chmod 600 config.yaml).
  • AccessSecret после сохранения хранится в зашифрованном виде, но всё равно не следует копировать файл конфигурации в ненадёжные места.
  • Используйте для clmBot отдельную учётную запись запуска и предоставляйте минимально необходимые права, см. Требования к правам запуска.