mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-08 05:58:44 +00:00
5a2c6f0d4f
Plugin discovery documentation contained information about installing Elasticsearch 2.0 and installing an oracle JDK, both of which is no longer valid. While noticing that the instructions used cleartext HTTP to install packages, this commit replaces HTTPs links instead of HTTP where possible. In addition a few community links have been removed, as they do not seem to exist anymore. Co-authored-by: Alexander Reelsen <alexander@reelsen.net>
272 lines
9.2 KiB
Plaintext
272 lines
9.2 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}/targz.html#targz-layout[Directory layout of `.tar.gz` archives]
|
|
* {ref}/zip-windows.html#windows-layout[Directory layout of Windows `.zip` 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:
|
|
|
|
[discrete]
|
|
=== 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.
|
|
|
|
--
|
|
Unix::
|
|
To install a plugin from your local file system at `/path/to/plugin.zip`, you could run:
|
|
+
|
|
[source,shell]
|
|
-----------------------------------
|
|
sudo bin/elasticsearch-plugin install file:///path/to/plugin.zip
|
|
-----------------------------------
|
|
|
|
Windows::
|
|
To install a plugin from your local file system at `C:\path\to\plugin.zip`, you could run:
|
|
+
|
|
[source,shell]
|
|
-----------------------------------
|
|
bin\elasticsearch-plugin install file:///C:/path/to/plugin.zip
|
|
-----------------------------------
|
|
+
|
|
NOTE: Any path that contains spaces must be wrapped in quotes!
|
|
+
|
|
NOTE: If you are installing a plugin from the filesystem the plugin distribution
|
|
must not be contained in the `plugins` directory for the node that you are
|
|
installing the plugin to or installation will fail.
|
|
|
|
HTTP::
|
|
To install a plugin from an HTTP URL:
|
|
+
|
|
[source,shell]
|
|
-----------------------------------
|
|
sudo bin/elasticsearch-plugin install https://some.domain/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://host/plugin.zip
|
|
-----------------------------------
|
|
--
|
|
|
|
[[installing-multiple-plugins]]
|
|
=== Installing multiple plugins
|
|
|
|
Multiple plugins can be installed in one invocation as follows:
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
sudo bin/elasticsearch-plugin install [plugin_id] [plugin_id] ... [plugin_id]
|
|
-----------------------------------
|
|
|
|
Each `plugin_id` can be any valid form for installing a single plugin (e.g., the
|
|
name of a core plugin, or a custom URL).
|
|
|
|
For instance, to install the core <<analysis-icu,ICU plugin>>, and
|
|
<<repository-s3,S3 repository plugin>> run the following command:
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
sudo bin/elasticsearch-plugin install analysis-icu repository-s3
|
|
-----------------------------------
|
|
|
|
This command will install the versions of the plugins that matches your
|
|
Elasticsearch version. The installation will be treated as a transaction, so
|
|
that all the plugins will be installed, or none of the plugins will be installed
|
|
if any installation fails.
|
|
|
|
[[mandatory-plugins]]
|
|
=== 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.
|
|
|
|
[[listing-removing-updating]]
|
|
=== Listing, Removing and Updating Installed Plugins
|
|
|
|
[discrete]
|
|
=== 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
|
|
|
|
[discrete]
|
|
=== 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.
|
|
|
|
[discrete]
|
|
=== 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:
|
|
|
|
[discrete]
|
|
=== 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
|
|
|
|
[discrete]
|
|
=== 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]
|
|
-----------------------------------
|
|
|
|
[discrete]
|
|
=== 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>
|
|
---------------------
|
|
|
|
[discrete]
|
|
=== 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}/targz.html#targz-layout[Directory layout of `.tar.gz` archives]
|
|
* {ref}/zip-windows.html#windows-layout[Directory layout of Windows `.zip` archives]
|
|
* {ref}/deb.html#deb-layout[Directory layout of Debian package]
|
|
* {ref}/rpm.html#rpm-layout[Directory layout of RPM]
|