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:

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

  1. bin/opensearch-plugin list

Example

  1. $ ./opensearch-plugin list
  2. opensearch-alerting
  3. opensearch-anomaly-detection
  4. opensearch-asynchronous-search
  5. opensearch-cross-cluster-replication
  6. opensearch-geospatial
  7. opensearch-index-management
  8. opensearch-job-scheduler
  9. opensearch-knn
  10. opensearch-ml
  11. opensearch-notifications
  12. opensearch-notifications-core
  13. opensearch-observability
  14. opensearch-performance-analyzer
  15. opensearch-reports-scheduler
  16. opensearch-security
  17. opensearch-sql

List (with CAT API)

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

Usage

  1. GET _cat/plugins

Example response

  1. opensearch-node1 opensearch-alerting                  2.0.1.0
  2. opensearch-node1 opensearch-anomaly-detection         2.0.1.0
  3. opensearch-node1 opensearch-asynchronous-search       2.0.1.0
  4. opensearch-node1 opensearch-cross-cluster-replication 2.0.1.0
  5. opensearch-node1 opensearch-index-management          2.0.1.0
  6. opensearch-node1 opensearch-job-scheduler             2.0.1.0
  7. opensearch-node1 opensearch-knn                       2.0.1.0
  8. opensearch-node1 opensearch-ml                        2.0.1.0
  9. opensearch-node1 opensearch-notifications             2.0.1.0
  10. 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

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

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

Example

  1. $ sudo ./opensearch-plugin install analysis-icu
  2. -> Installing analysis-icu
  3. -> Downloading analysis-icu from opensearch
  4. [=================================================] 100%   
  5. -> 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

  1. bin/opensearch-plugin install <zip-file>

Example

Select to expand the example

  1. # Zip file is hosted on a remote server - in this case, Maven central repository.
  2. $ 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
  3. -> Installing https://repo1.maven.org/maven2/org/opensearch/plugin/opensearch-anomaly-detection/2.2.0.0/opensearch-anomaly-detection-2.2.0.0.zip
  4. -> Downloading https://repo1.maven.org/maven2/org/opensearch/plugin/opensearch-anomaly-detection/2.2.0.0/opensearch-anomaly-detection-2.2.0.0.zip
  5. [=================================================] 100%   
  6. @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  7. @     WARNING: plugin requires additional permissions     @
  8. @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  9. * java.lang.RuntimePermission accessClassInPackage.sun.misc
  10. * java.lang.RuntimePermission accessDeclaredMembers
  11. * java.lang.RuntimePermission getClassLoader
  12. * java.lang.RuntimePermission setContextClassLoader
  13. * java.lang.reflect.ReflectPermission suppressAccessChecks
  14. * java.net.SocketPermission * connect,resolve
  15. * javax.management.MBeanPermission org.apache.commons.pool2.impl.GenericObjectPool#-[org.apache.commons.pool2:name=pool,type=GenericObjectPool] registerMBean
  16. * javax.management.MBeanPermission org.apache.commons.pool2.impl.GenericObjectPool#-[org.apache.commons.pool2:name=pool,type=GenericObjectPool] unregisterMBean
  17. * javax.management.MBeanServerPermission createMBeanServer
  18. * javax.management.MBeanTrustPermission register
  19. See http://docs.oracle.com/javase/8/docs/technotes/guides/security/permissions.html
  20. for descriptions of what these permissions allow and the associated risks.
  22. Continue with installation? [y/N]y
  23. -> Installed opensearch-anomaly-detection with folder name opensearch-anomaly-detection
  25. # Zip file in a local directory.
  26. $ sudo ./opensearch-plugin install file:/home/user/opensearch-anomaly-detection-2.2.0.0.zip
  27. -> Installing file:/home/user/opensearch-anomaly-detection-2.2.0.0.zip
  28. -> Downloading file:/home/user/opensearch-anomaly-detection-2.2.0.0.zip
  29. [=================================================] 100%   
  30. @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  31. @     WARNING: plugin requires additional permissions     @
  32. @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  33. * java.lang.RuntimePermission accessClassInPackage.sun.misc
  34. * java.lang.RuntimePermission accessDeclaredMembers
  35. * java.lang.RuntimePermission getClassLoader
  36. * java.lang.RuntimePermission setContextClassLoader
  37. * java.lang.reflect.ReflectPermission suppressAccessChecks
  38. * java.net.SocketPermission * connect,resolve
  39. * javax.management.MBeanPermission org.apache.commons.pool2.impl.GenericObjectPool#-[org.apache.commons.pool2:name=pool,type=GenericObjectPool] registerMBean
  40. * javax.management.MBeanPermission org.apache.commons.pool2.impl.GenericObjectPool#-[org.apache.commons.pool2:name=pool,type=GenericObjectPool] unregisterMBean
  41. * javax.management.MBeanServerPermission createMBeanServer
  42. * javax.management.MBeanTrustPermission register
  43. See http://docs.oracle.com/javase/8/docs/technotes/guides/security/permissions.html
  44. for descriptions of what these permissions allow and the associated risks.
  46. Continue with installation? [y/N]y
  47. -> 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

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

