Grafana Configuration

 

Configure Grafana

You can use Grafana Cloud to avoid installing, maintaining, and scaling your own instance of Grafana. Create a free account to get started, which includes free forever access to 10k metrics, 50GB logs, 50GB traces, 500VUh k6 testing & more.

Grafana has default and custom configuration files. You can customize your Grafana instance by modifying the custom configuration file or by using environment variables. To see the list of settings for a Grafana instance, refer to View server settings.

NOTE

After you add custom options, uncomment the relevant sections of the configuration file. Restart Grafana for your changes to take effect.

Configuration file location

The default settings for a Grafana instance are stored in the $WORKING_DIR/conf/defaults.ini file. Do not change this file.

Depending on your OS, your custom configuration file is either the $WORKING_DIR/conf/custom.ini file or the /usr/local/etc/grafana/grafana.ini file. The custom configuration file path can be overridden using the --config parameter.

Linux

If you installed Grafana using the deb or rpm packages, then your configuration file is located at /etc/grafana/grafana.ini and a separate custom.ini is not used. This path is specified in the Grafana init.d script using --config file parameter.

Docker

Refer to Configure a Grafana Docker image for information about environmental variables, persistent storage, and building custom Docker images.

Windows

On Windows, the sample.ini file is located in the same directory as defaults.ini file. It contains all the settings commented out. Copy sample.ini and name it custom.ini.

macOS

By default, the configuration file is located at /usr/local/etc/grafana/grafana.ini. For a Grafana instance installed using Homebrew, edit the grafana.ini file directly. Otherwise, add a configuration file named custom.ini to the conf folder to override the settings defined in conf/defaults.ini.

Remove comments in the .ini files

Grafana uses semicolons (the ; char) to comment out lines in a .ini file. You must uncomment each line in the custom.ini or the grafana.ini file that you are modify by removing ; from the beginning of that line. Otherwise your changes will be ignored.

For example:

# The HTTP port  to use
;http_port = 3000

Override configuration with environment variables

Do not use environment variables to add new configuration settings. Instead, use environmental variables to override existing options.

To override an option:

bash

GF_<SectionName>_<KeyName>

Where the section name is the text within the brackets. Everything should be uppercase, . and - should be replaced by _. For example, if you have these configuration settings:

bash

# default section
instance_name = ${HOSTNAME}

[security]
admin_user = admin

[auth.google]
client_secret = 0ldS3cretKey

[plugin.grafana-image-renderer]
rendering_ignore_https_errors = true

[feature_toggles]
enable = newNavigation

You can override variables on Linux machines with:

bash

export GF_DEFAULT_INSTANCE_NAME=my-instance
export GF_SECURITY_ADMIN_USER=owner
export GF_AUTH_GOOGLE_CLIENT_SECRET=newS3cretKey
export GF_PLUGIN_GRAFANA_IMAGE_RENDERER_RENDERING_IGNORE_HTTPS_ERRORS=true
export GF_FEATURE_TOGGLES_ENABLE=newNavigation

Variable expansion

NOTE

Only available in Grafana 7.1+.

If any of your options contains the expression $__<provider>{<argument>} or ${<environment variable>}, then they will be processed by Grafana’s variable expander. The expander runs the provider with the provided argument to get the final value of the option.

There are three providers: env, file, and vault.

Env provider

The env provider can be used to expand an environment variable. If you set an option to $__env{PORT} the PORT environment variable will be used in its place. For environment variables you can also use the short-hand syntax ${PORT}. Grafana’s log directory would be set to the grafana directory in the directory behind the LOGDIR environment variable in the following example.

ini

[paths]
logs = $__env{LOGDIR}/grafana

File provider

file reads a file from the filesystem. It trims whitespace from the beginning and the end of files. The database password in the following example would be replaced by the content of the /etc/secrets/gf_sql_password file:

ini

[database]
password = $__file{/etc/secrets/gf_sql_password}

Vault provider

The vault provider allows you to manage your secrets with Hashicorp Vault.

Vault provider is only available in Grafana Enterprise v7.1+. For more information, refer to Vault integration in Grafana Enterprise.

---

app_mode

Options are production and development. Default is production. Do not change this option unless you are working on Grafana development.

instance_name

Set the name of the grafana-server instance. Used in logging, internal metrics, and clustering info. Defaults to: ${HOSTNAME}, which will be replaced with environment variable HOSTNAME, if that is empty or does not exist Grafana will try to use system calls to get the machine name.

---

[paths]

data

Path to where Grafana stores the sqlite3 database (if used), file-based sessions (if used), and other data. This path is usually specified via command line in the init.d script or the systemd service file.

macOS: The default SQLite database is located at /usr/local/var/lib/grafana

temp_data_lifetime

