From f92a6dd1c5a5871877f11150b22da7d056e45a5a Mon Sep 17 00:00:00 2001 From: Paul Echeverri Date: Mon, 14 Sep 2015 20:36:47 -0700 Subject: [PATCH 1/6] Adds a page on plugin management to address issue #4204. --- docs/index.asciidoc | 2 ++ docs/plugins.asciidoc | 70 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 72 insertions(+) create mode 100644 docs/plugins.asciidoc diff --git a/docs/index.asciidoc b/docs/index.asciidoc index e2a85ee48c87..ac9fff2a5ec7 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -11,6 +11,8 @@ include::setup.asciidoc[] include::getting-started.asciidoc[] +include::plugins.asciidoc[] + include::access.asciidoc[] include::discover.asciidoc[] diff --git a/docs/plugins.asciidoc b/docs/plugins.asciidoc new file mode 100644 index 000000000000..b7884c33dd53 --- /dev/null +++ b/docs/plugins.asciidoc @@ -0,0 +1,70 @@ +[[kibana-plugins]] +== Kibana Plugins + +Add-on functionality for Kibana is implemented with plug-in modules. You can use the `bin/kibana plugin` +command to manage these modules. You can also install a plugin manually by moving the plugin file to the +`plugins` directory. + +[float] +=== Installing Plugins + +Use the following command to install a plugin: + +[source,shell] +bin/kibana plugin --install // + +You can also use `-i` instead of `--install`, as in the following example: + +[source,shell] +bin/kibana plugin -i elasticsearch/marvel-ui/latest + +Because the organization given is `elasticsearch`, the plugin management tool automatically downloads the +plugin from `download.elastic.co`. + +[float] +=== Installing Plugins from Github + +When the specified plugin is not found at `download.elastic.co`, the plugin management tool parses the element +as a Github user name, as in the following example: + +[source,shell] +bin/kibana plugin --install rashidkpc/kibana-slideshow +Installing kibana-slideshow +Attempting to extract from https://download.elastic.co/rashidkpc/kibana-slideshow/kibana-slideshow-latest.tar.gz +Attempting to extract from https://github.com/rashidkpc/kibana-slideshow/archive/master.tar.gz + +[float] +=== Removing Plugins + +Use the `--remove` or `-r` option to remove a plugin, including any configuration information, as in the following +example: + +[source,shell] +bin/kibana plugin --remove rashidkpc/kibana-slideshow + +[float] +=== Configuring the Plugin Manager + +By default, the plugin manager provides you with feedback on the status of the activity you've asked the plugin manager +to perform. You can control the level of feedback with the `--quiet` and `--silent` options. Use the `--quiet` option to +suppress all non-error output. Use the `--silent` option to suppress all output. + +By default, plugin manager requests do not time out. Use the `--timeout` option, followed by a time, to change this +behavior, as in the following examples: + +[source,shell] +.Waits for 30 seconds before failing +bin/kibana plugin --install rashidkpc/kibana-slideshow --timeout 30s + +[source,shell] +.Waits for 1 minute before failing +bin/kibana plugin --install rashidkpc/kibana-slideshow --timeout 1m + +[float] +=== Plugin Manager Exit Codes + +[horizontal] +0:: Success +64:: Unknown command or incorrect option parameter +74:: I/O error +70:: Other error From 928907756c965b46231a9882ad84b63cef552747 Mon Sep 17 00:00:00 2001 From: Paul Echeverri Date: Wed, 16 Sep 2015 17:21:46 -0700 Subject: [PATCH 2/6] Updates plugin management section with new material. --- docs/plugins.asciidoc | 56 +++++++++++++++++++++++++++++++++++++------ 1 file changed, 49 insertions(+), 7 deletions(-) diff --git a/docs/plugins.asciidoc b/docs/plugins.asciidoc index b7884c33dd53..3f08bd879b07 100644 --- a/docs/plugins.asciidoc +++ b/docs/plugins.asciidoc @@ -28,10 +28,45 @@ When the specified plugin is not found at `download.elastic.co`, the plugin mana as a Github user name, as in the following example: [source,shell] -bin/kibana plugin --install rashidkpc/kibana-slideshow -Installing kibana-slideshow -Attempting to extract from https://download.elastic.co/rashidkpc/kibana-slideshow/kibana-slideshow-latest.tar.gz -Attempting to extract from https://github.com/rashidkpc/kibana-slideshow/archive/master.tar.gz +bin/kibana plugin --install github-user/sample-plugin +Installing sample-plugin +Attempting to extract from https://download.elastic.co/github-user/sample-plugin/sample-plugin-latest.tar.gz +Attempting to extract from https://github.com/github-user/sample-plugin/archive/master.tar.gz +Downloading bytes.................... +Extraction complete +Optimizing and caching browser bundles... +Plugin installation complete + +[float] +=== Installing Plugins from an Arbitrary URL + +You can specify a URL to a plugin with the `-u` or `--url` options after the `-i` or `--install` option, as in the +following example: + +[source,shell] +bin/kibana plugin -i sample-plugin -u https://some.sample.url/directory +Installing sample-plugin +Attempting to extract from https://some.sample.url/directory +Downloading bytes.................... +Extraction complete +Optimizing and caching browser bundles... +Plugin installation complete + +[float] +=== Installing Plugins to an Arbitrary Directory + +Use the `-d` or `--plugin-dir` option to specify a directory for plugins, as in the following example: + +[source,shell] +bin/kibana plugin -i elasticsearch/sample-plugin/latest -d +Installing sample-plugin +Attempting to extract from https://download.elastic.co/elasticsearch/sample-plugin/sample-plugin-latest.tar.gz +Downloading bytes.................... +Extraction complete +Optimizing and caching browser bundles... +Plugin installation complete + +NOTE: This command creates the specified directory if it does not already exist. [float] === Removing Plugins @@ -40,7 +75,7 @@ Use the `--remove` or `-r` option to remove a plugin, including any configuratio example: [source,shell] -bin/kibana plugin --remove rashidkpc/kibana-slideshow +bin/kibana plugin --remove elasticsearch/marvel-ui [float] === Configuring the Plugin Manager @@ -54,11 +89,18 @@ behavior, as in the following examples: [source,shell] .Waits for 30 seconds before failing -bin/kibana plugin --install rashidkpc/kibana-slideshow --timeout 30s +bin/kibana plugin --install username/sample-plugin --timeout 30s [source,shell] .Waits for 1 minute before failing -bin/kibana plugin --install rashidkpc/kibana-slideshow --timeout 1m +bin/kibana plugin --install username/sample-plugin --timeout 1m + +==== Plugins and Custom Kibana Configurations + +Use the `-c` or `--config` options to specify the path to the configuration file used to start Kibana. By default, Kibana +uses the configuration file `config/kibana.yml`. When you change your installed plugins, the `bin/kibana plugin` command +restarts the Kibana server. When you are using a customized configuration file, you must specify the +path to that configuration file each time you use the `bin/kibana plugin` command. [float] === Plugin Manager Exit Codes From 51004a2a08d45cc3051b0009c478262827e89071 Mon Sep 17 00:00:00 2001 From: Paul Echeverri Date: Thu, 17 Sep 2015 15:36:31 -0700 Subject: [PATCH 3/6] Stylistic fix, no substantive content change --- docs/plugins.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/plugins.asciidoc b/docs/plugins.asciidoc index 3f08bd879b07..7b0d370a49a0 100644 --- a/docs/plugins.asciidoc +++ b/docs/plugins.asciidoc @@ -95,6 +95,7 @@ bin/kibana plugin --install username/sample-plugin --timeout 30s .Waits for 1 minute before failing bin/kibana plugin --install username/sample-plugin --timeout 1m +[float] ==== Plugins and Custom Kibana Configurations Use the `-c` or `--config` options to specify the path to the configuration file used to start Kibana. By default, Kibana From 90ed4862503000eafc55bf3317132aa7874444b7 Mon Sep 17 00:00:00 2001 From: Paul Echeverri Date: Fri, 18 Sep 2015 14:56:24 -0700 Subject: [PATCH 4/6] Adds information on updating plugins --- docs/plugins.asciidoc | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/plugins.asciidoc b/docs/plugins.asciidoc index 7b0d370a49a0..bb7a88bc6bd7 100644 --- a/docs/plugins.asciidoc +++ b/docs/plugins.asciidoc @@ -77,6 +77,11 @@ example: [source,shell] bin/kibana plugin --remove elasticsearch/marvel-ui +[float] +=== Updating Plugins + +To update a plugin, remove the current version and reinstall the plugin. + [float] === Configuring the Plugin Manager From bb765f3be2c4c308a2fd9a65216640b225567217 Mon Sep 17 00:00:00 2001 From: Paul Echeverri Date: Fri, 18 Sep 2015 15:24:30 -0700 Subject: [PATCH 5/6] Updates URL supported protocols and install directory default. --- docs/plugins.asciidoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/plugins.asciidoc b/docs/plugins.asciidoc index bb7a88bc6bd7..3e72c8870a14 100644 --- a/docs/plugins.asciidoc +++ b/docs/plugins.asciidoc @@ -3,7 +3,7 @@ Add-on functionality for Kibana is implemented with plug-in modules. You can use the `bin/kibana plugin` command to manage these modules. You can also install a plugin manually by moving the plugin file to the -`plugins` directory. +`installedPlugins` directory and unpacking the plugin files into a new directory. [float] === Installing Plugins @@ -52,6 +52,8 @@ Extraction complete Optimizing and caching browser bundles... Plugin installation complete +You can specify URLs that use the HTTP, HTTPS, or `file` protocols. + [float] === Installing Plugins to an Arbitrary Directory From 410d27cf7b02883d09489918ad01d7c4549d895f Mon Sep 17 00:00:00 2001 From: Paul Echeverri Date: Fri, 18 Sep 2015 15:54:49 -0700 Subject: [PATCH 6/6] Adds final bits of extra info on plugin removal, typo fixes --- docs/plugins.asciidoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/plugins.asciidoc b/docs/plugins.asciidoc index 3e72c8870a14..c4b0087cd0eb 100644 --- a/docs/plugins.asciidoc +++ b/docs/plugins.asciidoc @@ -77,7 +77,9 @@ Use the `--remove` or `-r` option to remove a plugin, including any configuratio example: [source,shell] -bin/kibana plugin --remove elasticsearch/marvel-ui +bin/kibana plugin --remove marvel-ui + +You can also remove a plugin manually by deleting the plugin's subdirectory under the `installedPlugins` directory. [float] === Updating Plugins