How to Configure Grafana SSL for a Secure HTTPS Connection (Step-by-Step)

Configuring SSL to enable HTTPS on your Grafana instance is a critical step to protect your data, credentials, and visualizations. This guide provides a clear, step-by-step process for generating a self-signed SSL certificate and configuring your self-hosted Grafana server on Linux to use it.

Key Takeaways

• Why It Matters: Enabling HTTPS encrypts all traffic between users and your Grafana server, protecting sensitive data like login credentials and dashboard information from being intercepted.
• Core Method: This guide uses the OpenSSL command-line tool to generate a private key and a self-signed certificate.
• Configuration File: The primary changes are made within the [server] section of the /etc/grafana/grafana.ini file.
• Main Steps: The process involves generating the certificate and key, moving them to the Grafana directory, updating the grafana.ini configuration, and restarting the Grafana service.
• Browser Warning: Using a self-signed certificate will cause a browser privacy warning, which is expected. You must accept it to proceed. For production, a certificate from a trusted Certificate Authority (CA) is recommended.

Why Should I Use HTTPS for My Grafana Instance?

You should use HTTPS because, by default, a self-hosted Grafana installation communicates over unencrypted HTTP. This means all data, including usernames, passwords, API keys, and dashboard query results, are sent in plain text. An attacker on the same network could easily intercept this traffic. Enabling SSL/TLS to force an HTTPS connection encrypts this data, ensuring confidentiality, verifying the server’s identity, and protecting against man-in-the-middle attacks.

What Do I Need to Enable SSL in Grafana?

To enable SSL, you need two primary files: a private key file (.key) and an SSL certificate file (.crt). You will also need sudo or root access to your Linux server to generate these files, modify the Grafana configuration, and restart the service.

This guide will walk you through creating both files using OpenSSL, a standard tool available on most Linux distributions. The configuration changes are made in the grafana.ini file, specifically in the [server] section.

How Do I Generate a Self-Signed SSL Certificate for Grafana?

Generating a self-signed certificate involves a three-command process using OpenSSL. These steps create your private key, a certificate signing request (CSR), and finally, the certificate itself.

Open your server’s terminal and execute the following commands.

Step 1 – Generate a Private Key

This command creates a 2048-bit RSA private key named grafana.key. This key must be kept secure and private.

openssl genrsa -out grafana.key 2048

openssl genrsa -out grafana.key 2048

Step 2 – Create a Certificate Signing Request (CSR)

Next, create a CSR. You will be prompted to enter information like your country, organization, and a “Common Name.” The Common Name is crucial and should be the domain name or IP address you use to access Grafana.

openssl req -new -key grafana.key -out grafana.csr

openssl req -new -key grafana.key -out grafana.csr

Step 3 – Generate the Self-Signed Certificate

Finally, use your private key and CSR to generate the SSL certificate file (grafana.crt). We’ll set it to be valid for 365 days.

openssl x509 -req -days 365 -in grafana.csr -signkey grafana.key -out grafana.crt

openssl x509 -req -days 365 -in grafana.csr -signkey grafana.key -out grafana.crt

After running these commands, you will have two new files in your current directory: grafana.key and grafana.crt.

How Do I Configure Grafana to Use the New SSL Certificate?

With the certificate and key created, the next step is to place them in the correct directory, set their permissions, and tell Grafana how to use them.

Step 1 – Move the Certificate and Key Files

Move the two generated files to Grafana’s configuration directory, which is typically /etc/grafana/.

sudo mv grafana.crt grafana.key /etc/grafana/

sudo mv grafana.crt grafana.key /etc/grafana/

Step 2 – Set Secure File Ownership and Permissions

It is critical that only the grafana user can read these files. Change the ownership to the grafana user and group, and set the file permissions to read-only for the owner.

sudo chown grafana:grafana /etc/grafana/grafana.crt /etc/grafana/grafana.key
sudo chmod 400 /etc/grafana/grafana.key /etc/grafana/grafana.crt

sudo chown grafana:grafana /etc/grafana/grafana.crt /etc/grafana/grafana.key
sudo chmod 400 /etc/grafana/grafana.key /etc/grafana/grafana.crt

Step 3 – Edit the grafana.ini Configuration File

Open the main Grafana configuration file with a text editor like vim or nano.

