Installation on Grafana Labs

Configuration

Mon, 13 Apr 2026 16:15:04 -0700

Configuration

The Grafana back-end has a number of configuration options that can be specified in a .ini configuration file or specified using environment variables.

Config file locations

Default configuration from $WORKING_DIR/conf/defaults.ini
Custom configuration from $WORKING_DIR/conf/custom.ini
The custom configuration file path can be overridden using the --config parameter

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

Using environment variables

All options in the configuration file (listed below) can be overridden using environment variables using the syntax:

GF_<SectionName>_<KeyName>

Where the section name is the text within the brackets. Everything should be upper case, . should be replaced by _. For example, given these configuration settings:

# default section
instance_name = ${HOSTNAME}

[security]
admin_user = admin

[auth.google]
client_secret = 0ldS3cretKey

Then you can override them using:

export GF_DEFAULT_INSTANCE_NAME=my-instance
export GF_SECURITY_ADMIN_USER=true
export GF_AUTH_GOOGLE_CLIENT_SECRET=newS3cretKey

instance_name

Set the name of the grafana-server instance. Used in logging and internal metrics and in 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.

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. It can be overridden in the configuration file or in the default environment variable file.

[server]

http_addr

The IP address to bind to. If empty will bind to all interfaces

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:

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

Or redirect port 80 to the Grafana port using:

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

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

protocol

http or https

Note Grafana versions earlier than 3.0 are vulnerable to POODLE. So we strongly recommend to upgrade to 3.x or use a reverse proxy for ssl termination.

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 host header does not match 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.

static_root_path

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

cert_file

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

cert_key

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

router_logging

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

[database]

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 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. For example, for MySQL running on the same host as Grafana: host = 127.0.0.1:3306

name

The name of the Grafana database. Leave it set to grafana or some other name.

user

The database user (not applicable for sqlite3).

password

The database user’s password (not applicable for sqlite3). If the password contains # or ; you have to wrap it with trippel quotes. Ex """#password;"""

ssl_mode

For Postgres, use either disable, require or verify-full. For MySQL, use either true, false, or skip-verify.

ca_cert_path

(MySQL only) The path to the CA certificate to use. On many linux systems, certs can be found in /etc/ssl/certs.

client_key_path

(MySQL only) The path to the client key. Only if server requires client authentication.

client_cert_path

(MySQL only) The path to the client cert. Only if server requires client authentication.

server_cert_name

(MySQL only) The common name field of the certificate used by the mysql server. Not necessary if ssl_mode is set to skip-verify.

[security]

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 keep me logged in / remember me cookies.

disable_gravatar

Set to true to disable the use of Gravatar for user profile images. Default is false.

data_source_proxy_whitelist

Define a white list of allowed ips/domains to use in data sources. Format: ip_or_domain:port separated by spaces

[users]

allow_sign_up

Set to false to prohibit users from being able to sign up / create user accounts. Defaults to true. The admin user can still create users from the Grafana Admin Pages

allow_org_create

Set to false to prohibit users from creating new organizations. Defaults to true.

auto_assign_org

Set to true to automatically add new users to the main organization (id 1). When set to false, new users will automatically cause a new organization to be created for that new user.

auto_assign_org_role

The role new users will be assigned for the main organization (if the above setting is set to true). Defaults to Viewer, other valid options are Admin and Editor and Read Only Editor. e.g. :

auto_assign_org_role = Read Only Editor

[auth]

disable_login_form

Set to true to disable (hide) the login form, useful if you use OAuth, defaults to false.

disable_signout_menu

Set to true to disable the signout link in the side menu. useful if you use auth.proxy, defaults to false.

[auth.anonymous]

enabled

Set to true to enable anonymous access. Defaults to false

org_name

Set the organization name that should be used for anonymous users. If you change your organization name in the Grafana UI this setting needs to be updated to match the new name.

org_role

Specify role for anonymous users. Defaults to Viewer, other valid options are Editor and Admin.

[auth.github]

You need to create a GitHub application (you find this under the GitHub profile page). When you create the application you will need to specify a callback URL. Specify this as callback:

http://<my_grafana_server_name_or_ip>:<grafana_server_port>/login/github

This callback URL must match the full HTTP address that you use in your browser to access Grafana, but with the prefix path of /login/github. When the GitHub application is created you will get a Client ID and a Client Secret. Specify these in the Grafana configuration file. For example:

