mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-06 13:08:29 +00:00
b521c606ff
Before this commit he tests always run bin/plugin as root which is somewhat unrealistic and causes trouble (log files owned by root instead of elasticsearch). After this commit `bin/plugin` runs as root when elasticsearch is installed via the repository and as elasticsearch otherwise which is much more realistic. This also adds extra timeout to starting elasticsearch which is required when all the plugins are installed. And it fixes up a problem with logging elasticsearch's log if elasticsearch doesn't start which came up multiple time while debugging this problem. Also adds docs recommending running `bin/plugin` as the user that owns the Elasticsearch files or root if installed with the packages. Closes #13557
234 lines
7.0 KiB
Plaintext
234 lines
7.0 KiB
Plaintext
[[plugin-management]]
|
|
== Plugin Management
|
|
|
|
The `plugin` script is used to install, list, and remove plugins. It is
|
|
located in the `$ES_HOME/bin` directory by default but it may be in a
|
|
{ref}/setup-dir-layout.html[different location] if you installed Elasticsearch
|
|
with an RPM or deb package.
|
|
|
|
Run the following command to get usage instructions:
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
sudo bin/plugin -h
|
|
-----------------------------------
|
|
|
|
[IMPORTANT]
|
|
.Running as root
|
|
=====================
|
|
If Elasticsearch was installed using the deb or rpm package then run
|
|
`bin/plugin` as `root` so it can write to the appropriate files on disk.
|
|
Otherwise run `bin/plugin` as the user that owns all of the Elasticsearch
|
|
files.
|
|
=====================
|
|
|
|
[[installation]]
|
|
=== Installing Plugins
|
|
|
|
The documentation for each plugin usually includes specific installation
|
|
instructions for that plugin, but below we document the various available
|
|
options:
|
|
|
|
[float]
|
|
=== Core Elasticsearch plugins
|
|
|
|
Core Elasticsearch plugins can be installed as follows:
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
sudo bin/plugin install [plugin_name]
|
|
-----------------------------------
|
|
|
|
For instance, to install the core <<analysis-icu,ICU plugin>>, just run the
|
|
following command:
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
sudo bin/plugin install analysis-icu
|
|
-----------------------------------
|
|
|
|
This command will install the version of the plugin that matches your
|
|
Elasticsearch version.
|
|
|
|
[float]
|
|
=== Community and non-core plugins
|
|
|
|
Non-core plugins provided by Elasticsearch, or plugins provided by the
|
|
community, can be installed from `download.elastic.co`, from Maven (Central
|
|
and Sonatype), or from GitHub. In this case, the command is as follows:
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
sudo bin/plugin install [org]/[user|component]/[version]
|
|
-----------------------------------
|
|
|
|
For instance, to install the https://github.com/lmenezes/elasticsearch-kopf[Kopf]
|
|
plugin from GitHub, run one of the following commands:
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
sudo bin/plugin install lmenezes/elasticsearch-kopf <1>
|
|
sudo bin/plugin install lmenezes/elasticsearch-kopf/1.x <2>
|
|
-----------------------------------
|
|
<1> Installs the latest version from GitHub.
|
|
<2> Installs the 1.x version from GitHub.
|
|
|
|
When installing from Maven Central/Sonatype, `[org]` should be replaced by
|
|
the artifact `groupId`, and `[user|component]` by the `artifactId`. For
|
|
instance, to install the
|
|
https://github.com/elastic/elasticsearch-mapper-attachments[mapper attachment]
|
|
plugin from Sonatype, run:
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
sudo bin/plugin install org.elasticsearch/elasticsearch-mapper-attachments/2.6.0 <1>
|
|
-----------------------------------
|
|
<1> When installing from `download.elastic.co` or from Maven Central/Sonatype, the
|
|
version is required.
|
|
|
|
[float]
|
|
=== Custom URL or file system
|
|
|
|
A plugin can also be downloaded directly from a custom location by specifying the URL:
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
sudo bin/plugin install [url] <1>
|
|
-----------------------------------
|
|
<1> must be a valid URL, the plugin name is determined from its descriptor.
|
|
|
|
For instance, to install a plugin from your local file system, you could run:
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
sudo bin/plugin install file:/path/to/plugin.zip
|
|
-----------------------------------
|
|
|
|
[[listing-removing]]
|
|
=== Listing and Removing Installed Plugins
|
|
|
|
[float]
|
|
=== Listing plugins
|
|
|
|
A list of the currently loaded plugins can be retrieved with the `list` option:
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
sudo bin/plugin list
|
|
-----------------------------------
|
|
|
|
Alternatively, use the {ref}/cluster-nodes-info.html[node-info API] to find
|
|
out which plugins are installed on each node in the cluster
|
|
|
|
[float]
|
|
=== Removing plugins
|
|
|
|
Plugins can be removed manually, by deleting the appropriate directory under
|
|
`plugins/`, or using the public script:
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
sudo bin/plugin remove [pluginname]
|
|
-----------------------------------
|
|
|
|
=== Other command line parameters
|
|
|
|
The `plugin` scripts supports a number of other command line parameters:
|
|
|
|
[float]
|
|
=== Silent/Verbose mode
|
|
|
|
The `--verbose` parameter outputs more debug information, while the `--silent`
|
|
parameter turns off all output. The script may return the following exit
|
|
codes:
|
|
|
|
[horizontal]
|
|
`0`:: everything was OK
|
|
`64`:: unknown command or incorrect option parameter
|
|
`74`:: IO error
|
|
`70`:: any other error
|
|
|
|
[float]
|
|
=== Custom config directory
|
|
|
|
If your `elasticsearch.yml` config file is in a custom location, you will need
|
|
to specify the path to the config file when using the `plugin` script. You
|
|
can do this as follows:
|
|
|
|
[source,sh]
|
|
---------------------
|
|
sudo bin/plugin -Des.path.conf=/path/to/custom/config/dir install <plugin name>
|
|
---------------------
|
|
|
|
You can also set the `CONF_DIR` environment variable to the custom config
|
|
directory path.
|
|
|
|
[float]
|
|
=== Timeout settings
|
|
|
|
By default, the `plugin` script will wait indefinitely when downloading before
|
|
failing. The timeout parameter can be used to explicitly specify how long it
|
|
waits. Here is some examples of setting it to different values:
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
# Wait for 30 seconds before failing
|
|
sudo bin/plugin install mobz/elasticsearch-head --timeout 30s
|
|
|
|
# Wait for 1 minute before failing
|
|
sudo bin/plugin install mobz/elasticsearch-head --timeout 1m
|
|
|
|
# Wait forever (default)
|
|
sudo bin/plugin install mobz/elasticsearch-head --timeout 0
|
|
-----------------------------------
|
|
|
|
[float]
|
|
=== Proxy settings
|
|
|
|
To install a plugin via a proxy, you can pass the proxy details in with the
|
|
Java settings `proxyHost` and `proxyPort`. On Unix based systems, these
|
|
options can be set on the command line:
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
sudo bin/plugin install mobz/elasticsearch-head -DproxyHost=host_name -DproxyPort=port_number
|
|
-----------------------------------
|
|
|
|
On Windows, they need to be added to the `JAVA_OPTS` environment variable:
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
set JAVA_OPTS="-DproxyHost=host_name -DproxyPort=port_number"
|
|
bin/plugin install mobz/elasticsearch-head
|
|
-----------------------------------
|
|
|
|
=== Settings related to plugins
|
|
|
|
[float]
|
|
=== Custom plugins directory
|
|
|
|
The `plugins` directory can be changed from the default by adding the
|
|
following to the `elasticsearch.yml` config file:
|
|
|
|
[source,yml]
|
|
---------------------
|
|
path.plugins: /path/to/custom/plugins/dir
|
|
---------------------
|
|
|
|
The default location of the `plugins` directory depends on
|
|
{ref}/setup-dir-layout.html[which package you install].
|
|
|
|
[float]
|
|
=== Mandatory Plugins
|
|
|
|
If you rely on some plugins, you can define mandatory plugins by adding
|
|
`plugin.mandatory` setting to the `config/elasticsearch.yml` file, for
|
|
example:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
plugin.mandatory: mapper-attachments,lang-groovy
|
|
--------------------------------------------------
|
|
|
|
For safety reasons, a node will not start if it is missing a mandatory plugin.
|