[[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-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]]
=== 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
-----------------------------------
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.
=== 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>
---------------------
You can also set the `CONF_DIR` environment variable to the custom config
directory path.
[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="-DproxyHost=host_name -DproxyPort=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.