How long temporary images in data directory should be kept. Defaults to: 24h. Supported modifiers: h (hours), m (minutes), for example: 168h, 30m, 10h30m. Use 0 to never clean up temporary files.

logs

Path to where Grafana stores logs. This path is usually specified via command line in the init.d script or the systemd service file. You can override it in the configuration file or in the default environment variable file. However, please note that by overriding this the default log path will be used temporarily until Grafana has fully initialized/started.

Override log path using the command line argument cfg:default.paths.logs:

bash

./grafana-server --config /custom/config.ini --homepath /custom/homepath cfg:default.paths.logs=/custom/path

macOS: By default, the log file should be located at /usr/local/var/log/grafana/grafana.log.

plugins

Directory where Grafana automatically scans and looks for plugins. For information about manually or automatically installing plugins, refer to Install Grafana plugins.

macOS: By default, the Mac plugin location is: /usr/local/var/lib/grafana/plugins.

provisioning

Folder that contains provisioning config files that Grafana will apply on startup. Dashboards will be reloaded when the json files changes.

---

[server]

protocol

http,https,h2 or socket

min_tls_version

The TLS Handshake requires a minimum TLS version. The available options are TLS1.2 and TLS1.3. If you do not specify a version, the system uses TLS1.2.

http_addr

The host for the server to listen on. If your machine has more than one network interface, you can use this setting to expose the Grafana service on only one network interface and not have it available on others, such as the loopback interface. An empty value is equivalent to setting the value to 0.0.0.0, which means the Grafana service binds to all interfaces.

In environments where network address translation (NAT) is used, ensure you use the network interface address and not a final public address; otherwise, you might see errors such as bind: cannot assign requested address in the logs.

http_port

The port to bind to, defaults to 3000. To use port 80 you need to either give the Grafana binary permission for example:

bash

$ sudo setcap 'cap_net_bind_service=+ep' /usr/sbin/grafana-server

Or redirect port 80 to the Grafana port using:

bash

$ sudo iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 3000

Another way is to put a web server like Nginx or Apache in front of Grafana and have them proxy requests to Grafana.

domain

This setting is only used in as a part of the root_url setting (see below). Important if you use GitHub or Google OAuth.

enforce_domain

Redirect to correct domain if the host header does not match the domain. Prevents DNS rebinding attacks. Default is false.

root_url

This is the full URL used to access Grafana from a web browser. This is important if you use Google or GitHub OAuth authentication (for the callback URL to be correct).

NOTE

This setting is also important if you have a reverse proxy in front of Grafana that exposes it through a subpath. In that case add the subpath to the end of this URL setting.

serve_from_sub_path

Serve Grafana from subpath specified in root_url setting. By default it is set to false for compatibility reasons.

By enabling this setting and using a subpath in root_url above, e.g.root_url = http://localhost:3000/grafana, Grafana is accessible on http://localhost:3000/grafana. If accessed without subpath Grafana will redirect to an URL with the subpath.

router_logging

Set to true for Grafana to log all HTTP requests (not just errors). These are logged as Info level events to the Grafana log.

static_root_path

The path to the directory where the front end files (HTML, JS, and CSS files). Defaults to public which is why the Grafana binary needs to be executed with working directory set to the installation path.

enable_gzip

Set this option to true to enable HTTP compression, this can improve transfer speed and bandwidth utilization. It is recommended that most users set it to true. By default it is set to false for compatibility reasons.

cert_file

Path to the certificate file (if protocol is set to https or h2).

cert_key

Path to the certificate key file (if protocol is set to https or h2).

certs_watch_interval

Controls whether cert_key and cert_file are periodically watched for changes. Disabled, by default. When enabled, cert_key and cert_file are watched for changes. If there is change, the new certificates are loaded automatically.

WARNING

After the new certificates are loaded, connections with old certificates will not work. You must reload the connections to the old certs for them to work.

socket_gid

GID where the socket should be set when protocol=socket. Make sure that the target group is in the group of Grafana process and that Grafana process is the file owner before you change this setting. It is recommended to set the gid as http server user gid. Not set when the value is -1.

socket_mode

Mode where the socket should be set when protocol=socket. Make sure that Grafana process is the file owner before you change this setting.

socket

Path where the socket should be created when protocol=socket. Make sure Grafana has appropriate permissions for that path before you change this setting.

cdn_url

NOTE

Available in Grafana v7.4 and later versions.

Specify a full HTTP URL address to the root of your Grafana CDN assets. Grafana will add edition and version paths.

For example, given a cdn url like https://cdn.myserver.com grafana will try to load a javascript file from http://cdn.myserver.com/grafana-oss/7.4.0/public/build/app.<hash>.js.

read_timeout

Sets the maximum time using a duration format (5s/5m/5ms) before timing out read of an incoming request and closing idle connections. 0 means there is no timeout for reading the request.