You're viewing version 2.16 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Installing plugins

OpenSearch comprises of a number of plugins that add features and capabilities to the core platform. The plugins available to you are dependent on how OpenSearch was installed and which plugins were subsequently added or removed. For example, the minimal distribution of OpenSearch enables only core functionality, such as indexing and search. Using the minimal distribution of OpenSearch is beneficial when you are working in a testing environment, have custom plugins, or are intending to integrate OpenSearch with other services.

The standard distribution of OpenSearch has much more functionality included. You can choose to add additional plugins or remove any of the plugins you don’t need.

For a list of the available plugins, see Available plugins.

For a plugin to work properly with OpenSearch, it may request certain permissions as part of the installation process. Review the requested permissions and proceed accordingly. It is important that you understand a plugin’s functionality before installation. When opting for a community-provided plugin, ensure that the source is trustworthy and reliable.

Managing plugins

To manage plugins in OpenSearch, you can use a command line tool called opensearch-plugin. This tool allows you to perform the following actions:

• List installed plugins.
• Install plugins.
• Remove an installed plugin.

You can print help text by passing -h or --help. Depending on your host configuration, you might also need to run the command with sudo privileges.

If you’re running OpenSearch in a Docker container, plugins must be installed, removed, and configured by modifying the Docker image. For more information, see Working with plugins.

List

Use list to see a list of plugins that have already been installed.

Usage

bin/opensearch-plugin list

Example

$ ./opensearch-plugin list
opensearch-alerting
opensearch-anomaly-detection
opensearch-asynchronous-search
opensearch-cross-cluster-replication
opensearch-geospatial
opensearch-index-management
opensearch-job-scheduler
opensearch-knn
opensearch-ml
opensearch-notifications
opensearch-notifications-core
opensearch-observability
opensearch-performance-analyzer
opensearch-reports-scheduler
opensearch-security
opensearch-sql

List (with CAT API)

You can also list installed plugins by using the CAT API.

Usage

GET _cat/plugins

Example response

opensearch-node1 opensearch-alerting                  2.0.1.0
opensearch-node1 opensearch-anomaly-detection         2.0.1.0
opensearch-node1 opensearch-asynchronous-search       2.0.1.0
opensearch-node1 opensearch-cross-cluster-replication 2.0.1.0
opensearch-node1 opensearch-index-management          2.0.1.0
opensearch-node1 opensearch-job-scheduler             2.0.1.0
opensearch-node1 opensearch-knn                       2.0.1.0
opensearch-node1 opensearch-ml                        2.0.1.0
opensearch-node1 opensearch-notifications             2.0.1.0
opensearch-node1 opensearch-notifications-core        2.0.1.0

Install

There are three ways to install plugins using the opensearch-plugin tool:

• Install a plugin by name.
• Install a plugin from a zip file.
• Install a plugin using Maven coordinates.

Install a plugin by name

You can install plugins that aren’t already preinstalled in your installation by using the plugin name. For a list of plugins that may not be preinstalled, see Additional plugins.

Usage

bin/opensearch-plugin install <plugin-name>

Example

$ sudo ./opensearch-plugin install analysis-icu
-> Installing analysis-icu
-> Downloading analysis-icu from opensearch
[=================================================] 100%   
-> Installed analysis-icu with folder name analysis-icu

Install a plugin from a zip file

You can install remote zip files by replacing <zip-file> with the URL of the hosted file. The tool supports downloading over HTTP/HTTPS protocols only. For local zip files, replace <zip-file> with file: followed by the absolute or relative path to the plugin zip file, as shown in the second example that follows.

Usage

bin/opensearch-plugin install <zip-file>

Example