sudo vim /etc/grafana/grafana.ini

sudo vim /etc/grafana/grafana.ini

Search for the [server] section. You need to uncomment and modify the following four lines:

• protocol: Change this from http to https.
• cert_file: Provide the full path to your certificate file.
• cert_key: Provide the full path to your private key file.
• root_url: Update this to reflect the https protocol and your full domain name.

Your final configuration should look like this:

Ini, TOML

[server]
# Protocol to use, e.g. http, https, h2, socket
protocol = https

# The full path to the SSL cert file
cert_file = /etc/grafana/grafana.crt

# The full path to the SSL key file
cert_key = /etc/grafana/grafana.key

# The full public facing url you use in browser
root_url = https://your.grafana.domain:3000

[server]
# Protocol to use, e.g. http, https, h2, socket
protocol = https

# The full path to the SSL cert file
cert_file = /etc/grafana/grafana.crt

# The full path to the SSL key file
cert_key = /etc/grafana/grafana.key

# The full public facing url you use in browser
root_url = https://your.grafana.domain:3000

Step 4 – Restart the Grafana Service

Save your changes to the grafana.ini file and restart the Grafana service to apply them.

sudo systemctl restart grafana-server

sudo systemctl restart grafana-server

How Do I Access My Secure Grafana Instance?

Open your web browser and navigate to https://your.grafana.domain:3000. Because you used a self-signed certificate that your browser doesn’t recognize from a trusted authority, you will see a privacy warning like “Your connection is not private.” This is expected. You must click “Advanced” and choose to “Proceed” to your Grafana URL. After this initial acceptance, you will see the padlock icon in your address bar, confirming your connection is encrypted.

What’s the Next Step After Using a Self-Signed Certificate?

While a self-signed certificate is excellent for testing, development environments, or internal-only tools, it’s not ideal for production or public-facing instances due to the browser warning. The next logical step is to obtain a free certificate from a trusted Certificate Authority (CA) like Let’s Encrypt. Using a CA-signed certificate eliminates the browser privacy warning, providing a seamless and trusted experience for your users. Tools like Certbot can automate the process of obtaining and renewing Let’s Encrypt certificates, making it a robust and low-maintenance solution for production security. Many organizations use this method when building out their own comprehensive monitoring dashboards like a TIG stack.

Troubleshooting Common Grafana SSL Errors

Question: Why won’t Grafana start after I enabled HTTPS? Answer: This is usually due to an incorrect file path in grafana.ini or improper file permissions. Double-check that the cert_file and cert_key paths are correct. Then, verify that the grafana user has read permissions for both files using sudo -u grafana cat /etc/grafana/grafana.crt. If the command fails, your permissions are incorrect.

Question: Why do I still get a “Certificate not trusted” error in my browser? Answer: This error is normal and expected for self-signed certificates. Your browser has no way of verifying the identity of the certificate’s issuer (which is you). To avoid this in a production setting, you must use a certificate issued by a trusted third-party Certificate Authority (CA) like Let’s Encrypt or DigiCert.

Question: Can I use this method for Grafana in a Docker container? Answer: Yes, the principle is the same. You would typically generate the certificates on the host machine and then use a Docker volume to mount them into the container at /etc/grafana/. You would also need to pass the configuration variables (or a mounted grafana.ini file) and ensure the container’s HTTPS port is exposed to the host. This approach is also popular for users running Grafana on a Raspberry Pi to keep their home lab secure.

Conclusion

Securing your Grafana server with SSL/TLS is a non-negotiable step for protecting your data. By following this guide, you have successfully enabled HTTPS encryption using a self-signed certificate. For those running production systems, remember to consider graduating to a CA-signed certificate for a more professional and seamless user experience, especially if you are comparing the features available in the Grafana Enterprise edition.

Note: You will always have to accept this prompt (only once) unless you have purchased a Signed Certificate from a certificate authority vendor such as https://www.digicert.com/

What to know more about Grafana SSL? Check out our other posts about it:

Learn:

• What’s the difference between the Grafana Enterprise and Grafana Community editions?
• Why should I use Grafana?
• How do I install Grafana on a Raspberry Pi?
• Your Top Grafana Questions Answered (Q&A)

Thanks for taking the time to read this article. if you have any questions or feedback, please write in the comment section below.