[auth.github]
enabled = true
allow_sign_up = true
client_id = YOUR_GITHUB_APP_CLIENT_ID
client_secret = YOUR_GITHUB_APP_CLIENT_SECRET
scopes = user:email
auth_url = https://github.com/login/oauth/authorize
token_url = https://github.com/login/oauth/access_token
api_url = https://api.github.com/user
team_ids =
allowed_organizations =

Restart the Grafana back-end. You should now see a GitHub login button on the login page. You can now login or sign up with your GitHub accounts.

You may allow users to sign-up via GitHub authentication by setting the allow_sign_up option to true. When this option is set to true, any user successfully authenticating via GitHub authentication will be automatically signed up.

team_ids

Require an active team membership for at least one of the given teams on GitHub. If the authenticated user isn’t a member of at least one of the teams they will not be able to register or authenticate with your Grafana instance. For example:

[auth.github]
enabled = true
client_id = YOUR_GITHUB_APP_CLIENT_ID
client_secret = YOUR_GITHUB_APP_CLIENT_SECRET
scopes = user:email,read:org
team_ids = 150,300
auth_url = https://github.com/login/oauth/authorize
token_url = https://github.com/login/oauth/access_token
allow_sign_up = true

allowed_organizations

Require an active organization membership for at least one of the given organizations on GitHub. If the authenticated user isn’t a member of at least one of the organizations they will not be able to register or authenticate with your Grafana instance. For example

[auth.github]
enabled = true
client_id = YOUR_GITHUB_APP_CLIENT_ID
client_secret = YOUR_GITHUB_APP_CLIENT_SECRET
scopes = user:email,read:org
auth_url = https://github.com/login/oauth/authorize
token_url = https://github.com/login/oauth/access_token
allow_sign_up = true
# space-delimited organization names
allowed_organizations = github google

[auth.google]

You need to create a Google project. You can do this in the Google Developer Console. When you create the project you will need to specify a callback URL. Specify this as callback:

http://<my_grafana_server_name_or_ip>:<grafana_server_port>/login/google

This callback URL must match the full HTTP address that you use in your browser to access Grafana, but with the prefix path of /login/google. When the Google project is created you will get a Client ID and a Client Secret. Specify these in the Grafana configuration file. For example:

[auth.google]
enabled = true
client_id = YOUR_GOOGLE_APP_CLIENT_ID
client_secret = YOUR_GOOGLE_APP_CLIENT_SECRET
scopes = https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email
auth_url = https://accounts.google.com/o/oauth2/auth
token_url = https://accounts.google.com/o/oauth2/token
allowed_domains = mycompany.com mycompany.org
allow_sign_up = true

Restart the Grafana back-end. You should now see a Google login button on the login page. You can now login or sign up with your Google accounts. The allowed_domains option is optional, and domains were separated by space.

You may allow users to sign-up via Google authentication by setting the allow_sign_up option to true. When this option is set to true, any user successfully authenticating via Google authentication will be automatically signed up.

[auth.generic_oauth]

This option could be used if have your own oauth service.

This callback URL must match the full HTTP address that you use in your browser to access Grafana, but with the prefix path of /login/generic_oauth.

[auth.generic_oauth]
enabled = true
client_id = YOUR_APP_CLIENT_ID
client_secret = YOUR_APP_CLIENT_SECRET
scopes =
auth_url =
token_url =
api_url =
allowed_domains = mycompany.com mycompany.org
allow_sign_up = true

Set api_url to the resource that returns OpenID UserInfo compatible information.

[auth.basic]

enabled

When enabled is true (default) the http api will accept basic authentication.

[auth.ldap]

enabled

Set to true to enable LDAP integration (default: false)

config_file

Path to the LDAP specific configuration file (default: /etc/grafana/ldap.toml)

allow_sign_up

Allow sign up should almost always be true (default) to allow new Grafana users to be created (if ldap authentication is ok). If set to false only pre-existing Grafana users will be able to login (if ldap authentication is ok).

For details on LDAP Configuration, go to the LDAP Integration page.

[auth.proxy]

This feature allows you to handle authentication in a http reverse proxy.

enabled

Defaults to false

header_name

Defaults to X-WEBAUTH-USER

header_property

Defaults to username but can also be set to email

auto_sign_up