Example

Select to expand the example

  1. $ sudo ./opensearch-plugin install org.opensearch.plugin:opensearch-anomaly-detection:2.2.0.0
  2. -> Installing org.opensearch.plugin:opensearch-anomaly-detection:2.2.0.0
  3. -> Downloading org.opensearch.plugin:opensearch-anomaly-detection:2.2.0.0 from maven central
  4. [=================================================] 100%   
  5. @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  6. @     WARNING: plugin requires additional permissions     @
  7. @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  8. * java.lang.RuntimePermission accessClassInPackage.sun.misc
  9. * java.lang.RuntimePermission accessDeclaredMembers
  10. * java.lang.RuntimePermission getClassLoader
  11. * java.lang.RuntimePermission setContextClassLoader
  12. * java.lang.reflect.ReflectPermission suppressAccessChecks
  13. * java.net.SocketPermission * connect,resolve
  14. * javax.management.MBeanPermission org.apache.commons.pool2.impl.GenericObjectPool#-[org.apache.commons.pool2:name=pool,type=GenericObjectPool] registerMBean
  15. * javax.management.MBeanPermission org.apache.commons.pool2.impl.GenericObjectPool#-[org.apache.commons.pool2:name=pool,type=GenericObjectPool] unregisterMBean
  16. * javax.management.MBeanServerPermission createMBeanServer
  17. * javax.management.MBeanTrustPermission register
  18. See http://docs.oracle.com/javase/8/docs/technotes/guides/security/permissions.html
  19. for descriptions of what these permissions allow and the associated risks.
  21. Continue with installation? [y/N]y
  22. -> 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

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

Example

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

Remove

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

Usage

  1. bin/opensearch-plugin remove <plugin-name>

Example

  1. $ sudo ./opensearch-plugin remove opensearch-anomaly-detection
  2. -> 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:

  1. 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.

Plugin nameRepositoryEarliest available version
Alertingopensearch-alerting1.0.0
Anomaly Detectionopensearch-anomaly-detection1.0.0
Asynchronous Searchopensearch-asynchronous-search1.0.0
Cross Cluster Replicationopensearch-cross-cluster-replication1.1.0
Custom Codecsopensearch-custom-codecs2.10.0
Flow Frameworkflow-framework2.12.0
Notebooks1opensearch-notebooks1.0.0 to 1.1.0
Notificationsnotifications2.0.0
Reports Scheduleropensearch-reports-scheduler1.0.0
Geospatialopensearch-geospatial2.2.0
Index Managementopensearch-index-management1.0.0
Job Scheduleropensearch-job-scheduler1.0.0
k-NNopensearch-knn1.0.0
ML Commonsopensearch-ml1.3.0
Skillsopensearch-skills2.12.0
Neural Searchneural-search2.4.0
Observabilityopensearch-observability1.2.0
Performance Analyzer2opensearch-performance-analyzer1.0.0
Securityopensearch-security1.0.0
Security Analyticsopensearch-security-analytics2.4.0
SQLopensearch-sql1.0.0

1Dashboard Notebooks was merged in to the Observability plugin with the release of OpenSearch 1.2.0.
2Performance 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:

  1. 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.