From 1f780fdce133dc8c45d076ff9b8ebe73be88f7bf Mon Sep 17 00:00:00 2001 From: Jack Baldry Date: Mon, 20 Jan 2025 09:55:37 +0000 Subject: [PATCH] Lint for Writers' Toolkit style (#99234) --- .../setup-grafana/configure-grafana/_index.md | 1794 +++++++++-------- 1 file changed, 961 insertions(+), 833 deletions(-) diff --git a/docs/sources/setup-grafana/configure-grafana/_index.md b/docs/sources/setup-grafana/configure-grafana/_index.md index 780fd4c7a98..6469a11891b 100644 --- a/docs/sources/setup-grafana/configure-grafana/_index.md +++ b/docs/sources/setup-grafana/configure-grafana/_index.md @@ -1,70 +1,88 @@ --- aliases: - - ../administration/configuration/ - - ../installation/configuration/ -description: Configuration documentation + - ../administration/configuration/ # /docs/grafana/latest/administration/configuration/ + - ../installation/configuration/ # /docs/grafana/latest/installation/configuration/ +description: Learn how to configure Grafana and understand configuration options. labels: products: - enterprise - oss title: Configure Grafana +toc: + endLevel: 4 weight: 200 --- # Configure Grafana -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]({{< relref "../../administration/stats-and-license#view-server-settings" >}}). +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](/docs/grafana//administration/stats-and-license#view-server-settings). -{{% admonition type="note" %}} -After you add custom options, [uncomment](#remove-comments-in-the-ini-files) the relevant sections of the configuration file. Restart Grafana for your changes to take effect. -{{% /admonition %}} +{{< admonition type="note" >}} +After you add custom options, [uncomment](#remove-comments-in-the-ini-files) the relevant sections of the configuration file. + +Restart Grafana for your changes to take effect. +{{< /admonition >}} ## 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. +The default settings for a Grafana instance are stored in the `/conf/defaults.ini` file. +_Don't_ 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. +Depending on your OS, your custom configuration file is either the `/conf/custom.ini` file or the `/usr/local/etc/grafana/grafana.ini` file. +You can use a custom configuration path with the `--config` option. ### 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. +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` option. ### Docker -Refer to [Configure a Grafana Docker image]({{< relref "../configure-docker" >}}) for information about environmental variables, persistent storage, and building custom Docker images. +Refer to [Configure a Grafana Docker image](/docs/grafana//setup-grafana/configure-docker/) 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`. +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 `/opt/homebrew/etc/grafana/grafana.ini` or `/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`. +By default, the configuration file is located at `/opt/homebrew/etc/grafana/grafana.ini` or `/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` directory 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. +Grafana uses semicolons (`;`) to comment out lines in the INI file. +To uncomment a line, remove the semicolon (`;`) from the beginning of that line. + +Grafana ignores all configuration lines that begin with a semicolon. For example: -``` -# The HTTP port to use +```ini ;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. +Don't use environment variables to _add_ new configuration settings. +Instead, use environmental variables to _override_ existing options. To override an option: ```bash -GF__ +GF_
_ ``` -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: +Where _`
`_ is the text within the square brackets (`[` and `]`) in the configuration file. +All letters must be uppercase, periods (`.`) and dashes (`-`) must replaced by underscores (`_`). +For example, if you have these configuration settings: -```bash +```ini # default section instance_name = ${HOSTNAME} @@ -93,75 +111,87 @@ export GF_FEATURE_TOGGLES_ENABLE=newNavigation ## Variable expansion -If any of your options contains the expression `$__{}` -or `${}`, 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. +If any of your options contains the expression `$__{}`or `${}`, then Grafana evaluates them. +The evaluation 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 +### `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. +The `env` provider expands environment variables. +If you set an option to `$__env{PORT}` the value of the `PORT` environment variable replaces it. +For environment variables you can also use the short-hand syntax `${PORT}`. + +The following example sets the log directory to the path in the `LOGDIR` environment variable: ```ini [paths] logs = $__env{LOGDIR}/grafana ``` -### File provider +### `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: +The `file` provider reads a file from the filesystem. +It trims whitespace from the beginning and the end of files. + +The following example sets the database password to the contents of the `/etc/secrets/gf_sql_password` file: ```ini [database] password = $__file{/etc/secrets/gf_sql_password} ``` -### Vault provider +### `vault` provider -The `vault` provider allows you to manage your secrets with [Hashicorp Vault](https://www.hashicorp.com/products/vault). +The `vault` provider lets manage your secrets with [Hashicorp Vault](https://www.hashicorp.com/products/vault). -> Vault provider is only available in Grafana Enterprise v7.1+. For more information, refer to [Vault integration]({{< relref "../configure-security/configure-database-encryption/integrate-with-hashicorp-vault" >}}) in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise" >}}). +{{< admonition type="note" >}} +The `vault` provider is only available in Grafana Enterprise. + +For more information, refer to [Integrate Grafana with Hashicorp Vault](/docs/grafana//setup-grafana/configure-security/configure-database-encryption/integrate-with-hashicorp-vault). + +{{< /admonition >}} + +## Configuration options + +The following headings describe the sections and configuration options of the Grafana configuration file. + +### `app_mode` + +Options are `production` and `development`. +Default is `production`. _Don't_ 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 uses the value of the environment variable `HOSTNAME`, if that is empty or doesn't exist Grafana tries to use system calls to get the machine name.
-## app_mode +### `[paths]` -Options are `production` and `development`. Default is `production`. _Do not_ change this option unless you are working on Grafana development. +#### `data` -## 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. +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 +#### `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 +#### `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. +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. + +{{< admonition type="note" >}} +When overriding the default log path in the configuration file or environment variable file, Grafana still logs to the default log path until it has fully started. +{{< /admonition >}} Override log path using the command line argument `cfg:default.paths.logs`: @@ -171,144 +201,147 @@ Override log path using the command line argument `cfg:default.paths.logs`: **macOS:** By default, the log file should be located at `/usr/local/var/log/grafana/grafana.log`. -### plugins +#### `plugins` Directory where Grafana automatically scans and looks for plugins. For information about manually or automatically installing plugins, refer to [Install Grafana plugins]({{< relref "../../administration/plugin-management#install-grafana-plugins" >}}). **macOS:** By default, the Mac plugin location is: `/usr/local/var/lib/grafana/plugins`. -### provisioning +#### `provisioning` -Folder that contains [provisioning]({{< relref "../../administration/provisioning" >}}) config files that Grafana will apply on startup. Dashboards will be reloaded when the json files changes. +Directory that contains [provisioning]({{< relref "../../administration/provisioning" >}}) configuration files that Grafana applies on startup. +Dashboards are reloaded when the JSON files change.
-## [server] +### `[server]` -### protocol +#### `protocol` `http`,`https`,`h2` or `socket` -### min_tls_version +#### `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 +#### `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. +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 +#### `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 +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 +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 +#### `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 +#### `enforce_domain` Redirect to correct domain if the host header does not match the domain. Prevents DNS rebinding attacks. Default is `false`. -### root_url +#### `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). -{{% admonition type="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. -{{% /admonition %}} +{{< admonition type="note" >}} +This setting is also important if you have a reverse proxy in front of Grafana that exposes it through a sub-path. -### serve_from_sub_path +In that case add the sub-path to the end of this URL setting. +{{< /admonition >}} -Serve Grafana from subpath specified in `root_url` setting. By default it is set to `false` for compatibility reasons. +#### `serve_from_sub_path` -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. +Serve Grafana from sub-path specified in `root_url` setting. By default it is set to `false` for compatibility reasons. -### router_logging +By enabling this setting and using a sub-path in `root_url` like `root_url = http://localhost:3000/grafana`, Grafana is accessible on `http://localhost:3000/grafana`. +If accessed without sub-path Grafana redirects the request to the sub-path. + +#### `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 +#### `static_root_path` -The path to the directory where the front end files (HTML, JS, and CSS +The path to the directory where the frontend 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 +#### `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 +#### `cert_file` Path to the certificate file (if `protocol` is set to `https` or `h2`). -### cert_key +#### `cert_key` Path to the certificate key file (if `protocol` is set to `https` or `h2`). -### certs_watch_interval +#### `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. -{{% admonition type="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. -{{% /admonition %}} +{{< admonition type="warning" >}} +After the new certificates are loaded, connections with old certificates don't work. +You must reload the connections with old certificates for them to work. +{{< /admonition >}} -### socket_gid +#### `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. +It is recommended to set the GID as HTTP server user GID. +Not set when the value is `-1`. -### socket_mode +#### `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 +#### `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 +#### `cdn_url` -Specify a full HTTP URL address to the root of your Grafana CDN assets. Grafana will add edition and version paths. +Specify a full HTTP URL address to the root of your Grafana CDN assets. Grafana adds 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..js`. +For example, given a CDN URL like `https://cdn.myserver.com`, Grafana tries to load a JavaScript file from +`http://cdn.myserver.com/grafana-oss/7.4.0/public/build/app..js`. -### read_timeout +#### `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.
-## [server.custom_response_headers] +### `[server.custom_response_headers]` This setting enables you to specify additional headers that the server adds to HTTP(S) responses. @@ -319,398 +352,430 @@ exampleHeader2 = exampleValue2
-## [database] +### `[database]` Grafana needs a database to store users and dashboards (and other things). By default it is configured to use [`sqlite3`](https://www.sqlite.org/index.html) which is an embedded database (included in the main Grafana binary). -### type +#### `type` Either `mysql`, `postgres` or `sqlite3`, it's your choice. -### host +#### `host` Only applicable to MySQL or Postgres. Includes IP or hostname and port or in case of Unix sockets the path to it. For example, for MySQL running on the same host as Grafana: `host = 127.0.0.1:3306` or with Unix sockets: `host = /var/run/mysqld/mysqld.sock` -### name +#### `name` The name of the Grafana database. Leave it set to `grafana` or some other name. -### user +#### `user` The database user (not applicable for `sqlite3`). -### password +#### `password` The database user's password (not applicable for `sqlite3`). If the password contains `#` or `;` you have to wrap it with triple quotes. For example `"""#password;"""` -### url +#### `url` Use either URL or the other fields below to configure the database Example: `mysql://user:secret@host:port/database` -### max_idle_conn +#### `max_idle_conn` The maximum number of connections in the idle connection pool. -### max_open_conn +#### `max_open_conn` The maximum number of open connections to the database. For MYSQL, configure this setting on both Grafana and the database. For more information, refer to [`sysvar_max_connections`](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_max_connections). -### conn_max_lifetime +#### `conn_max_lifetime` Sets the maximum amount of time a connection may be reused. The default is 14400 (which means 14400 seconds or 4 hours). For MySQL, this setting should be shorter than the [`wait_timeout`](https://dev.mysql.com/doc/refman/5.7/en/server-system-variables.html#sysvar_wait_timeout) variable. -### migration_locking +#### `migration_locking` Set to `false` to disable database locking during the migrations. Default is true. -### locking_attempt_timeout_sec +#### `locking_attempt_timeout_sec` -For "mysql" and "postgres" only. Specify the time (in seconds) to wait before failing to lock the database for the migrations. Default is 0. +For `mysql` and `postgres` only. +Specify the time, in seconds, to wait before failing to lock the database for the migrations. +Default is `0`. -### log_queries +#### `log_queries` -Set to `true` to log the sql calls and execution times. +Set to `true` to log the SQL calls and execution times. -### ssl_mode +#### `ssl_mode` -For Postgres, use use any [valid libpq `sslmode`](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS), e.g.`disable`, `require`, `verify-full`, etc. +For Postgres, use any [valid `libpq` `sslmode`](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS), for example, `disable`, `require`, `verify-full`, etc. For MySQL, use either `true`, `false`, or `skip-verify`. -### ssl_sni +#### `ssl_sni` -For Postgres, set to `0` to disable [Server Name Indication](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-SSLSNI). This is enabled by default on SSL-enabled connections. +For Postgres, set to `0` to disable [Server Name Indication](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-SSLSNI). +This is enabled by default on SSL-enabled connections. -### isolation_level +#### `isolation_level` Only the MySQL driver supports isolation levels in Grafana. In case the value is empty, the driver's default isolation level is applied. Available options are "READ-UNCOMMITTED", "READ-COMMITTED", "REPEATABLE-READ" or "SERIALIZABLE". -### ca_cert_path +#### `ca_cert_path` The path to the CA certificate to use. On many Linux systems, certs can be found in `/etc/ssl/certs`. -### client_key_path +#### `client_key_path` The path to the client key. Only if server requires client authentication. -### client_cert_path +#### `client_cert_path` The path to the client cert. Only if server requires client authentication. -### server_cert_name +#### `server_cert_name` The common name field of the certificate used by the `mysql` or `postgres` server. Not necessary if `ssl_mode` is set to `skip-verify`. -### path +#### `path` -Only applicable for `sqlite3` database. The file path where the database -will be stored. +Only applicable for `sqlite3` database. +The path to the database file. -### cache_mode +#### `cache_mode` For "sqlite3" only. [Shared cache](https://www.sqlite.org/sharedcache.html) setting used for connecting to the database. (private, shared) Defaults to `private`. -### wal +#### `wal` For "sqlite3" only. Setting to enable/disable [Write-Ahead Logging](https://sqlite.org/wal.html). The default value is `false` (disabled). -### query_retries +#### `query_retries` This setting applies to `sqlite` only and controls the number of times the system retries a query when the database is locked. The default value is `0` (disabled). -### transaction_retries +#### `transaction_retries` This setting applies to `sqlite` only and controls the number of times the system retries a transaction when the database is locked. The default value is `5`. -### instrument_queries +#### `instrument_queries` Set to `true` to add metrics and tracing for database queries. The default value is `false`.
-## [remote_cache] +### `[remote_cache]` Caches authentication details and session information in the configured database, Redis or Memcached. This setting does not configure [Query Caching in Grafana Enterprise]({{< relref "../../administration/data-source-management#query-and-resource-caching" >}}). -### type +#### `type` Either `redis`, `memcached`, or `database`. Defaults to `database` -### connstr +#### `connstr` The remote cache connection string. The format depends on the `type` of the remote cache. Options are `database`, `redis`, and `memcache`. -#### database +##### `database` -Leave empty when using `database` since it will use the primary database. +Leave empty when using `database` and Grafana uses the primary database. -#### redis +##### `redis` -Example connstr: `addr=127.0.0.1:6379,pool_size=100,db=0,ssl=false` +Example connection string: `addr=127.0.0.1:6379,pool_size=100,db=0,ssl=false` -- `addr` is the host `:` port of the redis server. -- `pool_size` (optional) is the number of underlying connections that can be made to redis. -- `db` (optional) is the number identifier of the redis database you want to use. -- `ssl` (optional) is if SSL should be used to connect to redis server. The value may be `true`, `false`, or `insecure`. Setting the value to `insecure` skips verification of the certificate chain and hostname when making the connection. +- `addr` is the host `:` port of the Redis server. +- `pool_size` (optional) is the number of underlying connections that can be made to Redis. +- `db` (optional) is the number identifier of the Redis database you want to use. +- `ssl` (optional) is if SSL should be used to connect to Redis server. The value may be `true`, `false`, or `insecure`. Setting the value to `insecure` skips verification of the certificate chain and hostname when making the connection. -#### memcache +##### `memcache` -Example connstr: `127.0.0.1:11211` +Example connection string: `127.0.0.1:11211`
-## [dataproxy] +### `[dataproxy]` -### logging +#### `logging` This enables data proxy logging, default is `false`. -### timeout +#### `timeout` How long the data proxy should wait before timing out. Default is 30 seconds. This setting also applies to core backend HTTP data sources where query requests use an HTTP client with timeout set. -### keep_alive_seconds +#### `keep_alive_seconds` -Interval between keep-alive probes. Default is `30` seconds. For more details check the [Dialer.KeepAlive](https://golang.org/pkg/net/#Dialer.KeepAlive) documentation. +Interval between keep-alive probes. Default is `30` seconds. For more details, refer to the [`Dialer.KeepAlive`](https://golang.org/pkg/net/#Dialer.KeepAlive) documentation. -### tls_handshake_timeout_seconds +#### `tls_handshake_timeout_seconds` -The length of time that Grafana will wait for a successful TLS handshake with the datasource. Default is `10` seconds. For more details check the [Transport.TLSHandshakeTimeout](https://golang.org/pkg/net/http/#Transport.TLSHandshakeTimeout) documentation. +The length of time that Grafana waits for a successful TLS handshake with the data source. +Default is `10` seconds. +For more information, refer to the [`Transport.TLSHandshakeTimeout`](https://golang.org/pkg/net/http/#Transport.TLSHandshakeTimeout) documentation. -### expect_continue_timeout_seconds +#### `expect_continue_timeout_seconds` -The length of time that Grafana will wait for a datasource’s first response headers after fully writing the request headers, if the request has an “Expect: 100-continue” header. A value of `0` will result in the body being sent immediately. Default is `1` second. For more details check the [Transport.ExpectContinueTimeout](https://golang.org/pkg/net/http/#Transport.ExpectContinueTimeout) documentation. +The length of time that Grafana waits for the first response headers from a data source after fully writing the request headers, if the request has an `Expect: 100-continue` header. +A value of `0` results in the body being sent immediately. +Default is `1` second. +For more information, refer to the [`Transport.ExpectContinueTimeout`](https://golang.org/pkg/net/http/#Transport.ExpectContinueTimeout) documentation. -### max_conns_per_host +#### `max_conns_per_host` -Optionally limits the total number of connections per host, including connections in the dialing, active, and idle states. On limit violation, dials are blocked. A value of `0` means that there are no limits. Default is `0`. -For more details check the [Transport.MaxConnsPerHost](https://golang.org/pkg/net/http/#Transport.MaxConnsPerHost) documentation. +Limits the total number of connections per host, including connections in the dialing, active, and idle states. +On limit violation, dials are blocked. +A value of `0` means that there are no limits. +Default is `0`. +For more information, refer to the [`Transport.MaxConnsPerHost`](https://golang.org/pkg/net/http/#Transport.MaxConnsPerHost) documentation. -### max_idle_connections +#### `max_idle_connections` -The maximum number of idle connections that Grafana will maintain. Default is `100`. For more details check the [Transport.MaxIdleConns](https://golang.org/pkg/net/http/#Transport.MaxIdleConns) documentation. +The maximum number of idle connections that Grafana maintains. Default is `100`. +For more information, refer to the [`Transport.MaxIdleConns`](https://golang.org/pkg/net/http/#Transport.MaxIdleConns) documentation. -### idle_conn_timeout_seconds +#### `idle_conn_timeout_seconds` -The length of time that Grafana maintains idle connections before closing them. Default is `90` seconds. For more details check the [Transport.IdleConnTimeout](https://golang.org/pkg/net/http/#Transport.IdleConnTimeout) documentation. +The length of time that Grafana maintains idle connections before closing them. Default is `90` seconds. +For more information, refer to the [`Transport.IdleConnTimeout`](https://golang.org/pkg/net/http/#Transport.IdleConnTimeout) documentation. -### send_user_header +#### `send_user_header` -If enabled and user is not anonymous, data proxy will add X-Grafana-User header with username into the request. Default is `false`. +If enabled and user is not anonymous, data proxy adds the `X-Grafana-User` header with username into the request. Default is `false`. -### response_limit +#### `response_limit` -Limits the amount of bytes that will be read/accepted from responses of outgoing HTTP requests. Default is `0` which means disabled. +Limits the amount of bytes that Grafana reads from responses of outgoing HTTP requests. Default is `0` which means disabled. -### row_limit +#### `row_limit` -Limits the number of rows that Grafana will process from SQL (relational) data sources. Default is `1000000`. +Limits the number of rows that Grafana processes from SQL data sources. Default is `1000000`. -### user_agent +#### `user_agent` Sets a custom value for the `User-Agent` header for outgoing data proxy requests. If empty, the default value is `Grafana/` (for example `Grafana/9.0.0`).
-## [analytics] +### `[analytics]` -### enabled +#### `enabled` This option is also known as _usage analytics_. When `false`, this option disables the writers that write to the Grafana database and the associated features, such as dashboard and data source insights, presence indicators, and advanced dashboard search. The default value is `true`. -### reporting_enabled +#### `reporting_enabled` -When enabled Grafana will send anonymous usage statistics to -`stats.grafana.org`. No IP addresses are being tracked, only simple counters to -track running instances, versions, dashboard and error counts. It is very helpful -to us, so please leave this enabled. Counters are sent every 24 hours. Default -value is `true`. +When enabled Grafana sends anonymous usage statistics to `stats.grafana.org`. +Grafana doesn't track IP addresses, only counters of running instances, versions, dashboards, and errors. -### check_for_updates +The anonymous usage statistics help inform the future development of Grafana. +Counters are sent every 24 hours. +Default value is `true`. -Set to false, disables checking for new versions of Grafana from Grafana's GitHub repository. When enabled, the check for a new version runs every 10 minutes. It will notify, via the UI, when a new version is available. The check itself will not prompt any auto-updates of the Grafana software, nor will it send any sensitive information. +#### `check_for_updates` -### check_for_plugin_updates +Set to `false` to disable checking for new versions of Grafana in GitHub. +When enabled, the check for a new version runs every ten minutes. +It notifies, via the UI, when a new version is available. +The check itself doesn't cause automatic updates of the Grafana software, nor does it send any sensitive information. -Set to false disables checking for new versions of installed plugins from https://grafana.com. When enabled, the check for a new plugin runs every 10 minutes. It will notify, via the UI, when a new plugin update exists. The check itself will not prompt any auto-updates of the plugin, nor will it send any sensitive information. +#### `check_for_plugin_updates` -### google_analytics_ua_id +Set to `false` to disable checking for new versions of installed plugins from https://grafana.com. +When enabled, the check for a new plugin runs every ten minutes. +It notifies, via the UI, when a new plugin update exists. +The check itself doesn't cause any automatic updates of any plugins, nor does it send any sensitive information. -If you want to track Grafana usage via Google analytics specify _your_ Universal -Analytics ID here. By default this feature is disabled. +#### `google_analytics_ua_id` -### google_analytics_4_id +If you want to track Grafana usage with Google Analytics specify _your_ Universal Analytics ID here. +By default this feature is disabled. -If you want to track Grafana usage via Google Analytics 4 specify _your_ GA4 ID here. By default this feature is disabled. +#### `google_analytics_4_id` -### google_tag_manager_id +If you want to track Grafana usage with Google Analytics 4 specify _your_ GA4 ID here. +By default this feature is disabled. + +#### `google_tag_manager_id` Google Tag Manager ID, only enabled if you enter an ID here. -### rudderstack_write_key +#### `rudderstack_write_key` -If you want to track Grafana usage via Rudderstack specify _your_ Rudderstack +If you want to track Grafana usage via RudderStack specify _your_ RudderStack Write Key here. The `rudderstack_data_plane_url` must also be provided for this feature to be enabled. By default this feature is disabled. -### rudderstack_data_plane_url +#### `rudderstack_data_plane_url` -Rudderstack data plane url that will receive Rudderstack events. The -`rudderstack_write_key` must also be provided for this feature to be enabled. +RudderStack data plane URL to receive RudderStack events. +You must also provide the `rudderstack_write_key` to enable this feature. -### rudderstack_sdk_url +#### `rudderstack_sdk_url` -Optional. If tracking with Rudderstack is enabled, you can provide a custom -URL to load the Rudderstack SDK. +Optional. +If tracking with RudderStack is enabled, you can provide a custom URL to load the RudderStack SDK. -### rudderstack_config_url +#### `rudderstack_config_url` -Optional. If tracking with Rudderstack is enabled, you can provide a custom -URL to load the Rudderstack config. +Optional. +If tracking with RudderStack is enabled, you can provide a custom URL to load the RudderStack configuration. -### rudderstack_integrations_url +#### `rudderstack_integrations_url` -Optional. If tracking with Rudderstack is enabled, you can provide a custom -URL to load the SDK for destinations running in device mode. This setting is only valid for -Rudderstack version 1.1 and higher. +Optional. +If tracking with RudderStack is enabled, you can provide a custom URL to load the SDK for destinations running in device mode. +This setting is only valid for RudderStack version 1.1 and higher. -### application_insights_connection_string +#### `application_insights_connection_string` If you want to track Grafana usage via Azure Application Insights, then specify _your_ Application Insights connection string. Since the connection string contains semicolons, you need to wrap it in backticks (`). By default, tracking usage is disabled. -### application_insights_endpoint_url +#### `application_insights_endpoint_url` Optionally, use this option to override the default endpoint address for Application Insights data collecting. For details, refer to the [Azure documentation](https://docs.microsoft.com/en-us/azure/azure-monitor/app/custom-endpoints?tabs=js).
-### feedback_links_enabled +#### `feedback_links_enabled` Set to `false` to remove all feedback links from the UI. Default is `true`. -## [security] +### `[security]` -### disable_initial_admin_creation +#### `disable_initial_admin_creation` -Disable creation of admin user on first start of Grafana. Default is `false`. +Disable creation of a Grafana Admin user on first start of Grafana. Default is `false`. -### admin_user +#### `admin_user` The name of the default Grafana Admin user, who has full permissions. Default is `admin`. -### admin_password +#### `admin_password` The password of the default Grafana Admin. Set once on first-run. Default is `admin`. -### admin_email +#### `admin_email` The email of the default Grafana Admin, created on startup. Default is `admin@localhost`. -### secret_key +#### `secret_key` Used for signing some data source settings like secrets and passwords, the encryption format used is AES-256 in CFB mode. Cannot be changed without requiring an update to data source settings to re-encode them. -### disable_gravatar +#### `disable_gravatar` Set to `true` to disable the use of Gravatar for user profile images. Default is `false`. -### data_source_proxy_whitelist +#### `data_source_proxy_whitelist` -Define a whitelist of allowed IP addresses or domains, with ports, to be used in data source URLs with the Grafana data source proxy. Format: `ip_or_domain:port` separated by spaces. PostgreSQL, MySQL, and MSSQL data sources do not use the proxy and are therefore unaffected by this setting. +Define a allowlist of IP addresses or domains with ports, that can be used in data source URLs with the Grafana data source proxy. -### disable_brute_force_login_protection +The format is `` or `:` separated by spaces. +PostgreSQL, MySQL, and MSSQL data sources don't use the proxy and are not affected by this setting. -Set to `true` to disable [brute force login protection](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html#account-lockout). Default is `false`. An existing user's account will be unable to login for 5 minutes if all login attempts are spent within a 5 minute window. +#### `disable_brute_force_login_protection` -### brute_force_login_protection_max_attempts +Set to `true` to disable [brute force login protection](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html#account-lockout). +Default is `false`. +An existing user's account is unable to login for five minutes if all login attempts are spent within a 5 minute window. -Configure how many login attempts a user have within a 5 minute window before the account will be locked. Default is `5`. +#### `brute_force_login_protection_max_attempts` -### cookie_secure +Configure how many login attempts a user can have within a five minute window before their account is locked. +Default is `5`. + +#### `cookie_secure` Set to `true` if you host Grafana behind HTTPS. Default is `false`. -### cookie_samesite +#### `cookie_samesite` Sets the `SameSite` cookie attribute and prevents the browser from sending this cookie along with cross-site requests. The main goal is to mitigate the risk of cross-origin information leakage. This setting also provides some protection against cross-site request forgery attacks (CSRF), [read more about SameSite here](https://owasp.org/www-community/SameSite). Valid values are `lax`, `strict`, `none`, and `disabled`. Default is `lax`. Using value `disabled` does not add any `SameSite` attribute to cookies. -### allow_embedding +#### `allow_embedding` -When `false`, the HTTP header `X-Frame-Options: deny` will be set in Grafana HTTP responses which will instruct -browsers to not allow rendering Grafana in a ``, `