Help for plugin authors

The Elasticsearch repository contains examples of:

These examples provide the bare bones needed to get started. For more information about how to write a plugin, we recommend looking at the plugins listed in this documentation for inspiration.

All plugin files must be contained in a directory called elasticsearch.

All plugins must contain a file called plugin-descriptor.properties in the folder named elasticsearch. The format for this file is described in detail in this example:

# Elasticsearch plugin descriptor file
# This file must exist as 'plugin-descriptor.properties' in a folder named `elasticsearch`
# inside all plugins.
#
### example plugin for "foo"
#
# foo.zip <-- zip file for the plugin, with this structure:
#|____elasticsearch/
#| |____   <arbitrary name1>.jar <-- classes, resources, dependencies
#| |____   <arbitrary nameN>.jar <-- any number of jars
#| |____   plugin-descriptor.properties <-- example contents below:
#
# classname=foo.bar.BazPlugin
# description=My cool plugin
# version=2.0
# elasticsearch.version=2.0
# java.version=1.7
#
### mandatory elements for all plugins:
#
# 'description': simple summary of the plugin
description=${description}
#
# 'version': plugin's version
version=${version}
#
# 'name': the plugin name
name=${name}
#
# 'classname': the name of the class to load, fully-qualified.
classname=${classname}
#
# 'java.version': version of java the code is built against
# use the system property java.specification.version
# version string must be a sequence of nonnegative decimal integers
# separated by "."'s and may have leading zeros
java.version=${javaVersion}
#
# 'elasticsearch.version': version of elasticsearch compiled against
elasticsearch.version=${elasticsearchVersion}
### optional elements for plugins:
#
#  'extended.plugins': other plugins this plugin extends through SPI
extended.plugins=${extendedPlugins}
#
# 'has.native.controller': whether or not the plugin has a native controller
has.native.controller=${hasNativeController}
#
# 'requires.keystore': whether or not the plugin needs the elasticsearch keystore be created
requires.keystore=${requiresKeystore}

Either fill in this template yourself or, if you are using Elasticsearch’s Gradle build system, you can fill in the necessary values in the build.gradle file for your plugin.

Note that only jar files in the elasticsearch directory are added to the classpath for the plugin! If you need other resources, package them into a resources jar.

When testing a Java plugin, it will only be auto-loaded if it is in the plugins/ directory. Use bin/elasticsearch-plugin install file:///path/to/your/plugin to install your plugin for testing.

You may also load your plugin within the test framework for integration tests. Read more in Changing Node Configuration.

Some plugins may need additional security permissions. A plugin can include the optional plugin-security.policy file containing grant statements for additional permissions. Any additional permissions will be displayed to the user with a large warning, and they will have to confirm them when installing the plugin interactively. So if possible, it is best to avoid requesting any spurious permissions!

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.

Keep in mind that the Java security model is stack-based, and the additional permissions will only be granted to the jars in your plugin, so you will have write proper security code around operations requiring elevated privileges. It is recommended to add a check to prevent unprivileged code (such as scripts) from gaining escalated permissions. For example:

// ES permission you should check before doPrivileged() blocks
import org.elasticsearch.SpecialPermission;

SecurityManager sm = System.getSecurityManager();
if (sm != null) {
  // unprivileged code such as scripts do not have SpecialPermission
  sm.checkPermission(new SpecialPermission());
}
AccessController.doPrivileged(
  // sensitive operation
);

See Secure Coding Guidelines for Java SE for more information.

It is also possible to bundle multiple plugins into a meta plugin. A directory for each sub-plugin must be contained in a directory called elasticsearch. The meta plugin must also contain a file called `meta-plugin-descriptor.properties in the directory named elasticsearch. The format for this file is described in detail in this example:

# Elasticsearch meta plugin descriptor file
# This file must exist as 'meta-plugin-descriptor.properties' in a folder named `elasticsearch`.
#
### example meta plugin for "meta-foo"
#
# meta-foo.zip <-- zip file for the meta plugin, with this structure:
#|____elasticsearch/
#| |____   <bundled_plugin_1> <-- The plugin files for bundled_plugin_1 (the content of the elastisearch directory)
#| |____   <bundled_plugin_2>  <-- The plugin files for bundled_plugin_2
#| |____   meta-plugin-descriptor.properties <-- example contents below:
#
# description=My meta plugin
# name=meta-foo
#
### mandatory elements for all meta plugins:
#
# 'description': simple summary of the meta plugin
description=${description}
#
# 'name': the meta plugin name
name=${name}

A meta plugin can be installed/removed like a normal plugin with the bin/elasticsearch-plugin command.