Skip to main content

clmBot Runtime Permission Requirements

When performing automatic certificate renewal, clmBot needs read and write access to the target certificate files, and will reload or restart the corresponding middleware service after the update. This document describes the recommended minimum permission configuration for various middleware scenarios.

Note

Middleware reload / restart commands are defined in the servers[].after_script field of config.yaml, and users can adjust them according to the 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 use a dedicated system account (such as clmbot) to run clmBot, and follow these principles:

  • Only grant this account the permissions required to read clmBot configuration, log directories, and target certificate installation points.
  • Only grant write permissions to certificate files, private key files managed by clmBot, and their parent directories.
  • Only allow execution of verified middleware reload / restart commands, and do not grant NOPASSWD: ALL or full root privileges.
  • before_script and after_script must be manually audited, and permissions required in scripts should be granted item by item.

Not recommended practices:

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

Permission Requirements for Each Middleware​

nginx​

clmBot requires the following permissions:

  1. Read and write permissions for the certificate directory: Read and write access to the directory where the target certificate file (.crt), CA chain file (optional), and private key file (.key) are located, to allow writing new certificates and creating .bak backups.
  2. Execute the reload command: after_script generates the following script by default to reload nginx after certificate renewal:
nginx -t && nginx -s reload

Least privilege recommendations:

  • Only grant access to the target certificate directory, and do not grant read/write permissions to the entire /etc/nginx.
  • Precisely authorize nginx -t and nginx -s reload through sudoers, and do not grant a full root shell.

Apache HTTP Server​

clmBot requires the following permissions:

  1. Certificate directory read/write permissions: Read and write permissions for the directories where SSLCertificateFile, SSLCertificateChainFile, and SSLCertificateKeyFile are located.
  2. Permission to execute service restart commands: 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 grant access to the target certificate directory, and do not grant permissions to the entire Apache configuration directory.
  • Through sudoers, grant restart permission only to the Apache service name actually in use on the current system.

Tomcat​

clmBot requires the following permissions:

  1. Read and write permissions for the certificate directory: Read and write permissions for the directory where PEM certificate/private key files or JKS keystore files are located.
  2. Permission to 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"

Least privilege recommendations:

  • Prioritize placing clmBot and Tomcat in the same business group, and only grant read/write permissions to the target keystore or certificate directory.
  • Only allow execution of shutdown.sh and startup.sh for the corresponding Tomcat instance; do not grant permissions to the entire /opt directory.
  • In multi-instance Tomcat environments, split authorizations by instance.

IIS​

IIS scenarios rely on Windows PowerShell scripts to import PFX files and update HTTPS bindings, and require 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 the creation and cleanup of temporary PFX files.

Least privilege recommendations:

  • Use a dedicated Windows service account, and only grant the permissions required to manage target IIS site bindings.
  • PowerShell execution policies and module permissions should be audited separately according to the host security baseline.

Linux sudoers Configuration Example​

The following examples only demonstrate 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

Example of certificate directory permissions:

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 grant precise permissions using ACL:

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​

Tip

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

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