216 lines
6.7 KiB
Plaintext
216 lines
6.7 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
|
|
different location depending on which Elasticsearch package you installed:
|
|
|
|
* {ref}/zip-targz.html#zip-targz-layout[Directory layout of `.zip` and `.tar.gz` archives]
|
|
* {ref}/deb.html#deb-layout[Directory layout of Debian package]
|
|
* {ref}/rpm.html#rpm-layout[Directory layout of RPM]
|
|
|
|
Run the following command to get usage instructions:
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
sudo bin/elasticsearch-plugin -h
|
|
-----------------------------------
|
|
// NOTCONSOLE
|
|
|
|
[IMPORTANT]
|
|
.Running as root
|
|
=====================
|
|
If Elasticsearch was installed using the deb or rpm package then run
|
|
`/usr/share/elasticsearch-plugin` as `root` so it can write to the appropriate files on disk.
|
|
Otherwise run `bin/elasticsearch-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/elasticsearch-plugin install [plugin_name]
|
|
-----------------------------------
|
|
// NOTCONSOLE
|
|
|
|
For instance, to install the core <<analysis-icu,ICU plugin>>, just run the
|
|
following command:
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
sudo bin/elasticsearch-plugin install analysis-icu
|
|
-----------------------------------
|
|
// NOTCONSOLE
|
|
|
|
This command will install the version of the plugin that matches your
|
|
Elasticsearch version and also show a progress bar while downloading.
|
|
|
|
[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/elasticsearch-plugin install [url] <1>
|
|
-----------------------------------
|
|
// NOTCONSOLE
|
|
<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/elasticsearch-plugin install file:///path/to/plugin.zip
|
|
-----------------------------------
|
|
// NOTCONSOLE
|
|
|
|
The plugin script will refuse to talk to an HTTPS URL with an untrusted
|
|
certificate. To use a self-signed HTTPS cert, you will need to add the CA cert
|
|
to a local Java truststore and pass the location to the script as follows:
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
sudo ES_JAVA_OPTS="-Djavax.net.ssl.trustStore=/path/to/trustStore.jks" bin/elasticsearch-plugin install https://....
|
|
-----------------------------------
|
|
// NOTCONSOLE
|
|
|
|
[[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/elasticsearch-plugin list
|
|
-----------------------------------
|
|
// NOTCONSOLE
|
|
|
|
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/elasticsearch-plugin remove [pluginname]
|
|
-----------------------------------
|
|
// NOTCONSOLE
|
|
|
|
After a Java plugin has been removed, you will need to restart the node to complete the removal process.
|
|
|
|
=== 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 including the progress bar. 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/elasticsearch-plugin -Epath.conf=/path/to/custom/config/dir install <plugin name>
|
|
---------------------
|
|
// NOTCONSOLE
|
|
|
|
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/elasticsearch-plugin install analysis-icu --timeout 30s
|
|
|
|
# Wait for 1 minute before failing
|
|
sudo bin/elasticsearch-plugin install analysis-icu --timeout 1m
|
|
|
|
# Wait forever (default)
|
|
sudo bin/elasticsearch-plugin install analysis-icu --timeout 0
|
|
-----------------------------------
|
|
// NOTCONSOLE
|
|
|
|
[float]
|
|
=== Proxy settings
|
|
|
|
To install a plugin via a proxy, you can add the proxy details to the
|
|
`ES_JAVA_OPTS` environment variable with the Java settings `http.proxyHost`
|
|
and `http.proxyPort` (or `https.proxyHost` and `https.proxyPort`):
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
sudo ES_JAVA_OPTS="-Dhttp.proxyHost=host_name -Dhttp.proxyPort=port_number -Dhttps.proxyHost=host_name -Dhttps.proxyPort=https_port_number" bin/elasticsearch-plugin install analysis-icu
|
|
-----------------------------------
|
|
// NOTCONSOLE
|
|
|
|
Or on Windows:
|
|
|
|
[source,shell]
|
|
------------------------------------
|
|
set ES_JAVA_OPTS="-DproxyHost=host_name -DproxyPort=port_number -Dhttps.proxyHost=host_name -Dhttps.proxyPort=https_port_number"
|
|
bin/elasticsearch-plugin install analysis-icu
|
|
------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
=== Plugins directory
|
|
|
|
The default location of the `plugins` directory depends on which package you install:
|
|
|
|
* {ref}/zip-targz.html#zip-targz-layout[Directory layout of `.zip` and `.tar.gz` archives]
|
|
* {ref}/deb.html#deb-layout[Directory layout of Debian package]
|
|
* {ref}/rpm.html#rpm-layout[Directory layout of RPM]
|
|
|
|
[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: analysis-icu,lang-js
|
|
--------------------------------------------------
|
|
|
|
For safety reasons, a node will not start if it is missing a mandatory plugin.
|