mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
Docs: Update plugin installation and CLI (#21179)
* Update plugin docs * Updated plugins installation documentation Moved all Grafana CLI commands into cli.md, moved API script into user.md, rewrote installation.md as an actual task that refers the user to the plugins installation page * Update cli.md * Update cli.md * Update docs/sources/administration/cli.md Co-Authored-By: Dan Cech <dcech@grafana.com> * Update docs/sources/administration/cli.md Co-Authored-By: Dan Cech <dcech@grafana.com> * Update docs/sources/http_api/user.md Co-Authored-By: Dan Cech <dcech@grafana.com> * Update docs/sources/http_api/user.md Co-Authored-By: Dan Cech <dcech@grafana.com> * Update cli.md * Fixed links * Update cli.md * Update cli.md * Update cli.md * Update cli.md Co-authored-by: Dan Cech <dan@aussiedan.com>
This commit is contained in:
Diana Payton
GitHub
parent
77ec7afa2b
commit
aada45a4cb
@ -10,41 +10,215 @@ weight = 8
|
||||
|
||||
# Grafana CLI
|
||||
|
||||
Grafana cli is a small executable that is bundled with Grafana-server and is supposed to be executed on the same machine Grafana-server is running on.
|
||||
Grafana CLI is a small executable that is bundled with Grafana server and is supposed to be executed on the same machine Grafana server is running on.
|
||||
|
||||
## Plugins
|
||||
Grafana CLI has `plugins` and `admin` commands, as well as global options.
|
||||
|
||||
The CLI allows you to install, upgrade and manage your plugins on the machine it is running on.
|
||||
You can find more information about how to install and manage your plugins in the
|
||||
[plugins page]({{< relref "../plugins/installation.md" >}}).
|
||||
To list all commands and options:
|
||||
```
|
||||
grafana-cli -h
|
||||
```
|
||||
|
||||
## Admin
|
||||
**Linux users**
|
||||
Some commands, such as installing or removing plugins, require `sudo` in order to run.
|
||||
|
||||
> This feature is only available in Grafana 4.1 and above.
|
||||
**Windows users**
|
||||
Some commands, such as installing or removing plugins, require you to run Windows PowerShell as Administrator.
|
||||
|
||||
To show all admin commands:
|
||||
`grafana-cli admin`
|
||||
Before you enter commands, `cd` into the Grafana bin directory. The default path is:
|
||||
```
|
||||
cd "C:\Program Files\GrafanaLabs\grafana\bin"
|
||||
```
|
||||
|
||||
## Grafana CLI command syntax
|
||||
|
||||
The general syntax for commands in Grafana CLI is:
|
||||
```bash
|
||||
grafana-cli [global options] command [command options] [arguments...]
|
||||
```
|
||||
|
||||
## Global options
|
||||
|
||||
Grafana CLI allows you to temporarily override certain Grafana default settings. Except for `--help` and `--version`, most global options are only used by developers.
|
||||
|
||||
Each global option applies only to the command in which it is used. For example, `--pluginsDir value` does not permanently change where Grafana saves plugins. It only changes it for command in which you apply the option.
|
||||
|
||||
### Display Grafana CLI help
|
||||
|
||||
`--help` or `-h` displays the help, including default paths and Docker configuration information.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
grafana-cli -h
|
||||
```
|
||||
|
||||
### Display Grafana CLI version
|
||||
|
||||
`--version` or `-v` prints the version of Grafana CLI currently running.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
grafana-cli -v
|
||||
```
|
||||
|
||||
### Override default plugin directory
|
||||
|
||||
`--pluginsDir value` overrides the path to where your local Grafana instance stores plugins. Use this option if you want to install, update, or remove a plugin somewhere other than the default directory ("/var/lib/grafana/plugins") [$GF_PLUGIN_DIR].
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
grafana-cli --pluginsDir "/var/lib/grafana/devplugins" plugins install <plugin-id>
|
||||
```
|
||||
|
||||
### Override default plugin repo URL
|
||||
|
||||
`--repo value` allows you to download and install or update plugins from a repository other than the default Grafana repo.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
grafana-cli --repo "https://example.com/plugins" plugins install <plugin-id>
|
||||
```
|
||||
|
||||
### Override default plugin .zip URL
|
||||
|
||||
`--pluginUrl value` allows you to download a .zip file containing a plugin from a local URL instead of downloading it from the default Grafana source.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
grafana-cli --pluginUrl https://company.com/grafana/plugins/<plugin-id>-<plugin-version>.zip plugins install <plugin-id>
|
||||
```
|
||||
|
||||
### Override Transport Layer Security
|
||||
|
||||
**Warning:** Turning off TLS is a significant security risk. We do not recommend using this option.
|
||||
|
||||
`--insecure` allows you to turn off Transport Layer Security (TLS) verification (insecure). You might want to do this if you are downloading a plugin from a non-default source.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
grafana-cli --insecure --pluginUrl https://company.com/grafana/plugins/<plugin-id>-<plugin-version>.zip plugins install <plugin-id>
|
||||
```
|
||||
|
||||
### Enable debug logging
|
||||
|
||||
`--debug` or `-d` enables debug logging. Debug output is returned and shown in the terminal.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
grafana-cli --debug plugins install <plugin-id>
|
||||
```
|
||||
|
||||
### Override a configuration setting
|
||||
|
||||
`--configOverrides` is a command line argument that acts like an environmental variable override.
|
||||
|
||||
For example, you can use it to redirect logging to another file (maybe to log plugin installs in a service like Hosted Grafana) or when resetting the admin password and you have non-default values for some important config value (like where the database is located).
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
grafana-cli --configOverrides cfg:default.paths.log=/dev/null plugins install <plugin-id>
|
||||
```
|
||||
|
||||
### Override homepath value
|
||||
|
||||
Sets the path for the Grafana install/home path, defaults to working directory. You do not need to use this if you are in the Grafana installation directory when using the CLI.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
grafana-cli admin reset-admin-password --homepath "c:\Program Files\grafana" mynewpassword
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
grafana-cli admin reset-admin-password --config "/etc/configuration/" mynewpassword
|
||||
```
|
||||
|
||||
## Plugins commands
|
||||
|
||||
Grafana CLI allows you to install, upgrade, and manage your Grafana plugins. For more information about installing plugins, refer to [plugins page]({{< relref "..\plugins\installation.md" >}}).
|
||||
|
||||
All listed commands apply to the Grafana default repositories and directories. You can override the defaults with [Global Options](#global-options).
|
||||
|
||||
### List available plugins
|
||||
|
||||
```bash
|
||||
grafana-cli plugins list-remote
|
||||
```
|
||||
|
||||
### Install the latest version of a plugin
|
||||
|
||||
```bash
|
||||
grafana-cli plugins install <plugin-id>
|
||||
```
|
||||
|
||||
### Install a specific version of a plugin
|
||||
|
||||
```bash
|
||||
grafana-cli plugins install <plugin-id> <version>
|
||||
```
|
||||
|
||||
### List installed plugins
|
||||
|
||||
```bash
|
||||
grafana-cli plugins ls
|
||||
```
|
||||
|
||||
### Update all installed plugins
|
||||
```bash
|
||||
grafana-cli plugins update-all
|
||||
```
|
||||
|
||||
### Update one plugin
|
||||
|
||||
```bash
|
||||
grafana-cli plugins update <plugin-id>
|
||||
```
|
||||
|
||||
### Remove one plugin
|
||||
|
||||
```bash
|
||||
grafana-cli plugins remove <plugin-id>
|
||||
```
|
||||
|
||||
## Admin commands
|
||||
|
||||
Admin commands are only available in Grafana 4.1 and later.
|
||||
|
||||
### Show all admin commands
|
||||
|
||||
```bash
|
||||
grafana-cli admin
|
||||
```
|
||||
|
||||
### Reset admin password
|
||||
|
||||
You can reset the password for the admin user using the CLI. The use case for this command is when you have lost the admin password.
|
||||
`grafana-cli admin reset-admin-password <new password>` resets the password for the admin user using the CLI. You might need to do this if you lose the admin password.
|
||||
|
||||
`grafana-cli admin reset-admin-password ...`
|
||||
If there are two flags being used to set the homepath and the config file path, then running the command returns this error:
|
||||
|
||||
If running the command returns this error:
|
||||
> Could not find config defaults, make sure homepath command line parameter is set or working directory is homepath
|
||||
|
||||
> Could not find config defaults, make sure homepath command line parameter is set or working directory is homepath
|
||||
|
||||
then there are two flags that can be used to set homepath and the config file path.
|
||||
|
||||
`grafana-cli --homepath "/usr/share/grafana" admin reset-admin-password newpass`
|
||||
|
||||
If you have not lost the admin password then it is better to set in the Grafana UI. If you need to set the password in a script then the [Grafana API](http://docs.grafana.org/http_api/user/#change-password) can be used. Here is an example using curl with basic auth:
|
||||
To correct this, use the `--homepath` global option to specify the Grafana default homepath for this command:
|
||||
|
||||
```bash
|
||||
curl -X PUT -H "Content-Type: application/json" -d '{
|
||||
"oldPassword": "admin",
|
||||
"newPassword": "newpass",
|
||||
"confirmNew": "newpass"
|
||||
}' http://admin:admin@<your_grafana_host>:3000/api/user/password
|
||||
grafana-cli --homepath "/usr/share/grafana" admin reset-admin-password <new password>
|
||||
```
|
||||
|
||||
If you have not lost the admin password, we recommend that you change the user password either in the User Preferences or in the Server Admin > User tab.
|
||||
|
||||
If you need to set the password in a script, then you can use the [Grafana User API]({{{< relref "..\http_api\user.md#change-password).
|
||||
">}}}
|
||||
### Migrate data and encrypt passwords
|
||||
|
||||
`data-migration` runs a script that migrates or cleans up data in your database.
|
||||
|
||||
`encrypt-datasource-passwords` migrates passwords from unsecured fields to secure_json_data field. Returns `ok` unless there is an error. Safe to execute multiple times.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
grafana-cli admin data-migration encrypt-datasource-passwords
|
||||
```
|
||||
|
||||
@ -332,6 +332,18 @@ Content-Type: application/json
|
||||
{"message":"User password changed"}
|
||||
```
|
||||
|
||||
**Change Password with a Script**
|
||||
|
||||
If you need to change a password with a script, here is an example of changing the Admin password using curl with basic auth:
|
||||
|
||||
```bash
|
||||
curl -X PUT -H "Content-Type: application/json" -d '{
|
||||
"oldPassword": "oldpass",
|
||||
"newPassword": "newpass",
|
||||
"confirmNew": "newpass"
|
||||
}' http://admin:oldpass@<your_grafana_host>:3000/api/user/password
|
||||
```
|
||||
|
||||
## Switch user context for a specified user
|
||||
|
||||
`POST /api/users/:userId/using/:organizationId`
|
||||
|
||||
@ -6,15 +6,3 @@ name = "Plugins"
|
||||
identifier = "plugins"
|
||||
weight = 8
|
||||
+++
|
||||
|
||||
|
||||
# Plugins
|
||||
|
||||
Plugins make it easy to create and add any kind of panel, data source or complete
|
||||
application, to show your data or improve your favorite dashboards.
|
||||
|
||||
Grafana has a strong community of contributors and plugin developers.
|
||||
By making it easier to develop and install plugins we hope that the community
|
||||
can grow even stronger and develop new plugins that we would never think about.
|
||||
|
||||
You can discover available plugins on [Grafana.com](https://grafana.com/plugins)
|
||||
|
||||
@ -12,6 +12,8 @@ weight = 1
|
||||
|
||||
You can extend Grafana by writing your own plugins and then share them with other users in [our plugin repository](https://grafana.com/plugins).
|
||||
|
||||
Grafana already has a strong community of contributors and plugin developers. By making it easier to develop and install plugins with resources such as this guide, we hope that the community can grow even stronger and develop new plugins that we would never think about.
|
||||
|
||||
## Short version
|
||||
|
||||
1. [Setup grafana](http://docs.grafana.org/project/building_from_source/)
|
||||
|
||||
@ -1,109 +1,27 @@
|
||||
+++
|
||||
title = "Installing Plugins"
|
||||
title = "Install plugins"
|
||||
type = "docs"
|
||||
[menu.docs]
|
||||
parent = "plugins"
|
||||
weight = 1
|
||||
+++
|
||||
|
||||
# Grafana Plugins
|
||||
# Install Grafana plugins
|
||||
|
||||
From Grafana 3.0+ not only are data source plugins supported but also panel plugins and apps.
|
||||
Having panels as plugins make it easy to create and add any kind of panel, to show your data
|
||||
or improve your favorite dashboards. Apps is something new in Grafana that enables
|
||||
bundling of data sources, panels, dashboards and Grafana pages into a cohesive experience.
|
||||
Grafana supports data source, panel, and app plugins. Having panels as plugins makes it easy to create and add any kind of panel, to show your data, or improve your favorite dashboards. Apps enable the bundling of data sources, panels, dashboards, and Grafana pages into a cohesive experience.
|
||||
|
||||
Grafana already have a strong community of contributors and plugin developers.
|
||||
By making it easier to develop and install plugins we hope that the community
|
||||
can grow even stronger and develop new plugins that we would never think about.
|
||||
1. In a web browser, navigate to the official [Grafana Plugins page](https://grafana.com/plugins) and find a plugin that you want to install.
|
||||
2. Click the plugin, and then click the **Installation** tab.
|
||||
3. In the **For** field, select the organization that contains the Grafana instance you want to install the plugin on.
|
||||
|
||||
To discover plugins, check out the official [Plugin Repository](https://grafana.com/plugins).
|
||||
## Install plugin on Hosted Grafana
|
||||
|
||||
# Installing Plugins
|
||||
On the Installation tab, click the name of the Hosted Grafana instance that you want to install the plugin on.
|
||||
|
||||
The easiest way to install plugins is by using the CLI tool grafana-cli which is bundled with grafana. Before any modification take place after modifying plugins, grafana-server needs to be restarted.
|
||||
Grafana handles the plugin installation automatically.
|
||||
|
||||
### Grafana Plugin Directory
|
||||
## Install plugin on local Grafana
|
||||
|
||||
On Linux systems the grafana-cli will assume that the grafana plugin directory is `/var/lib/grafana/plugins`. It's possible to override the directory which grafana-cli will operate on by specifying the --pluginsDir flag. On Windows systems this parameter have to be specified for every call.
|
||||
Follow the instructions on the Install tab. You can either install the plugin with a Grafana CLI command or by downloading a .zip file into the Grafana plugins directory. We recommend using Grafana CLI in most instances. The .zip option is available if your Grafana server does not have access to the internet.
|
||||
|
||||
### Grafana-cli Commands
|
||||
|
||||
List available plugins
|
||||
```bash
|
||||
grafana-cli plugins list-remote
|
||||
```
|
||||
|
||||
Install the latest version of a plugin
|
||||
```bash
|
||||
grafana-cli plugins install <plugin-id>
|
||||
```
|
||||
|
||||
Install a specific version of a plugin
|
||||
```bash
|
||||
grafana-cli plugins install <plugin-id> <version>
|
||||
```
|
||||
|
||||
List installed plugins
|
||||
```bash
|
||||
grafana-cli plugins ls
|
||||
```
|
||||
|
||||
Update all installed plugins
|
||||
```bash
|
||||
grafana-cli plugins update-all
|
||||
```
|
||||
|
||||
Update one plugin
|
||||
```bash
|
||||
grafana-cli plugins update <plugin-id>
|
||||
```
|
||||
|
||||
Remove one plugin
|
||||
```bash
|
||||
grafana-cli plugins remove <plugin-id>
|
||||
```
|
||||
|
||||
### Installing Plugins Manually
|
||||
|
||||
If your Grafana Server does not have access to the Internet, then the plugin will have to downloaded and manually copied to your Grafana Server.
|
||||
|
||||
The Download URL from Grafana.com API is in this form:
|
||||
|
||||
`https://grafana.com/api/plugins/<plugin id>/versions/<version number>/download`
|
||||
|
||||
You can specify a local URL by using the `--pluginUrl` option.
|
||||
```bash
|
||||
grafana-cli --pluginUrl https://nexus.company.com/grafana/plugins/<plugin-id>-<plugin-version>.zip plugins install <plugin-id>
|
||||
```
|
||||
|
||||
To manually install a Plugin via the Grafana.com API:
|
||||
|
||||
1. Find the plugin you want to download, the plugin id can be found on the Installation Tab on the plugin's page on Grafana.com. In this example, the plugin id is `jdbranham-diagram-panel`:
|
||||
|
||||
{{< imgbox img="/img/docs/installation-tab.png" caption="Installation Tab" >}}
|
||||
|
||||
2. Use the Grafana API to find the plugin using this url `https://grafana.com/api/plugins/<plugin id from step 1>`. For example: https://grafana.com/api/plugins/jdbranham-diagram-panel should return:
|
||||
```bash
|
||||
{
|
||||
"id": 145,
|
||||
"typeId": 3,
|
||||
"typeName": "Panel",
|
||||
"typeCode": "panel",
|
||||
"slug": "jdbranham-diagram-panel",
|
||||
"name": "Diagram",
|
||||
"description": "Diagram panel for grafana",
|
||||
...
|
||||
```
|
||||
|
||||
3. Find the download link:
|
||||
```bash
|
||||
{
|
||||
"rel": "download",
|
||||
"href": "/plugins/jdbranham-diagram-panel/versions/1.4.0/download"
|
||||
}
|
||||
```
|
||||
|
||||
4. Download the plugin with `https://grafana.com/api/plugins/<plugin id from step 1>/versions/<current version>/download` (for example: https://grafana.com/api/plugins/jdbranham-diagram-panel/versions/1.4.0/download). Unzip the downloaded file into the Grafana Server's `plugins` directory.
|
||||
|
||||
5. Restart the Grafana Server.
|
||||
For more information about Grafana CLI plugin commands, refer to [Plugin commands]({{< relref "..\..\administration\cli.md#plugins-commands" >}}).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user