diff --git a/docs/sources/enterprise/activate-license.md b/docs/sources/enterprise/activate-license.md index 77c6d769067..69861b5d6d7 100644 --- a/docs/sources/enterprise/activate-license.md +++ b/docs/sources/enterprise/activate-license.md @@ -11,22 +11,30 @@ Follow these steps to activate your Grafana Enterprise license: ## Step 1. Download your license file -To download your Grafana Enterprise license, log in to your [Grafana Cloud Account](https://grafana.com) and go to your **Org Profile**. In the side menu there is a section for Grafana Enterprise licenses. At the bottom of the license details page there is **Download Token** link that will download the license.jwt file containing your license. +To download your Grafana Enterprise license: -## Step 2. Add your license file to a Grafana instance + 1. Log in to your [Grafana Cloud Account](https://grafana.com). + 1. Go to your **Org Profile**. + 1. Go to the section for Grafana Enterprise licenses in the side menu. + 1. At the bottom of the license details page there is **Download Token** link that will download the *license.jwt* file containing your license to your computer. -There are two different ways to add the license file to a Grafana instance: +## Step 2. Add your license to a Grafana instance -- Option 1: Upload the license file through the Grafana Server Administrator page +There are three different ways to add the license to a Grafana instance: + +### Upload the license file through the Grafana Server Administrator page + + This is the preferred option for single instance installations of + Grafana Enterprise. 1. Sign in as a Grafana server admin. 1. Navigate to **Server Admin > Upgrade** within Grafana. 1. Click **Upload license token file**. 1. Select your license file, and upload it. -- Option 2: Place the *license.jwt* file in Grafana's data folder. +### Place the license.jwt file in Grafana's data folder - This is usually located at `/var/lib/grafana` on Linux systems. + The data folder is usually `/var/lib/grafana` on Linux systems. You can also configure a custom location for the license file using the grafana.ini setting: @@ -37,7 +45,20 @@ There are two different ways to add the license file to a Grafana instance: This setting can also be set with an environment variable, which is useful if you're running Grafana with Docker and have a custom volume where you have placed the license file. In this case, set the environment variable `GF_ENTERPRISE_LICENSE_PATH` to point to the location of your license file. -## Step 3. Ensure that the license file's root url matches the root_url configuration option +### Set the content of the license file as a configuration option + + You can add a license by pasting the content of the `license.jwt` + to the grafana.ini configuration file: + + ```bash + [enterprise] + license_text = eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aGlzIjoiaXMiLCJub3QiOiJhIiwidmFsaWQiOiJsaWNlbnNlIn0.bxDzxIoJlYMwiEYKYT_l2s42z0Y30tY-6KKoyz9RuLE + ``` + + This option can be set using the `GF_ENTERPRISE_LICENSE_TEXT` + environment variable. + +## Step 3. Ensure that the license file's root URL matches the root_url configuration option Update the [`root_url`]({{< relref "../administration/configuration/#root-url" >}}) in your configuration. It should be the URL that users type in their browsers to access the frontend, not the node hostname(s). @@ -55,3 +76,11 @@ Or with an environment variable: ``` GF_SERVER_ROOT_URL=https://grafana.blah.com/ ``` + +## Step 4. Restart Grafana + +To finalize the installation of Grafana Enterprise, restart Grafana to +enable all Grafana Enterprise features. + +On Linux, when installed as a Systemd service you can restart Grafana +by running `sudo systemctl restart grafana-server.service`. diff --git a/docs/sources/enterprise/enterprise-configuration.md b/docs/sources/enterprise/enterprise-configuration.md index 7ddc3bd0049..69861a1a715 100644 --- a/docs/sources/enterprise/enterprise-configuration.md +++ b/docs/sources/enterprise/enterprise-configuration.md @@ -9,6 +9,31 @@ weight = 300 This page describes Grafana Enterprise-specific configuration options that you can specify in a `.ini` configuration file or using environment variables. Refer to [Configuration]({{< relref "../administration/configuration.md" >}}) for more information about available configuration options. +## [enterprise] + +### license_path + +Local filesystem path to Grafana Enterprise's license file. +Defaults to `/license.jwt`. + +### license_text + +> **Note:** Available in Grafana Enterprise v7.4+. + +When set to the text representation (i.e. content of the license file) +of the license, Grafana will evaluate and apply the given license to +the instance. + +### auto_refresh_license + +> **Note:** Available in Grafana Enterprise v7.4+. + +When enabled, Grafana will send the license and usage statistics to +the license issuer. If the license has been updated on the issuer's +side to be valid for a different number of users or a new duration, +your Grafana instance will be updated with the new terms +automatically. Defaults to `true`. + ## [white_labeling] ### app_title diff --git a/docs/sources/http_api/licensing.md b/docs/sources/http_api/licensing.md new file mode 100644 index 00000000000..c24667af1af --- /dev/null +++ b/docs/sources/http_api/licensing.md @@ -0,0 +1,98 @@ ++++ +title = "Licensing HTTP API " +description = "Grafana Licensing HTTP API" +keywords = ["grafana", "http", "documentation", "api", "licensing", "enterprise"] +aliases = ["/docs/grafana/latest/http_api/licensing/"] ++++ + +> Licensing is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "../enterprise" >}}). + +## Manually force license refresh + +> **Note:** Available in Grafana Enterprise v7.4+. + +`POST /api/licensing/token/renew` + +Manually ask license issuer for a new token. + +**Example request:** + +```http +POST /api/licensing/token/renew +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk + +{} +``` + +**Example response:** + +```http +HTTP/1.1 200 OK +Content-Type: application/json +Content-Length: 357 + +{ + "jti":"2", + "iss":"https://grafana.com", + "sub":"https://play.grafana.org/" + "lid":"1", + "included_admins":5, + "included_viewers":10, + "lic_exp_warn_days":30, + "tok_exp_warn_days":2, + "update_days":1, + "prod":["grafana-enterprise"], + "company":"Grafana Labs" +} +``` + +The response is a JSON blob available for debugging purposes. The +available fields may change at any time without any prior notice. + +Status Codes: + +- **200** - OK +- **401** - Unauthorized +- **403** - Access denied + +## Remove license from database + +> **Note:** Available in Grafana Enterprise v7.4+. + +`DELETE /api/licensing/token` + +Removes the license stored in the Grafana database. + +**Example request:** + +```http +DELETE /api/licensing/token +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk + +{"instance": "http://play.grafana.org/"} +``` + +JSON Body schema: + +- **instance** – Root URL for the instance for which the license should be deleted. Required. + +**Example response:** + +```http +HTTP/1.1 202 Accepted +Content-Type: application/json +Content-Length: 2 + +{} +``` + +Status codes: + +- **202** - Accepted, license removed or did not exist. +- **401** - Unauthorized +- **403** - Access denied +- **422** - Unprocessable entity, incorrect instance name provided.