Skip to main content

Configuration Reference

The behavior of clmBot is controlled by the config.yaml configuration file in the installation directory. This file is automatically generated when login, discover-certificate, or add-server is executed, and it can also be manually edited.

By default, clmBot reads config.yaml from the current directory. You can also specify the configuration file path using the global parameter -c:

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

Overall Structure​

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: Connection Configuration​

FieldDescription
base_urlCloud API address, fill in according to the delivery information; generally no modification is required
ignore_sslWhether to ignore HTTPS certificate verification. Only enable in controlled environments using self-signed certificates
access_keyAccessKey assigned by the cloud
access_secretAccessSecret assigned by the cloud. After the plaintext is saved by the program for the first time, it will be automatically migrated to an encrypted value starting with ENC1+

servers: Installation Point List​

Each servers[] entry corresponds to a certificate installation point:

FieldDescription
idInstallation point identifier, it is recommended to use a name with business meaning
sub_codeCertificate subscription number, corresponding to the certificate subscription in the admin console; clmBot retrieves the latest certificate based on it
formatCertificate format and file path; only one of pem, pfx, jks, iis, exchange can be retained
before_scriptScript executed before the update; if the script fails, the update of the current installation point will be interrupted
after_scriptScript executed after the update, usually used to reload middleware services

format: Certificate format​

pem​

Applicable to scenarios using PEM files, such as nginx, Apache HTTP Server, Tomcat, etc.:

FieldDescription
cert_pathPath to the site certificate file. On update, the leaf certificate is written; if ca_path is empty, the full certificate chain is written as well
ca_pathPath to the CA chain file, can be empty
key_pathPath to the private key file

pfx​

For services requiring a single-file certificate package (PKCS#12):

FieldDescription
pathPath to the PFX file
key_passPassword for the PFX private key; can be left empty if the target service does not require a password

jks​

For Java keystore scenarios such as Tomcat:

FieldDescription
pathPath to the JKS file
aliasAlias for the certificate entry. When empty, it can only be automatically inferred if the keystore contains a single entry
key_passEntry private key password
store_passKeystore password

IIS​

For Windows IIS HTTPS binding:

FieldDescription
nameIIS site name, viewable in IIS Manager
addrHTTPS binding IP, * means all IPs
portHTTPS binding port
domainHTTPS binding domain, can be left blank if no SNI domain

The IIS installation point uses clmBot's built-in script to automatically complete certificate import and binding updates, so no script configuration is usually required.

Exchange​

For Windows Exchange service certificates:

FieldDescription
servicesList of Exchange service names that need the new certificate enabled, e.g., ["IIS", "SMTP", "POP", "IMAP"]

Script Execution Notes​

before_script and after_script are executed in the following order during certificate update:

  1. Attempt to back up the local certificate file (generate a timestamped .bak backup); if the backup fails, log the error and continue.
  2. Execute before_script; if it fails, abort the update for the current installation point.
  3. Write the new certificate.
  4. Execute after_script as configured; the script is responsible for reloading or restarting the middleware service.

When the local certificate is already up to date, the entire update (including the script) is skipped; if you need to force execution after_script, you can use the --force-after parameter.

The script runs on Linux via bash and on Windows via powershell.exe -NoProfile -ExecutionPolicy Bypass.

Script template variables​

When writing before_script / after_script, you can use the following template variables, which clmBot replaces with actual values before execution.

General variables:

VariableDescription
{{ .ID }}Installation point id
{{ .SUB_CODE }}Certificate subscription number
{{ .OS_TYPE }}Operating system type (windows / linux / darwin)
{{ .IS_WINDOWS }}Whether it is Windows (true / false)
{{ .IS_LINUX }}Whether it is Linux (true / false)
{{ .TIMESTAMP }}Current timestamp (seconds)
{{ .DATETIME }}Current date and time (2006-01-02 15:04:05 format)
{{ .DATE }}Current date (2006-01-02 format)
{{ .LATEST }}Whether the certificate is up to date (true / false). When used with --force-after, it can determine in the script whether to skip subsequent operations

Variables provided by certificate format:

FormatVariableDescription
pem{{ .PEM_CERT_PATH }}Site certificate file path
pem{{ .PEM_CA_PATH }}CA chain file path
pem{{ .PEM_KEY_PATH }}Private key file path
pfx{{ .PFX_PATH }}PFX file path
pfx{{ .PFX_KEY_PASS }}PFX private key password
jks{{ .JKS_PATH }}JKS file path
jks{{ .JKS_ALIAS }}Certificate entry alias
jks{{ .JKS_KEY_PASS }}Entry private key password
jks{{ .JKS_STORE_PASS }}Keystore password
iis{{ .IIS_SITE_NAME }}IIS site name
iis{{ .IIS_IPADDR }}HTTPS binding IP
iis{{ .IIS_PORT }}HTTPS binding port
iis{{ .IIS_DOMAIN }}HTTPS binding domain
exchange{{ .EXCHANGE_SERVICES }}Exchange service name list (comma-separated)

Security Recommendations​

  • config.yaml contains access credentials and private key paths. Restrict its file permissions to read/write only for the running account (e.g., chmod 600 config.yaml).
  • AccessSecret is stored in encrypted form after saving, but you should still avoid copying the configuration file to untrusted locations.
  • Use a dedicated running account for clmBot and grant the least privileges required. See Runtime Permission Requirements.