219 lines
7.3 KiB
Plaintext
219 lines
7.3 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
|
|
-----------------------------------
|
|
|
|
[IMPORTANT]
|
|
.Running as root
|
|
=====================
|
|
If Elasticsearch was installed using the deb or rpm package then run
|
|
`/usr/share/elasticsearch/bin/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]
|
|
-----------------------------------
|
|
|
|
For instance, to install the core <<analysis-icu,ICU plugin>>, just run the
|
|
following command:
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
sudo bin/elasticsearch-plugin install analysis-icu
|
|
-----------------------------------
|
|
|
|
This command will install the version of the plugin that matches your
|
|
Elasticsearch version and also show a progress bar while downloading.
|
|
|
|
[[plugin-management-custom-url]]
|
|
=== 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>
|
|
-----------------------------------
|
|
<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
|
|
-----------------------------------
|
|
|
|
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://....
|
|
-----------------------------------
|
|
|
|
[[listing-removing-updating]]
|
|
=== Listing, Removing and Updating 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
|
|
-----------------------------------
|
|
|
|
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]
|
|
-----------------------------------
|
|
|
|
After a Java plugin has been removed, you will need to restart the node to
|
|
complete the removal process.
|
|
|
|
By default, plugin configuration files (if any) are preserved on disk; this is
|
|
so that configuration is not lost while upgrading a plugin. If you wish to
|
|
purge the configuration files while removing a plugin, use `-p` or `--purge`.
|
|
This can option can be used after a plugin is removed to remove any lingering
|
|
configuration files.
|
|
|
|
[float]
|
|
=== Updating plugins
|
|
|
|
Plugins are built for a specific version of Elasticsearch, and therefore must be reinstalled
|
|
each time Elasticsearch is updated.
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
sudo bin/elasticsearch-plugin remove [pluginname]
|
|
sudo bin/elasticsearch-plugin install [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 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]
|
|
=== Batch mode
|
|
|
|
Certain plugins require more privileges than those provided by default in core
|
|
Elasticsearch. These plugins will list the required privileges and ask the
|
|
user for confirmation before continuing with installation.
|
|
|
|
When running the plugin install script from another program (e.g. install
|
|
automation scripts), the plugin script should detect that it is not being
|
|
called from the console and skip the confirmation response, automatically
|
|
granting all requested permissions. If console detection fails, then batch
|
|
mode can be forced by specifying `-b` or `--batch` as follows:
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
sudo bin/elasticsearch-plugin install --batch [pluginname]
|
|
-----------------------------------
|
|
|
|
[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 ES_PATH_CONF=/path/to/conf/dir bin/elasticsearch-plugin install <plugin name>
|
|
---------------------
|
|
|
|
[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
|
|
-----------------------------------
|
|
|
|
Or on Windows:
|
|
|
|
[source,shell]
|
|
------------------------------------
|
|
set 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
|
|
------------------------------------
|
|
|
|
=== 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.
|