Skip to content

N
nexpie-grafana-theme
Commit aada45a4 by Diana Payton Committed by GitHub
Options

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>
parent 77ec7afa
Showing with 221 additions and 127 deletions
docs/sources/administration/cli.md
......@@ -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
```
**Linux users**
Some commands, such as installing or removing plugins, require `sudo` in order to run.
**Windows users**
Some commands, such as installing or removing plugins, require you to run Windows PowerShell as Administrator.
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
## Admin
`--configOverrides` is a command line argument that acts like an environmental variable override.
> This feature is only available in Grafana 4.1 and above.
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).
To show all admin commands:
`grafana-cli admin`
**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.
If there are two flags being used to set the homepath and the config file path, then running the command returns this error:
`grafana-cli admin reset-admin-password ...`
> Could not find config defaults, make sure homepath command line parameter is set or working directory is homepath
If running the command returns this error:
To correct this, use the `--homepath` global option to specify the Grafana default homepath for this command:
```bash
grafana-cli --homepath "/usr/share/grafana" admin reset-admin-password <new password>
```
> Could not find config defaults, make sure homepath command line parameter is set or working directory is homepath
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.
then there are two flags that can be used to set homepath and the config file path.
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
`grafana-cli --homepath "/usr/share/grafana" admin reset-admin-password newpass`
`data-migration` runs a script that migrates or cleans up data in your database.
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:
`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
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 admin data-migration encrypt-datasource-passwords
```
docs/sources/http_api/user.md
......@@ -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`
......
docs/sources/plugins/_index.md
......@@ -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)
docs/sources/plugins/developing/development.md
......@@ -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/)
......
docs/sources/plugins/installation.md
+++
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" >}}).
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment