From 9fd3748c10cb0b74b0ab9a7d49ee0b211e955e37 Mon Sep 17 00:00:00 2001 From: Lorenzo Dematte Date: Thu, 24 Apr 2025 15:11:17 +0200 Subject: [PATCH 1/2] small docs fixes --- docs/extend/creating-classic-plugins.md | 8 ++++++-- libs/entitlement/README.md | 2 +- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/extend/creating-classic-plugins.md b/docs/extend/creating-classic-plugins.md index 96f405bd45219..ad67a154b1e69 100644 --- a/docs/extend/creating-classic-plugins.md +++ b/docs/extend/creating-classic-plugins.md @@ -80,8 +80,12 @@ 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: in general this entitlement should *not* be needed! Your plugin should use {{es}} thread pools and executors (see `Plugin#getExecutorBuilders`) instead of creating and managing its own threads. 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 create and manage their own threads. In this case it is justifiable to request this entitlement. Example: ```yaml diff --git a/libs/entitlement/README.md b/libs/entitlement/README.md index 707afe4f8f4fb..261c95eb3f6be 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. From 7468aa798394ebc642c44b41d0e3051946f0d8ab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lorenzo=20Dematt=C3=A9?= Date: Thu, 24 Apr 2025 16:58:09 +0200 Subject: [PATCH 2/2] Update docs/extend/creating-classic-plugins.md Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com> --- docs/extend/creating-classic-plugins.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/extend/creating-classic-plugins.md b/docs/extend/creating-classic-plugins.md index ad67a154b1e69..469e904b9c0a5 100644 --- a/docs/extend/creating-classic-plugins.md +++ b/docs/extend/creating-classic-plugins.md @@ -82,10 +82,11 @@ The entitlements currently implemented and enforced in {{es}} that are available Allows code to call methods that create or modify properties on Java Threads, for example `Thread#start` or `ThreadGroup#setMaxPriority`. -NOTE: in general this entitlement should *not* be needed! Your plugin should use {{es}} thread pools and executors (see `Plugin#getExecutorBuilders`) instead of creating and managing its own threads. Setting the name, priority, daemon state and context class loader are things no plugins should do when executing on -{{es}} threadpools. +:::{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 (e.g. Apache HTTP client) need to create and manage their own threads. In this case it is justifiable to request this entitlement. +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