# Zip file is hosted on a remote server - in this case, Maven central repository.
$ sudo ./opensearch-plugin install https://repo1.maven.org/maven2/org/opensearch/plugin/opensearch-anomaly-detection/2.2.0.0/opensearch-anomaly-detection-2.2.0.0.zip
-> Installing https://repo1.maven.org/maven2/org/opensearch/plugin/opensearch-anomaly-detection/2.2.0.0/opensearch-anomaly-detection-2.2.0.0.zip
-> Downloading https://repo1.maven.org/maven2/org/opensearch/plugin/opensearch-anomaly-detection/2.2.0.0/opensearch-anomaly-detection-2.2.0.0.zip
[=================================================] 100%   
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@     WARNING: plugin requires additional permissions     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
* java.lang.RuntimePermission accessClassInPackage.sun.misc
* java.lang.RuntimePermission accessDeclaredMembers
* java.lang.RuntimePermission getClassLoader
* java.lang.RuntimePermission setContextClassLoader
* java.lang.reflect.ReflectPermission suppressAccessChecks
* java.net.SocketPermission * connect,resolve
* javax.management.MBeanPermission org.apache.commons.pool2.impl.GenericObjectPool#-[org.apache.commons.pool2:name=pool,type=GenericObjectPool] registerMBean
* javax.management.MBeanPermission org.apache.commons.pool2.impl.GenericObjectPool#-[org.apache.commons.pool2:name=pool,type=GenericObjectPool] unregisterMBean
* javax.management.MBeanServerPermission createMBeanServer
* javax.management.MBeanTrustPermission register
See http://docs.oracle.com/javase/8/docs/technotes/guides/security/permissions.html
for descriptions of what these permissions allow and the associated risks.

Continue with installation? [y/N]y
-> Installed opensearch-anomaly-detection with folder name opensearch-anomaly-detection

# Zip file in a local directory.
$ sudo ./opensearch-plugin install file:/home/user/opensearch-anomaly-detection-2.2.0.0.zip
-> Installing file:/home/user/opensearch-anomaly-detection-2.2.0.0.zip
-> Downloading file:/home/user/opensearch-anomaly-detection-2.2.0.0.zip
[=================================================] 100%   
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@     WARNING: plugin requires additional permissions     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
* java.lang.RuntimePermission accessClassInPackage.sun.misc
* java.lang.RuntimePermission accessDeclaredMembers
* java.lang.RuntimePermission getClassLoader
* java.lang.RuntimePermission setContextClassLoader
* java.lang.reflect.ReflectPermission suppressAccessChecks
* java.net.SocketPermission * connect,resolve
* javax.management.MBeanPermission org.apache.commons.pool2.impl.GenericObjectPool#-[org.apache.commons.pool2:name=pool,type=GenericObjectPool] registerMBean
* javax.management.MBeanPermission org.apache.commons.pool2.impl.GenericObjectPool#-[org.apache.commons.pool2:name=pool,type=GenericObjectPool] unregisterMBean
* javax.management.MBeanServerPermission createMBeanServer
* javax.management.MBeanTrustPermission register
See http://docs.oracle.com/javase/8/docs/technotes/guides/security/permissions.html
for descriptions of what these permissions allow and the associated risks.

Continue with installation? [y/N]y
-> Installed opensearch-anomaly-detection with folder name opensearch-anomaly-detection

Install a plugin using Maven coordinates

The opensearch-plugin install tool also allows you to specify Maven coordinates for available artifacts and versions hosted on Maven Central. The tool parses the Maven coordinates you provide and constructs a URL. As a result, the host must be able to connect directly to the Maven Central site. The plugin installation fails if you pass coordinates to a proxy or local repository.

Usage

bin/opensearch-plugin install <groupId>:<artifactId>:<version>

Example

