diff --git a/docs/sources/_index.md b/docs/sources/_index.md index 58f34b46b41..7b50a3734e5 100755 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -53,7 +53,7 @@ aliases = ["/docs/grafana/v1.1", "/docs/grafana/latest/guides/reference/admin",

Getting started

Learn the basics of using Grafana.

- }}" class="nav-cards__item nav-cards__item--guide"> + }}" class="nav-cards__item nav-cards__item--guide">

Configure Grafana

Review the configuration and setup options.

diff --git a/docs/sources/administration/cli.md b/docs/sources/administration/cli.md index 75e51d1b1f2..5b02f04a78b 100644 --- a/docs/sources/administration/cli.md +++ b/docs/sources/administration/cli.md @@ -130,7 +130,7 @@ grafana-cli --homepath "c:\Program Files\grafana" admin reset-admin-password myn ### Override config file -`--config value` overrides the default location where Grafana expects the configuration file. Refer to [Configuration]({{< relref "../installation/configuration.md" >}}) for more information about configuring Grafana and default configuration file locations. +`--config value` overrides the default location where Grafana expects the configuration file. Refer to [Configuration]({{< relref "../administration/configuration.md" >}}) for more information about configuring Grafana and default configuration file locations. **Example:** ```bash diff --git a/docs/sources/installation/configuration.md b/docs/sources/administration/configuration.md similarity index 60% rename from docs/sources/installation/configuration.md rename to docs/sources/administration/configuration.md index 459177041f9..1d5ce776e57 100644 --- a/docs/sources/installation/configuration.md +++ b/docs/sources/administration/configuration.md @@ -3,6 +3,7 @@ title = "Configuration" description = "Configuration documentation" keywords = ["grafana", "configuration", "documentation"] type = "docs" +aliases = ["/docs/grafana/latest/installation/configuration/"] [menu.docs] name = "Configuration" identifier = "config" @@ -83,17 +84,24 @@ export GF_PLUGIN_GRAFANA_IMAGE_RENDERER_RENDERING_IGNORE_HTTPS_ERRORS=true > For any changes to `conf/grafana.ini` (or corresponding environment variables) to take effect, you must restart Grafana for the changes to take effect. +
+ +## 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. +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` @@ -104,7 +112,7 @@ How long temporary images in `data` directory should be kept. Defaults to: `24h` ### logs -Path to where Grafana will store 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. 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.log`: @@ -116,16 +124,24 @@ Override log path using the command line argument `cfg:default.paths.log`: ### plugins -Directory where Grafana will automatically scan and look for plugins. Manually or automatically install any plugins here. +Directory where Grafana automatically scans and looks for plugins. Manually or automatically install any plugins here. **macOS:** By default, the Mac plugin location is: `/usr/local/var/lib/grafana/plugins`. ### 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 +Folder that contains [provisioning]({{< relref "provisioning.md" >}}) config files that grafana will apply on startup. Dashboards will be reloaded when the json files changes + +
## [server] +### protocol + +`http`,`https`,`h2` or `socket` + +> **Note:** Grafana versions earlier than 3.0 are vulnerable to [POODLE](https://en.wikipedia.org/wiki/POODLE). So we strongly recommend to upgrade to 3.x or use a reverse proxy for SSL termination. + ### http_addr The IP address to bind to. If empty will bind to all interfaces @@ -146,15 +162,6 @@ $ sudo iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 300 Another way is put a webserver like Nginx or Apache in front of Grafana and have them proxy requests to Grafana. -### protocol - -`http`,`https`,`h2` or `socket` - -> **Note:** Grafana versions earlier than 3.0 are vulnerable to [POODLE](https://en.wikipedia.org/wiki/POODLE). So we strongly recommend to upgrade to 3.x or use a reverse proxy for SSL termination. - -### socket -Path where the socket should be created when `protocol=socket`. Please make sure that Grafana has appropriate permissions. - ### 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. @@ -174,14 +181,19 @@ callback URL to be correct). > case add the subpath to the end of this URL setting. ### serve_from_sub_path -> Available in 6.3 and above + +> Available in Grafana 6.3+. 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 will be accessible on +`root_url = http://localhost:3000/grafana`, Grafana is accessible on `http://localhost:3000/grafana`. +### 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 @@ -203,10 +215,9 @@ Path to the certificate file (if `protocol` is set to `https` or `h2`). Path to the certificate key file (if `protocol` is set to `https` or `h2`). -### router_logging +### socket -Set to `true` for Grafana to log all HTTP requests (not just errors). These are logged as Info level events -to grafana log. +Path where the socket should be created when `protocol=socket`. Make sure that Grafana has appropriate permissions before you change this setting.
@@ -216,20 +227,10 @@ Grafana needs a database to store users and dashboards (and other things). By default it is configured to use `sqlite3` which is an embedded database (included in the main Grafana binary). -### url - -Use either URL or the other fields below to configure the database -Example: `mysql://user:secret@host:port/database` - ### type Either `mysql`, `postgres` or `sqlite3`, it's your choice. -### path - -Only applicable for `sqlite3` database. The file path where the database -will be stored. - ### host Only applicable to MySQL or Postgres. Includes IP or hostname and port or in case of Unix sockets the path to it. @@ -249,6 +250,25 @@ The database user (not applicable for `sqlite3`). 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 + +Use either URL or the other fields below to configure the database +Example: `mysql://user:secret@host:port/database` + +### max_idle_conn +The maximum number of connections in the idle connection pool. + +### max_open_conn +The maximum number of open connections to the database. + +### 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. + +### log_queries + +Set to `true` to log the sql calls and execution times. + ### ssl_mode For Postgres, use either `disable`, `require` or `verify-full`. @@ -270,19 +290,10 @@ The path to the client cert. Only if server requires client authentication. The common name field of the certificate used by the `mysql` or `postgres` server. Not necessary if `ssl_mode` is set to `skip-verify`. -### max_idle_conn -The maximum number of connections in the idle connection pool. +### path -### max_open_conn -The maximum number of open connections to the database. - -### 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. - -### log_queries - -Set to `true` to log the sql calls and execution times. +Only applicable for `sqlite3` database. The file path where the database +will be stored. ### cache_mode @@ -295,17 +306,17 @@ Defaults to `private`. ### type -Either `redis`, `memcached` or `database`. Defaults to `database` +Either `redis`, `memcached`, or `database`. Defaults to `database` ### connstr -The remote cache connection string. The format depends on the `type` of the remote cache. +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. -#### Redis +#### redis Example connstr: `addr=127.0.0.1:6379,pool_size=100,db=0,ssl=false` @@ -314,167 +325,12 @@ Example connstr: `addr=127.0.0.1:6379,pool_size=100,db=0,ssl=false` - `db` (optional) is the number indentifer 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`
-## [security] - -### disable_initial_admin_creation - -> Only available in Grafana v6.5+. - -Disable creation of admin user on first start of grafana. - -### admin_user - -The name of the default Grafana admin user (who has full permissions). -Defaults to `admin`. - -### admin_password - -The password of the default Grafana admin. Set once on first-run. Defaults to `admin`. - -### login_remember_days - -The number of days the keep me logged in / remember me cookie lasts. - -### 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 - -Set to `true` to disable the use of Gravatar for user profile images. -Default is `false`. - -### 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. - -### cookie_secure - -Set to `true` if you host Grafana behind HTTPS. Default is `false`. - -### disable_brute_force_login_protection - -Set to `true` to disable [brute force login protection](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html#account-lockout). Default is `false`. - -### 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://www.owasp.org/index.php/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 - -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 ``, `