"Fossies" - the Fresh Open Source Software Archive

Member "elasticsearch-6.8.23/docs/plugins/plugin-script.asciidoc" (29 Dec 2021, 8262 Bytes) of package /linux/www/elasticsearch-6.8.23-src.tar.gz:

As a special service "Fossies" has tried to format the requested source page into HTML format (assuming AsciiDoc format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field.

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:

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.

Installing Plugins

The documentation for each plugin usually includes specific installation instructions for that plugin, but below we document the various available options:

Core Elasticsearch plugins

Core Elasticsearch plugins can be installed as follows:

sudo bin/elasticsearch-plugin install [plugin_name]

For instance, to install the core ICU plugin, just run the following command:

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.

Custom URL or file system

A plugin can also be downloaded directly from a custom location by specifying the URL:

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:

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:

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:

sudo bin/elasticsearch-plugin install http://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:

sudo ES_JAVA_OPTS="-Djavax.net.ssl.trustStore=/path/to/trustStore.jks" bin/elasticsearch-plugin install https://host/plugin.zip

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:

plugin.mandatory: analysis-icu,lang-js

For safety reasons, a node will not start if it is missing a mandatory plugin.

Listing, Removing and Updating Installed Plugins

Listing plugins

A list of the currently loaded plugins can be retrieved with the list option:

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

Removing plugins

Plugins can be removed manually, by deleting the appropriate directory under plugins/, or using the public script:

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.

Updating plugins

Plugins are built for a specific version of Elasticsearch, and therefore must be reinstalled each time Elasticsearch is updated.

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:

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:

0

everything was OK
64

unknown command or incorrect option parameter
74

IO error
70

any other error

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:

sudo bin/elasticsearch-plugin install --batch [pluginname]

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:

sudo ES_PATH_CONF=/path/to/conf/dir bin/elasticsearch-plugin install <plugin name>

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):

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:

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]