CoolerControl

Appearance

On this page

Updated at:

SSL/TLS ​

CoolerControl supports TLS encryption to secure communication between the daemon and clients. This is especially important when accessing the daemon over a network.

How TLS Works in CoolerControl ​

CoolerControl uses a dual-protocol design: the same port (default 11987) handles both HTTP and HTTPS automatically. The daemon detects a TLS handshake on each incoming connection and responds accordingly.

  • Localhost connections are always allowed over plain HTTP.
  • Non-localhost connections over HTTP are automatically redirected to HTTPS with a 301 redirect.

This means you don't need separate ports for HTTP and HTTPS — everything goes through one port.

TLS Configuration ​

SSL/TLS is enabled by default for non-local connections using a self-signed certificate. You will see a security warning in your browser when accessing the daemon over a network.

SSL/TLS can be configured in the daemon's configuration file /etc/coolercontrol/config.toml:

toml
[settings]
# Enable TLS
tls_enabled = true
# Path to TLS certificate file
tls_cert_path = "/path/to/cert.pem"
# Path to TLS private key file
tls_key_path = "/path/to/key.pem"

or using environment variables:

bash
CC_TLS=ON
CC_CERT_PATH="/path/to/cert.pem"
CC_KEY_PATH="/path/to/key.pem"

After editing the configuration, restart the daemon:

bash
sudo systemctl stop coolercontrold
sudo nano /etc/coolercontrol/config.toml
sudo systemctl start coolercontrold

Self-Signed Certificates ​

CoolerControl will automatically generate self-signed certificates if TLS is enabled and no custom certificate paths are configured. The generated files are stored at:

  • /etc/coolercontrol/coolercontrol.crt — Self-signed TLS certificate
  • /etc/coolercontrol/coolercontrol.key — TLS private key (permissions: 0o600)

Certificate Details ​

The auto-generated self-signed certificate includes the following Subject Alternative Names (SANs):

  • localhost, localhost4, localhost6, localhost.localdomain, localhost4.localdomain4, localhost6.localdomain6
  • 127.0.0.1, ::1, 0.0.0.0, ::

The certificate uses CN = CoolerControl self signed cert and Organization = CoolerControl.

Browser Trust for Self-Signed Certificates ​

When using a self-signed certificate, browsers will show a security warning. You can proceed past it:

Chrome:

  1. Navigate to https://<daemon-ip>:11987/
  2. Click Advanced → Proceed to <daemon-ip> (unsafe)

Firefox:

  1. Navigate to https://<daemon-ip>:11987/
  2. Click Advanced… → Accept the Risk and Continue

TIP

To avoid repeated warnings, you can import the certificate into your OS trust store:

bash
# Copy the cert to your local machine
scp root@remote-server:/etc/coolercontrol/coolercontrol.crt /tmp/

# Fedora/RHEL
sudo cp /tmp/coolercontrol.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

# Debian/Ubuntu
sudo cp /tmp/coolercontrol.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

# Arch
sudo trust anchor /tmp/coolercontrol.crt

After importing, restart your browser for the change to take effect.

Using Let's Encrypt ​

For publicly accessible deployments, use Let's Encrypt to obtain free, trusted certificates. This eliminates browser security warnings and provides proper TLS trust.

Prerequisites ​

  • A domain name pointing to your server's public IP (e.g., cooler.example.com)
  • Port 80 accessible from the internet (for HTTP-01 challenge), or the ability to set DNS TXT records (for DNS-01 challenge)
  • certbot installed on your server

Install Certbot ​

bash
# Debian/Ubuntu
sudo apt install certbot

# Fedora/RHEL
sudo dnf install certbot

# Arch Linux
sudo pacman -S certbot

Obtain a Certificate ​

Standalone mode (simplest — certbot runs its own temporary web server on port 80):

bash
sudo certbot certonly --standalone -d your-domain.com

Webroot mode (if you already have a web server or reverse proxy running on port 80):

bash
sudo certbot certonly --webroot -w /var/www/html -d your-domain.com

DNS challenge (for servers without port 80 access):

bash
sudo certbot certonly --manual --preferred-challenges dns -d your-domain.com

This will prompt you to create a DNS TXT record. Follow the instructions to complete verification.

Configure CoolerControl to Use Let's Encrypt ​

Certificates are stored at /etc/letsencrypt/live/your-domain.com/. Update your daemon configuration:

toml
[settings]
tls_enabled = true
tls_cert_path = "/etc/letsencrypt/live/your-domain.com/fullchain.pem"
tls_key_path = "/etc/letsencrypt/live/your-domain.com/privkey.pem"

WARNING

The coolercontrold process needs read access to the Let's Encrypt key files. By default, /etc/letsencrypt/live/ and /etc/letsencrypt/archive/ are owned by root with restricted permissions. Since coolercontrold runs as root, this is typically not an issue, but verify with:

bash
sudo ls -la /etc/letsencrypt/live/your-domain.com/

Restart the daemon to apply:

bash
sudo systemctl restart coolercontrold

Auto-Renewal ​

Let's Encrypt certificates expire after 90 days. Set up automatic renewal:

Using the systemd timer (recommended):

bash
sudo systemctl enable --now certbot-renewal.timer

Using cron:

bash
# Add to root's crontab (sudo crontab -e)
0 0,12 * * * certbot renew --quiet

Post-Renewal Hook ​

To automatically restart coolercontrold after certificate renewal so it picks up the new certificate:

bash
sudo certbot renew --deploy-hook "systemctl restart coolercontrold"

To make this permanent, create a renewal hook file:

bash
echo 'systemctl restart coolercontrold' | sudo tee /etc/letsencrypt/renewal-hooks/deploy/coolercontrold.sh
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/coolercontrold.sh

Verify Renewal ​

Test that renewal works without actually renewing:

bash
sudo certbot renew --dry-run

Troubleshooting ​

  • Permission errors on key files: Ensure coolercontrold can read the certificate and key. Check ownership and permissions under /etc/letsencrypt/.
  • Port 80 blocked by firewall: The HTTP-01 challenge requires port 80. Temporarily open it or use the DNS challenge method instead.
  • Certificate not updating after renewal: The daemon must be restarted to pick up new certificates. Set up a deploy hook as described above.

Certificate Renewal Note ​

CoolerControl reads TLS certificates at startup. If you replace or renew certificates, you must restart the daemon for the new certificates to take effect:

bash
sudo systemctl restart coolercontrold

Reverse Proxy Alternative ​

Instead of configuring TLS directly in CoolerControl, you can use a reverse proxy to handle TLS termination. This is often more flexible and enables features like automatic Let's Encrypt certificate management. See the Reverse Proxy guide for detailed setup instructions with nginx, Caddy, and Traefik.

The allow_unencrypted Setting ​

By default, when TLS is enabled, non-localhost HTTP connections are redirected to HTTPS. If you need to allow unencrypted HTTP from non-localhost clients (for example, behind a trusted reverse proxy that connects over HTTP), you can set:

toml
[settings]
allow_unencrypted = true

DANGER

This disables the HTTPS redirect for all non-localhost connections. Only use this in trusted network environments or when a reverse proxy handles TLS termination in front of CoolerControl.

See Also ​

Released under the GPLv3+ License.

Copyright © 2021-present Guy Boldon