94 lines
3.6 KiB
Plaintext
94 lines
3.6 KiB
Plaintext
|
[[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.
|
||
|
|
|
||
|
|
You may also load your plugin within the test framework for integration tests.
|
||
|
|
Check {ref}/integration-tests.html#changing-node-configuration[Changing Node Configuration] for more information.
|
||
|
|
|
||
|
|
[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[]
|