Creating classic plugins

Classic plugins provide Elasticsearch with mechanisms for custom authentication, authorization, scoring, and more.

Classic plugins are ZIP files composed of JAR files and a metadata file called plugin-descriptor.properties, a Java properties file that describes the plugin.

Note that only JAR files at the root of the plugin are added to the classpath for the plugin. If you need other resources, package them into a resources JAR.

The Elasticsearch repository contains examples of plugins. Some of these include:

These examples provide the bare bones needed to get started. For more information about how to write a plugin, we recommend looking at the source code of existing plugins for inspiration.

Use bin/elasticsearch-plugin install file:///path/to/your/plugin to install your plugin for testing. The Java plugin is auto-loaded only if it’s in the plugins/ directory.

Some plugins may need additional entitlements.

Elasticsearch limits the ability to perform certain security-sensitive actions as part of its Entitlement security mechanism (e.g. to limit the potential fallout from remote code execution (RCE) vulnerabilities).

The Entitlement model is based on Java modules. An entitlement granted to a Java module allows the module’s code to perform the security-sensitive action associated with that entitlement. For example, the ability to create threads is limited to modules that have the manage_threads entitlement; likewise, the ability to read a file from the filesystem is limited to modules that have the files entitlement for that particular file.

In practice, an entitlement allows plugin code to call a well-defined set of corresponding JDK methods; without the entitlement calls to those JDK methods are denied and throw a NotEntitledException. Plugin can include the optional entitlement-policy.yaml file to define modules and required entitlements. Any additional entitlement requested by the plugin will be displayed to the user with a large warning, and users will have to confirm them when installing the plugin interactively. Therefore, it is best to avoid requesting any spurious entitlement!

If you are using the Elasticsearch Gradle build system, place this file in src/main/plugin-metadata and it will be applied during unit tests as well.

An entitlement policy applies to all of your plugin jars (your own code and third party dependencies). You have to write your policy file accordingly. For example, if a plugin uses the Example API client to perform network operations, it will need a policy that may look like this:

org.elasticsearch.example-plugin:
  - manage_threads
com.example.api.client:
  - set_https_connection_properties
  - outbound_network

Note how the network related entitlements are granted to the com.example.api.client module, as the code performing the sensitive network operations is in the example-api-client dependency.

If your plugin is not modular, all entitlements must be specified under the catch-all ALL-UNNAMED module name:

ALL-UNNAMED:
  - manage_threads
  - set_https_connection_properties
  - outbound_network