Skip to main content

Runtime Permission Requirements for clmBot

When clmBot performs automatic certificate renewal, it needs read/write access to the target certificate files and must reload or restart the corresponding middleware services after the update. This document describes the recommended minimal permission configuration for various middleware scenarios.

Note

The middleware reload / restart commands are defined in the config.yaml field of servers[].after_script. Users can adjust them based on their actual environment. clmBot does not require long-term operation under high-privilege accounts such as root or Administrator.

Principle of Least Privilege​

It is recommended to run clmBot with a dedicated system account (e.g., clmbot) and follow these principles:

  • Grant this account only the permissions needed to read the clmBot configuration, log directories, and target certificate installation points.
  • Grant write permissions only to the certificate files, private key files, and their containing directories managed by clmBot.
  • Allow only confirmed middleware reload / restart commands to be executed; do not grant NOPASSWD: ALL or full root permissions.
  • before_script and after_script must undergo manual review, and the permissions required in scripts should be granted on a per-item basis.

Not recommended practices:

  • Let clmBot run persistently as root or Administrator.
  • Grant clmBot full access to the middleware configuration directory, certificate directory, or system service control permissions.
  • Grant bash, powershell.exe, and systemctl unrestricted execution permissions.

Permission Requirements for Each Middleware​

nginx​

clmBot requires the following permissions:

  1. Read/write permissions on certificate directories: Read and write access to the directories containing the target certificate file (.crt), the CA chain file (optional), and the private key file (.key), so that new certificates can be written and the .bak backup can be created.
  2. Execute the reload command: after_script generates the following script by default to reload nginx after certificate updates:
nginx -t && nginx -s reload

Least-privilege recommendations:

  • Only open the target certificate directory; do not grant read/write permissions to the entire /etc/nginx.
  • Use sudoers to grant precise authorization for nginx -t and nginx -s reload; do not grant a full root shell.

Apache HTTP Server​

clmBot requires the following permissions:

  1. Read/write permissions for the certificate directory: Read/write access to the directories containing SSLCertificateFile, SSLCertificateChainFile, and SSLCertificateKeyFile.
  2. Execution permission for the service restart command: after_script generates one of the following scripts by default (depending on the distribution):
systemctl restart httpd.service
systemctl restart apache2.service

Minimum authorization recommendations:

  • Only open the target certificate directory; do not grant access to the entire Apache configuration directory.
  • Via sudoers, grant restart permissions only to the Apache service name actually used on the current system.

Tomcat​

clmBot requires the following permissions:

  1. Read/write permissions on certificate directories: Read/write access to the directory containing PEM certificate/private key files or the JKS keystore file.
  2. Execute stop and start scripts: after_script generates the following scripts by default:
export JAVA_HOME="<java_home>" && "<catalina_base>/bin/shutdown.sh" && "<catalina_base>/bin/startup.sh"

Minimum authorization recommendations:

  • Prioritize placing clmBot and Tomcat in the same business group, granting only read/write permissions for the target keystore or certificate directory.
  • Only allow execution of shutdown.sh and startup.sh for the corresponding Tomcat instance, without granting access to the entire /opt directory.
  • In multi-instance Tomcat environments, authorization should be split per instance.

IIS​

IIS scenarios rely on Windows PowerShell scripts to import PFX and update HTTPS bindings, requiring administrator privileges.

clmBot requires the following permissions:

  1. Run under an administrator account: Execute powershell.exe -NoProfile -ExecutionPolicy Bypass to import the temporary PFX and update IIS site bindings.
  2. Read/write permissions for the certificate directory: For creating and cleaning up temporary PFX files.

Minimum authorization recommendations:

  • Use a dedicated Windows service account, granting only the permissions needed to manage the target IIS site bindings.
  • PowerShell execution policy and module permissions should be reviewed separately according to the host security baseline.

Example Linux sudoers configuration​

The following example only illustrates the authorization granularity; adjust the actual paths according to the target host.

nginx:

clmbot ALL=(root) NOPASSWD: /usr/sbin/nginx -t
clmbot ALL=(root) NOPASSWD: /usr/sbin/nginx -s reload

Apache:

clmbot ALL=(root) NOPASSWD: /bin/systemctl restart apache2.service

Tomcat:

clmbot ALL=(tomcat) NOPASSWD: /opt/apache-tomcat/bin/shutdown.sh
clmbot ALL=(tomcat) NOPASSWD: /opt/apache-tomcat/bin/startup.sh

Certificate Inventory Permission Example:

chown -R root:clmbot /etc/ssl/example
chmod 0750 /etc/ssl/example
chmod 0640 /etc/ssl/example/site.crt /etc/ssl/example/ca.crt
chmod 0640 /etc/ssl/example/site.key

To allow clmBot to write to and back up the above files, you can use ACL for precise authorization:

setfacl -m u:clmbot:rwx /etc/ssl/example
setfacl -m u:clmbot:rw- /etc/ssl/example/site.crt
setfacl -m u:clmbot:rw- /etc/ssl/example/ca.crt
setfacl -m u:clmbot:rw- /etc/ssl/example/site.key

Pre-Launch Permission Checklist​

Note

Before deploying clmBot, it is recommended to verify the following permission configurations item by item.

  • Whether clmBot runs with a dedicated account, rather than root or an administrator.
  • Whether config.yaml allows read and write access only to necessary accounts.
  • Whether the certificate file pointed to by each servers[].format has only the required read and write permissions enabled.
  • Whether the directory containing certificate files allows creation and cleanup of .bak backup files.
  • Whether before_script and after_script have been manually audited.
  • Whether sudoers contains only exact commands, rather than ALL, bash, or the full systemctl.
  • Whether the reload or restart permissions for nginx / Apache / Tomcat cover only the target instances.
  • Whether the service mode (clm-bot server) listening address and port comply with the host firewall policy.
Last updated on