diff --git a/.buildkite/pipelines/intake.yml b/.buildkite/pipelines/intake.yml index 31f6b6dce5fd2..4adc8a1d31aa6 100644 --- a/.buildkite/pipelines/intake.yml +++ b/.buildkite/pipelines/intake.yml @@ -56,7 +56,7 @@ steps: timeout_in_minutes: 300 matrix: setup: - BWC_VERSION: ["8.17.7", "8.18.2", "8.19.0", "9.0.2", "9.1.0"] + BWC_VERSION: ["8.17.7", "8.18.3", "8.19.0", "9.0.2", "9.1.0"] agents: provider: gcp image: family/elasticsearch-ubuntu-2004 diff --git a/.buildkite/pipelines/periodic-micro-benchmarks.yml b/.buildkite/pipelines/periodic-micro-benchmarks.yml new file mode 100644 index 0000000000000..29997ab192178 --- /dev/null +++ b/.buildkite/pipelines/periodic-micro-benchmarks.yml @@ -0,0 +1,10 @@ +steps: + - label: periodic-micro-benchmarks + command: | + .ci/scripts/run-gradle.sh :benchmarks:run --args 'org.elasticsearch.benchmark._nightly -rf json -rff build/result.json' + timeout_in_minutes: 300 + agents: + provider: gcp + image: family/elasticsearch-ubuntu-2004 + machineType: custom-32-98304 + buildDirectory: /dev/shm/bk diff --git a/.buildkite/pipelines/periodic-packaging.template.yml b/.buildkite/pipelines/periodic-packaging.template.yml index 8b2c3c04aa34e..417f8e9246234 100644 --- a/.buildkite/pipelines/periodic-packaging.template.yml +++ b/.buildkite/pipelines/periodic-packaging.template.yml @@ -40,6 +40,7 @@ steps: setup: image: - windows-2022 + - windows-2025 agents: provider: gcp image: family/elasticsearch-{{matrix.image}} diff --git a/.buildkite/pipelines/periodic-packaging.yml b/.buildkite/pipelines/periodic-packaging.yml index e2189ec313374..c5fdeb5737a52 100644 --- a/.buildkite/pipelines/periodic-packaging.yml +++ b/.buildkite/pipelines/periodic-packaging.yml @@ -319,8 +319,8 @@ steps: env: BWC_VERSION: 8.17.7 - - label: "{{matrix.image}} / 8.18.2 / packaging-tests-upgrade" - command: ./.ci/scripts/packaging-test.sh -Dbwc.checkout.align=true destructiveDistroUpgradeTest.v8.18.2 + - label: "{{matrix.image}} / 8.18.3 / packaging-tests-upgrade" + command: ./.ci/scripts/packaging-test.sh -Dbwc.checkout.align=true destructiveDistroUpgradeTest.v8.18.3 timeout_in_minutes: 300 matrix: setup: @@ -333,7 +333,7 @@ steps: machineType: custom-16-32768 buildDirectory: /dev/shm/bk env: - BWC_VERSION: 8.18.2 + BWC_VERSION: 8.18.3 - label: "{{matrix.image}} / 8.19.0 / packaging-tests-upgrade" command: ./.ci/scripts/packaging-test.sh -Dbwc.checkout.align=true destructiveDistroUpgradeTest.v8.19.0 @@ -393,6 +393,7 @@ steps: setup: image: - windows-2022 + - windows-2025 agents: provider: gcp image: family/elasticsearch-{{matrix.image}} diff --git a/.buildkite/pipelines/periodic-platform-support.yml b/.buildkite/pipelines/periodic-platform-support.yml index ea0d7b13b55b4..84577b917a007 100644 --- a/.buildkite/pipelines/periodic-platform-support.yml +++ b/.buildkite/pipelines/periodic-platform-support.yml @@ -38,6 +38,7 @@ steps: setup: image: - windows-2022 + - windows-2025 GRADLE_TASK: - checkPart1 - checkPart2 diff --git a/.buildkite/pipelines/periodic.yml b/.buildkite/pipelines/periodic.yml index c007452bb4f6d..f49de2b030a49 100644 --- a/.buildkite/pipelines/periodic.yml +++ b/.buildkite/pipelines/periodic.yml @@ -344,8 +344,8 @@ steps: - signal_reason: agent_stop limit: 3 - - label: 8.18.2 / bwc - command: .ci/scripts/run-gradle.sh -Dbwc.checkout.align=true v8.18.2#bwcTest + - label: 8.18.3 / bwc + command: .ci/scripts/run-gradle.sh -Dbwc.checkout.align=true v8.18.3#bwcTest timeout_in_minutes: 300 agents: provider: gcp @@ -354,7 +354,7 @@ steps: buildDirectory: /dev/shm/bk preemptible: true env: - BWC_VERSION: 8.18.2 + BWC_VERSION: 8.18.3 retry: automatic: - exit_status: "-1" @@ -486,7 +486,7 @@ steps: setup: ES_RUNTIME_JAVA: - openjdk21 - BWC_VERSION: ["8.17.7", "8.18.2", "8.19.0", "9.0.2", "9.1.0"] + BWC_VERSION: ["8.17.7", "8.18.3", "8.19.0", "9.0.2", "9.1.0"] agents: provider: gcp image: family/elasticsearch-ubuntu-2004 @@ -529,7 +529,7 @@ steps: ES_RUNTIME_JAVA: - openjdk21 - openjdk23 - BWC_VERSION: ["8.17.7", "8.18.2", "8.19.0", "9.0.2", "9.1.0"] + BWC_VERSION: ["8.17.7", "8.18.3", "8.19.0", "9.0.2", "9.1.0"] agents: provider: gcp image: family/elasticsearch-ubuntu-2004 diff --git a/.buildkite/pipelines/pull-request/packaging-tests-windows.yml b/.buildkite/pipelines/pull-request/packaging-tests-windows.yml index df5505bea9a62..93b7872c8b5a8 100644 --- a/.buildkite/pipelines/pull-request/packaging-tests-windows.yml +++ b/.buildkite/pipelines/pull-request/packaging-tests-windows.yml @@ -11,6 +11,7 @@ steps: setup: image: - windows-2022 + - windows-2025 PACKAGING_TASK: - default-windows-archive agents: diff --git a/.ci/bwcVersions b/.ci/bwcVersions index 2cd0d1da12f2e..312906a89c73e 100644 --- a/.ci/bwcVersions +++ b/.ci/bwcVersions @@ -17,7 +17,7 @@ BWC_VERSION: - "8.15.5" - "8.16.6" - "8.17.7" - - "8.18.2" + - "8.18.3" - "8.19.0" - "9.0.2" - "9.1.0" diff --git a/.ci/scripts/run-gradle.sh b/.ci/scripts/run-gradle.sh index b091c4a7c7d89..b19eec92449f9 100755 --- a/.ci/scripts/run-gradle.sh +++ b/.ci/scripts/run-gradle.sh @@ -41,4 +41,4 @@ else fi set -e -$GRADLEW -S --max-workers=$MAX_WORKERS $@ +$GRADLEW -S --max-workers=$MAX_WORKERS "$@" diff --git a/.ci/snapshotBwcVersions b/.ci/snapshotBwcVersions index 3f69c8fff9457..247bbc73e43e3 100644 --- a/.ci/snapshotBwcVersions +++ b/.ci/snapshotBwcVersions @@ -1,6 +1,6 @@ BWC_VERSION: - "8.17.7" - - "8.18.2" + - "8.18.3" - "8.19.0" - "9.0.2" - "9.1.0" diff --git a/benchmarks/src/main/java/org/elasticsearch/benchmark/esql/QueryPlanningBenchmark.java b/benchmarks/src/main/java/org/elasticsearch/benchmark/_nightly/esql/QueryPlanningBenchmark.java similarity index 88% rename from benchmarks/src/main/java/org/elasticsearch/benchmark/esql/QueryPlanningBenchmark.java rename to benchmarks/src/main/java/org/elasticsearch/benchmark/_nightly/esql/QueryPlanningBenchmark.java index 6ed1294e16299..d2811962dd29d 100644 --- a/benchmarks/src/main/java/org/elasticsearch/benchmark/esql/QueryPlanningBenchmark.java +++ b/benchmarks/src/main/java/org/elasticsearch/benchmark/_nightly/esql/QueryPlanningBenchmark.java @@ -7,7 +7,7 @@ * License v3.0 only", or the "Server Side Public License, v 1". */ -package org.elasticsearch.benchmark.esql; +package org.elasticsearch.benchmark._nightly.esql; import org.elasticsearch.common.logging.LogConfigurator; import org.elasticsearch.common.settings.Settings; @@ -67,9 +67,9 @@ public class QueryPlanningBenchmark { } private PlanTelemetry telemetry; - private EsqlParser parser; - private Analyzer analyzer; - private LogicalPlanOptimizer optimizer; + private EsqlParser defaultParser; + private Analyzer manyFieldsAnalyzer; + private LogicalPlanOptimizer defaultOptimizer; @Setup public void setup() { @@ -100,8 +100,8 @@ public void setup() { var functionRegistry = new EsqlFunctionRegistry(); telemetry = new PlanTelemetry(functionRegistry); - parser = new EsqlParser(); - analyzer = new Analyzer( + defaultParser = new EsqlParser(); + manyFieldsAnalyzer = new Analyzer( new AnalyzerContext( config, functionRegistry, @@ -112,10 +112,10 @@ public void setup() { ), new Verifier(new Metrics(functionRegistry), new XPackLicenseState(() -> 0L)) ); - optimizer = new LogicalPlanOptimizer(new LogicalOptimizerContext(config, FoldContext.small())); + defaultOptimizer = new LogicalPlanOptimizer(new LogicalOptimizerContext(config, FoldContext.small())); } - private LogicalPlan plan(String query) { + private LogicalPlan plan(EsqlParser parser, Analyzer analyzer, LogicalPlanOptimizer optimizer, String query) { var parsed = parser.createStatement(query, new QueryParams(), telemetry); var analyzed = analyzer.analyze(parsed); var optimized = optimizer.optimize(analyzed); @@ -124,6 +124,6 @@ private LogicalPlan plan(String query) { @Benchmark public void manyFields(Blackhole blackhole) { - blackhole.consume(plan("FROM test | LIMIT 10")); + blackhole.consume(plan(defaultParser, manyFieldsAnalyzer, defaultOptimizer, "FROM test | LIMIT 10")); } } diff --git a/benchmarks/src/main/java/org/elasticsearch/benchmark/compute/operator/EvalBenchmark.java b/benchmarks/src/main/java/org/elasticsearch/benchmark/compute/operator/EvalBenchmark.java index 6fa015df4aac5..5bd003fe4271f 100644 --- a/benchmarks/src/main/java/org/elasticsearch/benchmark/compute/operator/EvalBenchmark.java +++ b/benchmarks/src/main/java/org/elasticsearch/benchmark/compute/operator/EvalBenchmark.java @@ -13,6 +13,7 @@ import org.elasticsearch.common.breaker.NoopCircuitBreaker; import org.elasticsearch.common.logging.LogConfigurator; import org.elasticsearch.common.settings.Settings; +import org.elasticsearch.common.unit.ByteSizeUnit; import org.elasticsearch.common.util.BigArrays; import org.elasticsearch.compute.data.Block; import org.elasticsearch.compute.data.BlockFactory; @@ -44,13 +45,15 @@ import org.elasticsearch.xpack.esql.expression.function.scalar.conditional.Case; import org.elasticsearch.xpack.esql.expression.function.scalar.date.DateTrunc; import org.elasticsearch.xpack.esql.expression.function.scalar.math.Abs; +import org.elasticsearch.xpack.esql.expression.function.scalar.math.RoundTo; import org.elasticsearch.xpack.esql.expression.function.scalar.multivalue.MvMin; import org.elasticsearch.xpack.esql.expression.function.scalar.nulls.Coalesce; -import org.elasticsearch.xpack.esql.expression.function.scalar.string.RLike; import org.elasticsearch.xpack.esql.expression.function.scalar.string.ToLower; import org.elasticsearch.xpack.esql.expression.function.scalar.string.ToUpper; +import org.elasticsearch.xpack.esql.expression.function.scalar.string.regex.RLike; import org.elasticsearch.xpack.esql.expression.predicate.operator.arithmetic.Add; import org.elasticsearch.xpack.esql.expression.predicate.operator.comparison.Equals; +import org.elasticsearch.xpack.esql.expression.predicate.operator.comparison.LessThan; import org.elasticsearch.xpack.esql.planner.Layout; import org.elasticsearch.xpack.esql.plugin.EsqlPlugin; import org.elasticsearch.xpack.esql.session.Configuration; @@ -128,6 +131,10 @@ static void selfTest() { "long_equal_to_int", "mv_min", "mv_min_ascending", + "round_to_4_via_case", + "round_to_2", + "round_to_3", + "round_to_4", "rlike", "to_lower", "to_lower_ords", @@ -240,6 +247,65 @@ private static EvalOperator.ExpressionEvaluator evaluator(String operation) { RLike rlike = new RLike(Source.EMPTY, keywordField, new RLikePattern(".ar")); yield EvalMapper.toEvaluator(FOLD_CONTEXT, rlike, layout(keywordField)).get(driverContext); } + case "round_to_4_via_case" -> { + FieldAttribute f = longField(); + + Expression ltkb = new LessThan(Source.EMPTY, f, kb()); + Expression ltmb = new LessThan(Source.EMPTY, f, mb()); + Expression ltgb = new LessThan(Source.EMPTY, f, gb()); + EvalOperator.ExpressionEvaluator evaluator = EvalMapper.toEvaluator( + FOLD_CONTEXT, + new Case(Source.EMPTY, ltkb, List.of(b(), ltmb, kb(), ltgb, mb(), gb())), + layout(f) + ).get(driverContext); + String desc = "CaseLazyEvaluator"; + if (evaluator.toString().contains(desc) == false) { + throw new IllegalArgumentException("Evaluator was [" + evaluator + "] but expected one containing [" + desc + "]"); + } + yield evaluator; + } + case "round_to_2" -> { + FieldAttribute f = longField(); + + EvalOperator.ExpressionEvaluator evaluator = EvalMapper.toEvaluator( + FOLD_CONTEXT, + new RoundTo(Source.EMPTY, f, List.of(b(), kb())), + layout(f) + ).get(driverContext); + String desc = "RoundToLong2"; + if (evaluator.toString().contains(desc) == false) { + throw new IllegalArgumentException("Evaluator was [" + evaluator + "] but expected one containing [" + desc + "]"); + } + yield evaluator; + } + case "round_to_3" -> { + FieldAttribute f = longField(); + + EvalOperator.ExpressionEvaluator evaluator = EvalMapper.toEvaluator( + FOLD_CONTEXT, + new RoundTo(Source.EMPTY, f, List.of(b(), kb(), mb())), + layout(f) + ).get(driverContext); + String desc = "RoundToLong3"; + if (evaluator.toString().contains(desc) == false) { + throw new IllegalArgumentException("Evaluator was [" + evaluator + "] but expected one containing [" + desc + "]"); + } + yield evaluator; + } + case "round_to_4" -> { + FieldAttribute f = longField(); + + EvalOperator.ExpressionEvaluator evaluator = EvalMapper.toEvaluator( + FOLD_CONTEXT, + new RoundTo(Source.EMPTY, f, List.of(b(), kb(), mb(), gb())), + layout(f) + ).get(driverContext); + String desc = "RoundToLong4"; + if (evaluator.toString().contains(desc) == false) { + throw new IllegalArgumentException("Evaluator was [" + evaluator + "] but expected one containing [" + desc + "]"); + } + yield evaluator; + } case "to_lower", "to_lower_ords" -> { FieldAttribute keywordField = keywordField(); ToLower toLower = new ToLower(Source.EMPTY, keywordField, configuration()); @@ -419,6 +485,69 @@ private static void checkExpected(String operation, Page actual) { } } } + case "round_to_4_via_case", "round_to_4" -> { + long b = 1; + long kb = ByteSizeUnit.KB.toBytes(1); + long mb = ByteSizeUnit.MB.toBytes(1); + long gb = ByteSizeUnit.GB.toBytes(1); + + LongVector f = actual.getBlock(0).asVector(); + LongVector result = actual.getBlock(1).asVector(); + for (int i = 0; i < BLOCK_LENGTH; i++) { + long expected = f.getLong(i); + if (expected < kb) { + expected = b; + } else if (expected < mb) { + expected = kb; + } else if (expected < gb) { + expected = mb; + } else { + expected = gb; + } + if (result.getLong(i) != expected) { + throw new AssertionError("[" + operation + "] expected [" + expected + "] but was [" + result.getLong(i) + "]"); + } + } + } + case "round_to_3" -> { + long b = 1; + long kb = ByteSizeUnit.KB.toBytes(1); + long mb = ByteSizeUnit.MB.toBytes(1); + + LongVector f = actual.getBlock(0).asVector(); + LongVector result = actual.getBlock(1).asVector(); + for (int i = 0; i < BLOCK_LENGTH; i++) { + long expected = f.getLong(i); + if (expected < kb) { + expected = b; + } else if (expected < mb) { + expected = kb; + } else { + expected = mb; + } + if (result.getLong(i) != expected) { + throw new AssertionError("[" + operation + "] expected [" + expected + "] but was [" + result.getLong(i) + "]"); + } + } + } + case "round_to_2" -> { + long b = 1; + long kb = ByteSizeUnit.KB.toBytes(1); + + LongVector f = actual.getBlock(0).asVector(); + LongVector result = actual.getBlock(1).asVector(); + for (int i = 0; i < BLOCK_LENGTH; i++) { + long expected = f.getLong(i); + if (expected < kb) { + expected = b; + } else { + expected = kb; + } + if (result.getLong(i) != expected) { + throw new AssertionError("[" + operation + "] expected [" + expected + "] but was [" + result.getLong(i) + "]"); + } + } + } case "to_lower" -> checkBytes(operation, actual, false, new BytesRef[] { new BytesRef("foo"), new BytesRef("bar") }); case "to_lower_ords" -> checkBytes(operation, actual, true, new BytesRef[] { new BytesRef("foo"), new BytesRef("bar") }); case "to_upper" -> checkBytes(operation, actual, false, new BytesRef[] { new BytesRef("FOO"), new BytesRef("BAR") }); @@ -450,7 +579,7 @@ private static void checkBytes(String operation, Page actual, boolean expectOrds private static Page page(String operation) { return switch (operation) { - case "abs", "add", "date_trunc", "equal_to_const" -> { + case "abs", "add", "date_trunc", "equal_to_const", "round_to_4_via_case", "round_to_2", "round_to_3", "round_to_4" -> { var builder = blockFactory.newLongBlockBuilder(BLOCK_LENGTH); for (int i = 0; i < BLOCK_LENGTH; i++) { builder.appendLong(i * 100_000); @@ -540,6 +669,26 @@ private static Page page(String operation) { }; } + private static Literal b() { + return lit(1L); + } + + private static Literal kb() { + return lit(ByteSizeUnit.KB.toBytes(1)); + } + + private static Literal mb() { + return lit(ByteSizeUnit.MB.toBytes(1)); + } + + private static Literal gb() { + return lit(ByteSizeUnit.GB.toBytes(1)); + } + + private static Literal lit(long v) { + return new Literal(Source.EMPTY, v, DataType.LONG); + } + @Benchmark @OperationsPerInvocation(1024 * BLOCK_LENGTH) public void run() { diff --git a/benchmarks/src/main/java/org/elasticsearch/benchmark/compute/operator/TopNBenchmark.java b/benchmarks/src/main/java/org/elasticsearch/benchmark/compute/operator/TopNBenchmark.java index 945e7b6c14fca..24006463ce4c4 100644 --- a/benchmarks/src/main/java/org/elasticsearch/benchmark/compute/operator/TopNBenchmark.java +++ b/benchmarks/src/main/java/org/elasticsearch/benchmark/compute/operator/TopNBenchmark.java @@ -125,6 +125,7 @@ private static Operator operator(String data, int topCount) { topCount, elementTypes, encoders, + List.of(), IntStream.range(0, count).mapToObj(c -> new TopNOperator.SortOrder(c, false, false)).toList(), 16 * 1024 ); diff --git a/benchmarks/src/main/java/org/elasticsearch/benchmark/script/ScriptScoreBenchmark.java b/benchmarks/src/main/java/org/elasticsearch/benchmark/script/ScriptScoreBenchmark.java index e61171aeff027..b94af73a6b5f2 100644 --- a/benchmarks/src/main/java/org/elasticsearch/benchmark/script/ScriptScoreBenchmark.java +++ b/benchmarks/src/main/java/org/elasticsearch/benchmark/script/ScriptScoreBenchmark.java @@ -30,8 +30,10 @@ import org.elasticsearch.index.fielddata.IndexFieldDataCache; import org.elasticsearch.index.fielddata.IndexNumericFieldData; import org.elasticsearch.index.mapper.MappedFieldType; +import org.elasticsearch.index.mapper.MappingLookup; import org.elasticsearch.index.mapper.NumberFieldMapper.NumberFieldType; import org.elasticsearch.index.mapper.NumberFieldMapper.NumberType; +import org.elasticsearch.index.mapper.SourceFieldMetrics; import org.elasticsearch.indices.breaker.CircuitBreakerService; import org.elasticsearch.indices.breaker.NoneCircuitBreakerService; import org.elasticsearch.plugins.PluginsLoader; @@ -90,7 +92,7 @@ public class ScriptScoreBenchmark { private final SearchLookup lookup = new SearchLookup( fieldTypes::get, (mft, lookup, fdo) -> mft.fielddataBuilder(FieldDataContext.noRuntimeFields("benchmark")).build(fieldDataCache, breakerService), - SourceProvider.fromStoredFields() + SourceProvider.fromLookup(MappingLookup.EMPTY, null, SourceFieldMetrics.NOOP) ); @Param({ "expression", "metal", "painless_cast", "painless_def" }) diff --git a/build-tools-internal/gradle/wrapper/gradle-wrapper.properties b/build-tools-internal/gradle/wrapper/gradle-wrapper.properties index f373f37ad8290..3d25d539e993f 100644 --- a/build-tools-internal/gradle/wrapper/gradle-wrapper.properties +++ b/build-tools-internal/gradle/wrapper/gradle-wrapper.properties @@ -1,7 +1,7 @@ distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists -distributionSha256Sum=efe9a3d147d948d7528a9887fa35abcf24ca1a43ad06439996490f77569b02d1 -distributionUrl=https\://services.gradle.org/distributions/gradle-8.14-all.zip +distributionSha256Sum=d7042b3c11565c192041fc8c4703f541b888286404b4f267138c1d094d8ecdca +distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.1-all.zip networkTimeout=10000 validateDistributionUrl=true zipStoreBase=GRADLE_USER_HOME diff --git a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/ElasticsearchTestBasePlugin.java b/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/ElasticsearchTestBasePlugin.java index fa75a2011ab90..9fbba42d09ad3 100644 --- a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/ElasticsearchTestBasePlugin.java +++ b/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/ElasticsearchTestBasePlugin.java @@ -120,6 +120,7 @@ public void execute(Task t) { "--add-opens=java.base/java.nio.file=ALL-UNNAMED", "--add-opens=java.base/java.time=ALL-UNNAMED", "--add-opens=java.management/java.lang.management=ALL-UNNAMED", + "--enable-native-access=ALL-UNNAMED", "-XX:+HeapDumpOnOutOfMemoryError" ); diff --git a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/BreakingChangesGenerator.java b/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/BreakingChangesGenerator.java deleted file mode 100644 index 849e05742f2b8..0000000000000 --- a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/BreakingChangesGenerator.java +++ /dev/null @@ -1,85 +0,0 @@ -/* - * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one - * or more contributor license agreements. Licensed under the "Elastic License - * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side - * Public License v 1"; you may not use this file except in compliance with, at - * your election, the "Elastic License 2.0", the "GNU Affero General Public - * License v3.0 only", or the "Server Side Public License, v 1". - */ - -package org.elasticsearch.gradle.internal.release; - -import com.google.common.annotations.VisibleForTesting; - -import org.elasticsearch.gradle.VersionProperties; - -import java.io.File; -import java.io.FileWriter; -import java.io.IOException; -import java.nio.file.Files; -import java.util.HashMap; -import java.util.List; -import java.util.Map; -import java.util.Objects; -import java.util.TreeMap; - -import static java.util.Comparator.comparing; -import static java.util.stream.Collectors.groupingBy; -import static java.util.stream.Collectors.toList; - -/** - * Generates the page that contains breaking changes deprecations for a minor release series. - */ -public class BreakingChangesGenerator { - - static void update(File migrationTemplateFile, File migrationOutputFile, List entries) throws IOException { - try (FileWriter output = new FileWriter(migrationOutputFile)) { - output.write( - generateMigrationFile( - QualifiedVersion.of(VersionProperties.getElasticsearch()), - Files.readString(migrationTemplateFile.toPath()), - entries - ) - ); - } - } - - @VisibleForTesting - static String generateMigrationFile(QualifiedVersion version, String template, List entries) throws IOException { - final Map>> deprecationsByNotabilityByArea = entries.stream() - .map(ChangelogEntry::getDeprecation) - .filter(Objects::nonNull) - .sorted(comparing(ChangelogEntry.Deprecation::getTitle)) - .collect( - groupingBy( - ChangelogEntry.Deprecation::isNotable, - TreeMap::new, - groupingBy(ChangelogEntry.Deprecation::getArea, TreeMap::new, toList()) - ) - ); - - final Map>> breakingByNotabilityByArea = entries.stream() - .map(ChangelogEntry::getBreaking) - .filter(Objects::nonNull) - .sorted(comparing(ChangelogEntry.Breaking::getTitle)) - .collect( - groupingBy( - ChangelogEntry.Breaking::isNotable, - TreeMap::new, - groupingBy(ChangelogEntry.Breaking::getArea, TreeMap::new, toList()) - ) - ); - - final Map bindings = new HashMap<>(); - bindings.put("breakingByNotabilityByArea", breakingByNotabilityByArea); - bindings.put("deprecationsByNotabilityByArea", deprecationsByNotabilityByArea); - bindings.put("isElasticsearchSnapshot", version.isSnapshot()); - bindings.put("majorDotMinor", version.major() + "." + version.minor()); - bindings.put("majorDotMinorDotRevision", version.major() + "." + version.minor() + "." + version.revision()); - bindings.put("majorMinor", String.valueOf(version.major()) + version.minor()); - bindings.put("nextMajor", (version.major() + 1) + ".0"); - bindings.put("version", version); - - return TemplateUtils.render(template, bindings); - } -} diff --git a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/BundleChangelogsTask.java b/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/BundleChangelogsTask.java new file mode 100644 index 0000000000000..7749079a698d5 --- /dev/null +++ b/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/BundleChangelogsTask.java @@ -0,0 +1,252 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the "Elastic License + * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side + * Public License v 1"; you may not use this file except in compliance with, at + * your election, the "Elastic License 2.0", the "GNU Affero General Public + * License v3.0 only", or the "Server Side Public License, v 1". + */ + +package org.elasticsearch.gradle.internal.release; + +import com.fasterxml.jackson.annotation.JsonInclude; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.dataformat.yaml.YAMLFactory; +import com.fasterxml.jackson.dataformat.yaml.YAMLGenerator; + +import org.gradle.api.DefaultTask; +import org.gradle.api.file.ConfigurableFileCollection; +import org.gradle.api.file.Directory; +import org.gradle.api.file.DirectoryProperty; +import org.gradle.api.file.FileCollection; +import org.gradle.api.file.RegularFile; +import org.gradle.api.file.RegularFileProperty; +import org.gradle.api.logging.Logger; +import org.gradle.api.logging.Logging; +import org.gradle.api.model.ObjectFactory; +import org.gradle.api.tasks.InputDirectory; +import org.gradle.api.tasks.InputFiles; +import org.gradle.api.tasks.OutputFile; +import org.gradle.api.tasks.TaskAction; +import org.gradle.api.tasks.options.Option; +import org.gradle.process.ExecOperations; + +import java.io.File; +import java.io.IOException; +import java.io.StringReader; +import java.time.Instant; +import java.util.Comparator; +import java.util.List; +import java.util.Properties; +import java.util.Set; +import java.util.stream.Collectors; + +import javax.annotation.Nullable; +import javax.inject.Inject; + +import static java.util.stream.Collectors.toList; + +public class BundleChangelogsTask extends DefaultTask { + private static final Logger LOGGER = Logging.getLogger(BundleChangelogsTask.class); + + private final ConfigurableFileCollection changelogs; + + private final RegularFileProperty bundleFile; + private final DirectoryProperty changelogDirectory; + private final DirectoryProperty changelogBundlesDirectory; + + private final GitWrapper gitWrapper; + + @Nullable + private String branch; + @Nullable + private String bcRef; + + private boolean finalize; + + @Option(option = "branch", description = "Branch (or other ref) to use for generating the changelog bundle.") + public void setBranch(String branch) { + this.branch = branch; + } + + @Option( + option = "bc-ref", + description = "A source ref, typically the sha of a BC, that should be used to source PRs for changelog entries. " + + "The actual content of the changelogs will come from the 'branch' ref. " + + "You should generally always use bc-ref." + ) + public void setBcRef(String ref) { + this.bcRef = ref; + } + + @Option(option = "finalize", description = "Specify that the bundle is finalized, i.e. that the version has been released.") + public void setFinalize(boolean finalize) { + this.finalize = finalize; + } + + private static final ObjectMapper yamlMapper = new ObjectMapper( + new YAMLFactory().enable(YAMLGenerator.Feature.MINIMIZE_QUOTES) + .disable(YAMLGenerator.Feature.SPLIT_LINES) + .enable(YAMLGenerator.Feature.INDENT_ARRAYS_WITH_INDICATOR) + .disable(YAMLGenerator.Feature.WRITE_DOC_START_MARKER) + .enable(YAMLGenerator.Feature.LITERAL_BLOCK_STYLE) + ).setSerializationInclusion(JsonInclude.Include.NON_NULL); + + @Inject + public BundleChangelogsTask(ObjectFactory objectFactory, ExecOperations execOperations) { + changelogs = objectFactory.fileCollection(); + + bundleFile = objectFactory.fileProperty(); + changelogDirectory = objectFactory.directoryProperty(); + changelogBundlesDirectory = objectFactory.directoryProperty(); + + gitWrapper = new GitWrapper(execOperations); + } + + /* + Given a branch, and possibly a build candidate commit sha + Check out the changelog yaml files from the branch/BC sha + Then, bundle them all up into one file and write it to disk, along with a timestamp and whether the release is considered released + + When using a branch without a BC sha: + - Check out the changelog yaml files from the HEAD of the branch + + When using a BC sha: + - Check out the changelog yaml files from the BC commit + - Update those files with any updates from the HEAD of the branch (in case the changelogs get modified later) + - Check for any changelog yaml files that were added AFTER the BC, + but whose PR was merged before the BC (in case someone adds a forgotten changelog after the fact) + */ + @TaskAction + public void executeTask() throws IOException { + if (branch == null) { + throw new IllegalArgumentException("'branch' not specified."); + } + + final String upstreamRemote = gitWrapper.getUpstream(); + Set entriesFromBc = Set.of(); + + var didCheckoutChangelogs = false; + try { + var usingBcRef = bcRef != null && bcRef.isEmpty() == false; + if (usingBcRef) { + // Check out all the changelogs that existed at the time of the BC + checkoutChangelogs(gitWrapper, upstreamRemote, bcRef); + entriesFromBc = changelogDirectory.getAsFileTree().getFiles().stream().map(File::getName).collect(Collectors.toSet()); + + // Then add/update changelogs from the HEAD of the branch + // We do an "add" here, rather than checking out the entire directory, in case changelogs have been removed for some reason + addChangelogsFromRef(gitWrapper, upstreamRemote, branch); + } else { + checkoutChangelogs(gitWrapper, upstreamRemote, branch); + } + + didCheckoutChangelogs = true; + Properties props = new Properties(); + props.load( + new StringReader( + gitWrapper.runCommand("git", "show", upstreamRemote + "/" + branch + ":build-tools-internal/version.properties") + ) + ); + String version = props.getProperty("elasticsearch"); + + LOGGER.info("Finding changelog files for " + version + "..."); + + Set finalEntriesFromBc = entriesFromBc; + List entries = changelogDirectory.getAsFileTree().getFiles().stream().filter(f -> { + // When not using a bc ref, we just take everything from the branch/sha passed in + if (usingBcRef == false) { + return true; + } + + // If the changelog was present in the BC sha, always use it + if (finalEntriesFromBc.contains(f.getName())) { + return true; + } + + // Otherwise, let's check to see if a reference to the PR exists in the commit log for the sha + // This specifically covers the case of a PR being merged into the BC with a missing changelog file, and the file added + // later. + var prNumber = f.getName().replace(".yaml", ""); + var output = gitWrapper.runCommand("git", "log", bcRef, "--grep", "(#" + prNumber + ")"); + return output.trim().isEmpty() == false; + }).map(ChangelogEntry::parse).sorted(Comparator.comparing(ChangelogEntry::getPr)).collect(toList()); + + ChangelogBundle bundle = new ChangelogBundle(version, finalize, Instant.now().toString(), entries); + + yamlMapper.writeValue(new File("docs/release-notes/changelog-bundles/" + version + ".yml"), bundle); + } finally { + if (didCheckoutChangelogs) { + gitWrapper.runCommand("git", "restore", "-s@", "-SW", "--", changelogDirectory.get().toString()); + } + } + } + + private void checkoutChangelogs(GitWrapper gitWrapper, String upstream, String ref) { + gitWrapper.updateRemote(upstream); + + // If the changelog directory contains modified/new files, we should error out instead of wiping them out silently + var output = gitWrapper.runCommand("git", "status", "--porcelain", changelogDirectory.get().toString()).trim(); + if (output.isEmpty() == false) { + throw new IllegalStateException( + "Changelog directory contains changes that will be wiped out by this task:\n" + changelogDirectory.get() + "\n" + output + ); + } + + gitWrapper.runCommand("rm", "-rf", changelogDirectory.get().toString()); + var refSpec = upstream + "/" + ref; + if (ref.contains("upstream/")) { + refSpec = ref.replace("upstream/", upstream + "/"); + } else if (ref.matches("^[0-9a-f]+$")) { + refSpec = ref; + } + gitWrapper.runCommand("git", "checkout", refSpec, "--", changelogDirectory.get().toString()); + } + + private void addChangelogsFromRef(GitWrapper gitWrapper, String upstream, String ref) { + var refSpec = upstream + "/" + ref; + if (ref.contains("upstream/")) { + refSpec = ref.replace("upstream/", upstream + "/"); + } else if (ref.matches("^[0-9a-f]+$")) { + refSpec = ref; + } + + gitWrapper.runCommand("git", "checkout", refSpec, "--", changelogDirectory.get() + "/*.yaml"); + } + + @InputDirectory + public DirectoryProperty getChangelogDirectory() { + return changelogDirectory; + } + + public void setChangelogDirectory(Directory dir) { + this.changelogDirectory.set(dir); + } + + @InputDirectory + public DirectoryProperty getChangelogBundlesDirectory() { + return changelogBundlesDirectory; + } + + public void setChangelogBundlesDirectory(Directory dir) { + this.changelogBundlesDirectory.set(dir); + } + + @InputFiles + public FileCollection getChangelogs() { + return changelogs; + } + + public void setChangelogs(FileCollection files) { + this.changelogs.setFrom(files); + } + + @OutputFile + public RegularFileProperty getBundleFile() { + return bundleFile; + } + + public void setBundleFile(RegularFile file) { + this.bundleFile.set(file); + } +} diff --git a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/ChangelogBundle.java b/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/ChangelogBundle.java new file mode 100644 index 0000000000000..68e08d9769188 --- /dev/null +++ b/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/ChangelogBundle.java @@ -0,0 +1,52 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the "Elastic License + * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side + * Public License v 1"; you may not use this file except in compliance with, at + * your election, the "Elastic License 2.0", the "GNU Affero General Public + * License v3.0 only", or the "Server Side Public License, v 1". + */ + +package org.elasticsearch.gradle.internal.release; + +import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.dataformat.yaml.YAMLFactory; +import com.fasterxml.jackson.dataformat.yaml.YAMLGenerator; + +import org.gradle.api.logging.Logger; +import org.gradle.api.logging.Logging; + +import java.io.File; +import java.io.IOException; +import java.io.UncheckedIOException; +import java.util.List; + +public record ChangelogBundle(String version, boolean released, String generated, List changelogs) { + + private static final Logger LOGGER = Logging.getLogger(GenerateReleaseNotesTask.class); + private static final ObjectMapper yamlMapper = new ObjectMapper( + new YAMLFactory().enable(YAMLGenerator.Feature.MINIMIZE_QUOTES).disable(YAMLGenerator.Feature.SPLIT_LINES) + ); + + public ChangelogBundle(String version, String generated, List changelogs) { + this(version, false, generated, changelogs); + } + + public static ChangelogBundle parse(File file) { + try { + return yamlMapper.readValue(file, ChangelogBundle.class); + } catch (IOException e) { + LOGGER.error("Failed to parse changelog bundle from " + file.getAbsolutePath(), e); + throw new UncheckedIOException(e); + } + } + + public static ChangelogBundle copy(ChangelogBundle bundle) { + List changelogs = bundle.changelogs().stream().toList(); + return new ChangelogBundle(bundle.version(), bundle.released(), bundle.generated(), changelogs); + } + + public ChangelogBundle withChangelogs(List changelogs) { + return new ChangelogBundle(version, released, generated, changelogs); + } +} diff --git a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/ChangelogEntry.java b/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/ChangelogEntry.java index ff3ad2f944c52..e7b8cad1c8e49 100644 --- a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/ChangelogEntry.java +++ b/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/ChangelogEntry.java @@ -9,6 +9,7 @@ package org.elasticsearch.gradle.internal.release; +import com.fasterxml.jackson.annotation.JsonIgnore; import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.dataformat.yaml.YAMLFactory; @@ -35,12 +36,12 @@ public class ChangelogEntry { private static final Logger LOGGER = Logging.getLogger(GenerateReleaseNotesTask.class); private Integer pr; - private List issues; + private String summary; private String area; private String type; - private String summary; - private Highlight highlight; + private List issues; private Breaking breaking; + private Highlight highlight; private Deprecation deprecation; private static final ObjectMapper yamlMapper = new ObjectMapper(new YAMLFactory()); @@ -193,6 +194,7 @@ public void setBody(String body) { this.body = body; } + @JsonIgnore public String getAnchor() { return generatedAnchor(this.title); } @@ -278,6 +280,7 @@ public void setNotable(boolean notable) { this.notable = notable; } + @JsonIgnore public String getAnchor() { return generatedAnchor(this.title); } diff --git a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/GenerateReleaseNotesTask.java b/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/GenerateReleaseNotesTask.java index 87aa03f0445c5..655af7ae98c12 100644 --- a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/GenerateReleaseNotesTask.java +++ b/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/GenerateReleaseNotesTask.java @@ -13,75 +13,60 @@ import org.elasticsearch.gradle.VersionProperties; import org.gradle.api.DefaultTask; -import org.gradle.api.GradleException; -import org.gradle.api.file.ConfigurableFileCollection; -import org.gradle.api.file.FileCollection; +import org.gradle.api.file.Directory; +import org.gradle.api.file.DirectoryProperty; import org.gradle.api.file.RegularFile; import org.gradle.api.file.RegularFileProperty; import org.gradle.api.logging.Logger; import org.gradle.api.logging.Logging; import org.gradle.api.model.ObjectFactory; +import org.gradle.api.tasks.InputDirectory; import org.gradle.api.tasks.InputFile; -import org.gradle.api.tasks.InputFiles; import org.gradle.api.tasks.OutputFile; import org.gradle.api.tasks.TaskAction; import org.gradle.process.ExecOperations; -import java.io.File; import java.io.IOException; -import java.nio.file.Path; import java.util.ArrayList; -import java.util.HashMap; +import java.util.Comparator; import java.util.HashSet; -import java.util.Iterator; import java.util.List; -import java.util.Locale; -import java.util.Map; -import java.util.Set; -import java.util.stream.Stream; import javax.inject.Inject; -import static java.util.Comparator.naturalOrder; -import static java.util.stream.Collectors.toSet; - /** * Orchestrates the steps required to generate or update various release notes files. */ public class GenerateReleaseNotesTask extends DefaultTask { private static final Logger LOGGER = Logging.getLogger(GenerateReleaseNotesTask.class); - private final ConfigurableFileCollection changelogs; - - private final RegularFileProperty releaseNotesIndexTemplate; private final RegularFileProperty releaseNotesTemplate; private final RegularFileProperty releaseHighlightsTemplate; private final RegularFileProperty breakingChangesTemplate; - private final RegularFileProperty migrationIndexTemplate; + private final RegularFileProperty deprecationsTemplate; - private final RegularFileProperty releaseNotesIndexFile; private final RegularFileProperty releaseNotesFile; private final RegularFileProperty releaseHighlightsFile; - private final RegularFileProperty breakingChangesMigrationFile; - private final RegularFileProperty migrationIndexFile; + private final RegularFileProperty breakingChangesFile; + private final RegularFileProperty deprecationsFile; + + private final DirectoryProperty changelogBundleDirectory; private final GitWrapper gitWrapper; @Inject public GenerateReleaseNotesTask(ObjectFactory objectFactory, ExecOperations execOperations) { - changelogs = objectFactory.fileCollection(); - - releaseNotesIndexTemplate = objectFactory.fileProperty(); releaseNotesTemplate = objectFactory.fileProperty(); releaseHighlightsTemplate = objectFactory.fileProperty(); breakingChangesTemplate = objectFactory.fileProperty(); - migrationIndexTemplate = objectFactory.fileProperty(); + deprecationsTemplate = objectFactory.fileProperty(); - releaseNotesIndexFile = objectFactory.fileProperty(); releaseNotesFile = objectFactory.fileProperty(); releaseHighlightsFile = objectFactory.fileProperty(); - breakingChangesMigrationFile = objectFactory.fileProperty(); - migrationIndexFile = objectFactory.fileProperty(); + breakingChangesFile = objectFactory.fileProperty(); + deprecationsFile = objectFactory.fileProperty(); + + changelogBundleDirectory = objectFactory.directoryProperty(); gitWrapper = new GitWrapper(execOperations); } @@ -94,170 +79,42 @@ public void executeTask() throws IOException { findAndUpdateUpstreamRemote(gitWrapper); } - LOGGER.info("Finding changelog files..."); - - final Map> filesByVersion = partitionFilesByVersion( - gitWrapper, - currentVersion, - this.changelogs.getFiles() - ); - - final List entries = new ArrayList<>(); - final Map> changelogsByVersion = new HashMap<>(); - - filesByVersion.forEach((version, files) -> { - Set entriesForVersion = files.stream().map(ChangelogEntry::parse).collect(toSet()); - entries.addAll(entriesForVersion); - changelogsByVersion.put(version, entriesForVersion); - }); - - final Set versions = getVersions(gitWrapper, currentVersion); + LOGGER.info("Finding changelog bundles..."); + List allBundles = this.changelogBundleDirectory.getAsFileTree() + .getFiles() + .stream() + .map(ChangelogBundle::parse) + .toList(); - LOGGER.info("Updating release notes index..."); - ReleaseNotesIndexGenerator.update( - versions, - this.releaseNotesIndexTemplate.get().getAsFile(), - this.releaseNotesIndexFile.get().getAsFile() - ); + var bundles = getSortedBundlesWithUniqueChangelogs(allBundles); LOGGER.info("Generating release notes..."); - final QualifiedVersion qualifiedVersion = QualifiedVersion.of(currentVersion); - ReleaseNotesGenerator.update( - this.releaseNotesTemplate.get().getAsFile(), - this.releaseNotesFile.get().getAsFile(), - qualifiedVersion, - changelogsByVersion.getOrDefault(qualifiedVersion, Set.of()) - ); - - // Only update breaking changes and migration guide for new minors - if (qualifiedVersion.revision() == 0) { - LOGGER.info("Generating release highlights..."); - ReleaseHighlightsGenerator.update( - this.releaseHighlightsTemplate.get().getAsFile(), - this.releaseHighlightsFile.get().getAsFile(), - entries - ); - - LOGGER.info("Generating breaking changes / deprecations notes..."); - BreakingChangesGenerator.update( - this.breakingChangesTemplate.get().getAsFile(), - this.breakingChangesMigrationFile.get().getAsFile(), - entries - ); - - LOGGER.info("Updating migration/index..."); - MigrationIndexGenerator.update( - getMinorVersions(versions), - this.migrationIndexTemplate.get().getAsFile(), - this.migrationIndexFile.get().getAsFile() - ); - } + ReleaseNotesGenerator.update(this.releaseNotesTemplate.get().getAsFile(), this.releaseNotesFile.get().getAsFile(), bundles); + ReleaseNotesGenerator.update(this.breakingChangesTemplate.get().getAsFile(), this.breakingChangesFile.get().getAsFile(), bundles); + ReleaseNotesGenerator.update(this.deprecationsTemplate.get().getAsFile(), this.deprecationsFile.get().getAsFile(), bundles); } - /** - * Find all tags in the major series for the supplied version - * @param gitWrapper used to call `git` - * @param currentVersion the version to base the query upon - * @return all versions in the series - */ - @VisibleForTesting - static Set getVersions(GitWrapper gitWrapper, String currentVersion) { - QualifiedVersion qualifiedVersion = QualifiedVersion.of(currentVersion); - final String pattern = "v" + qualifiedVersion.major() + ".*"; - // We may be generating notes for a minor version prior to the latest minor, so we need to filter out versions that are too new. - Set versions = Stream.concat( - gitWrapper.listVersions(pattern).filter(v -> v.isBefore(qualifiedVersion)), - Stream.of(qualifiedVersion) - ).collect(toSet()); - - // If this is a new minor ensure we include the previous minor, which may not have been released - if (qualifiedVersion.minor() > 0 && qualifiedVersion.revision() == 0) { - QualifiedVersion previousMinor = new QualifiedVersion(qualifiedVersion.major(), qualifiedVersion.minor() - 1, 0, null); - versions.add(previousMinor); - } - - return versions; - } - - /** - * Convert set of QualifiedVersion to MinorVersion by deleting all but the major and minor components. - */ @VisibleForTesting - static Set getMinorVersions(Set versions) { - return versions.stream().map(MinorVersion::of).collect(toSet()); - } - - /** - * Group a set of files by the version in which they first appeared, up until the supplied version. Any files not - * present in an earlier version are assumed to have been introduced in the specified version. - * - *

This method works by finding all git tags prior to {@param versionString} in the same minor series, and - * examining the git tree for that tag. By doing this over each tag, it is possible to see how the contents - * of the changelog directory changed over time. - * - * @param gitWrapper used to call `git` - * @param versionString the "current" version. Does not require a tag in git. - * @param allFilesInCheckout the files to partition - * @return a mapping from version to the files added in that version. - */ - @VisibleForTesting - static Map> partitionFilesByVersion( - GitWrapper gitWrapper, - String versionString, - Set allFilesInCheckout - ) { - if (needsGitTags(versionString) == false) { - return Map.of(QualifiedVersion.of(versionString), allFilesInCheckout); - } - - QualifiedVersion currentVersion = QualifiedVersion.of(versionString); - - // Find all tags for this minor series, using a wildcard tag pattern. - String tagWildcard = String.format(Locale.ROOT, "v%d.%d*", currentVersion.major(), currentVersion.minor()); - - final List earlierVersions = gitWrapper.listVersions(tagWildcard) - // Only keep earlier versions, and if `currentVersion` is a prerelease, then only prereleases too. - .filter( - each -> each.isBefore(currentVersion) - && (currentVersion.isSnapshot() || (currentVersion.hasQualifier() == each.hasQualifier())) - ) - .sorted(naturalOrder()) + static List getSortedBundlesWithUniqueChangelogs(List bundles) { + List sorted = bundles.stream() + .sorted(Comparator.comparing(ChangelogBundle::released).reversed().thenComparing(ChangelogBundle::generated)) .toList(); - if (earlierVersions.isEmpty()) { - throw new GradleException("Failed to find git tags prior to [v" + currentVersion + "]"); - } - - Map> partitionedFiles = new HashMap<>(); - - Set mutableAllFilesInCheckout = new HashSet<>(allFilesInCheckout); - - // 1. For each earlier version - earlierVersions.forEach(earlierVersion -> { - // 2. Find all the changelog files it contained - Set filesInTreeForVersion = gitWrapper.listFiles("v" + earlierVersion, "docs/changelog") - .map(line -> Path.of(line).getFileName().toString()) - .collect(toSet()); - - Set filesForVersion = new HashSet<>(); - partitionedFiles.put(earlierVersion, filesForVersion); - - // 3. Find the `File` object for each one - final Iterator filesIterator = mutableAllFilesInCheckout.iterator(); - while (filesIterator.hasNext()) { - File nextFile = filesIterator.next(); - if (filesInTreeForVersion.contains(nextFile.getName())) { - // 4. And remove it so that it is associated with the earlier version - filesForVersion.add(nextFile); - filesIterator.remove(); - } + // Ensure that each changelog/PR only shows up once, in its earliest release + var uniquePrs = new HashSet(); + List modifiedBundles = new ArrayList<>(); + for (int i = sorted.size() - 1; i >= 0; i--) { + var bundle = sorted.get(i); + if (bundle.released() == false) { + List entries = bundle.changelogs().stream().filter(c -> false == uniquePrs.contains(c.getPr())).toList(); + modifiedBundles.add(bundle.withChangelogs(entries)); + } else { + modifiedBundles.add(bundle); } - }); - - // 5. Associate whatever is left with the current version. - partitionedFiles.put(currentVersion, mutableAllFilesInCheckout); + uniquePrs.addAll(bundle.changelogs().stream().map(ChangelogEntry::getPr).toList()); + } - return partitionedFiles; + return modifiedBundles; } /** @@ -266,18 +123,7 @@ static Map> partitionFilesByVersion( */ private static void findAndUpdateUpstreamRemote(GitWrapper gitWrapper) { LOGGER.info("Finding upstream git remote"); - // We need to ensure the tags are up-to-date. Find the correct remote to use - String upstream = gitWrapper.listRemotes() - .entrySet() - .stream() - .filter(entry -> entry.getValue().contains("elastic/elasticsearch")) - .findFirst() - .map(Map.Entry::getKey) - .orElseThrow( - () -> new GradleException( - "I need to ensure the git tags are up-to-date, but I couldn't find a git remote for [elastic/elasticsearch]" - ) - ); + String upstream = gitWrapper.getUpstream(); LOGGER.info("Updating remote [{}]", upstream); // Now update the remote, and make sure we update the tags too @@ -308,22 +154,13 @@ static boolean needsGitTags(String versionString) { return true; } - @InputFiles - public FileCollection getChangelogs() { - return changelogs; - } - - public void setChangelogs(FileCollection files) { - this.changelogs.setFrom(files); - } - - @InputFile - public RegularFileProperty getReleaseNotesIndexTemplate() { - return releaseNotesIndexTemplate; + @InputDirectory + public DirectoryProperty getChangelogBundleDirectory() { + return changelogBundleDirectory; } - public void setReleaseNotesIndexTemplate(RegularFile file) { - this.releaseNotesIndexTemplate.set(file); + public void setChangelogBundleDirectory(Directory dir) { + this.changelogBundleDirectory.set(dir); } @InputFile @@ -354,21 +191,12 @@ public void setBreakingChangesTemplate(RegularFile file) { } @InputFile - public RegularFileProperty getMigrationIndexTemplate() { - return migrationIndexTemplate; - } - - public void setMigrationIndexTemplate(RegularFile file) { - this.migrationIndexTemplate.set(file); - } - - @OutputFile - public RegularFileProperty getReleaseNotesIndexFile() { - return releaseNotesIndexFile; + public RegularFileProperty getDeprecationsTemplate() { + return deprecationsTemplate; } - public void setReleaseNotesIndexFile(RegularFile file) { - this.releaseNotesIndexFile.set(file); + public void setDeprecationsTemplate(RegularFile file) { + this.deprecationsTemplate.set(file); } @OutputFile @@ -390,20 +218,20 @@ public void setReleaseHighlightsFile(RegularFile file) { } @OutputFile - public RegularFileProperty getBreakingChangesMigrationFile() { - return breakingChangesMigrationFile; + public RegularFileProperty getBreakingChangesFile() { + return breakingChangesFile; } - public void setBreakingChangesMigrationFile(RegularFile file) { - this.breakingChangesMigrationFile.set(file); + public void setBreakingChangesFile(RegularFile file) { + this.breakingChangesFile.set(file); } @OutputFile - public RegularFileProperty getMigrationIndexFile() { - return migrationIndexFile; + public RegularFileProperty getDeprecationsFile() { + return deprecationsFile; } - public void setMigrationIndexFile(RegularFile file) { - this.migrationIndexFile.set(file); + public void setDeprecationsFile(RegularFile file) { + this.deprecationsFile.set(file); } } diff --git a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/GitWrapper.java b/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/GitWrapper.java index f50b3c0890220..6c726d4a16f80 100644 --- a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/GitWrapper.java +++ b/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/GitWrapper.java @@ -9,6 +9,7 @@ package org.elasticsearch.gradle.internal.release; +import org.gradle.api.GradleException; import org.gradle.process.ExecOperations; import java.io.ByteArrayOutputStream; @@ -87,4 +88,14 @@ public Stream listVersions(String pattern) { public Stream listFiles(String ref, String path) { return runCommand("git", "ls-tree", "--name-only", "-r", ref, path).lines(); } + + public String getUpstream() { + String upstream = listRemotes().entrySet() + .stream() + .filter(entry -> entry.getValue().contains("elastic/elasticsearch")) + .findFirst() + .map(Map.Entry::getKey) + .orElseThrow(() -> new GradleException("Couldn't find a git remote for [elastic/elasticsearch]")); + return upstream; + } } diff --git a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/MigrationIndexGenerator.java b/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/MigrationIndexGenerator.java deleted file mode 100644 index 668da0da6d0d0..0000000000000 --- a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/MigrationIndexGenerator.java +++ /dev/null @@ -1,51 +0,0 @@ -/* - * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one - * or more contributor license agreements. Licensed under the "Elastic License - * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side - * Public License v 1"; you may not use this file except in compliance with, at - * your election, the "Elastic License 2.0", the "GNU Affero General Public - * License v3.0 only", or the "Server Side Public License, v 1". - */ - -package org.elasticsearch.gradle.internal.release; - -import com.google.common.annotations.VisibleForTesting; - -import java.io.File; -import java.io.FileWriter; -import java.io.IOException; -import java.nio.file.Files; -import java.util.HashMap; -import java.util.List; -import java.util.Map; -import java.util.Set; -import java.util.TreeSet; -import java.util.stream.Collectors; - -import static java.util.Comparator.reverseOrder; - -/** - * This class ensures that the migrate/index page has the appropriate anchors and include directives - * for the current repository version. - */ -public class MigrationIndexGenerator { - - static void update(Set versions, File indexTemplate, File indexFile) throws IOException { - try (FileWriter indexFileWriter = new FileWriter(indexFile)) { - indexFileWriter.write(generateFile(versions, Files.readString(indexTemplate.toPath()))); - } - } - - @VisibleForTesting - static String generateFile(Set versionsSet, String template) throws IOException { - final Set versions = new TreeSet<>(reverseOrder()); - versions.addAll(versionsSet); - final List includeVersions = versions.stream().map(MinorVersion::underscore).collect(Collectors.toList()); - - final Map bindings = new HashMap<>(); - bindings.put("versions", versions); - bindings.put("includeVersions", includeVersions); - - return TemplateUtils.render(template, bindings); - } -} diff --git a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/ReleaseHighlightsGenerator.java b/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/ReleaseHighlightsGenerator.java deleted file mode 100644 index 25e4bec79c353..0000000000000 --- a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/ReleaseHighlightsGenerator.java +++ /dev/null @@ -1,68 +0,0 @@ -/* - * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one - * or more contributor license agreements. Licensed under the "Elastic License - * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side - * Public License v 1"; you may not use this file except in compliance with, at - * your election, the "Elastic License 2.0", the "GNU Affero General Public - * License v3.0 only", or the "Server Side Public License, v 1". - */ - -package org.elasticsearch.gradle.internal.release; - -import com.google.common.annotations.VisibleForTesting; - -import org.elasticsearch.gradle.VersionProperties; - -import java.io.File; -import java.io.FileWriter; -import java.io.IOException; -import java.nio.file.Files; -import java.util.ArrayList; -import java.util.Comparator; -import java.util.HashMap; -import java.util.List; -import java.util.Map; -import java.util.Objects; -import java.util.stream.Collectors; - -/** - * Generates the release highlights notes, for changelog files that contain the highlight field. - */ -public class ReleaseHighlightsGenerator { - static void update(File templateFile, File outputFile, List entries) throws IOException { - try (FileWriter output = new FileWriter(outputFile)) { - output.write( - generateFile(QualifiedVersion.of(VersionProperties.getElasticsearch()), Files.readString(templateFile.toPath()), entries) - ); - } - } - - @VisibleForTesting - static String generateFile(QualifiedVersion version, String template, List entries) throws IOException { - final List priorVersions = new ArrayList<>(); - - if (version.minor() > 0) { - final int major = version.major(); - for (int minor = version.minor() - 1; minor >= 0; minor--) { - String majorMinor = major + "." + minor; - priorVersions.add("{ref-bare}/" + majorMinor + "/release-highlights.html[" + majorMinor + "]"); - } - } - - final Map> groupedHighlights = entries.stream() - .map(ChangelogEntry::getHighlight) - .filter(Objects::nonNull) - .sorted(Comparator.comparingInt(ChangelogEntry.Highlight::getPr)) - .collect(Collectors.groupingBy(ChangelogEntry.Highlight::isNotable, Collectors.toList())); - - final List notableHighlights = groupedHighlights.getOrDefault(true, List.of()); - final List nonNotableHighlights = groupedHighlights.getOrDefault(false, List.of()); - - final Map bindings = new HashMap<>(); - bindings.put("priorVersions", priorVersions); - bindings.put("notableHighlights", notableHighlights); - bindings.put("nonNotableHighlights", nonNotableHighlights); - - return TemplateUtils.render(template, bindings); - } -} diff --git a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/ReleaseNotesGenerator.java b/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/ReleaseNotesGenerator.java index df0e35c487f54..6e8b9d9fa8023 100644 --- a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/ReleaseNotesGenerator.java +++ b/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/ReleaseNotesGenerator.java @@ -15,13 +15,16 @@ import java.io.FileWriter; import java.io.IOException; import java.nio.file.Files; +import java.util.ArrayList; +import java.util.Collection; import java.util.HashMap; import java.util.List; import java.util.Map; -import java.util.Set; +import java.util.Objects; import java.util.TreeMap; import static java.util.Comparator.comparing; +import static java.util.Comparator.comparingInt; import static java.util.stream.Collectors.groupingBy; import static java.util.stream.Collectors.toList; @@ -30,6 +33,17 @@ * type of change, then by team area. */ public class ReleaseNotesGenerator { + + private record ChangelogsBundleWrapper( + QualifiedVersion version, + ChangelogBundle bundle, + Map>> changelogsByTypeByArea, + QualifiedVersion unqualifiedVersion, + String versionWithoutSeparator, + List notableHighlights, + List nonNotableHighlights + ) {} + /** * These mappings translate change types into the headings as they should appear in the release notes. */ @@ -39,40 +53,95 @@ public class ReleaseNotesGenerator { TYPE_LABELS.put("breaking", "Breaking changes"); TYPE_LABELS.put("breaking-java", "Breaking Java changes"); TYPE_LABELS.put("bug", "Bug fixes"); + TYPE_LABELS.put("fixes", "Fixes"); TYPE_LABELS.put("deprecation", "Deprecations"); TYPE_LABELS.put("enhancement", "Enhancements"); TYPE_LABELS.put("feature", "New features"); + TYPE_LABELS.put("features-enhancements", "Features and enhancements"); TYPE_LABELS.put("new-aggregation", "New aggregation"); TYPE_LABELS.put("regression", "Regressions"); TYPE_LABELS.put("upgrade", "Upgrades"); } - static void update(File templateFile, File outputFile, QualifiedVersion version, Set changelogs) throws IOException { + /** + * These are the types of changes that are considered "Features and Enhancements" in the release notes. + */ + private static final List FEATURE_ENHANCEMENT_TYPES = List.of("feature", "new-aggregation", "enhancement", "upgrade"); + + static void update(File templateFile, File outputFile, List bundles) throws IOException { final String templateString = Files.readString(templateFile.toPath()); try (FileWriter output = new FileWriter(outputFile)) { - output.write(generateFile(templateString, version, changelogs)); + output.write(generateFile(templateString, bundles)); } } @VisibleForTesting - static String generateFile(String template, QualifiedVersion version, Set changelogs) throws IOException { - final var changelogsByTypeByArea = buildChangelogBreakdown(changelogs); + static String generateFile(String template, List bundles) throws IOException { + var bundlesWrapped = new ArrayList(); + + for (var bundle : bundles) { + var changelogs = bundle.changelogs(); + final var changelogsByTypeByArea = buildChangelogBreakdown(changelogs); + + final Map> groupedHighlights = changelogs.stream() + .map(ChangelogEntry::getHighlight) + .filter(Objects::nonNull) + .sorted(comparingInt(ChangelogEntry.Highlight::getPr)) + .collect(groupingBy(ChangelogEntry.Highlight::isNotable, toList())); + + final var notableHighlights = groupedHighlights.getOrDefault(true, List.of()); + final var nonNotableHighlights = groupedHighlights.getOrDefault(false, List.of()); + + final var version = QualifiedVersion.of(bundle.version()); + final var versionWithoutSeparator = version.withoutQualifier().toString().replaceAll("\\.", ""); + + final var wrapped = new ChangelogsBundleWrapper( + version, + bundle, + changelogsByTypeByArea, + version.withoutQualifier(), + versionWithoutSeparator, + notableHighlights, + nonNotableHighlights + ); + + bundlesWrapped.add(wrapped); + } final Map bindings = new HashMap<>(); - bindings.put("version", version); - bindings.put("changelogsByTypeByArea", changelogsByTypeByArea); bindings.put("TYPE_LABELS", TYPE_LABELS); + bindings.put("changelogBundles", bundlesWrapped); return TemplateUtils.render(template, bindings); } - private static Map>> buildChangelogBreakdown(Set changelogs) { + /** + * The new markdown release notes are grouping several of the old change types together. + * This method maps the change type that developers use in the changelogs to the new type that the release notes cares about. + */ + private static String getTypeFromEntry(ChangelogEntry entry) { + if (entry.getBreaking() != null) { + return "breaking"; + } + + if (FEATURE_ENHANCEMENT_TYPES.contains(entry.getType())) { + return "features-enhancements"; + } + + if (entry.getType().equals("bug")) { + return "fixes"; + } + + return entry.getType(); + } + + private static Map>> buildChangelogBreakdown(Collection changelogs) { Map>> changelogsByTypeByArea = changelogs.stream() .collect( groupingBy( // Entries with breaking info are always put in the breaking section - entry -> entry.getBreaking() == null ? entry.getType() : "breaking", + entry -> getTypeFromEntry(entry), TreeMap::new, // Group changelogs for each type by their team area groupingBy( diff --git a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/ReleaseNotesIndexGenerator.java b/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/ReleaseNotesIndexGenerator.java deleted file mode 100644 index b8c195f47d824..0000000000000 --- a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/ReleaseNotesIndexGenerator.java +++ /dev/null @@ -1,54 +0,0 @@ -/* - * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one - * or more contributor license agreements. Licensed under the "Elastic License - * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side - * Public License v 1"; you may not use this file except in compliance with, at - * your election, the "Elastic License 2.0", the "GNU Affero General Public - * License v3.0 only", or the "Server Side Public License, v 1". - */ - -package org.elasticsearch.gradle.internal.release; - -import com.google.common.annotations.VisibleForTesting; - -import java.io.File; -import java.io.FileWriter; -import java.io.IOException; -import java.nio.file.Files; -import java.util.HashMap; -import java.util.List; -import java.util.Map; -import java.util.Set; -import java.util.TreeSet; -import java.util.stream.Collectors; - -import static java.util.Comparator.reverseOrder; - -/** - * This class ensures that the release notes index page has the appropriate anchors and include directives - * for the current repository version. - */ -public class ReleaseNotesIndexGenerator { - - static void update(Set versions, File indexTemplate, File indexFile) throws IOException { - try (FileWriter indexFileWriter = new FileWriter(indexFile)) { - indexFileWriter.write(generateFile(versions, Files.readString(indexTemplate.toPath()))); - } - } - - @VisibleForTesting - static String generateFile(Set versionsSet, String template) throws IOException { - final Set versions = new TreeSet<>(reverseOrder()); - - // For the purpose of generating the index, snapshot versions are the same as released versions. Prerelease versions are not. - versionsSet.stream().map(v -> v.isSnapshot() ? v.withoutQualifier() : v).forEach(versions::add); - - final List includeVersions = versions.stream().map(QualifiedVersion::toString).collect(Collectors.toList()); - - final Map bindings = new HashMap<>(); - bindings.put("versions", versions); - bindings.put("includeVersions", includeVersions); - - return TemplateUtils.render(template, bindings); - } -} diff --git a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/ReleaseToolsPlugin.java b/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/ReleaseToolsPlugin.java index 22af46a4e5ccd..fce8b0c545dbb 100644 --- a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/ReleaseToolsPlugin.java +++ b/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/ReleaseToolsPlugin.java @@ -23,7 +23,6 @@ import org.gradle.api.tasks.util.PatternSet; import java.io.File; -import java.util.function.Function; import javax.inject.Inject; @@ -55,9 +54,9 @@ public void apply(Project project) { project.getTasks().register("tagVersions", TagVersionsTask.class); project.getTasks().register("setCompatibleVersions", SetCompatibleVersionsTask.class, t -> t.setThisVersion(version)); - final FileTree yamlFiles = projectDirectory.dir("docs/changelog") - .getAsFileTree() - .matching(new PatternSet().include("**/*.yml", "**/*.yaml")); + final Directory changeLogDirectory = projectDirectory.dir("docs/changelog"); + final Directory changeLogBundlesDirectory = projectDirectory.dir("docs/release-notes/changelog-bundles"); + final FileTree yamlFiles = changeLogDirectory.getAsFileTree().matching(new PatternSet().include("**/*.yml", "**/*.yaml")); final Provider validateChangelogsTask = project.getTasks() .register("validateChangelogs", ValidateYamlAgainstSchemaTask.class, task -> { @@ -68,49 +67,41 @@ public void apply(Project project) { task.setReport(new File(project.getBuildDir(), "reports/validateYaml.txt")); }); - final Function> configureGenerateTask = shouldConfigureYamlFiles -> task -> { + final Action configureBundleTask = task -> { task.setGroup("Documentation"); - if (shouldConfigureYamlFiles) { - task.setChangelogs(yamlFiles); - task.setDescription("Generates release notes from changelog files held in this checkout"); - } else { - task.setDescription("Generates stub release notes e.g. after feature freeze"); - } - - task.setReleaseNotesIndexTemplate(projectDirectory.file(RESOURCES + "templates/release-notes-index.asciidoc")); - task.setReleaseNotesIndexFile(projectDirectory.file("docs/reference/release-notes.asciidoc")); - - task.setReleaseNotesTemplate(projectDirectory.file(RESOURCES + "templates/release-notes.asciidoc")); - task.setReleaseNotesFile( - projectDirectory.file( - String.format( - "docs/reference/release-notes/%d.%d.%d.asciidoc", - version.getMajor(), - version.getMinor(), - version.getRevision() - ) - ) - ); + task.setDescription("Generates release notes from changelog files held in this checkout"); + task.setChangelogs(yamlFiles); + task.setChangelogDirectory(changeLogDirectory); + task.setChangelogBundlesDirectory(changeLogBundlesDirectory); + task.setBundleFile(projectDirectory.file("docs/release-notes/changelogs-" + version.toString() + ".yml")); + task.getOutputs().upToDateWhen(o -> false); + }; + + final Action configureGenerateTask = task -> { + task.setGroup("Documentation"); + task.setDescription("Generates release notes for all versions/branches using changelog bundles in this checkout"); + + task.setReleaseNotesTemplate(projectDirectory.file(RESOURCES + "templates/index.md")); + task.setReleaseNotesFile(projectDirectory.file("docs/release-notes/index.md")); task.setReleaseHighlightsTemplate(projectDirectory.file(RESOURCES + "templates/release-highlights.asciidoc")); task.setReleaseHighlightsFile(projectDirectory.file("docs/reference/release-notes/highlights.asciidoc")); - task.setBreakingChangesTemplate(projectDirectory.file(RESOURCES + "templates/breaking-changes.asciidoc")); - task.setBreakingChangesMigrationFile( - projectDirectory.file( - String.format("docs/reference/migration/migrate_%d_%d.asciidoc", version.getMajor(), version.getMinor()) - ) - ); - task.setMigrationIndexTemplate(projectDirectory.file(RESOURCES + "templates/migration-index.asciidoc")); - task.setMigrationIndexFile(projectDirectory.file("docs/reference/migration/index.asciidoc")); + task.setBreakingChangesTemplate(projectDirectory.file(RESOURCES + "templates/breaking-changes.md")); + task.setBreakingChangesFile(projectDirectory.file("docs/release-notes/breaking-changes.md")); + + task.setDeprecationsTemplate(projectDirectory.file(RESOURCES + "templates/deprecations.md")); + task.setDeprecationsFile(projectDirectory.file("docs/release-notes/deprecations.md")); + + task.setChangelogBundleDirectory(changeLogBundlesDirectory); + + task.getOutputs().upToDateWhen(o -> false); task.dependsOn(validateChangelogsTask); }; - project.getTasks().register("generateReleaseNotes", GenerateReleaseNotesTask.class).configure(configureGenerateTask.apply(true)); - project.getTasks() - .register("generateStubReleaseNotes", GenerateReleaseNotesTask.class) - .configure(configureGenerateTask.apply(false)); + project.getTasks().register("bundleChangelogs", BundleChangelogsTask.class).configure(configureBundleTask); + project.getTasks().register("generateReleaseNotes", GenerateReleaseNotesTask.class).configure(configureGenerateTask); project.getTasks().register("pruneChangelogs", PruneChangelogsTask.class).configure(task -> { task.setGroup("Documentation"); diff --git a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/test/rest/RestTestBasePlugin.java b/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/test/rest/RestTestBasePlugin.java index 1259d13773ce7..2f9fe2ed06e98 100644 --- a/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/test/rest/RestTestBasePlugin.java +++ b/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/test/rest/RestTestBasePlugin.java @@ -165,7 +165,7 @@ public void apply(Project project) { nonInputSystemProperties.systemProperty(TESTS_FEATURES_METADATA_PATH, () -> featureMetadataConfig.getAsPath()); // Enable parallel execution for these tests since each test gets its own cluster - task.setMaxParallelForks(task.getProject().getGradle().getStartParameter().getMaxWorkerCount() / 2); + task.setMaxParallelForks(Math.max(1, task.getProject().getGradle().getStartParameter().getMaxWorkerCount() / 2)); nonInputSystemProperties.systemProperty(TESTS_MAX_PARALLEL_FORKS_SYSPROP, () -> String.valueOf(task.getMaxParallelForks())); // Disable test failure reporting since this stuff is now captured in build scans diff --git a/build-tools-internal/src/main/resources/minimumGradleVersion b/build-tools-internal/src/main/resources/minimumGradleVersion index b9d71048250a3..3e2c3fbefcb12 100644 --- a/build-tools-internal/src/main/resources/minimumGradleVersion +++ b/build-tools-internal/src/main/resources/minimumGradleVersion @@ -1 +1 @@ -8.14 \ No newline at end of file +8.14.1 \ No newline at end of file diff --git a/build-tools-internal/src/main/resources/templates/breaking-changes.asciidoc b/build-tools-internal/src/main/resources/templates/breaking-changes.asciidoc deleted file mode 100644 index 855a443a8081f..0000000000000 --- a/build-tools-internal/src/main/resources/templates/breaking-changes.asciidoc +++ /dev/null @@ -1,98 +0,0 @@ -[[migrating-${majorDotMinor}]] -== Migrating to ${majorDotMinor} -++++ -${majorDotMinor} -++++ - -This section discusses the changes that you need to be aware of when migrating -your application to {es} ${majorDotMinor}. - -See also <> and <>. -<% if (isElasticsearchSnapshot) { %> -coming::[${majorDotMinorDotRevision}] -<% } %> - -[discrete] -[[breaking-changes-${majorDotMinor}]] -=== Breaking changes -<% if (breakingByNotabilityByArea.isEmpty()) { %> -There are no breaking changes in {es} ${majorDotMinor}. -<% } else { %> -The following changes in {es} ${majorDotMinor} might affect your applications -and prevent them from operating normally. -Before upgrading to ${majorDotMinor}, review these changes and take the described steps -to mitigate the impact. -<% - if (breakingByNotabilityByArea.getOrDefault(true, []).isEmpty()) { %> - -There are no notable breaking changes in {es} ${majorDotMinor}. -But there are some less critical breaking changes. -<% } - [true, false].each { isNotable -> - def breakingByArea = breakingByNotabilityByArea.getOrDefault(isNotable, []) - if (breakingByArea.isEmpty() == false) { - breakingByArea.eachWithIndex { area, breakingChanges, i -> - print "\n[discrete]\n" - print "[[breaking_${majorMinor}_${ area.toLowerCase().replaceAll("[^a-z0-9]+", "_") }_changes]]\n" - print "==== ${area} changes\n" - - for (breaking in breakingChanges) { %> -[[${ breaking.anchor }]] -.${breaking.title} -[%collapsible] -==== -*Details* + -${breaking.details.trim()} - -*Impact* + -${breaking.impact.trim()} -==== -<% - } - } - - } - } -} - -if (deprecationsByNotabilityByArea.isEmpty() == false) { %> - -[discrete] -[[deprecated-${majorDotMinor}]] -=== Deprecations - -The following functionality has been deprecated in {es} ${majorDotMinor} -and will be removed in a future version. -While this won't have an immediate impact on your applications, -we strongly encourage you to take the described steps to update your code -after upgrading to ${majorDotMinor}. - -To find out if you are using any deprecated functionality, -enable <>. -<% - [true, false].each { isNotable -> - def deprecationsByArea = deprecationsByNotabilityByArea.getOrDefault(isNotable, []) - if (deprecationsByArea.isEmpty() == false) { - deprecationsByArea.eachWithIndex { area, deprecations, i -> - print "\n[discrete]\n" - print "[[deprecations_${majorMinor}_${ area.toLowerCase().replaceAll("[^a-z0-9]+", "_") }]]\n" - print "==== ${area} deprecations\n" - - for (deprecation in deprecations) { %> -[[${ deprecation.anchor }]] -.${deprecation.title} -[%collapsible] -==== -*Details* + -${deprecation.details.trim()} - -*Impact* + -${deprecation.impact.trim()} -==== -<% - } - } - - } - } -} %> diff --git a/build-tools-internal/src/main/resources/templates/breaking-changes.md b/build-tools-internal/src/main/resources/templates/breaking-changes.md new file mode 100644 index 0000000000000..a4cbd8ce7c164 --- /dev/null +++ b/build-tools-internal/src/main/resources/templates/breaking-changes.md @@ -0,0 +1,50 @@ +--- +navigation_title: "Breaking changes" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/breaking-changes.html +--- + +# Elasticsearch breaking changes [elasticsearch-breaking-changes] + +Breaking changes can impact your Elastic applications, potentially disrupting normal operations. Before you upgrade, carefully review the Elasticsearch breaking changes and take the necessary steps to mitigate any issues. + +If you are migrating from a version prior to version 9.0, you must first upgrade to the last 8.x version available. To learn how to upgrade, check out [Upgrade](docs-content://deploy-manage/upgrade.md). + +% ## Next version [elasticsearch-nextversion-breaking-changes] +<% +for(bundle in changelogBundles) { + def version = bundle.version + def versionForIds = bundle.version.toString().equals('9.0.0') ? bundle.versionWithoutSeparator : bundle.version + def changelogsByTypeByArea = bundle.changelogsByTypeByArea + def unqualifiedVersion = bundle.unqualifiedVersion + def coming = !bundle.bundle.released + + if (coming) { + print "\n" + print "```{applies_to}\n" + print "stack: coming ${version}\n" + print "```" + } +%> +## ${unqualifiedVersion} [elasticsearch-${versionForIds}-breaking-changes] +<% + if (!changelogsByTypeByArea['breaking']) { + print "\nNo breaking changes in this version.\n" + } else { + for (team in (changelogsByTypeByArea['breaking'] ?: [:]).keySet()) { + print "\n${team}:\n"; + + for (change in changelogsByTypeByArea['breaking'][team]) { + print "* ${change.summary} [#${change.pr}](https://github.com/elastic/elasticsearch/pull/${change.pr})" + if (change.issues != null && change.issues.empty == false) { + print change.issues.size() == 1 ? " (issue: " : " (issues: " + print change.issues.collect { "[#${it}](https://github.com/elastic/elasticsearch/issues/${it})" }.join(", ") + print ")" + } + print "\n" + } + } + + print "\n\n" + } +} diff --git a/build-tools-internal/src/main/resources/templates/deprecations.md b/build-tools-internal/src/main/resources/templates/deprecations.md new file mode 100644 index 0000000000000..38c58682a999b --- /dev/null +++ b/build-tools-internal/src/main/resources/templates/deprecations.md @@ -0,0 +1,53 @@ +--- +navigation_title: "Deprecations" +--- + +# {{es}} deprecations [elasticsearch-deprecations] + +Over time, certain Elastic functionality becomes outdated and is replaced or removed. To help with the transition, Elastic deprecates functionality for a period before removal, giving you time to update your applications. + +Review the deprecated functionality for Elasticsearch. While deprecations have no immediate impact, we strongly encourage you update your implementation after you upgrade. To learn how to upgrade, check out [Upgrade](docs-content://deploy-manage/upgrade.md). + +To give you insight into what deprecated features you’re using, {{es}}: + +* Returns a `Warn` HTTP header whenever you submit a request that uses deprecated functionality. +* [Logs deprecation warnings](docs-content://deploy-manage/monitor/logging-configuration/update-elasticsearch-logging-levels.md#deprecation-logging) when deprecated functionality is used. +* [Provides a deprecation info API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-migration-deprecations) that scans a cluster’s configuration and mappings for deprecated functionality. + +% ## Next version [elasticsearch-nextversion-deprecations] +<% +for(bundle in changelogBundles) { + def version = bundle.version + def versionForIds = bundle.version.toString().equals('9.0.0') ? bundle.versionWithoutSeparator : bundle.version + def changelogsByTypeByArea = bundle.changelogsByTypeByArea + def unqualifiedVersion = bundle.unqualifiedVersion + def coming = !bundle.bundle.released + + if (coming) { + print "\n" + print "```{applies_to}\n" + print "stack: coming ${version}\n" + print "```" + } +%> +## ${unqualifiedVersion} [elasticsearch-${versionForIds}-deprecations] +<% + if (!changelogsByTypeByArea['deprecation']) { + print "\nNo deprecations in this version.\n" + } else { + for (team in (changelogsByTypeByArea['deprecation'] ?: [:]).keySet()) { + print "\n${team}:\n"; + + for (change in changelogsByTypeByArea['deprecation'][team]) { + print "* ${change.summary} [#${change.pr}](https://github.com/elastic/elasticsearch/pull/${change.pr})" + if (change.issues != null && change.issues.empty == false) { + print change.issues.size() == 1 ? " (issue: " : " (issues: " + print change.issues.collect { "[#${it}](https://github.com/elastic/elasticsearch/issues/${it})" }.join(", ") + print ")" + } + print "\n" + } + } + print "\n\n" + } +} diff --git a/build-tools-internal/src/main/resources/templates/index.md b/build-tools-internal/src/main/resources/templates/index.md new file mode 100644 index 0000000000000..cb417eb49dc64 --- /dev/null +++ b/build-tools-internal/src/main/resources/templates/index.md @@ -0,0 +1,76 @@ +--- +navigation_title: "Elasticsearch" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/es-release-notes.html +--- + +# Elasticsearch release notes [elasticsearch-release-notes] + +Review the changes, fixes, and more in each version of Elasticsearch. + +To check for security updates, go to [Security announcements for the Elastic stack](https://discuss.elastic.co/c/announcements/security-announcements/31). + +% Release notes include only features, enhancements, and fixes. Add breaking changes, deprecations, and known issues to the applicable release notes sections. + +% ## version.next [elasticsearch-next-release-notes] + +% ### Features and enhancements [elasticsearch-next-features-enhancements] +% * + +% ### Fixes [elasticsearch-next-fixes] +% * +<% +for(bundle in changelogBundles) { + def version = bundle.version + def versionForIds = bundle.version.toString().equals('9.0.0') ? bundle.versionWithoutSeparator : bundle.version + def changelogsByTypeByArea = bundle.changelogsByTypeByArea + def notableHighlights = bundle.notableHighlights + def nonNotableHighlights = bundle.nonNotableHighlights + def unqualifiedVersion = bundle.unqualifiedVersion + def coming = !bundle.bundle.released + + if (coming) { + print "\n" + print "```{applies_to}\n" + print "stack: coming ${version}\n" + print "```" + } +%> +## ${unqualifiedVersion} [elasticsearch-${versionForIds}-release-notes] +<% +if (!notableHighlights.isEmpty() || !nonNotableHighlights.isEmpty()) { + print "\n### Highlights [elasticsearch-${versionForIds}-highlights]\n" +} + +for (highlights in [notableHighlights, nonNotableHighlights]) { + if (!highlights.isEmpty()) { + for (highlight in highlights) { %> +::::{dropdown} ${highlight.title} +${highlight.body.trim()} +:::: +<% } + } +} + +for (changeType in ['features-enhancements', 'fixes', 'regression']) { + if (changelogsByTypeByArea[changeType] == null || changelogsByTypeByArea[changeType].empty) { + continue; + } +%> +### ${ TYPE_LABELS.getOrDefault(changeType, 'No mapping for TYPE_LABELS[' + changeType + ']') } [elasticsearch-${versionForIds}-${changeType}] +<% for (team in changelogsByTypeByArea[changeType].keySet()) { + print "\n${team}:\n"; + + for (change in changelogsByTypeByArea[changeType][team]) { + print "* ${change.summary} [#${change.pr}](https://github.com/elastic/elasticsearch/pull/${change.pr})" + if (change.issues != null && change.issues.empty == false) { + print change.issues.size() == 1 ? " (issue: " : " (issues: " + print change.issues.collect { "[#${it}](https://github.com/elastic/elasticsearch/issues/${it})" }.join(", ") + print ")" + } + print "\n" + } +} +} +print "\n" +} diff --git a/build-tools-internal/src/main/resources/templates/release-notes-index.asciidoc b/build-tools-internal/src/main/resources/templates/release-notes-index.asciidoc deleted file mode 100644 index ba30aea3bf14e..0000000000000 --- a/build-tools-internal/src/main/resources/templates/release-notes-index.asciidoc +++ /dev/null @@ -1,12 +0,0 @@ -[[es-release-notes]] -= Release notes - -[partintro] --- - -This section summarizes the changes in each release. - -<% versions.each { print "* <>\n" } %> --- - -<% includeVersions.each { print "include::release-notes/${ it }.asciidoc[]\n" } %> diff --git a/build-tools-internal/src/main/resources/templates/release-notes.asciidoc b/build-tools-internal/src/main/resources/templates/release-notes.asciidoc deleted file mode 100644 index 096608435333a..0000000000000 --- a/build-tools-internal/src/main/resources/templates/release-notes.asciidoc +++ /dev/null @@ -1,45 +0,0 @@ -<% -def unqualifiedVersion = version.withoutQualifier() -%>[[release-notes-$unqualifiedVersion]] -== {es} version ${unqualifiedVersion} -<% if (version.isSnapshot()) { %> -coming[$unqualifiedVersion] -<% } %> -Also see <>. -<% if (changelogsByTypeByArea["security"] != null) { %> -[discrete] -[[security-updates-${unqualifiedVersion}]] -=== Security updates - -<% for (change in changelogsByTypeByArea.remove("security").remove("_all_")) { - print "* ${change.summary}\n" -} -} -if (changelogsByTypeByArea["known-issue"] != null) { %> -[discrete] -[[known-issues-${unqualifiedVersion}]] -=== Known issues - -<% for (change in changelogsByTypeByArea.remove("known-issue").remove("_all_")) { - print "* ${change.summary}\n" -} -} -for (changeType in changelogsByTypeByArea.keySet()) { %> -[[${ changeType }-${ unqualifiedVersion }]] -[float] -=== ${ TYPE_LABELS.getOrDefault(changeType, 'No mapping for TYPE_LABELS[' + changeType + ']') } -<% for (team in changelogsByTypeByArea[changeType].keySet()) { - print "\n${team}::\n"; - - for (change in changelogsByTypeByArea[changeType][team]) { - print "* ${change.summary} {es-pull}${change.pr}[#${change.pr}]" - if (change.issues != null && change.issues.empty == false) { - print change.issues.size() == 1 ? " (issue: " : " (issues: " - print change.issues.collect { "{es-issue}${it}[#${it}]" }.join(", ") - print ")" - } - print "\n" - } -} -} -print "\n\n" diff --git a/build-tools-internal/src/test/java/org/elasticsearch/gradle/internal/release/BreakingChangesGeneratorTest.java b/build-tools-internal/src/test/java/org/elasticsearch/gradle/internal/release/BreakingChangesGeneratorTest.java deleted file mode 100644 index 5d51f3514cbc3..0000000000000 --- a/build-tools-internal/src/test/java/org/elasticsearch/gradle/internal/release/BreakingChangesGeneratorTest.java +++ /dev/null @@ -1,130 +0,0 @@ -/* - * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one - * or more contributor license agreements. Licensed under the "Elastic License - * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side - * Public License v 1"; you may not use this file except in compliance with, at - * your election, the "Elastic License 2.0", the "GNU Affero General Public - * License v3.0 only", or the "Server Side Public License, v 1". - */ - -package org.elasticsearch.gradle.internal.release; - -import org.junit.Test; - -import java.nio.charset.StandardCharsets; -import java.nio.file.Files; -import java.nio.file.Paths; -import java.util.List; -import java.util.Objects; - -import static org.hamcrest.MatcherAssert.assertThat; -import static org.hamcrest.Matchers.equalTo; - -public class BreakingChangesGeneratorTest { - - /** - * Check that the breaking changes can be correctly generated. - */ - @Test - public void generateIndexFile_rendersCorrectMarkup() throws Exception { - // given: - final String template = getResource("/templates/breaking-changes.asciidoc"); - final String expectedOutput = getResource( - "/org/elasticsearch/gradle/internal/release/BreakingChangesGeneratorTest.generateMigrationFile.asciidoc" - ); - - final List entries = getEntries(); - - // when: - final String actualOutput = BreakingChangesGenerator.generateMigrationFile( - QualifiedVersion.of("8.4.0-SNAPSHOT"), - template, - entries - ); - - // then: - assertThat(actualOutput, equalTo(expectedOutput)); - } - - private List getEntries() { - ChangelogEntry entry1 = new ChangelogEntry(); - ChangelogEntry.Breaking breaking1 = new ChangelogEntry.Breaking(); - entry1.setBreaking(breaking1); - - breaking1.setNotable(true); - breaking1.setTitle("Breaking change number 1"); - breaking1.setArea("API"); - breaking1.setDetails("Breaking change details 1"); - breaking1.setImpact("Breaking change impact description 1"); - - ChangelogEntry entry2 = new ChangelogEntry(); - ChangelogEntry.Breaking breaking2 = new ChangelogEntry.Breaking(); - entry2.setBreaking(breaking2); - - breaking2.setNotable(true); - breaking2.setTitle("Breaking change number 2"); - breaking2.setArea("Cluster and node setting"); - breaking2.setDetails("Breaking change details 2"); - breaking2.setImpact("Breaking change impact description 2"); - - ChangelogEntry entry3 = new ChangelogEntry(); - ChangelogEntry.Breaking breaking3 = new ChangelogEntry.Breaking(); - entry3.setBreaking(breaking3); - - breaking3.setNotable(false); - breaking3.setTitle("Breaking change number 3"); - breaking3.setArea("Transform"); - breaking3.setDetails("Breaking change details 3"); - breaking3.setImpact("Breaking change impact description 3"); - - ChangelogEntry entry4 = new ChangelogEntry(); - ChangelogEntry.Breaking breaking4 = new ChangelogEntry.Breaking(); - entry4.setBreaking(breaking4); - - breaking4.setNotable(true); - breaking4.setTitle("Breaking change number 4"); - breaking4.setArea("Cluster and node setting"); - breaking4.setDetails("Breaking change details 4"); - breaking4.setImpact("Breaking change impact description 4"); - breaking4.setEssSettingChange(true); - - ChangelogEntry entry5 = new ChangelogEntry(); - ChangelogEntry.Deprecation deprecation5 = new ChangelogEntry.Deprecation(); - entry5.setDeprecation(deprecation5); - - deprecation5.setNotable(true); - deprecation5.setTitle("Deprecation change number 5"); - deprecation5.setArea("Cluster and node setting"); - deprecation5.setDetails("Deprecation change details 5"); - deprecation5.setImpact("Deprecation change impact description 5"); - deprecation5.setEssSettingChange(false); - - ChangelogEntry entry6 = new ChangelogEntry(); - ChangelogEntry.Deprecation deprecation6 = new ChangelogEntry.Deprecation(); - entry6.setDeprecation(deprecation6); - - deprecation6.setNotable(true); - deprecation6.setTitle("Deprecation change number 6"); - deprecation6.setArea("Cluster and node setting"); - deprecation6.setDetails("Deprecation change details 6"); - deprecation6.setImpact("Deprecation change impact description 6"); - deprecation6.setEssSettingChange(false); - - ChangelogEntry entry7 = new ChangelogEntry(); - ChangelogEntry.Deprecation deprecation7 = new ChangelogEntry.Deprecation(); - entry7.setDeprecation(deprecation7); - - deprecation7.setNotable(false); - deprecation7.setTitle("Deprecation change number 7"); - deprecation7.setArea("Cluster and node setting"); - deprecation7.setDetails("Deprecation change details 7"); - deprecation7.setImpact("Deprecation change impact description 7"); - deprecation7.setEssSettingChange(false); - - return List.of(entry1, entry2, entry3, entry4, entry5, entry6, entry7); - } - - private String getResource(String name) throws Exception { - return Files.readString(Paths.get(Objects.requireNonNull(this.getClass().getResource(name)).toURI()), StandardCharsets.UTF_8); - } -} diff --git a/build-tools-internal/src/test/java/org/elasticsearch/gradle/internal/release/GenerateReleaseNotesTaskTest.java b/build-tools-internal/src/test/java/org/elasticsearch/gradle/internal/release/GenerateReleaseNotesTaskTest.java index 78bdb8017f476..98b09bbcaf4dc 100644 --- a/build-tools-internal/src/test/java/org/elasticsearch/gradle/internal/release/GenerateReleaseNotesTaskTest.java +++ b/build-tools-internal/src/test/java/org/elasticsearch/gradle/internal/release/GenerateReleaseNotesTaskTest.java @@ -9,38 +9,12 @@ package org.elasticsearch.gradle.internal.release; -import org.junit.Before; import org.junit.Test; -import java.io.File; -import java.util.Map; -import java.util.Set; -import java.util.stream.Stream; - import static org.hamcrest.MatcherAssert.assertThat; -import static org.hamcrest.Matchers.aMapWithSize; -import static org.hamcrest.Matchers.allOf; -import static org.hamcrest.Matchers.containsInAnyOrder; -import static org.hamcrest.Matchers.equalTo; -import static org.hamcrest.Matchers.hasEntry; -import static org.hamcrest.Matchers.hasItem; -import static org.hamcrest.Matchers.hasKey; import static org.hamcrest.Matchers.is; -import static org.mockito.Matchers.anyString; -import static org.mockito.Matchers.eq; -import static org.mockito.Mockito.mock; -import static org.mockito.Mockito.verify; -import static org.mockito.Mockito.verifyNoMoreInteractions; -import static org.mockito.Mockito.when; public class GenerateReleaseNotesTaskTest { - private GitWrapper gitWrapper; - - @Before - public void setup() { - this.gitWrapper = mock(GitWrapper.class); - } - /** * Check that the task does not update git tags if the current version is a snapshot of the first patch release. */ @@ -88,250 +62,4 @@ public void needsGitTags_withFirsAlphaRelease_returnsFalse() { public void needsGitTags_withLaterAlphaRelease_returnsFalse() { assertThat(GenerateReleaseNotesTask.needsGitTags("8.0.0-alpha2"), is(true)); } - - /** - * Check that partitioning changelog files when the current version is a snapshot returns a map with a single entry. - */ - @Test - public void partitionFiles_withSnapshot_returnsSingleMapping() { - // when: - Map> partitionedFiles = GenerateReleaseNotesTask.partitionFilesByVersion( - gitWrapper, - "8.0.0-SNAPSHOT", - Set.of(new File("docs/changelog/1234.yaml")) - ); - - // then: - assertThat(partitionedFiles, aMapWithSize(1)); - assertThat( - partitionedFiles, - hasEntry(equalTo(QualifiedVersion.of("8.0.0-SNAPSHOT")), hasItem(new File("docs/changelog/1234.yaml"))) - ); - verifyNoMoreInteractions(gitWrapper); - } - - /** - * Check that partitioning changelog files when the current version is the first release - * in a minor series returns a map with a single entry. - */ - @Test - public void partitionFiles_withFirstRevision_returnsSingleMapping() { - // when: - Map> partitionedFiles = GenerateReleaseNotesTask.partitionFilesByVersion( - gitWrapper, - "8.5.0", - Set.of(new File("docs/changelog/1234.yaml")) - ); - - // then: - assertThat(partitionedFiles, aMapWithSize(1)); - assertThat(partitionedFiles, hasEntry(equalTo(QualifiedVersion.of("8.5.0")), hasItem(new File("docs/changelog/1234.yaml")))); - verifyNoMoreInteractions(gitWrapper); - } - - /** - * Check that partitioning changelog files when the current version is the first alpha prerelease returns a map with a single entry. - */ - @Test - public void partitionFiles_withFirstAlpha_returnsSingleMapping() { - // when: - Map> partitionedFiles = GenerateReleaseNotesTask.partitionFilesByVersion( - gitWrapper, - "8.0.0-alpha1", - Set.of(new File("docs/changelog/1234.yaml")) - ); - - // then: - assertThat(partitionedFiles, aMapWithSize(1)); - assertThat(partitionedFiles, hasEntry(equalTo(QualifiedVersion.of("8.0.0-alpha1")), hasItem(new File("docs/changelog/1234.yaml")))); - verifyNoMoreInteractions(gitWrapper); - } - - /** - * Check that when deriving a lit of versions from git tags, the current unreleased version is included. - */ - @Test - public void getVersions_includesCurrentAndPreviousVersion() { - // given: - when(gitWrapper.listVersions(anyString())).thenReturn( - Stream.of("8.0.0-alpha1", "8.0.0-alpha2", "8.0.0-beta1", "8.0.0-beta2", "8.0.0-beta3", "8.0.0-rc1", "8.0.0", "8.0.1", "8.1.0") - .map(QualifiedVersion::of) - ); - - // when: - Set versions = GenerateReleaseNotesTask.getVersions(gitWrapper, "8.3.0-SNAPSHOT"); - - // then: - assertThat( - versions, - containsInAnyOrder( - Stream.of( - "8.0.0-alpha1", - "8.0.0-alpha2", - "8.0.0-beta1", - "8.0.0-beta2", - "8.0.0-beta3", - "8.0.0-rc1", - "8.0.0", - "8.0.1", - "8.1.0", - "8.2.0", - "8.3.0-SNAPSHOT" - ).map(QualifiedVersion::of).toArray(QualifiedVersion[]::new) - ) - ); - } - - /** - * Check that when deriving a list of major.minor versions from git tags, the current unreleased version is included, - * but any higher version numbers are not. - */ - @Test - public void getMinorVersions_includesCurrentButNotFutureVersions() { - // given: - when(gitWrapper.listVersions(anyString())).thenReturn( - Stream.of("8.0.0-alpha1", "8.0.0-alpha2", "8.0.0", "8.0.1", "8.1.0", "8.2.0", "8.2.1", "8.3.0", "8.3.1", "8.4.0") - .map(QualifiedVersion::of) - ); - - // when: - Set versions = GenerateReleaseNotesTask.getVersions(gitWrapper, "8.3.0-SNAPSHOT"); - Set minorVersions = GenerateReleaseNotesTask.getMinorVersions(versions); - - // then: - assertThat( - minorVersions, - containsInAnyOrder(new MinorVersion(8, 0), new MinorVersion(8, 1), new MinorVersion(8, 2), new MinorVersion(8, 3)) - ); - } - - /** - * Check that the task partitions the list of files correctly by version for a prerelease. - */ - @Test - public void partitionFiles_withPrerelease_correctlyGroupsByPrereleaseVersion() { - // given: - when(gitWrapper.listVersions(anyString())).thenReturn( - Stream.of("8.0.0-alpha1", "8.0.0-alpha2", "8.0.0-beta1", "8.0.0-beta2", "8.0.0-beta3", "8.0.0-rc1", "8.0.0") - .map(QualifiedVersion::of) - ); - when(gitWrapper.listFiles(eq("v8.0.0-alpha1"), anyString())).thenReturn( - Stream.of("docs/changelog/1_1234.yaml", "docs/changelog/1_5678.yaml") - ); - when(gitWrapper.listFiles(eq("v8.0.0-alpha2"), anyString())).thenReturn( - Stream.of("docs/changelog/2_1234.yaml", "docs/changelog/2_5678.yaml") - ); - - Set allFiles = Set.of( - new File("docs/changelog/1_1234.yaml"), - new File("docs/changelog/1_5678.yaml"), - new File("docs/changelog/2_1234.yaml"), - new File("docs/changelog/2_5678.yaml"), - new File("docs/changelog/3_1234.yaml"), - new File("docs/changelog/3_5678.yaml") - ); - - // when: - Map> partitionedFiles = GenerateReleaseNotesTask.partitionFilesByVersion( - gitWrapper, - "8.0.0-beta1", - allFiles - ); - - // then: - verify(gitWrapper).listVersions("v8.0*"); - verify(gitWrapper).listFiles("v8.0.0-alpha1", "docs/changelog"); - verify(gitWrapper).listFiles("v8.0.0-alpha2", "docs/changelog"); - - assertThat( - partitionedFiles, - allOf( - aMapWithSize(3), - hasKey(QualifiedVersion.of("8.0.0-alpha1")), - hasKey(QualifiedVersion.of("8.0.0-alpha2")), - hasKey(QualifiedVersion.of("8.0.0-beta1")) - ) - ); - - assertThat( - partitionedFiles, - allOf( - hasEntry( - equalTo(QualifiedVersion.of("8.0.0-alpha1")), - containsInAnyOrder(new File("docs/changelog/1_1234.yaml"), new File("docs/changelog/1_5678.yaml")) - ), - hasEntry( - equalTo(QualifiedVersion.of("8.0.0-alpha2")), - containsInAnyOrder(new File("docs/changelog/2_1234.yaml"), new File("docs/changelog/2_5678.yaml")) - ), - hasEntry( - equalTo(QualifiedVersion.of("8.0.0-beta1")), - containsInAnyOrder(new File("docs/changelog/3_1234.yaml"), new File("docs/changelog/3_5678.yaml")) - ) - ) - ); - } - - /** - * Check that the task partitions the list of files correctly by version for a patch release. - */ - @Test - public void partitionFiles_withPatchRelease_correctlyGroupsByPatchVersion() { - // given: - when(gitWrapper.listVersions(anyString())).thenReturn( - Stream.of("8.0.0-alpha1", "8.0.0-alpha2", "8.0.0-beta1", "8.0.0-rc1", "8.0.0", "8.0.1", "8.0.2", "8.1.0") - .map(QualifiedVersion::of) - ); - when(gitWrapper.listFiles(eq("v8.0.0"), anyString())).thenReturn( - Stream.of("docs/changelog/1_1234.yaml", "docs/changelog/1_5678.yaml") - ); - when(gitWrapper.listFiles(eq("v8.0.1"), anyString())).thenReturn( - Stream.of("docs/changelog/2_1234.yaml", "docs/changelog/2_5678.yaml") - ); - - Set allFiles = Set.of( - new File("docs/changelog/1_1234.yaml"), - new File("docs/changelog/1_5678.yaml"), - new File("docs/changelog/2_1234.yaml"), - new File("docs/changelog/2_5678.yaml"), - new File("docs/changelog/3_1234.yaml"), - new File("docs/changelog/3_5678.yaml") - ); - - // when: - Map> partitionedFiles = GenerateReleaseNotesTask.partitionFilesByVersion(gitWrapper, "8.0.2", allFiles); - - // then: - verify(gitWrapper).listVersions("v8.0*"); - verify(gitWrapper).listFiles("v8.0.0", "docs/changelog"); - verify(gitWrapper).listFiles("v8.0.1", "docs/changelog"); - - assertThat( - partitionedFiles, - allOf( - aMapWithSize(3), - hasKey(QualifiedVersion.of("8.0.0")), - hasKey(QualifiedVersion.of("8.0.1")), - hasKey(QualifiedVersion.of("8.0.2")) - ) - ); - - assertThat( - partitionedFiles, - allOf( - hasEntry( - equalTo(QualifiedVersion.of("8.0.0")), - containsInAnyOrder(new File("docs/changelog/1_1234.yaml"), new File("docs/changelog/1_5678.yaml")) - ), - hasEntry( - equalTo(QualifiedVersion.of("8.0.1")), - containsInAnyOrder(new File("docs/changelog/2_1234.yaml"), new File("docs/changelog/2_5678.yaml")) - ), - hasEntry( - equalTo(QualifiedVersion.of("8.0.2")), - containsInAnyOrder(new File("docs/changelog/3_1234.yaml"), new File("docs/changelog/3_5678.yaml")) - ) - ) - ); - } } diff --git a/build-tools-internal/src/test/java/org/elasticsearch/gradle/internal/release/ReleaseHighlightsGeneratorTest.java b/build-tools-internal/src/test/java/org/elasticsearch/gradle/internal/release/ReleaseHighlightsGeneratorTest.java deleted file mode 100644 index 4e8320d8c0b65..0000000000000 --- a/build-tools-internal/src/test/java/org/elasticsearch/gradle/internal/release/ReleaseHighlightsGeneratorTest.java +++ /dev/null @@ -1,87 +0,0 @@ -/* - * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one - * or more contributor license agreements. Licensed under the "Elastic License - * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side - * Public License v 1"; you may not use this file except in compliance with, at - * your election, the "Elastic License 2.0", the "GNU Affero General Public - * License v3.0 only", or the "Server Side Public License, v 1". - */ - -package org.elasticsearch.gradle.internal.release; - -import org.junit.Test; - -import java.nio.charset.StandardCharsets; -import java.nio.file.Files; -import java.nio.file.Paths; -import java.util.List; -import java.util.Objects; - -import static org.hamcrest.Matchers.equalTo; -import static org.junit.Assert.assertThat; - -public class ReleaseHighlightsGeneratorTest { - - /** - * Check that the release highlights can be correctly generated when there are no highlights. - */ - @Test - public void generateFile_withNoHighlights_rendersCorrectMarkup() throws Exception { - // given: - final String template = getResource("/templates/release-highlights.asciidoc"); - final String expectedOutput = getResource( - "/org/elasticsearch/gradle/internal/release/ReleaseHighlightsGeneratorTest.noHighlights.generateFile.asciidoc" - ); - - // when: - final String actualOutput = ReleaseHighlightsGenerator.generateFile(QualifiedVersion.of("8.4.0-SNAPSHOT"), template, List.of()); - - // then: - assertThat(actualOutput, equalTo(expectedOutput)); - } - - /** - * Check that the release highlights can be correctly generated. - */ - @Test - public void generateFile_rendersCorrectMarkup() throws Exception { - // given: - final String template = getResource("/templates/release-highlights.asciidoc"); - final String expectedOutput = getResource( - "/org/elasticsearch/gradle/internal/release/ReleaseHighlightsGeneratorTest.generateFile.asciidoc" - ); - - final List entries = getEntries(); - - // when: - final String actualOutput = ReleaseHighlightsGenerator.generateFile(QualifiedVersion.of("8.4.0-SNAPSHOT"), template, entries); - - // then: - assertThat(actualOutput, equalTo(expectedOutput)); - } - - private List getEntries() { - ChangelogEntry entry123 = makeChangelogEntry(123, true); - ChangelogEntry entry456 = makeChangelogEntry(456, true); - ChangelogEntry entry789 = makeChangelogEntry(789, false); - // Return unordered list, to test correct re-ordering - return List.of(entry456, entry123, entry789); - } - - private ChangelogEntry makeChangelogEntry(int pr, boolean notable) { - ChangelogEntry entry = new ChangelogEntry(); - entry.setPr(pr); - ChangelogEntry.Highlight highlight = new ChangelogEntry.Highlight(); - entry.setHighlight(highlight); - - highlight.setNotable(notable); - highlight.setTitle("Notable release highlight number " + pr); - highlight.setBody("Notable release body number " + pr); - - return entry; - } - - private String getResource(String name) throws Exception { - return Files.readString(Paths.get(Objects.requireNonNull(this.getClass().getResource(name)).toURI()), StandardCharsets.UTF_8); - } -} diff --git a/build-tools-internal/src/test/java/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.java b/build-tools-internal/src/test/java/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.java index cbb53698c586b..248f59ad0fe18 100644 --- a/build-tools-internal/src/test/java/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.java +++ b/build-tools-internal/src/test/java/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.java @@ -15,67 +15,115 @@ import java.nio.file.Files; import java.nio.file.Paths; import java.util.ArrayList; -import java.util.HashSet; import java.util.List; import java.util.Objects; -import java.util.Set; +import static org.elasticsearch.gradle.internal.release.GenerateReleaseNotesTask.getSortedBundlesWithUniqueChangelogs; import static org.hamcrest.Matchers.equalTo; import static org.junit.Assert.assertThat; public class ReleaseNotesGeneratorTest { - /** - * Check that the release notes can be correctly generated. - */ + private static final List CHANGE_TYPES = List.of( + "breaking", + "breaking-java", + "bug", + "fixes", + "deprecation", + "enhancement", + "feature", + "features-enhancements", + "new-aggregation", + "regression", + "upgrade" + ); + @Test - public void generateFile_rendersCorrectMarkup() throws Exception { + public void generateFile_index_rendersCorrectMarkup() throws Exception { + testTemplate("index.md"); + } + + @Test + public void generateFile_index_noHighlights_rendersCorrectMarkup() throws Exception { + var bundles = getBundles(); + bundles = bundles.stream().filter(b -> false == b.version().equals("9.1.0")).toList(); + + testTemplate("index.md", "index.no-highlights.md", bundles); + } + + @Test + public void generateFile_index_noChanges_rendersCorrectMarkup() throws Exception { + var bundles = new ArrayList(); + + testTemplate("index.md", "index.no-changes.md", bundles); + } + + @Test + public void generateFile_breakingChanges_rendersCorrectMarkup() throws Exception { + testTemplate("breaking-changes.md"); + } + + @Test + public void generateFile_deprecations_rendersCorrectMarkup() throws Exception { + testTemplate("deprecations.md"); + } + + public void testTemplate(String templateFilename) throws Exception { + testTemplate(templateFilename, templateFilename, null); + } + + public void testTemplate(String templateFilename, String outputFilename) throws Exception { + testTemplate(templateFilename, outputFilename, null); + } + + public void testTemplate(String templateFilename, String outputFilename, List bundles) throws Exception { // given: - final String template = getResource("/templates/release-notes.asciidoc"); - final String expectedOutput = getResource( - "/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.generateFile.asciidoc" - ); + final String template = getResource("/templates/" + templateFilename); + final String expectedOutput = getResource("/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest." + outputFilename); - final Set entries = getEntries(); + if (bundles == null) { + bundles = getBundles(); + } + + bundles = getSortedBundlesWithUniqueChangelogs(bundles); // when: - final String actualOutput = ReleaseNotesGenerator.generateFile(template, QualifiedVersion.of("8.2.0-SNAPSHOT"), entries); + final String actualOutput = ReleaseNotesGenerator.generateFile(template, bundles); // then: assertThat(actualOutput, equalTo(expectedOutput)); } - private Set getEntries() { - final Set entries = new HashSet<>(); - entries.addAll(buildEntries(1, 2)); - entries.addAll(buildEntries(2, 2)); - entries.addAll(buildEntries(3, 2)); - - // Security issues are presented first in the notes - final ChangelogEntry securityEntry = new ChangelogEntry(); - securityEntry.setArea("Security"); - securityEntry.setType("security"); - securityEntry.setSummary("Test security issue"); - entries.add(securityEntry); - - // known issues are presented after security issues - final ChangelogEntry knownIssue = new ChangelogEntry(); - knownIssue.setArea("Search"); - knownIssue.setType("known-issue"); - knownIssue.setSummary("Test known issue"); - entries.add(knownIssue); + private List getBundles() { + List bundles = new ArrayList<>(); + + for (int i = 0; i < CHANGE_TYPES.size(); i++) { + bundles.add( + new ChangelogBundle( + "9.0." + i, + i != CHANGE_TYPES.size() - 1, + "2025-05-16T00:00:" + String.format("%d", 10 + i), + buildEntries(i, 2) + ) + ); + } - return entries; + final List entries = new ArrayList<>(); + entries.add(makeHighlightsEntry(51, false)); + entries.add(makeHighlightsEntry(50, true)); + entries.add(makeHighlightsEntry(52, true)); + + bundles.add(new ChangelogBundle("9.1.0", false, "2025-05-17T00:00:00", entries)); + + return bundles; } private List buildEntries(int seed, int count) { // Sample of possible areas from `changelog-schema.json` final List areas = List.of("Aggregation", "Cluster", "Indices", "Mappings", "Search", "Security"); - // Possible change types, with `breaking`, `breaking-java`, `known-issue` and `security` removed. - final List types = List.of("bug", "deprecation", "enhancement", "feature", "new-aggregation", "regression", "upgrade"); final String area = areas.get(seed % areas.size()); - final String type = types.get(seed % types.size()); + final String type = CHANGE_TYPES.get(seed % CHANGE_TYPES.size()); final List entries = new ArrayList<>(count); @@ -101,6 +149,30 @@ private List buildEntries(int seed, int count) { return entries; } + private List getHighlightsEntries() { + ChangelogEntry entry123 = makeHighlightsEntry(123, true); + ChangelogEntry entry456 = makeHighlightsEntry(456, true); + ChangelogEntry entry789 = makeHighlightsEntry(789, false); + // Return unordered list, to test correct re-ordering + return List.of(entry456, entry123, entry789); + } + + private ChangelogEntry makeHighlightsEntry(int pr, boolean notable) { + ChangelogEntry entry = new ChangelogEntry(); + entry.setPr(pr); + ChangelogEntry.Highlight highlight = new ChangelogEntry.Highlight(); + entry.setHighlight(highlight); + + highlight.setNotable(notable); + highlight.setTitle((notable ? "[Notable] " : "") + "Release highlight number " + pr); + highlight.setBody("Release highlight body number " + pr); + entry.setType("feature"); + entry.setArea("Search"); + entry.setSummary(""); + + return entry; + } + private String getResource(String name) throws Exception { return Files.readString(Paths.get(Objects.requireNonNull(this.getClass().getResource(name)).toURI()), StandardCharsets.UTF_8); } diff --git a/build-tools-internal/src/test/java/org/elasticsearch/gradle/internal/release/ReleaseNotesIndexGeneratorTest.java b/build-tools-internal/src/test/java/org/elasticsearch/gradle/internal/release/ReleaseNotesIndexGeneratorTest.java deleted file mode 100644 index 2a32040035ec7..0000000000000 --- a/build-tools-internal/src/test/java/org/elasticsearch/gradle/internal/release/ReleaseNotesIndexGeneratorTest.java +++ /dev/null @@ -1,60 +0,0 @@ -/* - * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one - * or more contributor license agreements. Licensed under the "Elastic License - * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side - * Public License v 1"; you may not use this file except in compliance with, at - * your election, the "Elastic License 2.0", the "GNU Affero General Public - * License v3.0 only", or the "Server Side Public License, v 1". - */ - -package org.elasticsearch.gradle.internal.release; - -import org.junit.Test; - -import java.nio.charset.StandardCharsets; -import java.nio.file.Files; -import java.nio.file.Paths; -import java.util.Objects; -import java.util.Set; -import java.util.stream.Collectors; -import java.util.stream.Stream; - -import static org.hamcrest.Matchers.equalTo; -import static org.junit.Assert.assertThat; - -public class ReleaseNotesIndexGeneratorTest { - - /** - * Check that a release notes index can be generated. - */ - @Test - public void generateFile_rendersCorrectMarkup() throws Exception { - // given: - final Set versions = Stream.of( - "8.0.0-alpha1", - "8.0.0-beta2", - "8.0.0-rc3", - "8.0.0", - "8.0.1", - "8.0.2", - "8.1.0", - "8.1.1", - "8.2.0-SNAPSHOT" - ).map(QualifiedVersion::of).collect(Collectors.toSet()); - - final String template = getResource("/templates/release-notes-index.asciidoc"); - final String expectedOutput = getResource( - "/org/elasticsearch/gradle/internal/release/ReleaseNotesIndexGeneratorTest.generateFile.asciidoc" - ); - - // when: - final String actualOutput = ReleaseNotesIndexGenerator.generateFile(versions, template); - - // then: - assertThat(actualOutput, equalTo(expectedOutput)); - } - - private String getResource(String name) throws Exception { - return Files.readString(Paths.get(Objects.requireNonNull(this.getClass().getResource(name)).toURI()), StandardCharsets.UTF_8); - } -} diff --git a/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/BreakingChangesGeneratorTest.generateMigrationFile.asciidoc b/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/BreakingChangesGeneratorTest.generateMigrationFile.asciidoc deleted file mode 100644 index ee78d10fd4b07..0000000000000 --- a/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/BreakingChangesGeneratorTest.generateMigrationFile.asciidoc +++ /dev/null @@ -1,134 +0,0 @@ -[[migrating-8.4]] -== Migrating to 8.4 -++++ -8.4 -++++ - -This section discusses the changes that you need to be aware of when migrating -your application to {es} 8.4. - -See also <> and <>. - -coming::[8.4.0] - - -[discrete] -[[breaking-changes-8.4]] -=== Breaking changes - -The following changes in {es} 8.4 might affect your applications -and prevent them from operating normally. -Before upgrading to 8.4, review these changes and take the described steps -to mitigate the impact. - -[discrete] -[[breaking_84_api_changes]] -==== API changes - -[[breaking_change_number_1]] -.Breaking change number 1 -[%collapsible] -==== -*Details* + -Breaking change details 1 - -*Impact* + -Breaking change impact description 1 -==== - -[discrete] -[[breaking_84_cluster_and_node_setting_changes]] -==== Cluster and node setting changes - -[[breaking_change_number_2]] -.Breaking change number 2 -[%collapsible] -==== -*Details* + -Breaking change details 2 - -*Impact* + -Breaking change impact description 2 -==== - -[[breaking_change_number_4]] -.Breaking change number 4 -[%collapsible] -==== -*Details* + -Breaking change details 4 - -*Impact* + -Breaking change impact description 4 -==== - -[discrete] -[[breaking_84_transform_changes]] -==== Transform changes - -[[breaking_change_number_3]] -.Breaking change number 3 -[%collapsible] -==== -*Details* + -Breaking change details 3 - -*Impact* + -Breaking change impact description 3 -==== - - -[discrete] -[[deprecated-8.4]] -=== Deprecations - -The following functionality has been deprecated in {es} 8.4 -and will be removed in a future version. -While this won't have an immediate impact on your applications, -we strongly encourage you to take the described steps to update your code -after upgrading to 8.4. - -To find out if you are using any deprecated functionality, -enable <>. - -[discrete] -[[deprecations_84_cluster_and_node_setting]] -==== Cluster and node setting deprecations - -[[deprecation_change_number_5]] -.Deprecation change number 5 -[%collapsible] -==== -*Details* + -Deprecation change details 5 - -*Impact* + -Deprecation change impact description 5 -==== - -[[deprecation_change_number_6]] -.Deprecation change number 6 -[%collapsible] -==== -*Details* + -Deprecation change details 6 - -*Impact* + -Deprecation change impact description 6 -==== - -[discrete] -[[deprecations_84_cluster_and_node_setting]] -==== Cluster and node setting deprecations - -[[deprecation_change_number_7]] -.Deprecation change number 7 -[%collapsible] -==== -*Details* + -Deprecation change details 7 - -*Impact* + -Deprecation change impact description 7 -==== - diff --git a/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.breaking-changes.md b/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.breaking-changes.md new file mode 100644 index 0000000000000..1b8d1f3a981cb --- /dev/null +++ b/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.breaking-changes.md @@ -0,0 +1,71 @@ +--- +navigation_title: "Breaking changes" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/breaking-changes.html +--- + +# Elasticsearch breaking changes [elasticsearch-breaking-changes] + +Breaking changes can impact your Elastic applications, potentially disrupting normal operations. Before you upgrade, carefully review the Elasticsearch breaking changes and take the necessary steps to mitigate any issues. + +If you are migrating from a version prior to version 9.0, you must first upgrade to the last 8.x version available. To learn how to upgrade, check out [Upgrade](docs-content://deploy-manage/upgrade.md). + +% ## Next version [elasticsearch-nextversion-breaking-changes] + +```{applies_to} +stack: coming 9.1.0 +``` +## 9.1.0 [elasticsearch-9.1.0-breaking-changes] + +No breaking changes in this version. + +```{applies_to} +stack: coming 9.0.10 +``` +## 9.0.10 [elasticsearch-9.0.10-breaking-changes] + +No breaking changes in this version. + +## 9.0.9 [elasticsearch-9.0.9-breaking-changes] + +No breaking changes in this version. + +## 9.0.8 [elasticsearch-9.0.8-breaking-changes] + +No breaking changes in this version. + +## 9.0.7 [elasticsearch-9.0.7-breaking-changes] + +No breaking changes in this version. + +## 9.0.6 [elasticsearch-9.0.6-breaking-changes] + +No breaking changes in this version. + +## 9.0.5 [elasticsearch-9.0.5-breaking-changes] + +No breaking changes in this version. + +## 9.0.4 [elasticsearch-9.0.4-breaking-changes] + +No breaking changes in this version. + +## 9.0.3 [elasticsearch-9.0.3-breaking-changes] + +No breaking changes in this version. + +## 9.0.2 [elasticsearch-9.0.2-breaking-changes] + +No breaking changes in this version. + +## 9.0.1 [elasticsearch-9.0.1-breaking-changes] + +No breaking changes in this version. + +## 9.0.0 [elasticsearch-900-breaking-changes] + +Aggregation: +* Test changelog entry 0_0 [#0](https://github.com/elastic/elasticsearch/pull/0) (issue: [#1](https://github.com/elastic/elasticsearch/issues/1)) +* Test changelog entry 0_1 [#2](https://github.com/elastic/elasticsearch/pull/2) (issues: [#3](https://github.com/elastic/elasticsearch/issues/3), [#4](https://github.com/elastic/elasticsearch/issues/4)) + + diff --git a/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.deprecations.md b/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.deprecations.md new file mode 100644 index 0000000000000..35587f559014b --- /dev/null +++ b/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.deprecations.md @@ -0,0 +1,75 @@ +--- +navigation_title: "Deprecations" +--- + +# {{es}} deprecations [elasticsearch-deprecations] + +Over time, certain Elastic functionality becomes outdated and is replaced or removed. To help with the transition, Elastic deprecates functionality for a period before removal, giving you time to update your applications. + +Review the deprecated functionality for Elasticsearch. While deprecations have no immediate impact, we strongly encourage you update your implementation after you upgrade. To learn how to upgrade, check out [Upgrade](docs-content://deploy-manage/upgrade.md). + +To give you insight into what deprecated features you’re using, {{es}}: + +* Returns a `Warn` HTTP header whenever you submit a request that uses deprecated functionality. +* [Logs deprecation warnings](docs-content://deploy-manage/monitor/logging-configuration/update-elasticsearch-logging-levels.md#deprecation-logging) when deprecated functionality is used. +* [Provides a deprecation info API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-migration-deprecations) that scans a cluster’s configuration and mappings for deprecated functionality. + +% ## Next version [elasticsearch-nextversion-deprecations] + +```{applies_to} +stack: coming 9.1.0 +``` +## 9.1.0 [elasticsearch-9.1.0-deprecations] + +No deprecations in this version. + +```{applies_to} +stack: coming 9.0.10 +``` +## 9.0.10 [elasticsearch-9.0.10-deprecations] + +No deprecations in this version. + +## 9.0.9 [elasticsearch-9.0.9-deprecations] + +No deprecations in this version. + +## 9.0.8 [elasticsearch-9.0.8-deprecations] + +No deprecations in this version. + +## 9.0.7 [elasticsearch-9.0.7-deprecations] + +No deprecations in this version. + +## 9.0.6 [elasticsearch-9.0.6-deprecations] + +No deprecations in this version. + +## 9.0.5 [elasticsearch-9.0.5-deprecations] + +No deprecations in this version. + +## 9.0.4 [elasticsearch-9.0.4-deprecations] + +Search: +* Test changelog entry 4_0 [#4000](https://github.com/elastic/elasticsearch/pull/4000) (issue: [#4001](https://github.com/elastic/elasticsearch/issues/4001)) +* Test changelog entry 4_1 [#4002](https://github.com/elastic/elasticsearch/pull/4002) (issues: [#4003](https://github.com/elastic/elasticsearch/issues/4003), [#4004](https://github.com/elastic/elasticsearch/issues/4004)) + + + +## 9.0.3 [elasticsearch-9.0.3-deprecations] + +No deprecations in this version. + +## 9.0.2 [elasticsearch-9.0.2-deprecations] + +No deprecations in this version. + +## 9.0.1 [elasticsearch-9.0.1-deprecations] + +No deprecations in this version. + +## 9.0.0 [elasticsearch-900-deprecations] + +No deprecations in this version. diff --git a/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.generateFile.asciidoc b/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.generateFile.asciidoc deleted file mode 100644 index 77b00f9ba9852..0000000000000 --- a/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.generateFile.asciidoc +++ /dev/null @@ -1,44 +0,0 @@ -[[release-notes-8.2.0]] -== {es} version 8.2.0 - -coming[8.2.0] - -Also see <>. - -[discrete] -[[security-updates-8.2.0]] -=== Security updates - -* Test security issue - -[discrete] -[[known-issues-8.2.0]] -=== Known issues - -* Test known issue - -[[deprecation-8.2.0]] -[float] -=== Deprecations - -Cluster:: -* Test changelog entry 1_0 {es-pull}1000[#1000] (issue: {es-issue}1001[#1001]) -* Test changelog entry 1_1 {es-pull}1002[#1002] (issues: {es-issue}1003[#1003], {es-issue}1004[#1004]) - -[[enhancement-8.2.0]] -[float] -=== Enhancements - -Indices:: -* Test changelog entry 2_0 {es-pull}2000[#2000] (issue: {es-issue}2001[#2001]) -* Test changelog entry 2_1 {es-pull}2002[#2002] (issues: {es-issue}2003[#2003], {es-issue}2004[#2004]) - -[[feature-8.2.0]] -[float] -=== New features - -Mappings:: -* Test changelog entry 3_0 {es-pull}3000[#3000] (issue: {es-issue}3001[#3001]) -* Test changelog entry 3_1 {es-pull}3002[#3002] (issues: {es-issue}3003[#3003], {es-issue}3004[#3004]) - - diff --git a/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.index.md b/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.index.md new file mode 100644 index 0000000000000..52c20341e1b5c --- /dev/null +++ b/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.index.md @@ -0,0 +1,132 @@ +--- +navigation_title: "Elasticsearch" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/es-release-notes.html +--- + +# Elasticsearch release notes [elasticsearch-release-notes] + +Review the changes, fixes, and more in each version of Elasticsearch. + +To check for security updates, go to [Security announcements for the Elastic stack](https://discuss.elastic.co/c/announcements/security-announcements/31). + +% Release notes include only features, enhancements, and fixes. Add breaking changes, deprecations, and known issues to the applicable release notes sections. + +% ## version.next [elasticsearch-next-release-notes] + +% ### Features and enhancements [elasticsearch-next-features-enhancements] +% * + +% ### Fixes [elasticsearch-next-fixes] +% * + +```{applies_to} +stack: coming 9.1.0 +``` +## 9.1.0 [elasticsearch-9.1.0-release-notes] + +### Highlights [elasticsearch-9.1.0-highlights] + +::::{dropdown} [Notable] Release highlight number 50 +Release highlight body number 50 +:::: + +::::{dropdown} [Notable] Release highlight number 52 +Release highlight body number 52 +:::: + +::::{dropdown} Release highlight number 51 +Release highlight body number 51 +:::: + +### Features and enhancements [elasticsearch-9.1.0-features-enhancements] + +Search: +* [#51](https://github.com/elastic/elasticsearch/pull/51) +* [#50](https://github.com/elastic/elasticsearch/pull/50) +* [#52](https://github.com/elastic/elasticsearch/pull/52) + + +```{applies_to} +stack: coming 9.0.10 +``` +## 9.0.10 [elasticsearch-9.0.10-release-notes] + +### Features and enhancements [elasticsearch-9.0.10-features-enhancements] + +Search: +* Test changelog entry 10_0 [#10000](https://github.com/elastic/elasticsearch/pull/10000) (issue: [#10001](https://github.com/elastic/elasticsearch/issues/10001)) +* Test changelog entry 10_1 [#10002](https://github.com/elastic/elasticsearch/pull/10002) (issues: [#10003](https://github.com/elastic/elasticsearch/issues/10003), [#10004](https://github.com/elastic/elasticsearch/issues/10004)) + + +## 9.0.9 [elasticsearch-9.0.9-release-notes] + +### Regressions [elasticsearch-9.0.9-regression] + +Mappings: +* Test changelog entry 9_0 [#9000](https://github.com/elastic/elasticsearch/pull/9000) (issue: [#9001](https://github.com/elastic/elasticsearch/issues/9001)) +* Test changelog entry 9_1 [#9002](https://github.com/elastic/elasticsearch/pull/9002) (issues: [#9003](https://github.com/elastic/elasticsearch/issues/9003), [#9004](https://github.com/elastic/elasticsearch/issues/9004)) + + +## 9.0.8 [elasticsearch-9.0.8-release-notes] + +### Features and enhancements [elasticsearch-9.0.8-features-enhancements] + +Indices: +* Test changelog entry 8_0 [#8000](https://github.com/elastic/elasticsearch/pull/8000) (issue: [#8001](https://github.com/elastic/elasticsearch/issues/8001)) +* Test changelog entry 8_1 [#8002](https://github.com/elastic/elasticsearch/pull/8002) (issues: [#8003](https://github.com/elastic/elasticsearch/issues/8003), [#8004](https://github.com/elastic/elasticsearch/issues/8004)) + + +## 9.0.7 [elasticsearch-9.0.7-release-notes] + +### Features and enhancements [elasticsearch-9.0.7-features-enhancements] + +Cluster: +* Test changelog entry 7_0 [#7000](https://github.com/elastic/elasticsearch/pull/7000) (issue: [#7001](https://github.com/elastic/elasticsearch/issues/7001)) +* Test changelog entry 7_1 [#7002](https://github.com/elastic/elasticsearch/pull/7002) (issues: [#7003](https://github.com/elastic/elasticsearch/issues/7003), [#7004](https://github.com/elastic/elasticsearch/issues/7004)) + + +## 9.0.6 [elasticsearch-9.0.6-release-notes] + +### Features and enhancements [elasticsearch-9.0.6-features-enhancements] + +Aggregation: +* Test changelog entry 6_0 [#6000](https://github.com/elastic/elasticsearch/pull/6000) (issue: [#6001](https://github.com/elastic/elasticsearch/issues/6001)) +* Test changelog entry 6_1 [#6002](https://github.com/elastic/elasticsearch/pull/6002) (issues: [#6003](https://github.com/elastic/elasticsearch/issues/6003), [#6004](https://github.com/elastic/elasticsearch/issues/6004)) + + +## 9.0.5 [elasticsearch-9.0.5-release-notes] + +### Features and enhancements [elasticsearch-9.0.5-features-enhancements] + +Security: +* Test changelog entry 5_0 [#5000](https://github.com/elastic/elasticsearch/pull/5000) (issue: [#5001](https://github.com/elastic/elasticsearch/issues/5001)) +* Test changelog entry 5_1 [#5002](https://github.com/elastic/elasticsearch/pull/5002) (issues: [#5003](https://github.com/elastic/elasticsearch/issues/5003), [#5004](https://github.com/elastic/elasticsearch/issues/5004)) + + +## 9.0.4 [elasticsearch-9.0.4-release-notes] + + +## 9.0.3 [elasticsearch-9.0.3-release-notes] + +### Fixes [elasticsearch-9.0.3-fixes] + +Mappings: +* Test changelog entry 3_0 [#3000](https://github.com/elastic/elasticsearch/pull/3000) (issue: [#3001](https://github.com/elastic/elasticsearch/issues/3001)) +* Test changelog entry 3_1 [#3002](https://github.com/elastic/elasticsearch/pull/3002) (issues: [#3003](https://github.com/elastic/elasticsearch/issues/3003), [#3004](https://github.com/elastic/elasticsearch/issues/3004)) + + +## 9.0.2 [elasticsearch-9.0.2-release-notes] + +### Fixes [elasticsearch-9.0.2-fixes] + +Indices: +* Test changelog entry 2_0 [#2000](https://github.com/elastic/elasticsearch/pull/2000) (issue: [#2001](https://github.com/elastic/elasticsearch/issues/2001)) +* Test changelog entry 2_1 [#2002](https://github.com/elastic/elasticsearch/pull/2002) (issues: [#2003](https://github.com/elastic/elasticsearch/issues/2003), [#2004](https://github.com/elastic/elasticsearch/issues/2004)) + + +## 9.0.1 [elasticsearch-9.0.1-release-notes] + + +## 9.0.0 [elasticsearch-900-release-notes] + diff --git a/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.index.no-changes.md b/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.index.no-changes.md new file mode 100644 index 0000000000000..5ec235cb3718a --- /dev/null +++ b/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.index.no-changes.md @@ -0,0 +1,21 @@ +--- +navigation_title: "Elasticsearch" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/es-release-notes.html +--- + +# Elasticsearch release notes [elasticsearch-release-notes] + +Review the changes, fixes, and more in each version of Elasticsearch. + +To check for security updates, go to [Security announcements for the Elastic stack](https://discuss.elastic.co/c/announcements/security-announcements/31). + +% Release notes include only features, enhancements, and fixes. Add breaking changes, deprecations, and known issues to the applicable release notes sections. + +% ## version.next [elasticsearch-next-release-notes] + +% ### Features and enhancements [elasticsearch-next-features-enhancements] +% * + +% ### Fixes [elasticsearch-next-fixes] +% * diff --git a/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.index.no-highlights.md b/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.index.no-highlights.md new file mode 100644 index 0000000000000..ee81015b54f67 --- /dev/null +++ b/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/ReleaseNotesGeneratorTest.index.no-highlights.md @@ -0,0 +1,105 @@ +--- +navigation_title: "Elasticsearch" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/es-release-notes.html +--- + +# Elasticsearch release notes [elasticsearch-release-notes] + +Review the changes, fixes, and more in each version of Elasticsearch. + +To check for security updates, go to [Security announcements for the Elastic stack](https://discuss.elastic.co/c/announcements/security-announcements/31). + +% Release notes include only features, enhancements, and fixes. Add breaking changes, deprecations, and known issues to the applicable release notes sections. + +% ## version.next [elasticsearch-next-release-notes] + +% ### Features and enhancements [elasticsearch-next-features-enhancements] +% * + +% ### Fixes [elasticsearch-next-fixes] +% * + +```{applies_to} +stack: coming 9.0.10 +``` +## 9.0.10 [elasticsearch-9.0.10-release-notes] + +### Features and enhancements [elasticsearch-9.0.10-features-enhancements] + +Search: +* Test changelog entry 10_0 [#10000](https://github.com/elastic/elasticsearch/pull/10000) (issue: [#10001](https://github.com/elastic/elasticsearch/issues/10001)) +* Test changelog entry 10_1 [#10002](https://github.com/elastic/elasticsearch/pull/10002) (issues: [#10003](https://github.com/elastic/elasticsearch/issues/10003), [#10004](https://github.com/elastic/elasticsearch/issues/10004)) + + +## 9.0.9 [elasticsearch-9.0.9-release-notes] + +### Regressions [elasticsearch-9.0.9-regression] + +Mappings: +* Test changelog entry 9_0 [#9000](https://github.com/elastic/elasticsearch/pull/9000) (issue: [#9001](https://github.com/elastic/elasticsearch/issues/9001)) +* Test changelog entry 9_1 [#9002](https://github.com/elastic/elasticsearch/pull/9002) (issues: [#9003](https://github.com/elastic/elasticsearch/issues/9003), [#9004](https://github.com/elastic/elasticsearch/issues/9004)) + + +## 9.0.8 [elasticsearch-9.0.8-release-notes] + +### Features and enhancements [elasticsearch-9.0.8-features-enhancements] + +Indices: +* Test changelog entry 8_0 [#8000](https://github.com/elastic/elasticsearch/pull/8000) (issue: [#8001](https://github.com/elastic/elasticsearch/issues/8001)) +* Test changelog entry 8_1 [#8002](https://github.com/elastic/elasticsearch/pull/8002) (issues: [#8003](https://github.com/elastic/elasticsearch/issues/8003), [#8004](https://github.com/elastic/elasticsearch/issues/8004)) + + +## 9.0.7 [elasticsearch-9.0.7-release-notes] + +### Features and enhancements [elasticsearch-9.0.7-features-enhancements] + +Cluster: +* Test changelog entry 7_0 [#7000](https://github.com/elastic/elasticsearch/pull/7000) (issue: [#7001](https://github.com/elastic/elasticsearch/issues/7001)) +* Test changelog entry 7_1 [#7002](https://github.com/elastic/elasticsearch/pull/7002) (issues: [#7003](https://github.com/elastic/elasticsearch/issues/7003), [#7004](https://github.com/elastic/elasticsearch/issues/7004)) + + +## 9.0.6 [elasticsearch-9.0.6-release-notes] + +### Features and enhancements [elasticsearch-9.0.6-features-enhancements] + +Aggregation: +* Test changelog entry 6_0 [#6000](https://github.com/elastic/elasticsearch/pull/6000) (issue: [#6001](https://github.com/elastic/elasticsearch/issues/6001)) +* Test changelog entry 6_1 [#6002](https://github.com/elastic/elasticsearch/pull/6002) (issues: [#6003](https://github.com/elastic/elasticsearch/issues/6003), [#6004](https://github.com/elastic/elasticsearch/issues/6004)) + + +## 9.0.5 [elasticsearch-9.0.5-release-notes] + +### Features and enhancements [elasticsearch-9.0.5-features-enhancements] + +Security: +* Test changelog entry 5_0 [#5000](https://github.com/elastic/elasticsearch/pull/5000) (issue: [#5001](https://github.com/elastic/elasticsearch/issues/5001)) +* Test changelog entry 5_1 [#5002](https://github.com/elastic/elasticsearch/pull/5002) (issues: [#5003](https://github.com/elastic/elasticsearch/issues/5003), [#5004](https://github.com/elastic/elasticsearch/issues/5004)) + + +## 9.0.4 [elasticsearch-9.0.4-release-notes] + + +## 9.0.3 [elasticsearch-9.0.3-release-notes] + +### Fixes [elasticsearch-9.0.3-fixes] + +Mappings: +* Test changelog entry 3_0 [#3000](https://github.com/elastic/elasticsearch/pull/3000) (issue: [#3001](https://github.com/elastic/elasticsearch/issues/3001)) +* Test changelog entry 3_1 [#3002](https://github.com/elastic/elasticsearch/pull/3002) (issues: [#3003](https://github.com/elastic/elasticsearch/issues/3003), [#3004](https://github.com/elastic/elasticsearch/issues/3004)) + + +## 9.0.2 [elasticsearch-9.0.2-release-notes] + +### Fixes [elasticsearch-9.0.2-fixes] + +Indices: +* Test changelog entry 2_0 [#2000](https://github.com/elastic/elasticsearch/pull/2000) (issue: [#2001](https://github.com/elastic/elasticsearch/issues/2001)) +* Test changelog entry 2_1 [#2002](https://github.com/elastic/elasticsearch/pull/2002) (issues: [#2003](https://github.com/elastic/elasticsearch/issues/2003), [#2004](https://github.com/elastic/elasticsearch/issues/2004)) + + +## 9.0.1 [elasticsearch-9.0.1-release-notes] + + +## 9.0.0 [elasticsearch-900-release-notes] + diff --git a/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/ReleaseNotesIndexGeneratorTest.generateFile.asciidoc b/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/ReleaseNotesIndexGeneratorTest.generateFile.asciidoc deleted file mode 100644 index f07a5f21db195..0000000000000 --- a/build-tools-internal/src/test/resources/org/elasticsearch/gradle/internal/release/ReleaseNotesIndexGeneratorTest.generateFile.asciidoc +++ /dev/null @@ -1,30 +0,0 @@ -[[es-release-notes]] -= Release notes - -[partintro] --- - -This section summarizes the changes in each release. - -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> - --- - -include::release-notes/8.2.0.asciidoc[] -include::release-notes/8.1.1.asciidoc[] -include::release-notes/8.1.0.asciidoc[] -include::release-notes/8.0.2.asciidoc[] -include::release-notes/8.0.1.asciidoc[] -include::release-notes/8.0.0.asciidoc[] -include::release-notes/8.0.0-rc3.asciidoc[] -include::release-notes/8.0.0-beta2.asciidoc[] -include::release-notes/8.0.0-alpha1.asciidoc[] - diff --git a/build-tools/build.gradle b/build-tools/build.gradle index e457999fedfee..9d9ec139b175b 100644 --- a/build-tools/build.gradle +++ b/build-tools/build.gradle @@ -51,6 +51,10 @@ gradlePlugin { id = 'elasticsearch.stable-esplugin' implementationClass = 'org.elasticsearch.gradle.plugin.StablePluginBuildPlugin' } + testBuildInfo { + id = 'elasticsearch.test-build-info' + implementationClass = 'org.elasticsearch.gradle.test.TestBuildInfoPlugin' + } javaRestTest { id = 'elasticsearch.java-rest-test' implementationClass = 'org.elasticsearch.gradle.test.JavaRestTestPlugin' diff --git a/build-tools/src/integTest/groovy/org/elasticsearch/gradle/test/TestBuildInfoPluginFuncTest.groovy b/build-tools/src/integTest/groovy/org/elasticsearch/gradle/test/TestBuildInfoPluginFuncTest.groovy new file mode 100644 index 0000000000000..266c1ab1b107b --- /dev/null +++ b/build-tools/src/integTest/groovy/org/elasticsearch/gradle/test/TestBuildInfoPluginFuncTest.groovy @@ -0,0 +1,115 @@ +package org.elasticsearch.gradle.test + +import com.fasterxml.jackson.databind.ObjectMapper + +import org.elasticsearch.gradle.fixtures.AbstractGradleFuncTest +import org.gradle.testkit.runner.TaskOutcome + +class TestBuildInfoPluginFuncTest extends AbstractGradleFuncTest { + def "basic functionality"() { + given: + file("src/main/java/com/example/Example.java") << """ + package com.example; + + public class Example { + } + """ + + file("src/main/java/module-info.java") << """ + module com.example { + exports com.example; + } + """ + + buildFile << """ + import org.elasticsearch.gradle.plugin.GenerateTestBuildInfoTask; + + plugins { + id 'java' + id 'elasticsearch.test-build-info' + } + + repositories { + mavenCentral() + } + + tasks.withType(GenerateTestBuildInfoTask.class) { + componentName = 'example-component' + outputFile = new File('build/generated-build-info/plugin-test-build-info.json') + } + """ + + def location = Map.of( + "module", "com.example", + "representative_class", "com/example/Example.class" + ) + def expectedOutput = Map.of( + "component", "example-component", + "locations", List.of(location) + ) + + def output = file("build/generated-build-info/plugin-test-build-info.json") + + when: + def result = gradleRunner('generateTestBuildInfo').build() + + then: + result.task(":generateTestBuildInfo").outcome == TaskOutcome.SUCCESS + output.exists() == true + new ObjectMapper().readValue(output, Map.class) == expectedOutput + } + + def "dependencies"() { + buildFile << """ + import org.elasticsearch.gradle.plugin.GenerateTestBuildInfoTask; + + plugins { + id 'java' + id 'elasticsearch.test-build-info' + } + + repositories { + mavenCentral() + } + + dependencies { + // We pin to specific versions here because they are known to have the properties we want to test. + // We're not actually running this code. + implementation "org.ow2.asm:asm:9.7.1" // has module-info.class + implementation "junit:junit:4.13" // has Automatic-Module-Name, and brings in hamcrest which does not + } + + tasks.withType(GenerateTestBuildInfoTask.class) { + componentName = 'example-component' + outputFile = new File('build/generated-build-info/plugin-test-build-info.json') + } + """ + + def output = file("build/generated-build-info/plugin-test-build-info.json") + + def locationFromModuleInfo = Map.of( + "module", "org.objectweb.asm", + "representative_class", 'org/objectweb/asm/AnnotationVisitor.class' + ) + def locationFromManifest = Map.of( + "module", "junit", + "representative_class", 'junit/textui/TestRunner.class' + ) + def locationFromJarFileName = Map.of( + "module", "hamcrest.core", + "representative_class", 'org/hamcrest/BaseDescription.class' + ) + def expectedOutput = Map.of( + "component", "example-component", + "locations", List.of(locationFromModuleInfo, locationFromManifest, locationFromJarFileName) + ) + + when: + def result = gradleRunner('generateTestBuildInfo').build() + + then: + result.task(":generateTestBuildInfo").outcome == TaskOutcome.SUCCESS + output.exists() == true + new ObjectMapper().readValue(output, Map.class) == expectedOutput + } +} diff --git a/build-tools/src/main/java/org/elasticsearch/gradle/plugin/BasePluginBuildPlugin.java b/build-tools/src/main/java/org/elasticsearch/gradle/plugin/BasePluginBuildPlugin.java index 9e20ce64ed88e..e00a4b45f8a61 100644 --- a/build-tools/src/main/java/org/elasticsearch/gradle/plugin/BasePluginBuildPlugin.java +++ b/build-tools/src/main/java/org/elasticsearch/gradle/plugin/BasePluginBuildPlugin.java @@ -121,7 +121,10 @@ private TaskProvider createBundleTasks(final Project project, PluginPropert task.getIsLicensed().set(providerFactory.provider(extension::isLicensed)); var mainSourceSet = project.getExtensions().getByType(SourceSetContainer.class).getByName(SourceSet.MAIN_SOURCE_SET_NAME); - FileCollection moduleInfoFile = mainSourceSet.getOutput().getAsFileTree().matching(p -> p.include("module-info.class")); + FileCollection moduleInfoFile = mainSourceSet.getOutput() + .getClassesDirs() + .getAsFileTree() + .matching(p -> p.include("module-info.class")); task.getModuleInfoFile().setFrom(moduleInfoFile); }); diff --git a/build-tools/src/main/java/org/elasticsearch/gradle/plugin/GenerateTestBuildInfoTask.java b/build-tools/src/main/java/org/elasticsearch/gradle/plugin/GenerateTestBuildInfoTask.java new file mode 100644 index 0000000000000..f015942eb7152 --- /dev/null +++ b/build-tools/src/main/java/org/elasticsearch/gradle/plugin/GenerateTestBuildInfoTask.java @@ -0,0 +1,357 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the "Elastic License + * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side + * Public License v 1"; you may not use this file except in compliance with, at + * your election, the "Elastic License 2.0", the "GNU Affero General Public + * License v3.0 only", or the "Server Side Public License, v 1". + */ + +package org.elasticsearch.gradle.plugin; + +import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.PropertyNamingStrategies; +import com.fasterxml.jackson.databind.SerializationFeature; + +import org.gradle.api.DefaultTask; +import org.gradle.api.file.FileCollection; +import org.gradle.api.file.RegularFileProperty; +import org.gradle.api.provider.Property; +import org.gradle.api.tasks.CacheableTask; +import org.gradle.api.tasks.Classpath; +import org.gradle.api.tasks.Input; +import org.gradle.api.tasks.Optional; +import org.gradle.api.tasks.OutputFile; +import org.gradle.api.tasks.TaskAction; +import org.jetbrains.annotations.NotNull; +import org.objectweb.asm.ClassReader; +import org.objectweb.asm.ClassVisitor; +import org.objectweb.asm.ModuleVisitor; +import org.objectweb.asm.Opcodes; + +import java.io.File; +import java.io.FileInputStream; +import java.io.IOException; +import java.io.InputStream; +import java.nio.charset.StandardCharsets; +import java.nio.file.FileVisitResult; +import java.nio.file.Files; +import java.nio.file.Path; +import java.nio.file.SimpleFileVisitor; +import java.nio.file.attribute.BasicFileAttributes; +import java.security.CodeSource; +import java.util.ArrayList; +import java.util.Comparator; +import java.util.List; +import java.util.jar.JarEntry; +import java.util.jar.JarFile; +import java.util.jar.Manifest; +import java.util.regex.Matcher; +import java.util.regex.Pattern; +import java.util.zip.ZipEntry; + +import static java.nio.file.FileVisitResult.CONTINUE; +import static java.nio.file.FileVisitResult.TERMINATE; + +/** + * This task generates a file with a class to module mapping + * used to imitate modular behavior during unit tests so + * entitlements can lookup correct policies. + */ +@CacheableTask +public abstract class GenerateTestBuildInfoTask extends DefaultTask { + + public static final String DESCRIPTION = "generates plugin test dependencies file"; + + public static final String META_INF_VERSIONS_PREFIX = "META-INF/versions/"; + public static final String JAR_DESCRIPTOR_SUFFIX = ".jar"; + + public GenerateTestBuildInfoTask() { + setDescription(DESCRIPTION); + } + + @Input + @Optional + public abstract Property getModuleName(); + + @Input + public abstract Property getComponentName(); + + @Classpath + public abstract Property getCodeLocations(); + + @OutputFile + public abstract RegularFileProperty getOutputFile(); + + @TaskAction + public void generatePropertiesFile() throws IOException { + Path outputFile = getOutputFile().get().getAsFile().toPath(); + Files.createDirectories(outputFile.getParent()); + + try (var writer = Files.newBufferedWriter(outputFile, StandardCharsets.UTF_8)) { + ObjectMapper mapper = new ObjectMapper().configure(SerializationFeature.INDENT_OUTPUT, true) + .setPropertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE); + mapper.writeValue(writer, new OutputFileContents(getComponentName().get(), buildLocationList())); + } + } + + /** + * The output of this task is a JSON file formatted according to this record. + * @param component the entitlements component name of the artifact we're describing + * @param locations a {@link Location} for each code directory/jar in this artifact + */ + record OutputFileContents(String component, List locations) {} + + /** + * Our analog of a single {@link CodeSource#getLocation()}. + * All classes in any single location (a directory or jar) + * are considered to be part of the same Java module for entitlements purposes. + * Since tests run without Java modules, and entitlements are all predicated on modules, + * this info lets us determine what the module would have been + * so we can look up the appropriate entitlements. + * + * @param module the name of the Java module corresponding to this {@code Location}. + * @param representativeClass an example of any .class file within this {@code Location} + * whose name will be unique within its {@link ClassLoader} at run time. + */ + record Location(String module, String representativeClass) {} + + /** + * Build the list of {@link Location}s for all {@link #getCodeLocations() code locations}. + * There are different methods for finding these depending on if the + * classpath entry is a jar or a directory + */ + private List buildLocationList() throws IOException { + List locations = new ArrayList<>(); + for (File file : getCodeLocations().get().getFiles()) { + if (file.exists()) { + if (file.getName().endsWith(JAR_DESCRIPTOR_SUFFIX)) { + extractLocationsFromJar(file, locations); + } else if (file.isDirectory()) { + extractLocationsFromDirectory(file, locations); + } else { + throw new IllegalArgumentException("unrecognized classpath entry: " + file); + } + } + } + return List.copyOf(locations); + } + + /** + * find the first class and module when the class path entry is a jar + */ + private void extractLocationsFromJar(File file, List locations) throws IOException { + try (JarFile jarFile = new JarFile(file)) { + var className = extractClassNameFromJar(jarFile); + + if (className.isPresent()) { + String moduleName = extractModuleNameFromJar(file, jarFile); + locations.add(new Location(moduleName, className.get())); + } + } + } + + /** + * look through the jar to find the first unique class that isn't + * in META-INF (those may not be unique) and isn't module-info.class + * (which is also not unique) and avoid anonymous classes + */ + private java.util.Optional extractClassNameFromJar(JarFile jarFile) { + return jarFile.stream() + .filter( + je -> je.getName().startsWith("META-INF") == false + && je.getName().equals("module-info.class") == false + && je.getName().contains("$") == false + && je.getName().endsWith(".class") + ) + .findFirst() + .map(ZipEntry::getName); + } + + /** + * Look through the jar for the module name using a succession of techniques corresponding + * to how the JDK itself determines module names, + * as documented in {@link java.lang.module.ModuleFinder#of}. + */ + private String extractModuleNameFromJar(File file, JarFile jarFile) throws IOException { + String moduleName = null; + + if (jarFile.isMultiRelease()) { + StringBuilder dir = versionDirectoryIfExists(jarFile); + if (dir != null) { + dir.append("/module-info.class"); + moduleName = getModuleNameFromModuleInfoFile(dir.toString(), jarFile); + } + } + + if (moduleName == null) { + moduleName = getModuleNameFromModuleInfoFile("module-info.class", jarFile); + } + + if (moduleName == null) { + moduleName = getAutomaticModuleNameFromManifest(jarFile); + } + + if (moduleName == null) { + moduleName = deriveModuleNameFromJarFileName(file); + } + + return moduleName; + } + + /** + * if the jar is multi-release, there will be a set versions + * under the path META-INF/versions/; + * each version will have its own module-info.class if this is a modular jar; + * look for the module name in the module-info from the latest version + * fewer than or equal to the current JVM version + * + * @return a {@link StringBuilder} with the {@code META-INF/versions/} if it exists; otherwise null + */ + private static StringBuilder versionDirectoryIfExists(JarFile jarFile) { + Comparator numericOrder = Integer::compareTo; + List versions = jarFile.stream() + .filter(je -> je.getName().startsWith(META_INF_VERSIONS_PREFIX) && je.getName().endsWith("/module-info.class")) + .map( + je -> Integer.parseInt( + je.getName().substring(META_INF_VERSIONS_PREFIX.length(), je.getName().length() - META_INF_VERSIONS_PREFIX.length()) + ) + ) + .sorted(numericOrder.reversed()) + .toList(); + int major = Runtime.version().feature(); + StringBuilder path = new StringBuilder(META_INF_VERSIONS_PREFIX); + for (int version : versions) { + if (version <= major) { + return path.append(version); + } + } + return null; + } + + /** + * Looks into the specified {@code module-info.class} file, if it exists, and extracts the declared name of the module. + * @return the module name, or null if there is no such {@code module-info.class} file. + */ + private String getModuleNameFromModuleInfoFile(String moduleInfoFileName, JarFile jarFile) throws IOException { + JarEntry moduleEntry = jarFile.getJarEntry(moduleInfoFileName); + if (moduleEntry != null) { + try (InputStream inputStream = jarFile.getInputStream(moduleEntry)) { + return extractModuleNameFromModuleInfo(inputStream); + } + } + return null; + } + + /** + * Looks into the {@code MANIFEST.MF} file and returns the {@code Automatic-Module-Name} value if there is one. + * @return the module name, or null if the manifest is nonexistent or has no {@code Automatic-Module-Name} value + */ + private static String getAutomaticModuleNameFromManifest(JarFile jarFile) throws IOException { + JarEntry manifestEntry = jarFile.getJarEntry("META-INF/MANIFEST.MF"); + if (manifestEntry != null) { + try (InputStream inputStream = jarFile.getInputStream(manifestEntry)) { + Manifest manifest = new Manifest(inputStream); + String amn = manifest.getMainAttributes().getValue("Automatic-Module-Name"); + if (amn != null) { + return amn; + } + } + } + return null; + } + + /** + * Compose a module name from the given {@code jarFile} name, + * as documented in {@link java.lang.module.ModuleFinder#of}. + */ + private static @NotNull String deriveModuleNameFromJarFileName(File jarFile) { + String jn = jarFile.getName().substring(0, jarFile.getName().length() - JAR_DESCRIPTOR_SUFFIX.length()); + Matcher matcher = Pattern.compile("-(\\d+(\\.|$))").matcher(jn); + if (matcher.find()) { + jn = jn.substring(0, matcher.start()); + } + jn = jn.replaceAll("[^A-Za-z0-9]", "."); + return jn; + } + + /** + * find the first class and module when the class path entry is a directory + */ + private void extractLocationsFromDirectory(File dir, List locations) throws IOException { + String className = extractClassNameFromDirectory(dir); + String moduleName = extractModuleNameFromDirectory(dir); + + if (className != null && moduleName != null) { + locations.add(new Location(moduleName, className)); + } + } + + /** + * look through the directory to find the first unique class that isn't + * module-info.class (which may not be unique) and avoid anonymous classes + */ + private String extractClassNameFromDirectory(File dir) throws IOException { + var visitor = new SimpleFileVisitor() { + String result = null; + + @Override + public @NotNull FileVisitResult visitFile(@NotNull Path candidate, @NotNull BasicFileAttributes attrs) { + String name = candidate.getFileName().toString(); // Just the part after the last dir separator + if (name.endsWith(".class") && (name.equals("module-info.class") || name.contains("$")) == false) { + result = candidate.toAbsolutePath() + .toString() + .substring(dir.getAbsolutePath().length() + 1) + .replace(File.separatorChar, '/'); + return TERMINATE; + } else { + return CONTINUE; + } + } + }; + Files.walkFileTree(dir.toPath(), visitor); + return visitor.result; + } + + /** + * look through the directory to find the module name in either module-info.class + * if it exists or the preset one derived from the jar task + */ + private String extractModuleNameFromDirectory(File dir) throws IOException { + var visitor = new SimpleFileVisitor() { + private String result = getModuleName().getOrNull(); + + @Override + public @NotNull FileVisitResult visitFile(@NotNull Path candidate, @NotNull BasicFileAttributes attrs) throws IOException { + String name = candidate.getFileName().toString(); // Just the part after the last dir separator + if (name.equals("module-info.class")) { + try (InputStream inputStream = new FileInputStream(candidate.toFile())) { + result = extractModuleNameFromModuleInfo(inputStream); + return TERMINATE; + } + } else { + return CONTINUE; + } + } + }; + Files.walkFileTree(dir.toPath(), visitor); + return visitor.result; + } + + /** + * a helper method to extract the module name from module-info.class + * using an ASM ClassVisitor + */ + private String extractModuleNameFromModuleInfo(InputStream inputStream) throws IOException { + String[] moduleName = new String[1]; + ClassReader cr = new ClassReader(inputStream); + cr.accept(new ClassVisitor(Opcodes.ASM9) { + @Override + public ModuleVisitor visitModule(String name, int access, String version) { + moduleName[0] = name; + return super.visitModule(name, access, version); + } + }, Opcodes.ASM9); + return moduleName[0]; + } +} diff --git a/build-tools/src/main/java/org/elasticsearch/gradle/plugin/PluginBuildPlugin.java b/build-tools/src/main/java/org/elasticsearch/gradle/plugin/PluginBuildPlugin.java index d5fec104c063e..667bed7688543 100644 --- a/build-tools/src/main/java/org/elasticsearch/gradle/plugin/PluginBuildPlugin.java +++ b/build-tools/src/main/java/org/elasticsearch/gradle/plugin/PluginBuildPlugin.java @@ -10,11 +10,16 @@ package org.elasticsearch.gradle.plugin; import org.elasticsearch.gradle.VersionProperties; +import org.elasticsearch.gradle.test.TestBuildInfoPlugin; import org.gradle.api.Plugin; import org.gradle.api.Project; import org.gradle.api.file.RegularFile; import org.gradle.api.provider.Provider; import org.gradle.api.provider.ProviderFactory; +import org.gradle.jvm.tasks.Jar; +import org.gradle.language.jvm.tasks.ProcessResources; + +import java.util.concurrent.Callable; import javax.inject.Inject; @@ -33,6 +38,7 @@ public PluginBuildPlugin(ProviderFactory providerFactory) { @Override public void apply(final Project project) { project.getPluginManager().apply(BasePluginBuildPlugin.class); + project.getPluginManager().apply(TestBuildInfoPlugin.class); var dependencies = project.getDependencies(); dependencies.add("compileOnly", "org.elasticsearch:elasticsearch:" + VersionProperties.getElasticsearch()); @@ -51,6 +57,30 @@ public void apply(final Project project) { task.getOutputFile().set(file); }); - } + project.getTasks().withType(GenerateTestBuildInfoTask.class).named("generateTestBuildInfo").configure(task -> { + var jarTask = project.getTasks().withType(Jar.class).named("jar").get(); + String moduleName = (String) jarTask.getManifest().getAttributes().get("Automatic-Module-Name"); + if (moduleName == null) { + moduleName = jarTask.getArchiveBaseName().getOrNull(); + } + if (moduleName != null) { + task.getModuleName().set(moduleName); + } + var propertiesExtension = project.getExtensions().getByType(PluginPropertiesExtension.class); + task.getComponentName().set(providerFactory.provider(propertiesExtension::getName)); + task.getOutputFile().set(project.getLayout().getBuildDirectory().file("generated-build-info/plugin-test-build-info.json")); + }); + project.getTasks().withType(ProcessResources.class).named("processResources").configure(task -> { + task.into( + (Callable) () -> "META-INF/es-plugins/" + + project.getExtensions().getByType(PluginPropertiesExtension.class).getName() + + "/", + copy -> { + copy.from(project.getTasks().withType(GeneratePluginPropertiesTask.class).named("pluginProperties")); + copy.from(project.getLayout().getProjectDirectory().file("src/main/plugin-metadata/entitlement-policy.yaml")); + } + ); + }); + } } diff --git a/build-tools/src/main/java/org/elasticsearch/gradle/test/TestBuildInfoPlugin.java b/build-tools/src/main/java/org/elasticsearch/gradle/test/TestBuildInfoPlugin.java new file mode 100644 index 0000000000000..3cab57a333d2c --- /dev/null +++ b/build-tools/src/main/java/org/elasticsearch/gradle/test/TestBuildInfoPlugin.java @@ -0,0 +1,57 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the "Elastic License + * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side + * Public License v 1"; you may not use this file except in compliance with, at + * your election, the "Elastic License 2.0", the "GNU Affero General Public + * License v3.0 only", or the "Server Side Public License, v 1". + */ + +package org.elasticsearch.gradle.test; + +import org.elasticsearch.gradle.dependencies.CompileOnlyResolvePlugin; +import org.elasticsearch.gradle.plugin.GenerateTestBuildInfoTask; +import org.gradle.api.Plugin; +import org.gradle.api.Project; +import org.gradle.api.artifacts.Configuration; +import org.gradle.api.file.FileCollection; +import org.gradle.api.provider.ProviderFactory; +import org.gradle.api.tasks.SourceSet; +import org.gradle.api.tasks.SourceSetContainer; +import org.gradle.language.jvm.tasks.ProcessResources; + +import javax.inject.Inject; + +/** + * This plugin configures the {@link GenerateTestBuildInfoTask} task + * with customizations for component name and output file name coming + * from the source using the plugin (server or ES plugin). + */ +public class TestBuildInfoPlugin implements Plugin { + + protected final ProviderFactory providerFactory; + + @Inject + public TestBuildInfoPlugin(ProviderFactory providerFactory) { + this.providerFactory = providerFactory; + } + + @Override + public void apply(Project project) { + var testBuildInfoTask = project.getTasks().register("generateTestBuildInfo", GenerateTestBuildInfoTask.class, task -> { + FileCollection codeLocations = project.getConfigurations().getByName("runtimeClasspath"); + Configuration compileOnly = project.getConfigurations() + .findByName(CompileOnlyResolvePlugin.RESOLVEABLE_COMPILE_ONLY_CONFIGURATION_NAME); + if (compileOnly != null) { + codeLocations = codeLocations.minus(compileOnly); + } + var sourceSets = project.getExtensions().getByType(SourceSetContainer.class); + codeLocations = codeLocations.plus(sourceSets.getByName(SourceSet.MAIN_SOURCE_SET_NAME).getOutput().getClassesDirs()); + task.getCodeLocations().set(codeLocations); + }); + + project.getTasks().withType(ProcessResources.class).named("processResources").configure(task -> { + task.into("META-INF", copy -> copy.from(testBuildInfoTask)); + }); + } +} diff --git a/build-tools/src/main/java/org/elasticsearch/gradle/testclusters/RunTask.java b/build-tools/src/main/java/org/elasticsearch/gradle/testclusters/RunTask.java index 07f88151a5154..0d981e8e5d17c 100644 --- a/build-tools/src/main/java/org/elasticsearch/gradle/testclusters/RunTask.java +++ b/build-tools/src/main/java/org/elasticsearch/gradle/testclusters/RunTask.java @@ -46,7 +46,7 @@ public abstract class RunTask extends DefaultTestClustersTask { private Boolean apmServerEnabled = false; - private List plugins = List.of(); + private List plugins; private Boolean preserveData = false; @@ -115,7 +115,12 @@ public void setPlugins(String plugins) { } } + public void setPlugins(List plugins) { + this.plugins = plugins; + } + @Input + @Optional public List getPlugins() { return plugins; } diff --git a/catalog-info.yaml b/catalog-info.yaml index b001eee61e699..0768e1670666f 100644 --- a/catalog-info.yaml +++ b/catalog-info.yaml @@ -263,3 +263,41 @@ spec: Daily: branch: main cronline: "0 12 * * * America/New_York" +--- +# yaml-language-server: $schema=https://gist.githubusercontent.com/elasticmachine/988b80dae436cafea07d9a4a460a011d/raw/e57ee3bed7a6f73077a3f55a38e76e40ec87a7cf/rre.schema.json +apiVersion: backstage.io/v1alpha1 +kind: Resource +metadata: + name: buildkite-pipeline-elasticsearch-periodic-micro-benchmarks + description: Runs periodic micro benchmarks fom the main branch + links: + - title: Pipeline + url: https://buildkite.com/elastic/elasticsearch-periodic-micro-benchmarks +spec: + type: buildkite-pipeline + system: buildkite + owner: group:elasticsearch-team + implementation: + apiVersion: buildkite.elastic.dev/v1 + kind: Pipeline + metadata: + description: ":elasticsearch: Runs nightly micro benchmarks fom the main branch" + name: elasticsearch / periodic / micro-benchmarks + spec: + repository: elastic/elasticsearch + pipeline_file: .buildkite/pipelines/periodic-micro-benchmarks.yml + branch_configuration: main + teams: + elasticsearch-team: {} + ml-core: {} + everyone: + access_level: BUILD_AND_READ + provider_settings: + build_branches: false + build_pull_requests: false + publish_commit_status: false + trigger_mode: none + schedules: + Daily: + branch: main + cronline: "@daily" diff --git a/distribution/docker/src/docker/Dockerfile b/distribution/docker/src/docker/Dockerfile index 26ebe19022246..4cb4e9fe008f3 100644 --- a/distribution/docker/src/docker/Dockerfile +++ b/distribution/docker/src/docker/Dockerfile @@ -22,7 +22,7 @@ <% if (docker_base == 'iron_bank') { %> ARG BASE_REGISTRY=registry1.dso.mil ARG BASE_IMAGE=ironbank/redhat/ubi/ubi9 -ARG BASE_TAG=9.5 +ARG BASE_TAG=9.6 <% } %> ################################################################################ diff --git a/distribution/docker/src/docker/dockerfiles/cloud_ess_fips/Dockerfile b/distribution/docker/src/docker/dockerfiles/cloud_ess_fips/Dockerfile index cd190776da0d0..66bc9198d68d4 100644 --- a/distribution/docker/src/docker/dockerfiles/cloud_ess_fips/Dockerfile +++ b/distribution/docker/src/docker/dockerfiles/cloud_ess_fips/Dockerfile @@ -24,7 +24,7 @@ # Extract Elasticsearch artifact ################################################################################ -FROM docker.elastic.co/wolfi/chainguard-base-fips:latest@sha256:ebfc3f1d7dba992231747a2e05ad1b859843e81b5e676ad342859d7cf9e425a7 AS builder +FROM docker.elastic.co/wolfi/chainguard-base-fips:latest@sha256:68e0781cd592beda39880428985d5fecca1cf2abb18365da73bf1f7ebd994974 AS builder # Install required packages to extract the Elasticsearch distribution RUN <%= retry.loop(package_manager, "export DEBIAN_FRONTEND=noninteractive && ${package_manager} update && ${package_manager} update && ${package_manager} add --no-cache curl") %> @@ -103,7 +103,7 @@ WORKDIR /usr/share/elasticsearch/config # Add entrypoint ################################################################################ -FROM docker.elastic.co/wolfi/chainguard-base-fips:latest@sha256:ebfc3f1d7dba992231747a2e05ad1b859843e81b5e676ad342859d7cf9e425a7 +FROM docker.elastic.co/wolfi/chainguard-base-fips:latest@sha256:68e0781cd592beda39880428985d5fecca1cf2abb18365da73bf1f7ebd994974 RUN <%= retry.loop(package_manager, "export DEBIAN_FRONTEND=noninteractive && \n" + diff --git a/distribution/docker/src/docker/dockerfiles/wolfi/Dockerfile b/distribution/docker/src/docker/dockerfiles/wolfi/Dockerfile index 8d6e090dbdaac..edb6fd2b3e265 100644 --- a/distribution/docker/src/docker/dockerfiles/wolfi/Dockerfile +++ b/distribution/docker/src/docker/dockerfiles/wolfi/Dockerfile @@ -24,7 +24,7 @@ # Extract Elasticsearch artifact ################################################################################ -FROM docker.elastic.co/wolfi/chainguard-base:latest@sha256:29150cd940cc7f69407d978d5a19c86f4d9e67cf44e4d6ded787a497e8f27c9a AS builder +FROM docker.elastic.co/wolfi/chainguard-base:latest@sha256:3d19648819612728a676ab4061edfb3283bd7117a22c6c4479ee1c1d51831832 AS builder # Install required packages to extract the Elasticsearch distribution RUN <%= retry.loop(package_manager, "export DEBIAN_FRONTEND=noninteractive && ${package_manager} update && ${package_manager} update && ${package_manager} add --no-cache curl") %> @@ -79,7 +79,7 @@ RUN sed -i -e 's/ES_DISTRIBUTION_TYPE=tar/ES_DISTRIBUTION_TYPE=docker/' bin/elas # Add entrypoint ################################################################################ -FROM docker.elastic.co/wolfi/chainguard-base:latest@sha256:29150cd940cc7f69407d978d5a19c86f4d9e67cf44e4d6ded787a497e8f27c9a +FROM docker.elastic.co/wolfi/chainguard-base:latest@sha256:3d19648819612728a676ab4061edfb3283bd7117a22c6c4479ee1c1d51831832 RUN <%= retry.loop(package_manager, "export DEBIAN_FRONTEND=noninteractive && \n" + diff --git a/docs/changelog/124825.yaml b/docs/changelog/124825.yaml new file mode 100644 index 0000000000000..413695a5ae641 --- /dev/null +++ b/docs/changelog/124825.yaml @@ -0,0 +1,5 @@ +pr: 124825 +summary: Check alias during update +area: Transform +type: bug +issues: [] diff --git a/docs/changelog/125408.yaml b/docs/changelog/125408.yaml new file mode 100644 index 0000000000000..3333bbc3ef9f4 --- /dev/null +++ b/docs/changelog/125408.yaml @@ -0,0 +1,6 @@ +pr: 125408 +summary: Prevent ML data retention logic from failing when deleting documents in read-only + indices +area: Machine Learning +type: bug +issues: [] diff --git a/docs/changelog/126581.yaml b/docs/changelog/126581.yaml new file mode 100644 index 0000000000000..53fcb8a6057b3 --- /dev/null +++ b/docs/changelog/126581.yaml @@ -0,0 +1,10 @@ +pr: 126581 +summary: "Optimize shared blob cache evictions on shard removal + Shared blob cache evictions occur on the cluster applier thread when shards are + removed from a node. These can be expensive if a large number of shards are + being removed. This change uses the context of the removal to avoid unnecessary + evictions that might hold up the applier thread. + " +area: Snapshot/Restore +type: enhancement +issues: [] diff --git a/docs/changelog/126992.yaml b/docs/changelog/126992.yaml deleted file mode 100644 index e5f8ba5ed9c54..0000000000000 --- a/docs/changelog/126992.yaml +++ /dev/null @@ -1,6 +0,0 @@ -pr: 126992 -summary: Add missing `outbound_network` entitlement to x-pack-core -area: Infra/Core -type: bug -issues: - - 127003 diff --git a/docs/changelog/127337.yaml b/docs/changelog/127337.yaml deleted file mode 100644 index c9c2ab744544f..0000000000000 --- a/docs/changelog/127337.yaml +++ /dev/null @@ -1,6 +0,0 @@ -pr: 127337 -summary: Http proxy support in JWT realm -area: Authentication -type: enhancement -issues: - - 114956 diff --git a/docs/changelog/127371.yaml b/docs/changelog/127371.yaml new file mode 100644 index 0000000000000..10f5f17243193 --- /dev/null +++ b/docs/changelog/127371.yaml @@ -0,0 +1,6 @@ +pr: 127371 +summary: Add cancellation support in `TransportGetAllocationStatsAction` +area: Allocation +type: feature +issues: + - 123248 diff --git a/docs/changelog/127475.yaml b/docs/changelog/127475.yaml deleted file mode 100644 index 0398fda30b014..0000000000000 --- a/docs/changelog/127475.yaml +++ /dev/null @@ -1,5 +0,0 @@ -pr: 127475 -summary: Remove dangling spaces wherever found -area: Security -type: bug -issues: [] diff --git a/docs/changelog/127549.yaml b/docs/changelog/127549.yaml new file mode 100644 index 0000000000000..5f24111d22689 --- /dev/null +++ b/docs/changelog/127549.yaml @@ -0,0 +1,5 @@ +pr: 127549 +summary: Add local optimizations for `constant_keyword` +area: ES|QL +type: enhancement +issues: [] diff --git a/docs/changelog/127563.yaml b/docs/changelog/127563.yaml new file mode 100644 index 0000000000000..1e88e9d487b25 --- /dev/null +++ b/docs/changelog/127563.yaml @@ -0,0 +1,6 @@ +pr: 127563 +summary: "ESQL: Avoid unintended attribute removal" +area: ES|QL +type: bug +issues: + - 127468 diff --git a/docs/changelog/127564.yaml b/docs/changelog/127564.yaml new file mode 100644 index 0000000000000..4604763542b57 --- /dev/null +++ b/docs/changelog/127564.yaml @@ -0,0 +1,6 @@ +pr: 127564 +summary: Consider inlinestats when having `field_caps` check for field names +area: ES|QL +type: bug +issues: + - 127236 diff --git a/docs/changelog/127583.yaml b/docs/changelog/127583.yaml new file mode 100644 index 0000000000000..6e315a2b827b9 --- /dev/null +++ b/docs/changelog/127583.yaml @@ -0,0 +1,6 @@ +pr: 127583 +summary: Add optimization to purge join on null merge key +area: ES|QL +type: enhancement +issues: + - 125577 diff --git a/docs/changelog/127628.yaml b/docs/changelog/127628.yaml new file mode 100644 index 0000000000000..083b425f13eb4 --- /dev/null +++ b/docs/changelog/127628.yaml @@ -0,0 +1,5 @@ +pr: 127628 +summary: Ensure config reload on ..data symlink switch for CSI driver support +area: Infra/Settings +type: enhancement +issues: [] diff --git a/docs/changelog/127658.yaml b/docs/changelog/127658.yaml deleted file mode 100644 index 1a8d5ced7c8b6..0000000000000 --- a/docs/changelog/127658.yaml +++ /dev/null @@ -1,5 +0,0 @@ -pr: 127658 -summary: Append all data to Chat Completion buffer -area: Machine Learning -type: bug -issues: [] diff --git a/docs/changelog/127687.yaml b/docs/changelog/127687.yaml new file mode 100644 index 0000000000000..e053c4a31ad2e --- /dev/null +++ b/docs/changelog/127687.yaml @@ -0,0 +1,6 @@ +pr: 127687 +summary: "ESQL: Fix alias removal in regex extraction with JOIN" +area: ES|QL +type: bug +issues: + - 127467 diff --git a/docs/changelog/127731.yaml b/docs/changelog/127731.yaml new file mode 100644 index 0000000000000..2641c96e2e05b --- /dev/null +++ b/docs/changelog/127731.yaml @@ -0,0 +1,5 @@ +pr: 127731 +summary: ESQL - Enable telemetry for COMPLETION command +area: Search +type: feature +issues: [] diff --git a/docs/changelog/127752.yaml b/docs/changelog/127752.yaml deleted file mode 100644 index b4721af3431a7..0000000000000 --- a/docs/changelog/127752.yaml +++ /dev/null @@ -1,6 +0,0 @@ -pr: 127752 -summary: Downsampling does not consider passthrough fields as dimensions -area: Downsampling -type: bug -issues: - - 125156 diff --git a/docs/changelog/127767.yaml b/docs/changelog/127767.yaml new file mode 100644 index 0000000000000..659fc31fbaf83 --- /dev/null +++ b/docs/changelog/127767.yaml @@ -0,0 +1,5 @@ +pr: 127767 +summary: Integrate `OpenAi` Chat Completion in `SageMaker` +area: Machine Learning +type: enhancement +issues: [] diff --git a/docs/changelog/127798.yaml b/docs/changelog/127798.yaml deleted file mode 100644 index f9f2ceb93b4f1..0000000000000 --- a/docs/changelog/127798.yaml +++ /dev/null @@ -1,5 +0,0 @@ -pr: 127798 -summary: Handle streaming request body in audit log -area: Audit -type: bug -issues: [] diff --git a/docs/changelog/127824.yaml b/docs/changelog/127824.yaml deleted file mode 100644 index 6868f3c39297a..0000000000000 --- a/docs/changelog/127824.yaml +++ /dev/null @@ -1,6 +0,0 @@ -pr: 127824 -summary: Skip the validation when retrieving the index mode during reindexing a time - series data stream -area: TSDB -type: bug -issues: [] diff --git a/docs/changelog/127856.yaml b/docs/changelog/127856.yaml deleted file mode 100644 index bdd7657a58e73..0000000000000 --- a/docs/changelog/127856.yaml +++ /dev/null @@ -1,5 +0,0 @@ -pr: 127856 -summary: Fix services API Google Vertex AI Rerank location field requirement -area: Machine Learning -type: bug -issues: [] diff --git a/docs/changelog/127877.yaml b/docs/changelog/127877.yaml deleted file mode 100644 index 58f2504e41c33..0000000000000 --- a/docs/changelog/127877.yaml +++ /dev/null @@ -1,5 +0,0 @@ -pr: 127877 -summary: Check hidden frames in entitlements -area: Infra/Core -type: bug -issues: [] diff --git a/docs/changelog/127924.yaml b/docs/changelog/127924.yaml new file mode 100644 index 0000000000000..4aaaa710563ab --- /dev/null +++ b/docs/changelog/127924.yaml @@ -0,0 +1,5 @@ +pr: 127924 +summary: Limit Replace function memory usage +area: ES|QL +type: enhancement +issues: [] diff --git a/docs/changelog/127939.yaml b/docs/changelog/127939.yaml new file mode 100644 index 0000000000000..7cc67e6207a85 --- /dev/null +++ b/docs/changelog/127939.yaml @@ -0,0 +1,5 @@ +pr: 127939 +summary: Add Custom inference service +area: Machine Learning +type: enhancement +issues: [] diff --git a/docs/changelog/127949.yaml b/docs/changelog/127949.yaml deleted file mode 100644 index 82a8b65fc9ec4..0000000000000 --- a/docs/changelog/127949.yaml +++ /dev/null @@ -1,5 +0,0 @@ -pr: 127949 -summary: Ensure ordinal builder emit ordinal blocks -area: ES|QL -type: bug -issues: [] diff --git a/docs/changelog/127966.yaml b/docs/changelog/127966.yaml new file mode 100644 index 0000000000000..0c896715149bf --- /dev/null +++ b/docs/changelog/127966.yaml @@ -0,0 +1,5 @@ +pr: 127966 +summary: "[ML] Add Rerank support to the Inference Plugin" +area: Machine Learning +type: enhancement +issues: [] diff --git a/docs/changelog/127975.yaml b/docs/changelog/127975.yaml deleted file mode 100644 index 35a76a2474a34..0000000000000 --- a/docs/changelog/127975.yaml +++ /dev/null @@ -1,5 +0,0 @@ -pr: 127975 -summary: Fix a bug in `significant_terms` -area: Aggregations -type: bug -issues: [] diff --git a/docs/changelog/127991.yaml b/docs/changelog/127991.yaml deleted file mode 100644 index dead04164ccab..0000000000000 --- a/docs/changelog/127991.yaml +++ /dev/null @@ -1,6 +0,0 @@ -pr: 127991 -summary: Avoid nested docs in painless execute api -area: Infra/Scripting -type: bug -issues: - - 41004 diff --git a/docs/changelog/128043.yaml b/docs/changelog/128043.yaml deleted file mode 100644 index 90c2a538d03ca..0000000000000 --- a/docs/changelog/128043.yaml +++ /dev/null @@ -1,19 +0,0 @@ -pr: 128043 -summary: Make S3 custom query parameter optional -area: Snapshot/Restore -type: breaking -issues: [] -breaking: - title: Make S3 custom query parameter optional - area: Cluster and node setting - details: >- - Earlier versions of Elasticsearch would record the purpose of each S3 API - call using the `?x-purpose=` custom query parameter. This isn't believed to - be necessary outside of the ECH/ECE/ECK/... managed services, and it adds - rather a lot to the request logs, so with this change we make the feature - optional and disabled by default. - impact: >- - If you wish to reinstate the old behaviour on a S3 repository, set - `s3.client.${CLIENT_NAME}.add_purpose_custom_query_parameter` to `true` - for the relevant client. - notable: false diff --git a/docs/changelog/128047.yaml b/docs/changelog/128047.yaml deleted file mode 100644 index fb3d58794afbd..0000000000000 --- a/docs/changelog/128047.yaml +++ /dev/null @@ -1,6 +0,0 @@ -pr: 128047 -summary: Add missing entitlement to `repository-azure` -area: Snapshot/Restore -type: bug -issues: - - 128046 diff --git a/docs/changelog/128099.yaml b/docs/changelog/128099.yaml new file mode 100644 index 0000000000000..1f26cb00bd75d --- /dev/null +++ b/docs/changelog/128099.yaml @@ -0,0 +1,5 @@ +pr: 128099 +summary: Remove first `FlowControlHandler` from HTTP pipeline +area: Network +type: enhancement +issues: [] diff --git a/docs/changelog/128105.yaml b/docs/changelog/128105.yaml new file mode 100644 index 0000000000000..2dd6b55f54d24 --- /dev/null +++ b/docs/changelog/128105.yaml @@ -0,0 +1,5 @@ +pr: 128105 +summary: "Adding Google VertexAI chat completion integration" +area: Inference +type: enhancement +issues: [ ] diff --git a/docs/changelog/128111.yaml b/docs/changelog/128111.yaml deleted file mode 100644 index d3b113a682d4a..0000000000000 --- a/docs/changelog/128111.yaml +++ /dev/null @@ -1,5 +0,0 @@ -pr: 128111 -summary: Fix union types in CCS -area: ES|QL -type: bug -issues: [] diff --git a/docs/changelog/128139.yaml b/docs/changelog/128139.yaml new file mode 100644 index 0000000000000..b21e2c744f4d9 --- /dev/null +++ b/docs/changelog/128139.yaml @@ -0,0 +1,5 @@ +pr: 128139 +summary: Skip indexing points for `seq_no` in tsdb and logsdb +area: Mapping +type: enhancement +issues: [] diff --git a/docs/changelog/128163.yaml b/docs/changelog/128163.yaml new file mode 100644 index 0000000000000..6cebf3738017f --- /dev/null +++ b/docs/changelog/128163.yaml @@ -0,0 +1,17 @@ +pr: 128163 +summary: Make `skip_unavailable` catch all errors +area: ES|QL +type: breaking +issues: [ ] +breaking: + title: Cluster setting "skip_unavailable" catches all runtime errors + area: ES|QL + details: "If `skip_unavailable` is set to `true`, the runtime errors from this cluster\ + \ do not lead to a failure of the query. Instead, the cluster is set to `skipped`\ + \ or `partial` status, and the query execution continues. This is a breaking change\ + \ from previous versions, where `skip_unavailable` only applied to errors related\ + \ to a cluster being unavailable." + impact: "The errors on remote clusters, e.g. missing indices, will not lead to a\ + \ failure of the query. Instead, the cluster is set to `skipped` or `partial` status\ + \ in the response metadata." + notable: false diff --git a/docs/changelog/128213.yaml b/docs/changelog/128213.yaml new file mode 100644 index 0000000000000..a1f108cbbec8e --- /dev/null +++ b/docs/changelog/128213.yaml @@ -0,0 +1,5 @@ +pr: 128213 +summary: Refactor `SourceProvider` creation to consistently use `MappingLookup` +area: Mapping +type: enhancement +issues: [] diff --git a/docs/changelog/128218.yaml b/docs/changelog/128218.yaml new file mode 100644 index 0000000000000..a3a291aa8d580 --- /dev/null +++ b/docs/changelog/128218.yaml @@ -0,0 +1,5 @@ +pr: 128218 +summary: Improve exception for trained model deployment scale up timeout +area: Machine Learning +type: enhancement +issues: [] diff --git a/docs/changelog/128241.yaml b/docs/changelog/128241.yaml new file mode 100644 index 0000000000000..26e3154fb7fde --- /dev/null +++ b/docs/changelog/128241.yaml @@ -0,0 +1,5 @@ +pr: 128241 +summary: Adding VoyageAI's v3.5 models +area: Machine Learning +type: enhancement +issues: [] diff --git a/docs/changelog/128259.yaml b/docs/changelog/128259.yaml new file mode 100644 index 0000000000000..8c30b7cd1d021 --- /dev/null +++ b/docs/changelog/128259.yaml @@ -0,0 +1,6 @@ +pr: 128259 +summary: Added geometry validation for GEO types to exit early on invalid latitudes +area: Geo +type: bug +issues: + - 128234 diff --git a/docs/changelog/128260.yaml b/docs/changelog/128260.yaml new file mode 100644 index 0000000000000..059e514685601 --- /dev/null +++ b/docs/changelog/128260.yaml @@ -0,0 +1,7 @@ +pr: 128260 +summary: Fix validation NPE in Enrich and add extra @Nullable annotations +area: ES|QL +type: bug +issues: + - 126297 + - 126253 diff --git a/docs/changelog/128263.yaml b/docs/changelog/128263.yaml new file mode 100644 index 0000000000000..27ed06878dd40 --- /dev/null +++ b/docs/changelog/128263.yaml @@ -0,0 +1,5 @@ +pr: 128263 +summary: Allow lookup join on mixed numeric fields +area: ES|QL +type: enhancement +issues: [] diff --git a/docs/changelog/128273.yaml b/docs/changelog/128273.yaml new file mode 100644 index 0000000000000..0f6a7ce2561d7 --- /dev/null +++ b/docs/changelog/128273.yaml @@ -0,0 +1,5 @@ +pr: 128273 +summary: Improve get-snapshots message for unreadable repository +area: Snapshot/Restore +type: enhancement +issues: [] diff --git a/docs/changelog/128278.yaml b/docs/changelog/128278.yaml new file mode 100644 index 0000000000000..e8cc008a393df --- /dev/null +++ b/docs/changelog/128278.yaml @@ -0,0 +1,5 @@ +pr: 128278 +summary: ROUND_TO function +area: ES|QL +type: enhancement +issues: [] diff --git a/docs/changelog/128293.yaml b/docs/changelog/128293.yaml new file mode 100644 index 0000000000000..92181f0b46704 --- /dev/null +++ b/docs/changelog/128293.yaml @@ -0,0 +1,5 @@ +pr: 128293 +summary: Use `IndexOrDocValuesQuery` in `NumberFieldType#termQuery` implementations +area: Search +type: enhancement +issues: [] diff --git a/docs/changelog/128298.yaml b/docs/changelog/128298.yaml new file mode 100644 index 0000000000000..bfa16cb509304 --- /dev/null +++ b/docs/changelog/128298.yaml @@ -0,0 +1,6 @@ +pr: 128298 +summary: Better handling of node ids from shutdown metadata (avoid NPE on already removed nodes) +area: Infra/Node Lifecycle +type: bug +issues: + - 100201 diff --git a/docs/changelog/128314.yaml b/docs/changelog/128314.yaml new file mode 100644 index 0000000000000..f63a06e68177e --- /dev/null +++ b/docs/changelog/128314.yaml @@ -0,0 +1,5 @@ +pr: 128314 +summary: Fix NPE in APMTracer through `RestController` +area: Infra/REST API +type: bug +issues: [] diff --git a/docs/changelog/128320.yaml b/docs/changelog/128320.yaml new file mode 100644 index 0000000000000..ecd575d1ce93f --- /dev/null +++ b/docs/changelog/128320.yaml @@ -0,0 +1,5 @@ +pr: 128320 +summary: Use new source loader when lower `docId` is accessed +area: Codec +type: bug +issues: [] diff --git a/docs/changelog/128323.yaml b/docs/changelog/128323.yaml new file mode 100644 index 0000000000000..b6114c26ddc6e --- /dev/null +++ b/docs/changelog/128323.yaml @@ -0,0 +1,5 @@ +pr: 128323 +summary: "Fix: Allow non-score secondary sorts in pinned retriever sub-retrievers" +area: Relevance +type: bug +issues: [] diff --git a/docs/changelog/128338.yaml b/docs/changelog/128338.yaml new file mode 100644 index 0000000000000..28b8ba49ff054 --- /dev/null +++ b/docs/changelog/128338.yaml @@ -0,0 +1,5 @@ +pr: 128338 +summary: Pass timeout to chat completion +area: Machine Learning +type: bug +issues: [] diff --git a/docs/changelog/128362.yaml b/docs/changelog/128362.yaml new file mode 100644 index 0000000000000..89a59a18f645a --- /dev/null +++ b/docs/changelog/128362.yaml @@ -0,0 +1,5 @@ +pr: 128362 +summary: Avoid unnecessary determinization in index pattern conflict checks +area: Indices APIs +type: bug +issues: [] diff --git a/docs/changelog/128393.yaml b/docs/changelog/128393.yaml new file mode 100644 index 0000000000000..1f4a2bf8697f3 --- /dev/null +++ b/docs/changelog/128393.yaml @@ -0,0 +1,6 @@ +pr: 128393 +summary: Pushdown constructs doing case-insensitive regexes +area: ES|QL +type: enhancement +issues: + - 127479 diff --git a/docs/changelog/128405.yaml b/docs/changelog/128405.yaml new file mode 100644 index 0000000000000..aefa068814747 --- /dev/null +++ b/docs/changelog/128405.yaml @@ -0,0 +1,5 @@ +pr: 128405 +summary: Modify the mechanism to pause indexing +area: Distributed +type: bug +issues: [] diff --git a/docs/changelog/128449.yaml b/docs/changelog/128449.yaml new file mode 100644 index 0000000000000..12798783942e6 --- /dev/null +++ b/docs/changelog/128449.yaml @@ -0,0 +1,5 @@ +pr: 128449 +summary: "[Draft] Support concurrent multipart uploads in Azure" +area: Snapshot/Restore +type: enhancement +issues: [] diff --git a/docs/changelog/128464.yaml b/docs/changelog/128464.yaml new file mode 100644 index 0000000000000..b8cd59c82b77f --- /dev/null +++ b/docs/changelog/128464.yaml @@ -0,0 +1,5 @@ +pr: 128464 +summary: Add support for parameters in LIMIT command +area: ES|QL +type: enhancement +issues: [] diff --git a/docs/changelog/128473.yaml b/docs/changelog/128473.yaml new file mode 100644 index 0000000000000..447ff998b1610 --- /dev/null +++ b/docs/changelog/128473.yaml @@ -0,0 +1,5 @@ +pr: 128473 +summary: Conditionally force sequential reading in `LuceneSyntheticSourceChangesSnapshot` +area: Logs +type: enhancement +issues: [] diff --git a/docs/changelog/128531.yaml b/docs/changelog/128531.yaml new file mode 100644 index 0000000000000..de4a767136ca7 --- /dev/null +++ b/docs/changelog/128531.yaml @@ -0,0 +1,5 @@ +pr: 128531 +summary: Combine small pages in Limit +area: ES|QL +type: enhancement +issues: [] diff --git a/docs/changelog/128532.yaml b/docs/changelog/128532.yaml new file mode 100644 index 0000000000000..926ad461ba6ed --- /dev/null +++ b/docs/changelog/128532.yaml @@ -0,0 +1,5 @@ +pr: 128532 +summary: "Prevent invalid privileges in manage roles privilege" +area: "Authorization" +type: bug +issues: [127496] diff --git a/docs/changelog/128584.yaml b/docs/changelog/128584.yaml new file mode 100644 index 0000000000000..e5e380559786d --- /dev/null +++ b/docs/changelog/128584.yaml @@ -0,0 +1,5 @@ +pr: 128584 +summary: '`InferenceService` support aliases' +area: Machine Learning +type: enhancement +issues: [] diff --git a/docs/changelog/128615.yaml b/docs/changelog/128615.yaml new file mode 100644 index 0000000000000..9270c701c1bec --- /dev/null +++ b/docs/changelog/128615.yaml @@ -0,0 +1,5 @@ +pr: 128615 +summary: Fix and test off-heap stats when using direct IO for accessing the raw vectors +area: Vector Search +type: bug +issues: [] diff --git a/docs/changelog/128650.yaml b/docs/changelog/128650.yaml new file mode 100644 index 0000000000000..a587f4f2cdf71 --- /dev/null +++ b/docs/changelog/128650.yaml @@ -0,0 +1,6 @@ +pr: 128650 +summary: Update shardGenerations for all indices on snapshot finalization +area: Snapshot/Restore +type: enhancement +issues: + - 108907 diff --git a/docs/docset.yml b/docs/docset.yml index 5281ad753b32d..15bd674a5fb5e 100644 --- a/docs/docset.yml +++ b/docs/docset.yml @@ -1,4 +1,6 @@ project: 'Elasticsearch' +products: + - id: elasticsearch max_toc_depth: 2 exclude: - README.md diff --git a/docs/internal/DistributedArchitectureGuide.md b/docs/internal/DistributedArchitectureGuide.md index 538b3a4af18f3..86364069b692a 100644 --- a/docs/internal/DistributedArchitectureGuide.md +++ b/docs/internal/DistributedArchitectureGuide.md @@ -46,7 +46,7 @@ to communicate with Elasticsearch. (Sketch of important classes? Might inform more sections to add for details.) -(A NodeB can coordinate a search across several other nodes, when NodeB itself does not have the data, and then return a result to the caller. Explain this coordinating role) +(A node can coordinate a search across several other nodes, when the node itself does not have the data, and then return a result to the caller. Explain this coordinating role) ### Node Roles diff --git a/docs/internal/GeneralArchitectureGuide.md b/docs/internal/GeneralArchitectureGuide.md index f0184044527cd..d74490e62e9df 100644 --- a/docs/internal/GeneralArchitectureGuide.md +++ b/docs/internal/GeneralArchitectureGuide.md @@ -2,49 +2,183 @@ # REST and Transport Layers -### REST Layer - -The REST and Transport layers are bound together through the `ActionModule`. `ActionModule#initRestHandlers` registers all the -rest actions with a `RestController` that matches incoming requests to particular REST actions. `RestController#registerHandler` -uses each `Rest*Action`'s `#routes()` implementation to match HTTP requests to that particular `Rest*Action`. Typically, REST -actions follow the class naming convention `Rest*Action`, which makes them easier to find, but not always; the `#routes()` -definition can also be helpful in finding a REST action. `RestController#dispatchRequest` eventually calls `#handleRequest` on a -`RestHandler` implementation. `RestHandler` is the base class for `BaseRestHandler`, which most `Rest*Action` instances extend to -implement a particular REST action. - -`BaseRestHandler#handleRequest` calls into `BaseRestHandler#prepareRequest`, which children `Rest*Action` classes extend to -define the behavior for a particular action. `RestController#dispatchRequest` passes a `RestChannel` to the `Rest*Action` via -`RestHandler#handleRequest`: `Rest*Action#prepareRequest` implementations return a `RestChannelConsumer` defining how to execute -the action and reply on the channel (usually in the form of completing an ActionListener wrapper). `Rest*Action#prepareRequest` -implementations are responsible for parsing the incoming request, and verifying that the structure of the request is valid. -`BaseRestHandler#handleRequest` will then check that all the request parameters have been consumed: unexpected request parameters -result in an error. - -### How REST Actions Connect to Transport Actions - -The Rest layer uses an implementation of `AbstractClient`. `BaseRestHandler#prepareRequest` takes a `NodeClient`: this client -knows how to connect to a specified TransportAction. A `Rest*Action` implementation will return a `RestChannelConsumer` that -most often invokes a call into a method on the `NodeClient` to pass through to the TransportAction. Along the way from -`BaseRestHandler#prepareRequest` through the `AbstractClient` and `NodeClient` code, `NodeClient#executeLocally` is called: this -method calls into `TaskManager#registerAndExecute`, registering the operation with the `TaskManager` so it can be found in Task -API requests, before moving on to execute the specified TransportAction. - -`NodeClient` has a `NodeClient#actions` map from `ActionType` to `TransportAction`. `ActionModule#setupActions` registers all the -core TransportActions, as well as those defined in any plugins that are being used: plugins can override `Plugin#getActions()` to -define additional TransportActions. Note that not all TransportActions will be mapped back to a REST action: many TransportActions -are only used for internode operations/communications. - -### Transport Layer - -(Managed by the TransportService, TransportActions must be registered there, too) - -(Executing a TransportAction (either locally via NodeClient or remotely via TransportService) is where most of the authorization & other security logic runs) - -(What actions, and why, are registered in TransportService but not NodeClient?) - -### Direct Node to Node Transport Layer - -(TransportService maps incoming requests to TransportActions) +In general, there are two types of network communication used in Elasticsearch: +- External clients interact with the cluster via the public REST API over HTTP connections, this is referred to as the "REST layer" +- Cluster nodes communicate internally using a binary message format over TCP connections, this is referred to as the "Transport layer" + +Cross-cluster [replication](https://www.elastic.co/guide/en/elasticsearch/reference/current/xpack-ccr.html) (CCR) +and [search](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html) (CCS) also use +transport messaging for inter-cluster communication. +More information on CCR/CCS can be found in the [Distributed architecture guide](./DistributedArchitectureGuide.md#cross-cluster-replication-ccr) + +## REST Layer + +### Handler registration + +All REST handlers exposed by Elasticsearch are registered in [ActionModule#initRestHandlers]. This method registers all the +REST actions with the [RestController] using [#registerHandler(...)][RestController#registerHandler]. These registrations populate +a map of [routes][RestHandler#routes] to [RestHandler]s to allow routing of incoming HTTP requests to their respective handlers. +There are many REST endpoints configured statically in [ActionModule][ActionModule#initRestHandlers], and additional +endpoints can be contributed by [ActionPlugin]s by implementing the [getRestHandlers][ActionPlugin#getRestHandlers] method. + +Typically, REST actions follow the class naming convention `Rest*Action`, which makes them easier to find, but not always; the +[#routes()][RestHandler#routes] implementation for each `Rest*Action` can also be helpful in finding a particular REST action. + +When a [RestRequest] is received, [RestController#dispatchRequest] uses the request path to identify the destination handler and calls +[#handleRequest][RestHandler#handleRequest] on it. [BaseRestHandler] is a common base class extended by most `Rest*Action` implementations. + +### Handler invocation + +The usual flow of a REST request being handled is as follows +1. [RestController#dispatchRequest] inspects the [RestRequest] and matches it to a handler using its map of paths to handlers. +2. [BaseRestHandler#handleRequest] performs some basic parameter validation. +3. [BaseRestHandler] calls into [BaseRestHandler#prepareRequest], which `Rest*Action` subclasses implement to define the behavior +for a particular action. [prepareRequest][BaseRestHandler#prepareRequest] processes the request parameters to produce a +[RestChannelConsumer] that is ready to execute the action and return the response on a [RestChannel]. +4. `BaseRestHandler` validates that the handler consumed all the request parameters, throwing an exception if any +were left unconsumed. +5. `BaseRestHandler` then supplies the channel to the [RestChannelConsumer] to begin executing the action. Some handlers, such as the +[RestBulkAction], consume the request as a stream of chunks to allow incremental processing of large requests. +6. The response is written to the `RestChannel`, either as a [single payload][RestToXContentListener] or a +[stream of chunks][RestChunkedToXContentListener]. + +### Request interceptor + +The [RestController] accepts a [RestInterceptor] that can intercept [RestRequest]s and add additional pre-handling. A single +[RestServerActionPlugin] can provide a `RestInterceptor` implementation, through which all requests are passed. The +[Security][Security#getRestHandlerInterceptor] plugin uses this capability to register an interceptor to authorize access to endpoints +that require [operator privileges], populate the [audit logs] and perform some additional authentication when required. + +### HTTP server infrastructure + +HTTP traffic is handled by an implementation of a [HttpServerTransport]. The `HttpServerTransport` is responsible for binding to a +port, handling REST client connections, parsing received requests into [RestRequest] instances and dispatching those +requests to a [HttpServerTransport.Dispatcher]. The [RestController] is an implementation of `HttpServerTransport.Dispatcher`. +The `HttpServerTransport` is pluggable. There is a single [Netty](https://netty.io/)-based implementation +of `HttpServerTransport`, the [Netty4HttpServerTransport], but some plugins, such as `Security`, supply instances of it with +additional configuration to implement features like IP filtering or TLS (see [Security#getHttpTransports]). + +[ActionModule#initRestHandlers]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/action/ActionModule.java#L814 +[ActionModule]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/action/ActionModule.java +[ActionPlugin]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/plugins/ActionPlugin.java +[audit logs]:https://www.elastic.co/docs/deploy-manage/security/logging-configuration/enabling-audit-logs +[BaseRestHandler#handleRequest]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/rest/BaseRestHandler.java#L79 +[BaseRestHandler#prepareRequest]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/rest/BaseRestHandler.java#L247 +[BaseRestHandler]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/rest/BaseRestHandler.java +[HttpServerTransport.Dispatcher]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/http/HttpServerTransport.java#L36 +[HttpServerTransport]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/http/HttpServerTransport.java +[Netty4HttpServerTransport]:https://github.com/elastic/elasticsearch/blob/v9.0.1/modules/transport-netty4/src/main/java/org/elasticsearch/http/netty4/Netty4HttpServerTransport.java +[operator privileges]:https://www.elastic.co/docs/deploy-manage/users-roles/cluster-or-deployment-auth/operator-privileges +[RestBulkAction]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/rest/action/document/RestBulkAction.java +[RestChannelConsumer]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/rest/BaseRestHandler.java#L204 +[RestChannel]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/rest/RestChannel.java +[RestChunkedToXContentListener]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/rest/action/RestChunkedToXContentListener.java +[RestController#dispatchRequest]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/rest/RestController.java#L304 +[RestController#registerHandler]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/rest/RestController.java#L299 +[RestController]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/rest/RestController.java +[RestHandler#handleRequest]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/rest/RestHandler.java#L37 +[RestHandler#routes]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/rest/RestHandler.java#L75 +[RestHandler]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/rest/RestHandler.java +[RestInterceptor]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/rest/RestInterceptor.java +[RestRequest]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/rest/RestRequest.java +[RestServerActionPlugin]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/plugins/interceptor/RestServerActionPlugin.java +[RestToXContentListener]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/rest/action/RestToXContentListener.java +[Route]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/rest/RestHandler.java#L123 +[Security#getHttpTransports]:https://github.com/elastic/elasticsearch/blob/v9.0.1/x-pack/plugin/security/src/main/java/org/elasticsearch/xpack/security/Security.java#L1959 +[Security#getRestHandlerInterceptor]:https://github.com/elastic/elasticsearch/blob/v9.0.1/x-pack/plugin/security/src/main/java/org/elasticsearch/xpack/security/Security.java#L2140 +[TransportAction]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/action/support/TransportAction.java +[ActionPlugin#getRestHandlers]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/plugins/ActionPlugin.java#L76 + +## Transport Layer + +`Rest*Action` implementations typically translate received requests into an [ActionRequest] which is dispatched via the [NodeClient] +passed in by the [RestController]. The [NodeClient] is the entrypoint into the "transport layer" over which internal cluster actions +are coordinated. + +> [!NOTE] +> `Rest*Action` classes usually have a corresponding `Transport*Action`, this naming convention makes it easy to locate the corresponding +> [RestHandler] for a [TransportAction]. (e.g. `RestGetAction` calls `TransportGetAction`). There are actions for which this pattern +> does not hold, in those cases you can locate the transport action for a REST action by looking at the `NodeClient` invocation in the +> `Rest*Action`'s `prepareRequest` implementation, it should specify the `ActionType` being invoked which can then be used to locate +> the `Transport*Action` class that handles it. + +### Action registration +Elasticsearch contains many [TransportAction]s, configured statically in [ActionModule#setupActions]. [ActionPlugin]s can +contribute additional actions via the [getActions][ActionPlugin#getActions] method. `TransportAction`s define the request and response +types used to invoke the action and the logic for performing the action. + +`TransportAction`s that are registered in `ActionModule#setupActions` (including those supplied by plugins) are locally bound to their +[ActionType]. This map of `type -> action` bindings is what [NodeClient] instances use to locate actions in [NodeClient#executeLocally]. + +The actions themselves sometimes dispatch downstream actions to other nodes in the cluster via the transport layer (see +[TransportService#sendRequest]). To be callable in this way, actions must register themselves with the [TransportService] by calling +[TransportService#registerRequestHandler]. [HandledTransportAction] is a common parent class that registers an action with the +`TransportService`. + +> [!NOTE] +> The name [TransportAction] can be misleading, as it suggests they are all invoke-able and invoked via the TCP transport. In fact, +> a majority of transport actions are only ever invoked locally via the [NodeClient]. The two key features of a `TransportAction` are: +> - Their constructor parameters are provided via dependency injection (Guice) at runtime rather than direct instantiation. +> - They represent a security boundary; we check that the calling user is authorized to call the action they're calling using +> [TransportInterceptor]s, which are described below. + +### Action invocation +The [NodeClient] executes all actions locally on the invoking node using the [NodeClient#executeLocally] method. This method invokes +[TaskManager#registerAndExecute] to register a task, execute the action, then unregister the task once the action completes. +There is more information about task management in the [Distributed architecture guide](./DistributedArchitectureGuide.md#task-management--tracking) + +There are a few common patterns for [TransportAction] execution that are present in the codebase. Some prominent examples include... + +- [TransportMasterNodeAction]: Executes an action on the master node. Typically used to perform cluster state updates, as these can only +be performed on the master. The base class contains logic for locating the master node and delegating to it to execute the specified logic. +- [TransportNodesAction]: Executes an action on many nodes then collates the responses. +- [TransportLocalClusterStateAction]: Waits for a cluster state that optionally meets some criteria and performs a read action on it on the +coordinating node. +- [TransportReplicationAction]: Execute an action on a primary shard followed by all replicas that exist for that shard. The base class +implements logic for locating the primary and replica shards in the cluster and delegating to the relevant nodes. Often used for index +updates in stateful Elasticsearch. +- [TransportSingleShardAction]: Executes a read operation on a specific shard, the base class contains logic for locating an available copy +of the nominated shard and delegating to the relevant node to execute the action. On a failure, the action is retried on a different copy. + +### Transport interceptors + +The transport action infrastructure allows the configuration of interceptors which can implement cross-cutting concerns like security around +action invocations. Implementations of [TransportInterceptor] interface are able to intercept action requests by wrapping +[TransportRequestHandler]s, or by intercepting requests before they are sent. Plugins that implement the [NetworkPlugin] interface are able +to register interceptors by implementing the [getTransportInterceptors][NetworkPlugin#getTransportInterceptors] method. + +### Transport infrastructure + +The transport infrastructure is pluggable and implementations can be provided by [NetworkPlugin#getTransports]. The role of the [Transport] +is to establish connections between nodes over which [TransportRequest]s can be sent, maintain a registry of [TransportRequestHandler]s for +routing inbound requests and maintain state to correlate inbound responses with the original requests. There is a single [Netty](https://netty.io/)-based TCP +transport used in production Elasticsearch, the [Netty4Transport], but the security plugin extends that to add SSL and IP filtering +capabilities. + +[ActionModule#setupActions]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/action/ActionModule.java#L600 +[ActionPlugin#getActions]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/plugins/ActionPlugin.java#L55 +[ActionRequest]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/action/ActionRequest.java +[ActionType]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/action/ActionType.java +[HandledTransportAction]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/action/support/HandledTransportAction.java +[Netty4Transport]:https://github.com/elastic/elasticsearch/blob/v9.0.1/modules/transport-netty4/src/main/java/org/elasticsearch/transport/netty4/Netty4Transport.java +[NetworkPlugin#getTransportInterceptors]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/plugins/NetworkPlugin.java#L47 +[NetworkPlugin#getTransports]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/plugins/NetworkPlugin.java#L58 +[NetworkPlugin]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/plugins/NetworkPlugin.java +[NodeClient#executeLocally]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/client/internal/node/NodeClient.java#L101 +[NodeClient]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/client/internal/node/NodeClient.java +[TaskManager#registerAndExecute]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/tasks/TaskManager.java#L175 +[TransportInterceptor]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/transport/TransportInterceptor.java +[TransportLocalClusterStateAction]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/action/support/local/TransportLocalClusterStateAction.java +[TransportMasterNodeAction]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/action/support/master/TransportMasterNodeAction.java +[TransportNodesAction]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/action/support/nodes/TransportNodesAction.java +[TransportReplicationAction]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/action/support/replication/TransportReplicationAction.java +[TransportRequestHandler]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/transport/TransportRequestHandler.java +[TransportRequest]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/transport/TransportRequest.java +[TransportService#registerRequestHandler]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/transport/TransportService.java#L1208 +[TransportService#sendRequest]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/transport/TransportService.java#L769 +[TransportService]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/transport/TransportService.java +[TransportSingleShardAction]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/action/support/single/shard/TransportSingleShardAction.java +[Transport]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/transport/Transport.java ## Serializations diff --git a/docs/reference/aggregations/_snippets/search-aggregations-metrics-percentile-aggregation-approximate.md b/docs/reference/aggregations/_snippets/search-aggregations-metrics-percentile-aggregation-approximate.md index 76a05164b1258..4913043d1eff0 100644 --- a/docs/reference/aggregations/_snippets/search-aggregations-metrics-percentile-aggregation-approximate.md +++ b/docs/reference/aggregations/_snippets/search-aggregations-metrics-percentile-aggregation-approximate.md @@ -1,6 +1,6 @@ There are many different algorithms to calculate percentiles. The naive implementation simply stores all the values in a sorted array. To find the 50th percentile, you simply find the value that is at `my_array[count(my_array) * 0.5]`. -Clearly, the naive implementation does not scale — the sorted array grows linearly with the number of values in your dataset. To calculate percentiles across potentially billions of values in an Elasticsearch cluster, *approximate* percentiles are calculated. +Clearly, the naive implementation does not scale — the sorted array grows linearly with the number of values in your dataset. To calculate percentiles across potentially billions of values in an Elasticsearch cluster, *approximate* percentiles are calculated. The algorithm used by the `percentile` metric is called TDigest (introduced by Ted Dunning in [Computing Accurate Quantiles using T-Digests](https://github.com/tdunning/t-digest/blob/master/docs/t-digest-paper/histo.pdf)). diff --git a/docs/reference/aggregations/pipeline.md b/docs/reference/aggregations/pipeline.md index 86dcfc3656181..b1f7386e393fc 100644 --- a/docs/reference/aggregations/pipeline.md +++ b/docs/reference/aggregations/pipeline.md @@ -230,7 +230,7 @@ An alternate syntax is supported to cope with aggregations or metrics which have ## Dealing with gaps in the data [gap-policy] -Data in the real world is often noisy and sometimes contains **gaps** — places where data simply doesn’t exist. This can occur for a variety of reasons, the most common being: +Data in the real world is often noisy and sometimes contains **gaps** — places where data simply doesn’t exist. This can occur for a variety of reasons, the most common being: * Documents falling into a bucket do not contain a required field * There are no documents matching the query for one or more buckets diff --git a/docs/reference/aggregations/search-aggregations-bucket-composite-aggregation.md b/docs/reference/aggregations/search-aggregations-bucket-composite-aggregation.md index bca1a0dce4069..03fc0477eb016 100644 --- a/docs/reference/aggregations/search-aggregations-bucket-composite-aggregation.md +++ b/docs/reference/aggregations/search-aggregations-bucket-composite-aggregation.md @@ -606,7 +606,7 @@ PUT my-index-000001 ``` 1. This index is sorted by `username` first then by `timestamp`. -2. …​ in ascending order for the `username` field and in descending order for the `timestamp` field.1. could be used to optimize these composite aggregations: +2. … in ascending order for the `username` field and in descending order for the `timestamp` field.1. could be used to optimize these composite aggregations: diff --git a/docs/reference/aggregations/search-aggregations-bucket-datehistogram-aggregation.md b/docs/reference/aggregations/search-aggregations-bucket-datehistogram-aggregation.md index 7169b1d28da1f..6ff26774e3ec3 100644 --- a/docs/reference/aggregations/search-aggregations-bucket-datehistogram-aggregation.md +++ b/docs/reference/aggregations/search-aggregations-bucket-datehistogram-aggregation.md @@ -679,7 +679,7 @@ Response: } ``` -The response will contain all the buckets having the relative day of the week as key : 1 for Monday, 2 for Tuesday…​ 7 for Sunday. +The response will contain all the buckets having the relative day of the week as key : 1 for Monday, 2 for Tuesday… 7 for Sunday. diff --git a/docs/reference/aggregations/search-aggregations-bucket-rare-terms-aggregation.md b/docs/reference/aggregations/search-aggregations-bucket-rare-terms-aggregation.md index 3c17abd2db2b7..07ac4e2c8f916 100644 --- a/docs/reference/aggregations/search-aggregations-bucket-rare-terms-aggregation.md +++ b/docs/reference/aggregations/search-aggregations-bucket-rare-terms-aggregation.md @@ -7,7 +7,7 @@ mapped_pages: # Rare terms aggregation [search-aggregations-bucket-rare-terms-aggregation] -A multi-bucket value source based aggregation which finds "rare" terms — terms that are at the long-tail of the distribution and are not frequent. Conceptually, this is like a `terms` aggregation that is sorted by `_count` ascending. As noted in the [terms aggregation docs](/reference/aggregations/search-aggregations-bucket-terms-aggregation.md#search-aggregations-bucket-terms-aggregation-order), actually ordering a `terms` agg by count ascending has unbounded error. Instead, you should use the `rare_terms` aggregation +A multi-bucket value source based aggregation which finds "rare" terms — terms that are at the long-tail of the distribution and are not frequent. Conceptually, this is like a `terms` aggregation that is sorted by `_count` ascending. As noted in the [terms aggregation docs](/reference/aggregations/search-aggregations-bucket-terms-aggregation.md#search-aggregations-bucket-terms-aggregation-order), actually ordering a `terms` agg by count ascending has unbounded error. Instead, you should use the `rare_terms` aggregation ## Syntax [_syntax_3] @@ -117,7 +117,7 @@ This does, however, mean that a large number of results can be returned if chose ## Max Bucket Limit [search-aggregations-bucket-rare-terms-aggregation-max-buckets] -The Rare Terms aggregation is more liable to trip the `search.max_buckets` soft limit than other aggregations due to how it works. The `max_bucket` soft-limit is evaluated on a per-shard basis while the aggregation is collecting results. It is possible for a term to be "rare" on a shard but become "not rare" once all the shard results are merged together. This means that individual shards tend to collect more buckets than are truly rare, because they only have their own local view. This list is ultimately pruned to the correct, smaller list of rare terms on the coordinating node…​ but a shard may have already tripped the `max_buckets` soft limit and aborted the request. +The Rare Terms aggregation is more liable to trip the `search.max_buckets` soft limit than other aggregations due to how it works. The `max_bucket` soft-limit is evaluated on a per-shard basis while the aggregation is collecting results. It is possible for a term to be "rare" on a shard but become "not rare" once all the shard results are merged together. This means that individual shards tend to collect more buckets than are truly rare, because they only have their own local view. This list is ultimately pruned to the correct, smaller list of rare terms on the coordinating node… but a shard may have already tripped the `max_buckets` soft limit and aborted the request. When aggregating on fields that have potentially many "rare" terms, you may need to increase the `max_buckets` soft limit. Alternatively, you might need to find a way to filter the results to return fewer rare values (smaller time span, filter by category, etc), or re-evaluate your definition of "rare" (e.g. if something appears 100,000 times, is it truly "rare"?) diff --git a/docs/reference/aggregations/search-aggregations-bucket-significantterms-aggregation.md b/docs/reference/aggregations/search-aggregations-bucket-significantterms-aggregation.md index 05486bb5ba2b4..0ac394bb600da 100644 --- a/docs/reference/aggregations/search-aggregations-bucket-significantterms-aggregation.md +++ b/docs/reference/aggregations/search-aggregations-bucket-significantterms-aggregation.md @@ -253,8 +253,8 @@ Like most design decisions, this is the basis of a trade-off in which we have ch The JLH score can be used as a significance score by adding the parameter ```js - "jlh": { - } + "jlh": { + } ``` The scores are derived from the doc frequencies in *foreground* and *background* sets. The *absolute* change in popularity (foregroundPercent - backgroundPercent) would favor common terms whereas the *relative* change in popularity (foregroundPercent/ backgroundPercent) would favor rare terms. Rare vs common is essentially a precision vs recall balance and so the absolute and relative changes are multiplied to provide a sweet spot between precision and recall. @@ -265,9 +265,9 @@ The scores are derived from the doc frequencies in *foreground* and *background* Mutual information as described in "Information Retrieval", Manning et al., Chapter 13.5.1 can be used as significance score by adding the parameter ```js - "mutual_information": { - "include_negatives": true - } + "mutual_information": { + "include_negatives": true + } ``` Mutual information does not differentiate between terms that are descriptive for the subset or for documents outside the subset. The significant terms therefore can contain terms that appear more or less frequent in the subset than outside the subset. To filter out the terms that appear less often in the subset than in documents outside the subset, `include_negatives` can be set to `false`. @@ -284,8 +284,8 @@ Per default, the assumption is that the documents in the bucket are also contain Chi square as described in "Information Retrieval", Manning et al., Chapter 13.5.2 can be used as significance score by adding the parameter ```js - "chi_square": { - } + "chi_square": { + } ``` Chi square behaves like mutual information and can be configured with the same parameters `include_negatives` and `background_is_superset`. @@ -296,8 +296,8 @@ Chi square behaves like mutual information and can be configured with the same p Google normalized distance as described in ["The Google Similarity Distance", Cilibrasi and Vitanyi, 2007](https://arxiv.org/pdf/cs/0412098v3.pdf) can be used as significance score by adding the parameter ```js - "gnd": { - } + "gnd": { + } ``` `gnd` also accepts the `background_is_superset` parameter. @@ -394,8 +394,8 @@ The benefit of this heuristic is that the scoring logic is simple to explain to It would be hard for a seasoned boxer to win a championship if the prize was awarded purely on the basis of percentage of fights won - by these rules a newcomer with only one fight under their belt would be impossible to beat. Multiple observations are typically required to reinforce a view so it is recommended in these cases to set both `min_doc_count` and `shard_min_doc_count` to a higher value such as 10 in order to filter out the low-frequency terms that otherwise take precedence. ```js - "percentage": { - } + "percentage": { + } ``` @@ -413,11 +413,11 @@ If none of the above measures suits your usecase than another option is to imple Customized scores can be implemented via a script: ```js - "script_heuristic": { + "script_heuristic": { "script": { - "lang": "painless", - "source": "params._subset_freq/(params._superset_freq - params._subset_freq + 1)" - } + "lang": "painless", + "source": "params._subset_freq/(params._superset_freq - params._subset_freq + 1)" + } } ``` diff --git a/docs/reference/aggregations/search-aggregations-bucket-significanttext-aggregation.md b/docs/reference/aggregations/search-aggregations-bucket-significanttext-aggregation.md index 7eaf9b06bd8be..6175926e80023 100644 --- a/docs/reference/aggregations/search-aggregations-bucket-significanttext-aggregation.md +++ b/docs/reference/aggregations/search-aggregations-bucket-significanttext-aggregation.md @@ -21,7 +21,7 @@ Re-analyzing *large* result sets will require a lot of time and memory. It is re * Suggesting "H5N1" when users search for "bird flu" to help expand queries * Suggesting keywords relating to stock symbol $ATI for use in an automated news classifier -In these cases the words being selected are not simply the most popular terms in results. The most popular words tend to be very boring (*and, of, the, we, I, they* …​). The significant words are the ones that have undergone a significant change in popularity measured between a *foreground* and *background* set. If the term "H5N1" only exists in 5 documents in a 10 million document index and yet is found in 4 of the 100 documents that make up a user’s search results that is significant and probably very relevant to their search. 5/10,000,000 vs 4/100 is a big swing in frequency. +In these cases the words being selected are not simply the most popular terms in results. The most popular words tend to be very boring (*and, of, the, we, I, they* … ). The significant words are the ones that have undergone a significant change in popularity measured between a *foreground* and *background* set. If the term "H5N1" only exists in 5 documents in a 10 million document index and yet is found in 4 of the 100 documents that make up a user’s search results that is significant and probably very relevant to their search. 5/10,000,000 vs 4/100 is a big swing in frequency. ## Basic use [_basic_use_2] diff --git a/docs/reference/aggregations/search-aggregations-bucket-terms-aggregation.md b/docs/reference/aggregations/search-aggregations-bucket-terms-aggregation.md index f84deb2d6297c..598d8f7617520 100644 --- a/docs/reference/aggregations/search-aggregations-bucket-terms-aggregation.md +++ b/docs/reference/aggregations/search-aggregations-bucket-terms-aggregation.md @@ -696,7 +696,7 @@ When aggregating on multiple indices the type of the aggregated field may not be ### Failed Trying to Format Bytes [_failed_trying_to_format_bytes] -When running a terms aggregation (or other aggregation, but in practice usually terms) over multiple indices, you may get an error that starts with "Failed trying to format bytes…​". This is usually caused by two of the indices not having the same mapping type for the field being aggregated. +When running a terms aggregation (or other aggregation, but in practice usually terms) over multiple indices, you may get an error that starts with "Failed trying to format bytes… ". This is usually caused by two of the indices not having the same mapping type for the field being aggregated. **Use an explicit `value_type`** Although it’s best to correct the mappings, you can work around this issue if the field is unmapped in one of the indices. Setting the `value_type` parameter can resolve the issue by coercing the unmapped field into the correct type. diff --git a/docs/reference/aggregations/search-aggregations-metrics-boxplot-aggregation.md b/docs/reference/aggregations/search-aggregations-metrics-boxplot-aggregation.md index d8997339a9541..5966978a3bc2c 100644 --- a/docs/reference/aggregations/search-aggregations-metrics-boxplot-aggregation.md +++ b/docs/reference/aggregations/search-aggregations-metrics-boxplot-aggregation.md @@ -126,7 +126,7 @@ GET latency/_search 1. Compression controls memory usage and approximation error -The TDigest algorithm uses a number of "nodes" to approximate percentiles — the more nodes available, the higher the accuracy (and large memory footprint) proportional to the volume of data. The `compression` parameter limits the maximum number of nodes to `20 * compression`. +The TDigest algorithm uses a number of "nodes" to approximate percentiles — the more nodes available, the higher the accuracy (and large memory footprint) proportional to the volume of data. The `compression` parameter limits the maximum number of nodes to `20 * compression`. Therefore, by increasing the compression value, you can increase the accuracy of your percentiles at the cost of more memory. Larger compression values also make the algorithm slower since the underlying tree data structure grows in size, resulting in more expensive operations. The default compression value is `100`. diff --git a/docs/reference/aggregations/search-aggregations-metrics-percentile-aggregation.md b/docs/reference/aggregations/search-aggregations-metrics-percentile-aggregation.md index 9d16953007749..b45a126bda750 100644 --- a/docs/reference/aggregations/search-aggregations-metrics-percentile-aggregation.md +++ b/docs/reference/aggregations/search-aggregations-metrics-percentile-aggregation.md @@ -60,7 +60,7 @@ By default, the `percentile` metric will generate a range of percentiles: `[ 1, As you can see, the aggregation will return a calculated value for each percentile in the default range. If we assume response times are in milliseconds, it is immediately obvious that the webpage normally loads in 10-720ms, but occasionally spikes to 940-980ms. -Often, administrators are only interested in outliers — the extreme percentiles. We can specify just the percents we are interested in (requested percentiles must be a value between 0-100 inclusive): +Often, administrators are only interested in outliers — the extreme percentiles. We can specify just the percents we are interested in (requested percentiles must be a value between 0-100 inclusive): ```console GET latency/_search @@ -177,7 +177,7 @@ GET latency/_search There are many different algorithms to calculate percentiles. The naive implementation simply stores all the values in a sorted array. To find the 50th percentile, you simply find the value that is at `my_array[count(my_array) * 0.5]`. -Clearly, the naive implementation does not scale — the sorted array grows linearly with the number of values in your dataset. To calculate percentiles across potentially billions of values in an Elasticsearch cluster, *approximate* percentiles are calculated. +Clearly, the naive implementation does not scale — the sorted array grows linearly with the number of values in your dataset. To calculate percentiles across potentially billions of values in an Elasticsearch cluster, *approximate* percentiles are calculated. The algorithm used by the `percentile` metric is called TDigest (introduced by Ted Dunning in [Computing Accurate Quantiles using T-Digests](https://github.com/tdunning/t-digest/blob/master/docs/t-digest-paper/histo.pdf)). @@ -222,7 +222,7 @@ GET latency/_search 1. Compression controls memory usage and approximation error -The TDigest algorithm uses a number of "nodes" to approximate percentiles — the more nodes available, the higher the accuracy (and large memory footprint) proportional to the volume of data. The `compression` parameter limits the maximum number of nodes to `20 * compression`. +The TDigest algorithm uses a number of "nodes" to approximate percentiles — the more nodes available, the higher the accuracy (and large memory footprint) proportional to the volume of data. The `compression` parameter limits the maximum number of nodes to `20 * compression`. Therefore, by increasing the compression value, you can increase the accuracy of your percentiles at the cost of more memory. Larger compression values also make the algorithm slower since the underlying tree data structure grows in size, resulting in more expensive operations. The default compression value is `100`. diff --git a/docs/reference/aggregations/search-aggregations-metrics-weight-avg-aggregation.md b/docs/reference/aggregations/search-aggregations-metrics-weight-avg-aggregation.md index ea83567f7fdff..6829795ae7bca 100644 --- a/docs/reference/aggregations/search-aggregations-metrics-weight-avg-aggregation.md +++ b/docs/reference/aggregations/search-aggregations-metrics-weight-avg-aggregation.md @@ -9,7 +9,7 @@ mapped_pages: A `single-value` metrics aggregation that computes the weighted average of numeric values that are extracted from the aggregated documents. These values can be extracted either from specific numeric fields in the documents. -When calculating a regular average, each datapoint has an equal "weight" …​ it contributes equally to the final value. Weighted averages, on the other hand, weight each datapoint differently. The amount that each datapoint contributes to the final value is extracted from the document. +When calculating a regular average, each datapoint has an equal "weight" … it contributes equally to the final value. Weighted averages, on the other hand, weight each datapoint differently. The amount that each datapoint contributes to the final value is extracted from the document. As a formula, a weighted average is the `∑(value * weight) / ∑(weight)` diff --git a/docs/reference/elasticsearch-plugins/analysis-kuromoji-analyzer.md b/docs/reference/elasticsearch-plugins/analysis-kuromoji-analyzer.md index 6b1b96e841f66..bed37ed537630 100644 --- a/docs/reference/elasticsearch-plugins/analysis-kuromoji-analyzer.md +++ b/docs/reference/elasticsearch-plugins/analysis-kuromoji-analyzer.md @@ -22,7 +22,7 @@ It supports the `mode` and `user_dictionary` settings from [`kuromoji_tokenizer` The `kuromoji_tokenizer` tokenizer uses characters from the MeCab-IPADIC dictionary to split text into tokens. The dictionary includes some full-width characters, such as `ｏ` and `ｆ`. If a text contains full-width characters, the tokenizer can produce unexpected tokens. -For example, the `kuromoji_tokenizer` tokenizer converts the text `Ｃｕｌｔｕｒｅ　ｏｆ　Ｊａｐａｎ` to the tokens `[ culture, o, f, japan ]` instead of `[ culture, of, japan ]`. +For example, the `kuromoji_tokenizer` tokenizer converts the text `Ｃｕｌｔｕｒｅ ｏｆ Ｊａｐａｎ` to the tokens `[ culture, o, f, japan ]` instead of `[ culture, of, japan ]`. To avoid this, add the [`icu_normalizer` character filter](/reference/elasticsearch-plugins/analysis-icu-normalization-charfilter.md) to a custom analyzer based on the `kuromoji` analyzer. The `icu_normalizer` character filter converts full-width characters to their normal equivalents. diff --git a/docs/reference/elasticsearch-plugins/discovery-azure-classic-scale.md b/docs/reference/elasticsearch-plugins/discovery-azure-classic-scale.md index 6e46c2fdb8186..1b5d50b112b32 100644 --- a/docs/reference/elasticsearch-plugins/discovery-azure-classic-scale.md +++ b/docs/reference/elasticsearch-plugins/discovery-azure-classic-scale.md @@ -3,7 +3,7 @@ mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/plugins/current/discovery-azure-classic-scale.html --- -# Scaling out! [discovery-azure-classic-scale] +# Scaling out [discovery-azure-classic-scale] You need first to create an image of your previous machine. Disconnect from your machine and run locally the following commands: diff --git a/docs/reference/elasticsearch-plugins/integrations.md b/docs/reference/elasticsearch-plugins/integrations.md index 56e94ffc8c5d9..c8aa783593e1b 100644 --- a/docs/reference/elasticsearch-plugins/integrations.md +++ b/docs/reference/elasticsearch-plugins/integrations.md @@ -31,7 +31,7 @@ Integrations are not plugins, but are external tools or modules that make it eas * [Ingest processor template](https://github.com/spinscale/cookiecutter-elasticsearch-ingest-processor): A template for creating new ingest processors. * [Kafka Standalone Consumer (Indexer)](https://github.com/BigDataDevs/kafka-elasticsearch-consumer): Kafka Standalone Consumer [Indexer] will read messages from Kafka in batches, processes(as implemented) and bulk-indexes them into Elasticsearch. Flexible and scalable. More documentation in above GitHub repo’s Wiki. * [Scrutineer](https://github.com/Aconex/scrutineer): A high performance consistency checker to compare what you’ve indexed with your source of truth content (e.g. DB) -* [FS Crawler](https://github.com/dadoonet/fscrawler): The File System (FS) crawler allows to index documents (PDF, Open Office…​) from your local file system and over SSH. (by David Pilato) +* [FS Crawler](https://github.com/dadoonet/fscrawler): The File System (FS) crawler allows to index documents (PDF, Open Office… ) from your local file system and over SSH. (by David Pilato) * [Elasticsearch Evolution](https://github.com/senacor/elasticsearch-evolution): A library to migrate elasticsearch mappings. * [PGSync](https://pgsync.com): A tool for syncing data from Postgres to Elasticsearch. diff --git a/docs/reference/elasticsearch/configuration-reference/auding-settings.md b/docs/reference/elasticsearch/configuration-reference/auding-settings.md index ae7c0937b5d52..8439de8015f0e 100644 --- a/docs/reference/elasticsearch/configuration-reference/auding-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/auding-settings.md @@ -25,7 +25,7 @@ If configured, auditing settings must be set on every node in the cluster. Stati $$$xpack-security-audit-enabled$$$ `xpack.security.audit.enabled` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Set to `true` to enable auditing on the node. The default value is `false`. This puts the auditing events in a dedicated file named `_audit.json` on each node. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Set to `true` to enable auditing on the node. The default value is `false`. This puts the auditing events in a dedicated file named `_audit.json` on each node. If enabled, this setting must be configured in `elasticsearch.yml` on all nodes in the cluster. @@ -38,17 +38,17 @@ The events and some other information about what gets logged can be controlled b $$$xpack-sa-lf-events-include$$$ `xpack.security.audit.logfile.events.include` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Specifies the [kind of events](/reference/elasticsearch/elasticsearch-audit-events.md) to print in the auditing output. In addition, `_all` can be used to exhaustively audit all the events, but this is usually discouraged since it will get very verbose. The default list value contains: `access_denied, access_granted, anonymous_access_denied, authentication_failed, connection_denied, tampered_request, run_as_denied, run_as_granted, security_config_change`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Specifies the [kind of events](/reference/elasticsearch/elasticsearch-audit-events.md) to print in the auditing output. In addition, `_all` can be used to exhaustively audit all the events, but this is usually discouraged since it will get very verbose. The default list value contains: `access_denied, access_granted, anonymous_access_denied, authentication_failed, connection_denied, tampered_request, run_as_denied, run_as_granted, security_config_change`. $$$xpack-sa-lf-events-exclude$$$ `xpack.security.audit.logfile.events.exclude` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Excludes the specified [kind of events](/reference/elasticsearch/elasticsearch-audit-events.md) from the include list. This is useful in the case where the `events.include` setting contains the special value `_all`. The default is the empty list. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Excludes the specified [kind of events](/reference/elasticsearch/elasticsearch-audit-events.md) from the include list. This is useful in the case where the `events.include` setting contains the special value `_all`. The default is the empty list. $$$xpack-sa-lf-events-emit-request$$$ `xpack.security.audit.logfile.events.emit_request_body` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Specifies whether to include the full request body from REST requests as an attribute of certain kinds of audit events. This setting can be used to [audit search queries](docs-content://deploy-manage/security/logging-configuration/auditing-search-queries.md). +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Specifies whether to include the full request body from REST requests as an attribute of certain kinds of audit events. This setting can be used to [audit search queries](docs-content://deploy-manage/security/logging-configuration/auditing-search-queries.md). The default value is `false`, so request bodies are not printed. @@ -63,22 +63,22 @@ $$$xpack-sa-lf-events-emit-request$$$ $$$xpack-sa-lf-emit-node-name$$$ `xpack.security.audit.logfile.emit_node_name` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Specifies whether to include the [node name](docs-content://deploy-manage/deploy/self-managed/important-settings-configuration.md#node-name) as a field in each audit event. The default value is `false`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Specifies whether to include the [node name](docs-content://deploy-manage/deploy/self-managed/important-settings-configuration.md#node-name) as a field in each audit event. The default value is `false`. $$$xpack-sa-lf-emit-node-host-address$$$ `xpack.security.audit.logfile.emit_node_host_address` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Specifies whether to include the node’s IP address as a field in each audit event. The default value is `false`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Specifies whether to include the node’s IP address as a field in each audit event. The default value is `false`. $$$xpack-sa-lf-emit-node-host-name$$$ `xpack.security.audit.logfile.emit_node_host_name` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Specifies whether to include the node’s host name as a field in each audit event. The default value is `false`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Specifies whether to include the node’s host name as a field in each audit event. The default value is `false`. $$$xpack-sa-lf-emit-node-id$$$ `xpack.security.audit.logfile.emit_node_id` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Specifies whether to include the node id as a field in each audit event. Unlike [node name](docs-content://deploy-manage/deploy/self-managed/important-settings-configuration.md#node-name), whose value might change if the administrator changes the setting in the config file, the node id will persist across cluster restarts and the administrator cannot change it. The default value is `true`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Specifies whether to include the node id as a field in each audit event. Unlike [node name](docs-content://deploy-manage/deploy/self-managed/important-settings-configuration.md#node-name), whose value might change if the administrator changes the setting in the config file, the node id will persist across cluster restarts and the administrator cannot change it. The default value is `true`. ## Audit Logfile Event Ignore Policies [audit-event-ignore-policies] @@ -88,26 +88,26 @@ The following settings affect the [ignore policies](docs-content://deploy-manage $$$xpack-sa-lf-events-ignore-users$$$ `xpack.security.audit.logfile.events.ignore_filters..users` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) A list of user names or wildcards. The specified policy will not print audit events for users matching these values. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) A list of user names or wildcards. The specified policy will not print audit events for users matching these values. $$$xpack-sa-lf-events-ignore-realms$$$ `xpack.security.audit.logfile.events.ignore_filters..realms` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) A list of authentication realm names or wildcards. The specified policy will not print audit events for users in these realms. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) A list of authentication realm names or wildcards. The specified policy will not print audit events for users in these realms. $$$xpack-sa-lf-events-ignore-actions$$$ `xpack.security.audit.logfile.events.ignore_filters..actions` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) A list of action names or wildcards. Action name can be found in the `action` field of the audit event. The specified policy will not print audit events for actions matching these values. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) A list of action names or wildcards. Action name can be found in the `action` field of the audit event. The specified policy will not print audit events for actions matching these values. $$$xpack-sa-lf-events-ignore-roles$$$ `xpack.security.audit.logfile.events.ignore_filters..roles` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) A list of role names or wildcards. The specified policy will not print audit events for users that have these roles. If the user has several roles, some of which are **not** covered by the policy, the policy will **not** cover this event. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) A list of role names or wildcards. The specified policy will not print audit events for users that have these roles. If the user has several roles, some of which are **not** covered by the policy, the policy will **not** cover this event. $$$xpack-sa-lf-events-ignore-indices$$$ `xpack.security.audit.logfile.events.ignore_filters..indices` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) A list of index names or wildcards. The specified policy will not print audit events when all the indices in the event match these values. If the event concerns several indices, some of which are **not** covered by the policy, the policy will **not** cover this event. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) A list of index names or wildcards. The specified policy will not print audit events when all the indices in the event match these values. If the event concerns several indices, some of which are **not** covered by the policy, the policy will **not** cover this event. diff --git a/docs/reference/elasticsearch/configuration-reference/circuit-breaker-settings.md b/docs/reference/elasticsearch/configuration-reference/circuit-breaker-settings.md index c5ec2c19785af..7a7222e9a03ef 100644 --- a/docs/reference/elasticsearch/configuration-reference/circuit-breaker-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/circuit-breaker-settings.md @@ -26,12 +26,12 @@ For information about circuit breaker errors, see [Circuit breaker errors](docs- The parent-level breaker can be configured with the following settings: `indices.breaker.total.use_real_memory` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Determines whether the parent breaker should take real memory usage into account (`true`) or only consider the amount that is reserved by child circuit breakers (`false`). Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Determines whether the parent breaker should take real memory usage into account (`true`) or only consider the amount that is reserved by child circuit breakers (`false`). Defaults to `true`. $$$indices-breaker-total-limit$$$ `indices.breaker.total.limit` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Starting limit for overall parent breaker. Defaults to 70% of JVM heap if `indices.breaker.total.use_real_memory` is `false`. If `indices.breaker.total.use_real_memory` is `true`, defaults to 95% of the JVM heap. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Starting limit for overall parent breaker. Defaults to 70% of JVM heap if `indices.breaker.total.use_real_memory` is `false`. If `indices.breaker.total.use_real_memory` is `true`, defaults to 95% of the JVM heap. ### Field data circuit breaker [fielddata-circuit-breaker] @@ -41,12 +41,12 @@ The field data circuit breaker estimates the heap memory required to load a fiel $$$fielddata-circuit-breaker-limit$$$ `indices.breaker.fielddata.limit` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Limit for fielddata breaker. Defaults to 40% of JVM heap. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Limit for fielddata breaker. Defaults to 40% of JVM heap. $$$fielddata-circuit-breaker-overhead$$$ `indices.breaker.fielddata.overhead` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) A constant that all field data estimations are multiplied with to determine a final estimation. Defaults to `1.03`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) A constant that all field data estimations are multiplied with to determine a final estimation. Defaults to `1.03`. ### Request circuit breaker [request-circuit-breaker] @@ -56,12 +56,12 @@ The request circuit breaker allows Elasticsearch to prevent per-request data str $$$request-breaker-limit$$$ `indices.breaker.request.limit` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Limit for request breaker, defaults to 60% of JVM heap. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Limit for request breaker, defaults to 60% of JVM heap. $$$request-breaker-overhead$$$ `indices.breaker.request.overhead` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) A constant that all request estimations are multiplied with to determine a final estimation. Defaults to `1`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) A constant that all request estimations are multiplied with to determine a final estimation. Defaults to `1`. ### In flight requests circuit breaker [in-flight-circuit-breaker] @@ -69,10 +69,10 @@ $$$request-breaker-overhead$$$ The in flight requests circuit breaker allows Elasticsearch to limit the memory usage of all currently active incoming requests on transport or HTTP level from exceeding a certain amount of memory on a node. The memory usage is based on the content length of the request itself. This circuit breaker also considers that memory is not only needed for representing the raw request but also as a structured object which is reflected by default overhead. `network.breaker.inflight_requests.limit` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Limit for in flight requests breaker, defaults to 100% of JVM heap. This means that it is bound by the limit configured for the parent circuit breaker. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Limit for in flight requests breaker, defaults to 100% of JVM heap. This means that it is bound by the limit configured for the parent circuit breaker. `network.breaker.inflight_requests.overhead` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) A constant that all in flight requests estimations are multiplied with to determine a final estimation. Defaults to 2. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) A constant that all in flight requests estimations are multiplied with to determine a final estimation. Defaults to 2. ### Script compilation circuit breaker [script-compilation-circuit-breaker] @@ -82,7 +82,7 @@ Slightly different than the previous memory-based circuit breaker, the script co See the "prefer-parameters" section of the [scripting](docs-content://explore-analyze/scripting/modules-scripting-using.md) documentation for more information. `script.max_compilations_rate` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Limit for the number of unique dynamic scripts within a certain interval that are allowed to be compiled. Defaults to `150/5m`, meaning 150 every 5 minutes. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Limit for the number of unique dynamic scripts within a certain interval that are allowed to be compiled. Defaults to `150/5m`, meaning 150 every 5 minutes. If the cluster regularly hits the given `max_compilation_rate`, it’s possible the script cache is undersized, use [Nodes Stats](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-nodes-stats) to inspect the number of recent cache evictions, `script.cache_evictions_history` and compilations `script.compilations_history`. If there are a large number of recent cache evictions or compilations, the script cache may be undersized, consider doubling the size of the script cache via the setting `script.cache.max_size`. @@ -94,7 +94,7 @@ Poorly written regular expressions can degrade cluster stability and performance $$$script-painless-regex-enabled$$$ `script.painless.regex.enabled` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Enables regex in Painless scripts. Accepts: +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Enables regex in Painless scripts. Accepts: `limited` (Default) : Enables regex but limits complexity using the [`script.painless.regex.limit-factor`](#script-painless-regex-limit-factor) cluster setting. @@ -109,7 +109,7 @@ $$$script-painless-regex-enabled$$$ $$$script-painless-regex-limit-factor$$$ `script.painless.regex.limit-factor` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Limits the number of characters a regular expression in a Painless script can consider. {{es}} calculates this limit by multiplying the setting value by the script input’s character length. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Limits the number of characters a regular expression in a Painless script can consider. {{es}} calculates this limit by multiplying the setting value by the script input’s character length. For example, the input `foobarbaz` has a character length of `9`. If `script.painless.regex.limit-factor` is `6`, a regular expression on `foobarbaz` can consider up to 54 (9 * 6) characters. If the expression exceeds this limit, it triggers the regex circuit breaker and returns an error. @@ -126,13 +126,13 @@ To prevent this from happening, a special circuit breaker is used, which limits This circuit breaker can be configured using the following settings: `breaker.eql_sequence.limit` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) The limit for circuit breaker used to restrict the memory utilisation during the execution of an EQL sequence query. This value is defined as a percentage of the JVM heap. Defaults to `50%`. If the [parent circuit breaker](#parent-circuit-breaker) is set to a value less than `50%`, this setting uses that value as its default instead. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The limit for circuit breaker used to restrict the memory utilisation during the execution of an EQL sequence query. This value is defined as a percentage of the JVM heap. Defaults to `50%`. If the [parent circuit breaker](#parent-circuit-breaker) is set to a value less than `50%`, this setting uses that value as its default instead. `breaker.eql_sequence.overhead` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) A constant that sequence query memory estimates are multiplied by to determine a final estimate. Defaults to `1`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) A constant that sequence query memory estimates are multiplied by to determine a final estimate. Defaults to `1`. `breaker.eql_sequence.type` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Circuit breaker type. Valid values are: +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Circuit breaker type. Valid values are: `memory` (Default) : The breaker limits memory usage for EQL sequence queries. @@ -145,11 +145,11 @@ This circuit breaker can be configured using the following settings: ### {{ml-cap}} circuit breaker [circuit-breakers-page-model-inference] `breaker.model_inference.limit` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) The limit for the trained model circuit breaker. This value is defined as a percentage of the JVM heap. Defaults to `50%`. If the [parent circuit breaker](#parent-circuit-breaker) is set to a value less than `50%`, this setting uses that value as its default instead. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The limit for the trained model circuit breaker. This value is defined as a percentage of the JVM heap. Defaults to `50%`. If the [parent circuit breaker](#parent-circuit-breaker) is set to a value less than `50%`, this setting uses that value as its default instead. `breaker.model_inference.overhead` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) A constant that all trained model estimations are multiplied by to determine a final estimation. Defaults to `1`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) A constant that all trained model estimations are multiplied by to determine a final estimation. Defaults to `1`. `breaker.model_inference.type` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The underlying type of the circuit breaker. There are two valid options: `noop` and `memory`. `noop` means the circuit breaker does nothing to prevent too much memory usage. `memory` means the circuit breaker tracks the memory used by trained models and can potentially break and prevent `OutOfMemory` errors. The default value is `memory`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The underlying type of the circuit breaker. There are two valid options: `noop` and `memory`. `noop` means the circuit breaker does nothing to prevent too much memory usage. `memory` means the circuit breaker tracks the memory used by trained models and can potentially break and prevent `OutOfMemory` errors. The default value is `memory`. diff --git a/docs/reference/elasticsearch/configuration-reference/cluster-level-shard-allocation-routing-settings.md b/docs/reference/elasticsearch/configuration-reference/cluster-level-shard-allocation-routing-settings.md index 9b398f675c4d5..8023ea507abf5 100644 --- a/docs/reference/elasticsearch/configuration-reference/cluster-level-shard-allocation-routing-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/cluster-level-shard-allocation-routing-settings.md @@ -30,7 +30,7 @@ You can use the following settings to control shard allocation and recovery: $$$cluster-routing-allocation-enable$$$ `cluster.routing.allocation.enable` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Enable or disable allocation for specific kinds of shards: +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Enable or disable allocation for specific kinds of shards: * `all` - (default) Allows shard allocation for all kinds of shards. * `primaries` - Allows shard allocation only for primary shards. @@ -43,19 +43,19 @@ This setting only affects future allocations, and does not re-allocate or un-all $$$cluster-routing-allocation-same-shard-host$$$ `cluster.routing.allocation.same_shard.host` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) If `true`, forbids multiple copies of a shard from being allocated to distinct nodes on the same host, i.e. which have the same network address. Defaults to `false`, meaning that copies of a shard may sometimes be allocated to nodes on the same host. This setting is only relevant if you run multiple nodes on each host. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) If `true`, forbids multiple copies of a shard from being allocated to distinct nodes on the same host, i.e. which have the same network address. Defaults to `false`, meaning that copies of a shard may sometimes be allocated to nodes on the same host. This setting is only relevant if you run multiple nodes on each host. `cluster.routing.allocation.node_concurrent_incoming_recoveries` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) How many concurrent incoming shard recoveries are allowed to happen on a node. Incoming recoveries are the recoveries where the target shard (most likely the replica unless a shard is relocating) is allocated on the node. Defaults to `2`. Increasing this setting may cause shard movements to have a performance impact on other activity in your cluster, but may not make shard movements complete noticeably sooner. We do not recommend adjusting this setting from its default of `2`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) How many concurrent incoming shard recoveries are allowed to happen on a node. Incoming recoveries are the recoveries where the target shard (most likely the replica unless a shard is relocating) is allocated on the node. Defaults to `2`. Increasing this setting may cause shard movements to have a performance impact on other activity in your cluster, but may not make shard movements complete noticeably sooner. We do not recommend adjusting this setting from its default of `2`. `cluster.routing.allocation.node_concurrent_outgoing_recoveries` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) How many concurrent outgoing shard recoveries are allowed to happen on a node. Outgoing recoveries are the recoveries where the source shard (most likely the primary unless a shard is relocating) is allocated on the node. Defaults to `2`. Increasing this setting may cause shard movements to have a performance impact on other activity in your cluster, but may not make shard movements complete noticeably sooner. We do not recommend adjusting this setting from its default of `2`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) How many concurrent outgoing shard recoveries are allowed to happen on a node. Outgoing recoveries are the recoveries where the source shard (most likely the primary unless a shard is relocating) is allocated on the node. Defaults to `2`. Increasing this setting may cause shard movements to have a performance impact on other activity in your cluster, but may not make shard movements complete noticeably sooner. We do not recommend adjusting this setting from its default of `2`. `cluster.routing.allocation.node_concurrent_recoveries` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) A shortcut to set both `cluster.routing.allocation.node_concurrent_incoming_recoveries` and `cluster.routing.allocation.node_concurrent_outgoing_recoveries`. The value of this setting takes effect only when the more specific setting is not configured. Defaults to `2`. Increasing this setting may cause shard movements to have a performance impact on other activity in your cluster, but may not make shard movements complete noticeably sooner. We do not recommend adjusting this setting from its default of `2`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) A shortcut to set both `cluster.routing.allocation.node_concurrent_incoming_recoveries` and `cluster.routing.allocation.node_concurrent_outgoing_recoveries`. The value of this setting takes effect only when the more specific setting is not configured. Defaults to `2`. Increasing this setting may cause shard movements to have a performance impact on other activity in your cluster, but may not make shard movements complete noticeably sooner. We do not recommend adjusting this setting from its default of `2`. `cluster.routing.allocation.node_initial_primaries_recoveries` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) While the recovery of replicas happens over the network, the recovery of an unassigned primary after node restart uses data from the local disk. These should be fast so more initial primary recoveries can happen in parallel on each node. Defaults to `4`. Increasing this setting may cause shard recoveries to have a performance impact on other activity in your cluster, but may not make shard recoveries complete noticeably sooner. We do not recommend adjusting this setting from its default of `4`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) While the recovery of replicas happens over the network, the recovery of an unassigned primary after node restart uses data from the local disk. These should be fast so more initial primary recoveries can happen in parallel on each node. Defaults to `4`. Increasing this setting may cause shard recoveries to have a performance impact on other activity in your cluster, but may not make shard recoveries complete noticeably sooner. We do not recommend adjusting this setting from its default of `4`. ## Shard rebalancing settings [shards-rebalancing-settings] @@ -65,7 +65,7 @@ A cluster is *balanced* when it has an equal number of shards on each node, with You can use the following settings to control the rebalancing of shards across the cluster: `cluster.routing.allocation.allow_rebalance` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Specify when shard rebalancing is allowed: +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Specify when shard rebalancing is allowed: * `always` - (default) Always allow rebalancing. * `indices_primaries_active` - Only when all primaries in the cluster are allocated. @@ -73,7 +73,7 @@ You can use the following settings to control the rebalancing of shards across t `cluster.routing.rebalance.enable` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Enable or disable rebalancing for specific kinds of shards: +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Enable or disable rebalancing for specific kinds of shards: * `all` - (default) Allows shard balancing for all kinds of shards. * `primaries` - Allows shard balancing only for primary shards. @@ -84,7 +84,7 @@ Rebalancing is important to ensure the cluster returns to a healthy and fully re `cluster.routing.allocation.cluster_concurrent_rebalance` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Defines the number of concurrent shard rebalances are allowed across the whole cluster. Defaults to `2`. Note that this setting only controls the number of concurrent shard relocations due to imbalances in the cluster. This setting does not limit shard relocations due to [allocation filtering](#cluster-shard-allocation-filtering) or [forced awareness](docs-content://deploy-manage/distributed-architecture/shard-allocation-relocation-recovery/shard-allocation-awareness.md#forced-awareness). Increasing this setting may cause the cluster to use additional resources moving shards between nodes, so we generally do not recommend adjusting this setting from its default of `2`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Defines the number of concurrent shard rebalances are allowed across the whole cluster. Defaults to `2`. Note that this setting only controls the number of concurrent shard relocations due to imbalances in the cluster. This setting does not limit shard relocations due to [allocation filtering](#cluster-shard-allocation-filtering) or [forced awareness](docs-content://deploy-manage/distributed-architecture/shard-allocation-relocation-recovery/shard-allocation-awareness.md#forced-awareness). Increasing this setting may cause the cluster to use additional resources moving shards between nodes, so we generally do not recommend adjusting this setting from its default of `2`. `cluster.routing.allocation.type` : Selects the algorithm used for computing the cluster balance. Defaults to `desired_balance` which selects the *desired balance allocator*. This allocator runs a background task which computes the desired balance of shards in the cluster. Once this background task completes, {{es}} moves shards to their desired locations. @@ -104,19 +104,19 @@ The weight of a node depends on the number of shards it holds and on the total e The following settings control how {{es}} combines these values into an overall measure of each node’s weight. `cluster.routing.allocation.balance.threshold` -: (float, [Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) The minimum improvement in weight which triggers a rebalancing shard movement. Defaults to `1.0f`. Raising this value will cause {{es}} to stop rebalancing shards sooner, leaving the cluster in a more unbalanced state. +: (float, [Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The minimum improvement in weight which triggers a rebalancing shard movement. Defaults to `1.0f`. Raising this value will cause {{es}} to stop rebalancing shards sooner, leaving the cluster in a more unbalanced state. `cluster.routing.allocation.balance.shard` -: (float, [Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Defines the weight factor for the total number of shards allocated to each node. Defaults to `0.45f`. Raising this value increases the tendency of {{es}} to equalize the total number of shards across nodes ahead of the other balancing variables. +: (float, [Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Defines the weight factor for the total number of shards allocated to each node. Defaults to `0.45f`. Raising this value increases the tendency of {{es}} to equalize the total number of shards across nodes ahead of the other balancing variables. `cluster.routing.allocation.balance.index` -: (float, [Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Defines the weight factor for the number of shards per index allocated to each node. Defaults to `0.55f`. Raising this value increases the tendency of {{es}} to equalize the number of shards of each index across nodes ahead of the other balancing variables. +: (float, [Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Defines the weight factor for the number of shards per index allocated to each node. Defaults to `0.55f`. Raising this value increases the tendency of {{es}} to equalize the number of shards of each index across nodes ahead of the other balancing variables. `cluster.routing.allocation.balance.disk_usage` -: (float, [Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Defines the weight factor for balancing shards according to their predicted disk size in bytes. Defaults to `2e-11f`. Raising this value increases the tendency of {{es}} to equalize the total disk usage across nodes ahead of the other balancing variables. +: (float, [Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Defines the weight factor for balancing shards according to their predicted disk size in bytes. Defaults to `2e-11f`. Raising this value increases the tendency of {{es}} to equalize the total disk usage across nodes ahead of the other balancing variables. `cluster.routing.allocation.balance.write_load` -: (float, [Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Defines the weight factor for the write load of each shard, in terms of the estimated number of indexing threads needed by the shard. Defaults to `10.0f`. Raising this value increases the tendency of {{es}} to equalize the total write load across nodes ahead of the other balancing variables. +: (float, [Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Defines the weight factor for the write load of each shard, in terms of the estimated number of indexing threads needed by the shard. Defaults to `10.0f`. Raising this value increases the tendency of {{es}} to equalize the total write load across nodes ahead of the other balancing variables. ::::{note} * If you have a large cluster, it may be unnecessary to keep it in a perfectly balanced state at all times. It is less resource-intensive for the cluster to operate in a somewhat unbalanced state rather than to perform all the shard movements needed to achieve the perfect balance. If so, increase the value of `cluster.routing.allocation.balance.threshold` to define the acceptable imbalance between nodes. For instance, if you have an average of 500 shards per node and can accept a difference of 5% (25 typical shards) between nodes, set `cluster.routing.allocation.balance.threshold` to `25`. @@ -173,35 +173,35 @@ You can use the following settings to control disk-based allocation: $$$cluster-routing-disk-threshold$$$ `cluster.routing.allocation.disk.threshold_enabled` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Defaults to `true`. Set to `false` to disable the disk allocation decider. Upon disabling, it will also remove any existing `index.blocks.read_only_allow_delete` index blocks. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Defaults to `true`. Set to `false` to disable the disk allocation decider. Upon disabling, it will also remove any existing `index.blocks.read_only_allow_delete` index blocks. $$$cluster-routing-watermark-low$$$ `cluster.routing.allocation.disk.watermark.low` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Controls the low watermark for disk usage. It defaults to `85%`, meaning that {{es}} will not allocate shards to nodes that have more than 85% disk used. It can alternatively be set to a ratio value, e.g., `0.85`. It can also be set to an absolute byte value (like `500mb`) to prevent {{es}} from allocating shards if less than the specified amount of space is available. This setting has no effect on the primary shards of newly-created indices but will prevent their replicas from being allocated. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Controls the low watermark for disk usage. It defaults to `85%`, meaning that {{es}} will not allocate shards to nodes that have more than 85% disk used. It can alternatively be set to a ratio value, e.g., `0.85`. It can also be set to an absolute byte value (like `500mb`) to prevent {{es}} from allocating shards if less than the specified amount of space is available. This setting has no effect on the primary shards of newly-created indices but will prevent their replicas from being allocated. `cluster.routing.allocation.disk.watermark.low.max_headroom` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Controls the max headroom for the low watermark (in case of a percentage/ratio value). Defaults to 200GB when `cluster.routing.allocation.disk.watermark.low` is not explicitly set. This caps the amount of free space required. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Controls the max headroom for the low watermark (in case of a percentage/ratio value). Defaults to 200GB when `cluster.routing.allocation.disk.watermark.low` is not explicitly set. This caps the amount of free space required. $$$cluster-routing-watermark-high$$$ `cluster.routing.allocation.disk.watermark.high` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Controls the high watermark. It defaults to `90%`, meaning that {{es}} will attempt to relocate shards away from a node whose disk usage is above 90%. It can alternatively be set to a ratio value, e.g., `0.9`. It can also be set to an absolute byte value (similarly to the low watermark) to relocate shards away from a node if it has less than the specified amount of free space. This setting affects the allocation of all shards, whether previously allocated or not. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Controls the high watermark. It defaults to `90%`, meaning that {{es}} will attempt to relocate shards away from a node whose disk usage is above 90%. It can alternatively be set to a ratio value, e.g., `0.9`. It can also be set to an absolute byte value (similarly to the low watermark) to relocate shards away from a node if it has less than the specified amount of free space. This setting affects the allocation of all shards, whether previously allocated or not. `cluster.routing.allocation.disk.watermark.high.max_headroom` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Controls the max headroom for the high watermark (in case of a percentage/ratio value). Defaults to 150GB when `cluster.routing.allocation.disk.watermark.high` is not explicitly set. This caps the amount of free space required. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Controls the max headroom for the high watermark (in case of a percentage/ratio value). Defaults to 150GB when `cluster.routing.allocation.disk.watermark.high` is not explicitly set. This caps the amount of free space required. `cluster.routing.allocation.disk.watermark.enable_for_single_data_node` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) In earlier releases, the default behaviour was to disregard disk watermarks for a single data node cluster when making an allocation decision. This is deprecated behavior since 7.14 and has been removed in 8.0. The only valid value for this setting is now `true`. The setting will be removed in a future release. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) In earlier releases, the default behaviour was to disregard disk watermarks for a single data node cluster when making an allocation decision. This is deprecated behavior since 7.14 and has been removed in 8.0. The only valid value for this setting is now `true`. The setting will be removed in a future release. $$$cluster-routing-flood-stage$$$ `cluster.routing.allocation.disk.watermark.flood_stage` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Controls the flood stage watermark, which defaults to 95%. {{es}} enforces a read-only index block ([`index.blocks.read_only_allow_delete`](/reference/elasticsearch/index-settings/index-block.md)) on every index that has one or more shards allocated on the node, and that has at least one disk exceeding the flood stage. This setting is a last resort to prevent nodes from running out of disk space. The index block is automatically released when the disk utilization falls below the high watermark. Similarly to the low and high watermark values, it can alternatively be set to a ratio value, e.g., `0.95`, or an absolute byte value. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Controls the flood stage watermark, which defaults to 95%. {{es}} enforces a read-only index block ([`index.blocks.read_only_allow_delete`](/reference/elasticsearch/index-settings/index-block.md)) on every index that has one or more shards allocated on the node, and that has at least one disk exceeding the flood stage. This setting is a last resort to prevent nodes from running out of disk space. The index block is automatically released when the disk utilization falls below the high watermark. Similarly to the low and high watermark values, it can alternatively be set to a ratio value, e.g., `0.95`, or an absolute byte value. `cluster.routing.allocation.disk.watermark.flood_stage.max_headroom` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Controls the max headroom for the flood stage watermark (in case of a percentage/ratio value). Defaults to 100GB when `cluster.routing.allocation.disk.watermark.flood_stage` is not explicitly set. This caps the amount of free space required. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Controls the max headroom for the flood stage watermark (in case of a percentage/ratio value). Defaults to 100GB when `cluster.routing.allocation.disk.watermark.flood_stage` is not explicitly set. This caps the amount of free space required. ::::{note} You can’t mix the usage of percentage/ratio values and byte values across the `cluster.routing.allocation.disk.watermark.low`, `cluster.routing.allocation.disk.watermark.high`, and `cluster.routing.allocation.disk.watermark.flood_stage` settings. Either all values must be set to percentage/ratio values, or all must be set to byte values. This is required so that {{es}} can validate that the settings are internally consistent, ensuring that the low disk threshold is less than the high disk threshold, and the high disk threshold is less than the flood stage threshold. A similar comparison check is done for the max headroom values. @@ -211,13 +211,13 @@ You can’t mix the usage of percentage/ratio values and byte values across the $$$cluster-routing-flood-stage-frozen$$$ `cluster.routing.allocation.disk.watermark.flood_stage.frozen` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Controls the flood stage watermark for dedicated frozen nodes, which defaults to 95%. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Controls the flood stage watermark for dedicated frozen nodes, which defaults to 95%. `cluster.routing.allocation.disk.watermark.flood_stage.frozen.max_headroom` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Controls the max headroom for the flood stage watermark (in case of a percentage/ratio value) for dedicated frozen nodes. Defaults to 20GB when `cluster.routing.allocation.disk.watermark.flood_stage.frozen` is not explicitly set. This caps the amount of free space required on dedicated frozen nodes. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Controls the max headroom for the flood stage watermark (in case of a percentage/ratio value) for dedicated frozen nodes. Defaults to 20GB when `cluster.routing.allocation.disk.watermark.flood_stage.frozen` is not explicitly set. This caps the amount of free space required on dedicated frozen nodes. `cluster.info.update.interval` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) How often {{es}} should check on disk usage for each node in the cluster. Defaults to `30s`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) How often {{es}} should check on disk usage for each node in the cluster. Defaults to `30s`. ::::{note} Percentage values refer to used disk space, while byte values refer to free disk space. This can be confusing, because it flips the meaning of high and low. For example, it makes sense to set the low watermark to 10gb and the high watermark to 5gb, but not the other way around. @@ -230,10 +230,10 @@ Percentage values refer to used disk space, while byte values refer to free disk You can use [custom node attributes](/reference/elasticsearch/configuration-reference/node-settings.md#custom-node-attributes) as *awareness attributes* to enable {{es}} to take your physical hardware configuration into account when allocating shards. If {{es}} knows which nodes are on the same physical server, in the same rack, or in the same zone, it can distribute the primary shard and its replica shards to minimize the risk of losing all shard copies in the event of a failure. [Learn more about shard allocation awareness](docs-content://deploy-manage/distributed-architecture/shard-allocation-relocation-recovery/shard-allocation-awareness.md). `cluster.routing.allocation.awareness.attributes` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) The node attributes that {{es}} should use as awareness attributes. For example, if you have a `rack_id` attribute that specifies the rack in which each node resides, you can set this setting to `rack_id` to ensure that primary and replica shards are not allocated on the same rack. You can specify multiple attributes as a comma-separated list. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The node attributes that {{es}} should use as awareness attributes. For example, if you have a `rack_id` attribute that specifies the rack in which each node resides, you can set this setting to `rack_id` to ensure that primary and replica shards are not allocated on the same rack. You can specify multiple attributes as a comma-separated list. `cluster.routing.allocation.awareness.force.*` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) The shard allocation awareness values that must exist for shards to be reallocated in case of location failure. Learn more about [forced awareness](docs-content://deploy-manage/distributed-architecture/shard-allocation-relocation-recovery/shard-allocation-awareness.md#forced-awareness). +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The shard allocation awareness values that must exist for shards to be reallocated in case of location failure. Learn more about [forced awareness](docs-content://deploy-manage/distributed-architecture/shard-allocation-relocation-recovery/shard-allocation-awareness.md#forced-awareness). ## Cluster-level shard allocation filtering [cluster-shard-allocation-filtering] @@ -242,7 +242,7 @@ You can use cluster-level shard allocation filters to control where {{es}} alloc Shard allocation filters can be based on [custom node attributes](/reference/elasticsearch/configuration-reference/node-settings.md#custom-node-attributes) or the built-in `_name`, `_host_ip`, `_publish_ip`, `_ip`, `_host`, `_id` and `_tier` attributes. -The `cluster.routing.allocation` settings are [dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting), enabling live indices to be moved from one set of nodes to another. Shards are only relocated if it is possible to do so without breaking another routing constraint, such as never allocating a primary and replica shard on the same node. +The `cluster.routing.allocation` settings are [Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), enabling live indices to be moved from one set of nodes to another. Shards are only relocated if it is possible to do so without breaking another routing constraint, such as never allocating a primary and replica shard on the same node. The most common use case for cluster-level shard allocation filtering is when you want to decommission a node. To move shards off of a node prior to shutting it down, you could create a filter that excludes the node by its IP address: @@ -258,13 +258,13 @@ PUT _cluster/settings ### Cluster routing settings [cluster-routing-settings] `cluster.routing.allocation.include.{{attribute}}` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Allocate shards to a node whose `{{attribute}}` has at least one of the comma-separated values. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Allocate shards to a node whose `{{attribute}}` has at least one of the comma-separated values. `cluster.routing.allocation.require.{{attribute}}` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Only allocate shards to a node whose `{{attribute}}` has *all* of the comma-separated values. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Only allocate shards to a node whose `{{attribute}}` has *all* of the comma-separated values. `cluster.routing.allocation.exclude.{{attribute}}` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Do not allocate shards to a node whose `{{attribute}}` has *any* of the comma-separated values. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Do not allocate shards to a node whose `{{attribute}}` has *any* of the comma-separated values. The cluster allocation settings support the following built-in attributes: @@ -309,4 +309,4 @@ PUT _cluster/settings ## Node Allocation Stats Cache [node-allocation-stats-cache] `cluster.routing.allocation.stats.cache.ttl` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Calculating the node allocation stats for a [Get node statistics API call](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-nodes-stats) can become expensive on the master for clusters with a high number of nodes. To prevent overloading the master the node allocation stats are cached on the master for 1 minute `1m` by default. This setting can be used to adjust the cache time to live value, if necessary, keeping in mind the tradeoff between the freshness of the statistics and the processing costs on the master. The cache can be disabled (not recommended) by setting the value to `0s` (the minimum value). The maximum value is 10 minutes `10m`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Calculating the node allocation stats for a [Get node statistics API call](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-nodes-stats) can become expensive on the master for clusters with a high number of nodes. To prevent overloading the master the node allocation stats are cached on the master for 1 minute `1m` by default. This setting can be used to adjust the cache time to live value, if necessary, keeping in mind the tradeoff between the freshness of the statistics and the processing costs on the master. The cache can be disabled (not recommended) by setting the value to `0s` (the minimum value). The maximum value is 10 minutes `10m`. diff --git a/docs/reference/elasticsearch/configuration-reference/cross-cluster-replication-settings.md b/docs/reference/elasticsearch/configuration-reference/cross-cluster-replication-settings.md index 58638af440441..1c30c7f509a9d 100644 --- a/docs/reference/elasticsearch/configuration-reference/cross-cluster-replication-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/cross-cluster-replication-settings.md @@ -15,7 +15,7 @@ These {{ccr}} settings can be dynamically updated on a live cluster with the [cl The following setting can be used to rate-limit the data transmitted during [remote recoveries](docs-content://deploy-manage/tools/cross-cluster-replication.md#ccr-remote-recovery): -`ccr.indices.recovery.max_bytes_per_sec` ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) +`ccr.indices.recovery.max_bytes_per_sec` ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) : Limits the total inbound and outbound remote recovery traffic on each node. Since this limit applies on each node, but there may be many nodes performing remote recoveries concurrently, the total amount of remote recovery bytes may be much higher than this limit. If you set this limit too high then there is a risk that ongoing remote recoveries will consume an excess of bandwidth (or other resources) which could destabilize the cluster. This setting is used by both the leader and follower clusters. For example if it is set to `20mb` on a leader, the leader will only send `20mb/s` to the follower even if the follower is requesting and can accept `60mb/s`. Defaults to `40mb`. @@ -23,15 +23,15 @@ The following setting can be used to rate-limit the data transmitted during [rem The following *expert* settings can be set to manage the resources consumed by remote recoveries: -`ccr.indices.recovery.max_concurrent_file_chunks` ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) +`ccr.indices.recovery.max_concurrent_file_chunks` ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) : Controls the number of file chunk requests that can be sent in parallel per recovery. As multiple remote recoveries might already running in parallel, increasing this expert-level setting might only help in situations where remote recovery of a single shard is not reaching the total inbound and outbound remote recovery traffic as configured by `ccr.indices.recovery.max_bytes_per_sec`. Defaults to `5`. The maximum allowed value is `10`. -`ccr.indices.recovery.chunk_size`([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) +`ccr.indices.recovery.chunk_size`([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) : Controls the chunk size requested by the follower during file transfer. Defaults to `1mb`. -`ccr.indices.recovery.recovery_activity_timeout`([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) +`ccr.indices.recovery.recovery_activity_timeout`([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) : Controls the timeout for recovery activity. This timeout primarily applies on the leader cluster. The leader cluster must open resources in-memory to supply data to the follower during the recovery process. If the leader does not receive recovery requests from the follower for this period of time, it will close the resources. Defaults to 60 seconds. -`ccr.indices.recovery.internal_action_timeout` ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) +`ccr.indices.recovery.internal_action_timeout` ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) : Controls the timeout for individual network requests during the remote recovery process. An individual action timing out can fail the recovery. Defaults to 60 seconds. diff --git a/docs/reference/elasticsearch/configuration-reference/data-stream-lifecycle-settings.md b/docs/reference/elasticsearch/configuration-reference/data-stream-lifecycle-settings.md index 34ed18422d46b..55a02fa6748e9 100644 --- a/docs/reference/elasticsearch/configuration-reference/data-stream-lifecycle-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/data-stream-lifecycle-settings.md @@ -17,22 +17,22 @@ These are the settings available for configuring [data stream lifecycle](docs-co $$$data-streams-lifecycle-retention-max$$$ `data_streams.lifecycle.retention.max` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting), [time unit value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) The maximum retention period that will apply to all user data streams managed by the data stream lifecycle. The max retention will also override the retention of a data stream whose configured retention exceeds the max retention. It should be greater than `10s`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), [time unit value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) The maximum retention period that will apply to all user data streams managed by the data stream lifecycle. The max retention will also override the retention of a data stream whose configured retention exceeds the max retention. It should be greater than `10s`. $$$data-streams-lifecycle-retention-default$$$ `data_streams.lifecycle.retention.default` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting), [time unit value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) The retention period that will apply to all user data streams managed by the data stream lifecycle that do not have retention configured. It should be greater than `10s` and less or equals than [`data_streams.lifecycle.retention.max`](#data-streams-lifecycle-retention-max). +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), [time unit value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) The retention period that will apply to all user data streams managed by the data stream lifecycle that do not have retention configured. It should be greater than `10s` and less or equals than [`data_streams.lifecycle.retention.max`](#data-streams-lifecycle-retention-max). $$$data-streams-lifecycle-poll-interval$$$ `data_streams.lifecycle.poll_interval` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting), [time unit value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) How often {{es}} checks what is the next action for all data streams with a built-in lifecycle. Defaults to `5m`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), [time unit value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) How often {{es}} checks what is the next action for all data streams with a built-in lifecycle. Defaults to `5m`. $$$cluster-lifecycle-default-rollover$$$ `cluster.lifecycle.default.rollover` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting), string) This property accepts a key value pair formatted string and configures the conditions that would trigger a data stream to [rollover](docs-content://manage-data/lifecycle/index-lifecycle-management/rollover.md) when it has `lifecycle` configured. This property is an implementation detail and subject to change. Currently, it defaults to `max_age=auto,max_primary_shard_size=50gb,min_docs=1,max_primary_shard_docs=200000000`, this means that your data stream will rollover if any of the following conditions are met: +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), string) This property accepts a key value pair formatted string and configures the conditions that would trigger a data stream to [rollover](docs-content://manage-data/lifecycle/index-lifecycle-management/rollover.md) when it has `lifecycle` configured. This property is an implementation detail and subject to change. Currently, it defaults to `max_age=auto,max_primary_shard_size=50gb,min_docs=1,max_primary_shard_docs=200000000`, this means that your data stream will rollover if any of the following conditions are met: * Either any primary shard reaches the size of 50GB, * or any primary shard contains 200.000.000 documents @@ -43,17 +43,17 @@ $$$cluster-lifecycle-default-rollover$$$ $$$data-streams-lifecycle-target-merge-factor$$$ `data_streams.lifecycle.target.merge.policy.merge_factor` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting), integer) Data stream lifecycle implements [tail merging](docs-content://manage-data/lifecycle/data-stream.md#data-streams-lifecycle-how-it-works) by updating the lucene merge policy factor for the target backing index. The merge factor is both the number of segments that should be merged together, and the maximum number of segments that we expect to find on a given tier. This setting controls what value does [Data stream lifecycle](docs-content://manage-data/lifecycle/data-stream.md) configures on the target index. It defaults to `16`. The value will be visible under the `index.merge.policy.merge_factor` index setting on the target index. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), integer) Data stream lifecycle implements [tail merging](docs-content://manage-data/lifecycle/data-stream.md#data-streams-lifecycle-how-it-works) by updating the lucene merge policy factor for the target backing index. The merge factor is both the number of segments that should be merged together, and the maximum number of segments that we expect to find on a given tier. This setting controls what value does [Data stream lifecycle](docs-content://manage-data/lifecycle/data-stream.md) configures on the target index. It defaults to `16`. The value will be visible under the `index.merge.policy.merge_factor` index setting on the target index. $$$data-streams-lifecycle-target-floor-segment$$$ `data_streams.lifecycle.target.merge.policy.floor_segment` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Data stream lifecycle implements [tail merging](docs-content://manage-data/lifecycle/data-stream.md#data-streams-lifecycle-how-it-works) by updating the lucene merge policy floor segment for the target backing index. This floor segment size is a way to prevent indices from having a long tail of very small segments. This setting controls what value does [data stream lifecycle](docs-content://manage-data/lifecycle/data-stream.md) configures on the target index. It defaults to `100MB`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Data stream lifecycle implements [tail merging](docs-content://manage-data/lifecycle/data-stream.md#data-streams-lifecycle-how-it-works) by updating the lucene merge policy floor segment for the target backing index. This floor segment size is a way to prevent indices from having a long tail of very small segments. This setting controls what value does [data stream lifecycle](docs-content://manage-data/lifecycle/data-stream.md) configures on the target index. It defaults to `100MB`. $$$data-streams-lifecycle-signalling-error-retry-interval$$$ `data_streams.lifecycle.signalling.error_retry_interval` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting), integer) Represents the number of retries data stream lifecycle has to perform for an index in an error step in order to signal that the index is not progressing (i.e. it’s stuck in an error step). The current signalling mechanism is a log statement at the `error` level however, the signalling mechanism can be extended in the future. Defaults to 10 retries. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), integer) Represents the number of retries data stream lifecycle has to perform for an index in an error step in order to signal that the index is not progressing (i.e. it’s stuck in an error step). The current signalling mechanism is a log statement at the `error` level however, the signalling mechanism can be extended in the future. Defaults to 10 retries. ## Index level settings [_index_level_settings] @@ -63,9 +63,17 @@ The following index-level settings are typically configured on the backing indic $$$index-lifecycle-prefer-ilm$$$ `index.lifecycle.prefer_ilm` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-settings), boolean) This setting determines which feature is managing the backing index of a data stream if, and only if, the backing index has an [{{ilm}}](docs-content://manage-data/lifecycle/index-lifecycle-management.md) ({{ilm-init}}) policy and the data stream has also a built-in lifecycle. When `true` this index is managed by {{ilm-init}}, when `false` the backing index is managed by the data stream lifecycle. Defaults to `true`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), boolean) This setting determines which feature is managing the backing index of a data stream if, and only if, the backing index has an [{{ilm}}](docs-content://manage-data/lifecycle/index-lifecycle-management.md) ({{ilm-init}}) policy and the data stream has also a built-in lifecycle. When `true` this index is managed by {{ilm-init}}, when `false` the backing index is managed by the data stream lifecycle. Defaults to `true`. $$$index-data-stream-lifecycle-origination-date$$$ `index.lifecycle.origination_date` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-settings), long) If specified, this is the timestamp used to calculate the backing index generation age after this backing index has been [rolled over](docs-content://manage-data/lifecycle/index-lifecycle-management/rollover.md). The generation age is used to determine data retention, consequently, you can use this setting if you create a backing index that contains older data and want to ensure that the retention period or other parts of the lifecycle will be applied based on the data’s original timestamp and not the timestamp they got indexed. Specified as a Unix epoch value in milliseconds. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), long) If specified, this is the timestamp used to calculate the backing index generation age after this backing index has been [rolled over](docs-content://manage-data/lifecycle/index-lifecycle-management/rollover.md). The generation age is used to determine data retention, consequently, you can use this setting if you create a backing index that contains older data and want to ensure that the retention period or other parts of the lifecycle will be applied based on the data’s original timestamp and not the timestamp they got indexed. Specified as a Unix epoch value in milliseconds. + +## Reindex settings [reindex-data-stream-settings] + +You can use the following settings to control the behavior of the reindex data stream API: + +`migrate.max_concurrent_indices_reindexed_per_data_stream` ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The number of backing indices within a given data stream which will be reindexed concurrently. Defaults to `1`. + +`migrate.data_stream_reindex_max_request_per_second` ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The average maximum number of documents within a given backing index to reindex per second. Defaults to `1000`, though can be any decimal number greater than `0`. To remove throttling, set to `-1`. This setting can be used to throttle the reindex process and manage resource usage. Consult the [reindex throttle docs](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-reindex#docs-reindex-throttle) for more information. \ No newline at end of file diff --git a/docs/reference/elasticsearch/configuration-reference/discovery-cluster-formation-settings.md b/docs/reference/elasticsearch/configuration-reference/discovery-cluster-formation-settings.md index 5458f9a35640a..94b98ed909b38 100644 --- a/docs/reference/elasticsearch/configuration-reference/discovery-cluster-formation-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/discovery-cluster-formation-settings.md @@ -11,7 +11,7 @@ applies_to: [Discovery and cluster formation](docs-content://deploy-manage/distributed-architecture/discovery-cluster-formation.md) are affected by the following settings: `discovery.seed_hosts` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Provides a list of the addresses of the master-eligible nodes in the cluster. May also be a single string containing the addresses separated by commas. Each address has the format `host:port` or `host`. The `host` is either a host name to be resolved by DNS, an IPv4 address, or an IPv6 address. IPv6 addresses must be enclosed in square brackets. If a host name resolves via DNS to multiple addresses, {{es}} uses all of them. DNS lookups are subject to [JVM DNS caching](docs-content://deploy-manage/deploy/self-managed/networkaddress-cache-ttl.md). If the `port` is not given then it is determined by checking the following settings in order: +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Provides a list of the addresses of the master-eligible nodes in the cluster. May also be a single string containing the addresses separated by commas. Each address has the format `host:port` or `host`. The `host` is either a host name to be resolved by DNS, an IPv4 address, or an IPv6 address. IPv6 addresses must be enclosed in square brackets. If a host name resolves via DNS to multiple addresses, {{es}} uses all of them. DNS lookups are subject to [JVM DNS caching](docs-content://deploy-manage/deploy/self-managed/networkaddress-cache-ttl.md). If the `port` is not given then it is determined by checking the following settings in order: 1. `transport.profiles.default.port` 2. `transport.port` @@ -19,13 +19,13 @@ applies_to: `discovery.seed_providers` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies which types of [seed hosts provider](docs-content://deploy-manage/distributed-architecture/discovery-cluster-formation/discovery-hosts-providers.md#built-in-hosts-providers) to use to obtain the addresses of the seed nodes used to start the discovery process. By default, it is the [settings-based seed hosts provider](docs-content://deploy-manage/distributed-architecture/discovery-cluster-formation/discovery-hosts-providers.md#settings-based-hosts-provider) which obtains the seed node addresses from the `discovery.seed_hosts` setting. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies which types of [seed hosts provider](docs-content://deploy-manage/distributed-architecture/discovery-cluster-formation/discovery-hosts-providers.md#built-in-hosts-providers) to use to obtain the addresses of the seed nodes used to start the discovery process. By default, it is the [settings-based seed hosts provider](docs-content://deploy-manage/distributed-architecture/discovery-cluster-formation/discovery-hosts-providers.md#settings-based-hosts-provider) which obtains the seed node addresses from the `discovery.seed_hosts` setting. `discovery.type` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies whether {{es}} should form a multiple-node cluster. Defaults to `multi-node`, which means that {{es}} discovers other nodes when forming a cluster and allows other nodes to join the cluster later. If set to `single-node`, {{es}} forms a single-node cluster and suppresses the timeout set by `cluster.publish.timeout`. For more information about when you might use this setting, see [Single-node discovery](docs-content://deploy-manage/deploy/self-managed/bootstrap-checks.md#single-node-discovery). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies whether {{es}} should form a multiple-node cluster. Defaults to `multi-node`, which means that {{es}} discovers other nodes when forming a cluster and allows other nodes to join the cluster later. If set to `single-node`, {{es}} forms a single-node cluster and suppresses the timeout set by `cluster.publish.timeout`. For more information about when you might use this setting, see [Single-node discovery](docs-content://deploy-manage/deploy/self-managed/bootstrap-checks.md#single-node-discovery). `cluster.initial_master_nodes` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets the initial set of master-eligible nodes in a brand-new cluster. By default this list is empty, meaning that this node expects to join a cluster that has already been bootstrapped. Remove this setting once the cluster has formed, and never set it again for this cluster. Do not configure this setting on master-ineligible nodes. Do not configure this setting on nodes joining an existing cluster. Do not configure this setting on nodes which are restarting. Do not configure this setting when performing a full-cluster restart. See [`cluster.initial_master_nodes`](docs-content://deploy-manage/deploy/self-managed/important-settings-configuration.md#initial_master_nodes). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets the initial set of master-eligible nodes in a brand-new cluster. By default this list is empty, meaning that this node expects to join a cluster that has already been bootstrapped. Remove this setting once the cluster has formed, and never set it again for this cluster. Do not configure this setting on master-ineligible nodes. Do not configure this setting on nodes joining an existing cluster. Do not configure this setting on nodes which are restarting. Do not configure this setting when performing a full-cluster restart. See [`cluster.initial_master_nodes`](docs-content://deploy-manage/deploy/self-managed/important-settings-configuration.md#initial_master_nodes). ## Expert settings [_expert_settings] @@ -38,84 +38,84 @@ If you adjust these settings then your cluster may not form correctly or may bec `discovery.cluster_formation_warning_timeout` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets how long a node will try to form a cluster before logging a warning that the cluster did not form. Defaults to `10s`. If a cluster has not formed after `discovery.cluster_formation_warning_timeout` has elapsed then the node will log a warning message that starts with the phrase `master not discovered` which describes the current state of the discovery process. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets how long a node will try to form a cluster before logging a warning that the cluster did not form. Defaults to `10s`. If a cluster has not formed after `discovery.cluster_formation_warning_timeout` has elapsed then the node will log a warning message that starts with the phrase `master not discovered` which describes the current state of the discovery process. `discovery.find_peers_interval` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets how long a node will wait before attempting another discovery round. Defaults to `1s`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets how long a node will wait before attempting another discovery round. Defaults to `1s`. `discovery.probe.connect_timeout` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets how long to wait when attempting to connect to each address. Defaults to `30s`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets how long to wait when attempting to connect to each address. Defaults to `30s`. `discovery.probe.handshake_timeout` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets how long to wait when attempting to identify the remote node via a handshake. Defaults to `30s`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets how long to wait when attempting to identify the remote node via a handshake. Defaults to `30s`. `discovery.request_peers_timeout` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets how long a node will wait after asking its peers again before considering the request to have failed. Defaults to `3s`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets how long a node will wait after asking its peers again before considering the request to have failed. Defaults to `3s`. `discovery.find_peers_warning_timeout` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets how long a node will attempt to discover its peers before it starts to log verbose messages describing why the connection attempts are failing. Defaults to `3m`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets how long a node will attempt to discover its peers before it starts to log verbose messages describing why the connection attempts are failing. Defaults to `3m`. `discovery.seed_resolver.max_concurrent_resolvers` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies how many concurrent DNS lookups to perform when resolving the addresses of seed nodes. Defaults to `10`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies how many concurrent DNS lookups to perform when resolving the addresses of seed nodes. Defaults to `10`. `discovery.seed_resolver.timeout` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies how long to wait for each DNS lookup performed when resolving the addresses of seed nodes. Defaults to `5s`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies how long to wait for each DNS lookup performed when resolving the addresses of seed nodes. Defaults to `5s`. `cluster.auto_shrink_voting_configuration` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Controls whether the [voting configuration](docs-content://deploy-manage/distributed-architecture/discovery-cluster-formation/modules-discovery-voting.md) sheds departed nodes automatically, as long as it still contains at least 3 nodes. The default value is `true`. If set to `false`, the voting configuration never shrinks automatically and you must remove departed nodes manually with the [voting configuration exclusions API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-post-voting-config-exclusions). +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Controls whether the [voting configuration](docs-content://deploy-manage/distributed-architecture/discovery-cluster-formation/modules-discovery-voting.md) sheds departed nodes automatically, as long as it still contains at least 3 nodes. The default value is `true`. If set to `false`, the voting configuration never shrinks automatically and you must remove departed nodes manually with the [voting configuration exclusions API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-post-voting-config-exclusions). $$$master-election-settings$$$`cluster.election.back_off_time` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets the amount to increase the upper bound on the wait before an election on each election failure. Note that this is *linear* backoff. This defaults to `100ms`. Changing this setting from the default may cause your cluster to fail to elect a master node. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets the amount to increase the upper bound on the wait before an election on each election failure. Note that this is *linear* backoff. This defaults to `100ms`. Changing this setting from the default may cause your cluster to fail to elect a master node. `cluster.election.duration` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets how long each election is allowed to take before a node considers it to have failed and schedules a retry. This defaults to `500ms`. Changing this setting from the default may cause your cluster to fail to elect a master node. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets how long each election is allowed to take before a node considers it to have failed and schedules a retry. This defaults to `500ms`. Changing this setting from the default may cause your cluster to fail to elect a master node. `cluster.election.initial_timeout` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets the upper bound on how long a node will wait initially, or after the elected master fails, before attempting its first election. This defaults to `100ms`. Changing this setting from the default may cause your cluster to fail to elect a master node. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets the upper bound on how long a node will wait initially, or after the elected master fails, before attempting its first election. This defaults to `100ms`. Changing this setting from the default may cause your cluster to fail to elect a master node. `cluster.election.max_timeout` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets the maximum upper bound on how long a node will wait before attempting an first election, so that an network partition that lasts for a long time does not result in excessively sparse elections. This defaults to `10s`. Changing this setting from the default may cause your cluster to fail to elect a master node. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets the maximum upper bound on how long a node will wait before attempting an first election, so that an network partition that lasts for a long time does not result in excessively sparse elections. This defaults to `10s`. Changing this setting from the default may cause your cluster to fail to elect a master node. $$$fault-detection-settings$$$`cluster.fault_detection.follower_check.interval` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets how long the elected master waits between follower checks to each other node in the cluster. Defaults to `1s`. Changing this setting from the default may cause your cluster to become unstable. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets how long the elected master waits between follower checks to each other node in the cluster. Defaults to `1s`. Changing this setting from the default may cause your cluster to become unstable. `cluster.fault_detection.follower_check.timeout` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets how long the elected master waits for a response to a follower check before considering it to have failed. Defaults to `10s`. Changing this setting from the default may cause your cluster to become unstable. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets how long the elected master waits for a response to a follower check before considering it to have failed. Defaults to `10s`. Changing this setting from the default may cause your cluster to become unstable. `cluster.fault_detection.follower_check.retry_count` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets how many consecutive follower check failures must occur to each node before the elected master considers that node to be faulty and removes it from the cluster. Defaults to `3`. Changing this setting from the default may cause your cluster to become unstable. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets how many consecutive follower check failures must occur to each node before the elected master considers that node to be faulty and removes it from the cluster. Defaults to `3`. Changing this setting from the default may cause your cluster to become unstable. `cluster.fault_detection.leader_check.interval` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets how long each node waits between checks of the elected master. Defaults to `1s`. Changing this setting from the default may cause your cluster to become unstable. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets how long each node waits between checks of the elected master. Defaults to `1s`. Changing this setting from the default may cause your cluster to become unstable. `cluster.fault_detection.leader_check.timeout` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets how long each node waits for a response to a leader check from the elected master before considering it to have failed. Defaults to `10s`. Changing this setting from the default may cause your cluster to become unstable. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets how long each node waits for a response to a leader check from the elected master before considering it to have failed. Defaults to `10s`. Changing this setting from the default may cause your cluster to become unstable. `cluster.fault_detection.leader_check.retry_count` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets how many consecutive leader check failures must occur before a node considers the elected master to be faulty and attempts to find or elect a new master. Defaults to `3`. Changing this setting from the default may cause your cluster to become unstable. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets how many consecutive leader check failures must occur before a node considers the elected master to be faulty and attempts to find or elect a new master. Defaults to `3`. Changing this setting from the default may cause your cluster to become unstable. `cluster.follower_lag.timeout` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets how long the master node waits to receive acknowledgements for cluster state updates from lagging nodes. The default value is `90s`. If a node does not successfully apply the cluster state update within this period of time, it is considered to have failed and is removed from the cluster. See [Publishing the cluster state](docs-content://deploy-manage/distributed-architecture/discovery-cluster-formation/cluster-state-overview.md#cluster-state-publishing). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets how long the master node waits to receive acknowledgements for cluster state updates from lagging nodes. The default value is `90s`. If a node does not successfully apply the cluster state update within this period of time, it is considered to have failed and is removed from the cluster. See [Publishing the cluster state](docs-content://deploy-manage/distributed-architecture/discovery-cluster-formation/cluster-state-overview.md#cluster-state-publishing). `cluster.max_voting_config_exclusions` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Sets a limit on the number of voting configuration exclusions at any one time. The default value is `10`. See [*Add and remove nodes in your cluster*](docs-content://deploy-manage/maintenance/add-and-remove-elasticsearch-nodes.md). +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Sets a limit on the number of voting configuration exclusions at any one time. The default value is `10`. See [*Add and remove nodes in your cluster*](docs-content://deploy-manage/maintenance/add-and-remove-elasticsearch-nodes.md). `cluster.publish.info_timeout` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets how long the master node waits for each cluster state update to be completely published to all nodes before logging a message indicating that some nodes are responding slowly. The default value is `10s`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets how long the master node waits for each cluster state update to be completely published to all nodes before logging a message indicating that some nodes are responding slowly. The default value is `10s`. `cluster.publish.timeout` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets how long the master node waits for each cluster state update to be completely published to all nodes, unless `discovery.type` is set to `single-node`. The default value is `30s`. See [Publishing the cluster state](docs-content://deploy-manage/distributed-architecture/discovery-cluster-formation/cluster-state-overview.md#cluster-state-publishing). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets how long the master node waits for each cluster state update to be completely published to all nodes, unless `discovery.type` is set to `single-node`. The default value is `30s`. See [Publishing the cluster state](docs-content://deploy-manage/distributed-architecture/discovery-cluster-formation/cluster-state-overview.md#cluster-state-publishing). `cluster.discovery_configuration_check.interval` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets the interval of some checks that will log warnings about an incorrect discovery configuration. The default value is `30s`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets the interval of some checks that will log warnings about an incorrect discovery configuration. The default value is `30s`. `cluster.join_validation.cache_timeout` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) When a node requests to join the cluster, the elected master node sends it a copy of a recent cluster state to detect certain problems which might prevent the new node from joining the cluster. The master caches the state it sends and uses the cached state if another node joins the cluster soon after. This setting controls how long the master waits until it clears this cache. Defaults to `60s`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) When a node requests to join the cluster, the elected master node sends it a copy of a recent cluster state to detect certain problems which might prevent the new node from joining the cluster. The master caches the state it sends and uses the cached state if another node joins the cluster soon after. This setting controls how long the master waits until it clears this cache. Defaults to `60s`. $$$no-master-block$$$ `cluster.no_master_block` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Specifies which operations are rejected when there is no active master in a cluster. This setting has three valid values: +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Specifies which operations are rejected when there is no active master in a cluster. This setting has three valid values: `all` : All operations on the node (both read and write operations) are rejected. This also applies for API cluster state read or write operations, like the get index settings, update mapping, and cluster state API. @@ -134,11 +134,11 @@ $$$no-master-block$$$ `monitor.fs.health.enabled` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) If `true`, the node runs periodic [filesystem health checks](docs-content://deploy-manage/distributed-architecture/discovery-cluster-formation/cluster-fault-detection.md#cluster-fault-detection-filesystem-health). Defaults to `true`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) If `true`, the node runs periodic [filesystem health checks](docs-content://deploy-manage/distributed-architecture/discovery-cluster-formation/cluster-fault-detection.md#cluster-fault-detection-filesystem-health). Defaults to `true`. `monitor.fs.health.refresh_interval` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Interval between successive [filesystem health checks](docs-content://deploy-manage/distributed-architecture/discovery-cluster-formation/cluster-fault-detection.md#cluster-fault-detection-filesystem-health). Defaults to `2m`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Interval between successive [filesystem health checks](docs-content://deploy-manage/distributed-architecture/discovery-cluster-formation/cluster-fault-detection.md#cluster-fault-detection-filesystem-health). Defaults to `2m`. `monitor.fs.health.slow_path_logging_threshold` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) If a [filesystem health checks](docs-content://deploy-manage/distributed-architecture/discovery-cluster-formation/cluster-fault-detection.md#cluster-fault-detection-filesystem-health) takes longer than this threshold then {{es}} logs a warning. Defaults to `5s`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) If a [filesystem health checks](docs-content://deploy-manage/distributed-architecture/discovery-cluster-formation/cluster-fault-detection.md#cluster-fault-detection-filesystem-health) takes longer than this threshold then {{es}} logs a warning. Defaults to `5s`. diff --git a/docs/reference/elasticsearch/configuration-reference/field-data-cache-settings.md b/docs/reference/elasticsearch/configuration-reference/field-data-cache-settings.md index 9d1f0d26f2768..90e028a5f8d07 100644 --- a/docs/reference/elasticsearch/configuration-reference/field-data-cache-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/field-data-cache-settings.md @@ -22,5 +22,5 @@ You can monitor memory usage for field data as well as the field data circuit br `indices.fielddata.cache.size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The max size of the field data cache, eg `38%` of node heap space, or an absolute value, eg `12GB`. Defaults to unbounded. If you choose to set it, it should be smaller than [Field data circuit breaker](/reference/elasticsearch/configuration-reference/circuit-breaker-settings.md#fielddata-circuit-breaker) limit. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The max size of the field data cache, eg `38%` of node heap space, or an absolute value, eg `12GB`. Defaults to unbounded. If you choose to set it, it should be smaller than [Field data circuit breaker](/reference/elasticsearch/configuration-reference/circuit-breaker-settings.md#fielddata-circuit-breaker) limit. diff --git a/docs/reference/elasticsearch/configuration-reference/health-diagnostic-settings.md b/docs/reference/elasticsearch/configuration-reference/health-diagnostic-settings.md index 21d7932b31b2f..eebec8399af52 100644 --- a/docs/reference/elasticsearch/configuration-reference/health-diagnostic-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/health-diagnostic-settings.md @@ -15,36 +15,36 @@ The following are the *expert-level* settings available for configuring an inter ## Cluster level settings [_cluster_level_settings_2] `health.master_history.has_master_lookup_timeframe` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The amount of time a node looks back to see if it has observed a master at all, before moving on with other checks. Defaults to `30s` (30 seconds). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The amount of time a node looks back to see if it has observed a master at all, before moving on with other checks. Defaults to `30s` (30 seconds). `master_history.max_age` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The timeframe we record the master history to be used for diagnosing the cluster health. Master node changes older than this time will not be considered when diagnosing the cluster health. Defaults to `30m` (30 minutes). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The timeframe we record the master history to be used for diagnosing the cluster health. Master node changes older than this time will not be considered when diagnosing the cluster health. Defaults to `30m` (30 minutes). `health.master_history.identity_changes_threshold` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The number of master identity changes witnessed by a node that indicates the cluster is not healthy. Defaults to `4`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The number of master identity changes witnessed by a node that indicates the cluster is not healthy. Defaults to `4`. `health.master_history.no_master_transitions_threshold` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The number of transitions to no master witnessed by a node that indicates the cluster is not healthy. Defaults to `4`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The number of transitions to no master witnessed by a node that indicates the cluster is not healthy. Defaults to `4`. `health.node.enabled` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Enables the health node, which allows the health API to provide indications about cluster wide health aspects such as disk space. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Enables the health node, which allows the health API to provide indications about cluster wide health aspects such as disk space. `health.reporting.local.monitor.interval` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Determines the interval in which each node of the cluster monitors aspects that comprise its local health such as its disk usage. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Determines the interval in which each node of the cluster monitors aspects that comprise its local health such as its disk usage. `health.ilm.max_time_on_action` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) The minimum amount of time an index has to be in an {{ilm}} ({{ilm-init}}) action before it is considered stagnant. Defaults to `1d` (1 day). +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The minimum amount of time an index has to be in an {{ilm}} ({{ilm-init}}) action before it is considered stagnant. Defaults to `1d` (1 day). `health.ilm.max_time_on_step` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) The minimum amount of time an index has to be in an {{ilm-init}} step before it is considered stagnant. Defaults to `1d` (1 day). +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The minimum amount of time an index has to be in an {{ilm-init}} step before it is considered stagnant. Defaults to `1d` (1 day). `health.ilm.max_retries_per_step` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) The minimum amount of times an index has retried by an {{ilm-init}} step before it is considered stagnant. Defaults to `100` +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The minimum amount of times an index has retried by an {{ilm-init}} step before it is considered stagnant. Defaults to `100` `health.periodic_logger.enabled` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Enables the health periodic logger, which logs the health statuses of each health indicator along with the top level one as observed by the Health API. Defaults to `false`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Enables the health periodic logger, which logs the health statuses of each health indicator along with the top level one as observed by the Health API. Defaults to `false`. `health.periodic_logger.poll_interval` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings), [time unit value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) How often {{es}} logs the health status of the cluster and of each health indicator as observed by the Health API. Defaults to `60s` (60 seconds). +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), [time unit value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) How often {{es}} logs the health status of the cluster and of each health indicator as observed by the Health API. Defaults to `60s` (60 seconds). diff --git a/docs/reference/elasticsearch/configuration-reference/index-lifecycle-management-settings.md b/docs/reference/elasticsearch/configuration-reference/index-lifecycle-management-settings.md index d1363a3aee318..75c2b54ad9dd3 100644 --- a/docs/reference/elasticsearch/configuration-reference/index-lifecycle-management-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/index-lifecycle-management-settings.md @@ -15,24 +15,24 @@ These are the settings available for configuring [{{ilm}}](docs-content://manage ## Cluster level settings [_cluster_level_settings_3] `xpack.ilm.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), Boolean) +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), Boolean) :::{admonition} Deprecated in 7.8.0 This deprecated setting has no effect and will be removed in Elasticsearch 8.0. ::: `indices.lifecycle.history_index_enabled` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting), Boolean) Whether ILM’s history index is enabled. If enabled, ILM will record the history of actions taken as part of ILM policies to the `ilm-history-*` indices. Defaults to `true`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), Boolean) Whether ILM’s history index is enabled. If enabled, ILM will record the history of actions taken as part of ILM policies to the `ilm-history-*` indices. Defaults to `true`. $$$indices-lifecycle-poll-interval$$$ `indices.lifecycle.poll_interval` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting), [time unit value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) How often {{ilm}} checks for indices that meet policy criteria. Defaults to `10m`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), [time unit value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) How often {{ilm}} checks for indices that meet policy criteria. Defaults to `10m`. $$$indices-lifecycle-rollover-only-if-has-documents$$$ `indices.lifecycle.rollover.only_if_has_documents` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting), Boolean) Whether ILM will only roll over non-empty indices. If enabled, ILM will only roll over indices as long as they contain at least one document. Defaults to `true`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), Boolean) Whether ILM will only roll over non-empty indices. If enabled, ILM will only roll over indices as long as they contain at least one document. Defaults to `true`. ## Index level settings [_index_level_settings_2] @@ -40,31 +40,31 @@ $$$indices-lifecycle-rollover-only-if-has-documents$$$ These index-level {{ilm-init}} settings are typically configured through index templates. For more information, see [Create a lifecycle policy](docs-content://manage-data/lifecycle/index-lifecycle-management/tutorial-automate-rollover.md#ilm-gs-create-policy). `index.lifecycle.indexing_complete` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-settings), Boolean) Indicates whether or not the index has been rolled over. Automatically set to `true` when {{ilm-init}} completes the rollover action. You can explicitly set it to [skip rollover](docs-content://manage-data/lifecycle/index-lifecycle-management/skip-rollover.md). Defaults to `false`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), Boolean) Indicates whether or not the index has been rolled over. Automatically set to `true` when {{ilm-init}} completes the rollover action. You can explicitly set it to [skip rollover](docs-content://manage-data/lifecycle/index-lifecycle-management/skip-rollover.md). Defaults to `false`. $$$index-lifecycle-name$$$ `index.lifecycle.name` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-settings), string) The name of the policy to use to manage the index. For information about how {{es}} applies policy changes, see [Policy updates](docs-content://manage-data/lifecycle/index-lifecycle-management/policy-updates.md). If you are restoring an index from snapshot that was previously managed by {{ilm}}, you can override this setting to null during the restore operation to disable further management of the index. See also [Index level settings](#index-lifecycle-rollover-alias). +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), string) The name of the policy to use to manage the index. For information about how {{es}} applies policy changes, see [Policy updates](docs-content://manage-data/lifecycle/index-lifecycle-management/policy-updates.md). If you are restoring an index from snapshot that was previously managed by {{ilm}}, you can override this setting to null during the restore operation to disable further management of the index. See also [Index level settings](#index-lifecycle-rollover-alias). $$$index-lifecycle-origination-date$$$ `index.lifecycle.origination_date` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-settings), long) If specified, this is the timestamp used to calculate the index age for its phase transitions. Use this setting if you create a new index that contains old data and want to use the original creation date to calculate the index age. Specified as a Unix epoch value in milliseconds. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), long) If specified, this is the timestamp used to calculate the index age for its phase transitions. Use this setting if you create a new index that contains old data and want to use the original creation date to calculate the index age. Specified as a Unix epoch value in milliseconds. $$$index-lifecycle-parse-origination-date$$$ `index.lifecycle.parse_origination_date` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-settings), Boolean) Set to `true` to parse the origination date from the index name. This origination date is used to calculate the index age for its phase transitions. The index name must match the pattern `^.*-{{date_format}}-\\d+`, where the `date_format` is `yyyy.MM.dd` and the trailing digits are optional. An index that was rolled over would normally match the full format, for example `logs-2016.10.31-000002`). If the index name doesn’t match the pattern, index creation fails. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), Boolean) Set to `true` to parse the origination date from the index name. This origination date is used to calculate the index age for its phase transitions. The index name must match the pattern `^.*-{{date_format}}-\\d+`, where the `date_format` is `yyyy.MM.dd` and the trailing digits are optional. An index that was rolled over would normally match the full format, for example `logs-2016.10.31-000002`). If the index name doesn’t match the pattern, index creation fails. $$$index-lifecycle-step-wait-time-threshold$$$ `index.lifecycle.step.wait_time_threshold` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-settings), [time value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) Time to wait for the cluster to resolve allocation issues during an {{ilm-init}} [`shrink`](/reference/elasticsearch/index-lifecycle-actions/ilm-shrink.md) action. Must be greater than `1h` (1 hour). Defaults to `12h` (12 hours). See [Shard allocation for shrink](/reference/elasticsearch/index-lifecycle-actions/ilm-shrink.md#ilm-shrink-shard-allocation). +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), [time value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) Time to wait for the cluster to resolve allocation issues during an {{ilm-init}} [`shrink`](/reference/elasticsearch/index-lifecycle-actions/ilm-shrink.md) action. Must be greater than `1h` (1 hour). Defaults to `12h` (12 hours). See [Shard allocation for shrink](/reference/elasticsearch/index-lifecycle-actions/ilm-shrink.md#ilm-shrink-shard-allocation). $$$index-lifecycle-rollover-alias$$$ `index.lifecycle.rollover_alias` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-settings), string) The index alias to update when the index rolls over. Specify when using a policy that contains a rollover action. When the index rolls over, the alias is updated to reflect that the index is no longer the write index. For more information about rolling indices, see [Rollover](docs-content://manage-data/lifecycle/index-lifecycle-management/rollover.md). If you are restoring an index from snapshot that was previously managed by {{ilm}}, you can override this setting to null during the restore operation to disable further management of future indices. See also [Index level settings](#index-lifecycle-name). +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), string) The index alias to update when the index rolls over. Specify when using a policy that contains a rollover action. When the index rolls over, the alias is updated to reflect that the index is no longer the write index. For more information about rolling indices, see [Rollover](docs-content://manage-data/lifecycle/index-lifecycle-management/rollover.md). If you are restoring an index from snapshot that was previously managed by {{ilm}}, you can override this setting to null during the restore operation to disable further management of future indices. See also [Index level settings](#index-lifecycle-name). diff --git a/docs/reference/elasticsearch/configuration-reference/index-management-settings.md b/docs/reference/elasticsearch/configuration-reference/index-management-settings.md index 602061e057ee7..7b2aac4f20a90 100644 --- a/docs/reference/elasticsearch/configuration-reference/index-management-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/index-management-settings.md @@ -14,17 +14,17 @@ You can use the following cluster settings to enable or disable index management $$$auto-create-index$$$ `action.auto_create_index` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) [Automatically create an index](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-create) if it doesn’t already exist and apply any configured index templates. Defaults to `true`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) [Automatically create an index](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-create) if it doesn’t already exist and apply any configured index templates. Defaults to `true`. $$$action-destructive-requires-name$$$ `action.destructive_requires_name` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) When set to `true`, you must specify the index name to [delete an index](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-delete). It is not possible to delete all indices with `_all` or use wildcards. Defaults to `true`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) When set to `true`, you must specify the index name to [delete an index](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-delete). It is not possible to delete all indices with `_all` or use wildcards. Defaults to `true`. $$$cluster-indices-close-enable$$$ `cluster.indices.close.enable` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Enables [closing of open indices](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-close) in {{es}}. If `false`, you cannot close open indices. Defaults to `true` for versions 7.2.0 and later, and to `false` for previous versions. In versions 7.1 and below, closed indices represent a data loss risk: if you close an index, it is not included in snapshots and you will not be able to restore the data. Similarly, closed indices are not included when you make cluster configuration changes, such as scaling to a different capacity, failover, and many other operations. Lastly, closed indices can lead to inaccurate disk space counts. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Enables [closing of open indices](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-close) in {{es}}. If `false`, you cannot close open indices. Defaults to `true` for versions 7.2.0 and later, and to `false` for previous versions. In versions 7.1 and below, closed indices represent a data loss risk: if you close an index, it is not included in snapshots and you will not be able to restore the data. Similarly, closed indices are not included when you make cluster configuration changes, such as scaling to a different capacity, failover, and many other operations. Lastly, closed indices can lead to inaccurate disk space counts. ::::{warning} For versions 7.1 and below, closed indices represent a data loss risk. Enable this setting only temporarily for these versions. @@ -38,7 +38,7 @@ $$$cluster-indices-close-enable$$$ $$$stack-templates-enabled$$$ `stack.templates.enabled` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) If `true`, enables built-in index and component templates. [{{agent}}](docs-content://reference/fleet/index.md) uses these templates to create data streams. If `false`, {{es}} disables these index and component templates. Defaults to `true`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) If `true`, enables built-in index and component templates. [{{agent}}](docs-content://reference/fleet/index.md) uses these templates to create data streams. If `false`, {{es}} disables these index and component templates. Defaults to `true`. ::::{note} It is not recommended to disable the built-in stack templates, as some functionality of {{es}} or Kibana will not work correctly when disabled. Features like log and metric collection, as well as Kibana reporting, may malfunction without the built-in stack templates. Stack templates should only be disabled temporarily, if necessary, to resolve upgrade issues, then re-enabled after any issues have been resolved. @@ -81,7 +81,7 @@ The following settings for Elastic Universal Profiling are supported: $$$reindex-remote-whitelist$$$ `reindex.remote.whitelist` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the hosts that can be [reindexed from remotely](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-reindex). Expects a YAML array of `host:port` strings. Consists of a comma-delimited list of `host:port` entries. Defaults to `["\*.io:*", "\*.com:*"]`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the hosts that can be [reindexed from remotely](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-reindex). Expects a YAML array of `host:port` strings. Consists of a comma-delimited list of `host:port` entries. Defaults to `["\*.io:*", "\*.com:*"]`. `reindex.ssl.certificate` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") : Specifies the path to the PEM encoded certificate (or certificate chain) to be used for HTTP client authentication (if required by the remote cluster) This setting requires that `reindex.ssl.key` also be set. You cannot specify both `reindex.ssl.certificate` and `reindex.ssl.keystore.path`. @@ -145,5 +145,4 @@ $$$reindex-remote-whitelist$$$ : The type of the truststore (`reindex.ssl.truststore.path`). Must be either `jks` or `PKCS12`. If the truststore path ends in ".p12", ".pfx" or "pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. `reindex.ssl.verification_mode` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: Indicates the type of verification to protect against man in the middle attacks and certificate forgery. One of `full` (verify the hostname and the certificate path), `certificate` (verify the certificate path, but not the hostname) or `none` (perform no verification - this is strongly discouraged in production environments). Defaults to `full`. - +: Indicates the type of verification to protect against man in the middle attacks and certificate forgery. One of `full` (verify the hostname and the certificate path), `certificate` (verify the certificate path, but not the hostname) or `none` (perform no verification - this is strongly discouraged in production environments). Defaults to `full`. \ No newline at end of file diff --git a/docs/reference/elasticsearch/configuration-reference/index-recovery-settings.md b/docs/reference/elasticsearch/configuration-reference/index-recovery-settings.md index a8e07f14ec2b9..c572888188735 100644 --- a/docs/reference/elasticsearch/configuration-reference/index-recovery-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/index-recovery-settings.md @@ -21,7 +21,7 @@ You can view a list of in-progress and completed recoveries using the [cat recov ## Recovery settings [recovery-settings] `indices.recovery.max_bytes_per_sec` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Limits total inbound and outbound recovery traffic for each node. Applies to both peer recoveries as well as snapshot recoveries (i.e., restores from a snapshot). Defaults to `40mb` unless the node is a dedicated [cold](docs-content://manage-data/lifecycle/data-tiers.md#cold-tier) or [frozen](docs-content://manage-data/lifecycle/data-tiers.md#frozen-tier) node, in which case the default relates to the total memory available to the node: +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Limits total inbound and outbound recovery traffic for each node. Applies to both peer recoveries as well as snapshot recoveries (i.e., restores from a snapshot). Defaults to `40mb` unless the node is a dedicated [cold](docs-content://manage-data/lifecycle/data-tiers.md#cold-tier) or [frozen](docs-content://manage-data/lifecycle/data-tiers.md#frozen-tier) node, in which case the default relates to the total memory available to the node: | Total memory | Default recovery rate on cold and frozen nodes | | --- | --- | @@ -44,19 +44,19 @@ You can view a list of in-progress and completed recoveries using the [cat recov You can use the following *expert* setting to manage resources for peer recoveries. `indices.recovery.max_concurrent_file_chunks` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings), Expert) Number of file chunks sent in parallel for each recovery. Defaults to `2`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), Expert) Number of file chunks sent in parallel for each recovery. Defaults to `2`. You can increase the value of this setting when the recovery of a single shard is not reaching the traffic limit set by `indices.recovery.max_bytes_per_sec`, up to a maximum of `8`. `indices.recovery.max_concurrent_operations` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings), Expert) Number of operations sent in parallel for each recovery. Defaults to `1`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), Expert) Number of operations sent in parallel for each recovery. Defaults to `1`. Concurrently replaying operations during recovery can be very resource-intensive and may interfere with indexing, search, and other activities in your cluster. Do not increase this setting without carefully verifying that your cluster has the resources available to handle the extra load that will result. `indices.recovery.use_snapshots` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings), Expert) Enables snapshot-based peer recoveries. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), Expert) Enables snapshot-based peer recoveries. {{es}} recovers replicas and relocates primary shards using the *peer recovery* process, which involves constructing a new copy of a shard on the target node. When `indices.recovery.use_snapshots` is `false` {{es}} will construct this new copy by transferring the index data from the current primary. When this setting is `true` {{es}} will attempt to copy the index data from a recent snapshot first, and will only copy data from the primary if it cannot identify a suitable snapshot. Defaults to `true`. @@ -66,13 +66,13 @@ You can use the following *expert* setting to manage resources for peer recoveri `indices.recovery.max_concurrent_snapshot_file_downloads` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings), Expert) Number of snapshot file downloads requests sent in parallel to the target node for each recovery. Defaults to `5`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), Expert) Number of snapshot file downloads requests sent in parallel to the target node for each recovery. Defaults to `5`. Do not increase this setting without carefully verifying that your cluster has the resources available to handle the extra load that will result. `indices.recovery.max_concurrent_snapshot_file_downloads_per_node` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings), Expert) Number of snapshot file downloads requests executed in parallel in the target node for all recoveries. Defaults to `25`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), Expert) Number of snapshot file downloads requests executed in parallel in the target node for all recoveries. Defaults to `25`. Do not increase this setting without carefully verifying that your cluster has the resources available to handle the extra load that will result. @@ -106,20 +106,20 @@ The service should determine values for the absolute maximum bandwidths settings : ([byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units) per second) The absolute maximum network throughput for a recovery-like workload on the node, which applies to both reads and writes. If set, `node.bandwidth.recovery.disk.read` and `node.bandwidth.recovery.disk.write` must also be set. `node.bandwidth.recovery.factor.read` -: (float, [dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) The proportion of the maximum read bandwidth that may be used for recoveries if `indices.recovery.max_bytes_per_sec` is not set. Must be greater than `0` and not greater than `1`. If not set, the value of `node.bandwidth.recovery.operator.factor.read` is used. If no factor settings are set then the value `0.4` is used. +: (float, [Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The proportion of the maximum read bandwidth that may be used for recoveries if `indices.recovery.max_bytes_per_sec` is not set. Must be greater than `0` and not greater than `1`. If not set, the value of `node.bandwidth.recovery.operator.factor.read` is used. If no factor settings are set then the value `0.4` is used. `node.bandwidth.recovery.factor.write` -: (float, [dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) The proportion of the maximum write bandwidth that may be used for recoveries if `indices.recovery.max_bytes_per_sec` is not set. Must be greater than `0` and not greater than `1`. If not set, the value of `node.bandwidth.recovery.operator.factor.write` is used. If no factor settings are set then the value `0.4` is used. +: (float, [Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The proportion of the maximum write bandwidth that may be used for recoveries if `indices.recovery.max_bytes_per_sec` is not set. Must be greater than `0` and not greater than `1`. If not set, the value of `node.bandwidth.recovery.operator.factor.write` is used. If no factor settings are set then the value `0.4` is used. `node.bandwidth.recovery.operator.factor.read` -: (float, [dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) The proportion of the maximum read bandwidth that may be used for recoveries if `indices.recovery.max_bytes_per_sec` and `node.bandwidth.recovery.factor.read` are not set. Must be greater than `0` and not greater than `1`. If not set, the value of `node.bandwidth.recovery.operator.factor` is used. If no factor settings are set then the value `0.4` is used. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. +: (float, [Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The proportion of the maximum read bandwidth that may be used for recoveries if `indices.recovery.max_bytes_per_sec` and `node.bandwidth.recovery.factor.read` are not set. Must be greater than `0` and not greater than `1`. If not set, the value of `node.bandwidth.recovery.operator.factor` is used. If no factor settings are set then the value `0.4` is used. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. `node.bandwidth.recovery.operator.factor.write` -: (float, [dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) The proportion of the maximum write bandwidth that may be used for recoveries if `indices.recovery.max_bytes_per_sec` and `node.bandwidth.recovery.factor.write` are not set. Must be greater than `0` and not greater than `1`. If not set, the value of `node.bandwidth.recovery.operator.factor` is used. If no factor settings are set then the value `0.4` is used. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. +: (float, [Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The proportion of the maximum write bandwidth that may be used for recoveries if `indices.recovery.max_bytes_per_sec` and `node.bandwidth.recovery.factor.write` are not set. Must be greater than `0` and not greater than `1`. If not set, the value of `node.bandwidth.recovery.operator.factor` is used. If no factor settings are set then the value `0.4` is used. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. `node.bandwidth.recovery.operator.factor` -: (float, [dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) The proportion of the maximum bandwidth that may be used for recoveries if neither `indices.recovery.max_bytes_per_sec` nor any other factor settings are set. Must be greater than `0` and not greater than `1`. Defaults to `0.4`. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. +: (float, [Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The proportion of the maximum bandwidth that may be used for recoveries if neither `indices.recovery.max_bytes_per_sec` nor any other factor settings are set. Must be greater than `0` and not greater than `1`. Defaults to `0.4`. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. `node.bandwidth.recovery.operator.factor.max_overcommit` -: (float, [dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) The proportion of the absolute maximum bandwidth that may be used for recoveries regardless of any other settings. Must be greater than `0`. Defaults to `100`. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. +: (float, [Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The proportion of the absolute maximum bandwidth that may be used for recoveries regardless of any other settings. Must be greater than `0`. Defaults to `100`. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. diff --git a/docs/reference/elasticsearch/configuration-reference/indexing-buffer-settings.md b/docs/reference/elasticsearch/configuration-reference/indexing-buffer-settings.md index 1c815b9d15d4e..3fba8fb0755b8 100644 --- a/docs/reference/elasticsearch/configuration-reference/indexing-buffer-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/indexing-buffer-settings.md @@ -13,11 +13,11 @@ The indexing buffer is used to store newly indexed documents. When it fills up, The following settings are *static* and must be configured on every data node in the cluster: `indices.memory.index_buffer_size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Accepts either a percentage or a byte size value. It defaults to `10%`, meaning that `10%` of the total heap allocated to a node will be used as the indexing buffer size shared across all shards. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Accepts either a percentage or a byte size value. It defaults to `10%`, meaning that `10%` of the total heap allocated to a node will be used as the indexing buffer size shared across all shards. `indices.memory.min_index_buffer_size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) If the `index_buffer_size` is specified as a percentage, then this setting can be used to specify an absolute minimum. Defaults to `48mb`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) If the `index_buffer_size` is specified as a percentage, then this setting can be used to specify an absolute minimum. Defaults to `48mb`. `indices.memory.max_index_buffer_size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) If the `index_buffer_size` is specified as a percentage, then this setting can be used to specify an absolute maximum. Defaults to unbounded. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) If the `index_buffer_size` is specified as a percentage, then this setting can be used to specify an absolute maximum. Defaults to unbounded. diff --git a/docs/reference/elasticsearch/configuration-reference/inference-settings.md b/docs/reference/elasticsearch/configuration-reference/inference-settings.md index 162df6e8116c0..5dbd6219f24ac 100644 --- a/docs/reference/elasticsearch/configuration-reference/inference-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/inference-settings.md @@ -19,30 +19,30 @@ You do not need to configure any settings to use the {{infer}} APIs. Each settin When certain failures occur, a log message is emitted. In the case of a reoccurring failure the logging throttler restricts repeated messages from being logged. `xpack.inference.logging.reset_interval` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Specifies the interval for when a cleanup thread will clear an internal cache of the previously logged messages. Defaults to one day (`1d`). +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Specifies the interval for when a cleanup thread will clear an internal cache of the previously logged messages. Defaults to one day (`1d`). `xpack.inference.logging.wait_duration` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Specifies the amount of time to wait after logging a message before that message can be logged again. Defaults to one hour (`1h`). +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Specifies the amount of time to wait after logging a message before that message can be logged again. Defaults to one hour (`1h`). ## {{infer-cap}} API HTTP settings [xpack-inference-http-settings] `xpack.inference.http.max_response_size` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Specifies the maximum size in bytes an HTTP response is allowed to have, defaults to `50mb`, the maximum configurable value is `100mb`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Specifies the maximum size in bytes an HTTP response is allowed to have, defaults to `50mb`, the maximum configurable value is `100mb`. `xpack.inference.http.max_total_connections` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Specifies the maximum number of connections the internal connection pool can lease. Defaults to `50`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Specifies the maximum number of connections the internal connection pool can lease. Defaults to `50`. `xpack.inference.http.max_route_connections` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Specifies the maximum number of connections a single route can lease from the internal connection pool. If this setting is set to a value equal to or greater than `xpack.inference.http.max_total_connections`, then a single third party service could lease all available connections and other third party services would be unable to lease connections. Defaults to `20`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Specifies the maximum number of connections a single route can lease from the internal connection pool. If this setting is set to a value equal to or greater than `xpack.inference.http.max_total_connections`, then a single third party service could lease all available connections and other third party services would be unable to lease connections. Defaults to `20`. `xpack.inference.http.connection_eviction_interval` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Specifies the interval that an eviction thread will run to remove expired and stale connections from the internal connection pool. Decreasing this time value can help improve throughput if multiple third party service are contending for the available connections in the pool. Defaults to one minute (`1m`). +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Specifies the interval that an eviction thread will run to remove expired and stale connections from the internal connection pool. Decreasing this time value can help improve throughput if multiple third party service are contending for the available connections in the pool. Defaults to one minute (`1m`). `xpack.inference.http.connection_eviction_max_idle_time` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Specifies the maximum duration a connection can be unused before it is marked as idle and can be closed and removed from the shared connection pool. Defaults to one minute (`1m`). +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Specifies the maximum duration a connection can be unused before it is marked as idle and can be closed and removed from the shared connection pool. Defaults to one minute (`1m`). `xpack.inference.http.request_executor.queue_capacity` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Specifies the size of the internal queue for requests waiting to be sent. If the queue is full and a request is sent to the {{infer}} API, it will be rejected. Defaults to `2000`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Specifies the size of the internal queue for requests waiting to be sent. If the queue is full and a request is sent to the {{infer}} API, it will be rejected. Defaults to `2000`. ## {{infer-cap}} API HTTP Retry settings [xpack-inference-http-retry-settings] @@ -50,13 +50,13 @@ When certain failures occur, a log message is emitted. In the case of a reoccurr When a third-party service returns a transient failure code (for example, 429), the request is retried by the {{infer}} API. These settings govern the retry behavior. When a request is retried, exponential backoff is used. `xpack.inference.http.retry.initial_delay` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Specifies the initial delay before retrying a request. Defaults to one second (`1s`). +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Specifies the initial delay before retrying a request. Defaults to one second (`1s`). `xpack.inference.http.retry.max_delay_bound` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Specifies the maximum delay for a request. Defaults to five seconds (`5s`). +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Specifies the maximum delay for a request. Defaults to five seconds (`5s`). `xpack.inference.http.retry.timeout` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Specifies the maximum amount of time a request can be retried. Once the request exceeds this time, the request will no longer be retried and a failure will be returned. Defaults to 30 seconds (`30s`). +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Specifies the maximum amount of time a request can be retried. Once the request exceeds this time, the request will no longer be retried and a failure will be returned. Defaults to 30 seconds (`30s`). ## {{infer-cap}} API Input text [xpack-inference-input-text] @@ -64,6 +64,6 @@ When a third-party service returns a transient failure code (for example, 429), For certain third-party service integrations, when the service returns an error indicating that the request input was too large, the input will be truncated and the request is retried. These settings govern how the truncation is performed. `xpack.inference.truncator.reduction_percentage` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Specifies the percentage to reduce the input text by if the 3rd party service responds with an error indicating it is too long. Defaults to 50 percent (`0.5`). +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Specifies the percentage to reduce the input text by if the 3rd party service responds with an error indicating it is too long. Defaults to 50 percent (`0.5`). diff --git a/docs/reference/elasticsearch/configuration-reference/license-settings.md b/docs/reference/elasticsearch/configuration-reference/license-settings.md index cd7e4860e817e..38b46ade1d2bc 100644 --- a/docs/reference/elasticsearch/configuration-reference/license-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/license-settings.md @@ -11,7 +11,7 @@ applies_to: You can configure this licensing setting in the `elasticsearch.yml` file. For more information, see [License management](docs-content://deploy-manage/license/manage-your-license-in-self-managed-cluster.md). `xpack.license.self_generated.type` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Set to `basic` (default) to enable basic {{xpack}} features.
+: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Set to `basic` (default) to enable basic {{xpack}} features.
If set to `trial`, the self-generated license gives access only to all the features of a x-pack for 30 days. You can later downgrade the cluster to a basic license if needed. diff --git a/docs/reference/elasticsearch/configuration-reference/local-gateway.md b/docs/reference/elasticsearch/configuration-reference/local-gateway.md index a749e54ea340c..376ef643315c3 100644 --- a/docs/reference/elasticsearch/configuration-reference/local-gateway.md +++ b/docs/reference/elasticsearch/configuration-reference/local-gateway.md @@ -19,16 +19,16 @@ These settings only take effect during a [full cluster restart](docs-content://d `gateway.expected_data_nodes` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Number of data nodes expected in the cluster. Recovery of local shards begins when the expected number of data nodes join the cluster. Defaults to `0`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Number of data nodes expected in the cluster. Recovery of local shards begins when the expected number of data nodes join the cluster. Defaults to `0`. `gateway.recover_after_time` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) If the expected number of nodes is not achieved, the recovery process waits for the configured amount of time before trying to recover. Defaults to `5m`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) If the expected number of nodes is not achieved, the recovery process waits for the configured amount of time before trying to recover. Defaults to `5m`. Once the `recover_after_time` duration has timed out, recovery will start as long as the following condition is met: `gateway.recover_after_data_nodes` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Recover as long as this many data nodes have joined the cluster. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Recover as long as this many data nodes have joined the cluster. These settings can be configured in `elasticsearch.yml` as follows: diff --git a/docs/reference/elasticsearch/configuration-reference/machine-learning-settings.md b/docs/reference/elasticsearch/configuration-reference/machine-learning-settings.md index 35fe856b9d570..b5ae7d523c38c 100644 --- a/docs/reference/elasticsearch/configuration-reference/machine-learning-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/machine-learning-settings.md @@ -28,7 +28,7 @@ To control memory usage used by {{ml}} jobs, you can use the [machine learning c ## General machine learning settings [general-ml-settings] `node.roles: [ ml ]` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Set `node.roles` to contain `ml` to identify the node as a *{{ml}} node*. If you want to run {{ml}} jobs, there must be at least one {{ml}} node in your cluster. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Set `node.roles` to contain `ml` to identify the node as a *{{ml}} node*. If you want to run {{ml}} jobs, there must be at least one {{ml}} node in your cluster. If you set `node.roles`, you must explicitly specify all the required roles for the node. To learn more, refer to [Node settings](/reference/elasticsearch/configuration-reference/node-settings.md). @@ -40,7 +40,7 @@ To control memory usage used by {{ml}} jobs, you can use the [machine learning c `xpack.ml.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The default value (`true`) enables {{ml}} APIs on the node. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The default value (`true`) enables {{ml}} APIs on the node. ::::{important} If you want to use {{ml-features}} in your cluster, it is recommended that you use the default value for this setting on all nodes. @@ -53,18 +53,18 @@ To control memory usage used by {{ml}} jobs, you can use the [machine learning c `xpack.ml.inference_model.cache_size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The maximum inference cache size allowed. The inference cache exists in the JVM heap on each ingest node. The cache affords faster processing times for the `inference` processor. The value can be a static byte sized value (such as `2gb`) or a percentage of total allocated heap. Defaults to `40%`. See also [{{ml-cap}} circuit breaker](/reference/elasticsearch/configuration-reference/circuit-breaker-settings.md#circuit-breakers-page-model-inference). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The maximum inference cache size allowed. The inference cache exists in the JVM heap on each ingest node. The cache affords faster processing times for the `inference` processor. The value can be a static byte sized value (such as `2gb`) or a percentage of total allocated heap. Defaults to `40%`. See also [{{ml-cap}} circuit breaker](/reference/elasticsearch/configuration-reference/circuit-breaker-settings.md#circuit-breakers-page-model-inference). $$$xpack-interference-model-ttl$$$ `xpack.ml.inference_model.time_to_live` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The time to live (TTL) for trained models in the inference model cache. The TTL is calculated from last access. Users of the cache (such as the inference processor or inference aggregator) cache a model on its first use and reset the TTL on every use. If a cached model is not accessed for the duration of the TTL, it is flagged for eviction from the cache. If a document is processed later, the model is again loaded into the cache. To update this setting in {{ess}}, see [Add {{es}} user settings](/reference/elasticsearch/configuration-reference/index.md). Defaults to `5m`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The time to live (TTL) for trained models in the inference model cache. The TTL is calculated from last access. Users of the cache (such as the inference processor or inference aggregator) cache a model on its first use and reset the TTL on every use. If a cached model is not accessed for the duration of the TTL, it is flagged for eviction from the cache. If a document is processed later, the model is again loaded into the cache. To update this setting in {{ess}}, see [Add {{es}} user settings](/reference/elasticsearch/configuration-reference/index.md). Defaults to `5m`. `xpack.ml.max_inference_processors` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) The total number of `inference` type processors allowed across all ingest pipelines. Once the limit is reached, adding an `inference` processor to a pipeline is disallowed. Defaults to `50`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The total number of `inference` type processors allowed across all ingest pipelines. Once the limit is reached, adding an `inference` processor to a pipeline is disallowed. Defaults to `50`. `xpack.ml.max_machine_memory_percent` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) The maximum percentage of the machine’s memory that {{ml}} may use for running analytics processes. These processes are separate to the {{es}} JVM. The limit is based on the total memory of the machine, not current free memory. Jobs are not allocated to a node if doing so would cause the estimated memory use of {{ml}} jobs to exceed the limit. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. The minimum value is `5`; the maximum value is `200`. Defaults to `30`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The maximum percentage of the machine’s memory that {{ml}} may use for running analytics processes. These processes are separate to the {{es}} JVM. The limit is based on the total memory of the machine, not current free memory. Jobs are not allocated to a node if doing so would cause the estimated memory use of {{ml}} jobs to exceed the limit. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. The minimum value is `5`; the maximum value is `200`. Defaults to `30`. ::::{tip} Do not configure this setting to a value higher than the amount of memory left over after running the {{es}} JVM unless you have enough swap space to accommodate it and have determined this is an appropriate configuration for a specialist use case. The maximum setting value is for the special case where it has been determined that using swap space for {{ml}} jobs is acceptable. The general best practice is to not use swap on {{es}} nodes. @@ -72,18 +72,18 @@ $$$xpack-interference-model-ttl$$$ `xpack.ml.max_model_memory_limit` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) The maximum `model_memory_limit` property value that can be set for any {{ml}} jobs in this cluster. If you try to create a job with a `model_memory_limit` property value that is greater than this setting value, an error occurs. Existing jobs are not affected when you update this setting. If this setting is `0` or unset, there is no maximum `model_memory_limit` value. If there are no nodes that meet the memory requirements for a job, this lack of a maximum memory limit means it’s possible to create jobs that cannot be assigned to any available nodes. For more information about the `model_memory_limit` property, see [Create {{anomaly-jobs}}](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ml-put-job) or [Create {{dfanalytics-jobs}}](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ml-put-data-frame-analytics). Defaults to `0` if `xpack.ml.use_auto_machine_memory_percent` is `false`. If `xpack.ml.use_auto_machine_memory_percent` is `true` and `xpack.ml.max_model_memory_limit` is not explicitly set then it will default to the largest `model_memory_limit` that could be assigned in the cluster. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The maximum `model_memory_limit` property value that can be set for any {{ml}} jobs in this cluster. If you try to create a job with a `model_memory_limit` property value that is greater than this setting value, an error occurs. Existing jobs are not affected when you update this setting. If this setting is `0` or unset, there is no maximum `model_memory_limit` value. If there are no nodes that meet the memory requirements for a job, this lack of a maximum memory limit means it’s possible to create jobs that cannot be assigned to any available nodes. For more information about the `model_memory_limit` property, see [Create {{anomaly-jobs}}](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ml-put-job) or [Create {{dfanalytics-jobs}}](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ml-put-data-frame-analytics). Defaults to `0` if `xpack.ml.use_auto_machine_memory_percent` is `false`. If `xpack.ml.use_auto_machine_memory_percent` is `true` and `xpack.ml.max_model_memory_limit` is not explicitly set then it will default to the largest `model_memory_limit` that could be assigned in the cluster. $$$xpack.ml.max_open_jobs$$$ `xpack.ml.max_open_jobs` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) The maximum number of jobs that can run simultaneously on a node. In this context, jobs include both {{anomaly-jobs}} and {{dfanalytics-jobs}}. The maximum number of jobs is also constrained by memory usage. Thus if the estimated memory usage of the jobs would be higher than allowed, fewer jobs will run on a node. Prior to version 7.1, this setting was a per-node non-dynamic setting. It became a cluster-wide dynamic setting in version 7.1. As a result, changes to its value after node startup are used only after every node in the cluster is running version 7.1 or higher. The minimum value is `1`; the maximum value is `512`. Defaults to `512`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The maximum number of jobs that can run simultaneously on a node. In this context, jobs include both {{anomaly-jobs}} and {{dfanalytics-jobs}}. The maximum number of jobs is also constrained by memory usage. Thus if the estimated memory usage of the jobs would be higher than allowed, fewer jobs will run on a node. Prior to version 7.1, this setting was a per-node non-dynamic setting. It became a cluster-wide dynamic setting in version 7.1. As a result, changes to its value after node startup are used only after every node in the cluster is running version 7.1 or higher. The minimum value is `1`; the maximum value is `512`. Defaults to `512`. `xpack.ml.nightly_maintenance_requests_per_second` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) The rate at which the nightly maintenance task deletes expired model snapshots and results. The setting is a proxy to the [`requests_per_second`](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-delete-by-query) parameter used in the delete by query requests and controls throttling. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. Valid values must be greater than `0.0` or equal to `-1.0`, where `-1.0` means a default value is used. Defaults to `-1.0` +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The rate at which the nightly maintenance task deletes expired model snapshots and results. The setting is a proxy to the [`requests_per_second`](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-delete-by-query) parameter used in the delete by query requests and controls throttling. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. Valid values must be greater than `0.0` or equal to `-1.0`, where `-1.0` means a default value is used. Defaults to `-1.0` `xpack.ml.node_concurrent_job_allocations` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) The maximum number of jobs that can concurrently be in the `opening` state on each node. Typically, jobs spend a small amount of time in this state before they move to `open` state. Jobs that must restore large models when they are opening spend more time in the `opening` state. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. Defaults to `2`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The maximum number of jobs that can concurrently be in the `opening` state on each node. Typically, jobs spend a small amount of time in this state before they move to `open` state. Jobs that must restore large models when they are opening spend more time in the `opening` state. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. Defaults to `2`. ## Advanced machine learning settings [advanced-ml-settings] @@ -91,13 +91,13 @@ $$$xpack.ml.max_open_jobs$$$ These settings are for advanced use cases; the default values are generally sufficient: `xpack.ml.enable_config_migration` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Reserved. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Reserved. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. `xpack.ml.max_anomaly_records` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) The maximum number of records that are output per bucket. Defaults to `500`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The maximum number of records that are output per bucket. Defaults to `500`. `xpack.ml.max_lazy_ml_nodes` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) The number of lazily spun up {{ml}} nodes. Useful in situations where {{ml}} nodes are not desired until the first {{ml}} job opens. If the current number of {{ml}} nodes is greater than or equal to this setting, it is assumed that there are no more lazy nodes available as the desired number of nodes have already been provisioned. If a job is opened and this setting has a value greater than zero and there are no nodes that can accept the job, the job stays in the `OPENING` state until a new {{ml}} node is added to the cluster and the job is assigned to run on that node. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. Defaults to `0`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The number of lazily spun up {{ml}} nodes. Useful in situations where {{ml}} nodes are not desired until the first {{ml}} job opens. If the current number of {{ml}} nodes is greater than or equal to this setting, it is assumed that there are no more lazy nodes available as the desired number of nodes have already been provisioned. If a job is opened and this setting has a value greater than zero and there are no nodes that can accept the job, the job stays in the `OPENING` state until a new {{ml}} node is added to the cluster and the job is assigned to run on that node. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. Defaults to `0`. ::::{important} This setting assumes some external process is capable of adding {{ml}} nodes to the cluster. This setting is only useful when used in conjunction with such an external process. @@ -105,12 +105,12 @@ These settings are for advanced use cases; the default values are generally suff `xpack.ml.max_ml_node_size` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) The maximum node size for {{ml}} nodes in a deployment that supports automatic cluster scaling. If you set it to the maximum possible size of future {{ml}} nodes, when a {{ml}} job is assigned to a lazy node it can check (and fail quickly) when scaling cannot support the size of the job. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. Defaults to `0b`, which means it will be assumed that automatic cluster scaling can add arbitrarily large nodes to the cluster. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The maximum node size for {{ml}} nodes in a deployment that supports automatic cluster scaling. If you set it to the maximum possible size of future {{ml}} nodes, when a {{ml}} job is assigned to a lazy node it can check (and fail quickly) when scaling cannot support the size of the job. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. Defaults to `0b`, which means it will be assumed that automatic cluster scaling can add arbitrarily large nodes to the cluster. $$$xpack.ml.model_repository$$$ `xpack.ml.model_repository` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) The location of the {{ml}} model repository where the model artifact files are available in case of a model installation in a restricted or closed network. `xpack.ml.model_repository` can be a string of a file location or an HTTP/HTTPS server. Example values are: +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The location of the {{ml}} model repository where the model artifact files are available in case of a model installation in a restricted or closed network. `xpack.ml.model_repository` can be a string of a file location or an HTTP/HTTPS server. Example values are: ``` xpack.ml.model_repository: file://${path.home}/config/models/ @@ -126,13 +126,13 @@ $$$xpack.ml.model_repository$$$ `xpack.ml.persist_results_max_retries` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) The maximum number of times to retry bulk indexing requests that fail while processing {{ml}} results. If the limit is reached, the {{ml}} job stops processing data and its status is `failed`. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. The minimum value is `0`; the maximum value is `50`. Defaults to `20`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The maximum number of times to retry bulk indexing requests that fail while processing {{ml}} results. If the limit is reached, the {{ml}} job stops processing data and its status is `failed`. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. The minimum value is `0`; the maximum value is `50`. Defaults to `20`. `xpack.ml.process_connect_timeout` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) The connection timeout for {{ml}} processes that run separately from the {{es}} JVM. When such processes are started they must connect to the {{es}} JVM. If the process does not connect within the time period specified by this setting then the process is assumed to have failed. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. The minimum value is `5s`. Defaults to `10s`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The connection timeout for {{ml}} processes that run separately from the {{es}} JVM. When such processes are started they must connect to the {{es}} JVM. If the process does not connect within the time period specified by this setting then the process is assumed to have failed. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. The minimum value is `5s`. Defaults to `10s`. `xpack.ml.use_auto_machine_memory_percent` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) If this setting is `true`, the `xpack.ml.max_machine_memory_percent` setting is ignored. Instead, the maximum percentage of the machine’s memory that can be used for running {{ml}} analytics processes is calculated automatically and takes into account the total node size and the size of the JVM on the node. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. The default value is `false`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) If this setting is `true`, the `xpack.ml.max_machine_memory_percent` setting is ignored. Instead, the maximum percentage of the machine’s memory that can be used for running {{ml}} analytics processes is calculated automatically and takes into account the total node size and the size of the JVM on the node. When the {{operator-feature}} is enabled, this setting can be updated only by operator users. The default value is `false`. ::::{important} * If you do not have dedicated {{ml}} nodes (that is to say, the node has multiple roles), do not enable this setting. Its calculations assume that {{ml}} analytics are the main purpose of the node. diff --git a/docs/reference/elasticsearch/configuration-reference/miscellaneous-cluster-settings.md b/docs/reference/elasticsearch/configuration-reference/miscellaneous-cluster-settings.md index a60daeadec1ea..eae53efb87657 100644 --- a/docs/reference/elasticsearch/configuration-reference/miscellaneous-cluster-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/miscellaneous-cluster-settings.md @@ -33,10 +33,10 @@ Changing the name of a cluster requires a [full cluster restart](docs-content:// An entire cluster may be set to read-only with the following setting: `cluster.blocks.read_only` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Make the whole cluster read only (indices do not accept write operations), metadata is not allowed to be modified (create or delete indices). Defaults to `false`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Make the whole cluster read only (indices do not accept write operations), metadata is not allowed to be modified (create or delete indices). Defaults to `false`. `cluster.blocks.read_only_allow_delete` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Identical to `cluster.blocks.read_only` but allows to delete indices to free up resources. Defaults to `false`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Identical to `cluster.blocks.read_only` but allows to delete indices to free up resources. Defaults to `false`. ::::{warning} Don’t rely on this setting to prevent changes to your cluster. Any user with access to the [cluster-update-settings](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings) API can make the cluster read-write again. @@ -67,7 +67,7 @@ You can dynamically adjust the cluster shard limit with the following setting: $$$cluster-max-shards-per-node$$$ `cluster.max_shards_per_node` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Limits the total number of primary and replica shards for the cluster. {{es}} calculates the limit as follows: +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Limits the total number of primary and replica shards for the cluster. {{es}} calculates the limit as follows: `cluster.max_shards_per_node * number of non-frozen data nodes` @@ -83,7 +83,7 @@ Notice that frozen shards have their own independent limit. $$$cluster-max-shards-per-node-frozen$$$ `cluster.max_shards_per_node.frozen` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Limits the total number of primary and replica frozen shards for the cluster. {{es}} calculates the limit as follows: +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Limits the total number of primary and replica frozen shards for the cluster. {{es}} calculates the limit as follows: `cluster.max_shards_per_node.frozen * number of frozen data nodes` @@ -122,7 +122,7 @@ User-defined cluster metadata is not intended to store sensitive or confidential The cluster state maintains index tombstones to explicitly denote indices that have been deleted. The number of tombstones maintained in the cluster state is controlled by the following setting: `cluster.indices.tombstones.size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Index tombstones prevent nodes that are not part of the cluster when a delete occurs from joining the cluster and reimporting the index as though the delete was never issued. To keep the cluster state from growing huge we only keep the last `cluster.indices.tombstones.size` deletes, which defaults to 500. You can increase it if you expect nodes to be absent from the cluster and miss more than 500 deletes. We think that is rare, thus the default. Tombstones don’t take up much space, but we also think that a number like 50,000 is probably too big. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Index tombstones prevent nodes that are not part of the cluster when a delete occurs from joining the cluster and reimporting the index as though the delete was never issued. To keep the cluster state from growing huge we only keep the last `cluster.indices.tombstones.size` deletes, which defaults to 500. You can increase it if you expect nodes to be absent from the cluster and miss more than 500 deletes. We think that is rare, thus the default. Tombstones don’t take up much space, but we also think that a number like 50,000 is probably too big. If {{es}} encounters index data that is absent from the current cluster state, those indices are considered to be dangling. For example, this can happen if you delete more than `cluster.indices.tombstones.size` indices while an {{es}} node is offline. @@ -150,7 +150,7 @@ Plugins can create a kind of tasks called persistent tasks. Those tasks are usua Every time a persistent task is created, the master node takes care of assigning the task to a node of the cluster, and the assigned node will then pick up the task and execute it locally. The process of assigning persistent tasks to nodes is controlled by the following settings: `cluster.persistent_tasks.allocation.enable` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Enable or disable allocation for persistent tasks: +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Enable or disable allocation for persistent tasks: * `all` - (default) Allows persistent tasks to be assigned to nodes * `none` - No allocations are allowed for any type of persistent task @@ -159,5 +159,5 @@ This setting does not affect the persistent tasks that are already being execute `cluster.persistent_tasks.allocation.recheck_interval` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) The master node will automatically check whether persistent tasks need to be assigned when the cluster state changes significantly. However, there may be other factors, such as memory usage, that affect whether persistent tasks can be assigned to nodes but do not cause the cluster state to change. This setting controls how often assignment checks are performed to react to these factors. The default is 30 seconds. The minimum permitted value is 10 seconds. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The master node will automatically check whether persistent tasks need to be assigned when the cluster state changes significantly. However, there may be other factors, such as memory usage, that affect whether persistent tasks can be assigned to nodes but do not cause the cluster state to change. This setting controls how often assignment checks are performed to react to these factors. The default is 30 seconds. The minimum permitted value is 10 seconds. diff --git a/docs/reference/elasticsearch/configuration-reference/monitoring-settings.md b/docs/reference/elasticsearch/configuration-reference/monitoring-settings.md index b5ef340fb74b4..4d2b6ed1c257d 100644 --- a/docs/reference/elasticsearch/configuration-reference/monitoring-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/monitoring-settings.md @@ -30,7 +30,7 @@ For more information, see [Monitor a cluster](docs-content://deploy-manage/monit ### General monitoring settings [general-monitoring-settings] `xpack.monitoring.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) :::{admonition} Deprecated in 7.8.0 This deprecated setting has no effect. @@ -46,7 +46,7 @@ The `xpack.monitoring.collection` settings control how data is collected from yo This setting was deprecated in 7.16.0. ::: - ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Set to `true` to enable the collection of monitoring data. When this setting is `false` (default), {{es}} monitoring data is not collected and all monitoring data from other sources such as {{kib}}, Beats, and {{ls}} is ignored. + ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Set to `true` to enable the collection of monitoring data. When this setting is `false` (default), {{es}} monitoring data is not collected and all monitoring data from other sources such as {{kib}}, Beats, and {{ls}} is ignored. $$$xpack-monitoring-collection-interval$$$ @@ -55,7 +55,7 @@ $$$xpack-monitoring-collection-interval$$$ This setting was deprecated in 6.3.0. ::: - ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Setting to `-1` to disable data collection is no longer supported beginning with 7.0.0. + ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Setting to `-1` to disable data collection is no longer supported beginning with 7.0.0. Controls how often data samples are collected. Defaults to `10s`. If you modify the collection interval, set the `xpack.monitoring.min_interval_seconds` option in `kibana.yml` to the same value. @@ -65,49 +65,49 @@ $$$xpack-monitoring-collection-interval$$$ This setting was deprecated in 7.16.0. ::: - ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Controls whether statistics about your {{es}} cluster should be collected. Defaults to `true`. This is different from `xpack.monitoring.collection.enabled`, which allows you to enable or disable all monitoring collection. However, this setting simply disables the collection of {{es}} data while still allowing other data (e.g., {{kib}}, {{ls}}, Beats, or APM Server monitoring data) to pass through this cluster. + ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Controls whether statistics about your {{es}} cluster should be collected. Defaults to `true`. This is different from `xpack.monitoring.collection.enabled`, which allows you to enable or disable all monitoring collection. However, this setting simply disables the collection of {{es}} data while still allowing other data (e.g., {{kib}}, {{ls}}, Beats, or APM Server monitoring data) to pass through this cluster. `xpack.monitoring.collection.cluster.stats.timeout` : :::{admonition} Deprecated in 7.16.0 This setting was deprecated in 7.16.0. ::: - ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Timeout for collecting the cluster statistics, in [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units). Defaults to `10s`. + ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Timeout for collecting the cluster statistics, in [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units). Defaults to `10s`. `xpack.monitoring.collection.node.stats.timeout` : :::{admonition} Deprecated in 7.16.0 This setting was deprecated in 7.16.0. ::: - ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Timeout for collecting the node statistics, in [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units). Defaults to `10s`. + ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Timeout for collecting the node statistics, in [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units). Defaults to `10s`. `xpack.monitoring.collection.indices` : :::{admonition} Deprecated in 7.16.0 This setting was deprecated in 7.16.0. ::: - ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Controls which indices the {{monitor-features}} collect data from. Defaults to all indices. Specify the index names as a comma-separated list, for example `test1,test2,test3`. Names can include wildcards, for example `test*`. You can explicitly exclude indices by prepending `-`. For example `test*,-test3` will monitor all indexes that start with `test` except for `test3`. System indices like .security* or .kibana* always start with a `.` and generally should be monitored. Consider adding `.*` to the list of indices ensure monitoring of system indices. For example: `.*,test*,-test3` + ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Controls which indices the {{monitor-features}} collect data from. Defaults to all indices. Specify the index names as a comma-separated list, for example `test1,test2,test3`. Names can include wildcards, for example `test*`. You can explicitly exclude indices by prepending `-`. For example `test*,-test3` will monitor all indexes that start with `test` except for `test3`. System indices like .security* or .kibana* always start with a `.` and generally should be monitored. Consider adding `.*` to the list of indices ensure monitoring of system indices. For example: `.*,test*,-test3` `xpack.monitoring.collection.index.stats.timeout` : :::{admonition} Deprecated in 7.16.0 This setting was deprecated in 7.16.0. ::: - ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Timeout for collecting index statistics, in [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units). Defaults to `10s`. + ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Timeout for collecting index statistics, in [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units). Defaults to `10s`. `xpack.monitoring.collection.index.recovery.active_only` : :::{admonition} Deprecated in 7.16.0 This setting was deprecated in 7.16.0. ::: - ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Controls whether or not all recoveries are collected. Set to `true` to collect only active recoveries. Defaults to `false`. + ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Controls whether or not all recoveries are collected. Set to `true` to collect only active recoveries. Defaults to `false`. `xpack.monitoring.collection.index.recovery.timeout` : :::{admonition} Deprecated in 7.16.0 This setting was deprecated in 7.16.0. ::: - ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Timeout for collecting the recovery information, in [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units). Defaults to `10s`. + ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Timeout for collecting the recovery information, in [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units). Defaults to `10s`. `xpack.monitoring.collection.min_interval_seconds` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") : Specifies the minimum number of seconds that a time bucket in a chart can represent. If you modify the `xpack.monitoring.collection.interval`, use the same value in this setting. @@ -121,7 +121,7 @@ $$$xpack-monitoring-history-duration$$$ This setting was deprecated in 7.16.0. ::: - ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) Retention duration beyond which the indices created by a monitoring exporter are automatically deleted, in [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units). Defaults to `7d` (7 days). + ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Retention duration beyond which the indices created by a monitoring exporter are automatically deleted, in [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units). Defaults to `7d` (7 days). This setting has a minimum value of `1d` (1 day) to ensure that something is being monitored and it cannot be disabled. @@ -131,7 +131,7 @@ $$$xpack-monitoring-history-duration$$$ `xpack.monitoring.exporters` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Configures where the agent stores monitoring data. By default, the agent uses a local exporter that indexes monitoring data on the cluster where it is installed. Use an HTTP exporter to send data to a separate monitoring cluster. For more information, see [Local exporter settings](#local-exporter-settings), [HTTP exporter settings](#http-exporter-settings), and [How it works](docs-content://deploy-manage/monitor/stack-monitoring.md). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Configures where the agent stores monitoring data. By default, the agent uses a local exporter that indexes monitoring data on the cluster where it is installed. Use an HTTP exporter to send data to a separate monitoring cluster. For more information, see [Local exporter settings](#local-exporter-settings), [HTTP exporter settings](#http-exporter-settings), and [How it works](docs-content://deploy-manage/monitor/stack-monitoring.md). ### Local exporter settings [local-exporter-settings] @@ -314,7 +314,7 @@ You can configure the following TLS/SSL settings. This setting was deprecated in 7.16.0. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Supported protocols with versions. Valid protocols: `SSLv2Hello`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM’s SSL provider supports TLSv1.3, the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is `TLSv1.2,TLSv1.1`. + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Supported protocols with versions. Valid protocols: `SSLv2Hello`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM’s SSL provider supports TLSv1.3, the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is `TLSv1.2,TLSv1.1`. {{es}} relies on your JDK’s implementation of SSL and TLS. View [Supported SSL/TLS versions by JDK version](docs-content://deploy-manage/security/supported-ssltls-versions-by-jdk-version.md) for more information. @@ -328,7 +328,7 @@ You can configure the following TLS/SSL settings. This setting was deprecated in 7.16.0. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Controls the verification of certificates. + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Controls the verification of certificates. Defaults to `full`. @@ -346,7 +346,7 @@ You can configure the following TLS/SSL settings. This setting was deprecated in 7.16.0. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. For more information, see Oracle’s [Java Cryptography Architecture documentation](https://docs.oracle.com/en/java/javase/11/security/oracle-providers.md#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2). @@ -365,7 +365,7 @@ When using PEM encoded files, use the following settings: This setting was deprecated in 7.16.0. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Path to a PEM encoded file containing the private key. + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Path to a PEM encoded file containing the private key. If HTTP client authentication is required, it uses this file. You cannot use this setting and `ssl.keystore.path` at the same time. @@ -375,7 +375,7 @@ When using PEM encoded files, use the following settings: This setting was deprecated in 7.16.0. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional :::{admonition} Deprecated in 7.17.0 Prefer `ssl.secure_key_passphrase` instead. @@ -396,7 +396,7 @@ When using PEM encoded files, use the following settings: This setting was deprecated in 7.16.0. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key. + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key. This setting can be used only if `ssl.key` is set. @@ -406,7 +406,7 @@ When using PEM encoded files, use the following settings: This setting was deprecated in 7.16.0. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) List of paths to PEM encoded certificate files that should be trusted. + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) List of paths to PEM encoded certificate files that should be trusted. This setting and `ssl.truststore.path` cannot be used at the same time. @@ -421,7 +421,7 @@ When using Java keystore files (JKS), which contain the private key, certificate This setting was deprecated in 7.16.0. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.key` at the same time. @@ -431,7 +431,7 @@ When using Java keystore files (JKS), which contain the private key, certificate Prefer `ssl.keystore.secure_password` instead. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the keystore. + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the keystore. `xpack.monitoring.exporters.$NAME.ssl.keystore.secure_password` : :::{admonition} Deprecated in 7.16.0 @@ -445,7 +445,7 @@ When using Java keystore files (JKS), which contain the private key, certificate Prefer `ssl.keystore.secure_key_password` instead. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. You cannot use this setting and `ssl.keystore.secure_password` at the same time. @@ -462,7 +462,7 @@ When using Java keystore files (JKS), which contain the private key, certificate This setting was deprecated in 7.16.0. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.certificate_authorities` at the same time. @@ -472,7 +472,7 @@ When using Java keystore files (JKS), which contain the private key, certificate Prefer `ssl.truststore.secure_password` instead. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the truststore. + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the truststore. You cannot use this setting and `ssl.truststore.secure_password` at the same time. @@ -496,7 +496,7 @@ PKCS#12 files are configured in the same way as Java keystore files: This setting was deprecated in 7.16.0. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.key` at the same time. @@ -506,14 +506,14 @@ PKCS#12 files are configured in the same way as Java keystore files: This setting was deprecated in 7.16.0. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The format of the keystore file. It must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The format of the keystore file. It must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. `xpack.monitoring.exporters.$NAME.ssl.keystore.password` : :::{admonition} Deprecated in 7.16.0 This setting was deprecated in 7.16.0. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the keystore. + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the keystore. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.keystore.secure_password` instead. @@ -527,7 +527,7 @@ PKCS#12 files are configured in the same way as Java keystore files: ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password for the keystore. `xpack.monitoring.exporters.$NAME.ssl.keystore.key_password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.keystore.secure_key_password` instead. @@ -548,7 +548,7 @@ PKCS#12 files are configured in the same way as Java keystore files: This setting was deprecated in 7.16.0. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.certificate_authorities` at the same time. @@ -558,14 +558,14 @@ PKCS#12 files are configured in the same way as Java keystore files: This setting was deprecated in 7.16.0. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Set this to `PKCS12` to indicate that the truststore is a PKCS#12 file. + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Set this to `PKCS12` to indicate that the truststore is a PKCS#12 file. `xpack.monitoring.exporters.$NAME.ssl.truststore.password` : :::{admonition} Deprecated in 7.16.0 This setting was deprecated in 7.16.0. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the truststore. + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the truststore. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.truststore.secure_password` instead. diff --git a/docs/reference/elasticsearch/configuration-reference/networking-settings.md b/docs/reference/elasticsearch/configuration-reference/networking-settings.md index 85f2287d5a0a4..5cd52acadd50b 100644 --- a/docs/reference/elasticsearch/configuration-reference/networking-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/networking-settings.md @@ -30,19 +30,19 @@ Configuring {{es}} to bind to a non-local address will [convert some warnings in Most users will need to configure only the following network settings. `network.host` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), string) Sets the address of this node for both HTTP and transport traffic. The node will bind to this address and will also use it as its publish address. Accepts an IP address, a hostname, or a [special value](#network-interface-values). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), string) Sets the address of this node for both HTTP and transport traffic. The node will bind to this address and will also use it as its publish address. Accepts an IP address, a hostname, or a [special value](#network-interface-values). Defaults to `_local_`. However, note that [security auto-configuration](docs-content://deploy-manage/deploy/self-managed/installing-elasticsearch.md) will add `http.host: 0.0.0.0` to your `elasticsearch.yml` configuration file, which overrides this default for HTTP traffic. `http.port` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) The port to bind for HTTP client communication. Accepts a single value or a range. If a range is specified, the node will bind to the first available port in the range. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) The port to bind for HTTP client communication. Accepts a single value or a range. If a range is specified, the node will bind to the first available port in the range. Defaults to `9200-9300`. `transport.port` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) The port to bind for communication between nodes. Accepts a single value or a range. If a range is specified, the node will bind to the first available port in the range. Set this setting to a single port, not a range, on every master-eligible node. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) The port to bind for communication between nodes. Accepts a single value or a range. If a range is specified, the node will bind to the first available port in the range. Set this setting to a single port, not a range, on every master-eligible node. Defaults to `9300-9400`. @@ -50,7 +50,7 @@ Most users will need to configure only the following network settings. $$$remote_cluster.port$$$ `remote_cluster.port` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) The port to bind for remote cluster client communication. Accepts a single value. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) The port to bind for remote cluster client communication. Accepts a single value. Defaults to `9443`. @@ -132,10 +132,10 @@ Use the [advanced network settings](#advanced-network-settings) if you wish to b These advanced settings let you bind to multiple addresses, or to use different addresses for binding and publishing. They are not required in most cases and you should not use them if you can use the [commonly used settings](#common-network-settings) instead. `network.bind_host` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), string) The network address(es) to which the node should bind in order to listen for incoming connections. Accepts a list of IP addresses, hostnames, and [special values](#network-interface-values). Defaults to the address given by `network.host`. Use this setting only if binding to multiple addresses or using different addresses for publishing and binding. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), string) The network address(es) to which the node should bind in order to listen for incoming connections. Accepts a list of IP addresses, hostnames, and [special values](#network-interface-values). Defaults to the address given by `network.host`. Use this setting only if binding to multiple addresses or using different addresses for publishing and binding. `network.publish_host` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), string) The network address that clients and other nodes can use to contact this node. Accepts an IP address, a hostname, or a [special value](#network-interface-values). Defaults to the address given by `network.host`. Use this setting only if binding to multiple addresses or using different addresses for publishing and binding. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), string) The network address that clients and other nodes can use to contact this node. Accepts an IP address, a hostname, or a [special value](#network-interface-values). Defaults to the address given by `network.host`. Use this setting only if binding to multiple addresses or using different addresses for publishing and binding. ::::{note} You can specify a list of addresses for `network.host` and `network.publish_host`. You can also specify one or more hostnames or [special values](#network-interface-values) that resolve to multiple addresses. If you do this then {{es}} chooses one of the addresses for its publish address. This choice uses heuristics based on IPv4/IPv6 stack preference and reachability and may change when the node restarts. Ensure each node is accessible at all possible publish addresses. @@ -147,28 +147,28 @@ You can specify a list of addresses for `network.host` and `network.publish_host Use the following settings to control the low-level parameters of the TCP connections used by the HTTP and transport interfaces. `network.tcp.keep_alive` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), boolean) Configures the `SO_KEEPALIVE` option for network sockets, which determines whether each connection sends TCP keepalive probes. Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), boolean) Configures the `SO_KEEPALIVE` option for network sockets, which determines whether each connection sends TCP keepalive probes. Defaults to `true`. `network.tcp.keep_idle` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) Configures the `TCP_KEEPIDLE` option for network sockets, which determines the time in seconds that a connection must be idle before starting to send TCP keepalive probes. Defaults to `-1`, which means to use the system default. This value cannot exceed `300` seconds. Only applicable on Linux and macOS. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) Configures the `TCP_KEEPIDLE` option for network sockets, which determines the time in seconds that a connection must be idle before starting to send TCP keepalive probes. Defaults to `-1`, which means to use the system default. This value cannot exceed `300` seconds. Only applicable on Linux and macOS. `network.tcp.keep_interval` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) Configures the `TCP_KEEPINTVL` option for network sockets, which determines the time in seconds between sending TCP keepalive probes. Defaults to `-1`, which means to use the system default. This value cannot exceed `300` seconds. Only applicable on Linux and macOS. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) Configures the `TCP_KEEPINTVL` option for network sockets, which determines the time in seconds between sending TCP keepalive probes. Defaults to `-1`, which means to use the system default. This value cannot exceed `300` seconds. Only applicable on Linux and macOS. `network.tcp.keep_count` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) Configures the `TCP_KEEPCNT` option for network sockets, which determines the number of unacknowledged TCP keepalive probes that may be sent on a connection before it is dropped. Defaults to `-1`, which means to use the system default. Only applicable on Linux and macOS. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) Configures the `TCP_KEEPCNT` option for network sockets, which determines the number of unacknowledged TCP keepalive probes that may be sent on a connection before it is dropped. Defaults to `-1`, which means to use the system default. Only applicable on Linux and macOS. `network.tcp.no_delay` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), boolean) Configures the `TCP_NODELAY` option on network sockets, which determines whether [TCP no delay](https://en.wikipedia.org/wiki/Nagle%27s_algorithm) is enabled. Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), boolean) Configures the `TCP_NODELAY` option on network sockets, which determines whether [TCP no delay](https://en.wikipedia.org/wiki/Nagle%27s_algorithm) is enabled. Defaults to `true`. `network.tcp.reuse_address` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), boolean) Configures the `SO_REUSEADDR` option for network sockets, which determines whether the address can be reused or not. Defaults to `false` on Windows and `true` otherwise. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), boolean) Configures the `SO_REUSEADDR` option for network sockets, which determines whether the address can be reused or not. Defaults to `false` on Windows and `true` otherwise. `network.tcp.send_buffer_size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) Configures the size of the TCP send buffer for network sockets. Defaults to `-1` which means to use the system default. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) Configures the size of the TCP send buffer for network sockets. Defaults to `-1` which means to use the system default. `network.tcp.receive_buffer_size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) Configures the size of the TCP receive buffer. Defaults to `-1` which means to use the system default. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) Configures the size of the TCP receive buffer. Defaults to `-1` which means to use the system default. @@ -177,44 +177,44 @@ Use the following settings to control the low-level parameters of the TCP connec Use the following advanced settings to configure the HTTP interface independently of the [transport interface](#transport-settings). You can also configure both interfaces together using the [network settings](#common-network-settings). `http.host` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), string) Sets the address of this node for HTTP traffic. The node will bind to this address and will also use it as its HTTP publish address. Accepts an IP address, a hostname, or a [special value](#network-interface-values). Use this setting only if you require different configurations for the transport and HTTP interfaces. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), string) Sets the address of this node for HTTP traffic. The node will bind to this address and will also use it as its HTTP publish address. Accepts an IP address, a hostname, or a [special value](#network-interface-values). Use this setting only if you require different configurations for the transport and HTTP interfaces. Defaults to the address given by `network.host`. However, note that [security auto-configuration](docs-content://deploy-manage/deploy/self-managed/installing-elasticsearch.md) will add `http.host: 0.0.0.0` to your `elasticsearch.yml` configuration file, which overrides this default. `http.bind_host` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), string) The network address(es) to which the node should bind in order to listen for incoming HTTP connections. Accepts a list of IP addresses, hostnames, and [special values](#network-interface-values). Defaults to the address given by `http.host` or `network.bind_host`. Use this setting only if you require to bind to multiple addresses or to use different addresses for publishing and binding, and you also require different binding configurations for the transport and HTTP interfaces. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), string) The network address(es) to which the node should bind in order to listen for incoming HTTP connections. Accepts a list of IP addresses, hostnames, and [special values](#network-interface-values). Defaults to the address given by `http.host` or `network.bind_host`. Use this setting only if you require to bind to multiple addresses or to use different addresses for publishing and binding, and you also require different binding configurations for the transport and HTTP interfaces. `http.publish_host` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), string) The network address for HTTP clients to contact the node using sniffing. Accepts an IP address, a hostname, or a [special value](#network-interface-values). Defaults to the address given by `http.host` or `network.publish_host`. Use this setting only if you require to bind to multiple addresses or to use different addresses for publishing and binding, and you also require different binding configurations for the transport and HTTP interfaces. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), string) The network address for HTTP clients to contact the node using sniffing. Accepts an IP address, a hostname, or a [special value](#network-interface-values). Defaults to the address given by `http.host` or `network.publish_host`. Use this setting only if you require to bind to multiple addresses or to use different addresses for publishing and binding, and you also require different binding configurations for the transport and HTTP interfaces. `http.publish_port` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) The port of the [HTTP publish address](#modules-network-binding-publishing). Configure this setting only if you need the publish port to be different from `http.port`. Defaults to the port assigned via `http.port`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) The port of the [HTTP publish address](#modules-network-binding-publishing). Configure this setting only if you need the publish port to be different from `http.port`. Defaults to the port assigned via `http.port`. `http.max_content_length` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) Maximum size of an HTTP request body. If the body is compressed, the limit applies to the HTTP request body size before compression. Defaults to `100mb`. Configuring this setting to greater than `100mb` can cause cluster instability and is not recommended. If you hit this limit when sending a request to the [Bulk](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-bulk) API, configure your client to send fewer documents in each bulk request. If you wish to index individual documents that exceed `100mb`, pre-process them into smaller documents before sending them to {{es}}. For instance, store the raw data in a system outside {{es}} and include a link to the raw data in the documents that {{es}} indexes. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) Maximum size of an HTTP request body. If the body is compressed, the limit applies to the HTTP request body size before compression. Defaults to `100mb`. Configuring this setting to greater than `100mb` can cause cluster instability and is not recommended. If you hit this limit when sending a request to the [Bulk](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-bulk) API, configure your client to send fewer documents in each bulk request. If you wish to index individual documents that exceed `100mb`, pre-process them into smaller documents before sending them to {{es}}. For instance, store the raw data in a system outside {{es}} and include a link to the raw data in the documents that {{es}} indexes. `http.max_initial_line_length` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) Maximum size of an HTTP URL. Defaults to `4kb`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) Maximum size of an HTTP URL. Defaults to `4kb`. `http.max_header_size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) Maximum size of allowed headers. Defaults to `16kb`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) Maximum size of allowed headers. Defaults to `16kb`. $$$http-compression$$$ `http.compression` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), boolean) Support for compression when possible (with Accept-Encoding). If HTTPS is enabled, defaults to `false`. Otherwise, defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), boolean) Support for compression when possible (with Accept-Encoding). If HTTPS is enabled, defaults to `false`. Otherwise, defaults to `true`. Disabling compression for HTTPS mitigates potential security risks, such as a [BREACH attack](https://en.wikipedia.org/wiki/BREACH). To compress HTTPS traffic, you must explicitly set `http.compression` to `true`. `http.compression_level` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) Defines the compression level to use for HTTP responses. Valid values are in the range of 1 (minimum compression) and 9 (maximum compression). Defaults to `3`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) Defines the compression level to use for HTTP responses. Valid values are in the range of 1 (minimum compression) and 9 (maximum compression). Defaults to `3`. $$$http-cors-enabled$$$ `http.cors.enabled` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), boolean) Enable or disable cross-origin resource sharing, which determines whether a browser on another origin can execute requests against {{es}}. Set to `true` to enable {{es}} to process pre-flight [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) requests. {{es}} will respond to those requests with the `Access-Control-Allow-Origin` header if the `Origin` sent in the request is permitted by the `http.cors.allow-origin` list. Set to `false` (the default) to make {{es}} ignore the `Origin` request header, effectively disabling CORS requests because {{es}} will never respond with the `Access-Control-Allow-Origin` response header. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), boolean) Enable or disable cross-origin resource sharing, which determines whether a browser on another origin can execute requests against {{es}}. Set to `true` to enable {{es}} to process pre-flight [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) requests. {{es}} will respond to those requests with the `Access-Control-Allow-Origin` header if the `Origin` sent in the request is permitted by the `http.cors.allow-origin` list. Set to `false` (the default) to make {{es}} ignore the `Origin` request header, effectively disabling CORS requests because {{es}} will never respond with the `Access-Control-Allow-Origin` response header. ::::{note} If the client does not send a pre-flight request with an `Origin` header or it does not check the response headers from the server to validate the `Access-Control-Allow-Origin` response header, then cross-origin security is compromised. If CORS is not enabled on {{es}}, the only way for the client to know is to send a pre-flight request and realize the required response headers are missing. @@ -224,7 +224,7 @@ $$$http-cors-enabled$$$ $$$http-cors-allow-origin$$$ `http.cors.allow-origin` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), string) Which origins to allow. If you prepend and append a forward slash (`/`) to the value, this will be treated as a regular expression, allowing you to support HTTP and HTTPs. For example, using `/https?:\/\/localhost(:[0-9]+)?/` would return the request header appropriately in both cases. Defaults to no origins allowed. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), string) Which origins to allow. If you prepend and append a forward slash (`/`) to the value, this will be treated as a regular expression, allowing you to support HTTP and HTTPs. For example, using `/https?:\/\/localhost(:[0-9]+)?/` would return the request header appropriately in both cases. Defaults to no origins allowed. ::::{important} A wildcard (`*`) is a valid value but is considered a security risk, as your {{es}} instance is open to cross origin requests from **anywhere**. @@ -234,27 +234,27 @@ $$$http-cors-allow-origin$$$ $$$http-cors-max-age$$$ `http.cors.max-age` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) Browsers send a "preflight" OPTIONS-request to determine CORS settings. `max-age` defines for how long, in seconds, the result should be cached. Defaults to `1728000` (20 days). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) Browsers send a "preflight" OPTIONS-request to determine CORS settings. `max-age` defines for how long, in seconds, the result should be cached. Defaults to `1728000` (20 days). $$$http-cors-allow-methods$$$ `http.cors.allow-methods` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), string) Which methods to allow. Defaults to `OPTIONS, HEAD, GET, POST, PUT, DELETE`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), string) Which methods to allow. Defaults to `OPTIONS, HEAD, GET, POST, PUT, DELETE`. $$$http-cors-allow-headers$$$ `http.cors.allow-headers` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), string) Which headers to allow. Defaults to `X-Requested-With, Content-Type, Content-Length, Authorization, Accept, User-Agent, X-Elastic-Client-Meta`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), string) Which headers to allow. Defaults to `X-Requested-With, Content-Type, Content-Length, Authorization, Accept, User-Agent, X-Elastic-Client-Meta`. $$$http-cors-expose-headers$$$ `http.cors.expose-headers` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Which response headers to expose in the client. Defaults to `X-elastic-product`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Which response headers to expose in the client. Defaults to `X-elastic-product`. $$$http-cors-allow-credentials$$$ `http.cors.allow-credentials` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), boolean) Whether the `Access-Control-Allow-Credentials` header should be returned. Defaults to `false`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), boolean) Whether the `Access-Control-Allow-Credentials` header should be returned. Defaults to `false`. ::::{note} This header is only returned when the setting is set to `true`. @@ -262,49 +262,49 @@ $$$http-cors-allow-credentials$$$ `http.detailed_errors.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), boolean) Configures whether detailed error reporting in HTTP responses is enabled. Defaults to `true`. When this option is set to `false`, only basic information is returned if an error occurs in the request, and requests with [`?error_trace` parameter](/reference/elasticsearch/rest-apis/common-options.md#common-options-error-options) set are rejected. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), boolean) Configures whether detailed error reporting in HTTP responses is enabled. Defaults to `true`. When this option is set to `false`, only basic information is returned if an error occurs in the request, and requests with [`?error_trace` parameter](/reference/elasticsearch/rest-apis/common-options.md#common-options-error-options) set are rejected. `http.pipelining.max_events` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) The maximum number of events to be queued up in memory before an HTTP connection is closed, defaults to `10000`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) The maximum number of events to be queued up in memory before an HTTP connection is closed, defaults to `10000`. `http.max_warning_header_count` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) The maximum number of warning headers in client HTTP responses. Defaults to `-1` which means the number of warning headers is unlimited. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) The maximum number of warning headers in client HTTP responses. Defaults to `-1` which means the number of warning headers is unlimited. `http.max_warning_header_size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) The maximum total size of warning headers in client HTTP responses. Defaults to `-1` which means the size of the warning headers is unlimited. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) The maximum total size of warning headers in client HTTP responses. Defaults to `-1` which means the size of the warning headers is unlimited. `http.tcp.keep_alive` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), boolean) Configures the `SO_KEEPALIVE` option for this socket, which determines whether it sends TCP keepalive probes. Defaults to `network.tcp.keep_alive`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), boolean) Configures the `SO_KEEPALIVE` option for this socket, which determines whether it sends TCP keepalive probes. Defaults to `network.tcp.keep_alive`. `http.tcp.keep_idle` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) Configures the `TCP_KEEPIDLE` option for HTTP sockets, which determines the time in seconds that a connection must be idle before starting to send TCP keepalive probes. Defaults to `network.tcp.keep_idle`, which uses the system default. This value cannot exceed `300` seconds. Only applicable on Linux and macOS. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) Configures the `TCP_KEEPIDLE` option for HTTP sockets, which determines the time in seconds that a connection must be idle before starting to send TCP keepalive probes. Defaults to `network.tcp.keep_idle`, which uses the system default. This value cannot exceed `300` seconds. Only applicable on Linux and macOS. `http.tcp.keep_interval` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) Configures the `TCP_KEEPINTVL` option for HTTP sockets, which determines the time in seconds between sending TCP keepalive probes. Defaults to `network.tcp.keep_interval`, which uses the system default. This value cannot exceed `300` seconds. Only applicable on Linux and macOS. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) Configures the `TCP_KEEPINTVL` option for HTTP sockets, which determines the time in seconds between sending TCP keepalive probes. Defaults to `network.tcp.keep_interval`, which uses the system default. This value cannot exceed `300` seconds. Only applicable on Linux and macOS. `http.tcp.keep_count` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) Configures the `TCP_KEEPCNT` option for HTTP sockets, which determines the number of unacknowledged TCP keepalive probes that may be sent on a connection before it is dropped. Defaults to `network.tcp.keep_count`, which uses the system default. Only applicable on Linux and macOS. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) Configures the `TCP_KEEPCNT` option for HTTP sockets, which determines the number of unacknowledged TCP keepalive probes that may be sent on a connection before it is dropped. Defaults to `network.tcp.keep_count`, which uses the system default. Only applicable on Linux and macOS. `http.tcp.no_delay` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), boolean) Configures the `TCP_NODELAY` option on HTTP sockets, which determines whether [TCP no delay](https://en.wikipedia.org/wiki/Nagle%27s_algorithm) is enabled. Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), boolean) Configures the `TCP_NODELAY` option on HTTP sockets, which determines whether [TCP no delay](https://en.wikipedia.org/wiki/Nagle%27s_algorithm) is enabled. Defaults to `true`. `http.tcp.reuse_address` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), boolean) Configures the `SO_REUSEADDR` option for HTTP sockets, which determines whether the address can be reused or not. Defaults to `false` on Windows and `true` otherwise. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), boolean) Configures the `SO_REUSEADDR` option for HTTP sockets, which determines whether the address can be reused or not. Defaults to `false` on Windows and `true` otherwise. `http.tcp.send_buffer_size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) The size of the TCP send buffer for HTTP traffic. Defaults to `network.tcp.send_buffer_size`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) The size of the TCP send buffer for HTTP traffic. Defaults to `network.tcp.send_buffer_size`. `http.tcp.receive_buffer_size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) The size of the TCP receive buffer for HTTP traffic. Defaults to `network.tcp.receive_buffer_size`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) The size of the TCP receive buffer for HTTP traffic. Defaults to `network.tcp.receive_buffer_size`. `http.client_stats.enabled` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting), boolean) Enable or disable collection of HTTP client stats. Defaults to `true`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), boolean) Enable or disable collection of HTTP client stats. Defaults to `true`. `http.client_stats.closed_channels.max_count` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) When `http.client_stats.enabled` is `true`, sets the maximum number of closed HTTP channels for which {{es}} reports statistics. Defaults to `10000`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) When `http.client_stats.enabled` is `true`, sets the maximum number of closed HTTP channels for which {{es}} reports statistics. Defaults to `10000`. `http.client_stats.closed_channels.max_age` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), [time value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) When `http.client_stats.enabled` is `true`, sets the maximum length of time after closing a HTTP channel that {{es}} will report that channel’s statistics. Defaults to `5m`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), [time value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) When `http.client_stats.enabled` is `true`, sets the maximum length of time after closing a HTTP channel that {{es}} will report that channel’s statistics. Defaults to `5m`. ### HTTP client configuration [_http_client_configuration] @@ -322,27 +322,27 @@ If you disable the response timeout in your client, make sure to configure TCP k Use the following advanced settings to configure the transport interface independently of the [HTTP interface](#http-settings). Use the [network settings](#common-network-settings) to configure both interfaces together. `transport.host` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), string) Sets the address of this node for transport traffic. The node will bind to this address and will also use it as its transport publish address. Accepts an IP address, a hostname, or a [special value](#network-interface-values). Use this setting only if you require different configurations for the transport and HTTP interfaces. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), string) Sets the address of this node for transport traffic. The node will bind to this address and will also use it as its transport publish address. Accepts an IP address, a hostname, or a [special value](#network-interface-values). Use this setting only if you require different configurations for the transport and HTTP interfaces. Defaults to the address given by `network.host`. `transport.bind_host` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), string) The network address(es) to which the node should bind in order to listen for incoming transport connections. Accepts a list of IP addresses, hostnames, and [special values](#network-interface-values). Defaults to the address given by `transport.host` or `network.bind_host`. Use this setting only if you require to bind to multiple addresses or to use different addresses for publishing and binding, and you also require different binding configurations for the transport and HTTP interfaces. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), string) The network address(es) to which the node should bind in order to listen for incoming transport connections. Accepts a list of IP addresses, hostnames, and [special values](#network-interface-values). Defaults to the address given by `transport.host` or `network.bind_host`. Use this setting only if you require to bind to multiple addresses or to use different addresses for publishing and binding, and you also require different binding configurations for the transport and HTTP interfaces. `transport.publish_host` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), string) The network address at which the node can be contacted by other nodes. Accepts an IP address, a hostname, or a [special value](#network-interface-values). Defaults to the address given by `transport.host` or `network.publish_host`. Use this setting only if you require to bind to multiple addresses or to use different addresses for publishing and binding, and you also require different binding configurations for the transport and HTTP interfaces. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), string) The network address at which the node can be contacted by other nodes. Accepts an IP address, a hostname, or a [special value](#network-interface-values). Defaults to the address given by `transport.host` or `network.publish_host`. Use this setting only if you require to bind to multiple addresses or to use different addresses for publishing and binding, and you also require different binding configurations for the transport and HTTP interfaces. `transport.publish_port` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) The port of the [transport publish address](#modules-network-binding-publishing). Set this parameter only if you need the publish port to be different from `transport.port`. Defaults to the port assigned via `transport.port`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) The port of the [transport publish address](#modules-network-binding-publishing). Set this parameter only if you need the publish port to be different from `transport.port`. Defaults to the port assigned via `transport.port`. `transport.connect_timeout` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), [time value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) The connect timeout for initiating a new connection (in time setting format). Defaults to `30s`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), [time value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) The connect timeout for initiating a new connection (in time setting format). Defaults to `30s`. $$$transport-settings-compress$$$ `transport.compress` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), string) Determines which transport requests are compressed before sending them to another node. {{es}} will compress transport responses if and only if the corresponding request was compressed. See also `transport.compression_scheme`, which specifies the compression scheme which is used. Accepts the following values: +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), string) Determines which transport requests are compressed before sending them to another node. {{es}} will compress transport responses if and only if the corresponding request was compressed. See also `transport.compression_scheme`, which specifies the compression scheme which is used. Accepts the following values: `false` : No transport requests are compressed. This option uses the most network bandwidth, but avoids the CPU overhead of compression and decompression. @@ -357,34 +357,34 @@ $$$transport-settings-compress$$$ $$$transport-settings-compression-scheme$$$ `transport.compression_scheme` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), string) Configures the compression scheme for requests which are selected for compression by to the `transport.compress` setting. Accepts either `deflate` or `lz4`, which offer different trade-offs between compression ratio and CPU usage. {{es}} will use the same compression scheme for responses as for the corresponding requests. Defaults to `lz4`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), string) Configures the compression scheme for requests which are selected for compression by to the `transport.compress` setting. Accepts either `deflate` or `lz4`, which offer different trade-offs between compression ratio and CPU usage. {{es}} will use the same compression scheme for responses as for the corresponding requests. Defaults to `lz4`. `transport.tcp.keep_alive` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), boolean) Configures the `SO_KEEPALIVE` option for transport sockets, which determines whether they send TCP keepalive probes. Defaults to `network.tcp.keep_alive`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), boolean) Configures the `SO_KEEPALIVE` option for transport sockets, which determines whether they send TCP keepalive probes. Defaults to `network.tcp.keep_alive`. `transport.tcp.keep_idle` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) Configures the `TCP_KEEPIDLE` option for transport sockets, which determines the time in seconds that a connection must be idle before starting to send TCP keepalive probes. Defaults to `network.tcp.keep_idle` if set, or the system default otherwise. This value cannot exceed `300` seconds. In cases where the system default is higher than `300`, the value is automatically lowered to `300`. Only applicable on Linux and macOS. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) Configures the `TCP_KEEPIDLE` option for transport sockets, which determines the time in seconds that a connection must be idle before starting to send TCP keepalive probes. Defaults to `network.tcp.keep_idle` if set, or the system default otherwise. This value cannot exceed `300` seconds. In cases where the system default is higher than `300`, the value is automatically lowered to `300`. Only applicable on Linux and macOS. `transport.tcp.keep_interval` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) Configures the `TCP_KEEPINTVL` option for transport sockets, which determines the time in seconds between sending TCP keepalive probes. Defaults to `network.tcp.keep_interval` if set, or the system default otherwise. This value cannot exceed `300` seconds. In cases where the system default is higher than `300`, the value is automatically lowered to `300`. Only applicable on Linux and macOS. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) Configures the `TCP_KEEPINTVL` option for transport sockets, which determines the time in seconds between sending TCP keepalive probes. Defaults to `network.tcp.keep_interval` if set, or the system default otherwise. This value cannot exceed `300` seconds. In cases where the system default is higher than `300`, the value is automatically lowered to `300`. Only applicable on Linux and macOS. `transport.tcp.keep_count` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) Configures the `TCP_KEEPCNT` option for transport sockets, which determines the number of unacknowledged TCP keepalive probes that may be sent on a connection before it is dropped. Defaults to `network.tcp.keep_count` if set, or the system default otherwise. Only applicable on Linux and macOS. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) Configures the `TCP_KEEPCNT` option for transport sockets, which determines the number of unacknowledged TCP keepalive probes that may be sent on a connection before it is dropped. Defaults to `network.tcp.keep_count` if set, or the system default otherwise. Only applicable on Linux and macOS. `transport.tcp.no_delay` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), boolean) Configures the `TCP_NODELAY` option on transport sockets, which determines whether [TCP no delay](https://en.wikipedia.org/wiki/Nagle%27s_algorithm) is enabled. Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), boolean) Configures the `TCP_NODELAY` option on transport sockets, which determines whether [TCP no delay](https://en.wikipedia.org/wiki/Nagle%27s_algorithm) is enabled. Defaults to `true`. `transport.tcp.reuse_address` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), boolean) Configures the `SO_REUSEADDR` option for network sockets, which determines whether the address can be reused or not. Defaults to `network.tcp.reuse_address`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), boolean) Configures the `SO_REUSEADDR` option for network sockets, which determines whether the address can be reused or not. Defaults to `network.tcp.reuse_address`. `transport.tcp.send_buffer_size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) The size of the TCP send buffer for transport traffic. Defaults to `network.tcp.send_buffer_size`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) The size of the TCP send buffer for transport traffic. Defaults to `network.tcp.send_buffer_size`. `transport.tcp.receive_buffer_size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) The size of the TCP receive buffer for transport traffic. Defaults to `network.tcp.receive_buffer_size`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) The size of the TCP receive buffer for transport traffic. Defaults to `network.tcp.receive_buffer_size`. `transport.ping_schedule` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), [time value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) Configures the time between sending application-level pings on all transport connections to promptly detect when a transport connection has failed. Defaults to `-1` meaning that application-level pings are not sent. You should use TCP keepalives (see `transport.tcp.keep_alive`) instead of application-level pings wherever possible. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), [time value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) Configures the time between sending application-level pings on all transport connections to promptly detect when a transport connection has failed. Defaults to `-1` meaning that application-level pings are not sent. You should use TCP keepalives (see `transport.tcp.keep_alive`) instead of application-level pings wherever possible. ### Transport profiles [transport-profiles] @@ -428,7 +428,7 @@ The `transport.compress` setting always configures local cluster request compres ### Response compression [response-compression] -The compression settings do not configure compression for responses. {{es}} will compress a response if the inbound request was compressed—​even when compression is not enabled. Similarly, {{es}} will not compress a response if the inbound request was uncompressed—​even when compression is enabled. The compression scheme used to compress a response will be the same scheme the remote node used to compress the request. +The compression settings do not configure compression for responses. {{es}} will compress a response if the inbound request was compressed— even when compression is not enabled. Similarly, {{es}} will not compress a response if the inbound request was uncompressed— even when compression is enabled. The compression scheme used to compress a response will be the same scheme the remote node used to compress the request. @@ -437,46 +437,46 @@ The compression settings do not configure compression for responses. {{es}} will Use the following advanced settings to configure the remote cluster interface (API key based model) independently of the [transport interface](#transport-settings). You can also configure both interfaces together using the [network settings](#common-network-settings). `remote_cluster_server.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), boolean) Determines whether the remote cluster server should be enabled. This setting must be `true` for `remote_cluster.port` and all following remote cluster settings to take effect. Enabling it allows the cluster to serve cross-cluster requests using the API key based model. Defaults to `false`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), boolean) Determines whether the remote cluster server should be enabled. This setting must be `true` for `remote_cluster.port` and all following remote cluster settings to take effect. Enabling it allows the cluster to serve cross-cluster requests using the API key based model. Defaults to `false`. `remote_cluster.host` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), string) Sets the address of this node for remote cluster server traffic. The node will bind to this address and will also use it as its remote cluster server publish address. Accepts an IP address, a hostname, or a [special value](#network-interface-values). Use this setting only if you require different configurations for the remote cluster server and transport interfaces. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), string) Sets the address of this node for remote cluster server traffic. The node will bind to this address and will also use it as its remote cluster server publish address. Accepts an IP address, a hostname, or a [special value](#network-interface-values). Use this setting only if you require different configurations for the remote cluster server and transport interfaces. Defaults to the address given by `transport.bind_host`. `remote_cluster.bind_host` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), string) The network address(es) to which the node should bind in order to listen for incoming remote cluster connections. Accepts a list of IP addresses, hostnames, and [special values](#network-interface-values). Defaults to the address given by `remote_cluster.host`. Use this setting only if you require to bind to multiple addresses or to use different addresses for publishing and binding, and you also require different binding configurations for the remote cluster server and transport interfaces. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), string) The network address(es) to which the node should bind in order to listen for incoming remote cluster connections. Accepts a list of IP addresses, hostnames, and [special values](#network-interface-values). Defaults to the address given by `remote_cluster.host`. Use this setting only if you require to bind to multiple addresses or to use different addresses for publishing and binding, and you also require different binding configurations for the remote cluster server and transport interfaces. `remote_cluster.publish_host` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), string) The network address at which the node can be contacted by other nodes. Accepts an IP address, a hostname, or a [special value](#network-interface-values). Defaults to the address given by `remote_cluster.host`. Use this setting only if you require to bind to multiple addresses or to use different addresses for publishing and binding, and you also require different binding configurations for the remote cluster server and transport interfaces. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), string) The network address at which the node can be contacted by other nodes. Accepts an IP address, a hostname, or a [special value](#network-interface-values). Defaults to the address given by `remote_cluster.host`. Use this setting only if you require to bind to multiple addresses or to use different addresses for publishing and binding, and you also require different binding configurations for the remote cluster server and transport interfaces. `remote_cluster.publish_port` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) The port of the [remote cluster server publish address](#modules-network-binding-publishing). Set this parameter only if you need the publish port to be different from `remote_cluster.port`. Defaults to the port assigned via `remote_cluster.port`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) The port of the [remote cluster server publish address](#modules-network-binding-publishing). Set this parameter only if you need the publish port to be different from `remote_cluster.port`. Defaults to the port assigned via `remote_cluster.port`. `remote_cluster.tcp.keep_alive` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), boolean) Configures the `SO_KEEPALIVE` option for remote cluster sockets, which determines whether they send TCP keepalive probes. Defaults to `transport.tcp.keep_alive`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), boolean) Configures the `SO_KEEPALIVE` option for remote cluster sockets, which determines whether they send TCP keepalive probes. Defaults to `transport.tcp.keep_alive`. `remote_cluster.tcp.keep_idle` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) Configures the `TCP_KEEPIDLE` option for transport sockets, which determines the time in seconds that a connection must be idle before starting to send TCP keepalive probes. Defaults to `transport.tcp.keep_idle` if set, or the system default otherwise. This value cannot exceed `300` seconds. In cases where the system default is higher than `300`, the value is automatically lowered to `300`. Only applicable on Linux and macOS. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) Configures the `TCP_KEEPIDLE` option for transport sockets, which determines the time in seconds that a connection must be idle before starting to send TCP keepalive probes. Defaults to `transport.tcp.keep_idle` if set, or the system default otherwise. This value cannot exceed `300` seconds. In cases where the system default is higher than `300`, the value is automatically lowered to `300`. Only applicable on Linux and macOS. `remote_cluster.tcp.keep_interval` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) Configures the `TCP_KEEPINTVL` option for transport sockets, which determines the time in seconds between sending TCP keepalive probes. Defaults to `transport.tcp.keep_interval` if set, or the system default otherwise. This value cannot exceed `300` seconds. In cases where the system default is higher than `300`, the value is automatically lowered to `300`. Only applicable on Linux and macOS. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) Configures the `TCP_KEEPINTVL` option for transport sockets, which determines the time in seconds between sending TCP keepalive probes. Defaults to `transport.tcp.keep_interval` if set, or the system default otherwise. This value cannot exceed `300` seconds. In cases where the system default is higher than `300`, the value is automatically lowered to `300`. Only applicable on Linux and macOS. `remote_cluster.tcp.keep_count` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) Configures the `TCP_KEEPCNT` option for transport sockets, which determines the number of unacknowledged TCP keepalive probes that may be sent on a connection before it is dropped. Defaults to `transport.tcp.keep_count` if set, or the system default otherwise. Only applicable on Linux and macOS. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) Configures the `TCP_KEEPCNT` option for transport sockets, which determines the number of unacknowledged TCP keepalive probes that may be sent on a connection before it is dropped. Defaults to `transport.tcp.keep_count` if set, or the system default otherwise. Only applicable on Linux and macOS. `remote_cluster.tcp.no_delay` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), boolean) Configures the `TCP_NODELAY` option on transport sockets, which determines whether [TCP no delay](https://en.wikipedia.org/wiki/Nagle%27s_algorithm) is enabled. Defaults to `transport.tcp.no_delay`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), boolean) Configures the `TCP_NODELAY` option on transport sockets, which determines whether [TCP no delay](https://en.wikipedia.org/wiki/Nagle%27s_algorithm) is enabled. Defaults to `transport.tcp.no_delay`. `remote_cluster.tcp.reuse_address` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), boolean) Configures the `SO_REUSEADDR` option for network sockets, which determines whether the address can be reused or not. Defaults to `transport.tcp.reuse_address`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), boolean) Configures the `SO_REUSEADDR` option for network sockets, which determines whether the address can be reused or not. Defaults to `transport.tcp.reuse_address`. `remote_cluster.tcp.send_buffer_size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) The size of the TCP send buffer for transport traffic. Defaults to `transport.tcp.send_buffer_size`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) The size of the TCP send buffer for transport traffic. Defaults to `transport.tcp.send_buffer_size`. `remote_cluster.tcp.receive_buffer_size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) The size of the TCP receive buffer for transport traffic. Defaults to `transport.tcp.receive_buffer_size`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), [byte value](/reference/elasticsearch/rest-apis/api-conventions.md#byte-units)) The size of the TCP receive buffer for transport traffic. Defaults to `transport.tcp.receive_buffer_size`. ## Request tracing [_request_tracing] @@ -655,10 +655,10 @@ It may also be possible to identify some reasons for delays from the server logs This mechanism can be controlled with the following settings: `network.thread.watchdog.interval` - : ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), [time value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) Defines the interval between watchdog checks. Defaults to `5s`. Set to `0` to disable the network thread watchdog. + : ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), [time value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) Defines the interval between watchdog checks. Defaults to `5s`. Set to `0` to disable the network thread watchdog. `network.thread.watchdog.quiet_time` - : ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), [time value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) Defines the interval between watchdog warnings. Defaults to `10m`. + : ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), [time value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) Defines the interval between watchdog warnings. Defaults to `10m`. diff --git a/docs/reference/elasticsearch/configuration-reference/node-query-cache-settings.md b/docs/reference/elasticsearch/configuration-reference/node-query-cache-settings.md index 78ee6a0800081..a52c9f21d51fb 100644 --- a/docs/reference/elasticsearch/configuration-reference/node-query-cache-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/node-query-cache-settings.md @@ -19,7 +19,7 @@ Caching is done on a per segment basis if a segment contains at least 10000 docu The following setting is *static* and must be configured on every data node in the cluster: `indices.queries.cache.size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Controls the memory size for the filter cache. Accepts either a percentage value, like `5%`, or an exact value, like `512mb`. Defaults to `10%`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Controls the memory size for the filter cache. Accepts either a percentage value, like `5%`, or an exact value, like `512mb`. Defaults to `10%`. ## Query cache index settings [query-cache-index-settings] diff --git a/docs/reference/elasticsearch/configuration-reference/node-settings.md b/docs/reference/elasticsearch/configuration-reference/node-settings.md index 72de57879007d..e14af98f3cf8c 100644 --- a/docs/reference/elasticsearch/configuration-reference/node-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/node-settings.md @@ -118,7 +118,7 @@ You can also set a node attribute using the `-E` command line argument when you `node.attr.` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) A custom attribute that you can assign to a node. For example, you might assign a `rack_id` attribute to each node to ensure that primary and replica shards are not allocated on the same rack. You can specify multiple attributes as a comma-separated list. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) A custom attribute that you can assign to a node. For example, you might assign a `rack_id` attribute to each node to ensure that primary and replica shards are not allocated on the same rack. You can specify multiple attributes as a comma-separated list. ## Other node settings [other-node-settings] diff --git a/docs/reference/elasticsearch/configuration-reference/search-settings.md b/docs/reference/elasticsearch/configuration-reference/search-settings.md index 8b01e979d9dc0..aa8e545b11415 100644 --- a/docs/reference/elasticsearch/configuration-reference/search-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/search-settings.md @@ -17,7 +17,7 @@ $$$indices-query-bool-max-clause-count$$$ This deprecated setting has no effect. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) {{es}} will now dynamically set the maximum number of allowed clauses in a query, using a heuristic based on the size of the search thread pool and the size of the heap allocated to the JVM. This limit has a minimum value of 1024 and will in most cases be larger (for example, a node with 30Gb RAM and 48 CPUs will have a maximum clause count of around 27,000). Larger heaps lead to higher values, and larger thread pools result in lower values. + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) {{es}} will now dynamically set the maximum number of allowed clauses in a query, using a heuristic based on the size of the search thread pool and the size of the heap allocated to the JVM. This limit has a minimum value of 1024 and will in most cases be larger (for example, a node with 30Gb RAM and 48 CPUs will have a maximum clause count of around 27,000). Larger heaps lead to higher values, and larger thread pools result in lower values. Queries with many clauses should be avoided whenever possible. If you previously bumped this setting to accommodate heavy queries, you might need to increase the amount of memory available to {{es}}, or to reduce the size of your search thread pool so that more memory is available to each concurrent search. @@ -27,7 +27,7 @@ $$$indices-query-bool-max-clause-count$$$ $$$search-settings-max-buckets$$$ `search.max_buckets` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings), integer) Maximum number of [aggregation buckets](/reference/aggregations/bucket.md) allowed in a single response. Defaults to 65,536. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), integer) Maximum number of [aggregation buckets](/reference/aggregations/bucket.md) allowed in a single response. Defaults to 65,536. Requests that attempt to return more than this limit will return an error. @@ -35,7 +35,7 @@ $$$search-settings-max-buckets$$$ $$$search-settings-only-allowed-scripts$$$ `search.aggs.only_allowed_metric_scripts` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings), boolean) Configures whether only explicitly allowed scripts can be used in [scripted metrics aggregations](/reference/aggregations/search-aggregations-metrics-scripted-metric-aggregation.md). Defaults to `false`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), boolean) Configures whether only explicitly allowed scripts can be used in [scripted metrics aggregations](/reference/aggregations/search-aggregations-metrics-scripted-metric-aggregation.md). Defaults to `false`. Requests using scripts not contained in either [`search.aggs.allowed_inline_metric_scripts`](/reference/elasticsearch/configuration-reference/search-settings.md#search-settings-allowed-inline-scripts) or [`search.aggs.allowed_stored_metric_scripts`](/reference/elasticsearch/configuration-reference/search-settings.md#search-settings-allowed-stored-scripts) will return an error. @@ -43,7 +43,7 @@ $$$search-settings-only-allowed-scripts$$$ $$$search-settings-allowed-inline-scripts$$$ `search.aggs.allowed_inline_metric_scripts` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings), list of strings) List of inline scripts that can be used in scripted metrics aggregations when [`search.aggs.only_allowed_metric_scripts`](#search-settings-only-allowed-scripts) is set to `true`. Defaults to an empty list. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), list of strings) List of inline scripts that can be used in scripted metrics aggregations when [`search.aggs.only_allowed_metric_scripts`](#search-settings-only-allowed-scripts) is set to `true`. Defaults to an empty list. Requests using other inline scripts will return an error. @@ -51,7 +51,7 @@ $$$search-settings-allowed-inline-scripts$$$ $$$search-settings-allowed-stored-scripts$$$ `search.aggs.allowed_stored_metric_scripts` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings), list of strings) List of ids of stored scripts that can be used in scripted metrics aggregations when [`search.aggs.only_allowed_metric_scripts`](#search-settings-only-allowed-scripts) is set to `true`. Defaults to an empty list. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), list of strings) List of ids of stored scripts that can be used in scripted metrics aggregations when [`search.aggs.only_allowed_metric_scripts`](#search-settings-only-allowed-scripts) is set to `true`. Defaults to an empty list. Requests using other stored scripts will return an error. @@ -59,7 +59,7 @@ $$$search-settings-allowed-stored-scripts$$$ $$$indices-query-bool-max-nested-depth$$$ `indices.query.bool.max_nested_depth` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), integer) Maximum nested depth of queries. Defaults to `30`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), integer) Maximum nested depth of queries. Defaults to `30`. This setting limits the nesting depth of queries. Deep nesting of queries may lead to stack overflow errors. diff --git a/docs/reference/elasticsearch/configuration-reference/security-settings.md b/docs/reference/elasticsearch/configuration-reference/security-settings.md index f198d36eee172..1ec6600038841 100644 --- a/docs/reference/elasticsearch/configuration-reference/security-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/security-settings.md @@ -19,37 +19,37 @@ All of these settings can be added to the `elasticsearch.yml` configuration file ### General security settings [general-security-settings] `xpack.security.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Defaults to `true`, which enables {{es}} {{security-features}} on the node. This setting must be enabled to use Elasticsearch’s authentication, authorization and audit features.
+: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Defaults to `true`, which enables {{es}} {{security-features}} on the node. This setting must be enabled to use Elasticsearch’s authentication, authorization and audit features.
If set to `false`, {{security-features}} are disabled, which is not recommended. It also affects all {{kib}} instances that connect to this {{es}} instance; you do not need to disable {{security-features}} in those `kibana.yml` files. For more information about disabling {{security-features}} in specific {{kib}} instances, see [{{kib}} security settings](kibana://reference/configuration-reference/security-settings.md). `xpack.security.autoconfiguration.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Defaults to `true`, which enables [security auto configuration](docs-content://deploy-manage/deploy/self-managed/installing-elasticsearch.md). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Defaults to `true`, which enables [security auto configuration](docs-content://deploy-manage/deploy/self-managed/installing-elasticsearch.md). If set to `false`, security auto configuration is disabled, which is not recommended. When disabled, security is not configured automatically when starting {{es}} for the first time, which means that you must [manually configure security](docs-content://deploy-manage/security/manually-configure-security-in-self-managed-cluster.md). `xpack.security.enrollment.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Defaults to `false`. Controls enrollment (of nodes and {{kib}}) to a local node that’s been [autoconfigured for security](docs-content://deploy-manage/deploy/self-managed/installing-elasticsearch.md). When set to `true`, the local node can generate new enrollment tokens. Existing tokens can be used for enrollment if they are still valid. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Defaults to `false`. Controls enrollment (of nodes and {{kib}}) to a local node that’s been [autoconfigured for security](docs-content://deploy-manage/deploy/self-managed/installing-elasticsearch.md). When set to `true`, the local node can generate new enrollment tokens. Existing tokens can be used for enrollment if they are still valid. The security autoconfiguration process will set this to `true` unless an administrator sets it to `false` before starting {{es}}. `xpack.security.hide_settings` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) A comma-separated list of settings that are omitted from the results of the [cluster nodes info API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-nodes-info). You can use wildcards to include multiple settings in the list. For example, the following value hides all the settings for the ad1 active_directory realm: `xpack.security.authc.realms.active_directory.ad1.*`. The API already omits all `ssl` settings, `bind_dn`, and `bind_password` due to the sensitive nature of the information. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) A comma-separated list of settings that are omitted from the results of the [cluster nodes info API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-nodes-info). You can use wildcards to include multiple settings in the list. For example, the following value hides all the settings for the ad1 active_directory realm: `xpack.security.authc.realms.active_directory.ad1.*`. The API already omits all `ssl` settings, `bind_dn`, and `bind_password` due to the sensitive nature of the information. `xpack.security.fips_mode.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Enables fips mode of operation. Set this to `true` if you run this {{es}} instance in a FIPS 140-2 enabled JVM. For more information, see [FIPS 140-2](docs-content://deploy-manage/security/fips-140-2.md). Defaults to `false`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Enables fips mode of operation. Set this to `true` if you run this {{es}} instance in a FIPS 140-2 enabled JVM. For more information, see [FIPS 140-2](docs-content://deploy-manage/security/fips-140-2.md). Defaults to `false`. `xpack.security.fips_mode.required_providers` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Optionally enforce specific Java JCE/JSSE security providers. For example, set this to `["BCFIPS", "BCJSSE"]` (case-insensitive) to require the Bouncy Castle FIPS JCE and JSSE security providers. Only applicable when `xpack.security.fips_mode.enabled` is set to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Optionally enforce specific Java JCE/JSSE security providers. For example, set this to `["BCFIPS", "BCJSSE"]` (case-insensitive) to require the Bouncy Castle FIPS JCE and JSSE security providers. Only applicable when `xpack.security.fips_mode.enabled` is set to `true`. ### Password hashing settings [password-hashing-settings] `xpack.security.authc.password_hashing.algorithm` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the hashing algorithm that is used for secure user credential storage. See [Table 2, Password hashing algorithms](#password-hashing-algorithms). If `xpack.security.fips_mode.enabled` is true (see [FIPS 140-2](docs-content://deploy-manage/security/fips-140-2.md)), defaults to `pbkdf2_stretch`. In all other cases, defaults to `bcrypt`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the hashing algorithm that is used for secure user credential storage. See [Table 2, Password hashing algorithms](#password-hashing-algorithms). If `xpack.security.fips_mode.enabled` is true (see [FIPS 140-2](docs-content://deploy-manage/security/fips-140-2.md)), defaults to `pbkdf2_stretch`. In all other cases, defaults to `bcrypt`. ### Anonymous access settings [anonymous-access-settings] @@ -57,13 +57,13 @@ All of these settings can be added to the `elasticsearch.yml` configuration file You can configure the following anonymous access settings in `elasticsearch.yml`. For more information, see [Enabling anonymous access](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/anonymous-access.md). `xpack.security.authc.anonymous.username` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The username (principal) of the anonymous user. Defaults to `_es_anonymous_user`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The username (principal) of the anonymous user. Defaults to `_es_anonymous_user`. `xpack.security.authc.anonymous.roles` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The roles to associate with the anonymous user. Required. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The roles to associate with the anonymous user. Required. `xpack.security.authc.anonymous.authz_exception` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) When `true`, an HTTP 403 response is returned if the anonymous user does not have the appropriate permissions for the requested action. The user is not prompted to provide credentials to access the requested resource. When set to `false`, an HTTP 401 response is returned and the user can provide credentials with the appropriate permissions to gain access. Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) When `true`, an HTTP 403 response is returned if the anonymous user does not have the appropriate permissions for the requested action. The user is not prompted to provide credentials to access the requested resource. When set to `false`, an HTTP 401 response is returned and the user can provide credentials with the appropriate permissions to gain access. Defaults to `true`. ### Automata Settings [security-automata-settings] @@ -71,16 +71,16 @@ You can configure the following anonymous access settings in `elasticsearch.yml` In places where the {{security-features}} accept wildcard patterns (e.g. index patterns in roles, group matches in the role mapping API), each pattern is compiled into an Automaton. The follow settings are available to control this behaviour. `xpack.security.automata.max_determinized_states` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The upper limit on how many automaton states may be created by a single pattern. This protects against too-difficult (e.g. exponentially hard) patterns. Defaults to `100,000`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The upper limit on how many automaton states may be created by a single pattern. This protects against too-difficult (e.g. exponentially hard) patterns. Defaults to `100,000`. `xpack.security.automata.cache.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Whether to cache the compiled automata. Compiling automata can be CPU intensive and may slowdown some operations. The cache reduces the frequency with which automata need to be compiled. Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Whether to cache the compiled automata. Compiling automata can be CPU intensive and may slowdown some operations. The cache reduces the frequency with which automata need to be compiled. Defaults to `true`. `xpack.security.automata.cache.size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The maximum number of items to retain in the automata cache. Defaults to `10,000`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The maximum number of items to retain in the automata cache. Defaults to `10,000`. `xpack.security.automata.cache.ttl` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The length of time to retain in an item in the automata cache (based on most recent usage). Defaults to `48h` (48 hours). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The length of time to retain in an item in the automata cache (based on most recent usage). Defaults to `48h` (48 hours). ### Document and field level security settings [field-document-security-settings] @@ -88,13 +88,13 @@ In places where the {{security-features}} accept wildcard patterns (e.g. index p You can set the following document and field level security settings in `elasticsearch.yml`. For more information, see [Setting up field and document level security](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md). `xpack.security.dls_fls.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Set to `false` to prevent document and field level security from being configured. Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Set to `false` to prevent document and field level security from being configured. Defaults to `true`. `xpack.security.dls.bitset.cache.ttl` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The time-to-live for cached `BitSet` entries for document level security. Document level security queries may depend on Lucene BitSet objects, and these are automatically cached to improve performance. Defaults to expire entries that are unused for `2h` (2 hours). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The time-to-live for cached `BitSet` entries for document level security. Document level security queries may depend on Lucene BitSet objects, and these are automatically cached to improve performance. Defaults to expire entries that are unused for `2h` (2 hours). `xpack.security.dls.bitset.cache.size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The maximum memory usage of cached `BitSet` entries for document level security. Document level security queries may depend on Lucene BitSet objects, and these are automatically cached to improve performance. Can be configured as a raw number of bytes (such as `200mb` or `1g`) or a percentage of the node’s JVM heap memory (such as `5%`). When the default value is exceeded, the least recently used entries are evicted. Defaults to `10%` of the heap assigned to the node. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The maximum memory usage of cached `BitSet` entries for document level security. Document level security queries may depend on Lucene BitSet objects, and these are automatically cached to improve performance. Can be configured as a raw number of bytes (such as `200mb` or `1g`) or a percentage of the node’s JVM heap memory (such as `5%`). When the default value is exceeded, the least recently used entries are evicted. Defaults to `10%` of the heap assigned to the node. ### Token service settings [token-service-settings] @@ -102,10 +102,10 @@ You can set the following document and field level security settings in `elastic You can set the following token service settings in `elasticsearch.yml`. `xpack.security.authc.token.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Set to `false` to disable the built-in token service. Defaults to `true` unless `xpack.security.http.ssl.enabled` is `false`. This prevents sniffing the token from a connection over plain http. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Set to `false` to disable the built-in token service. Defaults to `true` unless `xpack.security.http.ssl.enabled` is `false`. This prevents sniffing the token from a connection over plain http. `xpack.security.authc.token.timeout` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The length of time that a token is valid for. By default this value is `20m` or 20 minutes. The maximum value is 1 hour. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The length of time that a token is valid for. By default this value is `20m` or 20 minutes. The maximum value is 1 hour. ### API key service settings [api-key-service-settings] @@ -113,21 +113,21 @@ You can set the following token service settings in `elasticsearch.yml`. You can set the following API key service settings in `elasticsearch.yml`. `xpack.security.authc.api_key.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Set to `false` to disable the built-in API key service. Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Set to `false` to disable the built-in API key service. Defaults to `true`. `xpack.security.authc.api_key.cache.ttl` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The time-to-live for cached API key entries. A API key id and a hash of its API key are cached for this period of time. Specify the time period using the standard {{es}} [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units). Defaults to `1d`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The time-to-live for cached API key entries. A API key id and a hash of its API key are cached for this period of time. Specify the time period using the standard {{es}} [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units). Defaults to `1d`. `xpack.security.authc.api_key.cache.max_keys` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The maximum number of API key entries that can live in the cache at any given time. Defaults to 10,000. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The maximum number of API key entries that can live in the cache at any given time. Defaults to 10,000. `xpack.security.authc.api_key.cache.hash_algo` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), Expert) The hashing algorithm that is used for the in-memory cached API key credentials. For possible values, see [Table 1, Cache hash algorithms](#cache-hash-algo). Defaults to `ssha256`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), Expert) The hashing algorithm that is used for the in-memory cached API key credentials. For possible values, see [Table 1, Cache hash algorithms](#cache-hash-algo). Defaults to `ssha256`. $$$api-key-service-settings-delete-retention-period$$$ `xpack.security.authc.api_key.delete.retention_period` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Invalidated or expired API keys older than the retention period are eligible for deletion. Defaults to `7d`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Invalidated or expired API keys older than the retention period are eligible for deletion. Defaults to `7d`. ::::{note} Large real-time clock inconsistency across cluster nodes can cause problems with evaluating the API key retention period. That is, if the clock on the node invalidating the API key is significantly different than the one performing the deletion, the key may be retained for longer or shorter than the configured retention period. @@ -135,7 +135,7 @@ Large real-time clock inconsistency across cluster nodes can cause problems with `xpack.security.authc.api_key.delete.interval` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting), Expert) Cluster nodes schedule the automatic deletion of invalidated or expired API keys that are older than the retention period. This setting controls the minimum time interval between two such deletion jobs. Defaults to `24h`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), Expert) Cluster nodes schedule the automatic deletion of invalidated or expired API keys that are older than the retention period. This setting controls the minimum time interval between two such deletion jobs. Defaults to `24h`. ::::{note} This is a low-level setting that currently controls the interval between deletion jobs triggered per-node, not across the cluster. @@ -143,10 +143,10 @@ Large real-time clock inconsistency across cluster nodes can cause problems with `xpack.security.authc.api_key.delete.timeout` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), Expert) Sets the timeout of the internal search and delete call. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), Expert) Sets the timeout of the internal search and delete call. `xpack.security.authc.api_key.hashing.algorithm` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the hashing algorithm that is used for securing API key credentials. See [Table 3, Secure token hashing algorithms](#secure-token-hashing-algorithms). Defaults to `ssha256`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the hashing algorithm that is used for securing API key credentials. See [Table 3, Secure token hashing algorithms](#secure-token-hashing-algorithms). Defaults to `ssha256`. ### Security domain settings [security-domain-settings] @@ -218,10 +218,10 @@ The valid settings vary depending on the realm type. For more information, see [ #### Settings valid for all realms [ref-realm-settings] `order` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The priority of the realm within the realm chain. Realms with a lower order are consulted first. The value must be unique for each realm. This setting is required. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The priority of the realm within the realm chain. Realms with a lower order are consulted first. The value must be unique for each realm. This setting is required. `enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Indicates whether a realm is enabled. You can use this setting to disable a realm without removing its configuration information. Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Indicates whether a realm is enabled. You can use this setting to disable a realm without removing its configuration information. Defaults to `true`. #### Native realm settings [ref-native-settings] @@ -229,16 +229,16 @@ The valid settings vary depending on the realm type. For more information, see [ In addition to the [settings that are valid for all realms](#ref-realm-settings), you can specify the following optional settings: `cache.ttl` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The time-to-live for cached user entries. A user and a hash of its credentials are cached for this period of time. Specify the time period using the standard {{es}} [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units). Defaults to `20m`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The time-to-live for cached user entries. A user and a hash of its credentials are cached for this period of time. Specify the time period using the standard {{es}} [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units). Defaults to `20m`. `cache.max_users` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The maximum number of user entries that can live in the cache at any given time. Defaults to 100,000. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The maximum number of user entries that can live in the cache at any given time. Defaults to 100,000. `cache.hash_algo` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), Expert) The hashing algorithm that is used for the in-memory cached user credentials. For possible values, see [Table 1, Cache hash algorithms](#cache-hash-algo). Defaults to `ssha256`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), Expert) The hashing algorithm that is used for the in-memory cached user credentials. For possible values, see [Table 1, Cache hash algorithms](#cache-hash-algo). Defaults to `ssha256`. `authentication.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) If set to `false`, disables authentication support in this realm, so that it only supports user lookups. (See the [run as](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md) and [authorization realms](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms) features). Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) If set to `false`, disables authentication support in this realm, so that it only supports user lookups. (See the [run as](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md) and [authorization realms](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms) features). Defaults to `true`. #### File realm settings [ref-users-settings] @@ -246,16 +246,16 @@ In addition to the [settings that are valid for all realms](#ref-realm-settings) In addition to the [settings that are valid for all realms](#ref-realm-settings), you can specify the following settings: `cache.ttl` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The time-to-live for cached user entries. A user and a hash of its credentials are cached for this configured period of time. Defaults to `20m`. Specify values using the standard {{es}} [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units). Defaults to `20m`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The time-to-live for cached user entries. A user and a hash of its credentials are cached for this configured period of time. Defaults to `20m`. Specify values using the standard {{es}} [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units). Defaults to `20m`. `cache.max_users` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The maximum number of user entries that can live in the cache at a given time. Defaults to 100,000. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The maximum number of user entries that can live in the cache at a given time. Defaults to 100,000. `cache.hash_algo` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), Expert) The hashing algorithm that is used for the in-memory cached user credentials. See [Table 1, Cache hash algorithms](#cache-hash-algo). Defaults to `ssha256`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), Expert) The hashing algorithm that is used for the in-memory cached user credentials. See [Table 1, Cache hash algorithms](#cache-hash-algo). Defaults to `ssha256`. `authentication.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) If set to `false`, disables authentication support in this realm, so that it only supports user lookups. (See the [run as](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md) and [authorization realms](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms) features). Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) If set to `false`, disables authentication support in this realm, so that it only supports user lookups. (See the [run as](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md) and [authorization realms](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms) features). Defaults to `true`. #### LDAP realm settings [ref-ldap-settings] @@ -263,7 +263,7 @@ In addition to the [settings that are valid for all realms](#ref-realm-settings) In addition to the [Settings valid for all realms](#ref-realm-settings), you can specify the following settings: `url` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) One or more LDAP URLs in the `ldap[s]://:` format. Required. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) One or more LDAP URLs in the `ldap[s]://:` format. Required. To provide multiple URLs, use a YAML array (`["ldap://server1:636", "ldap://server2:636"]`) or comma-separated string (`"ldap://server1:636, ldap://server2:636"`). @@ -271,29 +271,29 @@ In addition to the [Settings valid for all realms](#ref-realm-settings), you can `load_balance.type` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The behavior to use when there are multiple LDAP URLs defined. For supported values see [load balancing and failover types](#load-balancing). Defaults to `failover`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The behavior to use when there are multiple LDAP URLs defined. For supported values see [load balancing and failover types](#load-balancing). Defaults to `failover`. `load_balance.cache_ttl` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) When using `dns_failover` or `dns_round_robin` as the load balancing type, this setting controls the amount of time to cache DNS lookups. Defaults to `1h`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) When using `dns_failover` or `dns_round_robin` as the load balancing type, this setting controls the amount of time to cache DNS lookups. Defaults to `1h`. `bind_dn` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The DN of the user that is used to bind to the LDAP and perform searches. Only applicable in user search mode. If not specified, an anonymous bind is attempted. Defaults to Empty. Due to its potential security impact, `bind_dn` is not exposed via the [nodes info API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-nodes-info). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The DN of the user that is used to bind to the LDAP and perform searches. Only applicable in user search mode. If not specified, an anonymous bind is attempted. Defaults to Empty. Due to its potential security impact, `bind_dn` is not exposed via the [nodes info API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-nodes-info). `bind_password` : :::{admonition} Deprecated in 6.3 Use `secure_bind_password` instead. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the user that is used to bind to the LDAP directory. Defaults to Empty. Due to its potential security impact, `bind_password` is not exposed via the [nodes info API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-nodes-info). + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the user that is used to bind to the LDAP directory. Defaults to Empty. Due to its potential security impact, `bind_password` is not exposed via the [nodes info API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-nodes-info). `secure_bind_password` : ([Secure](docs-content://deploy-manage/security/secure-settings.md), [Reloadable](docs-content://deploy-manage/security/secure-settings.md#reloadable-secure-settings)) The password for the user that is used to bind to the LDAP directory. Defaults to Empty. `user_dn_templates` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The DN template that replaces the user name with the string `{{0}}`. This setting is multivalued; you can specify multiple user contexts. Required to operate in user template mode. If `user_search.base_dn` is specified, this setting is not valid. For more information on the different modes, see [LDAP user authentication](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/ldap.md). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The DN template that replaces the user name with the string `{{0}}`. This setting is multivalued; you can specify multiple user contexts. Required to operate in user template mode. If `user_search.base_dn` is specified, this setting is not valid. For more information on the different modes, see [LDAP user authentication](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/ldap.md). `authorization_realms` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The names of the realms that should be consulted for delegated authorization. If this setting is used, then the LDAP realm does not perform role mapping and instead loads the user from the listed realms. The referenced realms are consulted in the order that they are defined in this list. See [Delegating authorization to another realm](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The names of the realms that should be consulted for delegated authorization. If this setting is used, then the LDAP realm does not perform role mapping and instead loads the user from the listed realms. The referenced realms are consulted in the order that they are defined in this list. See [Delegating authorization to another realm](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms). ::::{note} If any settings starting with `user_search` are specified, the `user_dn_templates` settings are ignored. @@ -301,90 +301,90 @@ In addition to the [Settings valid for all realms](#ref-realm-settings), you can `user_group_attribute` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the attribute to examine on the user for group membership. If any `group_search` settings are specified, this setting is ignored. Defaults to `memberOf`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the attribute to examine on the user for group membership. If any `group_search` settings are specified, this setting is ignored. Defaults to `memberOf`. `user_full_name_attribute` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the attribute to examine on the user for the full name of the user. Defaults to `cn`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the attribute to examine on the user for the full name of the user. Defaults to `cn`. `user_email_attribute` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the attribute to examine on the user for the email address of the user. Defaults to `mail`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the attribute to examine on the user for the email address of the user. Defaults to `mail`. `user_search.base_dn` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies a container DN to search for users. Required to operated in user search mode. If `user_dn_templates` is specified, this setting is not valid. For more information on the different modes, see [LDAP user authentication](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/ldap.md). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies a container DN to search for users. Required to operated in user search mode. If `user_dn_templates` is specified, this setting is not valid. For more information on the different modes, see [LDAP user authentication](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/ldap.md). `user_search.scope` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The scope of the user search. Valid values are `sub_tree`, `one_level` or `base`. `one_level` only searches objects directly contained within the `base_dn`. `sub_tree` searches all objects contained under `base_dn`. `base` specifies that the `base_dn` is the user object, and that it is the only user considered. Defaults to `sub_tree`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The scope of the user search. Valid values are `sub_tree`, `one_level` or `base`. `one_level` only searches objects directly contained within the `base_dn`. `sub_tree` searches all objects contained under `base_dn`. `base` specifies that the `base_dn` is the user object, and that it is the only user considered. Defaults to `sub_tree`. `user_search.filter` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the filter used to search the directory in attempts to match an entry with the username provided by the user. Defaults to `(uid={{0}})`. `{{0}}` is substituted with the username provided when searching. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the filter used to search the directory in attempts to match an entry with the username provided by the user. Defaults to `(uid={{0}})`. `{{0}}` is substituted with the username provided when searching. `user_search.attribute` : :::{admonition} Deprecated in 5.6 Use `user_search.filter` instead. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The attribute to match with the username sent with the request. Defaults to `uid`. + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The attribute to match with the username sent with the request. Defaults to `uid`. `user_search.pool.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Enables or disables connection pooling for user search. If set to `false`, a new connection is created for every search. The default is `true` when `bind_dn` is set. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Enables or disables connection pooling for user search. If set to `false`, a new connection is created for every search. The default is `true` when `bind_dn` is set. `user_search.pool.size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The maximum number of connections to the LDAP server to allow in the connection pool. Defaults to `20`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The maximum number of connections to the LDAP server to allow in the connection pool. Defaults to `20`. `user_search.pool.initial_size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The initial number of connections to create to the LDAP server on startup. Defaults to `0`. If the LDAP server is down, values greater than `0` could cause startup failures. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The initial number of connections to create to the LDAP server on startup. Defaults to `0`. If the LDAP server is down, values greater than `0` could cause startup failures. `user_search.pool.health_check.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Enables or disables a health check on LDAP connections in the connection pool. Connections are checked in the background at the specified interval. Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Enables or disables a health check on LDAP connections in the connection pool. Connections are checked in the background at the specified interval. Defaults to `true`. `user_search.pool.health_check.dn` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The distinguished name that is retrieved as part of the health check. Defaults to the value of `bind_dn` if present; if not, falls back to `user_search.base_dn`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The distinguished name that is retrieved as part of the health check. Defaults to the value of `bind_dn` if present; if not, falls back to `user_search.base_dn`. `user_search.pool.health_check.interval` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The interval to perform background checks of connections in the pool. Defaults to `60s`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The interval to perform background checks of connections in the pool. Defaults to `60s`. `group_search.base_dn` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The container DN to search for groups in which the user has membership. When this element is absent, {{es}} searches for the attribute specified by `user_group_attribute` set on the user in order to determine group membership. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The container DN to search for groups in which the user has membership. When this element is absent, {{es}} searches for the attribute specified by `user_group_attribute` set on the user in order to determine group membership. `group_search.scope` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies whether the group search should be `sub_tree`, `one_level` or `base`. `one_level` only searches objects directly contained within the `base_dn`. `sub_tree` searches all objects contained under `base_dn`. `base` specifies that the `base_dn` is a group object, and that it is the only group considered. Defaults to `sub_tree`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies whether the group search should be `sub_tree`, `one_level` or `base`. `one_level` only searches objects directly contained within the `base_dn`. `sub_tree` searches all objects contained under `base_dn`. `base` specifies that the `base_dn` is a group object, and that it is the only group considered. Defaults to `sub_tree`. `group_search.filter` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies a filter to use to look up a group. When not set, the realm searches for `group`, `groupOfNames`, `groupOfUniqueNames`, or `posixGroup` with the attributes `member`, `memberOf`, or `memberUid`. Any instance of `{{0}}` in the filter is replaced by the user attribute defined in `group_search.user_attribute`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies a filter to use to look up a group. When not set, the realm searches for `group`, `groupOfNames`, `groupOfUniqueNames`, or `posixGroup` with the attributes `member`, `memberOf`, or `memberUid`. Any instance of `{{0}}` in the filter is replaced by the user attribute defined in `group_search.user_attribute`. `group_search.user_attribute` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the user attribute that is fetched and provided as a parameter to the filter. If not set, the user DN is passed into the filter. Defaults to Empty. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the user attribute that is fetched and provided as a parameter to the filter. If not set, the user DN is passed into the filter. Defaults to Empty. `unmapped_groups_as_roles` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) If set to `true`, the names of any unmapped LDAP groups are used as role names and assigned to the user. A group is considered to be *unmapped* if it is not referenced in a [role-mapping file](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md#mapping-roles-file). API-based role mappings are not considered. Defaults to `false`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) If set to `true`, the names of any unmapped LDAP groups are used as role names and assigned to the user. A group is considered to be *unmapped* if it is not referenced in a [role-mapping file](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md#mapping-roles-file). API-based role mappings are not considered. Defaults to `false`. `files.role_mapping` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The [location](docs-content://deploy-manage/security.md) for the [YAML role mapping configuration file](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md). Defaults to `ES_PATH_CONF/role_mapping.yml`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The [location](docs-content://deploy-manage/security.md) for the [YAML role mapping configuration file](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md). Defaults to `ES_PATH_CONF/role_mapping.yml`. `follow_referrals` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies whether {{es}} should follow referrals returned by the LDAP server. Referrals are URLs returned by the server that are to be used to continue the LDAP operation (for example, search). Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies whether {{es}} should follow referrals returned by the LDAP server. Referrals are URLs returned by the server that are to be used to continue the LDAP operation (for example, search). Defaults to `true`. `metadata` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) A list of additional LDAP attributes that should be loaded from the LDAP server and stored in the authenticated user’s metadata field. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) A list of additional LDAP attributes that should be loaded from the LDAP server and stored in the authenticated user’s metadata field. `timeout.tcp_connect` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The TCP connect timeout period for establishing an LDAP connection. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to `5s` (5 seconds ). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The TCP connect timeout period for establishing an LDAP connection. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to `5s` (5 seconds ). `timeout.tcp_read` : :::{admonition} Deprecated in 7.7 This setting was deprecated in 7.7. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The TCP read timeout period after establishing an LDAP connection. This is equivalent to and is deprecated in favor of `timeout.response` and they cannot be used simultaneously. An `s` at the end indicates seconds, or `ms` indicates milliseconds. + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The TCP read timeout period after establishing an LDAP connection. This is equivalent to and is deprecated in favor of `timeout.response` and they cannot be used simultaneously. An `s` at the end indicates seconds, or `ms` indicates milliseconds. `timeout.response` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The time interval to wait for the response from the LDAP server. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to the value of `timeout.ldap_search`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The time interval to wait for the response from the LDAP server. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to the value of `timeout.ldap_search`. `timeout.ldap_search` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The timeout period for an LDAP search. The value is specified in the request and is enforced by the receiving LDAP Server. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to `5s` (5 seconds ). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The timeout period for an LDAP search. The value is specified in the request and is enforced by the receiving LDAP Server. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to `5s` (5 seconds ). `ssl.key` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Path to a PEM encoded file containing the private key. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Path to a PEM encoded file containing the private key. If HTTP client authentication is required, it uses this file. You cannot use this setting and `ssl.keystore.path` at the same time. @@ -392,7 +392,7 @@ In addition to the [Settings valid for all realms](#ref-realm-settings), you can `ssl.key_passphrase` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.secure_key_passphrase` instead. @@ -405,7 +405,7 @@ In addition to the [Settings valid for all realms](#ref-realm-settings), you can : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional. `ssl.certificate` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key. This setting can be used only if `ssl.key` is set. @@ -413,7 +413,7 @@ In addition to the [Settings valid for all realms](#ref-realm-settings), you can `ssl.certificate_authorities` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) List of paths to PEM encoded certificate files that should be trusted. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) List of paths to PEM encoded certificate files that should be trusted. This setting and `ssl.truststore.path` cannot be used at the same time. @@ -421,7 +421,7 @@ In addition to the [Settings valid for all realms](#ref-realm-settings), you can `ssl.keystore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.key` at the same time. @@ -429,10 +429,10 @@ In addition to the [Settings valid for all realms](#ref-realm-settings), you can `ssl.keystore.type` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The format of the keystore file. It must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The format of the keystore file. It must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. `ssl.keystore.password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the keystore. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the keystore. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.keystore.secure_password` instead. @@ -442,7 +442,7 @@ In addition to the [Settings valid for all realms](#ref-realm-settings), you can : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password for the keystore. `ssl.keystore.key_password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.keystore.secure_key_password` instead. @@ -452,10 +452,10 @@ In addition to the [Settings valid for all realms](#ref-realm-settings), you can `ssl.keystore.secure_key_password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. `ssl.truststore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.certificate_authorities` at the same time. @@ -463,7 +463,7 @@ In addition to the [Settings valid for all realms](#ref-realm-settings), you can `ssl.truststore.password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the truststore. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the truststore. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.truststore.secure_password` instead. @@ -476,10 +476,10 @@ In addition to the [Settings valid for all realms](#ref-realm-settings), you can : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) Password for the truststore. `ssl.truststore.type` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The format of the truststore file. It must be either `jks` or `PKCS12`. If the file name ends in ".p12", ".pfx" or "pkcs12", the default is `PKCS12`. Otherwise, it defaults to `jks`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The format of the truststore file. It must be either `jks` or `PKCS12`. If the file name ends in ".p12", ".pfx" or "pkcs12", the default is `PKCS12`. Otherwise, it defaults to `jks`. `ssl.verification_mode` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Indicates the type of verification when using `ldaps` to protect against man in the middle attacks and certificate forgery. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Indicates the type of verification when using `ldaps` to protect against man in the middle attacks and certificate forgery. Defaults to `full`. @@ -493,7 +493,7 @@ In addition to the [Settings valid for all realms](#ref-realm-settings), you can :::: `ssl.supported_protocols` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Supported protocols with versions. Valid protocols: `SSLv2Hello`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. The default is `TLSv1.3,TLSv1.2`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Supported protocols with versions. Valid protocols: `SSLv2Hello`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. The default is `TLSv1.3,TLSv1.2`. {{es}} relies on your JDK’s implementation of SSL and TLS. View [Supported SSL/TLS versions by JDK version](docs-content://deploy-manage/security/supported-ssltls-versions-by-jdk-version.md) for more information. @@ -503,22 +503,22 @@ In addition to the [Settings valid for all realms](#ref-realm-settings), you can `ssl.cipher_suites` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the cipher suites that should be supported when communicating with the LDAP server. Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the cipher suites that should be supported when communicating with the LDAP server. Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. For more information, see Oracle’s [Java Cryptography Architecture documentation](https://docs.oracle.com/en/java/javase/11/security/oracle-providers.md#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2). `cache.ttl` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the time-to-live for cached user entries. A user and a hash of its credentials are cached for this period of time. Use the standard {{es}} [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units). Defaults to `20m`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the time-to-live for cached user entries. A user and a hash of its credentials are cached for this period of time. Use the standard {{es}} [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units). Defaults to `20m`. `cache.max_users` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the maximum number of user entries that the cache can contain. Defaults to `100000`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the maximum number of user entries that the cache can contain. Defaults to `100000`. `cache.hash_algo` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), Expert) Specifies the hashing algorithm that is used for the in-memory cached user credentials. See [Table 1, Cache hash algorithms](#cache-hash-algo). Defaults to `ssha256`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), Expert) Specifies the hashing algorithm that is used for the in-memory cached user credentials. See [Table 1, Cache hash algorithms](#cache-hash-algo). Defaults to `ssha256`. `authentication.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) If set to `false`, disables authentication support in this realm, so that it only supports user lookups. (See the [run as](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md) and [authorization realms](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms) features). Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) If set to `false`, disables authentication support in this realm, so that it only supports user lookups. (See the [run as](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md) and [authorization realms](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms) features). Defaults to `true`. #### Active Directory realm settings [ref-ad-settings] @@ -526,7 +526,7 @@ In addition to the [Settings valid for all realms](#ref-realm-settings), you can In addition to the [settings that are valid for all realms](#ref-realm-settings), you can specify the following settings: `url` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) One or more LDAP URLs in the `ldap[s]://:` format. Defaults to `ldap://:389`. This setting is required when connecting using SSL/TLS or when using a custom port. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) One or more LDAP URLs in the `ldap[s]://:` format. Defaults to `ldap://:389`. This setting is required when connecting using SSL/TLS or when using a custom port. To provide multiple URLs, use a YAML array (`["ldap://server1:636", "ldap://server2:636"]`) or comma-separated string (`"ldap://server1:636, ldap://server2:636"`). @@ -536,19 +536,19 @@ In addition to the [settings that are valid for all realms](#ref-realm-settings) `load_balance.type` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The behavior to use when there are multiple LDAP URLs defined. For supported values see [load balancing and failover types](#load-balancing). Defaults to `failover`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The behavior to use when there are multiple LDAP URLs defined. For supported values see [load balancing and failover types](#load-balancing). Defaults to `failover`. `load_balance.cache_ttl` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) When using `dns_failover` or `dns_round_robin` as the load balancing type, this setting controls the amount of time to cache DNS lookups. Defaults to `1h`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) When using `dns_failover` or `dns_round_robin` as the load balancing type, this setting controls the amount of time to cache DNS lookups. Defaults to `1h`. `domain_name` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The domain name of Active Directory. If the `url` and the `user_search.base_dn` settings are not specified, the cluster can derive those values from this setting. Required. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The domain name of Active Directory. If the `url` and the `user_search.base_dn` settings are not specified, the cluster can derive those values from this setting. Required. `bind_dn` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The DN of the user that is used to bind to Active Directory and perform searches. Defaults to Empty. Due to its potential security impact, `bind_dn` is not exposed via the [nodes info API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-nodes-info). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The DN of the user that is used to bind to Active Directory and perform searches. Defaults to Empty. Due to its potential security impact, `bind_dn` is not exposed via the [nodes info API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-nodes-info). `bind_password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the user that is used to bind to Active Directory. Defaults to Empty. Due to its potential security impact, `bind_password` is not exposed via the [nodes info API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-nodes-info). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the user that is used to bind to Active Directory. Defaults to Empty. Due to its potential security impact, `bind_password` is not exposed via the [nodes info API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-nodes-info). :::{admonition} Deprecated in 6.3 Use `secure_bind_password` instead. @@ -558,71 +558,71 @@ In addition to the [settings that are valid for all realms](#ref-realm-settings) : ([Secure](docs-content://deploy-manage/security/secure-settings.md), [Reloadable](docs-content://deploy-manage/security/secure-settings.md#reloadable-secure-settings)) The password for the user that is used to bind to Active Directory. Defaults to Empty. `unmapped_groups_as_roles` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) If set to `true`, the names of any unmapped Active Directory groups are used as role names and assigned to the user. A group is considered *unmapped* when it is not referenced in any role-mapping files. API-based role mappings are not considered. Defaults to `false`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) If set to `true`, the names of any unmapped Active Directory groups are used as role names and assigned to the user. A group is considered *unmapped* when it is not referenced in any role-mapping files. API-based role mappings are not considered. Defaults to `false`. `files.role_mapping` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The [location](docs-content://deploy-manage/security.md) for the YAML role mapping configuration file. Defaults to `ES_PATH_CONF/role_mapping.yml`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The [location](docs-content://deploy-manage/security.md) for the YAML role mapping configuration file. Defaults to `ES_PATH_CONF/role_mapping.yml`. `user_search.base_dn` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The context to search for a user. Defaults to the root of the Active Directory domain. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The context to search for a user. Defaults to the root of the Active Directory domain. `user_search.scope` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies whether the user search should be `sub_tree`, `one_level` or `base`. `one_level` only searches users directly contained within the `base_dn`. `sub_tree` searches all objects contained under `base_dn`. `base` specifies that the `base_dn` is a user object, and that it is the only user considered. Defaults to `sub_tree`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies whether the user search should be `sub_tree`, `one_level` or `base`. `one_level` only searches users directly contained within the `base_dn`. `sub_tree` searches all objects contained under `base_dn`. `base` specifies that the `base_dn` is a user object, and that it is the only user considered. Defaults to `sub_tree`. `user_search.filter` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies a filter to use to lookup a user given a username. The default filter looks up `user` objects with either `sAMAccountName` or `userPrincipalName`. If specified, this must be a valid LDAP user search filter. For example `(&(objectClass=user)(sAMAccountName={{0}}))`. For more information, see [Search Filter Syntax](https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies a filter to use to lookup a user given a username. The default filter looks up `user` objects with either `sAMAccountName` or `userPrincipalName`. If specified, this must be a valid LDAP user search filter. For example `(&(objectClass=user)(sAMAccountName={{0}}))`. For more information, see [Search Filter Syntax](https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx). `user_search.upn_filter` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies a filter to use to lookup a user given a user principal name. The default filter looks up `user` objects with a matching `userPrincipalName`. If specified, this must be a valid LDAP user search filter. For example, `(&(objectClass=user)(userPrincipalName={{1}}))`. `{{1}}` is the full user principal name provided by the user. For more information, see [Search Filter Syntax](https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies a filter to use to lookup a user given a user principal name. The default filter looks up `user` objects with a matching `userPrincipalName`. If specified, this must be a valid LDAP user search filter. For example, `(&(objectClass=user)(userPrincipalName={{1}}))`. `{{1}}` is the full user principal name provided by the user. For more information, see [Search Filter Syntax](https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx). `user_search.down_level_filter` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies a filter to use to lookup a user given a down level logon name (DOMAIN\user). The default filter looks up `user` objects with a matching `sAMAccountName` in the domain provided. If specified, this must be a valid LDAP user search filter. For example, `(&(objectClass=user)(sAMAccountName={{0}}))`. For more information, see [Search Filter Syntax](https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies a filter to use to lookup a user given a down level logon name (DOMAIN\user). The default filter looks up `user` objects with a matching `sAMAccountName` in the domain provided. If specified, this must be a valid LDAP user search filter. For example, `(&(objectClass=user)(sAMAccountName={{0}}))`. For more information, see [Search Filter Syntax](https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx). `user_search.pool.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Enables or disables connection pooling for user search. When disabled a new connection is created for every search. The default is `true` when `bind_dn` is provided. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Enables or disables connection pooling for user search. When disabled a new connection is created for every search. The default is `true` when `bind_dn` is provided. `user_search.pool.size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The maximum number of connections to the Active Directory server to allow in the connection pool. Defaults to `20`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The maximum number of connections to the Active Directory server to allow in the connection pool. Defaults to `20`. `user_search.pool.initial_size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The initial number of connections to create to the Active Directory server on startup. Defaults to `0`. If the LDAP server is down, values greater than 0 could cause startup failures. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The initial number of connections to create to the Active Directory server on startup. Defaults to `0`. If the LDAP server is down, values greater than 0 could cause startup failures. `user_search.pool.health_check.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Enables or disables a health check on Active Directory connections in the connection pool. Connections are checked in the background at the specified interval. Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Enables or disables a health check on Active Directory connections in the connection pool. Connections are checked in the background at the specified interval. Defaults to `true`. `user_search.pool.health_check.dn` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The distinguished name to be retrieved as part of the health check. Defaults to the value of `bind_dn` if that setting is present. Otherwise, it defaults to the value of the `user_search.base_dn` setting. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The distinguished name to be retrieved as part of the health check. Defaults to the value of `bind_dn` if that setting is present. Otherwise, it defaults to the value of the `user_search.base_dn` setting. `user_search.pool.health_check.interval` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The interval to perform background checks of connections in the pool. Defaults to `60s`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The interval to perform background checks of connections in the pool. Defaults to `60s`. `group_search.base_dn` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The context to search for groups in which the user has membership. Defaults to the root of the Active Directory domain. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The context to search for groups in which the user has membership. Defaults to the root of the Active Directory domain. `group_search.scope` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies whether the group search should be `sub_tree`, `one_level` or `base`. `one_level` searches for groups directly contained within the `base_dn`. `sub_tree` searches all objects contained under `base_dn`. `base` specifies that the `base_dn` is a group object, and that it is the only group considered. Defaults to `sub_tree`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies whether the group search should be `sub_tree`, `one_level` or `base`. `one_level` searches for groups directly contained within the `base_dn`. `sub_tree` searches all objects contained under `base_dn`. `base` specifies that the `base_dn` is a group object, and that it is the only group considered. Defaults to `sub_tree`. `metadata` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) A list of additional LDAP attributes that should be loaded from the LDAP server and stored in the authenticated user’s metadata field. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) A list of additional LDAP attributes that should be loaded from the LDAP server and stored in the authenticated user’s metadata field. `timeout.tcp_connect` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The TCP connect timeout period for establishing an LDAP connection. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to `5s` (5 seconds ). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The TCP connect timeout period for establishing an LDAP connection. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to `5s` (5 seconds ). `timeout.tcp_read` : :::{admonition} Deprecated in 7.7 This is equivalent to and is deprecated in favor of `timeout.response` and they cannot be used simultaneously. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The TCP read timeout period after establishing an LDAP connection. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to the value of `timeout.ldap_search`. + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The TCP read timeout period after establishing an LDAP connection. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to the value of `timeout.ldap_search`. `timeout.response` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The time interval to wait for the response from the AD server. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to the value of `timeout.ldap_search`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The time interval to wait for the response from the AD server. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to the value of `timeout.ldap_search`. `timeout.ldap_search` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The timeout period for an LDAP search. The value is specified in the request and is enforced by the receiving LDAP Server. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to `5s` (5 seconds ). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The timeout period for an LDAP search. The value is specified in the request and is enforced by the receiving LDAP Server. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to `5s` (5 seconds ). `ssl.certificate` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key. This setting can be used only if `ssl.key` is set. @@ -630,7 +630,7 @@ In addition to the [settings that are valid for all realms](#ref-realm-settings) `ssl.certificate_authorities` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) List of paths to PEM encoded certificate files that should be trusted. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) List of paths to PEM encoded certificate files that should be trusted. This setting and `ssl.truststore.path` cannot be used at the same time. @@ -638,7 +638,7 @@ In addition to the [settings that are valid for all realms](#ref-realm-settings) `ssl.key` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Path to a PEM encoded file containing the private key. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Path to a PEM encoded file containing the private key. If HTTP client authentication is required, it uses this file. You cannot use this setting and `ssl.keystore.path` at the same time. @@ -646,7 +646,7 @@ In addition to the [settings that are valid for all realms](#ref-realm-settings) `ssl.key_passphrase` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.secure_key_passphrase` instead. @@ -659,7 +659,7 @@ In addition to the [settings that are valid for all realms](#ref-realm-settings) : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional. `ssl.keystore.key_password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.keystore.secure_key_password` instead. @@ -672,7 +672,7 @@ In addition to the [settings that are valid for all realms](#ref-realm-settings) : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password for the key in the keystore. The default is the keystore password. `ssl.keystore.password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the keystore. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the keystore. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.keystore.secure_password` instead. @@ -682,7 +682,7 @@ In addition to the [settings that are valid for all realms](#ref-realm-settings) : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password for the keystore. `ssl.keystore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.key` at the same time. @@ -690,10 +690,10 @@ In addition to the [settings that are valid for all realms](#ref-realm-settings) `ssl.keystore.type` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The format of the keystore file. It must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The format of the keystore file. It must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. `ssl.truststore.password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the truststore. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the truststore. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.truststore.secure_password` instead. @@ -706,7 +706,7 @@ In addition to the [settings that are valid for all realms](#ref-realm-settings) : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) Password for the truststore. `ssl.truststore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.certificate_authorities` at the same time. @@ -714,10 +714,10 @@ In addition to the [settings that are valid for all realms](#ref-realm-settings) `ssl.truststore.type` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The format of the truststore file. It must be either `jks` or `PKCS12`. If the file name ends in ".p12", ".pfx" or "pkcs12", the default is `PKCS12`. Otherwise, it defaults to `jks`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The format of the truststore file. It must be either `jks` or `PKCS12`. If the file name ends in ".p12", ".pfx" or "pkcs12", the default is `PKCS12`. Otherwise, it defaults to `jks`. `ssl.verification_mode` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Indicates the type of verification when using `ldaps` to protect against man in the middle attacks and certificate forgery. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Indicates the type of verification when using `ldaps` to protect against man in the middle attacks and certificate forgery. Defaults to `full`. @@ -731,7 +731,7 @@ In addition to the [settings that are valid for all realms](#ref-realm-settings) :::: `ssl.supported_protocols` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Supported protocols with versions. Valid protocols: `SSLv2Hello`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM’s SSL provider supports TLSv1.3, the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is `TLSv1.2,TLSv1.1`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Supported protocols with versions. Valid protocols: `SSLv2Hello`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM’s SSL provider supports TLSv1.3, the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is `TLSv1.2,TLSv1.1`. {{es}} relies on your JDK’s implementation of SSL and TLS. View [Supported SSL/TLS versions by JDK version](docs-content://deploy-manage/security/supported-ssltls-versions-by-jdk-version.md) for more information. @@ -741,25 +741,25 @@ In addition to the [settings that are valid for all realms](#ref-realm-settings) `ssl.cipher_suites` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the cipher suites that should be supported when communicating with the Active Directory server. Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the cipher suites that should be supported when communicating with the Active Directory server. Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. For more information, see Oracle’s [Java Cryptography Architecture documentation](https://docs.oracle.com/en/java/javase/11/security/oracle-providers.md#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2). `cache.ttl` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the time-to-live for cached user entries. A user and a hash of its credentials are cached for this configured period of time. Use the standard Elasticsearch [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)). Defaults to `20m`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the time-to-live for cached user entries. A user and a hash of its credentials are cached for this configured period of time. Use the standard Elasticsearch [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)). Defaults to `20m`. `cache.max_users` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the maximum number of user entries that the cache can contain. Defaults to `100000`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the maximum number of user entries that the cache can contain. Defaults to `100000`. `cache.hash_algo` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), Expert) Specifies the hashing algorithm that is used for the in-memory cached user credentials. See [Table 1, Cache hash algorithms](#cache-hash-algo). Defaults to `ssha256`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting), Expert) Specifies the hashing algorithm that is used for the in-memory cached user credentials. See [Table 1, Cache hash algorithms](#cache-hash-algo). Defaults to `ssha256`. `authentication.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) If set to `false`, disables authentication support in this realm, so that it only supports user lookups. (See the [run as](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md) and [authorization realms](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms) features). Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) If set to `false`, disables authentication support in this realm, so that it only supports user lookups. (See the [run as](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md) and [authorization realms](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms) features). Defaults to `true`. `follow_referrals` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) If set to `true`, {{es}} follows referrals returned by the LDAP server. Referrals are URLs returned by the server that are to be used to continue the LDAP operation (such as `search`). Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) If set to `true`, {{es}} follows referrals returned by the LDAP server. Referrals are URLs returned by the server that are to be used to continue the LDAP operation (such as `search`). Defaults to `true`. #### PKI realm settings [ref-pki-settings] @@ -767,16 +767,16 @@ In addition to the [settings that are valid for all realms](#ref-realm-settings) In addition to the [settings that are valid for all realms](#ref-realm-settings), you can specify the following settings: `username_pattern` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The regular expression pattern used to extract the username from the certificate DN. The username is used for auditing and logging. The username can also be used with the [role mapping API](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md) and [authorization delegation](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/authorization-delegation.md). The first match group is the used as the username. Defaults to `CN=(.*?)(?:,|$)`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The regular expression pattern used to extract the username from the certificate DN. The username is used for auditing and logging. The username can also be used with the [role mapping API](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md) and [authorization delegation](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/authorization-delegation.md). The first match group is the used as the username. Defaults to `CN=(.*?)(?:,|$)`. `certificate_authorities` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) List of paths to the PEM certificate files that should be used to authenticate a user’s certificate as trusted. Defaults to the trusted certificates configured for SSL. This setting cannot be used with `truststore.path`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) List of paths to the PEM certificate files that should be used to authenticate a user’s certificate as trusted. Defaults to the trusted certificates configured for SSL. This setting cannot be used with `truststore.path`. `truststore.algorithm` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Algorithm for the truststore. Defaults to `SunX509`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Algorithm for the truststore. Defaults to `SunX509`. `truststore.password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the truststore. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the truststore. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.truststore.secure_password` instead. @@ -791,22 +791,22 @@ If `truststore.path` is set, this setting is required. : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) Password for the truststore. `truststore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path of a truststore to use. Defaults to the trusted certificates configured for SSL. This setting cannot be used with `certificate_authorities`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path of a truststore to use. Defaults to the trusted certificates configured for SSL. This setting cannot be used with `certificate_authorities`. `files.role_mapping` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the [location](docs-content://deploy-manage/security.md) of the [YAML role mapping configuration file](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md). Defaults to `ES_PATH_CONF/role_mapping.yml`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the [location](docs-content://deploy-manage/security.md) of the [YAML role mapping configuration file](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md). Defaults to `ES_PATH_CONF/role_mapping.yml`. `authorization_realms` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The names of the realms that should be consulted for delegated authorization. If this setting is used, then the PKI realm does not perform role mapping and instead loads the user from the listed realms. See [Delegating authorization to another realm](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The names of the realms that should be consulted for delegated authorization. If this setting is used, then the PKI realm does not perform role mapping and instead loads the user from the listed realms. See [Delegating authorization to another realm](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms). `cache.ttl` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the time-to-live for cached user entries. A user and a hash of its credentials are cached for this period of time. Use the standard {{es}} [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)). Defaults to `20m`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the time-to-live for cached user entries. A user and a hash of its credentials are cached for this period of time. Use the standard {{es}} [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)). Defaults to `20m`. `cache.max_users` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the maximum number of user entries that the cache can contain. Defaults to `100000`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the maximum number of user entries that the cache can contain. Defaults to `100000`. `delegation.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Generally, in order for the clients to be authenticated by the PKI realm they must connect directly to {{es}}. That is, they must not pass through proxies which terminate the TLS connection. In order to allow for a **trusted** and **smart** proxy, such as Kibana, to sit before {{es}} and terminate TLS connections, but still allow clients to be authenticated on {{es}} by this realm, you need to toggle this to `true`. Defaults to `false`. If delegation is enabled, then either `truststore.path` or `certificate_authorities` setting must be defined. For more details, see [Configuring authentication delegation for PKI realms](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/pki.md#pki-realm-for-proxied-clients). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Generally, in order for the clients to be authenticated by the PKI realm they must connect directly to {{es}}. That is, they must not pass through proxies which terminate the TLS connection. In order to allow for a **trusted** and **smart** proxy, such as Kibana, to sit before {{es}} and terminate TLS connections, but still allow clients to be authenticated on {{es}} by this realm, you need to toggle this to `true`. Defaults to `false`. If delegation is enabled, then either `truststore.path` or `certificate_authorities` setting must be defined. For more details, see [Configuring authentication delegation for PKI realms](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/pki.md#pki-realm-for-proxied-clients). #### SAML realm settings [ref-saml-settings] @@ -814,10 +814,10 @@ If `truststore.path` is set, this setting is required. In addition to the [settings that are valid for all realms](#ref-realm-settings), you can specify the following settings. `idp.entity_id` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The Entity ID of the SAML Identity Provider. An Entity ID is a URI with a maximum length of 1024 characters. It can be a URL ([https://idp.example.com/](https://idp.example.com/)) or a URN (`urn:example.com:idp`) and can be found in the configuration or the SAML metadata of the Identity Provider. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The Entity ID of the SAML Identity Provider. An Entity ID is a URI with a maximum length of 1024 characters. It can be a URL ([https://idp.example.com/](https://idp.example.com/)) or a URN (`urn:example.com:idp`) and can be found in the configuration or the SAML metadata of the Identity Provider. `idp.metadata.path` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path *(recommended)* or URL to a SAML 2.0 metadata file describing the capabilities and configuration of the Identity Provider. If a path is provided, then it is resolved relative to the {{es}} config directory. If a URL is provided, then it must be either a `file` URL or a `https` URL. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path *(recommended)* or URL to a SAML 2.0 metadata file describing the capabilities and configuration of the Identity Provider. If a path is provided, then it is resolved relative to the {{es}} config directory. If a URL is provided, then it must be either a `file` URL or a `https` URL. {{es}} automatically polls this metadata resource and reloads the IdP configuration when changes are detected. File based resources are polled at a frequency determined by the global {{es}} `resource.reload.interval.high` setting, which defaults to 5 seconds. HTTPS resources are polled at a frequency determined by the realm’s `idp.metadata.http.refresh` and `idp.metadata.http.minimum_refresh` settings. @@ -825,85 +825,85 @@ In addition to the [settings that are valid for all realms](#ref-realm-settings) `idp.metadata.http.fail_on_error` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) If set to `true`, the realm will fail on startup (and prevent the node from starting) if it attempts to load metadata over HTTPS and that metadata is not available. If set to `false` (the default), the node will start but the affected SAML realm will not support user authentication until the metadata can be successfully loaded. This setting is ignored if metadata is loaded from a file. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) If set to `true`, the realm will fail on startup (and prevent the node from starting) if it attempts to load metadata over HTTPS and that metadata is not available. If set to `false` (the default), the node will start but the affected SAML realm will not support user authentication until the metadata can be successfully loaded. This setting is ignored if metadata is loaded from a file. `idp.metadata.http.refresh` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Controls the frequency with which `https` metadata is checked for changes. Defaults to `1h` (1 hour). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Controls the frequency with which `https` metadata is checked for changes. Defaults to `1h` (1 hour). Under some circumstances {{es}} may determine that the metadata needs to be checked more frequently. This may occur if previous attempts to load the metadata encountered an error, or if the metadata indicates that it is due to expire in less than the configured refresh interval. In these cases {{es}} will poll more often, but never more frequently than `idp.metadata.http.minimum_refresh`. If there is an attempt to authenticate against a realm that has not yet loaded metadata successfully, that realm may attempt to load metadata outside of the configured polling frequency. `idp.metadata.http.minimum_refresh` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Controls the minimum frequency with which `https` metadata is checked for changes. In regular operation {{es}} will use the value of `idp.metadata.http.refresh` as the polling interval. However, under some circumstances {{es}} may determine that it needs to poll more frequently. In these cases, the `minimum_refresh` will set the minimum frequency at which the metdata will be checked. Defaults to `5m` (5 minutes) and must not be set to a value greater than `idp.metadata.http.refresh` +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Controls the minimum frequency with which `https` metadata is checked for changes. In regular operation {{es}} will use the value of `idp.metadata.http.refresh` as the polling interval. However, under some circumstances {{es}} may determine that it needs to poll more frequently. In these cases, the `minimum_refresh` will set the minimum frequency at which the metdata will be checked. Defaults to `5m` (5 minutes) and must not be set to a value greater than `idp.metadata.http.refresh` `idp.use_single_logout` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Indicates whether to utilise the Identity Provider’s Single Logout service (if one exists in the IdP metadata file). Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Indicates whether to utilise the Identity Provider’s Single Logout service (if one exists in the IdP metadata file). Defaults to `true`. `sp.entity_id` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The Entity ID to use for this SAML Service Provider. This should be entered as a URI. We recommend that you use the base URL of your Kibana instance. For example, `https://kibana.example.com/`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The Entity ID to use for this SAML Service Provider. This should be entered as a URI. We recommend that you use the base URL of your Kibana instance. For example, `https://kibana.example.com/`. `sp.acs` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The URL of the Assertion Consumer Service within {{kib}}. Typically this is the "api/security/saml/callback" endpoint of your Kibana server. For example, `https://kibana.example.com/api/security/saml/callback`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The URL of the Assertion Consumer Service within {{kib}}. Typically this is the "api/security/saml/callback" endpoint of your Kibana server. For example, `https://kibana.example.com/api/security/saml/callback`. `sp.logout` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The URL of the Single Logout service within {{kib}}. Typically this is the "logout" endpoint of your Kibana server. For example, `https://kibana.example.com/logout`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The URL of the Single Logout service within {{kib}}. Typically this is the "logout" endpoint of your Kibana server. For example, `https://kibana.example.com/logout`. `attributes.principal` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The Name of the SAML attribute that contains the user’s principal (username). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The Name of the SAML attribute that contains the user’s principal (username). `attributes.groups` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The Name of the SAML attribute that contains the user’s groups. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The Name of the SAML attribute that contains the user’s groups. `attributes.name` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The Name of the SAML attribute that contains the user’s full name. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The Name of the SAML attribute that contains the user’s full name. `attributes.mail` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The Name of the SAML attribute that contains the user’s email address. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The Name of the SAML attribute that contains the user’s email address. `attributes.dn` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The Name of the SAML attribute that contains the user’s X.50 *Distinguished Name*. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The Name of the SAML attribute that contains the user’s X.50 *Distinguished Name*. `attribute_patterns.principal` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) A Java regular expression that is matched against the SAML attribute specified by `attributes.principal` before it is applied to the user’s *principal* property. The attribute value must match the pattern and the value of the first *capturing group* is used as the principal. For example, `^([^@]+)@example\\.com$` matches email addresses from the "example.com" domain and uses the local-part as the principal. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) A Java regular expression that is matched against the SAML attribute specified by `attributes.principal` before it is applied to the user’s *principal* property. The attribute value must match the pattern and the value of the first *capturing group* is used as the principal. For example, `^([^@]+)@example\\.com$` matches email addresses from the "example.com" domain and uses the local-part as the principal. `attribute_patterns.groups` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) As per `attribute_patterns.principal`, but for the *group* property. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) As per `attribute_patterns.principal`, but for the *group* property. `attribute_patterns.name` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) As per `attribute_patterns.principal`, but for the *name* property. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) As per `attribute_patterns.principal`, but for the *name* property. `attribute_patterns.mail` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) As per `attribute_patterns.principal`, but for the *mail* property. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) As per `attribute_patterns.principal`, but for the *mail* property. `attribute_patterns.dn` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) As per `attribute_patterns.principal`, but for the *dn* property. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) As per `attribute_patterns.principal`, but for the *dn* property. `attribute_delimiters.groups` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) A plain string that is used as a delimiter to split a single-valued SAML attribute specified by `attributes.groups` before it is applied to the user’s *groups* property. For example, splitting the SAML attribute value `engineering,elasticsearch-admins,employees` on a delimiter value of `,` will result in `engineering`, `elasticsearch-admins`, and `employees` as the list of groups for the user. The delimiter will always be split on, regardless of escaping in the input string. This setting does not support multi-valued SAML attributes. It cannot be used together with the `attribute_patterns` setting. You can only configure this setting for the groups attribute. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) A plain string that is used as a delimiter to split a single-valued SAML attribute specified by `attributes.groups` before it is applied to the user’s *groups* property. For example, splitting the SAML attribute value `engineering,elasticsearch-admins,employees` on a delimiter value of `,` will result in `engineering`, `elasticsearch-admins`, and `employees` as the list of groups for the user. The delimiter will always be split on, regardless of escaping in the input string. This setting does not support multi-valued SAML attributes. It cannot be used together with the `attribute_patterns` setting. You can only configure this setting for the groups attribute. `nameid_format` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The NameID format that should be requested when asking the IdP to authenticate the current user. The default is to not include the `nameid_format` attribute. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The NameID format that should be requested when asking the IdP to authenticate the current user. The default is to not include the `nameid_format` attribute. `nameid.allow_create` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The value of the `AllowCreate` attribute of the `NameIdPolicy` element in an authentication request. The default value is false. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The value of the `AllowCreate` attribute of the `NameIdPolicy` element in an authentication request. The default value is false. `nameid.sp_qualifier` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The value of the `SPNameQualifier` attribute of the `NameIdPolicy` element in an authentication request. The default is to not include the `SPNameQualifier` attribute. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The value of the `SPNameQualifier` attribute of the `NameIdPolicy` element in an authentication request. The default is to not include the `SPNameQualifier` attribute. `force_authn` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies whether to set the `ForceAuthn` attribute when requesting that the IdP authenticate the current user. If set to `true`, the IdP is required to verify the user’s identity, irrespective of any existing sessions they might have. Defaults to `false`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies whether to set the `ForceAuthn` attribute when requesting that the IdP authenticate the current user. If set to `true`, the IdP is required to verify the user’s identity, irrespective of any existing sessions they might have. Defaults to `false`. `populate_user_metadata` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies whether to populate the {{es}} user’s metadata with the values that are provided by the SAML attributes. Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies whether to populate the {{es}} user’s metadata with the values that are provided by the SAML attributes. Defaults to `true`. `authorization_realms` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The names of the realms that should be consulted for delegated authorization. If this setting is used, then the SAML realm does not perform role mapping and instead loads the user from the listed realms. See [Delegating authorization to another realm](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The names of the realms that should be consulted for delegated authorization. If this setting is used, then the SAML realm does not perform role mapping and instead loads the user from the listed realms. See [Delegating authorization to another realm](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms). `allowed_clock_skew` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The maximum amount of skew that can be tolerated between the IdP’s clock and the {{es}} node’s clock. Defaults to `3m` (3 minutes). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The maximum amount of skew that can be tolerated between the IdP’s clock and the {{es}} node’s clock. Defaults to `3m` (3 minutes). `req_authn_context_class_ref` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) A comma separated list of Authentication Context Class Reference values to be included in the Requested Authentication Context when requesting the IdP to authenticate the current user. The Authentication Context of the corresponding authentication response should contain at least one of the requested values. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) A comma separated list of Authentication Context Class Reference values to be included in the Requested Authentication Context when requesting the IdP to authenticate the current user. The Authentication Context of the corresponding authentication response should contain at least one of the requested values. For more information, see [Requesting specific authentication methods](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/saml.md#req-authn-context). @@ -914,25 +914,25 @@ In addition to the [settings that are valid for all realms](#ref-realm-settings) If a signing key is configured (that is, either `signing.key` or `signing.keystore.path` is set), then {{es}} signs outgoing SAML messages. Signing can be configured using the following settings: `signing.saml_messages` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) A list of SAML message types that should be signed or `*` to sign all messages. Each element in the list should be the local name of a SAML XML Element. Supported element types are `AuthnRequest`, `LogoutRequest` and `LogoutResponse`. Only valid if `signing.key` or `signing.keystore.path` is also specified. Defaults to `*`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) A list of SAML message types that should be signed or `*` to sign all messages. Each element in the list should be the local name of a SAML XML Element. Supported element types are `AuthnRequest`, `LogoutRequest` and `LogoutResponse`. Only valid if `signing.key` or `signing.keystore.path` is also specified. Defaults to `*`. `signing.key` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the path to the PEM encoded private key to use for SAML message signing. `signing.key` and `signing.keystore.path` cannot be used at the same time. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the path to the PEM encoded private key to use for SAML message signing. `signing.key` and `signing.keystore.path` cannot be used at the same time. `signing.secure_key_passphrase` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) Specifies the passphrase to decrypt the PEM encoded private key (`signing.key`) if it is encrypted. `signing.certificate` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the path to the PEM encoded certificate (or certificate chain) that corresponds to the `signing.key`. This certificate must also be included in the Service Provider metadata or manually configured within the IdP to allow for signature validation. This setting can only be used if `signing.key` is set. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the path to the PEM encoded certificate (or certificate chain) that corresponds to the `signing.key`. This certificate must also be included in the Service Provider metadata or manually configured within the IdP to allow for signature validation. This setting can only be used if `signing.key` is set. `signing.keystore.path` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path to the keystore that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `signing.key` at the same time. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path to the keystore that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `signing.key` at the same time. `signing.keystore.type` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The type of the keystore in `signing.keystore.path`. Must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or "pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The type of the keystore in `signing.keystore.path`. Must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or "pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. `signing.keystore.alias` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the alias of the key within the keystore that should be used for SAML message signing. If the keystore contains more than one private key, this setting must be specified. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the alias of the key within the keystore that should be used for SAML message signing. If the keystore contains more than one private key, this setting must be specified. `signing.keystore.secure_password` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password to the keystore in `signing.keystore.path`. @@ -946,22 +946,22 @@ If a signing key is configured (that is, either `signing.key` or `signing.keysto If an encryption key is configured (that is, either `encryption.key` or `encryption.keystore.path` is set), then {{es}} publishes an encryption certificate when generating metadata and attempts to decrypt incoming SAML content. Encryption can be configured using the following settings: `encryption.key` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the path to the PEM encoded private key to use for SAML message decryption. `encryption.key` and `encryption.keystore.path` cannot be used at the same time. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the path to the PEM encoded private key to use for SAML message decryption. `encryption.key` and `encryption.keystore.path` cannot be used at the same time. `encryption.secure_key_passphrase` : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) Specifies the passphrase to decrypt the PEM encoded private key (`encryption.key`) if it is encrypted. `encryption.certificate` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the path to the PEM encoded certificate (or certificate chain) that is associated with the `encryption.key`. This certificate must also be included in the Service Provider metadata or manually configured within the IdP to enable message encryption. This setting can be used only if `encryption.key` is set. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the path to the PEM encoded certificate (or certificate chain) that is associated with the `encryption.key`. This certificate must also be included in the Service Provider metadata or manually configured within the IdP to enable message encryption. This setting can be used only if `encryption.key` is set. `encryption.keystore.path` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path to the keystore that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `encryption.key` at the same time. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path to the keystore that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `encryption.key` at the same time. `encryption.keystore.type` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The type of the keystore (`encryption.keystore.path`). Must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or "pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The type of the keystore (`encryption.keystore.path`). Must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or "pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. `encryption.keystore.alias` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the alias of the key within the keystore (`encryption.keystore.path`) that should be used for SAML message decryption. If not specified, all compatible key pairs from the keystore are considered as candidate keys for decryption. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the alias of the key within the keystore (`encryption.keystore.path`) that should be used for SAML message decryption. If not specified, all compatible key pairs from the keystore are considered as candidate keys for decryption. `encryption.keystore.secure_password` : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password to the keystore (`encryption.keystore.path`). @@ -980,13 +980,13 @@ These settings are not used for any purpose other than loading metadata over htt `ssl.key` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Path to a PEM encoded file containing the private key. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Path to a PEM encoded file containing the private key. If HTTP client authentication is required, it uses this file. You cannot use this setting and `ssl.keystore.path` at the same time. `ssl.key_passphrase` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.secure_key_passphrase` instead. @@ -1002,28 +1002,28 @@ These settings are not used for any purpose other than loading metadata over htt `ssl.certificate` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key. This setting can be used only if `ssl.key` is set. `ssl.certificate_authorities` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) List of paths to PEM encoded certificate files that should be trusted. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) List of paths to PEM encoded certificate files that should be trusted. This setting and `ssl.truststore.path` cannot be used at the same time. `ssl.keystore.path` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.key` at the same time. `ssl.keystore.type` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The format of the keystore file. It must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The format of the keystore file. It must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. `ssl.keystore.password` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the keystore. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the keystore. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.keystore.secure_password` instead. @@ -1036,7 +1036,7 @@ These settings are not used for any purpose other than loading metadata over htt `ssl.keystore.key_password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.keystore.secure_key_password` instead. @@ -1053,16 +1053,16 @@ These settings are not used for any purpose other than loading metadata over htt You cannot use this setting and `ssl.keystore.key_password` at the same time. `ssl.truststore.path` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.certificate_authorities` at the same time. `ssl.truststore.type` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The format of the truststore file. It must be either `jks` or `PKCS12`. If the file name ends in ".p12", ".pfx" or "pkcs12", the default is `PKCS12`. Otherwise, it defaults to `jks`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The format of the truststore file. It must be either `jks` or `PKCS12`. If the file name ends in ".p12", ".pfx" or "pkcs12", the default is `PKCS12`. Otherwise, it defaults to `jks`. `ssl.truststore.password` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the truststore. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the truststore. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.truststore.secure_password` instead. @@ -1078,7 +1078,7 @@ You cannot use this setting and `ssl.keystore.key_password` at the same time. `ssl.verification_mode` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Controls the verification of certificates. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Controls the verification of certificates. Defaults to `full`. @@ -1092,7 +1092,7 @@ You cannot use this setting and `ssl.keystore.key_password` at the same time. :::: `ssl.supported_protocols` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Supported protocols with versions. Valid protocols: `SSLv2Hello`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM’s SSL provider supports TLSv1.3, the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is `TLSv1.2,TLSv1.1`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Supported protocols with versions. Valid protocols: `SSLv2Hello`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM’s SSL provider supports TLSv1.3, the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is `TLSv1.2,TLSv1.1`. {{es}} relies on your JDK’s implementation of SSL and TLS. View [Supported SSL/TLS versions by JDK version](docs-content://deploy-manage/security/supported-ssltls-versions-by-jdk-version.md) for more information. @@ -1102,7 +1102,7 @@ You cannot use this setting and `ssl.keystore.key_password` at the same time. `ssl.cipher_suites` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. For more information, see Oracle’s [Java Cryptography Architecture documentation](https://docs.oracle.com/en/java/javase/11/security/oracle-providers.md#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2). @@ -1113,22 +1113,22 @@ You cannot use this setting and `ssl.keystore.key_password` at the same time. In addition to the [settings that are valid for all realms](#ref-realm-settings), you can specify the following settings: `keytab.path` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the path to the Kerberos keytab file that contains the service principal used by this {{es}} node. This must be a location within the {{es}} configuration directory and the file must have read permissions. Required. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the path to the Kerberos keytab file that contains the service principal used by this {{es}} node. This must be a location within the {{es}} configuration directory and the file must have read permissions. Required. `remove_realm_name` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Set to `true` to remove the realm part of principal names. Principal names in Kerberos have the form `user/instance@REALM`. If this option is `true`, the realm part (`@REALM`) will not be included in the username. Defaults to `false`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Set to `true` to remove the realm part of principal names. Principal names in Kerberos have the form `user/instance@REALM`. If this option is `true`, the realm part (`@REALM`) will not be included in the username. Defaults to `false`. `krb.debug` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Set to `true` to enable debug logs for the Java login module that provides support for Kerberos authentication. Defaults to `false`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Set to `true` to enable debug logs for the Java login module that provides support for Kerberos authentication. Defaults to `false`. `cache.ttl` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The time-to-live for cached user entries. A user is cached for this period of time. Specify the time period using the standard {{es}} [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units). Defaults to `20m`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The time-to-live for cached user entries. A user is cached for this period of time. Specify the time period using the standard {{es}} [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units). Defaults to `20m`. `cache.max_users` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The maximum number of user entries that can live in the cache at any given time. Defaults to 100,000. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The maximum number of user entries that can live in the cache at any given time. Defaults to 100,000. `authorization_realms` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The names of the realms that should be consulted for delegated authorization. If this setting is used, then the Kerberos realm does not perform role mapping and instead loads the user from the listed realms. See [Delegating authorization to another realm](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The names of the realms that should be consulted for delegated authorization. If this setting is used, then the Kerberos realm does not perform role mapping and instead loads the user from the listed realms. See [Delegating authorization to another realm](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms). #### OpenID Connect realm settings [ref-oidc-settings] @@ -1136,122 +1136,122 @@ In addition to the [settings that are valid for all realms](#ref-realm-settings) In addition to the [settings that are valid for all realms](#ref-realm-settings), you can specify the following settings. `op.issuer` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) A verifiable Identifier for your OpenID Connect Provider. An Issuer Identifier is usually a case sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components. The value for this setting should be provided by your OpenID Connect Provider. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) A verifiable Identifier for your OpenID Connect Provider. An Issuer Identifier is usually a case sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components. The value for this setting should be provided by your OpenID Connect Provider. `op.authorization_endpoint` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The URL for the Authorization Endpoint at the OpenID Connect Provider. The value for this setting should be provided by your OpenID Connect Provider. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The URL for the Authorization Endpoint at the OpenID Connect Provider. The value for this setting should be provided by your OpenID Connect Provider. `op.token_endpoint` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The URL for the Token Endpoint at the OpenID Connect Provider. The value for this setting should be provided by your OpenID Connect Provider. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The URL for the Token Endpoint at the OpenID Connect Provider. The value for this setting should be provided by your OpenID Connect Provider. `op.userinfo_endpoint` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The URL for the User Info Endpoint at the OpenID Connect Provider. The value for this setting should be provided by your OpenID Connect Provider. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The URL for the User Info Endpoint at the OpenID Connect Provider. The value for this setting should be provided by your OpenID Connect Provider. `op.endsession_endpoint` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The URL for the End Session Endpoint at the OpenID Connect Provider. The value for this setting should be provided by your OpenID Connect Provider. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The URL for the End Session Endpoint at the OpenID Connect Provider. The value for this setting should be provided by your OpenID Connect Provider. `op.jwkset_path` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The file name or URL to a JSON Web Key Set (JWKS) with the public key material used to verify tokens and claims responses signed by the OpenID Connect Provider. A value is considered a file name if it does not begin with `https` or `http`. The file name is resolved relative to the {{es}} configuration directory. Changes to the file are polled at a frequency determined by the global {{es}} `resource.reload.interval.high` setting, which defaults to 5 seconds. + If a URL is provided, then it must begin with `https://` or `http://`. {{es}} automatically caches the retrieved JWK and will attempt to refresh the JWK upon signature verification failure, as this might indicate that the OpenID Connect Provider has rotated the signing keys. `authorization_realms` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The names of the realms that should be consulted for delegated authorization. If this setting is used, then the OpenID Connect realm does not perform role mapping and instead loads the user from the listed realms. See [Delegating authorization to another realm](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The names of the realms that should be consulted for delegated authorization. If this setting is used, then the OpenID Connect realm does not perform role mapping and instead loads the user from the listed realms. See [Delegating authorization to another realm](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms). `rp.client_id` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The OAuth 2.0 Client Identifier that was assigned to {{es}} during registration at the OpenID Connect Provider. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The OAuth 2.0 Client Identifier that was assigned to {{es}} during registration at the OpenID Connect Provider. `rp.client_secret` : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The OAuth 2.0 Client Secret that was assigned to {{es}} during registration at the OpenID Connect Provider. `rp.client_auth_method` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The client authentication method used by {{es}} to authenticate to the OpenID Connect Provider. Can be `client_secret_basic`, `client_secret_post`, or `client_secret_jwt`. Defaults to `client_secret_basic`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The client authentication method used by {{es}} to authenticate to the OpenID Connect Provider. Can be `client_secret_basic`, `client_secret_post`, or `client_secret_jwt`. Defaults to `client_secret_basic`. `rp.client_auth_jwt_signature_algorithm` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The signature algorithm that {{es}} uses to sign the JWT with which it authenticates as a client to the OpenID Connect Provider when `client_secret_jwt` is selected for `rp.client_auth_method`. Can be either `HS256`, `HS384`, or `HS512`. Defaults to `HS384`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The signature algorithm that {{es}} uses to sign the JWT with which it authenticates as a client to the OpenID Connect Provider when `client_secret_jwt` is selected for `rp.client_auth_method`. Can be either `HS256`, `HS384`, or `HS512`. Defaults to `HS384`. `rp.redirect_uri` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The Redirect URI within {{kib}}. If you want to use the authorization code flow, this is the `api/security/oidc/callback` endpoint of your {{kib}} server. If you want to use the implicit flow, it is the `api/security/oidc/implicit` endpoint. For example, `https://kibana.example.com/api/security/oidc/callback`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The Redirect URI within {{kib}}. If you want to use the authorization code flow, this is the `api/security/oidc/callback` endpoint of your {{kib}} server. If you want to use the implicit flow, it is the `api/security/oidc/implicit` endpoint. For example, `https://kibana.example.com/api/security/oidc/callback`. `rp.response_type` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) OAuth 2.0 Response Type value that determines the authorization processing flow to be used. Can be `code` for authorization code grant flow, or one of `id_token`, `id_token token` for the implicit flow. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) OAuth 2.0 Response Type value that determines the authorization processing flow to be used. Can be `code` for authorization code grant flow, or one of `id_token`, `id_token token` for the implicit flow. `rp.signature_algorithm` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The signature algorithm that will be used by {{es}} in order to verify the signature of the id tokens it will receive from the OpenID Connect Provider. Allowed values are `HS256`, `HS384`, `HS512`, `ES256`, `ES384`, `ES512`, `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `PS512`. Defaults to `RS256`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The signature algorithm that will be used by {{es}} in order to verify the signature of the id tokens it will receive from the OpenID Connect Provider. Allowed values are `HS256`, `HS384`, `HS512`, `ES256`, `ES384`, `ES512`, `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `PS512`. Defaults to `RS256`. `rp.requested_scopes` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The scope values that will be requested by the OpenID Connect Provider as part of the Authentication Request. Optional, defaults to `openid` +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The scope values that will be requested by the OpenID Connect Provider as part of the Authentication Request. Optional, defaults to `openid` `rp.post_logout_redirect_uri` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The Redirect URI (usually within {{kib}}) that the OpenID Connect Provider should redirect the browser to after a successful Single Logout. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The Redirect URI (usually within {{kib}}) that the OpenID Connect Provider should redirect the browser to after a successful Single Logout. `claims.principal` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The name of the OpenID Connect claim that contains the user’s principal (username). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The name of the OpenID Connect claim that contains the user’s principal (username). `claims.groups` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The name of the OpenID Connect claim that contains the user’s groups. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The name of the OpenID Connect claim that contains the user’s groups. `claims.name` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The name of the OpenID Connect claim that contains the user’s full name. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The name of the OpenID Connect claim that contains the user’s full name. `claims.mail` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The name of the OpenID Connect claim that contains the user’s email address. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The name of the OpenID Connect claim that contains the user’s email address. `claims.dn` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The name of the OpenID Connect claim that contains the user’s X.509 *Distinguished Name*. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The name of the OpenID Connect claim that contains the user’s X.509 *Distinguished Name*. `claim_patterns.principal` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) A Java regular expression that is matched against the OpenID Connect claim specified by `claims.principal` before it is applied to the user’s *principal* property. The attribute value must match the pattern and the value of the first *capturing group* is used as the principal. For example, `^([^@]+)@example\\.com$` matches email addresses from the "example.com" domain and uses the local-part as the principal. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) A Java regular expression that is matched against the OpenID Connect claim specified by `claims.principal` before it is applied to the user’s *principal* property. The attribute value must match the pattern and the value of the first *capturing group* is used as the principal. For example, `^([^@]+)@example\\.com$` matches email addresses from the "example.com" domain and uses the local-part as the principal. `claim_patterns.groups` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) As per `claim_patterns.principal`, but for the *group* property. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) As per `claim_patterns.principal`, but for the *group* property. `claim_patterns.name` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) As per `claim_patterns.principal`, but for the *name* property. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) As per `claim_patterns.principal`, but for the *name* property. `claim_patterns.mail` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) As per `claim_patterns.principal`, but for the *mail* property. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) As per `claim_patterns.principal`, but for the *mail* property. `claim_patterns.dn` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) As per `claim_patterns.principal`, but for the *dn* property. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) As per `claim_patterns.principal`, but for the *dn* property. `allowed_clock_skew` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The maximum allowed clock skew to be taken into consideration when validating id tokens with regards to their creation and expiration times. Defaults to `60s`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The maximum allowed clock skew to be taken into consideration when validating id tokens with regards to their creation and expiration times. Defaults to `60s`. `populate_user_metadata` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies whether to populate the {{es}} user’s metadata with the values that are provided by the OpenID Connect claims. Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies whether to populate the {{es}} user’s metadata with the values that are provided by the OpenID Connect claims. Defaults to `true`. `http.proxy.host` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the address of the proxy server that will be used by the internal http client for all back-channel communication to the OpenID Connect Provider endpoints. This includes requests to the Token Endpoint, the Userinfo Endpoint and requests to fetch the JSON Web Key Set from the OP if `op.jwkset_path` is set as a URL. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the address of the proxy server that will be used by the internal http client for all back-channel communication to the OpenID Connect Provider endpoints. This includes requests to the Token Endpoint, the Userinfo Endpoint and requests to fetch the JSON Web Key Set from the OP if `op.jwkset_path` is set as a URL. `http.proxy.scheme` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the protocol to use to connect to the proxy server that will be used by the http client for all back-channel communication to the OpenID Connect Provider endpoints. Defaults to `http`. Allowed values are `http` or `https`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the protocol to use to connect to the proxy server that will be used by the http client for all back-channel communication to the OpenID Connect Provider endpoints. Defaults to `http`. Allowed values are `http` or `https`. `http.proxy.port` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the port of the proxy server that will be used by the http client for all backchannel communication to the OpenID Connect Provider endpoints. Defaults to `80`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the port of the proxy server that will be used by the http client for all backchannel communication to the OpenID Connect Provider endpoints. Defaults to `80`. `http.connect_timeout` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Controls the behavior of the http client used for back-channel communication to the OpenID Connect Provider endpoints. Specifies the timeout until a connection is established. A value of zero means the timeout is not used. Defaults to `5s`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Controls the behavior of the http client used for back-channel communication to the OpenID Connect Provider endpoints. Specifies the timeout until a connection is established. A value of zero means the timeout is not used. Defaults to `5s`. `http.connection_read_timeout` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Controls the behavior of the http client used for back-channel communication to the OpenID Connect Provider endpoints. Specifies the timeout used when requesting a connection from the connection manager. Defaults to `5s` +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Controls the behavior of the http client used for back-channel communication to the OpenID Connect Provider endpoints. Specifies the timeout used when requesting a connection from the connection manager. Defaults to `5s` `http.socket_timeout` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Controls the behavior of the http client used for back-channel communication to the OpenID Connect Provider endpoints. Specifies the socket timeout (SO_TIMEOUT) in milliseconds, which is the timeout for waiting for data or, put differently, a maximum period inactivity between two consecutive data packets). Defaults to `5s`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Controls the behavior of the http client used for back-channel communication to the OpenID Connect Provider endpoints. Specifies the socket timeout (SO_TIMEOUT) in milliseconds, which is the timeout for waiting for data or, put differently, a maximum period inactivity between two consecutive data packets). Defaults to `5s`. `http.max_connections` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Controls the behavior of the http client used for back-channel communication to the OpenID Connect Provider endpoints. Specifies the maximum number of connections allowed across all endpoints. Defaults to `200`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Controls the behavior of the http client used for back-channel communication to the OpenID Connect Provider endpoints. Specifies the maximum number of connections allowed across all endpoints. Defaults to `200`. `http.max_endpoint_connections` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Controls the behavior of the http client used for back-channel communication to the OpenID Connect Provider endpoints. Specifies the maximum number of connections allowed per endpoint. Defaults to `200`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Controls the behavior of the http client used for back-channel communication to the OpenID Connect Provider endpoints. Specifies the maximum number of connections allowed per endpoint. Defaults to `200`. `http.tcp.keep_alive` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Whether to enable TCP keepalives on HTTP connections used for back-channel communication to the OpenID Connect Provider endpoints. Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Whether to enable TCP keepalives on HTTP connections used for back-channel communication to the OpenID Connect Provider endpoints. Defaults to `true`. `http.connection_pool_ttl` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Controls the behavior of the http client used for back-channel communication to the OpenID Connect Provider endpoints. Specifies the time-to-live of connections in the connection pool (default to 3 minutes). A connection is closed if it is idle for more than the specified timeout. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Controls the behavior of the http client used for back-channel communication to the OpenID Connect Provider endpoints. Specifies the time-to-live of connections in the connection pool (default to 3 minutes). A connection is closed if it is idle for more than the specified timeout. The server can also set the `Keep-Alive` HTTP response header. The effective time-to-live value is the smaller value between this setting and the `Keep-Alive` response header. Configure this setting to `-1` to let the server dictate the value. If the header is not set by the server and the setting has value of `-1`, the time-to-live is infinite and connections never expire. @@ -1266,13 +1266,13 @@ These settings are *only* used for the back-channel communication between {{es}} `ssl.key` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Path to a PEM encoded file containing the private key. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Path to a PEM encoded file containing the private key. If HTTP client authentication is required, it uses this file. You cannot use this setting and `ssl.keystore.path` at the same time. `ssl.key_passphrase` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.secure_key_passphrase` instead. @@ -1288,28 +1288,28 @@ These settings are *only* used for the back-channel communication between {{es}} `ssl.certificate` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key. This setting can be used only if `ssl.key` is set. `ssl.certificate_authorities` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) List of paths to PEM encoded certificate files that should be trusted. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) List of paths to PEM encoded certificate files that should be trusted. This setting and `ssl.truststore.path` cannot be used at the same time. `ssl.keystore.path` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.key` at the same time. `ssl.keystore.type` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The format of the keystore file. It must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The format of the keystore file. It must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. `ssl.keystore.password` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the keystore. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the keystore. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.keystore.secure_password` instead. @@ -1322,7 +1322,7 @@ These settings are *only* used for the back-channel communication between {{es}} `ssl.keystore.key_password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.keystore.secure_key_password` instead. @@ -1340,16 +1340,16 @@ These settings are *only* used for the back-channel communication between {{es}} `ssl.truststore.path` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.certificate_authorities` at the same time. `ssl.truststore.type` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The format of the truststore file. It must be either `jks` or `PKCS12`. If the file name ends in ".p12", ".pfx" or "pkcs12", the default is `PKCS12`. Otherwise, it defaults to `jks`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The format of the truststore file. It must be either `jks` or `PKCS12`. If the file name ends in ".p12", ".pfx" or "pkcs12", the default is `PKCS12`. Otherwise, it defaults to `jks`. `ssl.truststore.password` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the truststore. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the truststore. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.truststore.secure_password` instead. @@ -1365,7 +1365,7 @@ These settings are *only* used for the back-channel communication between {{es}} `ssl.verification_mode` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Controls the verification of certificates. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Controls the verification of certificates. Defaults to `full`. @@ -1379,7 +1379,7 @@ These settings are *only* used for the back-channel communication between {{es}} :::: `ssl.supported_protocols` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Supported protocols with versions. Valid protocols: `SSLv2Hello`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM’s SSL provider supports TLSv1.3, the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is `TLSv1.2,TLSv1.1`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Supported protocols with versions. Valid protocols: `SSLv2Hello`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM’s SSL provider supports TLSv1.3, the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is `TLSv1.2,TLSv1.1`. {{es}} relies on your JDK’s implementation of SSL and TLS. View [Supported SSL/TLS versions by JDK version](docs-content://deploy-manage/security/supported-ssltls-versions-by-jdk-version.md) for more information. @@ -1389,7 +1389,7 @@ These settings are *only* used for the back-channel communication between {{es}} `ssl.cipher_suites` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. For more information, see Oracle’s [Java Cryptography Architecture documentation](https://docs.oracle.com/en/java/javase/11/security/oracle-providers.md#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2). @@ -1400,32 +1400,32 @@ These settings are *only* used for the back-channel communication between {{es}} In addition to the [settings that are valid for all realms](#ref-realm-settings), you can specify the following settings. `token_type` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The token type, `id_token` or `access_token`, that the JWT realm uses to verify incoming JWTs. Defaults to `id_token`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The token type, `id_token` or `access_token`, that the JWT realm uses to verify incoming JWTs. Defaults to `id_token`. `allowed_audiences` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) A list of allowed JWT audiences that {{es}} should verify. {{es}} will only consume JWTs that were intended for any of these audiences, as denoted by the `aud` claim in the JWT). The audiences are compared with exact string matches and do not support wildcards or regex. Examples of `aud` claim are `https://example.com/client1` and `other_service,elasticsearch`. When `token_type` is `access_token`, the audiences can be optionally denoted by a different claim in the JWT if `aud` does not exist. See also [`fallback_claims.aud`](#security-settings-jwt-fallback-claims-aud). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) A list of allowed JWT audiences that {{es}} should verify. {{es}} will only consume JWTs that were intended for any of these audiences, as denoted by the `aud` claim in the JWT). The audiences are compared with exact string matches and do not support wildcards or regex. Examples of `aud` claim are `https://example.com/client1` and `other_service,elasticsearch`. When `token_type` is `access_token`, the audiences can be optionally denoted by a different claim in the JWT if `aud` does not exist. See also [`fallback_claims.aud`](#security-settings-jwt-fallback-claims-aud). `allowed_clock_skew` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The maximum allowed clock skew to be taken into consideration when validating JWTs with regards to their creation, not before, and expiration times. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The maximum allowed clock skew to be taken into consideration when validating JWTs with regards to their creation, not before, and expiration times. `allowed_issuer` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) A verifiable Identifier for your JWT Issuer. An Issuer Identifier is usually a case sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components. However, it can be any string. The value for this setting should be provided by your JWT Issuer. The issuer is compared with exact string matches and do not support wildcards or regex. Examples of `iss` claim are `https://example.com:8443/jwt` and `issuer123`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) A verifiable Identifier for your JWT Issuer. An Issuer Identifier is usually a case sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components. However, it can be any string. The value for this setting should be provided by your JWT Issuer. The issuer is compared with exact string matches and do not support wildcards or regex. Examples of `iss` claim are `https://example.com:8443/jwt` and `issuer123`. `allowed_subjects` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) A list of allowed JWT subjects that {{es}} should verify. {{es}} will only consume JWTs that were issued for any of these subjects, as denoted by the `sub` claim in the JWT. The subjects are compared with exact string matches and do not support wildcards or regex. Examples of `sub` claim are `https://example.com/user1` and `user_1,user2`. When `token_type` is `access_token`, this setting is mandatory and the subject can be optionally denoted by a different claim in the JWT if `sub` does not exist. See also [`fallback_claims.sub`](#security-settings-jwt-fallback-claims-sub). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) A list of allowed JWT subjects that {{es}} should verify. {{es}} will only consume JWTs that were issued for any of these subjects, as denoted by the `sub` claim in the JWT. The subjects are compared with exact string matches and do not support wildcards or regex. Examples of `sub` claim are `https://example.com/user1` and `user_1,user2`. When `token_type` is `access_token`, this setting is mandatory and the subject can be optionally denoted by a different claim in the JWT if `sub` does not exist. See also [`fallback_claims.sub`](#security-settings-jwt-fallback-claims-sub). $$$security-settings-jwt-fallback-claims-sub$$$ `fallback_claims.sub` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The alternative claim to look for the subject information if the `sub` claim does not exist. It is configurable only when the `token_type` is `access_token`. The fallback is applied everywhere the `sub` claim is used. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The alternative claim to look for the subject information if the `sub` claim does not exist. It is configurable only when the `token_type` is `access_token`. The fallback is applied everywhere the `sub` claim is used. $$$security-settings-jwt-fallback-claims-aud$$$ `fallback_claims.aud` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The alternative claim to look for the audiences information if the `aud` claim does not exist. It is configurable only when the `token_type` is `access_token`. The fallback is applied everywhere the `aud` claim is used. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The alternative claim to look for the audiences information if the `aud` claim does not exist. It is configurable only when the `token_type` is `access_token`. The fallback is applied everywhere the `aud` claim is used. `required_claims` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Additional claims and associated values that {{es}} should verify. This is a group setting that takes key/value pairs, where the key is a string and the value must be either a string or an array of strings. The values are compared with exact string matches and do not support wildcards or regex. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Additional claims and associated values that {{es}} should verify. This is a group setting that takes key/value pairs, where the key is a string and the value must be either a string or an array of strings. The values are compared with exact string matches and do not support wildcards or regex. For example: @@ -1437,45 +1437,45 @@ xpack.security.authc.realms.jwt.jwt1: ``` `allowed_signature_algorithms` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) A list of signature algorithms that will be used by {{es}} in order to verify the signature of the JWT it will receive from the JWT Issuer. Defaults to `RS256`. Examples are `HS512,RS512,ES512` and `ES384`. Allowed values are `HS256`, `HS384`, `HS512`, `ES256`, `ES384`, `ES512`, `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `PS512`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) A list of signature algorithms that will be used by {{es}} in order to verify the signature of the JWT it will receive from the JWT Issuer. Defaults to `RS256`. Examples are `HS512,RS512,ES512` and `ES384`. Allowed values are `HS256`, `HS384`, `HS512`, `ES256`, `ES384`, `ES512`, `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `PS512`. `authorization_realms` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The names of the realms that should be consulted for delegated authorization. If this setting is used, then the JWT realm does not perform role mapping and instead loads the user from the listed realms. See [Delegating authorization to another realm](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The names of the realms that should be consulted for delegated authorization. If this setting is used, then the JWT realm does not perform role mapping and instead loads the user from the listed realms. See [Delegating authorization to another realm](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms). `claims.dn` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The name of the JWT claim that contains the user’s Distinguished Name (DN), which uniquely identifies a user or group. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The name of the JWT claim that contains the user’s Distinguished Name (DN), which uniquely identifies a user or group. `claim_patterns.dn` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Accepts the same Java regular expression as [`claim_patterns.principal`](#jwt-claim-pattern-principal), but for the `dn` property. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Accepts the same Java regular expression as [`claim_patterns.principal`](#jwt-claim-pattern-principal), but for the `dn` property. `claims.groups` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The name of the JWT claim that contains the user’s groups, such as `groups` and `roles`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The name of the JWT claim that contains the user’s groups, such as `groups` and `roles`. `claim_patterns.group` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Accepts the same Java regular expression as [`claim_patterns.principal`](#jwt-claim-pattern-principal), but for the `group` property. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Accepts the same Java regular expression as [`claim_patterns.principal`](#jwt-claim-pattern-principal), but for the `group` property. `claims.mail` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The name of the JWT claim that contains the user’s e-mail address. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The name of the JWT claim that contains the user’s e-mail address. `claim_patterns.mail` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Accepts the same Java regular expression as [`claim_patterns.principal`](#jwt-claim-pattern-principal), but for the `mail` property. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Accepts the same Java regular expression as [`claim_patterns.principal`](#jwt-claim-pattern-principal), but for the `mail` property. `claims.name` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The name of the JWT claim that contains the user’s username. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The name of the JWT claim that contains the user’s username. `claim_patterns.name` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Accepts the same Java regular expression as [`claim_patterns.principal`](#jwt-claim-pattern-principal), but for the `name` property. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Accepts the same Java regular expression as [`claim_patterns.principal`](#jwt-claim-pattern-principal), but for the `name` property. `claims.principal` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The name of the JWT claim that contains the user’s principal (username), such as `sub`, `name`, `email`, and `dn`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The name of the JWT claim that contains the user’s principal (username), such as `sub`, `name`, `email`, and `dn`. $$$jwt-claim-pattern-principal$$$ `claim_patterns.principal` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) An optional Java regular expression that is matched against the JWT claim specified by `claims.principal` before it is applied to the user’s `principal` property. The value must match the pattern and the value of the first *capturing group* is used as the principal. For example, `^([^@]+)@example\\.com$` matches email addresses from the `example.com` domain and uses the local-part as the principal. Another example is `sub` which may not need a pattern setting. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) An optional Java regular expression that is matched against the JWT claim specified by `claims.principal` before it is applied to the user’s `principal` property. The value must match the pattern and the value of the first *capturing group* is used as the principal. For example, `^([^@]+)@example\\.com$` matches email addresses from the `example.com` domain and uses the local-part as the principal. Another example is `sub` which may not need a pattern setting. `client_authentication.type` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies whether to use `shared_secret` or `none` to authenticate incoming client requests. If this value is `shared_secret`, the client is authenticated using an HTTP request header that must match a pre-configured secret value. The client must provide this shared secret with every request in the `ES-Client-Authentication` header. If this value is `none`, then the request header `ES-Client-Authentication` is ignored. Defaults to `shared_secret`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies whether to use `shared_secret` or `none` to authenticate incoming client requests. If this value is `shared_secret`, the client is authenticated using an HTTP request header that must match a pre-configured secret value. The client must provide this shared secret with every request in the `ES-Client-Authentication` header. If this value is `none`, then the request header `ES-Client-Authentication` is ignored. Defaults to `shared_secret`. Enabling client authentication is recommended. If JWT bearer tokens are shared with other clients or services, client authentication restricts which ones are allowed to submit those JWTs to {{es}}. @@ -1484,40 +1484,40 @@ $$$jwt-claim-pattern-principal$$$ : ([Secure](docs-content://deploy-manage/security/secure-settings.md), [reloadable](docs-content://deploy-manage/security/secure-settings.md#reloadable-secure-settings)) Secret value string for client authentication. Required if `client_authentication.type` is `shared_secret`. `client_authentication.rotation_grace_period` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets the grace period for how long after rotating the `client_authentication.shared_secret` is valid. `client_authentication.shared_secret` can be rotated by updating the keystore then calling the [reload API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-nodes-reload-secure-settings). Defaults to `1m`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets the grace period for how long after rotating the `client_authentication.shared_secret` is valid. `client_authentication.shared_secret` can be rotated by updating the keystore then calling the [reload API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-nodes-reload-secure-settings). Defaults to `1m`. `http.proxy.host` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the address of the proxy server for the HTTP client that is used for fetching the JSON Web Key Set from a remote URL. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the address of the proxy server for the HTTP client that is used for fetching the JSON Web Key Set from a remote URL. `http.proxy.scheme` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the protocol to use to connect to the proxy server for the HTTP client that is used for fetching the JSON Web Key Set from a remote URL. Must be `http`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the protocol to use to connect to the proxy server for the HTTP client that is used for fetching the JSON Web Key Set from a remote URL. Must be `http`. `http.proxy.port` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the port of the proxy server for the HTTP client that is used for fetching the JSON Web Key Set from a remote URL. Defaults to `80`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the port of the proxy server for the HTTP client that is used for fetching the JSON Web Key Set from a remote URL. Defaults to `80`. `http.connect_timeout` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Sets the timeout for the HTTP client that is used for fetching the JSON Web Key Set from a remote URL. A value of zero means the timeout is not used. Defaults to `5s`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Sets the timeout for the HTTP client that is used for fetching the JSON Web Key Set from a remote URL. A value of zero means the timeout is not used. Defaults to `5s`. `http.connection_read_timeout` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the HTTP timeout used when requesting a connection from the connection manager. Defaults to `5s`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the HTTP timeout used when requesting a connection from the connection manager. Defaults to `5s`. `http.socket_timeout` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the maximum socket timeout (SO_TIMEOUT) for the HTTP client to wait for inactivity between two consecutive data packets. Defaults to `5s`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the maximum socket timeout (SO_TIMEOUT) for the HTTP client to wait for inactivity between two consecutive data packets. Defaults to `5s`. `http.max_connections` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the maximum number of connections allowed across all endpoints. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the maximum number of connections allowed across all endpoints. `http.max_endpoint_connections` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the maximum number of connections allowed per endpoint. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the maximum number of connections allowed per endpoint. `jwt.cache.size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the maximum number of JWT cache entries. If clients use a different JWT for every request, set to `0` to disable the JWT cache. Defaults to `100000`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the maximum number of JWT cache entries. If clients use a different JWT for every request, set to `0` to disable the JWT cache. Defaults to `100000`. `jwt.cache.ttl` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the time-to-live for the period of time to cache JWT entries. JWTs can only be cached if client authentication is successful (or disabled). Uses the standard {{es}} [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units). If clients use a different JWT for every request, set to `0` to disable the JWT cache. Defaults to `20m`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the time-to-live for the period of time to cache JWT entries. JWTs can only be cached if client authentication is successful (or disabled). Uses the standard {{es}} [time units](/reference/elasticsearch/rest-apis/api-conventions.md#time-units). If clients use a different JWT for every request, set to `0` to disable the JWT cache. Defaults to `20m`. `pkc_jwkset_path` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The file name or URL to a JSON Web Key Set (JWKS) with the public key material that the JWT Realm uses for verifying token signatures. A value is considered a file name if it does not begin with `https`. The file name is resolved relative to the {{es}} configuration directory. If a URL is provided, then it must begin with `https://` (`http://` is not supported). {{es}} automatically caches the JWK set and will attempt to refresh the JWK set upon signature verification failure, as this might indicate that the JWT Provider has rotated the signing keys. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The file name or URL to a JSON Web Key Set (JWKS) with the public key material that the JWT Realm uses for verifying token signatures. A value is considered a file name if it does not begin with `https`. The file name is resolved relative to the {{es}} configuration directory. If a URL is provided, then it must begin with `https://` (`http://` is not supported). {{es}} automatically caches the JWK set and will attempt to refresh the JWK set upon signature verification failure, as this might indicate that the JWT Provider has rotated the signing keys. `hmac_jwkset` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) Contents of a JSON Web Key Set (JWKS), including the secret key that the JWT realm uses to verify token signatures. This format supports multiple keys and optional attributes, and is preferred over the `hmac_key` setting. Cannot be used in conjunction with the `hmac_key` setting. Refer to [Configure {{es}} to use a JWT realm](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md). @@ -1526,7 +1526,7 @@ $$$jwt-claim-pattern-principal$$$ : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) Contents of a single JSON Web Key (JWK), including the secret key that the JWT realm uses to verify token signatures. This format only supports a single key without attributes, and cannot be used with the `hmac_jwkset` setting. This format is compatible with OIDC. The HMAC key must be a UNICODE string, where the key bytes are the UTF-8 encoding of the UNICODE string. The `hmac_jwkset` setting is preferred. Refer to [Configure {{es}} to use a JWT realm](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md). `populate_user_metadata` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies whether to populate the {{es}} user’s metadata with the values that are provided by the JWT claims. Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies whether to populate the {{es}} user’s metadata with the values that are provided by the JWT claims. Defaults to `true`. #### JWT realm SSL settings [ref-jwt-ssl-settings] @@ -1539,13 +1539,13 @@ These settings are *only* used for the back-channel communication between {{es}} `ssl.key` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Path to a PEM encoded file containing the private key. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Path to a PEM encoded file containing the private key. If HTTP client authentication is required, it uses this file. You cannot use this setting and `ssl.keystore.path` at the same time. `ssl.key_passphrase` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.secure_key_passphrase` instead. @@ -1561,28 +1561,28 @@ These settings are *only* used for the back-channel communication between {{es}} `ssl.certificate` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key. This setting can be used only if `ssl.key` is set. `ssl.certificate_authorities` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) List of paths to PEM encoded certificate files that should be trusted. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) List of paths to PEM encoded certificate files that should be trusted. This setting and `ssl.truststore.path` cannot be used at the same time. `ssl.keystore.path` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.key` at the same time. `ssl.keystore.type` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The format of the keystore file. It must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The format of the keystore file. It must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. `ssl.keystore.password` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the keystore. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the keystore. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.keystore.secure_password` instead. @@ -1595,7 +1595,7 @@ These settings are *only* used for the back-channel communication between {{es}} `ssl.keystore.key_password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.keystore.secure_key_password` instead. @@ -1613,16 +1613,16 @@ These settings are *only* used for the back-channel communication between {{es}} `ssl.truststore.path` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.certificate_authorities` at the same time. `ssl.truststore.type` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The format of the truststore file. It must be either `jks` or `PKCS12`. If the file name ends in ".p12", ".pfx" or "pkcs12", the default is `PKCS12`. Otherwise, it defaults to `jks`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The format of the truststore file. It must be either `jks` or `PKCS12`. If the file name ends in ".p12", ".pfx" or "pkcs12", the default is `PKCS12`. Otherwise, it defaults to `jks`. `ssl.truststore.password` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the truststore. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the truststore. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.truststore.secure_password` instead. @@ -1638,7 +1638,7 @@ These settings are *only* used for the back-channel communication between {{es}} `ssl.verification_mode` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Controls the verification of certificates. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Controls the verification of certificates. Defaults to `full`. @@ -1652,7 +1652,7 @@ These settings are *only* used for the back-channel communication between {{es}} :::: `ssl.supported_protocols` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Supported protocols with versions. Valid protocols: `SSLv2Hello`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM’s SSL provider supports TLSv1.3, the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is `TLSv1.2,TLSv1.1`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Supported protocols with versions. Valid protocols: `SSLv2Hello`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM’s SSL provider supports TLSv1.3, the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is `TLSv1.2,TLSv1.1`. {{es}} relies on your JDK’s implementation of SSL and TLS. View [Supported SSL/TLS versions by JDK version](docs-content://deploy-manage/security/supported-ssltls-versions-by-jdk-version.md) for more information. @@ -1662,7 +1662,7 @@ These settings are *only* used for the back-channel communication between {{es}} `ssl.cipher_suites` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. For more information, see Oracle’s [Java Cryptography Architecture documentation](https://docs.oracle.com/en/java/javase/11/security/oracle-providers.md#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2). @@ -1670,7 +1670,7 @@ These settings are *only* used for the back-channel communication between {{es}} #### Load balancing and failover [load-balancing] -The [static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting) `load_balance.type` setting can have the following values: +The [Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting) `load_balance.type` setting can have the following values: * `failover`: The URLs specified are used in the order that they are specified. The first server that can be connected to will be used for all subsequent connections. If a connection to that server fails then the next server that a connection can be established to will be used for subsequent connections. * `dns_failover`: In this mode of operation, only a single URL may be specified. This URL must contain a DNS name. The system will be queried for all IP addresses that correspond to this DNS name. Connections to the Active Directory or LDAP server will always be tried in the order in which they were retrieved. This differs from `failover` in that there is no reordering of the list and if a server has failed at the beginning of the list, it will still be tried for each subsequent connection. @@ -1681,7 +1681,7 @@ The [static](docs-content://deploy-manage/deploy/self-managed/configure-elastics ### General TLS settings [ssl-tls-settings] `xpack.security.ssl.diagnose.trust` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Controls whether to output diagnostic messages for SSL/TLS trust failures. If this is `true` (the default), a message will be printed to the Elasticsearch log whenever an SSL connection (incoming or outgoing) is rejected due to a failure to establish trust. This diagnostic message contains information that can be used to determine the cause of the failure and assist with resolving the problem. Set to `false` to disable these messages. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Controls whether to output diagnostic messages for SSL/TLS trust failures. If this is `true` (the default), a message will be printed to the Elasticsearch log whenever an SSL connection (incoming or outgoing) is rejected due to a failure to establish trust. This diagnostic message contains information that can be used to determine the cause of the failure and assist with resolving the problem. Set to `false` to disable these messages. #### TLS/SSL key and trusted certificate settings [tls-ssl-key-settings] @@ -1700,10 +1700,10 @@ Storing trusted certificates in a PKCS#12 file, although supported, is uncommon You can configure the following TLS/SSL settings. `xpack.security.http.ssl.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Used to enable or disable TLS/SSL on the HTTP networking layer, which {{es}} uses to communicate with other clients. The default is `false`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Used to enable or disable TLS/SSL on the HTTP networking layer, which {{es}} uses to communicate with other clients. The default is `false`. `xpack.security.http.ssl.supported_protocols` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Supported protocols with versions. Valid protocols: `SSLv2Hello`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM’s SSL provider supports TLSv1.3, the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is `TLSv1.2,TLSv1.1`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Supported protocols with versions. Valid protocols: `SSLv2Hello`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM’s SSL provider supports TLSv1.3, the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is `TLSv1.2,TLSv1.1`. {{es}} relies on your JDK’s implementation of SSL and TLS. View [Supported SSL/TLS versions by JDK version](docs-content://deploy-manage/security/supported-ssltls-versions-by-jdk-version.md) for more information. @@ -1713,10 +1713,10 @@ You can configure the following TLS/SSL settings. `xpack.security.http.ssl.client_authentication` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Controls the server’s behavior in regard to requesting a certificate from client connections. Valid values are `required`, `optional`, and `none`. `required` forces a client to present a certificate, while `optional` requests a client certificate but the client is not required to present one. Defaults to `none`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Controls the server’s behavior in regard to requesting a certificate from client connections. Valid values are `required`, `optional`, and `none`. `required` forces a client to present a certificate, while `optional` requests a client certificate but the client is not required to present one. Defaults to `none`. `xpack.security.http.ssl.verification_mode` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The SSL settings in `xpack.security.http.ssl` control a *server context* for TLS, which defines the settings for the TLS connection. The use of `verification_mode` in a TLS *server* is discouraged. Defines how to verify the certificates presented by another party in the TLS connection: +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The SSL settings in `xpack.security.http.ssl` control a *server context* for TLS, which defines the settings for the TLS connection. The use of `verification_mode` in a TLS *server* is discouraged. Defines how to verify the certificates presented by another party in the TLS connection: Defaults to `full`. @@ -1730,7 +1730,7 @@ You can configure the following TLS/SSL settings. :::: `xpack.security.http.ssl.cipher_suites` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. For more information, see Oracle’s [Java Cryptography Architecture documentation](https://docs.oracle.com/en/java/javase/11/security/oracle-providers.md#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2). @@ -1745,13 +1745,13 @@ The following settings are used to specify a private key, certificate, and the t When using PEM encoded files, use the following settings: `xpack.security.http.ssl.key` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Path to a PEM encoded file containing the private key. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Path to a PEM encoded file containing the private key. If HTTP client authentication is required, it uses this file. You cannot use this setting and `ssl.keystore.path` at the same time. `xpack.security.http.ssl.key_passphrase` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.secure_key_passphrase` instead. @@ -1764,13 +1764,13 @@ When using PEM encoded files, use the following settings: : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional. `xpack.security.http.ssl.certificate` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key. This setting can be used only if `ssl.key` is set. `xpack.security.http.ssl.certificate_authorities` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) List of paths to PEM encoded certificate files that should be trusted. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) List of paths to PEM encoded certificate files that should be trusted. This setting and `ssl.truststore.path` cannot be used at the same time. @@ -1781,13 +1781,13 @@ When using PEM encoded files, use the following settings: When using Java keystore files (JKS), which contain the private key, certificate and certificates that should be trusted, use the following settings: `xpack.security.http.ssl.keystore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.key` at the same time. `xpack.security.http.ssl.keystore.password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the keystore. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the keystore. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.keystore.secure_password` instead. @@ -1797,7 +1797,7 @@ When using Java keystore files (JKS), which contain the private key, certificate : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password for the keystore. `xpack.security.http.ssl.keystore.key_password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.keystore.secure_key_password` instead. @@ -1810,13 +1810,13 @@ When using Java keystore files (JKS), which contain the private key, certificate : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password for the key in the keystore. The default is the keystore password. `xpack.security.http.ssl.truststore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.certificate_authorities` at the same time. `xpack.security.http.ssl.truststore.password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the truststore. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the truststore. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.truststore.secure_password` instead. @@ -1836,16 +1836,16 @@ When using Java keystore files (JKS), which contain the private key, certificate PKCS#12 files are configured in the same way as Java keystore files: `xpack.security.http.ssl.keystore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.key` at the same time. `xpack.security.http.ssl.keystore.type` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The format of the keystore file. It must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The format of the keystore file. It must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. `xpack.security.http.ssl.keystore.password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the keystore. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the keystore. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.keystore.secure_password` instead. @@ -1855,7 +1855,7 @@ PKCS#12 files are configured in the same way as Java keystore files: : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password for the keystore. `xpack.security.http.ssl.keystore.key_password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.keystore.secure_key_password` instead. @@ -1868,16 +1868,16 @@ PKCS#12 files are configured in the same way as Java keystore files: : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password for the key in the keystore. The default is the keystore password. `xpack.security.http.ssl.truststore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.certificate_authorities` at the same time. `xpack.security.http.ssl.truststore.type` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Set this to `PKCS12` to indicate that the truststore is a PKCS#12 file. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Set this to `PKCS12` to indicate that the truststore is a PKCS#12 file. `xpack.security.http.ssl.truststore.password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the truststore. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the truststore. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.truststore.secure_password` instead. @@ -1896,10 +1896,10 @@ PKCS#12 files are configured in the same way as Java keystore files: You can configure the following TLS/SSL settings. `xpack.security.transport.ssl.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Used to enable or disable TLS/SSL on the transport networking layer, which nodes use to communicate with each other. The default is `false`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Used to enable or disable TLS/SSL on the transport networking layer, which nodes use to communicate with each other. The default is `false`. `xpack.security.transport.ssl.supported_protocols` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Supported protocols with versions. Valid protocols: `SSLv2Hello`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM’s SSL provider supports TLSv1.3, the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is `TLSv1.2,TLSv1.1`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Supported protocols with versions. Valid protocols: `SSLv2Hello`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM’s SSL provider supports TLSv1.3, the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is `TLSv1.2,TLSv1.1`. {{es}} relies on your JDK’s implementation of SSL and TLS. View [Supported SSL/TLS versions by JDK version](docs-content://deploy-manage/security/supported-ssltls-versions-by-jdk-version.md) for more information. @@ -1909,10 +1909,10 @@ You can configure the following TLS/SSL settings. `xpack.security.transport.ssl.client_authentication` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Controls the server’s behavior in regard to requesting a certificate from client connections. Valid values are `required`, `optional`, and `none`. `required` forces a client to present a certificate, while `optional` requests a client certificate but the client is not required to present one. Defaults to `required`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Controls the server’s behavior in regard to requesting a certificate from client connections. Valid values are `required`, `optional`, and `none`. `required` forces a client to present a certificate, while `optional` requests a client certificate but the client is not required to present one. Defaults to `required`. `xpack.security.transport.ssl.verification_mode` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Defines how to verify the certificates presented by another party in the TLS connection: +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Defines how to verify the certificates presented by another party in the TLS connection: Defaults to `full`. @@ -1926,7 +1926,7 @@ You can configure the following TLS/SSL settings. :::: `xpack.security.transport.ssl.cipher_suites` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. For more information, see Oracle’s [Java Cryptography Architecture documentation](https://docs.oracle.com/en/java/javase/11/security/oracle-providers.md#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2). @@ -1944,13 +1944,13 @@ The following settings are used to specify a private key, certificate, and the t When using PEM encoded files, use the following settings: `xpack.security.transport.ssl.key` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Path to a PEM encoded file containing the private key. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Path to a PEM encoded file containing the private key. If HTTP client authentication is required, it uses this file. You cannot use this setting and `ssl.keystore.path` at the same time. `xpack.security.transport.ssl.key_passphrase` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.secure_key_passphrase` instead. @@ -1963,13 +1963,13 @@ When using PEM encoded files, use the following settings: : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional. `xpack.security.transport.ssl.certificate` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key. This setting can be used only if `ssl.key` is set. `xpack.security.transport.ssl.certificate_authorities` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) List of paths to PEM encoded certificate files that should be trusted. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) List of paths to PEM encoded certificate files that should be trusted. This setting and `ssl.truststore.path` cannot be used at the same time. @@ -1982,13 +1982,13 @@ When using PEM encoded files, use the following settings: When using Java keystore files (JKS), which contain the private key, certificate and certificates that should be trusted, use the following settings: `xpack.security.transport.ssl.keystore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.key` at the same time. `xpack.security.transport.ssl.keystore.password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the keystore. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the keystore. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.keystore.secure_password` instead. @@ -1998,7 +1998,7 @@ When using Java keystore files (JKS), which contain the private key, certificate : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password for the keystore. `xpack.security.transport.ssl.keystore.key_password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.keystore.secure_key_password` instead. @@ -2011,13 +2011,13 @@ When using Java keystore files (JKS), which contain the private key, certificate : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password for the key in the keystore. The default is the keystore password. `xpack.security.transport.ssl.truststore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.certificate_authorities` at the same time. `xpack.security.transport.ssl.truststore.password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the truststore. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the truststore. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.truststore.secure_password` instead. @@ -2037,16 +2037,16 @@ When using Java keystore files (JKS), which contain the private key, certificate PKCS#12 files are configured in the same way as Java keystore files: `xpack.security.transport.ssl.keystore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.key` at the same time. `xpack.security.transport.ssl.keystore.type` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The format of the keystore file. It must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The format of the keystore file. It must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. `xpack.security.transport.ssl.keystore.password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the keystore. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the keystore. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.keystore.secure_password` instead. @@ -2056,7 +2056,7 @@ PKCS#12 files are configured in the same way as Java keystore files: : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password for the keystore. `xpack.security.transport.ssl.keystore.key_password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the key in the keystore. The default is the keystore password. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.keystore.secure_key_password` instead. @@ -2069,16 +2069,16 @@ PKCS#12 files are configured in the same way as Java keystore files: : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password for the key in the keystore. The default is the keystore password. `xpack.security.transport.ssl.truststore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.certificate_authorities` at the same time. `xpack.security.transport.ssl.truststore.type` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Set this to `PKCS12` to indicate that the truststore is a PKCS#12 file. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Set this to `PKCS12` to indicate that the truststore is a PKCS#12 file. `xpack.security.transport.ssl.truststore.password` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The password for the truststore. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The password for the truststore. :::{admonition} Deprecated in 7.17.0 Prefer `ssl.truststore.secure_password` instead. @@ -2097,10 +2097,10 @@ PKCS#12 files are configured in the same way as Java keystore files: You can configure the following TLS/SSL settings. `xpack.security.remote_cluster_server.ssl.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Used to enable or disable TLS/SSL on the remote cluster server networking layer, which {{es}} uses to communicate with remote cluster clients. The default is `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Used to enable or disable TLS/SSL on the remote cluster server networking layer, which {{es}} uses to communicate with remote cluster clients. The default is `true`. `xpack.security.remote_cluster_server.ssl.supported_protocols` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Supported protocols with versions. Valid protocols: `SSLv2Hello`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM’s SSL provider supports TLSv1.3, the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is `TLSv1.2,TLSv1.1`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Supported protocols with versions. Valid protocols: `SSLv2Hello`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM’s SSL provider supports TLSv1.3, the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is `TLSv1.2,TLSv1.1`. {{es}} relies on your JDK’s implementation of SSL and TLS. View [Supported SSL/TLS versions by JDK version](docs-content://deploy-manage/security/supported-ssltls-versions-by-jdk-version.md) for more information. @@ -2110,10 +2110,10 @@ You can configure the following TLS/SSL settings. `xpack.security.remote_cluster_server.ssl.client_authentication` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Controls the server’s behavior in regard to requesting a certificate from client connections. Valid values are `required`, `optional`, and `none`. `required` forces a client to present a certificate, while `optional` requests a client certificate but the client is not required to present one. Defaults to `none`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Controls the server’s behavior in regard to requesting a certificate from client connections. Valid values are `required`, `optional`, and `none`. `required` forces a client to present a certificate, while `optional` requests a client certificate but the client is not required to present one. Defaults to `none`. `xpack.security.remote_cluster_server.ssl.verification_mode` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The SSL settings in `xpack.security.remote_cluster_server.ssl` control a *server context* for TLS, which defines the settings for the TLS connection. The use of `verification_mode` in a TLS *server* is discouraged. Defines how to verify the certificates presented by another party in the TLS connection: +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The SSL settings in `xpack.security.remote_cluster_server.ssl` control a *server context* for TLS, which defines the settings for the TLS connection. The use of `verification_mode` in a TLS *server* is discouraged. Defines how to verify the certificates presented by another party in the TLS connection: Defaults to `full`. @@ -2127,7 +2127,7 @@ You can configure the following TLS/SSL settings. :::: `xpack.security.remote_cluster_server.ssl.cipher_suites` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. For more information, see Oracle’s [Java Cryptography Architecture documentation](https://docs.oracle.com/en/java/javase/11/security/oracle-providers.md#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2). @@ -2142,7 +2142,7 @@ The following settings are used to specify a private key, certificate, and the t When using PEM encoded files, use the following settings: `xpack.security.remote_cluster_server.ssl.key` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Path to a PEM encoded file containing the private key. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Path to a PEM encoded file containing the private key. If HTTP client authentication is required, it uses this file. You cannot use this setting and `ssl.keystore.path` at the same time. @@ -2151,13 +2151,13 @@ When using PEM encoded files, use the following settings: : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional. `xpack.security.remote_cluster_server.ssl.certificate` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key. This setting can be used only if `ssl.key` is set. `xpack.security.remote_cluster_server.ssl.certificate_authorities` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) List of paths to PEM encoded certificate files that should be trusted. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) List of paths to PEM encoded certificate files that should be trusted. This setting and `ssl.truststore.path` cannot be used at the same time. @@ -2168,7 +2168,7 @@ When using PEM encoded files, use the following settings: When using Java keystore files (JKS), which contain the private key, certificate and certificates that should be trusted, use the following settings: `xpack.security.remote_cluster_server.ssl.keystore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.key` at the same time. @@ -2180,7 +2180,7 @@ When using Java keystore files (JKS), which contain the private key, certificate : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password for the key in the keystore. The default is the keystore password. `xpack.security.remote_cluster_server.ssl.truststore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.certificate_authorities` at the same time. @@ -2196,13 +2196,13 @@ When using Java keystore files (JKS), which contain the private key, certificate PKCS#12 files are configured in the same way as Java keystore files: `xpack.security.remote_cluster_server.ssl.keystore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.key` at the same time. `xpack.security.remote_cluster_server.ssl.keystore.type` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The format of the keystore file. It must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The format of the keystore file. It must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. `xpack.security.remote_cluster_server.ssl.keystore.secure_password` : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password for the keystore. @@ -2211,13 +2211,13 @@ PKCS#12 files are configured in the same way as Java keystore files: : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password for the key in the keystore. The default is the keystore password. `xpack.security.remote_cluster_server.ssl.truststore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.certificate_authorities` at the same time. `xpack.security.remote_cluster_server.ssl.truststore.type` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Set this to `PKCS12` to indicate that the truststore is a PKCS#12 file. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Set this to `PKCS12` to indicate that the truststore is a PKCS#12 file. `xpack.security.remote_cluster_server.ssl.truststore.secure_password` : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) Password for the truststore. @@ -2229,10 +2229,10 @@ PKCS#12 files are configured in the same way as Java keystore files: You can configure the following TLS/SSL settings. `xpack.security.remote_cluster_client.ssl.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Used to enable or disable TLS/SSL on the remote cluster client networking layer, which {{es}} uses to communicate with remote cluster servers. The default is `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Used to enable or disable TLS/SSL on the remote cluster client networking layer, which {{es}} uses to communicate with remote cluster servers. The default is `true`. `xpack.security.remote_cluster_client.ssl.supported_protocols` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Supported protocols with versions. Valid protocols: `SSLv2Hello`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM’s SSL provider supports TLSv1.3, the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is `TLSv1.2,TLSv1.1`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Supported protocols with versions. Valid protocols: `SSLv2Hello`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM’s SSL provider supports TLSv1.3, the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is `TLSv1.2,TLSv1.1`. {{es}} relies on your JDK’s implementation of SSL and TLS. View [Supported SSL/TLS versions by JDK version](docs-content://deploy-manage/security/supported-ssltls-versions-by-jdk-version.md) for more information. @@ -2242,7 +2242,7 @@ You can configure the following TLS/SSL settings. `xpack.security.remote_cluster_client.ssl.verification_mode` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Defines how to verify the certificates presented by another party in the TLS connection: +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Defines how to verify the certificates presented by another party in the TLS connection: Defaults to `full`. @@ -2256,7 +2256,7 @@ You can configure the following TLS/SSL settings. :::: `xpack.security.remote_cluster_client.ssl.cipher_suites` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. For more information, see Oracle’s [Java Cryptography Architecture documentation](https://docs.oracle.com/en/java/javase/11/security/oracle-providers.md#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2). @@ -2271,7 +2271,7 @@ The following settings are used to specify a private key, certificate, and the t When using PEM encoded files, use the following settings: `xpack.security.remote_cluster_client.ssl.key` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Path to a PEM encoded file containing the private key. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Path to a PEM encoded file containing the private key. If HTTP client authentication is required, it uses this file. You cannot use this setting and `ssl.keystore.path` at the same time. @@ -2280,13 +2280,13 @@ When using PEM encoded files, use the following settings: : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional. `xpack.security.remote_cluster_client.ssl.certificate` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key. This setting can be used only if `ssl.key` is set. `xpack.security.remote_cluster_client.ssl.certificate_authorities` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) List of paths to PEM encoded certificate files that should be trusted. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) List of paths to PEM encoded certificate files that should be trusted. This setting and `ssl.truststore.path` cannot be used at the same time. @@ -2297,7 +2297,7 @@ When using PEM encoded files, use the following settings: When using Java keystore files (JKS), which contain the private key, certificate and certificates that should be trusted, use the following settings: `xpack.security.remote_cluster_client.ssl.keystore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.key` at the same time. @@ -2309,7 +2309,7 @@ When using Java keystore files (JKS), which contain the private key, certificate : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password for the key in the keystore. The default is the keystore password. `xpack.security.remote_cluster_client.ssl.truststore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.certificate_authorities` at the same time. @@ -2325,13 +2325,13 @@ When using Java keystore files (JKS), which contain the private key, certificate PKCS#12 files are configured in the same way as Java keystore files: `xpack.security.remote_cluster_client.ssl.keystore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.key` at the same time. `xpack.security.remote_cluster_client.ssl.keystore.type` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The format of the keystore file. It must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The format of the keystore file. It must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. `xpack.security.remote_cluster_client.ssl.keystore.secure_password` : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password for the keystore. @@ -2340,13 +2340,13 @@ PKCS#12 files are configured in the same way as Java keystore files: : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password for the key in the keystore. The default is the keystore password. `xpack.security.remote_cluster_client.ssl.truststore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.certificate_authorities` at the same time. `xpack.security.remote_cluster_client.ssl.truststore.type` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Set this to `PKCS12` to indicate that the truststore is a PKCS#12 file. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Set this to `PKCS12` to indicate that the truststore is a PKCS#12 file. `xpack.security.remote_cluster_client.ssl.truststore.secure_password` : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) Password for the truststore. @@ -2364,33 +2364,33 @@ As an example, lets look at the key setting. For the default transport this is ` You can configure the following settings for [IP filtering](docs-content://deploy-manage/security/ip-traffic-filtering.md). `xpack.security.transport.filter.allow` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) List of IP addresses to allow. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) List of IP addresses to allow. `xpack.security.transport.filter.deny` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) List of IP addresses to deny. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) List of IP addresses to deny. `xpack.security.http.filter.allow` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) List of IP addresses to allow just for HTTP. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) List of IP addresses to allow just for HTTP. `xpack.security.http.filter.deny` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) List of IP addresses to deny just for HTTP. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) List of IP addresses to deny just for HTTP. `transport.profiles.$PROFILE.xpack.security.filter.allow` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) List of IP addresses to allow for this profile. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) List of IP addresses to allow for this profile. `transport.profiles.$PROFILE.xpack.security.filter.deny` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) List of IP addresses to deny for this profile. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) List of IP addresses to deny for this profile. `xpack.security.remote_cluster.filter.allow` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) List of IP addresses to allow just for the [remote cluster server configured with the API key based model](docs-content://deploy-manage/remote-clusters/remote-clusters-api-key.md). +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) List of IP addresses to allow just for the [remote cluster server configured with the API key based model](docs-content://deploy-manage/remote-clusters/remote-clusters-api-key.md). `xpack.security.remote_cluster.filter.deny` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) List of IP addresses to deny just for the remote cluster server configured with the [API key based model](docs-content://deploy-manage/remote-clusters/remote-clusters-api-key.md). +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) List of IP addresses to deny just for the remote cluster server configured with the [API key based model](docs-content://deploy-manage/remote-clusters/remote-clusters-api-key.md). ## User cache and password hash algorithms [hashing-settings] -Certain realms store user credentials in memory. To limit exposure to credential theft and mitigate credential compromise, the cache only stores a hashed version of the user credentials in memory. By default, the user cache is hashed with a salted `sha-256` hash algorithm. You can use a different hashing algorithm by setting the [static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting) `cache.hash_algo` realm settings to any of the following values: +Certain realms store user credentials in memory. To limit exposure to credential theft and mitigate credential compromise, the cache only stores a hashed version of the user credentials in memory. By default, the user cache is hashed with a salted `sha-256` hash algorithm. You can use a different hashing algorithm by setting the [Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting) `cache.hash_algo` realm settings to any of the following values: $$$cache-hash-algo$$$ @@ -2422,7 +2422,7 @@ $$$cache-hash-algo$$$ | `pbkdf2_stretch_1000000` | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a pseudorandom function using 1000000 iterations, after hashing the initial input with SHA512 first. | | `noop`,`clear_text` | Doesn’t hash the credentials and keeps it in clear text in memory. CAUTION: keeping clear text is considered insecure and can be compromised at the OS level (for example through memory dumps and using `ptrace`). | -Likewise, realms that store passwords hash them using cryptographically strong and password-specific salt values. You can configure the algorithm for password hashing by setting the [static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting) `xpack.security.authc.password_hashing.algorithm` setting to one of the following: +Likewise, realms that store passwords hash them using cryptographically strong and password-specific salt values. You can configure the algorithm for password hashing by setting the [Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting) `xpack.security.authc.password_hashing.algorithm` setting to one of the following: $$$password-hashing-algorithms$$$ @@ -2457,7 +2457,7 @@ $$$password-hashing-algorithms$$$ Furthermore, {{es}} supports authentication via securely-generated high entropy tokens, for instance [API keys](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key). Analogous to passwords, only the tokens' hashes are stored. Since the tokens are guaranteed to have sufficiently high entropy to resist offline attacks, secure salted hash functions are supported in addition to the password-hashing algorithms mentioned above. -You can configure the algorithm for API key stored credential hashing by setting the [static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting) `xpack.security.authc.api_key.hashing.algorithm` setting to one of the following +You can configure the algorithm for API key stored credential hashing by setting the [Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting) `xpack.security.authc.api_key.hashing.algorithm` setting to one of the following $$$secure-token-hashing-algorithms$$$ diff --git a/docs/reference/elasticsearch/configuration-reference/shard-request-cache-settings.md b/docs/reference/elasticsearch/configuration-reference/shard-request-cache-settings.md index 9a801ea607dc7..95fcc9bd037c0 100644 --- a/docs/reference/elasticsearch/configuration-reference/shard-request-cache-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/shard-request-cache-settings.md @@ -13,7 +13,7 @@ The following settings affect the behavior of the [shard request cache](/referen ## Cache settings [_cache_settings] `indices.requests.cache.size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The maximum size of the cache, as a percentage of the heap. Default: `1%`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The maximum size of the cache, as a percentage of the heap. Default: `1%`. `indices.requests.cache.expire` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The TTL for cached results. Stale results are automatically invalidated when the index is refreshed, so you shouldn’t need to use this setting. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The TTL for cached results. Stale results are automatically invalidated when the index is refreshed, so you shouldn’t need to use this setting. diff --git a/docs/reference/elasticsearch/configuration-reference/snapshot-restore-settings.md b/docs/reference/elasticsearch/configuration-reference/snapshot-restore-settings.md index 4f7d27c6fc4ab..1ef310d85d76c 100644 --- a/docs/reference/elasticsearch/configuration-reference/snapshot-restore-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/snapshot-restore-settings.md @@ -14,7 +14,7 @@ The following cluster settings configure [snapshot and restore](docs-content://d $$$snapshot-max-concurrent-ops$$$ `snapshot.max_concurrent_operations` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting), integer) Maximum number of concurrent snapshot operations. Defaults to `1000`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), integer) Maximum number of concurrent snapshot operations. Defaults to `1000`. This limit applies in total to all ongoing snapshot creation, cloning, and deletion operations. {{es}} will reject any operations that would exceed this limit. @@ -29,26 +29,26 @@ The following cluster settings configure [{{slm}} ({{slm-init}})](docs-content:/ $$$slm-history-index-enabled$$$ `slm.history_index_enabled` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting), Boolean) Controls whether {{slm-init}} records the history of actions taken as part of {{slm-init}} policies to the `slm-history-*` indices. Defaults to `true`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), Boolean) Controls whether {{slm-init}} records the history of actions taken as part of {{slm-init}} policies to the `slm-history-*` indices. Defaults to `true`. $$$slm-retention-schedule$$$ `slm.retention_schedule` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting), [cron scheduler value](docs-content://explore-analyze/alerts-cases/watcher/schedule-types.md#schedule-cron)) Controls when the [retention task](docs-content://deploy-manage/tools/snapshot-and-restore/create-snapshots.md#slm-retention-task) runs. Can be a periodic or absolute time schedule. Supports all values supported by the [cron scheduler](docs-content://explore-analyze/alerts-cases/watcher/schedule-types.md#schedule-cron). Defaults to daily at 1:30am UTC: `0 30 1 * * ?`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), [cron scheduler value](docs-content://explore-analyze/alerts-cases/watcher/schedule-types.md#schedule-cron)) Controls when the [retention task](docs-content://deploy-manage/tools/snapshot-and-restore/create-snapshots.md#slm-retention-task) runs. Can be a periodic or absolute time schedule. Supports all values supported by the [cron scheduler](docs-content://explore-analyze/alerts-cases/watcher/schedule-types.md#schedule-cron). Defaults to daily at 1:30am UTC: `0 30 1 * * ?`. $$$slm-retention-duration$$$ `slm.retention_duration` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting), [time value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) Limits how long {{slm-init}} should spend deleting old snapshots. Defaults to one hour: `1h`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), [time value](/reference/elasticsearch/rest-apis/api-conventions.md#time-units)) Limits how long {{slm-init}} should spend deleting old snapshots. Defaults to one hour: `1h`. $$$slm-health-failed-snapshot-warn-threshold$$$ `slm.health.failed_snapshot_warn_threshold` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting), Long) The number of failed invocations since last successful snapshot that indicate a problem with the policy in the health api. Defaults to a health api warning after five repeated failures: `5L`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting), Long) The number of failed invocations since last successful snapshot that indicate a problem with the policy in the health api. Defaults to a health api warning after five repeated failures: `5L`. $$$repositories-url-allowed$$$ `repositories.url.allowed_urls` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the [read-only URL repositories](docs-content://deploy-manage/tools/snapshot-and-restore/read-only-url-repository.md) that snapshots can be restored from. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the [read-only URL repositories](docs-content://deploy-manage/tools/snapshot-and-restore/read-only-url-repository.md) that snapshots can be restored from. diff --git a/docs/reference/elasticsearch/configuration-reference/thread-pool-settings.md b/docs/reference/elasticsearch/configuration-reference/thread-pool-settings.md index 6c754ec160da2..7f786e9b8e29a 100644 --- a/docs/reference/elasticsearch/configuration-reference/thread-pool-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/thread-pool-settings.md @@ -80,7 +80,7 @@ $$$search-throttled$$$`search_throttled` $$$modules-threadpool-esql$$$`esql_worker` : Executes [{{esql}}](docs-content://explore-analyze/query-filter/languages/esql.md) operations. Thread pool type is `fixed` with a size of `int((`[`# of allocated processors`](#node.processors) ` * 3) / 2) + 1`, and queue_size of `1000`. -Thread pool settings are [static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting) and can be changed by editing `elasticsearch.yml`. Changing a specific thread pool can be done by setting its type-specific parameters; for example, changing the number of threads in the `write` thread pool: +Thread pool settings are [Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting) and can be changed by editing `elasticsearch.yml`. Changing a specific thread pool can be done by setting its type-specific parameters; for example, changing the number of threads in the `write` thread pool: ```yaml thread_pool: diff --git a/docs/reference/elasticsearch/configuration-reference/transforms-settings.md b/docs/reference/elasticsearch/configuration-reference/transforms-settings.md index e8b2953b162fd..f3ed829f49d6b 100644 --- a/docs/reference/elasticsearch/configuration-reference/transforms-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/transforms-settings.md @@ -16,7 +16,7 @@ You do not need to configure any settings to use {{transforms}}. It is enabled b ## General {{transforms}} settings [general-transform-settings] `node.roles: [ transform ]` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Set `node.roles` to contain `transform` to identify the node as a *transform node*. If you want to run {{transforms}}, there must be at least one {{transform}} node in your cluster. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Set `node.roles` to contain `transform` to identify the node as a *transform node*. If you want to run {{transforms}}, there must be at least one {{transform}} node in your cluster. If you set `node.roles`, you must explicitly specify all the required roles for the node. To learn more, refer to [Node settings](/reference/elasticsearch/configuration-reference/node-settings.md). @@ -30,8 +30,8 @@ You do not need to configure any settings to use {{transforms}}. It is enabled b This deprecated setting no longer has any effect. ::: - ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) + ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) `xpack.transform.num_transform_failure_retries` -: ([Dynamic](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)) The number of times that a {{transform}} retries when it experiences a non-fatal error. Once the number of retries is exhausted, the {{transform}} task is marked as `failed`. The default value is `10` with a valid minimum of `0` and maximum of `100`. If a {{transform}} is already running, it has to be restarted to use the changed setting. The `num_failure_retries` setting can also be specified on an individual {{transform}} level. Specifying this setting for each {{transform}} individually is recommended. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The number of times that a {{transform}} retries when it experiences a non-fatal error. Once the number of retries is exhausted, the {{transform}} task is marked as `failed`. The default value is `10` with a valid minimum of `0` and maximum of `100`. If a {{transform}} is already running, it has to be restarted to use the changed setting. The `num_failure_retries` setting can also be specified on an individual {{transform}} level. Specifying this setting for each {{transform}} individually is recommended. diff --git a/docs/reference/elasticsearch/configuration-reference/watcher-settings.md b/docs/reference/elasticsearch/configuration-reference/watcher-settings.md index e49ce56c38767..9d53fa55f7a58 100644 --- a/docs/reference/elasticsearch/configuration-reference/watcher-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/watcher-settings.md @@ -19,18 +19,18 @@ All of these settings can be added to the `elasticsearch.yml` configuration file ## General Watcher Settings [general-notification-settings] `xpack.watcher.enabled` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Set to `false` to disable {{watcher}} on the node. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Set to `false` to disable {{watcher}} on the node. $$$xpack-watcher-encrypt-sensitive-data$$$ `xpack.watcher.encrypt_sensitive_data` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Set to `true` to encrypt sensitive data. If this setting is enabled, you must also specify the `xpack.watcher.encryption_key` setting. For more information, see [*Encrypting sensitive data in {{watcher}}*](docs-content://explore-analyze/alerts-cases/watcher/encrypting-data.md). +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Set to `true` to encrypt sensitive data. If this setting is enabled, you must also specify the `xpack.watcher.encryption_key` setting. For more information, see [*Encrypting sensitive data in {{watcher}}*](docs-content://explore-analyze/alerts-cases/watcher/encrypting-data.md). `xpack.watcher.encryption_key` : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) Specifies the path to a file that contains a key for encrypting sensitive data. If `xpack.watcher.encrypt_sensitive_data` is set to `true`, this setting is required. For more information, see [*Encrypting sensitive data in {{watcher}}*](docs-content://explore-analyze/alerts-cases/watcher/encrypting-data.md). `xpack.watcher.max.history.record.size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The maximum size watcher history record that can be written into the watcher history index. Any larger history record will have some of its larger fields removed. Defaults to 10mb. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The maximum size watcher history record that can be written into the watcher history index. Any larger history record will have some of its larger fields removed. Defaults to 10mb. `xpack.watcher.trigger.schedule.engine` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") : Defines when the watch should start, based on date and time [Learn more](docs-content://explore-analyze/alerts-cases/watcher/schedule-types.md). @@ -39,31 +39,31 @@ $$$xpack-watcher-encrypt-sensitive-data$$$ : Controls [whether old watcher indices are automatically deleted](/reference/elasticsearch/configuration-reference/watcher-settings.md#general-notification-settings). `xpack.http.proxy.host` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the address of the proxy server to use to connect to HTTP services. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the address of the proxy server to use to connect to HTTP services. `xpack.http.proxy.port` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the port number to use to connect to the proxy server. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the port number to use to connect to the proxy server. `xpack.http.proxy.scheme` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Protocol used to communicate with the proxy server. Valid values are `http` and `https`. Defaults to the protocol used in the request. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Protocol used to communicate with the proxy server. Valid values are `http` and `https`. Defaults to the protocol used in the request. `xpack.http.default_connection_timeout` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The maximum period to wait until abortion of the request, when a connection is being initiated. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The maximum period to wait until abortion of the request, when a connection is being initiated. `xpack.http.default_read_timeout` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The maximum period of inactivity between two data packets, before the request is aborted. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The maximum period of inactivity between two data packets, before the request is aborted. `xpack.http.tcp.keep_alive` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Whether to enable TCP keepalives on HTTP connections. Defaults to `true`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Whether to enable TCP keepalives on HTTP connections. Defaults to `true`. `xpack.http.connection_pool_ttl` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The time-to-live of connections in the connection pool. If a connection is not re-used within this timeout, it is closed. By default, the time-to-live is infinite meaning that connections never expire. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The time-to-live of connections in the connection pool. If a connection is not re-used within this timeout, it is closed. By default, the time-to-live is infinite meaning that connections never expire. `xpack.http.max_response_size` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the maximum size an HTTP response is allowed to have, defaults to `10mb`, the maximum configurable value is `50mb`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the maximum size an HTTP response is allowed to have, defaults to `10mb`, the maximum configurable value is `50mb`. `xpack.http.whitelist` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) A list of URLs, that the internal HTTP client is allowed to connect to. This client is used in the HTTP input, the webhook, the slack, pagerduty, and jira actions. This setting can be updated dynamically. It defaults to `*` allowing everything. Note: If you configure this setting and you are using one of the slack/pagerduty actions, you have to ensure that the corresponding endpoints are explicitly allowed as well. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) A list of URLs, that the internal HTTP client is allowed to connect to. This client is used in the HTTP input, the webhook, the slack, pagerduty, and jira actions. This setting can be updated dynamically. It defaults to `*` allowing everything. Note: If you configure this setting and you are using one of the slack/pagerduty actions, you have to ensure that the corresponding endpoints are explicitly allowed as well. ## {{watcher}} HTTP TLS/SSL settings [ssl-notification-settings] @@ -71,7 +71,7 @@ $$$xpack-watcher-encrypt-sensitive-data$$$ You can configure the following TLS/SSL settings. `xpack.http.ssl.supported_protocols` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Supported protocols with versions. Valid protocols: `SSLv2Hello`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM’s SSL provider supports TLSv1.3, the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is `TLSv1.2,TLSv1.1`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Supported protocols with versions. Valid protocols: `SSLv2Hello`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM’s SSL provider supports TLSv1.3, the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is `TLSv1.2,TLSv1.1`. {{es}} relies on your JDK’s implementation of SSL and TLS. View [Supported SSL/TLS versions by JDK version](docs-content://deploy-manage/security/supported-ssltls-versions-by-jdk-version.md) for more information. @@ -81,7 +81,7 @@ You can configure the following TLS/SSL settings. `xpack.http.ssl.verification_mode` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Defines how to verify the certificates presented by another party in the TLS connection: +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Defines how to verify the certificates presented by another party in the TLS connection: Defaults to `full`. @@ -95,7 +95,7 @@ You can configure the following TLS/SSL settings. :::: `xpack.http.ssl.cipher_suites` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. For more information, see Oracle’s [Java Cryptography Architecture documentation](https://docs.oracle.com/en/java/javase/11/security/oracle-providers.md#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2). @@ -110,7 +110,7 @@ The following settings are used to specify a private key, certificate, and the t When using PEM encoded files, use the following settings: `xpack.http.ssl.key` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Path to a PEM encoded file containing the private key. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Path to a PEM encoded file containing the private key. If HTTP client authentication is required, it uses this file. You cannot use this setting and `ssl.keystore.path` at the same time. @@ -119,13 +119,13 @@ When using PEM encoded files, use the following settings: : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional. `xpack.http.ssl.certificate` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key. This setting can be used only if `ssl.key` is set. `xpack.http.ssl.certificate_authorities` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) List of paths to PEM encoded certificate files that should be trusted. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) List of paths to PEM encoded certificate files that should be trusted. This setting and `ssl.truststore.path` cannot be used at the same time. @@ -136,7 +136,7 @@ When using PEM encoded files, use the following settings: When using Java keystore files (JKS), which contain the private key, certificate and certificates that should be trusted, use the following settings: `xpack.http.ssl.keystore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.key` at the same time. @@ -148,7 +148,7 @@ When using Java keystore files (JKS), which contain the private key, certificate : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password for the key in the keystore. The default is the keystore password. `xpack.http.ssl.truststore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.certificate_authorities` at the same time. @@ -164,13 +164,13 @@ When using Java keystore files (JKS), which contain the private key, certificate PKCS#12 files are configured in the same way as Java keystore files: `xpack.http.ssl.keystore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore file that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.key` at the same time. `xpack.http.ssl.keystore.type` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The format of the keystore file. It must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The format of the keystore file. It must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. `xpack.http.ssl.keystore.secure_password` : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password for the keystore. @@ -179,13 +179,13 @@ PKCS#12 files are configured in the same way as Java keystore files: : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) The password for the key in the keystore. The default is the keystore password. `xpack.http.ssl.truststore.path` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `ssl.certificate_authorities` at the same time. `xpack.http.ssl.truststore.type` -: ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Set this to `PKCS12` to indicate that the truststore is a PKCS#12 file. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Set this to `PKCS12` to indicate that the truststore is a PKCS#12 file. `xpack.http.ssl.truststore.secure_password` : ([Secure](docs-content://deploy-manage/security/secure-settings.md)) Password for the truststore. @@ -197,13 +197,13 @@ PKCS#12 files are configured in the same way as Java keystore files: You can configure the following email notification settings in `elasticsearch.yml`. For more information about sending notifications via email, see [Configuring email actions](docs-content://explore-analyze/alerts-cases/watcher/actions-email.md#configuring-email-actions). `xpack.notification.email.default_account` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Default email account to use. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Default email account to use. If you configure multiple email accounts, you must either configure this setting or specify the email account to use in the [`email`](docs-content://explore-analyze/alerts-cases/watcher/actions-email.md) action. See [Configuring email accounts](docs-content://explore-analyze/alerts-cases/watcher/actions-email.md#configuring-email). `xpack.notification.email.recipient_allowlist` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Specifies addresses to which emails are allowed to be sent. Emails with recipients (`To:`, `Cc:`, or `Bcc:`) outside of these patterns will be rejected and an error thrown. This setting defaults to `["*"]` which means all recipients are allowed. Simple globbing is supported, such as `list-*@company.com` in the list of allowed recipients. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Specifies addresses to which emails are allowed to be sent. Emails with recipients (`To:`, `Cc:`, or `Bcc:`) outside of these patterns will be rejected and an error thrown. This setting defaults to `["*"]` which means all recipients are allowed. Simple globbing is supported, such as `list-*@company.com` in the list of allowed recipients. ::::{note} This setting can’t be used at the same time as `xpack.notification.email.account.domain_allowlist` and an error will be thrown if both are set at the same time. This setting can be used to specify domains to allow by using a wildcard pattern such as `*@company.com`. @@ -214,7 +214,7 @@ This setting can’t be used at the same time as `xpack.notification.email.accou : Specifies account information for sending notifications via email. You can specify the following email account attributes: `xpack.notification.email.account.domain_allowlist` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Specifies domains to which emails are allowed to be sent. Emails with recipients (`To:`, `Cc:`, or `Bcc:`) outside of these domains will be rejected and an error thrown. This setting defaults to `["*"]` which means all domains are allowed. Simple globbing is supported, such as `*.company.com` in the list of allowed domains. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Specifies domains to which emails are allowed to be sent. Emails with recipients (`To:`, `Cc:`, or `Bcc:`) outside of these domains will be rejected and an error thrown. This setting defaults to `["*"]` which means all domains are allowed. Simple globbing is supported, such as `*.company.com` in the list of allowed domains. ::::{note} This setting can’t be used at the same time as `xpack.notification.email.recipient_allowlist` and an error will be thrown if both are set at the same time. @@ -224,55 +224,55 @@ This setting can’t be used at the same time as `xpack.notification.email.recip $$$email-account-attributes$$$ `profile` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) The [email profile](docs-content://explore-analyze/alerts-cases/watcher/actions-email.md#configuring-email) to use to build the MIME messages that are sent from the account. Valid values: `standard`, `gmail` and `outlook`. Defaults to `standard`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The [email profile](docs-content://explore-analyze/alerts-cases/watcher/actions-email.md#configuring-email) to use to build the MIME messages that are sent from the account. Valid values: `standard`, `gmail` and `outlook`. Defaults to `standard`. `email_defaults.*` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) An optional set of email attributes to use as defaults for the emails sent from the account. See [Email action attributes](docs-content://explore-analyze/alerts-cases/watcher/actions-email.md#email-action-attributes) for the supported attributes. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) An optional set of email attributes to use as defaults for the emails sent from the account. See [Email action attributes](docs-content://explore-analyze/alerts-cases/watcher/actions-email.md#email-action-attributes) for the supported attributes. `smtp.auth` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Set to `true` to attempt to authenticate the user using the AUTH command. Defaults to `false`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Set to `true` to attempt to authenticate the user using the AUTH command. Defaults to `false`. `smtp.host` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) The SMTP server to connect to. Required. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The SMTP server to connect to. Required. `smtp.port` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) The SMTP server port to connect to. Defaults to 25. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The SMTP server port to connect to. Defaults to 25. `smtp.user` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) The user name for SMTP. Required. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The user name for SMTP. Required. `smtp.secure_password` : ([Secure](docs-content://deploy-manage/security/secure-settings.md), [reloadable](docs-content://deploy-manage/security/secure-settings.md#reloadable-secure-settings)) The password for the specified SMTP user. `smtp.starttls.enable` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Set to `true` to enable the use of the `STARTTLS` command (if supported by the server) to switch the connection to a TLS-protected connection before issuing any login commands. Note that an appropriate trust store must be configured so that the client will trust the server’s certificate. Defaults to `false`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Set to `true` to enable the use of the `STARTTLS` command (if supported by the server) to switch the connection to a TLS-protected connection before issuing any login commands. Note that an appropriate trust store must be configured so that the client will trust the server’s certificate. Defaults to `false`. `smtp.starttls.required` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) If `true`, then `STARTTLS` will be required. If that command fails, the connection will fail. Defaults to `false`. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) If `true`, then `STARTTLS` will be required. If that command fails, the connection will fail. Defaults to `false`. `smtp.ssl.trust` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) A list of SMTP server hosts that are assumed trusted and for which certificate verification is disabled. If set to "*", all hosts are trusted. If set to a whitespace separated list of hosts, those hosts are trusted. Otherwise, trust depends on the certificate the server presents. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) A list of SMTP server hosts that are assumed trusted and for which certificate verification is disabled. If set to "*", all hosts are trusted. If set to a whitespace separated list of hosts, those hosts are trusted. Otherwise, trust depends on the certificate the server presents. `smtp.timeout` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) The socket read timeout. Default is two minutes. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The socket read timeout. Default is two minutes. `smtp.connection_timeout` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) The socket connection timeout. Default is two minutes. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The socket connection timeout. Default is two minutes. `smtp.write_timeout` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) The socket write timeout. Default is two minutes. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) The socket write timeout. Default is two minutes. `smtp.local_address` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) A configurable local address when sending emails. Not configured by default. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) A configurable local address when sending emails. Not configured by default. `smtp.local_port` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) A configurable local port when sending emails. Not configured by default. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) A configurable local port when sending emails. Not configured by default. `smtp.send_partial` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) Send an email, despite one of the receiver addresses being invalid. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) Send an email, despite one of the receiver addresses being invalid. `smtp.wait_on_quit` -: ([Dynamic](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) If set to false the QUIT command is sent and the connection closed. If set to true, the QUIT command is sent and a reply is waited for. True by default. +: ([Dynamic](docs-content://deploy-manage/stack-settings.md#dynamic-cluster-setting)) If set to false the QUIT command is sent and the connection closed. If set to true, the QUIT command is sent and a reply is waited for. True by default. `xpack.notification.email.html.sanitization.allow` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on Elastic Cloud Hosted") : Specifies the HTML elements that are allowed in email notifications. For more information, see [Configuring HTML sanitization options](docs-content://explore-analyze/alerts-cases/watcher/actions-email.md#email-html-sanitization). You can specify individual HTML elements and the following HTML feature groups: @@ -280,36 +280,36 @@ $$$email-account-attributes$$$ $$$html-feature-groups$$$ `_tables` - : ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) All table related elements: ``, ``, ``, ``, ``, ``, and ``. + : ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) All table related elements: `
`, `
`, `
`, `
`, ``, ``, ``, ``, ``, and ``. `_blocks` - : ([Static](docs-content://deploy-manage/deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) The following block elements: `

`, `

`, `

`, `

`, `

`, `

`, `

`, `
`, `
`, `
`, `
`, `