elasticsearch/docs/plugins/development/creating-classic-plugins.asciidoc

[[creating-classic-plugins]]
=== Creating classic plugins

Classic plugins provide {es} with mechanisms for custom authentication,
authorization, scoring, and more.

[IMPORTANT]
.Plugin release lifecycle
==============================================

Classic plugins require you to build a new version for each new {es} release.
This version is checked when the plugin is installed and when it is loaded. {es}
will refuse to start in the presence of plugins with the incorrect
`elasticsearch.version`.

==============================================

[discrete]
==== Classic plugin file structure

Classis plugins are ZIP files composed of JAR files and
<<plugin-descriptor-file-{plugin-type},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.

[discrete]
==== Example plugins

The {es} repository contains {es-repo}tree/main/plugins/examples[examples of plugins]. Some of these include:

* a plugin with {es-repo}tree/main/plugins/examples/custom-settings[custom settings]
* adding {es-repo}tree/main/plugins/examples/rest-handler[custom rest endpoints]
* adding a {es-repo}tree/main/plugins/examples/rescore[custom rescorer]
* a script {es-repo}tree/main/plugins/examples/script-expert-scoring[implemented in Java]

These examples provide the bare bones needed to get started. For more
information about how to write a plugin, we recommend looking at the 
{es-repo}tree/main/plugins/[source code of existing plugins] for inspiration.

[discrete]
==== Testing your plugin

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.

[discrete]
[[plugin-authors-jsm]]
==== Java Security permissions

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 {es} Gradle build system, place this file in
`src/main/plugin-metadata` and it will be applied during unit tests as well.

The Java security model is stack-based, and additional
permissions are granted to the jars in your plugin, so you have to
write proper security code around operations requiring elevated privileges.
You might add a check to prevent unprivileged code (such as scripts)
from gaining escalated permissions. For example:

[source,java]
--------------------------------------------------
// 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
);
--------------------------------------------------

Check https://www.oracle.com/technetwork/java/seccodeguide-139067.html[Secure Coding Guidelines for Java SE]
for more information.

[[plugin-descriptor-file-classic]]
==== The plugin descriptor file for classic plugins

include::plugin-descriptor-file.asciidoc[]