From e9bedf118401c431d8a31a80299a482249bbd6e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lorenzo=20Dematt=C3=A9?= Date: Thu, 24 Apr 2025 18:11:18 +0200 Subject: [PATCH] [Entitlements] Small docs fixes (#127323) --- docs/extend/creating-classic-plugins.md | 9 +++++++-- libs/entitlement/README.md | 2 +- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/extend/creating-classic-plugins.md b/docs/extend/creating-classic-plugins.md index 96f405bd4521..469e904b9c0a 100644 --- a/docs/extend/creating-classic-plugins.md +++ b/docs/extend/creating-classic-plugins.md @@ -80,8 +80,13 @@ The entitlements currently implemented and enforced in {{es}} that are available #### `manage_threads` -Allows code to call methods that create or modify properties on Java Threads, for example `Thread#start` or `ThreadGroup#setMaxPriority`. In general, setting the name, priority, daemon state and context class loader are things no plugins should do when executing on -{{es}} threadpools; however, many 3rd party libraries that support async operations (e.g. Apache HTTP client) need to manage their own threads. In this case it is justifiable to request this entitlement. +Allows code to call methods that create or modify properties on Java Threads, for example `Thread#start` or `ThreadGroup#setMaxPriority`. + +:::{note} +This entitlement is rarely necessary. Your plugin should use {{es}} 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: ```yaml diff --git a/libs/entitlement/README.md b/libs/entitlement/README.md index 707afe4f8f4f..261c95eb3f6b 100644 --- a/libs/entitlement/README.md +++ b/libs/entitlement/README.md @@ -170,7 +170,7 @@ java.lang.IllegalStateException: Invalid module name in policy: layer [server] d IMPORTANT: this patching mechanism is intended to be used **only** for emergencies; once a missing entitlement is identified, the fix needs to be applied to the codebase, by raising a PR or submitting a bug via Github so that the bundled policies can be fixed. -### How to migrate a from a Java Security Manager Policy to an entitlement policy +### How to migrate from a Java Security Manager Policy to an entitlement policy Translating Java Security Permissions to Entitlements is usually not too difficult; - many permissions are not used anymore. The Entitlement system is targeting sensitive actions we identified as crucial to our code; any other permission is not checked anymore. Also, we do not have any entitlement related to reflection or access checks: Elasticsearch runs modularized, and we leverage and trust the Java module mechanism to enforce access and visibility.