Set to true to enable auto sign up of users who do not exist in Grafana DB. Defaults to true.

[session]

provider

Valid values are memory, file, mysql, postgres, memcache or redis. Default is file.

provider_config

This option should be configured differently depending on what type of session provider you have configured.

file: session file path, e.g. data/sessions
mysql: go-sql-driver/mysql dsn config string, e.g. user:password@tcp(127.0.0.1:3306)/database_name
postgres: ex: user=a password=b host=localhost port=5432 dbname=c sslmode=require
memcache: ex: 127.0.0.1:11211
redis: ex: addr=127.0.0.1:6379,pool_size=100,prefix=grafana

If you use MySQL or Postgres as the session store you need to create the session table manually.

Mysql Example:

CREATE TABLE `session` (
    `key`       CHAR(16) NOT NULL,
    `data`      BLOB,
    `expiry`    INT(11) UNSIGNED NOT NULL,
    PRIMARY KEY (`key`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8;

Postgres Example:

CREATE TABLE session (
    key       CHAR(16) NOT NULL,
    data      BYTEA,
    expiry    INTEGER NOT NULL,
    PRIMARY KEY (key)
);

Postgres valid sslmode are disable, require (default), verify-ca, and verify-full.

cookie_name

The name of the Grafana session cookie.

cookie_secure

Set to true if you host Grafana behind HTTPS only. Defaults to false.

session_life_time

How long sessions lasts in seconds. Defaults to 86400 (24 hours).

[analytics]

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 & error counts. It is very helpful to us, so please leave this enabled. Counters are sent every 24 hours. Default value is true.

google_analytics_ua_id

If you want to track Grafana usage via Google analytics specify your Universal Analytics ID here. By default this feature is disabled.

[dashboards.json]

If you have a system that automatically builds dashboards as json files you can enable this feature to have the Grafana backend index those json dashboards which will make them appear in regular dashboard search.

enabled

true or false. Is disabled by default.

path

The full path to a directory containing your json dashboards.

[smtp]

Email server settings.

enabled

defaults to false

host

defaults to localhost:25

user

In case of SMTP auth, defaults to empty

password

In case of SMTP auth, defaults to empty

cert_file

File path to a cert file, defaults to empty

key_file

File path to a key file, defaults to empty

skip_verify

Verify SSL for smtp server? defaults to false

from_address

Address used when sending out emails, defaults to admin@grafana.localhost

from_name

Name to be used when sending out emails, defaults to Grafana

[log]

mode

Either “console”, “file”, “syslog”. Default is console and file Use space to separate multiple modes, e.g. “console file”

level

Either “debug”, “info”, “warn”, “error”, “critical”, default is “info”

filters

optional settings to set different levels for specific loggers. Ex filters = sqlstore:debug

[metrics]

enabled

Enable metrics reporting. defaults true. Available via HTTP API /api/metrics.

interval_seconds

Flush/Write interval when sending metrics to external TSDB. Defaults to 10s.

[metrics.graphite]

Include this section if you want to send internal Grafana metrics to Graphite.

address

Format <Hostname or ip>:port

prefix

Graphite metric prefix. Defaults to prod.grafana.%(instance_name)s.

[snapshots]

external_enabled

Set to false to disable external snapshot publish endpoint (default true)

external_snapshot_url

Set root url to a Grafana instance where you want to publish external snapshots (defaults to https://snapshots-origin.raintank.io)

external_snapshot_name

Set name for external snapshot button. Defaults to Publish to snapshot.raintank.io

remove expired snapshot

Enabled to automatically remove expired snapshots

remove snapshots after 90 days

Time to live for snapshots.

[external_image_storage]

These options control how images should be made public so they can be shared on services like slack.

provider

You can choose between (s3, webdav). If left empty Grafana will ignore the upload action.

[external_image_storage.s3]

bucket_url

Bucket URL for S3. AWS region can be specified within URL or defaults to ‘us-east-1’, e.g.

access_key

Access key. e.g. AAAAAAAAAAAAAAAAAAAA

Access key requires permissions to the S3 bucket for the ‘s3:PutObject’ and ‘s3:PutObjectAcl’ actions.

secret_key

Secret key. e.g. AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

[external_image_storage.webdav]

url

Url to where Grafana will send PUT request with images

public_url

Optional parameter. Url to send to users in notifications, directly appended with the resulting uploaded file name.

username

basic auth username

password

basic auth password

[alerting]

enabled

Defaults to true. Set to false to disable alerting engine and hide Alerting from UI.

execute_alerts

execute_alerts = true

Makes it possible to turn off alert rule execution.

Installing on Debian / Ubuntu

Mon, 13 Apr 2026 16:15:04 -0700

Installing on Debian / Ubuntu

Description	Download
Stable for Debian-based Linux	grafana_4.3.0_amd64.deb

Read Upgrading Grafana for tips and guidance on updating an existing installation.

Install Stable

wget https://s3-us-west-2.amazonaws.com/grafana-releases/release/grafana_4.2.0_amd64.deb
sudo apt-get install -y adduser libfontconfig
sudo dpkg -i grafana_4.2.0_amd64.deb

APT Repository

Add the following line to your /etc/apt/sources.list file.

deb https://packagecloud.io/grafana/stable/debian/ jessie main

Use the above line even if you are on Ubuntu or another Debian version. There is also a testing repository if you want beta or release candidates.

deb https://packagecloud.io/grafana/testing/debian/ jessie main

Then add the Package Cloud key. This allows you to install signed packages.

curl https://packagecloud.io/gpg.key | sudo apt-key add -

Update your Apt repositories and install Grafana

sudo apt-get update
sudo apt-get install grafana

On some older versions of Ubuntu and Debian you may need to install the apt-transport-https package which is needed to fetch packages over HTTPS.

sudo apt-get install -y apt-transport-https

Package details

Installs binary to /usr/sbin/grafana-server
Installs Init.d script to /etc/init.d/grafana-server
Creates default file (environment vars) to /etc/default/grafana-server
Installs configuration file to /etc/grafana/grafana.ini
Installs systemd service (if systemd is available) name grafana-server.service
The default configuration sets the log file at /var/log/grafana/grafana.log
The default configuration specifies an sqlite3 db at /var/lib/grafana/grafana.db

Start the server (init.d service)

Start Grafana by running:

sudo service grafana-server start

This will start the grafana-server process as the grafana user, which was created during the package installation. The default HTTP port is 3000 and default user and group is admin.

To configure the Grafana server to start at boot time:

sudo update-rc.d grafana-server defaults

Start the server (via systemd)

To start the service using systemd:

systemctl daemon-reload
systemctl start grafana-server
systemctl status grafana-server

Enable the systemd service so that Grafana starts at boot.

sudo systemctl enable grafana-server.service

Environment file

The systemd service file and init.d script both use the file located at /etc/default/grafana-server for environment variables used when starting the back-end. Here you can override log directory, data directory and other variables.

Logging

By default Grafana will log to /var/log/grafana

Database

The default configuration specifies a sqlite3 database located at /var/lib/grafana/grafana.db. Please backup this database before upgrades. You can also use MySQL or Postgres as the Grafana database, as detailed on the configuration page.

Configuration

The configuration file is located at /etc/grafana/grafana.ini. Go the Configuration page for details on all those options.

Adding data sources

Installing from binary tar file

Download the latest .tar.gz file and extract it. This will extract into a folder named after the version you downloaded. This folder contains all files required to run Grafana. There are no init scripts or install scripts in this package.

To configure Grafana add a configuration file named custom.ini to the conf folder and override any of the settings defined in conf/defaults.ini.

Start Grafana by executing ./bin/grafana-server web. The grafana-server binary needs the working directory to be the root install directory (where the binary and the public folder is located).

Installing on Mac

Mon, 13 Apr 2026 16:15:04 -0700

Installing on Mac

Installation can be done using homebrew

Install latest stable:

brew update
brew install grafana

To start grafana look at the command printed after the homebrew install completes.

To upgrade use the reinstall command

brew update
brew reinstall grafana

You can also install the latest unstable grafana from git:

brew install --HEAD grafana/grafana/grafana

To upgrade grafana if you’ve installed from HEAD:

brew reinstall --HEAD grafana/grafana/grafana

Installing on RPM-based Linux

Mon, 13 Apr 2026 16:15:04 -0700

Installing on RPM-based Linux (CentOS, Fedora, OpenSuse, RedHat)

Description	Download
Stable for CentOS / Fedora / OpenSuse / Redhat Linux	4.3.0 (x86-64 rpm)

Read Upgrading Grafana for tips and guidance on updating an existing installation.

Install Stable

You can install Grafana using Yum directly.

$ sudo yum install https://s3-us-west-2.amazonaws.com/grafana-releases/release/grafana-4.2.0-1.x86_64.rpm

Or install manually using rpm.

On CentOS / Fedora / Redhat:

$ wget https://s3-us-west-2.amazonaws.com/grafana-releases/release/grafana-4.2.0-1.x86_64.rpm
$ sudo yum install initscripts fontconfig
$ sudo rpm -Uvh grafana-4.2.0-1.x86_64.rpm

On OpenSuse:

$ sudo rpm -i --nodeps grafana-4.2.0-1.x86_64.rpm

Install via YUM Repository

Add the following to a new file at /etc/yum.repos.d/grafana.repo

[grafana]
name=grafana
baseurl=https://packagecloud.io/grafana/stable/el/6/$basearch
repo_gpgcheck=1
enabled=1
gpgcheck=1
gpgkey=https://packagecloud.io/gpg.key https://grafanarel.s3.amazonaws.com/RPM-GPG-KEY-grafana
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt

There is also a testing repository if you want beta or release candidates.

baseurl=https://packagecloud.io/grafana/testing/el/6/$basearch

Then install Grafana via the yum command.

$ sudo yum install grafana

RPM GPG Key

The RPMs are signed, you can verify the signature with this public GPG key.

Package details

Installs binary to /usr/sbin/grafana-server
Copies init.d script to /etc/init.d/grafana-server
Installs default file (environment vars) to /etc/sysconfig/grafana-server
Copies configuration file to /etc/grafana/grafana.ini
Installs systemd service (if systemd is available) name grafana-server.service
The default configuration uses a log file at /var/log/grafana/grafana.log
The default configuration specifies an sqlite3 database at /var/lib/grafana/grafana.db

Start the server (init.d service)

You can start Grafana by running:

$ sudo service grafana-server start

This will start the grafana-server process as the grafana user, which is created during package installation. The default HTTP port is 3000, and default user and group is admin.

To configure the Grafana server to start at boot time:

$ sudo /sbin/chkconfig --add grafana-server

Start the server (via systemd)

$ systemctl daemon-reload
$ systemctl start grafana-server
$ systemctl status grafana-server

Enable the systemd service to start at boot

sudo systemctl enable grafana-server.service

Environment file

The systemd service file and init.d script both use the file located at /etc/sysconfig/grafana-server for environment variables used when starting the back-end. Here you can override log directory, data directory and other variables.

Logging

By default Grafana will log to /var/log/grafana

Database

Configuration

The configuration file is located at /etc/grafana/grafana.ini. Go the Configuration page for details on all those options.

Adding data sources

Server side image rendering

Server side image (png) rendering is a feature that is optional but very useful when sharing visualizations, for example in alert notifications.

If the image is missing text make sure you have font packages installed.

yum install fontconfig
yum install freetype*
yum install urw-fonts

Installing from binary tar file

To configure Grafana add a configuration file named custom.ini to the conf folder and override any of the settings defined in conf/defaults.ini.

Start Grafana by executing ./bin/grafana-server web. The grafana-server binary needs the working directory to be the root install directory (where the binary and the public folder is located).

Installing on Windows

Mon, 13 Apr 2026 16:15:04 -0700

Installing on Windows

Description	Download
Latest stable package for Windows	grafana.4.3.0.windows-x64.zip

Read Upgrading Grafana for tips and guidance on updating an existing installation.

Configure

The zip file contains a folder with the current Grafana version. Extract this folder to anywhere you want Grafana to run from. Go into the conf directory and copy sample.ini to custom.ini. You should edit custom.ini, never defaults.ini.

The default Grafana port is 3000, this port requires extra permissions on windows. Edit custom.ini and uncomment the http_port configuration option and change it to something like 8080 or similar. That port should not require extra Windows privileges.

Start Grafana by executing grafana-server.exe, preferably from the command line. If you want to run Grafana as windows service, download NSSM. It is very easy add Grafana as a Windows service using that tool.

Read more about the configuration options.

Building on Windows

The Grafana backend includes Sqlite3 which requires GCC to compile. So in order to compile Grafana on Windows you need to install GCC. We recommend TDM-GCC.

Copy conf/sample.ini to a file named conf/custom.ini and change the web server port to something like 8080. The default Grafana port, 3000, requires special privileges on Windows.

Installing using Docker

Mon, 13 Apr 2026 16:15:04 -0700

Installing using Docker

Grafana is very easy to install and run using the official docker container.

$ docker run -i -p 3000:3000 grafana/grafana

All Grafana configuration settings can be defined using environment variables, this is especially useful when using the above container.

Docker volumes & ENV config

The Docker container exposes two volumes, the sqlite3 database in the folder /var/lib/grafana and configuration files is in /etc/grafana/ folder. You can map these volumes to host folders when you start the container:

$ docker run -d -p 3000:3000 \
    -v /var/lib/grafana:/var/lib/grafana \
    -e "GF_SECURITY_ADMIN_PASSWORD=secret" \
    grafana/grafana

In the above example I map the data folder and sets a configuration option via an ENV instruction.

Configuration

The back-end web server has a number of configuration options. Go the Configuration page for details on all those options.

LDAP Authentication

Mon, 13 Apr 2026 16:15:04 -0700

LDAP Authentication

Grafana (2.1 and newer) ships with a strong LDAP integration feature. The LDAP integration in Grafana allows your Grafana users to login with their LDAP credentials. You can also specify mappings between LDAP group memberships and Grafana Organization user roles.

Configuration

You turn on LDAP in the main config file as well as specify the path to the LDAP specific configuration file (default: /etc/grafana/ldap.toml).

Example config

# Set to true to log user information returned from LDAP
verbose_logging = false

[[servers]]
# Ldap server host (specify multiple hosts space separated)
host = "127.0.0.1"
# Default port is 389 or 636 if use_ssl = true
port = 389
# Set to true if ldap server supports TLS
use_ssl = false
# Set to true if connect ldap server with STARTTLS pattern (create connection in insecure, then upgrade to secure connection with TLS)
start_tls = false
# set to true if you want to skip ssl cert validation
ssl_skip_verify = false
# set to the path to your root CA certificate or leave unset to use system defaults
# root_ca_cert = "/path/to/certificate.crt"

# Search user bind dn
bind_dn = "cn=admin,dc=grafana,dc=org"
# Search user bind password
# If the password contains # or ; you have to wrap it with trippel quotes. Ex """#password;"""
bind_password = 'grafana'

# User search filter, for example "(cn=%s)" or "(sAMAccountName=%s)" or "(uid=%s)"
search_filter = "(cn=%s)"

# An array of base dns to search through
search_base_dns = ["dc=grafana,dc=org"]

# In POSIX LDAP schemas, without memberOf attribute a secondary query must be made for groups.
# This is done by enabling group_search_filter below. You must also set member_of= "cn"
# in [servers.attributes] below.

## Group search filter, to retrieve the groups of which the user is a member (only set if memberOf attribute is not available)
# group_search_filter = "(&(objectClass=posixGroup)(memberUid=%s))"
## An array of the base DNs to search through for groups. Typically uses ou=groups
# group_search_base_dns = ["ou=groups,dc=grafana,dc=org"]

# Specify names of the ldap attributes your ldap uses
[servers.attributes]
name = "givenName"
surname = "sn"
username = "cn"
member_of = "memberOf"
email =  "email"

# Map ldap groups to grafana org roles
[[servers.group_mappings]]
group_dn = "cn=admins,dc=grafana,dc=org"
org_role = "Admin"
# The Grafana organization database id, optional, if left out the default org (id 1) will be used.  Setting this allows for multiple group_dn's to be assigned to the same org_role provided the org_id differs
# org_id = 1

[[servers.group_mappings]]
group_dn = "cn=users,dc=grafana,dc=org"
org_role = "Editor"

[[servers.group_mappings]]
# If you want to match all (or no ldap groups) then you can use wildcard
group_dn = "*"
org_role = "Viewer"

Bind & Bind Password

By default the configuration expects you to specify a bind DN and bind password. This should be a read only user that can perform LDAP searches. When the user DN is found a second bind is performed with the user provided username & password (in the normal Grafana login form).

bind_dn = "cn=admin,dc=grafana,dc=org"
bind_password = "grafana"

Single Bind Example

If you can provide a single bind expression that matches all possible users, you can skip the second bind and bind against the user DN directly. This allows you to not specify a bind_password in the configuration file.

bind_dn = "cn=%s,o=users,dc=grafana,dc=org"

In this case you skip providing a bind_password and instead provide a bind_dn value with a %s somewhere. This will be replaced with the username entered in on the Grafana login page. The search filter and search bases settings are still needed to perform the LDAP search to retrieve the other LDAP information (like LDAP groups and email).

POSIX schema (no memberOf attribute)

If your ldap server does not support the memberOf attribute add these options:

## Group search filter, to retrieve the groups of which the user is a member (only set if memberOf attribute is not available)
group_search_filter = "(&(objectClass=posixGroup)(memberUid=%s))"
## An array of the base DNs to search through for groups. Typically uses ou=groups
group_search_base_dns = ["ou=groups,dc=grafana,dc=org"]

Also change set member_of = "cn" in the [servers.attributes] section.

LDAP to Grafana Org Role Sync

Mappings

In [[servers.group_mappings]] you can map an LDAP group to a Grafana organization and role. These will be synced every time the user logs in, with LDAP being the authoritative source. So, if you change a user’s role in the Grafana Org. Users page, this change will be reset the next time the user logs in. If you change the LDAP groups of a user, the change will take effect the next time the user logs in.

Priority

The first group mapping that an LDAP user is matched to will be used for the sync. If you have LDAP users that fit multiple mappings, the topmost mapping in the TOML config will be used.

Migrating from older versions

Mon, 13 Apr 2026 16:15:04 -0700

Migrating from older versions

Normally new versions of Grafana are backward compatible. Any changes to database or dashboard schema will be automatically migrated when Grafana-server start up without any user action required.

Migrating from v1.x to v2.x

Grafana 2.0 represents a major update to Grafana. It brings new capabilities, many of which are enabled by its new back-end server and integrated database.

The new back-end lays a solid foundation that we hope to build on over the coming months. For the 2.0 release, it enables authentication as well as server-side sharing and rendering.

We’ve attempted to provide a smooth migration path for v1.9 users to migrate to Grafana 2.0.

Adding Data sources

The config.js file has been deprecated. Data sources are now managed via the UI or HTTP API. Manage your organizations data sources by clicking on the Data Sources menu on the side menu (which can be toggled via the Grafana icon in the upper left of your browser).

From here, you can add any Graphite, InfluxDB, elasticsearch, and OpenTSDB data sources that you were using with Grafana 1.x. Grafana 2.0 can be configured to communicate with your data source using a back-end mode which can eliminate many CORS-related issues, as well as provide more secure authentication to your data sources.

Note When you add your data sources please name them exactly as you named them in config.js in Grafana 1.x. That name is referenced by panels, annotation and template queries. That way when you import your old dashboard they will work without any changes.

Importing your existing dashboards

Grafana 2.0 now has integrated dashboard storage engine that can be configured to use an internal sqlite3 database, MySQL, or Postgres. This eliminates the need to use Elasticsearch for dashboard storage for Graphite users. Grafana 2.0 does not support storing dashboards in InfluxDB.

You can seamlessly import your existing dashboards.

Importing dashboards from Elasticsearch

Start by going to the Data Sources view (via the side menu), and make sure your Elasticsearch data source is added. Specify the Elasticsearch index name where your existing Grafana v1.x dashboards are stored (the default is grafana-dash).

Importing dashboards from InfluxDB

Start by going to the Data Sources view (via the side menu), and make sure your InfluxDB data source is added. Specify the database name where your Grafana v1.x dashboards are stored, the default is grafana.

Go to Import dashboards view

Go to the Dashboards view and click on the dashboards search drop down. Click the Import button at the bottom of the search drop down.

Import view

In the Import view you find the section Migrate dashboards. Pick the data source you added (from Elasticsearch or InfluxDB), and click the Import button.

Your dashboards should be automatically imported into the Grafana 2.0 back-end.

Dashboards will no longer be stored in your previous Elasticsearch or InfluxDB databases.

Invite your team

Explain users and orgs.

Enjoy the new features

Running Grafana behind a reverse proxy

Mon, 13 Apr 2026 16:15:04 -0700

Running Grafana behind a reverse proxy

It should be straight forward to get Grafana up and running behind a reverse proxy. But here are some things that you might run into.

Links and redirects will not be rendered correctly unless you set the server.domain setting.

[server]
domain = foo.bar

To use sub path ex http://foo.bar/grafana make sure to include /grafana in the end of root_url. Otherwise Grafana will not behave correctly. See example below.

Examples

Here are some example configurations for running Grafana behind a reverse proxy.

Grafana configuration (ex http://foo.bar.com)

[server]
domain = foo.bar

Nginx configuration

server {
  listen 80;
  root /usr/share/nginx/www;
  index index.html index.htm;

  location / {
   proxy_pass http://localhost:3000/;
  }
}

Examples with sub path (ex http://foo.bar.com/grafana)

Grafana configuration with sub path

[server]
domain = foo.bar
root_url = %(protocol)s://%(domain)s:/grafana

Nginx configuration with sub path

server {
  listen 80;
  root /usr/share/nginx/www;
  index index.html index.htm;

  location /grafana/ {
   proxy_pass http://localhost:3000/;
  }
}

Troubleshooting

Mon, 13 Apr 2026 16:15:04 -0700

Troubleshooting

visualization & query issues

The most common problems are related to the query & response from you data source. Even if it looks like a bug or visualization issue in Grafana it is 99% of time a problem with the data source query or the data source response.

So make sure to check the query sent and the raw response, learn how in this guide: How to troubleshoot metric query issues

Logging

If you encounter an error or problem it is a good idea to check the grafana server log. Usually located at /var/log/grafana/grafana.log on unix systems or in <grafana_install_dir>/data/log on other platforms & manual installs.

You can enable more logging by changing log level in you grafana configuration file.

FAQ

Checkout the FAQ section on our community page for frequently asked questions.

Upgrading

Mon, 13 Apr 2026 16:15:04 -0700

Upgrading Grafana

We recommend everyone to upgrade Grafana often to stay up to date with the latest fixes and enhancements. In order make this a reality Grafana upgrades are backward compatible and the upgrade process is simple & quick.

Upgrading is generally always safe (between many minor and one major version) and dashboards and graphs will look the same. There can be minor breaking changes in some edge cases which are usually outlined in the Release Notes and Changelog

Database Backup

Before upgrading it can be a good idea to backup your Grafana database. This will ensure that you can always rollback to your previous version. During startup, Grafana will automatically migrate the database schema (if there are changes or new tables). Sometimes this can cause issues if you later want to downgrade.

sqlite

If you use sqlite you only need to make a backup of you grafana.db file. This is usually located at /var/lib/grafana/grafana.db on unix system. If you are unsure what database you use and where it is stored check you grafana configuration file. If you installed grafana to custom location using a binary tar/zip it is usually in <grafana_install_dir>/data.

mysql

backup:
> mysqldump -u root -p[root_password] [grafana] > grafana_backup.sql

restore:
> mysql -u root -p grafana < grafana_backup.sql

postgres

backup:
> pg_dump grafana > grafana_backup

restore:
> psql grafana < grafana_backup

Ubuntu / Debian

If you installed grafana by downloading a debian package (.deb) you can just follow the same installation guide and execute the same dpkg -i command but with the new package. It will upgrade your Grafana install.

If you used our APT repository:

sudo apt-get update
sudo apt-get install grafana

Upgrading from binary tar file

If you downloaded the binary tar package you can just download and extract a new package and overwrite all your existing files. But this might overwrite your config changes. We recommend you place your config changes in a file named <grafana_install_dir>/conf/custom.ini as this will make upgrades easier without risking losing your config changes.

Centos / RHEL

If you installed grafana by downloading a rpm package you can just follow the same installation guide and execute the same yum install or rpm -i command but with the new package. It will upgrade your Grafana install.

If you used our YUM repository:

sudo yum update grafana

Docker

This just an example, details depend on how you configured your grafana container.

docker pull grafana
docker stop my-grafana-container
docker rm my-grafana-container
docker run --name=my-grafana-container --restart=always -v /var/lib/grafana:/var/lib/grafana

Windows

If you downloaded the windows binary package you can just download a newer package and extract to the same location (and overwrite the existing files). This might overwrite your config changes. We recommend you place your config changes in a file named <grafana_install_dir>/conf/custom.ini as this will make upgrades easier without risking losing your config changes.

Upgrading form 1.x

Migrating from 1.x to 2.x

Upgrading form 2.x

We are not aware of any issues upgrading directly from 2.x to 4.x but to on the safe side go via 3.x.