$ sudo ./opensearch-plugin install org.opensearch.plugin:opensearch-anomaly-detection:2.2.0.0
-> Installing org.opensearch.plugin:opensearch-anomaly-detection:2.2.0.0
-> Downloading org.opensearch.plugin:opensearch-anomaly-detection:2.2.0.0 from maven central
[=================================================] 100%   
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@     WARNING: plugin requires additional permissions     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
* java.lang.RuntimePermission accessClassInPackage.sun.misc
* java.lang.RuntimePermission accessDeclaredMembers
* java.lang.RuntimePermission getClassLoader
* java.lang.RuntimePermission setContextClassLoader
* java.lang.reflect.ReflectPermission suppressAccessChecks
* java.net.SocketPermission * connect,resolve
* javax.management.MBeanPermission org.apache.commons.pool2.impl.GenericObjectPool#-[org.apache.commons.pool2:name=pool,type=GenericObjectPool] registerMBean
* javax.management.MBeanPermission org.apache.commons.pool2.impl.GenericObjectPool#-[org.apache.commons.pool2:name=pool,type=GenericObjectPool] unregisterMBean
* javax.management.MBeanServerPermission createMBeanServer
* javax.management.MBeanTrustPermission register
See http://docs.oracle.com/javase/8/docs/technotes/guides/security/permissions.html
for descriptions of what these permissions allow and the associated risks.

Continue with installation? [y/N]y
-> Installed opensearch-anomaly-detection with folder name opensearch-anomaly-detection

Restart your OpenSearch node after installing a plugin.

Installing multiple plugins

Multiple plugins can be installed in a single invocation.

Usage

bin/opensearch-plugin install <plugin-name> <plugin-name> ... <plugin-name>

Example

$ sudo ./opensearch-plugin install analysis-nori repository-s3

Remove

You can remove a plugin that has already been installed with the remove option.

Usage

bin/opensearch-plugin remove <plugin-name>

Example

$ sudo ./opensearch-plugin remove opensearch-anomaly-detection
-> removing [opensearch-anomaly-detection]...

Restart your OpenSearch node after removing a plugin.

Batch mode

When installing a plugin that requires additional privileges that are not included by default, the plugin will prompt you for confirmation of the required privileges. To grant all requested privileges, use batch mode to skip the confirmation prompt.

To force batch mode when installing plugins, add the -b or --batch option:

bin/opensearch-plugin install --batch <plugin-name>

Available plugins

OpenSearch provides several bundled plugins that are available for immediate use with all OpenSearch distributions except for the minimal distribution. Additional plugins are available but must be installed separately using one of the installation options.

Bundled plugins

The following plugins are bundled with all OpenSearch distributions except for the minimal distribution. If you are using the minimal distribution, you can add these plugins by using one of the installation methods.

¹Dashboard Notebooks was merged in to the Observability plugin with the release of OpenSearch 1.2.0.
²Performance Analyzer is not available on Windows.

Additional plugins

There are many more plugins available in addition to those provided by the default distribution. These additional plugins have been built by OpenSearch developers or members of the OpenSearch community. For a list of additional plugins you can install, see Additional plugins.

Plugin compatibility

You can specify plugin compatibility with a particular OpenSearch version in the plugin-descriptor.properties file. For example, a plugin with the following property is compatible only with OpenSearch 2.3.0:

opensearch.version=2.3.0

Alternatively, you can specify a range of compatible OpenSearch versions by setting the dependencies property in the plugin-descriptor.properties file to one of the following notations:

• dependencies={ opensearch: "2.3.0" }: The plugin is compatible only with OpenSearch version 2.3.0.
• dependencies={ opensearch: "=2.3.0" }: The plugin is compatible only with OpenSearch version 2.3.0.
• dependencies={ opensearch: "~2.3.0" }: The plugin is compatible with all versions from 2.3.0 up to the next minor version, in this example, 2.4.0 (exclusive).
• dependencies={ opensearch: "^2.3.0" }: The plugin is compatible with all versions from 2.3.0 up to the next major version, in this example, 3.0.0 (exclusive).

You can specify only one of the opensearch.version or dependencies properties.

Related links

• Observability
• Security Analytics
• Security
• Alerting
• Anomaly detection
• Asynchronous search
• Cross-cluster replication
• Index State Management
• k-NN search
• ML Commons
• Neural search
• Notifications
• OpenSearch Dashboards
• Performance Analyzer
• SQL

Related articles

• Additional plugins
• Ingest-attachment plugin
• Mapper-size plugin