« Creating classic plugins The plugin descriptor file for classic plugins »
Elastic Docs ›Elasticsearch Plugins and Integrations [8.18] ›Creating an Elasticsearch plugin ›Creating classic plugins

Entitlements

edit
A newer version is available. Check out the latest documentation.

Entitlements

edit

The entitlements currently implemented and enforced in Elasticsearch that are available to plugins are the following ones:

manage_threads

edit

Allows code to call methods that create or modify properties on Java Threads, for example Thread#start or ThreadGroup#setMaxPriority.

This entitlement is rarely necessary. Your plugin should use Elasticsearch thread pools and executors (see Plugin#getExecutorBuilders) instead of creating and managing its own threads. Plugins should avoid modifying thread name, priority, daemon state, and context class loader when executing on ES threadpools.

However, many 3rd party libraries that support async operations, such as the Apache HTTP client, need to create and manage their own threads. In such cases, it makes sense to request this entitlement.

Example:

org.example.module: # or 'ALL-UNNAMED' if the plugin is non-modular
  - manage_threads

outbound_network

edit

Allows code to call methods to make a network connection. Elasticsearch does not grant any network access by default; each plugin that needs to directly connect to an external resource (e.g. to upload or download data) must request this entitlement.

Example:

org.example.module: # or 'ALL-UNNAMED' if the plugin is non-modular
  - outbound_network

set_https_connection_properties

edit

Allows code to call methods to change properties on an established HTTPS connection. While this is generally innocuous (e.g. the google API client uses it to modify the HTTPS connections they just created), these methods can allow code to change arbitrary connections.

Example:

org.example.module: # or 'ALL-UNNAMED' if the plugin is non-modular
  - set_https_connection_properties

inbound_network (deprecated)

edit

Allows code to call methods to listen for incoming connections, so external resources can connect directly to your plugin. This entitlement should only be used when absolutely necessary (e.g. if a library you depend on requires it for authentication). Granting it makes the Elasticsearch node more vulnerable to attacks. This entitlement is deprecated, and can be removed in a future version of Elasticsearch.

Example:

org.example.module: # or 'ALL-UNNAMED' if the plugin is non-modular
  - inbound_network

load_native_libraries

edit

Allows code to load native libraries and call restricted methods. This entitlement also enables native access for modules it is granted to. Native code may alter the JVM or circumvent access checks such as file or network restrictions.

Example:

org.example.module: # or 'ALL-UNNAMED' if the plugin is non-modular
  - load_native_libraries

files

edit

Allows code to access the filesystem, to read or write paths as specified by the entitlement’s fields. The filesystem of the OS hosting Elasticsearch may contain sensitive files, for example credentials. Some files are meant to be always accessible to Elasticsearch, but plugins can not access them directly: Elasticsearch enforces that certain files can only be read by its core code, while some other files can not be read or written at all. A plugin is always granted read access to the Elasticsearch config directory and read_write access to the temp directory; if the plugin requires to read, write or access additional files or directories, it must specify them via this entitlement.

It is possible to specify 3 different types of file entitlement:

  • path to specify an absolute path
  • relative_path to specify a relative path. The path will be resolved via the relative_to field, which is used to qualify the relative path. It can be a specific Elasticsearch directory (config or data), or to the user home directory (home) (the home of the user running Elasticsearch)

  • relative_path to specify a path resolved via the relative_to field, which can have the following values:

    • config: the Elasticsearch config directory
    • data: the Elasticsearch data directory
    • home: the home directory of the user running Elasticsearch
    • path_setting to specify a path defined via an Elasticsearch setting. The path can be absolute or relative; in the latter case, the path will be resolved using the basedir_if_relative path (which can assume the same values as relative_to)

Each of the 3 types has some additional fields:

  • mode (required): can be either read or read_write
  • platform (optional): indicates this item applies only to one platform, which can be one of linux, macos or windows. On other platforms, the item is ignored. If this field is not specified, the item applies to all platforms.
  • exclusive: access to this path is exclusive for this plugin; this means that other plugins will not be able to access to it, not even if they have an entitlement that would normally grant access to that path.

Example:

org.example.module: # or 'ALL-UNNAMED' if the plugin is non-modular
  - files:
    - path: "/absolute/path"
      mode: read
    - relative_path: "relative/file.txt"
      relative_to: data
      mode: read_write
    - path_setting: setting.name
      basedir_if_relative: data
      mode: read

write_system_properties

edit

Allows code to set one or more system properties (e.g. by calling System#setProperty). The code to which this entitlement is granted can change the properties listed in the properties field. In general, it’s best to avoid changing a system property dynamically as this can have effects on code which later reads the property. The global nature of system properties means one plugin could then affect another, depending on load order.

Example:

org.example.module: # or 'ALL-UNNAMED' if the plugin is non-modular
  - write_system_properties:
      properties:
        - property.one
        - property.two

Check the Entitlements README in the elasticsearch repository for more information.

« Creating classic plugins The plugin descriptor file for classic plugins »