External-Mirrors/keycloak
2
0
Fork 0
mirror of https://github.com/keycloak/keycloak.git synced 2026-01-09 23:12:06 -03:30
Code Issues Packages Projects Releases Wiki Activity

New CLI command: update-compatibility

Browse Source 
Closes #36306

Signed-off-by: Pedro Ruivo <pruivo@redhat.com>
Signed-off-by: Alexander Schwartz <aschwart@redhat.com>
Co-authored-by: Alexander Schwartz <aschwart@redhat.com>
This commit is contained in:
Pedro Ruivo 2025-01-24 15:05:58 +00:00 committed by GitHub
parent eace63043d
commit 588e60e058
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
27 changed files with 2737 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/guides/server/pinned-guides
View File

@ -19,4 +19,5 @@ management-interface
importExport
vault
all-config
all-provider-config
all-provider-config
update-compatibility

129
docs/guides/server/update-compatibility.adoc Normal file
View File

@ -0,0 +1,129 @@
<#import "/templates/guide.adoc" as tmpl>
<#import "/templates/kc.adoc" as kc>
<#import "/templates/links.adoc" as links>
<@tmpl.guide
title="Update Compatibility Tool"
summary="Learn how to use this tool before upgrade {project_name}"
preview="true"
previewDiscussionLink="https://github.com/keycloak/keycloak/discussions/36785"
>
// TODO Link to discussion?
The goal of this tool is to assist with modifying a {project_name} deployment, whether upgrading to a new version, enabling/disabling features, or changing configuration.
The outcome will indicate whether a rolling upgrade is possible or if a recreate upgrade is required.
This has been designed to be fully scriptable, so an update procedure can adapt to a rolling or recreate strategy depending on the configuration or version change.
It is also GitOps friendly as it allows storing the metadata of a currently running configuration in a file. This file can be used in a CI/CD run with the new configuration to determine if a rolling upgrade is possible or if a recreate upgrade is needed.
[NOTE]
====
.Rolling Upgrade
In the context of this guide, a rolling upgrade is an upgrade that can be performed with zero downtime for your deployment.
Your {project_name} nodes must be updated one by one; in other words, shut down one of your old deployment nodes and start a new deployment node.
Wait until the new node's start-up probe returns success before proceeding to the next {project_name} node. See {section} <@links.observability id="health"/> for details on how to enable and use the start-up probe.
====
[NOTE]
====
.Recreate Upgrade
A recreate upgrade is not compatible with zero-downtime and requires downtime to be applied.
Shut down all nodes of the cluster running the old version before starting the nodes with the new version.
====
The update compatibility tool involves two steps:
1. Generating the required metadata.
2. Checking the metadata to determine the possible upgrade type.
[WARNING]
====
This command is under development. At the moment, it takes into consideration only the version of {project_name} and the embedded Infinispan to determine if a rolling update is possible.
If those are unchanged, it reports that a rolling update is possible.
The current version does not yet verify configuration changes and assumes all configuration changes are eligible for a rolling update.
The same applies to changes to custom extensions and themes.
A good use case when to use this is, for example, when you want to do a rolling update when you change the {project_name} theme or your custom extensions, and only want run recreate update when the version of {project_name} changes which does not yet allow a rolling update.
While consumers of these commands should be aware of the limitations that exist today, they should not rely on the internal behavior or the structure of the metadata file as this is about to be enhanced in future versions.
Instead, they should rely only on the exit code of the `check` command to benefit from future enhancements on the internal logic to determine when a rolling update is possible.
====
== Generating the Metadata
To generate the metadata, execute the following command using the same {project_name} version and configuration options:
.Generate and save the metadata from the current deployment.
<@kc.updatecompatibility parameters="metadata --file=/path/to/file.json"/>
This command accepts all options used by the `start` command.
The metadata, in JSON format, is displayed in the console for debugging purposes.
The `--file` parameter allows you to save the metadata to a file.
This file is then used by the subsequent `check` command.
[WARNING]
====
Ensure that all configuration options, whether set via environment variables or CLI arguments, are included when running the above command.
Omitting any configuration options will result in incomplete metadata.
====
== Checking the Metadata
This command checks the metadata generated by the previous command and compares it with the current configuration and {project_name} version.
If you are upgrading to a new {project_name} version, this command must be executed with the new version.
.Check the metadata from a previous deployment.
<@kc.updatecompatibility parameters="check --file=/path/to/file.json"/>
[WARNING]
====
* Ensure that all configuration options, whether set via environment variables or CLI arguments, are included when running this command.
* Verify that the correct {project_name} version is used.
Failure to meet these requirements will result in an incorrect outcome.
====
The command will print the result to the console.
For example, if a rolling upgrade is possible, it will display:
.Rolling Upgrade possible message
[source,bash]
----
[OK] Rolling Upgrade is available.
----
Otherwise, the command will indicate that a rolling upgrade is not possible and, optionally, provide details about the incompatibility:
.Rolling Upgrade not possible message
[source,bash]
----
[Versions] Rolling Upgrade is not available. 'infinispan' is incompatible: Old=15.0.0.Final, New=15.0.11.Final #<1>
----
<1> In this example, the Infinispan version `15.0.0.Final` is not compatible with version `15.0.11.Final` and a rolling upgrade is not possible.
*Command exit code*
To aid in the development of your automation and/or DevOps pipelines, the command's exit code can be used to determine the upgrade type:
|===
|Exit Code |Description
m|0
|Rolling Upgrade is possible.
m|1
|Unexpected error occurred (e.g., the metadata file is missing or corrupted).
m|2
|Invalid CLI option.
m|3
|Rolling Upgrade is not possible.
The deployment must be shut down before applying the new configuration.
|===
</@tmpl.guide>

7
docs/guides/templates/kc.adoc
View File

@ -46,3 +46,10 @@ bin/kc.[sh|bat] import ${parameters}
bin/kc.[sh|bat] bootstrap-admin ${parameters}
----
</#macro>
<#macro updatecompatibility parameters>
[source,bash]
----
bin/kc.[sh|bat] update-compatibility ${parameters}
----
</#macro>

59
quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/Picocli.java
View File

@ -38,14 +38,12 @@ import java.util.ArrayList;
import java.util.Arrays;
import java.util.EnumMap;
import java.util.HashSet;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import java.util.Properties;
import java.util.Set;
import java.util.function.BiConsumer;
import java.util.function.Consumer;
import java.util.function.Function;
import java.util.stream.Collectors;
@ -63,6 +61,7 @@ import org.keycloak.quarkus.runtime.cli.command.Completion;
import org.keycloak.quarkus.runtime.cli.command.Main;
import org.keycloak.quarkus.runtime.cli.command.ShowConfig;
import org.keycloak.quarkus.runtime.cli.command.StartDev;
import org.keycloak.quarkus.runtime.cli.command.UpdateCompatibility;
import org.keycloak.quarkus.runtime.configuration.ConfigArgsConfigSource;
import org.keycloak.quarkus.runtime.configuration.Configuration;
import org.keycloak.quarkus.runtime.configuration.DisabledMappersInterceptor;
@ -102,9 +101,9 @@ public class Picocli {
boolean includeBuildTime;
}
private ExecutionExceptionHandler errorHandler = new ExecutionExceptionHandler();
private final ExecutionExceptionHandler errorHandler = new ExecutionExceptionHandler();
private Set<PropertyMapper<?>> allowedMappers;
private List<String> unrecognizedArgs = new ArrayList<>();
private final List<String> unrecognizedArgs = new ArrayList<>();
public void parseAndRun(List<String> cliArgs) {
// perform two passes over the cli args. First without option validation to determine the current command, then with option validation enabled
@ -255,7 +254,8 @@ public class Picocli {
|| cliArgs.contains("--help-all")
|| currentCommandName.equals(Build.NAME)
|| currentCommandName.equals(ShowConfig.NAME)
|| currentCommandName.equals(Completion.NAME);
|| currentCommandName.equals(Completion.NAME)
|| currentCommandName.equals(UpdateCompatibility.NAME);
}
private static boolean requiresReAugmentation(CommandLine cmdCommand) {
@ -280,18 +280,13 @@ public class Picocli {
private static List<String> getSanitizedRuntimeCliOptions() {
List<String> properties = new ArrayList<>();
parseConfigArgs(ConfigArgsConfigSource.getAllCliArgs(), new BiConsumer<String, String>() {
@Override
public void accept(String key, String value) {
PropertyMapper<?> mapper = PropertyMappers.getMapper(key);
parseConfigArgs(ConfigArgsConfigSource.getAllCliArgs(), (key, value) -> {
PropertyMapper<?> mapper = PropertyMappers.getMapper(key);
if (mapper == null || mapper.isRunTime()) {
properties.add(key + "=" + maskValue(key, value));
}
if (mapper == null || mapper.isRunTime()) {
properties.add(key + "=" + maskValue(key, value));
}
}, arg -> {
properties.add(arg);
});
}, properties::add);
return properties;
}
@ -429,10 +424,8 @@ public class Picocli {
mapper.validate(configValue);
mapper.getDeprecatedMetadata().ifPresent(metadata -> {
handleDeprecated(deprecatedInUse, mapper, configValueStr, metadata);
});
});;
mapper.getDeprecatedMetadata().ifPresent(metadata -> handleDeprecated(deprecatedInUse, mapper, configValueStr, metadata));
});
}
}
@ -761,12 +754,7 @@ public class Picocli {
OptionSpec.Builder optBuilder = OptionSpec.builder(name)
.description(getDecoratedOptionDescription(mapper))
.paramLabel(mapper.getParamLabel())
.completionCandidates(new Iterable<String>() {
@Override
public Iterator<String> iterator() {
return mapper.getExpectedValues().iterator();
}
})
.completionCandidates(() -> mapper.getExpectedValues().iterator())
.hidden(mapper.isHidden());
if (mapper.getDefaultValue().isPresent()) {
@ -910,17 +898,18 @@ public class Picocli {
}
});
if (options.length() > 0) {
out.println(
Ansi.AUTO.string(
new StringBuilder("@|bold,red ")
.append("The previous optimized build will be overridden with the following build options:")
.append(options)
.append("\nTo avoid that, run the 'build' command again and then start the optimized server instance using the '--optimized' flag.")
.append("|@").toString()
)
);
if (options.isEmpty()) {
return;
}
out.println(
Ansi.AUTO.string(
new StringBuilder("@|bold,red ")
.append("The previous optimized build will be overridden with the following build options:")
.append(options)
.append("\nTo avoid that, run the 'build' command again and then start the optimized server instance using the '--optimized' flag.")
.append("|@").toString()
)
);
}
private static void optionChanged(StringBuilder options, String key, String oldValue, String newValue) {

17
quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/ShortErrorMessageHandler.java
View File

@ -32,9 +32,7 @@ public class ShortErrorMessageHandler implements IParameterExceptionHandler {
String errorMessage = ex.getMessage();
String additionalSuggestion = null;
if (ex instanceof UnmatchedArgumentException) {
UnmatchedArgumentException uae = (UnmatchedArgumentException) ex;
if (ex instanceof UnmatchedArgumentException uae) {
String[] unmatched = getUnmatchedPartsByOptionSeparator(uae, "=");
String cliKey = unmatched[0];
@ -72,12 +70,10 @@ public class ShortErrorMessageHandler implements IParameterExceptionHandler {
}
}
}
} else if (ex instanceof MissingParameterException) {
MissingParameterException mpe = (MissingParameterException)ex;
} else if (ex instanceof MissingParameterException mpe) {
if (mpe.getMissing().size() == 1) {
ArgSpec spec = mpe.getMissing().get(0);
if (spec instanceof OptionSpec) {
OptionSpec option = (OptionSpec)spec;
if (spec instanceof OptionSpec option) {
errorMessage = getExpectedMessage(option);
}
}
@ -126,8 +122,11 @@ public class ShortErrorMessageHandler implements IParameterExceptionHandler {
}
public static String getExpectedValuesMessage(Iterable<String> specCandidates, boolean caseInsensitive) {
return specCandidates.iterator().hasNext() ? String.format(" Expected values are%s: %s",
caseInsensitive ? " (case insensitive)" : "", String.join(", ", specCandidates)) : "";
if (specCandidates == null || !specCandidates.iterator().hasNext()) {
return "";
}
return String.format(" Expected values are%s: %s", caseInsensitive ? " (case insensitive)" : "",
String.join(", ", specCandidates));
}
}

83
quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/command/AbstractUpdatesCommand.java Normal file
View File

@ -0,0 +1,83 @@
/*
* Copyright 2025 Red Hat, Inc. and/or its affiliates
* and other contributors as indicated by the @author tags.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.keycloak.quarkus.runtime.cli.command;
import java.io.File;
import java.util.List;
import java.util.function.Predicate;
import org.keycloak.config.OptionCategory;
import org.keycloak.quarkus.runtime.cli.PropertyException;
import org.keycloak.quarkus.runtime.compatibility.CompatibilityManager;
import org.keycloak.quarkus.runtime.compatibility.CompatibilityManagerImpl;
import picocli.CommandLine;
public abstract class AbstractUpdatesCommand extends AbstractCommand implements Runnable {
protected final CompatibilityManager compatibilityManager = new CompatibilityManagerImpl();
@CommandLine.Mixin
HelpAllMixin helpAllMixin;
@CommandLine.Mixin
OptimizedMixin optimizedMixin;
@Override
public List<OptionCategory> getOptionCategories() {
return super.getOptionCategories().stream()
.filter(Predicate.not(OptionCategory.EXPORT::equals))
.filter(Predicate.not(OptionCategory.IMPORT::equals))
.toList();
}
static void validateOptionIsPresent(String value, String option) {
if (value == null || value.isBlank()) {
throw new PropertyException("Missing required argument: " + option);
}
}
static void validateFileIsNotDirectory(File file, String option) {
if (file.isDirectory()) {
throw new PropertyException("Incorrect argument %s. Path '%s' is not a valid file.".formatted(option, file.getAbsolutePath()));
}
}
void printOut(String message) {
var cmd = getCommandLine();
if (cmd.isPresent()) {
cmd.get().getOut().println(message);
} else {
System.out.println(message);
}
}
void printError(String message) {
var cmd = getCommandLine();
if (cmd.isPresent()) {
var colorScheme = cmd.get().getColorScheme();
cmd.get().getErr().println(colorScheme.errorText(message));
} else {
System.err.println(message);
}
}
void printPreviewWarning() {
printError("Warning! This command is preview and is not recommended for use in production. It may change or be removed at a future release.");
}
}

5
quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/command/Main.java
View File

@ -67,7 +67,8 @@ import java.nio.file.Path;
Import.class,
ShowConfig.class,
Tools.class,
BootstrapAdmin.class
BootstrapAdmin.class,
UpdateCompatibility.class
})
public final class Main {
@ -111,4 +112,4 @@ public final class Main {
}
System.setProperty(KeycloakPropertiesConfigSource.KEYCLOAK_CONFIG_FILE_PROP, path);
}
}
}

32
quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/command/UpdateCompatibility.java Normal file
View File

@ -0,0 +1,32 @@
/*
* Copyright 2025 Red Hat, Inc. and/or its affiliates
* and other contributors as indicated by the @author tags.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.keycloak.quarkus.runtime.cli.command;
import picocli.CommandLine;
@CommandLine.Command(
name = UpdateCompatibility.NAME,
description = "[Preview] Tool for configuration compatibility.",
subcommands = {
UpdateCompatibilityCheck.class,
UpdateCompatibilityMetadata.class
})
public final class UpdateCompatibility {
public static final String NAME = "update-compatibility";
}

86
quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/command/UpdateCompatibilityCheck.java Normal file
View File

@ -0,0 +1,86 @@
/*
* Copyright 2025 Red Hat, Inc. and/or its affiliates
* and other contributors as indicated by the @author tags.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.keycloak.quarkus.runtime.cli.command;
import java.io.File;
import java.io.IOException;
import org.keycloak.quarkus.runtime.cli.PropertyException;
import org.keycloak.quarkus.runtime.compatibility.ServerInfo;
import org.keycloak.util.JsonSerialization;
import picocli.CommandLine;
@CommandLine.Command(
name = UpdateCompatibilityCheck.NAME,
description = "Checks if the metadata is compatible with the current configuration. A zero exit code means a rolling upgrade is possible between old and the current metadata."
)
public class UpdateCompatibilityCheck extends AbstractUpdatesCommand {
public static final String NAME = "check";
public static final String INPUT_OPTION_NAME = "--file";
@CommandLine.Option(names = {INPUT_OPTION_NAME}, paramLabel = "FILE",
description = "The file path to read the metadata.")
String inputFile;
@Override
public void run() {
printPreviewWarning();
validateConfig();
var info = readServerInfo();
var result = compatibilityManager.isCompatible(info);
result.errorMessage().ifPresent(this::printError);
result.endMessage().ifPresent(this::printOut);
picocli.exit(result.exitCode());
}
@Override
public String getName() {
return NAME;
}
@Override
public boolean includeRuntime() {
return true;
}
@Override
protected void validateConfig() {
super.validateConfig();
validateFileParameter();
}
private void validateFileParameter() {
validateOptionIsPresent(inputFile, INPUT_OPTION_NAME);
var file = new File(inputFile);
if (!file.exists()) {
throw new PropertyException("Incorrect argument %s. Path '%s' not found".formatted(INPUT_OPTION_NAME, file.getAbsolutePath()));
}
validateFileIsNotDirectory(file, INPUT_OPTION_NAME);
}
private ServerInfo readServerInfo() {
var file = new File(inputFile);
try {
return JsonSerialization.mapper.readValue(file, ServerInfo.class);
} catch (IOException e) {
throw new PropertyException("Unable to read file '%s'".formatted(file.getAbsolutePath()), e);
}
}
}

102
quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/command/UpdateCompatibilityMetadata.java Normal file
View File

@ -0,0 +1,102 @@
/*
* Copyright 2025 Red Hat, Inc. and/or its affiliates
* and other contributors as indicated by the @author tags.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.keycloak.quarkus.runtime.cli.command;
import java.io.File;
import java.io.IOException;
import com.fasterxml.jackson.core.JsonProcessingException;
import org.keycloak.quarkus.runtime.cli.PropertyException;
import org.keycloak.quarkus.runtime.compatibility.ServerInfo;
import org.keycloak.util.JsonSerialization;
import picocli.CommandLine;
@CommandLine.Command(
name = UpdateCompatibilityMetadata.NAME,
description = "Stores the metadata necessary to determine if a configuration is compatible."
)
public class UpdateCompatibilityMetadata extends AbstractUpdatesCommand {
public static final String NAME = "metadata";
public static final String OUTPUT_OPTION_NAME = "--file";
@CommandLine.Option(names = {OUTPUT_OPTION_NAME}, paramLabel = "FILE",
description = "The file path to store the metadata. It is stored in the JSON format.")
String outputFile;
@Override
public void run() {
printPreviewWarning();
validateConfig();
var info = compatibilityManager.current();
printToConsole(info);
writeToFile(info);
}
@Override
public String getName() {
return NAME;
}
@Override
public boolean includeRuntime() {
return true;
}
@Override
protected void validateConfig() {
super.validateConfig();
validateFileParameter();
}
private void validateFileParameter() {
if (noOutputFileSet()) {
return;
}
var file = new File(outputFile);
if (file.getParentFile() != null && !file.getParentFile().exists() && !file.getParentFile().mkdirs()) {
throw new PropertyException("Incorrect argument %s. Unable to create parent directory: %s".formatted(OUTPUT_OPTION_NAME, file.getParentFile().getAbsolutePath()));
}
validateFileIsNotDirectory(file, OUTPUT_OPTION_NAME);
}
private void printToConsole(ServerInfo info) {
try {
var json = JsonSerialization.mapper.writerWithDefaultPrettyPrinter().writeValueAsString(info);
printOut("Metadata:%n%s".formatted(json));
} catch (JsonProcessingException e) {
throw new PropertyException("Unable to create JSON representation of the metadata", e);
}
}
private void writeToFile(ServerInfo info) {
if (noOutputFileSet()) {
return;
}
var file = new File(outputFile);
try {
JsonSerialization.mapper.writeValue(file, info);
} catch (IOException e) {
throw new PropertyException("Unable to write file '%s'".formatted(file.getAbsolutePath()), e);
}
}
private boolean noOutputFileSet() {
return outputFile == null || outputFile.isBlank();
}
}

43
quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/compatibility/CompatibilityComparator.java Normal file
View File

@ -0,0 +1,43 @@
/*
* Copyright 2025 Red Hat, Inc. and/or its affiliates
* and other contributors as indicated by the @author tags.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.keycloak.quarkus.runtime.compatibility;
import java.util.Objects;
/**
* A comparator interface for configuration metadata entries.
* <p>
* An entry's old and new values are compatible if a Keycloak instance using the old value can make progress (and be
* correct) with a Keycloak instance using the new value.
*/
public interface CompatibilityComparator {
CompatibilityComparator EQUALS = (ignored, oldValue, newValue) -> Objects.equals(oldValue, newValue);
/**
* Checks if the metadata entry identified by the {@code key} parameter is compatible.
*
* @param key The metadata entry key.
* @param oldValue The metadata entry's old value.
* @param newValue The metadata entry's new value.
* @return {@code true} if the {@code oldValue} is backwards compatible with the {@code newValue} and {@code false}
* otherwise.
*/
boolean isCompatible(String key, String oldValue, String newValue);
}

50
quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/compatibility/CompatibilityManager.java Normal file
View File

@ -0,0 +1,50 @@
/*
* Copyright 2025 Red Hat, Inc. and/or its affiliates
* and other contributors as indicated by the @author tags.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.keycloak.quarkus.runtime.compatibility;
/**
* This interface manages the metadata for backwards compatibility checks.
*/
public interface CompatibilityManager {
/**
* @return The current metadata.
*/
ServerInfo current();
/**
* Adds a custom {@link CompatibilityComparator} to the version identified by {@code versionKey}.
*
* @param versionKey The version identification.
* @param comparator The new {@link CompatibilityComparator}. If {@code null}, this method will do nothing.
* @return This instance.
*/
CompatibilityManager addVersionComparator(String versionKey, CompatibilityComparator comparator);
/**
* Checks if the metadata is backwards compatible with the current metadata.
* <p>
* If a server's metadata is backwards compatible, it means that Keycloak can have server instances associated with
* the old and current metadata running in the same cluster.
*
* @param other The other metadata.
* @return The {@link CompatibilityResult} with the result of comparing the current with the {@code other} metadata.
*/
CompatibilityResult isCompatible(ServerInfo other);
}

82
quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/compatibility/CompatibilityManagerImpl.java Normal file
View File

@ -0,0 +1,82 @@
/*
* Copyright 2025 Red Hat, Inc. and/or its affiliates
* and other contributors as indicated by the @author tags.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.keycloak.quarkus.runtime.compatibility;
import java.util.HashMap;
import java.util.Map;
import java.util.stream.Collectors;
import java.util.stream.Stream;
import org.keycloak.common.Version;
/**
* The default implementation of {@link CompatibilityManager}.
* <p>
* This implementation uses equality by default. If the metadata represented by {@link ServerInfo} is different, the
* configuration is not backwards compatible. It supports installing customer {@link CompatibilityComparator} for
* different metadata entries.
*/
public class CompatibilityManagerImpl implements CompatibilityManager {
private final Map<String, CompatibilityComparator> versionComparators = new HashMap<>();
public static final String KEYCLOAK_VERSION_KEY = "keycloak";
public static final String INFINISPAN_VERSION_KEY = "infinispan";
@Override
public ServerInfo current() {
var info = new ServerInfo();
addVersions(info);
return info;
}
@Override
public CompatibilityManager addVersionComparator(String versionKey, CompatibilityComparator comparator) {
if (comparator != null) {
versionComparators.put(versionKey, comparator);
}
return this;
}
private static void addVersions(ServerInfo info) {
info.addVersion(KEYCLOAK_VERSION_KEY, Version.VERSION);
info.addVersion(INFINISPAN_VERSION_KEY, org.infinispan.commons.util.Version.getVersion());
}
@Override
public CompatibilityResult isCompatible(ServerInfo other) {
var current = current();
return compareVersions(current, other);
}
private CompatibilityResult compareVersions(ServerInfo current, ServerInfo other) {
var allKeys = Stream.concat(
current.getVersions().keySet().stream(),
other.getVersions().keySet().stream()
).collect(Collectors.toSet());
for (var key : allKeys) {
var comparator = versionComparators.getOrDefault(key, CompatibilityComparator.EQUALS);
var oldVersion = other.getVersions().get(key);
var newVersion = current.getVersions().get(key);
if (comparator.isCompatible(key, oldVersion, newVersion)) {
continue;
}
return new IncompatibleResult("Versions", key, oldVersion, newVersion);
}
return CompatibilityResult.OK;
}
}

67
quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/compatibility/CompatibilityResult.java Normal file
View File

@ -0,0 +1,67 @@
/*
* Copyright 2025 Red Hat, Inc. and/or its affiliates
* and other contributors as indicated by the @author tags.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.keycloak.quarkus.runtime.compatibility;
import java.util.Optional;
/**
* The result of {@link CompatibilityManager#isCompatible(ServerInfo)}.
* <p>
* It is composed by the exit code (to help building scripts around this tool as is is easier than parsing logs), and an
* optional error message.
*/
public interface CompatibilityResult {
int ROLLING_UPGRADE_EXIT_CODE = 0;
int RECREATE_UPGRADE_EXIT_CODE = 4;
/**
* The compatible {@link CompatibilityResult} implementation
*/
CompatibilityResult OK = new CompatibilityResult() {
@Override
public int exitCode() {
return ROLLING_UPGRADE_EXIT_CODE;
}
@Override
public Optional<String> endMessage() {
return Optional.of("[OK] Rolling Upgrade is available.");
}
};
/**
* @return The exit code to use to signal the compatibility result.
*/
int exitCode();
/**
* @return An optional error message explaining what caused the incompatibility.
*/
default Optional<String> errorMessage() {
return Optional.empty();
}
/**
* @return An optional message after the check is finished.
*/
default Optional<String> endMessage() {
return Optional.empty();
}
}

42
quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/compatibility/IncompatibleResult.java Normal file
View File

@ -0,0 +1,42 @@
/*
* Copyright 2025 Red Hat, Inc. and/or its affiliates
* and other contributors as indicated by the @author tags.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.keycloak.quarkus.runtime.compatibility;
import java.util.Optional;
/**
* A generic {@link CompatibilityResult} implementation to signal an incompatible configuration.
* <p>
* It returns an error message logging the metadata entry that is no compatible and its values.
*
* @param type The group where the metadata entry belongs (versions, cli options, features or other).
* @param key The metadata entry's key.
* @param oldValue The metadata entry's old value.
* @param newValue The metadata entry's new value.
*/
public record IncompatibleResult(String type, String key, String oldValue, String newValue) implements CompatibilityResult {
@Override
public int exitCode() {
return CompatibilityResult.RECREATE_UPGRADE_EXIT_CODE;
}
@Override
public Optional<String> errorMessage() {
return Optional.of("[%s] Rolling Upgrade is not available. '%s' is incompatible: Old=%s, New=%s".formatted(type, key, oldValue, newValue));
}
}

50
quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/compatibility/ServerInfo.java Normal file
View File

@ -0,0 +1,50 @@
/*
* Copyright 2025 Red Hat, Inc. and/or its affiliates
* and other contributors as indicated by the @author tags.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.keycloak.quarkus.runtime.compatibility;
import java.util.HashMap;
import java.util.Map;
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* The required metadata to detect incompatibilities between different configurations.
*/
public class ServerInfo {
/**
* Keycloak and other relevant dependencies versions.
*/
@JsonProperty("versions")
private Map<String, String> versions = new HashMap<>();
public Map<String, String> getVersions() {
return versions;
}
public void setVersions(Map<String, String> versions) {
this.versions = versions == null ? new HashMap<>() : versions;
}
public void addVersion(String key, String version) {
if (versions == null) {
versions = new HashMap<>();
}
versions.put(key, version);
}
}

33
quarkus/tests/integration/src/test/java/org/keycloak/it/cli/dist/HelpCommandDistTest.java vendored
View File

@ -42,6 +42,9 @@ import org.keycloak.quarkus.runtime.cli.command.Start;
import org.keycloak.quarkus.runtime.cli.command.StartDev;
import io.quarkus.test.junit.main.Launch;
import org.keycloak.quarkus.runtime.cli.command.UpdateCompatibility;
import org.keycloak.quarkus.runtime.cli.command.UpdateCompatibilityCheck;
import org.keycloak.quarkus.runtime.cli.command.UpdateCompatibilityMetadata;
@DistributionTest
@RawDistOnly(reason = "Verifying the help message output doesn't need long spin-up of docker dist tests.")
@ -133,6 +136,36 @@ public class HelpCommandDistTest {
assertHelp(cliResult);
}
@Test
@Launch({ UpdateCompatibility.NAME, "--help" })
void testUpdateCompatibilityHelp(CLIResult cliResult) {
assertHelp(cliResult);
}
@Test
@Launch({ UpdateCompatibility.NAME, UpdateCompatibilityMetadata.NAME, "--help" })
void testUpdateCompatibilityMetadataHelp(CLIResult cliResult) {
assertHelp(cliResult);
}
@Test
@Launch({ UpdateCompatibility.NAME, UpdateCompatibilityMetadata.NAME, "--help-all" })
void testUpdateCompatibilityMetadataHelpAll(CLIResult cliResult) {
assertHelp(cliResult);
}
@Test
@Launch({ UpdateCompatibility.NAME, UpdateCompatibilityCheck.NAME, "--help" })
void testUpdateCompatibilityCheckHelp(CLIResult cliResult) {
assertHelp(cliResult);
}
@Test
@Launch({ UpdateCompatibility.NAME, UpdateCompatibilityCheck.NAME, "--help-all" })
void testUpdateCompatibilityCheckHelpAll(CLIResult cliResult) {
assertHelp(cliResult);
}
@Test
public void testHelpDoesNotStartReAugJvm(KeycloakDistribution dist) {
for (String helpCmd : List.of("-h", "--help", "--help-all")) {

107
quarkus/tests/integration/src/test/java/org/keycloak/it/cli/dist/UpdateCommandDistTest.java vendored Normal file
View File

@ -0,0 +1,107 @@
/*
* Copyright 2025 Red Hat, Inc. and/or its affiliates
* and other contributors as indicated by the @author tags.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.keycloak.it.cli.dist;
import java.io.File;
import java.io.IOException;
import java.util.Map;
import io.quarkus.test.junit.main.Launch;
import org.junit.jupiter.api.Test;
import org.keycloak.common.Version;
import org.keycloak.it.junit5.extension.CLIResult;
import org.keycloak.it.junit5.extension.DistributionTest;
import org.keycloak.it.junit5.extension.RawDistOnly;
import org.keycloak.it.utils.KeycloakDistribution;
import org.keycloak.quarkus.runtime.cli.command.UpdateCompatibility;
import org.keycloak.quarkus.runtime.cli.command.UpdateCompatibilityCheck;
import org.keycloak.quarkus.runtime.cli.command.UpdateCompatibilityMetadata;
import org.keycloak.quarkus.runtime.compatibility.CompatibilityManagerImpl;
import org.keycloak.quarkus.runtime.compatibility.ServerInfo;
import org.keycloak.util.JsonSerialization;
import static org.junit.jupiter.api.Assertions.assertEquals;
@DistributionTest
@RawDistOnly(reason = "Requires creating JSON file to be available between containers")
public class UpdateCommandDistTest {
@Test
@Launch({UpdateCompatibility.NAME})
public void testMissingSubCommand(CLIResult cliResult) {
cliResult.assertError("Missing required subcommand");
}
@Test
@Launch({UpdateCompatibility.NAME, UpdateCompatibilityMetadata.NAME})
public void testMissingOptionOnSave(CLIResult cliResult) {
cliResult.assertNoMessage("Missing required argument");
}
@Test
@Launch({UpdateCompatibility.NAME, UpdateCompatibilityCheck.NAME})
public void testMissingOptionOnCheck(CLIResult cliResult) {
cliResult.assertError("Missing required argument: " + UpdateCompatibilityCheck.INPUT_OPTION_NAME);
}
@Test
public void testCompatible(KeycloakDistribution distribution) throws IOException {
var jsonFile = createTempFile("compatible");
var result = distribution.run(UpdateCompatibility.NAME, UpdateCompatibilityMetadata.NAME, UpdateCompatibilityMetadata.OUTPUT_OPTION_NAME, jsonFile.getAbsolutePath());
result.assertMessage("Metadata:");
assertEquals(0, result.exitCode());
var info = JsonSerialization.mapper.readValue(jsonFile, ServerInfo.class);
assertEquals(Version.VERSION, info.getVersions().get(CompatibilityManagerImpl.KEYCLOAK_VERSION_KEY));
assertEquals(org.infinispan.commons.util.Version.getVersion(), info.getVersions().get(CompatibilityManagerImpl.INFINISPAN_VERSION_KEY));
result = distribution.run(UpdateCompatibility.NAME, UpdateCompatibilityCheck.NAME, UpdateCompatibilityCheck.INPUT_OPTION_NAME, jsonFile.getAbsolutePath());
result.assertMessage("[OK] Rolling Upgrade is available.");
result.assertNoError("Rolling Upgrade is not available.");
}
@Test
public void testWrongVersions(KeycloakDistribution distribution) throws IOException {
var jsonFile = createTempFile("wrong-versions");
// incompatible keycloak version
var info = new ServerInfo();
info.setVersions(Map.of(CompatibilityManagerImpl.KEYCLOAK_VERSION_KEY, "0.0.0.Final",
CompatibilityManagerImpl.INFINISPAN_VERSION_KEY, org.infinispan.commons.util.Version.getVersion()));
JsonSerialization.mapper.writeValue(jsonFile, info);
var result = distribution.run(UpdateCompatibility.NAME, UpdateCompatibilityCheck.NAME, UpdateCompatibilityCheck.INPUT_OPTION_NAME, jsonFile.getAbsolutePath());
result.assertError("[Versions] Rolling Upgrade is not available. 'keycloak' is incompatible: Old=0.0.0.Final, New=%s".formatted(Version.VERSION));
// incompatible infinispan version
info.setVersions(Map.of(
CompatibilityManagerImpl.KEYCLOAK_VERSION_KEY, Version.VERSION,
CompatibilityManagerImpl.INFINISPAN_VERSION_KEY, "0.0.0.Final"));
JsonSerialization.mapper.writeValue(jsonFile, info);
result = distribution.run(UpdateCompatibility.NAME, UpdateCompatibilityCheck.NAME, UpdateCompatibilityCheck.INPUT_OPTION_NAME, jsonFile.getAbsolutePath());
result.assertError("[Versions] Rolling Upgrade is not available. 'infinispan' is incompatible: Old=0.0.0.Final, New=%s".formatted(org.infinispan.commons.util.Version.getVersion()));
}
private static File createTempFile(String prefix) throws IOException {
var file = File.createTempFile(prefix, ".json");
file.deleteOnExit();
return file;
}
}

9
quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testDefaultToHelp.approved.txt vendored
View File

@ -30,6 +30,13 @@ Commands:
bootstrap-admin Commands for bootstrapping admin access
user Add an admin user with a password
service Add an admin service account
update-compatibility [Preview] Tool for configuration compatibility.
check Checks if the metadata is compatible with the current
configuration. A zero exit code means a rolling
upgrade is possible between old and the current
metadata.
metadata Stores the metadata necessary to determine if a
configuration is compatible.
Examples:
@ -53,4 +60,4 @@ Examples:
production.
Use "kc.sh start --help" for the available options when starting the server.
Use "kc.sh <command> --help" for more information about other commands.
Use "kc.sh <command> --help" for more information about other commands.

9
quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testHelp.approved.txt vendored
View File

@ -30,6 +30,13 @@ Commands:
bootstrap-admin Commands for bootstrapping admin access
user Add an admin user with a password
service Add an admin service account
update-compatibility [Preview] Tool for configuration compatibility.
check Checks if the metadata is compatible with the current
configuration. A zero exit code means a rolling
upgrade is possible between old and the current
metadata.
metadata Stores the metadata necessary to determine if a
configuration is compatible.
Examples:
@ -53,4 +60,4 @@ Examples:
production.
Use "kc.sh start --help" for the available options when starting the server.
Use "kc.sh <command> --help" for more information about other commands.
Use "kc.sh <command> --help" for more information about other commands.

9
quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testHelpShort.approved.txt vendored
View File

@ -30,6 +30,13 @@ Commands:
bootstrap-admin Commands for bootstrapping admin access
user Add an admin user with a password
service Add an admin service account
update-compatibility [Preview] Tool for configuration compatibility.
check Checks if the metadata is compatible with the current
configuration. A zero exit code means a rolling
upgrade is possible between old and the current
metadata.
metadata Stores the metadata necessary to determine if a
configuration is compatible.
Examples:
@ -53,4 +60,4 @@ Examples:
production.
Use "kc.sh start --help" for the available options when starting the server.
Use "kc.sh <command> --help" for more information about other commands.
Use "kc.sh <command> --help" for more information about other commands.

367
quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testUpdateCompatibilityCheckHelp.approved.txt vendored Normal file
View File

@ -0,0 +1,367 @@
Usage:
kc.sh update-compatibility check [OPTIONS]
Checks if the metadata is compatible with the current configuration. A zero
exit code means a rolling upgrade is possible between old and the current
metadata.
Options:
--file <FILE> The file path to read the metadata.
-h, --help This help message.
--help-all This same help message but with additional options.
--optimized Use this option to achieve an optimal startup time if you have previously
built a server image using the 'build' command.
-v, --verbose Print out error details when running this command.
Cache:
--cache <type> Defines the cache mechanism for high-availability. By default in production
mode, a 'ispn' cache is used to create a cluster between multiple server
nodes. By default in development mode, a 'local' cache disables clustering
and is intended for development and testing purposes. Possible values are:
ispn, local. Default: ispn.
--cache-config-file <file>
Defines the file from which cache configuration should be loaded from. The
configuration file is relative to the 'conf/' directory.
--cache-embedded-authorization-max-count <max-count>
The maximum number of entries that can be stored in-memory by the
authorization cache.
--cache-embedded-client-sessions-max-count <max-count>
The maximum number of entries that can be stored in-memory by the
clientSessions cache. Available only when embedded Infinispan clusters
configured.
--cache-embedded-crl-max-count <max-count>
The maximum number of entries that can be stored in-memory by the crl cache.
--cache-embedded-keys-max-count <max-count>
The maximum number of entries that can be stored in-memory by the keys cache.
--cache-embedded-mtls-enabled <true|false>
Encrypts the network communication between Keycloak servers. Default: false.
--cache-embedded-mtls-key-store-file <file>
The Keystore file path. The Keystore must contain the certificate to use by
the TLS protocol. By default, it lookup 'cache-mtls-keystore.p12' under
conf/ directory.
--cache-embedded-mtls-key-store-password <password>
The password to access the Keystore.
--cache-embedded-mtls-trust-store-file <file>
The Truststore file path. It should contain the trusted certificates or the
Certificate Authority that signed the certificates. By default, it lookup
'cache-mtls-truststore.p12' under conf/ directory.
--cache-embedded-mtls-trust-store-password <password>
The password to access the Truststore.
--cache-embedded-offline-client-sessions-max-count <max-count>
The maximum number of entries that can be stored in-memory by the
offlineClientSessions cache. Available only when embedded Infinispan
clusters configured.
--cache-embedded-offline-sessions-max-count <max-count>
The maximum number of entries that can be stored in-memory by the
offlineSessions cache. Available only when embedded Infinispan clusters
configured.
--cache-embedded-realms-max-count <max-count>
The maximum number of entries that can be stored in-memory by the realms cache.
--cache-embedded-sessions-max-count <max-count>
The maximum number of entries that can be stored in-memory by the sessions
cache. Available only when embedded Infinispan clusters configured.
--cache-embedded-users-max-count <max-count>
The maximum number of entries that can be stored in-memory by the users cache.
--cache-remote-host <hostname>
The hostname of the external Infinispan cluster. Available only when feature
'multi-site', 'clusterless' or 'cache-embedded-remote-store' is set.
Required when feature 'multi-site' or 'clusterless' is set.
--cache-stack <stack>
Define the default stack to use for cluster communication and node discovery.
Possible values are: jdbc-ping, kubernetes, jdbc-ping-udp (deprecated), tcp
(deprecated), udp (deprecated), ec2 (deprecated), azure (deprecated), google
(deprecated), or a custom one. Default: jdbc-ping. Available only when
'cache' type is set to 'ispn'.
Config:
--config-keystore <config-keystore>
Specifies a path to the KeyStore Configuration Source.
--config-keystore-password <config-keystore-password>
Specifies a password to the KeyStore Configuration Source.
--config-keystore-type <config-keystore-type>
Specifies a type of the KeyStore Configuration Source. Default: PKCS12.
Database:
--db <vendor> The database vendor. In production mode the default value of 'dev-file' is
deprecated, you should explicitly specify the db instead. Possible values
are: dev-file, dev-mem, mariadb, mssql, mysql, oracle, postgres. Default:
dev-file.
--db-driver <driver> The fully qualified class name of the JDBC driver. If not set, a default
driver is set accordingly to the chosen database.
--db-password <password>
The password of the database user.
--db-pool-initial-size <size>
The initial size of the connection pool.
--db-pool-max-size <size>
The maximum size of the connection pool. Default: 100.
--db-pool-min-size <size>
The minimal size of the connection pool.
--db-schema <schema> The database schema to be used.
--db-url <jdbc-url> The full database JDBC URL. If not provided, a default URL is set based on the
selected database vendor. For instance, if using 'postgres', the default
JDBC URL would be 'jdbc:postgresql://localhost/keycloak'.
--db-url-database <dbname>
Sets the database name of the default JDBC URL of the chosen vendor. If the
`db-url` option is set, this option is ignored.
--db-url-host <hostname>
Sets the hostname of the default JDBC URL of the chosen vendor. If the
`db-url` option is set, this option is ignored.
--db-url-port <port> Sets the port of the default JDBC URL of the chosen vendor. If the `db-url`
option is set, this option is ignored.
--db-url-properties <properties>
Sets the properties of the default JDBC URL of the chosen vendor. Make sure to
set the properties accordingly to the format expected by the database
vendor, as well as appending the right character at the beginning of this
property value. If the `db-url` option is set, this option is ignored.
--db-username <username>
The username of the database user.
Transaction:
--transaction-xa-enabled <true|false>
If set to true, XA datasources will be used. Default: false.
Feature:
--features <feature> Enables a set of one or more features. Possible values are: <...>.
--features-disabled <feature>
Disables a set of one or more features. Possible values are: <...>.
Hostname v2:
--hostname <hostname|URL>
Address at which is the server exposed. Can be a full URL, or just a hostname.
When only hostname is provided, scheme, port and context path are resolved
from the request. Available only when hostname:v2 feature is enabled.
--hostname-admin <URL>
Address for accessing the administration console. Use this option if you are
exposing the administration console using a reverse proxy on a different
address than specified in the 'hostname' option. Available only when
hostname:v2 feature is enabled.
--hostname-backchannel-dynamic <true|false>
Enables dynamic resolving of backchannel URLs, including hostname, scheme,
port and context path. Set to true if your application accesses Keycloak via
a private network. If set to true, 'hostname' option needs to be specified
as a full URL. Default: false. Available only when hostname:v2 feature is
enabled.
--hostname-debug <true|false>
Toggles the hostname debug page that is accessible at
/realms/master/hostname-debug. Default: false. Available only when hostname:
v2 feature is enabled.
--hostname-strict <true|false>
Disables dynamically resolving the hostname from request headers. Should
always be set to true in production, unless your reverse proxy overwrites
the Host header. If enabled, the 'hostname' option needs to be specified.
Default: true. Available only when hostname:v2 feature is enabled.
HTTP(S):
--http-enabled <true|false>
Enables the HTTP listener. Enabled by default in development mode. Typically
not enabled in production unless the server is fronted by a TLS termination
proxy. Default: false.
--http-host <host> The HTTP Host. Default: 0.0.0.0.
--http-max-queued-requests <requests>
Maximum number of queued HTTP requests. Use this to shed load in an overload
situation. Excess requests will return a "503 Server not Available" response.
--http-pool-max-threads <threads>
The maximum number of threads. If this is not specified then it will be
automatically sized to the greater of 4 * the number of available processors
and 50. For example if there are 4 processors the max threads will be 50. If
there are 48 processors it will be 192.
--http-port <port> The used HTTP port. Default: 8080.
--http-relative-path <path>
Set the path relative to '/' for serving resources. The path must start with a
'/'. Default: /.
--https-certificate-file <file>
The file path to a server certificate or certificate chain in PEM format.
--https-certificate-key-file <file>
The file path to a private key in PEM format.
--https-certificates-reload-period <reload period>
Interval on which to reload key store, trust store, and certificate files
referenced by https-* options. May be a java.time.Duration value, an integer
number of seconds, or an integer followed by one of [ms, h, m, s, d]. Must
be greater than 30 seconds. Use -1 to disable. Default: 1h.
--https-cipher-suites <ciphers>
The cipher suites to use. If none is given, a reasonable default is selected.
--https-client-auth <auth>
Configures the server to require/request client authentication. Possible
values are: none, request, required. Default: none.
--https-key-store-file <file>
The key store which holds the certificate information instead of specifying
separate files.
--https-key-store-password <password>
The password of the key store file. Default: password.
--https-key-store-type <type>
The type of the key store file. If not given, the type is automatically
detected based on the file extension. If 'fips-mode' is set to 'strict' and
no value is set, it defaults to 'BCFKS'.
--https-port <port> The used HTTPS port. Default: 8443.
--https-protocols <protocols>
The list of protocols to explicitly enable. Default: TLSv1.3,TLSv1.2.
--https-trust-store-file <file>
The trust store which holds the certificate information of the certificates to
trust.
--https-trust-store-password <password>
The password of the trust store file.
--https-trust-store-type <type>
The type of the trust store file. If not given, the type is automatically
detected based on the file extension. If 'fips-mode' is set to 'strict' and
no value is set, it defaults to 'BCFKS'.
Health:
--health-enabled <true|false>
If the server should expose health check endpoints. If enabled, health checks
are available at the '/health', '/health/ready' and '/health/live'
endpoints. Default: false.
Management:
--http-management-port <port>
Port of the management interface. Relevant only when something is exposed on
the management interface - see the guide for details. Default: 9000.
--http-management-relative-path <path>
Set the path relative to '/' for serving resources from management interface.
The path must start with a '/'. If not given, the value is inherited from
HTTP options. Relevant only when something is exposed on the management
interface - see the guide for details. Default: /.
--https-management-certificate-file <file>
The file path to a server certificate or certificate chain in PEM format for
the management server. If not given, the value is inherited from HTTP
options. Relevant only when something is exposed on the management interface
- see the guide for details.
--https-management-certificate-key-file <file>
The file path to a private key in PEM format for the management server. If not
given, the value is inherited from HTTP options. Relevant only when
something is exposed on the management interface - see the guide for details.
--https-management-client-auth <auth>
Configures the management interface to require/request client authentication.
If not given, the value is inherited from HTTP options. Relevant only when
something is exposed on the management interface - see the guide for
details. Possible values are: none, request, required. Default: none.
--https-management-key-store-file <file>
The key store which holds the certificate information instead of specifying
separate files for the management server. If not given, the value is
inherited from HTTP options. Relevant only when something is exposed on the
management interface - see the guide for details.
--https-management-key-store-password <password>
The password of the key store file for the management server. If not given,
the value is inherited from HTTP options. Relevant only when something is
exposed on the management interface - see the guide for details. Default:
password.
--legacy-observability-interface <true|false>
DEPRECATED. If metrics/health endpoints should be exposed on the main HTTP
server (not recommended). If set to true, the management interface is
disabled. Default: false.
Metrics:
--metrics-enabled <true|false>
If the server should expose metrics. If enabled, metrics are available at the
'/metrics' endpoint. Default: false.
Proxy:
--proxy-headers <headers>
The proxy headers that should be accepted by the server. Misconfiguration
might leave the server exposed to security vulnerabilities. Takes precedence
over the deprecated proxy option. Possible values are: forwarded, xforwarded.
--proxy-protocol-enabled <true|false>
Whether the server should use the HA PROXY protocol when serving requests from
behind a proxy. When set to true, the remote address returned will be the
one from the actual connecting client. Default: false.
--proxy-trusted-addresses <trusted proxies>
A comma separated list of trusted proxy addresses. If set, then proxy headers
from other addresses will be ignored. By default all addresses are trusted.
A trusted proxy address is specified as an IP address (IPv4 or IPv6) or
Classless Inter-Domain Routing (CIDR) notation. Available only when
proxy-headers is set.
Vault:
--vault <provider> Enables a vault provider. Possible values are: file, keystore.
--vault-dir <dir> If set, secrets can be obtained by reading the content of files within the
given directory.
--vault-file <file> Path to the keystore file.
--vault-pass <pass> Password for the vault keystore.
--vault-type <type> Specifies the type of the keystore file. Default: PKCS12.
Logging:
--log <handler> Enable one or more log handlers in a comma-separated list. Possible values
are: console, file, syslog. Default: console.
--log-console-color <true|false>
Enable or disable colors when logging to console. Default: false. Available
only when Console log handler is activated.
--log-console-format <format>
The format of unstructured console log entries. If the format has spaces in
it, escape the value using "<format>". Default: %d{yyyy-MM-dd HH:mm:ss,SSS} %
-5p [%c] (%t) %s%e%n. Available only when Console log handler is activated.
--log-console-level <level>
Set the log level for the console handler. It specifies the most verbose log
level for logs shown in the output. It respects levels specified in the
'log-level' option, which represents the maximal verbosity for the whole
logging system. For more information, check the Logging guide. Possible
values are (case insensitive): off, fatal, error, warn, info, debug, trace,
all. Default: all. Available only when Console log handler is activated.
--log-console-output <output>
Set the log output to JSON or default (plain) unstructured logging. Possible
values are: default, json. Default: default. Available only when Console log
handler is activated.
--log-level <category:level>
The log level of the root category or a comma-separated list of individual
categories and their levels. For the root category, you don't need to
specify a category. Default: info.
--log-level-<category> <level>
The log level of a category. Takes precedence over the 'log-level' option.
Possible values are (case insensitive): off, fatal, error, warn, info,
debug, trace, all.
Tracing:
--tracing-enabled <true|false>
Enables the OpenTelemetry tracing. Default: false. Available only when
'opentelemetry' feature is enabled.
Truststore:
--tls-hostname-verifier <tls-hostname-verifier>
The TLS hostname verification policy for out-going HTTPS and SMTP requests.
Possible values are: ANY, WILDCARD (deprecated), STRICT (deprecated),
DEFAULT. Default: DEFAULT.
--truststore-paths <truststore-paths>
List of pkcs12 (p12, pfx, or pkcs12 file extensions), PEM files, or
directories containing those files that will be used as a system truststore.
Security:
--fips-mode <mode> Sets the FIPS mode. If 'non-strict' is set, FIPS is enabled but on
non-approved mode. For full FIPS compliance, set 'strict' to run on approved
mode. This option defaults to 'disabled' when 'fips' feature is disabled,
which is by default. This option defaults to 'non-strict' when 'fips'
feature is enabled. Possible values are: non-strict, strict. Default:
disabled.
Bootstrap Admin:
--bootstrap-admin-client-id <client id>
Client id for the temporary bootstrap admin service account. Used only when
the master realm is created. Available only when bootstrap admin client
secret is set. Default: temp-admin.
--bootstrap-admin-client-secret <client secret>
Client secret for the temporary bootstrap admin service account. Used only
when the master realm is created. Use a non-CLI configuration option for
this option if possible.
--bootstrap-admin-password <password>
Temporary bootstrap admin password. Used only when the master realm is
created. Use a non-CLI configuration option for this option if possible.
--bootstrap-admin-username <username>
Temporary bootstrap admin username. Used only when the master realm is
created. Available only when bootstrap admin password is set. Default:
temp-admin.

502
quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testUpdateCompatibilityCheckHelpAll.approved.txt vendored Normal file
View File

@ -0,0 +1,502 @@
Usage:
kc.sh update-compatibility check [OPTIONS]
Checks if the metadata is compatible with the current configuration. A zero
exit code means a rolling upgrade is possible between old and the current
metadata.
Options:
--file <FILE> The file path to read the metadata.
-h, --help This help message.
--help-all This same help message but with additional options.
--optimized Use this option to achieve an optimal startup time if you have previously
built a server image using the 'build' command.
-v, --verbose Print out error details when running this command.
Cache:
--cache <type> Defines the cache mechanism for high-availability. By default in production
mode, a 'ispn' cache is used to create a cluster between multiple server
nodes. By default in development mode, a 'local' cache disables clustering
and is intended for development and testing purposes. Possible values are:
ispn, local. Default: ispn.
--cache-config-file <file>
Defines the file from which cache configuration should be loaded from. The
configuration file is relative to the 'conf/' directory.
--cache-embedded-authorization-max-count <max-count>
The maximum number of entries that can be stored in-memory by the
authorization cache.
--cache-embedded-client-sessions-max-count <max-count>
The maximum number of entries that can be stored in-memory by the
clientSessions cache. Available only when embedded Infinispan clusters
configured.
--cache-embedded-crl-max-count <max-count>
The maximum number of entries that can be stored in-memory by the crl cache.
--cache-embedded-keys-max-count <max-count>
The maximum number of entries that can be stored in-memory by the keys cache.
--cache-embedded-mtls-enabled <true|false>
Encrypts the network communication between Keycloak servers. Default: false.
--cache-embedded-mtls-key-store-file <file>
The Keystore file path. The Keystore must contain the certificate to use by
the TLS protocol. By default, it lookup 'cache-mtls-keystore.p12' under
conf/ directory.
--cache-embedded-mtls-key-store-password <password>
The password to access the Keystore.
--cache-embedded-mtls-trust-store-file <file>
The Truststore file path. It should contain the trusted certificates or the
Certificate Authority that signed the certificates. By default, it lookup
'cache-mtls-truststore.p12' under conf/ directory.
--cache-embedded-mtls-trust-store-password <password>
The password to access the Truststore.
--cache-embedded-offline-client-sessions-max-count <max-count>
The maximum number of entries that can be stored in-memory by the
offlineClientSessions cache. Available only when embedded Infinispan
clusters configured.
--cache-embedded-offline-sessions-max-count <max-count>
The maximum number of entries that can be stored in-memory by the
offlineSessions cache. Available only when embedded Infinispan clusters
configured.
--cache-embedded-realms-max-count <max-count>
The maximum number of entries that can be stored in-memory by the realms cache.
--cache-embedded-sessions-max-count <max-count>
The maximum number of entries that can be stored in-memory by the sessions
cache. Available only when embedded Infinispan clusters configured.
--cache-embedded-users-max-count <max-count>
The maximum number of entries that can be stored in-memory by the users cache.
--cache-metrics-histograms-enabled <true|false>
Enable histograms for metrics for the embedded caches. Default: false.
Available only when metrics are enabled.
--cache-remote-host <hostname>
The hostname of the external Infinispan cluster. Available only when feature
'multi-site', 'clusterless' or 'cache-embedded-remote-store' is set.
Required when feature 'multi-site' or 'clusterless' is set.
--cache-remote-password <password>
The password for the authentication to the external Infinispan cluster. It is
optional if connecting to an unsecure external Infinispan cluster. If the
option is specified, 'cache-remote-username' is required as well. Available
only when remote host is set.
--cache-remote-port <port>
The port of the external Infinispan cluster. Default: 11222. Available only
when remote host is set.
--cache-remote-tls-enabled <true|false>
Enable TLS support to communicate with a secured remote Infinispan server.
Recommended to be enabled in production. Default: true. Available only when
remote host is set.
--cache-remote-username <username>
The username for the authentication to the external Infinispan cluster. It is
optional if connecting to an unsecure external Infinispan cluster. If the
option is specified, 'cache-remote-password' is required as well. Available
only when remote host is set.
--cache-stack <stack>
Define the default stack to use for cluster communication and node discovery.
Possible values are: jdbc-ping, kubernetes, jdbc-ping-udp (deprecated), tcp
(deprecated), udp (deprecated), ec2 (deprecated), azure (deprecated), google
(deprecated), or a custom one. Default: jdbc-ping. Available only when
'cache' type is set to 'ispn'.
Config:
--config-keystore <config-keystore>
Specifies a path to the KeyStore Configuration Source.
--config-keystore-password <config-keystore-password>
Specifies a password to the KeyStore Configuration Source.
--config-keystore-type <config-keystore-type>
Specifies a type of the KeyStore Configuration Source. Default: PKCS12.
Database:
--db <vendor> The database vendor. In production mode the default value of 'dev-file' is
deprecated, you should explicitly specify the db instead. Possible values
are: dev-file, dev-mem, mariadb, mssql, mysql, oracle, postgres. Default:
dev-file.
--db-driver <driver> The fully qualified class name of the JDBC driver. If not set, a default
driver is set accordingly to the chosen database.
--db-password <password>
The password of the database user.
--db-pool-initial-size <size>
The initial size of the connection pool.
--db-pool-max-size <size>
The maximum size of the connection pool. Default: 100.
--db-pool-min-size <size>
The minimal size of the connection pool.
--db-schema <schema> The database schema to be used.
--db-url <jdbc-url> The full database JDBC URL. If not provided, a default URL is set based on the
selected database vendor. For instance, if using 'postgres', the default
JDBC URL would be 'jdbc:postgresql://localhost/keycloak'.
--db-url-database <dbname>
Sets the database name of the default JDBC URL of the chosen vendor. If the
`db-url` option is set, this option is ignored.
--db-url-host <hostname>
Sets the hostname of the default JDBC URL of the chosen vendor. If the
`db-url` option is set, this option is ignored.
--db-url-port <port> Sets the port of the default JDBC URL of the chosen vendor. If the `db-url`
option is set, this option is ignored.
--db-url-properties <properties>
Sets the properties of the default JDBC URL of the chosen vendor. Make sure to
set the properties accordingly to the format expected by the database
vendor, as well as appending the right character at the beginning of this
property value. If the `db-url` option is set, this option is ignored.
--db-username <username>
The username of the database user.
Transaction:
--transaction-xa-enabled <true|false>
If set to true, XA datasources will be used. Default: false.
Feature:
--features <feature> Enables a set of one or more features. Possible values are: <...>.
--features-disabled <feature>
Disables a set of one or more features. Possible values are: <...>.
Hostname v2:
--hostname <hostname|URL>
Address at which is the server exposed. Can be a full URL, or just a hostname.
When only hostname is provided, scheme, port and context path are resolved
from the request. Available only when hostname:v2 feature is enabled.
--hostname-admin <URL>
Address for accessing the administration console. Use this option if you are
exposing the administration console using a reverse proxy on a different
address than specified in the 'hostname' option. Available only when
hostname:v2 feature is enabled.
--hostname-backchannel-dynamic <true|false>
Enables dynamic resolving of backchannel URLs, including hostname, scheme,
port and context path. Set to true if your application accesses Keycloak via
a private network. If set to true, 'hostname' option needs to be specified
as a full URL. Default: false. Available only when hostname:v2 feature is
enabled.
--hostname-debug <true|false>
Toggles the hostname debug page that is accessible at
/realms/master/hostname-debug. Default: false. Available only when hostname:
v2 feature is enabled.
--hostname-strict <true|false>
Disables dynamically resolving the hostname from request headers. Should
always be set to true in production, unless your reverse proxy overwrites
the Host header. If enabled, the 'hostname' option needs to be specified.
Default: true. Available only when hostname:v2 feature is enabled.
HTTP(S):
--http-enabled <true|false>
Enables the HTTP listener. Enabled by default in development mode. Typically
not enabled in production unless the server is fronted by a TLS termination
proxy. Default: false.
--http-host <host> The HTTP Host. Default: 0.0.0.0.
--http-max-queued-requests <requests>
Maximum number of queued HTTP requests. Use this to shed load in an overload
situation. Excess requests will return a "503 Server not Available" response.
--http-metrics-histograms-enabled <true|false>
Enables a histogram with default buckets for the duration of HTTP server
requests. Default: false. Available only when metrics are enabled.
--http-metrics-slos <list of buckets>
Service level objectives for HTTP server requests. Use this instead of the
default histogram, or use it in combination to add additional buckets.
Specify a list of comma-separated values defined in milliseconds. Example
with buckets from 5ms to 10s: 5,10,25,50,250,500,1000,2500,5000,10000
Available only when metrics are enabled.
--http-pool-max-threads <threads>
The maximum number of threads. If this is not specified then it will be
automatically sized to the greater of 4 * the number of available processors
and 50. For example if there are 4 processors the max threads will be 50. If
there are 48 processors it will be 192.
--http-port <port> The used HTTP port. Default: 8080.
--http-relative-path <path>
Set the path relative to '/' for serving resources. The path must start with a
'/'. Default: /.
--https-certificate-file <file>
The file path to a server certificate or certificate chain in PEM format.
--https-certificate-key-file <file>
The file path to a private key in PEM format.
--https-certificates-reload-period <reload period>
Interval on which to reload key store, trust store, and certificate files
referenced by https-* options. May be a java.time.Duration value, an integer
number of seconds, or an integer followed by one of [ms, h, m, s, d]. Must
be greater than 30 seconds. Use -1 to disable. Default: 1h.
--https-cipher-suites <ciphers>
The cipher suites to use. If none is given, a reasonable default is selected.
--https-client-auth <auth>
Configures the server to require/request client authentication. Possible
values are: none, request, required. Default: none.
--https-key-store-file <file>
The key store which holds the certificate information instead of specifying
separate files.
--https-key-store-password <password>
The password of the key store file. Default: password.
--https-key-store-type <type>
The type of the key store file. If not given, the type is automatically
detected based on the file extension. If 'fips-mode' is set to 'strict' and
no value is set, it defaults to 'BCFKS'.
--https-port <port> The used HTTPS port. Default: 8443.
--https-protocols <protocols>
The list of protocols to explicitly enable. Default: TLSv1.3,TLSv1.2.
--https-trust-store-file <file>
The trust store which holds the certificate information of the certificates to
trust.
--https-trust-store-password <password>
The password of the trust store file.
--https-trust-store-type <type>
The type of the trust store file. If not given, the type is automatically
detected based on the file extension. If 'fips-mode' is set to 'strict' and
no value is set, it defaults to 'BCFKS'.
Health:
--health-enabled <true|false>
If the server should expose health check endpoints. If enabled, health checks
are available at the '/health', '/health/ready' and '/health/live'
endpoints. Default: false.
Management:
--http-management-port <port>
Port of the management interface. Relevant only when something is exposed on
the management interface - see the guide for details. Default: 9000.
--http-management-relative-path <path>
Set the path relative to '/' for serving resources from management interface.
The path must start with a '/'. If not given, the value is inherited from
HTTP options. Relevant only when something is exposed on the management
interface - see the guide for details. Default: /.
--https-management-certificate-file <file>
The file path to a server certificate or certificate chain in PEM format for
the management server. If not given, the value is inherited from HTTP
options. Relevant only when something is exposed on the management interface
- see the guide for details.
--https-management-certificate-key-file <file>
The file path to a private key in PEM format for the management server. If not
given, the value is inherited from HTTP options. Relevant only when
something is exposed on the management interface - see the guide for details.
--https-management-client-auth <auth>
Configures the management interface to require/request client authentication.
If not given, the value is inherited from HTTP options. Relevant only when
something is exposed on the management interface - see the guide for
details. Possible values are: none, request, required. Default: none.
--https-management-key-store-file <file>
The key store which holds the certificate information instead of specifying
separate files for the management server. If not given, the value is
inherited from HTTP options. Relevant only when something is exposed on the
management interface - see the guide for details.
--https-management-key-store-password <password>
The password of the key store file for the management server. If not given,
the value is inherited from HTTP options. Relevant only when something is
exposed on the management interface - see the guide for details. Default:
password.
--legacy-observability-interface <true|false>
DEPRECATED. If metrics/health endpoints should be exposed on the main HTTP
server (not recommended). If set to true, the management interface is
disabled. Default: false.
Metrics:
--metrics-enabled <true|false>
If the server should expose metrics. If enabled, metrics are available at the
'/metrics' endpoint. Default: false.
Proxy:
--proxy-headers <headers>
The proxy headers that should be accepted by the server. Misconfiguration
might leave the server exposed to security vulnerabilities. Takes precedence
over the deprecated proxy option. Possible values are: forwarded, xforwarded.
--proxy-protocol-enabled <true|false>
Whether the server should use the HA PROXY protocol when serving requests from
behind a proxy. When set to true, the remote address returned will be the
one from the actual connecting client. Default: false.
--proxy-trusted-addresses <trusted proxies>
A comma separated list of trusted proxy addresses. If set, then proxy headers
from other addresses will be ignored. By default all addresses are trusted.
A trusted proxy address is specified as an IP address (IPv4 or IPv6) or
Classless Inter-Domain Routing (CIDR) notation. Available only when
proxy-headers is set.
Vault:
--vault <provider> Enables a vault provider. Possible values are: file, keystore.
--vault-dir <dir> If set, secrets can be obtained by reading the content of files within the
given directory.
--vault-file <file> Path to the keystore file.
--vault-pass <pass> Password for the vault keystore.
--vault-type <type> Specifies the type of the keystore file. Default: PKCS12.
Logging:
--log <handler> Enable one or more log handlers in a comma-separated list. Possible values
are: console, file, syslog. Default: console.
--log-console-color <true|false>
Enable or disable colors when logging to console. Default: false. Available
only when Console log handler is activated.
--log-console-format <format>
The format of unstructured console log entries. If the format has spaces in
it, escape the value using "<format>". Default: %d{yyyy-MM-dd HH:mm:ss,SSS} %
-5p [%c] (%t) %s%e%n. Available only when Console log handler is activated.
--log-console-include-trace <true|false>
Include tracing information in the console log. If the 'log-console-format'
option is specified, this option has no effect. Default: true. Available
only when Console log handler and Tracing is activated.
--log-console-level <level>
Set the log level for the console handler. It specifies the most verbose log
level for logs shown in the output. It respects levels specified in the
'log-level' option, which represents the maximal verbosity for the whole
logging system. For more information, check the Logging guide. Possible
values are (case insensitive): off, fatal, error, warn, info, debug, trace,
all. Default: all. Available only when Console log handler is activated.
--log-console-output <output>
Set the log output to JSON or default (plain) unstructured logging. Possible
values are: default, json. Default: default. Available only when Console log
handler is activated.
--log-file <file> Set the log file path and filename. Default: data/log/keycloak.log. Available
only when File log handler is activated.
--log-file-format <format>
Set a format specific to file log entries. Default: %d{yyyy-MM-dd HH:mm:ss,
SSS} %-5p [%c] (%t) %s%e%n. Available only when File log handler is
activated.
--log-file-include-trace <true|false>
Include tracing information in the file log. If the 'log-file-format' option
is specified, this option has no effect. Default: true. Available only when
File log handler and Tracing is activated.
--log-file-level <level>
Set the log level for the file handler. It specifies the most verbose log
level for logs shown in the output. It respects levels specified in the
'log-level' option, which represents the maximal verbosity for the whole
logging system. For more information, check the Logging guide. Possible
values are (case insensitive): off, fatal, error, warn, info, debug, trace,
all. Default: all. Available only when File log handler is activated.
--log-file-output <output>
Set the log output to JSON or default (plain) unstructured logging. Possible
values are: default, json. Default: default. Available only when File log
handler is activated.
--log-level <category:level>
The log level of the root category or a comma-separated list of individual
categories and their levels. For the root category, you don't need to
specify a category. Default: info.
--log-level-<category> <level>
The log level of a category. Takes precedence over the 'log-level' option.
Possible values are (case insensitive): off, fatal, error, warn, info,
debug, trace, all.
--log-syslog-app-name <name>
Set the app name used when formatting the message in RFC5424 format. Default:
keycloak. Available only when Syslog is activated.
--log-syslog-endpoint <host:port>
Set the IP address and port of the Syslog server. Default: localhost:514.
Available only when Syslog is activated.
--log-syslog-format <format>
Set a format specific to Syslog entries. Default: %d{yyyy-MM-dd HH:mm:ss,SSS} %
-5p [%c] (%t) %s%e%n. Available only when Syslog is activated.
--log-syslog-include-trace <true|false>
Include tracing information in the Syslog. If the 'log-syslog-format' option
is specified, this option has no effect. Default: true. Available only when
Syslog handler and Tracing is activated.
--log-syslog-level <level>
Set the log level for the Syslog handler. It specifies the most verbose log
level for logs shown in the output. It respects levels specified in the
'log-level' option, which represents the maximal verbosity for the whole
logging system. For more information, check the Logging guide. Possible
values are (case insensitive): off, fatal, error, warn, info, debug, trace,
all. Default: all. Available only when Syslog is activated.
--log-syslog-max-length <max-length>
Set the maximum length, in bytes, of the message allowed to be sent. The
length includes the header and the message. If not set, the default value is
2048 when 'log-syslog-type' is rfc5424 (default) and 1024 when
'log-syslog-type' is rfc3164. Available only when Syslog is activated.
--log-syslog-output <output>
Set the Syslog output to JSON or default (plain) unstructured logging.
Possible values are: default, json. Default: default. Available only when
Syslog is activated.
--log-syslog-protocol <protocol>
Set the protocol used to connect to the Syslog server. Possible values are:
tcp, udp, ssl-tcp. Default: tcp. Available only when Syslog is activated.
--log-syslog-type <type>
Set the Syslog type used to format the sent message. Possible values are:
rfc5424, rfc3164. Default: rfc5424. Available only when Syslog is activated.
Tracing:
--tracing-compression <method>
OpenTelemetry compression method used to compress payloads. If unset,
compression is disabled. Possible values are: gzip, none. Default: none.
Available only when Tracing is enabled.
--tracing-enabled <true|false>
Enables the OpenTelemetry tracing. Default: false. Available only when
'opentelemetry' feature is enabled.
--tracing-endpoint <url>
OpenTelemetry endpoint to connect to. Default: http://localhost:4317.
Available only when Tracing is enabled.
--tracing-jdbc-enabled <true|false>
Enables the OpenTelemetry JDBC tracing. Default: true. Available only when
Tracing is enabled.
--tracing-protocol <protocol>
OpenTelemetry protocol used for the telemetry data. Possible values are: grpc,
http/protobuf. Default: grpc. Available only when Tracing is enabled.
--tracing-resource-attributes <attributes>
OpenTelemetry resource attributes present in the exported trace to
characterize the telemetry producer. Values in format 'key1=val1,key2=val2'.
For more information, check the Tracing guide. Available only when Tracing
is enabled.
--tracing-sampler-ratio <ratio>
OpenTelemetry sampler ratio. Probability that a span will be sampled. Expected
double value in interval <0,1). Default: 1.0. Available only when Tracing is
enabled.
--tracing-sampler-type <type>
OpenTelemetry sampler to use for tracing. Possible values are: always_on,
always_off, traceidratio, parentbased_always_on, parentbased_always_off,
parentbased_traceidratio. Default: traceidratio. Available only when Tracing
is enabled.
--tracing-service-name <name>
OpenTelemetry service name. Takes precedence over 'service.name' defined in
the 'tracing-resource-attributes' property. Default: keycloak. Available
only when Tracing is enabled.
Events (Preview):
--event-metrics-user-enabled <true|false>
Preview: Create metrics based on user events. Default: false. Available only
when metrics are enabled and feature user-event-metrics is enabled.
--event-metrics-user-events <events>
Preview: Comma-separated list of events to be collected for user event
metrics. Reduce the number of metrics. If empty or not set, all events
create a metric. Possible values are:<...>
--event-metrics-user-tags <tags>
Preview: Comma-separated list of tags to be collected for user event metrics.
By default only 'realm' is enabled to avoid a high metrics cardinality.
Possible values are: realm, idp, clientId. Default: realm. Available only
when user event metrics are enabled.
Truststore:
--tls-hostname-verifier <tls-hostname-verifier>
The TLS hostname verification policy for out-going HTTPS and SMTP requests.
Possible values are: ANY, WILDCARD (deprecated), STRICT (deprecated),
DEFAULT. Default: DEFAULT.
--truststore-paths <truststore-paths>
List of pkcs12 (p12, pfx, or pkcs12 file extensions), PEM files, or
directories containing those files that will be used as a system truststore.
Security:
--fips-mode <mode> Sets the FIPS mode. If 'non-strict' is set, FIPS is enabled but on
non-approved mode. For full FIPS compliance, set 'strict' to run on approved
mode. This option defaults to 'disabled' when 'fips' feature is disabled,
which is by default. This option defaults to 'non-strict' when 'fips'
feature is enabled. Possible values are: non-strict, strict. Default:
disabled.
Bootstrap Admin:
--bootstrap-admin-client-id <client id>
Client id for the temporary bootstrap admin service account. Used only when
the master realm is created. Available only when bootstrap admin client
secret is set. Default: temp-admin.
--bootstrap-admin-client-secret <client secret>
Client secret for the temporary bootstrap admin service account. Used only
when the master realm is created. Use a non-CLI configuration option for
this option if possible.
--bootstrap-admin-password <password>
Temporary bootstrap admin password. Used only when the master realm is
created. Use a non-CLI configuration option for this option if possible.
--bootstrap-admin-username <username>
Temporary bootstrap admin username. Used only when the master realm is
created. Available only when bootstrap admin password is set. Default:
temp-admin.

18
quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testUpdateCompatibilityHelp.approved.txt vendored Normal file
View File

@ -0,0 +1,18 @@
Usage:
kc.sh update-compatibility [OPTIONS] [COMMAND]
[Preview] Tool for configuration compatibility.
Options:
-h, --help This help message.
-v, --verbose Print out error details when running this command.
Commands:
check Checks if the metadata is compatible with the current
configuration. A zero exit code means a rolling upgrade is
possible between old and the current metadata.
metadata Stores the metadata necessary to determine if a configuration is
compatible.

365
quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testUpdateCompatibilityMetadataHelp.approved.txt vendored Normal file
View File

@ -0,0 +1,365 @@
Usage:
kc.sh update-compatibility metadata [OPTIONS]
Stores the metadata necessary to determine if a configuration is compatible.
Options:
--file <FILE> The file path to store the metadata. It is stored in the JSON format.
-h, --help This help message.
--help-all This same help message but with additional options.
--optimized Use this option to achieve an optimal startup time if you have previously
built a server image using the 'build' command.
-v, --verbose Print out error details when running this command.
Cache:
--cache <type> Defines the cache mechanism for high-availability. By default in production
mode, a 'ispn' cache is used to create a cluster between multiple server
nodes. By default in development mode, a 'local' cache disables clustering
and is intended for development and testing purposes. Possible values are:
ispn, local. Default: ispn.
--cache-config-file <file>
Defines the file from which cache configuration should be loaded from. The
configuration file is relative to the 'conf/' directory.
--cache-embedded-authorization-max-count <max-count>
The maximum number of entries that can be stored in-memory by the
authorization cache.
--cache-embedded-client-sessions-max-count <max-count>
The maximum number of entries that can be stored in-memory by the
clientSessions cache. Available only when embedded Infinispan clusters
configured.
--cache-embedded-crl-max-count <max-count>
The maximum number of entries that can be stored in-memory by the crl cache.
--cache-embedded-keys-max-count <max-count>
The maximum number of entries that can be stored in-memory by the keys cache.
--cache-embedded-mtls-enabled <true|false>
Encrypts the network communication between Keycloak servers. Default: false.
--cache-embedded-mtls-key-store-file <file>
The Keystore file path. The Keystore must contain the certificate to use by
the TLS protocol. By default, it lookup 'cache-mtls-keystore.p12' under
conf/ directory.
--cache-embedded-mtls-key-store-password <password>
The password to access the Keystore.
--cache-embedded-mtls-trust-store-file <file>
The Truststore file path. It should contain the trusted certificates or the
Certificate Authority that signed the certificates. By default, it lookup
'cache-mtls-truststore.p12' under conf/ directory.
--cache-embedded-mtls-trust-store-password <password>
The password to access the Truststore.
--cache-embedded-offline-client-sessions-max-count <max-count>
The maximum number of entries that can be stored in-memory by the
offlineClientSessions cache. Available only when embedded Infinispan
clusters configured.
--cache-embedded-offline-sessions-max-count <max-count>
The maximum number of entries that can be stored in-memory by the
offlineSessions cache. Available only when embedded Infinispan clusters
configured.
--cache-embedded-realms-max-count <max-count>
The maximum number of entries that can be stored in-memory by the realms cache.
--cache-embedded-sessions-max-count <max-count>
The maximum number of entries that can be stored in-memory by the sessions
cache. Available only when embedded Infinispan clusters configured.
--cache-embedded-users-max-count <max-count>
The maximum number of entries that can be stored in-memory by the users cache.
--cache-remote-host <hostname>
The hostname of the external Infinispan cluster. Available only when feature
'multi-site', 'clusterless' or 'cache-embedded-remote-store' is set.
Required when feature 'multi-site' or 'clusterless' is set.
--cache-stack <stack>
Define the default stack to use for cluster communication and node discovery.
Possible values are: jdbc-ping, kubernetes, jdbc-ping-udp (deprecated), tcp
(deprecated), udp (deprecated), ec2 (deprecated), azure (deprecated), google
(deprecated), or a custom one. Default: jdbc-ping. Available only when
'cache' type is set to 'ispn'.
Config:
--config-keystore <config-keystore>
Specifies a path to the KeyStore Configuration Source.
--config-keystore-password <config-keystore-password>
Specifies a password to the KeyStore Configuration Source.
--config-keystore-type <config-keystore-type>
Specifies a type of the KeyStore Configuration Source. Default: PKCS12.
Database:
--db <vendor> The database vendor. In production mode the default value of 'dev-file' is
deprecated, you should explicitly specify the db instead. Possible values
are: dev-file, dev-mem, mariadb, mssql, mysql, oracle, postgres. Default:
dev-file.
--db-driver <driver> The fully qualified class name of the JDBC driver. If not set, a default
driver is set accordingly to the chosen database.
--db-password <password>
The password of the database user.
--db-pool-initial-size <size>
The initial size of the connection pool.
--db-pool-max-size <size>
The maximum size of the connection pool. Default: 100.
--db-pool-min-size <size>
The minimal size of the connection pool.
--db-schema <schema> The database schema to be used.
--db-url <jdbc-url> The full database JDBC URL. If not provided, a default URL is set based on the
selected database vendor. For instance, if using 'postgres', the default
JDBC URL would be 'jdbc:postgresql://localhost/keycloak'.
--db-url-database <dbname>
Sets the database name of the default JDBC URL of the chosen vendor. If the
`db-url` option is set, this option is ignored.
--db-url-host <hostname>
Sets the hostname of the default JDBC URL of the chosen vendor. If the
`db-url` option is set, this option is ignored.
--db-url-port <port> Sets the port of the default JDBC URL of the chosen vendor. If the `db-url`
option is set, this option is ignored.
--db-url-properties <properties>
Sets the properties of the default JDBC URL of the chosen vendor. Make sure to
set the properties accordingly to the format expected by the database
vendor, as well as appending the right character at the beginning of this
property value. If the `db-url` option is set, this option is ignored.
--db-username <username>
The username of the database user.
Transaction:
--transaction-xa-enabled <true|false>
If set to true, XA datasources will be used. Default: false.
Feature:
--features <feature> Enables a set of one or more features. Possible values are: <...>.
--features-disabled <feature>
Disables a set of one or more features. Possible values are: <...>.
Hostname v2:
--hostname <hostname|URL>
Address at which is the server exposed. Can be a full URL, or just a hostname.
When only hostname is provided, scheme, port and context path are resolved
from the request. Available only when hostname:v2 feature is enabled.
--hostname-admin <URL>
Address for accessing the administration console. Use this option if you are
exposing the administration console using a reverse proxy on a different
address than specified in the 'hostname' option. Available only when
hostname:v2 feature is enabled.
--hostname-backchannel-dynamic <true|false>
Enables dynamic resolving of backchannel URLs, including hostname, scheme,
port and context path. Set to true if your application accesses Keycloak via
a private network. If set to true, 'hostname' option needs to be specified
as a full URL. Default: false. Available only when hostname:v2 feature is
enabled.
--hostname-debug <true|false>
Toggles the hostname debug page that is accessible at
/realms/master/hostname-debug. Default: false. Available only when hostname:
v2 feature is enabled.
--hostname-strict <true|false>
Disables dynamically resolving the hostname from request headers. Should
always be set to true in production, unless your reverse proxy overwrites
the Host header. If enabled, the 'hostname' option needs to be specified.
Default: true. Available only when hostname:v2 feature is enabled.
HTTP(S):
--http-enabled <true|false>
Enables the HTTP listener. Enabled by default in development mode. Typically
not enabled in production unless the server is fronted by a TLS termination
proxy. Default: false.
--http-host <host> The HTTP Host. Default: 0.0.0.0.
--http-max-queued-requests <requests>
Maximum number of queued HTTP requests. Use this to shed load in an overload
situation. Excess requests will return a "503 Server not Available" response.
--http-pool-max-threads <threads>
The maximum number of threads. If this is not specified then it will be
automatically sized to the greater of 4 * the number of available processors
and 50. For example if there are 4 processors the max threads will be 50. If
there are 48 processors it will be 192.
--http-port <port> The used HTTP port. Default: 8080.
--http-relative-path <path>
Set the path relative to '/' for serving resources. The path must start with a
'/'. Default: /.
--https-certificate-file <file>
The file path to a server certificate or certificate chain in PEM format.
--https-certificate-key-file <file>
The file path to a private key in PEM format.
--https-certificates-reload-period <reload period>
Interval on which to reload key store, trust store, and certificate files
referenced by https-* options. May be a java.time.Duration value, an integer
number of seconds, or an integer followed by one of [ms, h, m, s, d]. Must
be greater than 30 seconds. Use -1 to disable. Default: 1h.
--https-cipher-suites <ciphers>
The cipher suites to use. If none is given, a reasonable default is selected.
--https-client-auth <auth>
Configures the server to require/request client authentication. Possible
values are: none, request, required. Default: none.
--https-key-store-file <file>
The key store which holds the certificate information instead of specifying
separate files.
--https-key-store-password <password>
The password of the key store file. Default: password.
--https-key-store-type <type>
The type of the key store file. If not given, the type is automatically
detected based on the file extension. If 'fips-mode' is set to 'strict' and
no value is set, it defaults to 'BCFKS'.
--https-port <port> The used HTTPS port. Default: 8443.
--https-protocols <protocols>
The list of protocols to explicitly enable. Default: TLSv1.3,TLSv1.2.
--https-trust-store-file <file>
The trust store which holds the certificate information of the certificates to
trust.
--https-trust-store-password <password>
The password of the trust store file.
--https-trust-store-type <type>
The type of the trust store file. If not given, the type is automatically
detected based on the file extension. If 'fips-mode' is set to 'strict' and
no value is set, it defaults to 'BCFKS'.
Health:
--health-enabled <true|false>
If the server should expose health check endpoints. If enabled, health checks
are available at the '/health', '/health/ready' and '/health/live'
endpoints. Default: false.
Management:
--http-management-port <port>
Port of the management interface. Relevant only when something is exposed on
the management interface - see the guide for details. Default: 9000.
--http-management-relative-path <path>
Set the path relative to '/' for serving resources from management interface.
The path must start with a '/'. If not given, the value is inherited from
HTTP options. Relevant only when something is exposed on the management
interface - see the guide for details. Default: /.
--https-management-certificate-file <file>
The file path to a server certificate or certificate chain in PEM format for
the management server. If not given, the value is inherited from HTTP
options. Relevant only when something is exposed on the management interface
- see the guide for details.
--https-management-certificate-key-file <file>
The file path to a private key in PEM format for the management server. If not
given, the value is inherited from HTTP options. Relevant only when
something is exposed on the management interface - see the guide for details.
--https-management-client-auth <auth>
Configures the management interface to require/request client authentication.
If not given, the value is inherited from HTTP options. Relevant only when
something is exposed on the management interface - see the guide for
details. Possible values are: none, request, required. Default: none.
--https-management-key-store-file <file>
The key store which holds the certificate information instead of specifying
separate files for the management server. If not given, the value is
inherited from HTTP options. Relevant only when something is exposed on the
management interface - see the guide for details.
--https-management-key-store-password <password>
The password of the key store file for the management server. If not given,
the value is inherited from HTTP options. Relevant only when something is
exposed on the management interface - see the guide for details. Default:
password.
--legacy-observability-interface <true|false>
DEPRECATED. If metrics/health endpoints should be exposed on the main HTTP
server (not recommended). If set to true, the management interface is
disabled. Default: false.
Metrics:
--metrics-enabled <true|false>
If the server should expose metrics. If enabled, metrics are available at the
'/metrics' endpoint. Default: false.
Proxy:
--proxy-headers <headers>
The proxy headers that should be accepted by the server. Misconfiguration
might leave the server exposed to security vulnerabilities. Takes precedence
over the deprecated proxy option. Possible values are: forwarded, xforwarded.
--proxy-protocol-enabled <true|false>
Whether the server should use the HA PROXY protocol when serving requests from
behind a proxy. When set to true, the remote address returned will be the
one from the actual connecting client. Default: false.
--proxy-trusted-addresses <trusted proxies>
A comma separated list of trusted proxy addresses. If set, then proxy headers
from other addresses will be ignored. By default all addresses are trusted.
A trusted proxy address is specified as an IP address (IPv4 or IPv6) or
Classless Inter-Domain Routing (CIDR) notation. Available only when
proxy-headers is set.
Vault:
--vault <provider> Enables a vault provider. Possible values are: file, keystore.
--vault-dir <dir> If set, secrets can be obtained by reading the content of files within the
given directory.
--vault-file <file> Path to the keystore file.
--vault-pass <pass> Password for the vault keystore.
--vault-type <type> Specifies the type of the keystore file. Default: PKCS12.
Logging:
--log <handler> Enable one or more log handlers in a comma-separated list. Possible values
are: console, file, syslog. Default: console.
--log-console-color <true|false>
Enable or disable colors when logging to console. Default: false. Available
only when Console log handler is activated.
--log-console-format <format>
The format of unstructured console log entries. If the format has spaces in
it, escape the value using "<format>". Default: %d{yyyy-MM-dd HH:mm:ss,SSS} %
-5p [%c] (%t) %s%e%n. Available only when Console log handler is activated.
--log-console-level <level>
Set the log level for the console handler. It specifies the most verbose log
level for logs shown in the output. It respects levels specified in the
'log-level' option, which represents the maximal verbosity for the whole
logging system. For more information, check the Logging guide. Possible
values are (case insensitive): off, fatal, error, warn, info, debug, trace,
all. Default: all. Available only when Console log handler is activated.
--log-console-output <output>
Set the log output to JSON or default (plain) unstructured logging. Possible
values are: default, json. Default: default. Available only when Console log
handler is activated.
--log-level <category:level>
The log level of the root category or a comma-separated list of individual
categories and their levels. For the root category, you don't need to
specify a category. Default: info.
--log-level-<category> <level>
The log level of a category. Takes precedence over the 'log-level' option.
Possible values are (case insensitive): off, fatal, error, warn, info,
debug, trace, all.
Tracing:
--tracing-enabled <true|false>
Enables the OpenTelemetry tracing. Default: false. Available only when
'opentelemetry' feature is enabled.
Truststore:
--tls-hostname-verifier <tls-hostname-verifier>
The TLS hostname verification policy for out-going HTTPS and SMTP requests.
Possible values are: ANY, WILDCARD (deprecated), STRICT (deprecated),
DEFAULT. Default: DEFAULT.
--truststore-paths <truststore-paths>
List of pkcs12 (p12, pfx, or pkcs12 file extensions), PEM files, or
directories containing those files that will be used as a system truststore.
Security:
--fips-mode <mode> Sets the FIPS mode. If 'non-strict' is set, FIPS is enabled but on
non-approved mode. For full FIPS compliance, set 'strict' to run on approved
mode. This option defaults to 'disabled' when 'fips' feature is disabled,
which is by default. This option defaults to 'non-strict' when 'fips'
feature is enabled. Possible values are: non-strict, strict. Default:
disabled.
Bootstrap Admin:
--bootstrap-admin-client-id <client id>
Client id for the temporary bootstrap admin service account. Used only when
the master realm is created. Available only when bootstrap admin client
secret is set. Default: temp-admin.
--bootstrap-admin-client-secret <client secret>
Client secret for the temporary bootstrap admin service account. Used only
when the master realm is created. Use a non-CLI configuration option for
this option if possible.
--bootstrap-admin-password <password>
Temporary bootstrap admin password. Used only when the master realm is
created. Use a non-CLI configuration option for this option if possible.
--bootstrap-admin-username <username>
Temporary bootstrap admin username. Used only when the master realm is
created. Available only when bootstrap admin password is set. Default:
temp-admin.

500
quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testUpdateCompatibilityMetadataHelpAll.approved.txt vendored Normal file
View File

@ -0,0 +1,500 @@
Usage:
kc.sh update-compatibility metadata [OPTIONS]
Stores the metadata necessary to determine if a configuration is compatible.
Options:
--file <FILE> The file path to store the metadata. It is stored in the JSON format.
-h, --help This help message.
--help-all This same help message but with additional options.
--optimized Use this option to achieve an optimal startup time if you have previously
built a server image using the 'build' command.
-v, --verbose Print out error details when running this command.
Cache:
--cache <type> Defines the cache mechanism for high-availability. By default in production
mode, a 'ispn' cache is used to create a cluster between multiple server
nodes. By default in development mode, a 'local' cache disables clustering
and is intended for development and testing purposes. Possible values are:
ispn, local. Default: ispn.
--cache-config-file <file>
Defines the file from which cache configuration should be loaded from. The
configuration file is relative to the 'conf/' directory.
--cache-embedded-authorization-max-count <max-count>
The maximum number of entries that can be stored in-memory by the
authorization cache.
--cache-embedded-client-sessions-max-count <max-count>
The maximum number of entries that can be stored in-memory by the
clientSessions cache. Available only when embedded Infinispan clusters
configured.
--cache-embedded-crl-max-count <max-count>
The maximum number of entries that can be stored in-memory by the crl cache.
--cache-embedded-keys-max-count <max-count>
The maximum number of entries that can be stored in-memory by the keys cache.
--cache-embedded-mtls-enabled <true|false>
Encrypts the network communication between Keycloak servers. Default: false.
--cache-embedded-mtls-key-store-file <file>
The Keystore file path. The Keystore must contain the certificate to use by
the TLS protocol. By default, it lookup 'cache-mtls-keystore.p12' under
conf/ directory.
--cache-embedded-mtls-key-store-password <password>
The password to access the Keystore.
--cache-embedded-mtls-trust-store-file <file>
The Truststore file path. It should contain the trusted certificates or the
Certificate Authority that signed the certificates. By default, it lookup
'cache-mtls-truststore.p12' under conf/ directory.
--cache-embedded-mtls-trust-store-password <password>
The password to access the Truststore.
--cache-embedded-offline-client-sessions-max-count <max-count>
The maximum number of entries that can be stored in-memory by the
offlineClientSessions cache. Available only when embedded Infinispan
clusters configured.
--cache-embedded-offline-sessions-max-count <max-count>
The maximum number of entries that can be stored in-memory by the
offlineSessions cache. Available only when embedded Infinispan clusters
configured.
--cache-embedded-realms-max-count <max-count>
The maximum number of entries that can be stored in-memory by the realms cache.
--cache-embedded-sessions-max-count <max-count>
The maximum number of entries that can be stored in-memory by the sessions
cache. Available only when embedded Infinispan clusters configured.
--cache-embedded-users-max-count <max-count>
The maximum number of entries that can be stored in-memory by the users cache.
--cache-metrics-histograms-enabled <true|false>
Enable histograms for metrics for the embedded caches. Default: false.
Available only when metrics are enabled.
--cache-remote-host <hostname>
The hostname of the external Infinispan cluster. Available only when feature
'multi-site', 'clusterless' or 'cache-embedded-remote-store' is set.
Required when feature 'multi-site' or 'clusterless' is set.
--cache-remote-password <password>
The password for the authentication to the external Infinispan cluster. It is
optional if connecting to an unsecure external Infinispan cluster. If the
option is specified, 'cache-remote-username' is required as well. Available
only when remote host is set.
--cache-remote-port <port>
The port of the external Infinispan cluster. Default: 11222. Available only
when remote host is set.
--cache-remote-tls-enabled <true|false>
Enable TLS support to communicate with a secured remote Infinispan server.
Recommended to be enabled in production. Default: true. Available only when
remote host is set.
--cache-remote-username <username>
The username for the authentication to the external Infinispan cluster. It is
optional if connecting to an unsecure external Infinispan cluster. If the
option is specified, 'cache-remote-password' is required as well. Available
only when remote host is set.
--cache-stack <stack>
Define the default stack to use for cluster communication and node discovery.
Possible values are: jdbc-ping, kubernetes, jdbc-ping-udp (deprecated), tcp
(deprecated), udp (deprecated), ec2 (deprecated), azure (deprecated), google
(deprecated), or a custom one. Default: jdbc-ping. Available only when
'cache' type is set to 'ispn'.
Config:
--config-keystore <config-keystore>
Specifies a path to the KeyStore Configuration Source.
--config-keystore-password <config-keystore-password>
Specifies a password to the KeyStore Configuration Source.
--config-keystore-type <config-keystore-type>
Specifies a type of the KeyStore Configuration Source. Default: PKCS12.
Database:
--db <vendor> The database vendor. In production mode the default value of 'dev-file' is
deprecated, you should explicitly specify the db instead. Possible values
are: dev-file, dev-mem, mariadb, mssql, mysql, oracle, postgres. Default:
dev-file.
--db-driver <driver> The fully qualified class name of the JDBC driver. If not set, a default
driver is set accordingly to the chosen database.
--db-password <password>
The password of the database user.
--db-pool-initial-size <size>
The initial size of the connection pool.
--db-pool-max-size <size>
The maximum size of the connection pool. Default: 100.
--db-pool-min-size <size>
The minimal size of the connection pool.
--db-schema <schema> The database schema to be used.
--db-url <jdbc-url> The full database JDBC URL. If not provided, a default URL is set based on the
selected database vendor. For instance, if using 'postgres', the default
JDBC URL would be 'jdbc:postgresql://localhost/keycloak'.
--db-url-database <dbname>
Sets the database name of the default JDBC URL of the chosen vendor. If the
`db-url` option is set, this option is ignored.
--db-url-host <hostname>
Sets the hostname of the default JDBC URL of the chosen vendor. If the
`db-url` option is set, this option is ignored.
--db-url-port <port> Sets the port of the default JDBC URL of the chosen vendor. If the `db-url`
option is set, this option is ignored.
--db-url-properties <properties>
Sets the properties of the default JDBC URL of the chosen vendor. Make sure to
set the properties accordingly to the format expected by the database
vendor, as well as appending the right character at the beginning of this
property value. If the `db-url` option is set, this option is ignored.
--db-username <username>
The username of the database user.
Transaction:
--transaction-xa-enabled <true|false>
If set to true, XA datasources will be used. Default: false.
Feature:
--features <feature> Enables a set of one or more features. Possible values are: <...>.
--features-disabled <feature>
Disables a set of one or more features. Possible values are: <...>.
Hostname v2:
--hostname <hostname|URL>
Address at which is the server exposed. Can be a full URL, or just a hostname.
When only hostname is provided, scheme, port and context path are resolved
from the request. Available only when hostname:v2 feature is enabled.
--hostname-admin <URL>
Address for accessing the administration console. Use this option if you are
exposing the administration console using a reverse proxy on a different
address than specified in the 'hostname' option. Available only when
hostname:v2 feature is enabled.
--hostname-backchannel-dynamic <true|false>
Enables dynamic resolving of backchannel URLs, including hostname, scheme,
port and context path. Set to true if your application accesses Keycloak via
a private network. If set to true, 'hostname' option needs to be specified
as a full URL. Default: false. Available only when hostname:v2 feature is
enabled.
--hostname-debug <true|false>
Toggles the hostname debug page that is accessible at
/realms/master/hostname-debug. Default: false. Available only when hostname:
v2 feature is enabled.
--hostname-strict <true|false>
Disables dynamically resolving the hostname from request headers. Should
always be set to true in production, unless your reverse proxy overwrites
the Host header. If enabled, the 'hostname' option needs to be specified.
Default: true. Available only when hostname:v2 feature is enabled.
HTTP(S):
--http-enabled <true|false>
Enables the HTTP listener. Enabled by default in development mode. Typically
not enabled in production unless the server is fronted by a TLS termination
proxy. Default: false.
--http-host <host> The HTTP Host. Default: 0.0.0.0.
--http-max-queued-requests <requests>
Maximum number of queued HTTP requests. Use this to shed load in an overload
situation. Excess requests will return a "503 Server not Available" response.
--http-metrics-histograms-enabled <true|false>
Enables a histogram with default buckets for the duration of HTTP server
requests. Default: false. Available only when metrics are enabled.
--http-metrics-slos <list of buckets>
Service level objectives for HTTP server requests. Use this instead of the
default histogram, or use it in combination to add additional buckets.
Specify a list of comma-separated values defined in milliseconds. Example
with buckets from 5ms to 10s: 5,10,25,50,250,500,1000,2500,5000,10000
Available only when metrics are enabled.
--http-pool-max-threads <threads>
The maximum number of threads. If this is not specified then it will be
automatically sized to the greater of 4 * the number of available processors
and 50. For example if there are 4 processors the max threads will be 50. If
there are 48 processors it will be 192.
--http-port <port> The used HTTP port. Default: 8080.
--http-relative-path <path>
Set the path relative to '/' for serving resources. The path must start with a
'/'. Default: /.
--https-certificate-file <file>
The file path to a server certificate or certificate chain in PEM format.
--https-certificate-key-file <file>
The file path to a private key in PEM format.
--https-certificates-reload-period <reload period>
Interval on which to reload key store, trust store, and certificate files
referenced by https-* options. May be a java.time.Duration value, an integer
number of seconds, or an integer followed by one of [ms, h, m, s, d]. Must
be greater than 30 seconds. Use -1 to disable. Default: 1h.
--https-cipher-suites <ciphers>
The cipher suites to use. If none is given, a reasonable default is selected.
--https-client-auth <auth>
Configures the server to require/request client authentication. Possible
values are: none, request, required. Default: none.
--https-key-store-file <file>
The key store which holds the certificate information instead of specifying
separate files.
--https-key-store-password <password>
The password of the key store file. Default: password.
--https-key-store-type <type>
The type of the key store file. If not given, the type is automatically
detected based on the file extension. If 'fips-mode' is set to 'strict' and
no value is set, it defaults to 'BCFKS'.
--https-port <port> The used HTTPS port. Default: 8443.
--https-protocols <protocols>
The list of protocols to explicitly enable. Default: TLSv1.3,TLSv1.2.
--https-trust-store-file <file>
The trust store which holds the certificate information of the certificates to
trust.
--https-trust-store-password <password>
The password of the trust store file.
--https-trust-store-type <type>
The type of the trust store file. If not given, the type is automatically
detected based on the file extension. If 'fips-mode' is set to 'strict' and
no value is set, it defaults to 'BCFKS'.
Health:
--health-enabled <true|false>
If the server should expose health check endpoints. If enabled, health checks
are available at the '/health', '/health/ready' and '/health/live'
endpoints. Default: false.
Management:
--http-management-port <port>
Port of the management interface. Relevant only when something is exposed on
the management interface - see the guide for details. Default: 9000.
--http-management-relative-path <path>
Set the path relative to '/' for serving resources from management interface.
The path must start with a '/'. If not given, the value is inherited from
HTTP options. Relevant only when something is exposed on the management
interface - see the guide for details. Default: /.
--https-management-certificate-file <file>
The file path to a server certificate or certificate chain in PEM format for
the management server. If not given, the value is inherited from HTTP
options. Relevant only when something is exposed on the management interface
- see the guide for details.
--https-management-certificate-key-file <file>
The file path to a private key in PEM format for the management server. If not
given, the value is inherited from HTTP options. Relevant only when
something is exposed on the management interface - see the guide for details.
--https-management-client-auth <auth>
Configures the management interface to require/request client authentication.
If not given, the value is inherited from HTTP options. Relevant only when
something is exposed on the management interface - see the guide for
details. Possible values are: none, request, required. Default: none.
--https-management-key-store-file <file>
The key store which holds the certificate information instead of specifying
separate files for the management server. If not given, the value is
inherited from HTTP options. Relevant only when something is exposed on the
management interface - see the guide for details.
--https-management-key-store-password <password>
The password of the key store file for the management server. If not given,
the value is inherited from HTTP options. Relevant only when something is
exposed on the management interface - see the guide for details. Default:
password.
--legacy-observability-interface <true|false>
DEPRECATED. If metrics/health endpoints should be exposed on the main HTTP
server (not recommended). If set to true, the management interface is
disabled. Default: false.
Metrics:
--metrics-enabled <true|false>
If the server should expose metrics. If enabled, metrics are available at the
'/metrics' endpoint. Default: false.
Proxy:
--proxy-headers <headers>
The proxy headers that should be accepted by the server. Misconfiguration
might leave the server exposed to security vulnerabilities. Takes precedence
over the deprecated proxy option. Possible values are: forwarded, xforwarded.
--proxy-protocol-enabled <true|false>
Whether the server should use the HA PROXY protocol when serving requests from
behind a proxy. When set to true, the remote address returned will be the
one from the actual connecting client. Default: false.
--proxy-trusted-addresses <trusted proxies>
A comma separated list of trusted proxy addresses. If set, then proxy headers
from other addresses will be ignored. By default all addresses are trusted.
A trusted proxy address is specified as an IP address (IPv4 or IPv6) or
Classless Inter-Domain Routing (CIDR) notation. Available only when
proxy-headers is set.
Vault:
--vault <provider> Enables a vault provider. Possible values are: file, keystore.
--vault-dir <dir> If set, secrets can be obtained by reading the content of files within the
given directory.
--vault-file <file> Path to the keystore file.
--vault-pass <pass> Password for the vault keystore.
--vault-type <type> Specifies the type of the keystore file. Default: PKCS12.
Logging:
--log <handler> Enable one or more log handlers in a comma-separated list. Possible values
are: console, file, syslog. Default: console.
--log-console-color <true|false>
Enable or disable colors when logging to console. Default: false. Available
only when Console log handler is activated.
--log-console-format <format>
The format of unstructured console log entries. If the format has spaces in
it, escape the value using "<format>". Default: %d{yyyy-MM-dd HH:mm:ss,SSS} %
-5p [%c] (%t) %s%e%n. Available only when Console log handler is activated.
--log-console-include-trace <true|false>
Include tracing information in the console log. If the 'log-console-format'
option is specified, this option has no effect. Default: true. Available
only when Console log handler and Tracing is activated.
--log-console-level <level>
Set the log level for the console handler. It specifies the most verbose log
level for logs shown in the output. It respects levels specified in the
'log-level' option, which represents the maximal verbosity for the whole
logging system. For more information, check the Logging guide. Possible
values are (case insensitive): off, fatal, error, warn, info, debug, trace,
all. Default: all. Available only when Console log handler is activated.
--log-console-output <output>
Set the log output to JSON or default (plain) unstructured logging. Possible
values are: default, json. Default: default. Available only when Console log
handler is activated.
--log-file <file> Set the log file path and filename. Default: data/log/keycloak.log. Available
only when File log handler is activated.
--log-file-format <format>
Set a format specific to file log entries. Default: %d{yyyy-MM-dd HH:mm:ss,
SSS} %-5p [%c] (%t) %s%e%n. Available only when File log handler is
activated.
--log-file-include-trace <true|false>
Include tracing information in the file log. If the 'log-file-format' option
is specified, this option has no effect. Default: true. Available only when
File log handler and Tracing is activated.
--log-file-level <level>
Set the log level for the file handler. It specifies the most verbose log
level for logs shown in the output. It respects levels specified in the
'log-level' option, which represents the maximal verbosity for the whole
logging system. For more information, check the Logging guide. Possible
values are (case insensitive): off, fatal, error, warn, info, debug, trace,
all. Default: all. Available only when File log handler is activated.
--log-file-output <output>
Set the log output to JSON or default (plain) unstructured logging. Possible
values are: default, json. Default: default. Available only when File log
handler is activated.
--log-level <category:level>
The log level of the root category or a comma-separated list of individual
categories and their levels. For the root category, you don't need to
specify a category. Default: info.
--log-level-<category> <level>
The log level of a category. Takes precedence over the 'log-level' option.
Possible values are (case insensitive): off, fatal, error, warn, info,
debug, trace, all.
--log-syslog-app-name <name>
Set the app name used when formatting the message in RFC5424 format. Default:
keycloak. Available only when Syslog is activated.
--log-syslog-endpoint <host:port>
Set the IP address and port of the Syslog server. Default: localhost:514.
Available only when Syslog is activated.
--log-syslog-format <format>
Set a format specific to Syslog entries. Default: %d{yyyy-MM-dd HH:mm:ss,SSS} %
-5p [%c] (%t) %s%e%n. Available only when Syslog is activated.
--log-syslog-include-trace <true|false>
Include tracing information in the Syslog. If the 'log-syslog-format' option
is specified, this option has no effect. Default: true. Available only when
Syslog handler and Tracing is activated.
--log-syslog-level <level>
Set the log level for the Syslog handler. It specifies the most verbose log
level for logs shown in the output. It respects levels specified in the
'log-level' option, which represents the maximal verbosity for the whole
logging system. For more information, check the Logging guide. Possible
values are (case insensitive): off, fatal, error, warn, info, debug, trace,
all. Default: all. Available only when Syslog is activated.
--log-syslog-max-length <max-length>
Set the maximum length, in bytes, of the message allowed to be sent. The
length includes the header and the message. If not set, the default value is
2048 when 'log-syslog-type' is rfc5424 (default) and 1024 when
'log-syslog-type' is rfc3164. Available only when Syslog is activated.
--log-syslog-output <output>
Set the Syslog output to JSON or default (plain) unstructured logging.
Possible values are: default, json. Default: default. Available only when
Syslog is activated.
--log-syslog-protocol <protocol>
Set the protocol used to connect to the Syslog server. Possible values are:
tcp, udp, ssl-tcp. Default: tcp. Available only when Syslog is activated.
--log-syslog-type <type>
Set the Syslog type used to format the sent message. Possible values are:
rfc5424, rfc3164. Default: rfc5424. Available only when Syslog is activated.
Tracing:
--tracing-compression <method>
OpenTelemetry compression method used to compress payloads. If unset,
compression is disabled. Possible values are: gzip, none. Default: none.
Available only when Tracing is enabled.
--tracing-enabled <true|false>
Enables the OpenTelemetry tracing. Default: false. Available only when
'opentelemetry' feature is enabled.
--tracing-endpoint <url>
OpenTelemetry endpoint to connect to. Default: http://localhost:4317.
Available only when Tracing is enabled.
--tracing-jdbc-enabled <true|false>
Enables the OpenTelemetry JDBC tracing. Default: true. Available only when
Tracing is enabled.
--tracing-protocol <protocol>
OpenTelemetry protocol used for the telemetry data. Possible values are: grpc,
http/protobuf. Default: grpc. Available only when Tracing is enabled.
--tracing-resource-attributes <attributes>
OpenTelemetry resource attributes present in the exported trace to
characterize the telemetry producer. Values in format 'key1=val1,key2=val2'.
For more information, check the Tracing guide. Available only when Tracing
is enabled.
--tracing-sampler-ratio <ratio>
OpenTelemetry sampler ratio. Probability that a span will be sampled. Expected
double value in interval <0,1). Default: 1.0. Available only when Tracing is
enabled.
--tracing-sampler-type <type>
OpenTelemetry sampler to use for tracing. Possible values are: always_on,
always_off, traceidratio, parentbased_always_on, parentbased_always_off,
parentbased_traceidratio. Default: traceidratio. Available only when Tracing
is enabled.
--tracing-service-name <name>
OpenTelemetry service name. Takes precedence over 'service.name' defined in
the 'tracing-resource-attributes' property. Default: keycloak. Available
only when Tracing is enabled.
Events (Preview):
--event-metrics-user-enabled <true|false>
Preview: Create metrics based on user events. Default: false. Available only
when metrics are enabled and feature user-event-metrics is enabled.
--event-metrics-user-events <events>
Preview: Comma-separated list of events to be collected for user event
metrics. Reduce the number of metrics. If empty or not set, all events
create a metric. Possible values are:<...>
--event-metrics-user-tags <tags>
Preview: Comma-separated list of tags to be collected for user event metrics.
By default only 'realm' is enabled to avoid a high metrics cardinality.
Possible values are: realm, idp, clientId. Default: realm. Available only
when user event metrics are enabled.
Truststore:
--tls-hostname-verifier <tls-hostname-verifier>
The TLS hostname verification policy for out-going HTTPS and SMTP requests.
Possible values are: ANY, WILDCARD (deprecated), STRICT (deprecated),
DEFAULT. Default: DEFAULT.
--truststore-paths <truststore-paths>
List of pkcs12 (p12, pfx, or pkcs12 file extensions), PEM files, or
directories containing those files that will be used as a system truststore.
Security:
--fips-mode <mode> Sets the FIPS mode. If 'non-strict' is set, FIPS is enabled but on
non-approved mode. For full FIPS compliance, set 'strict' to run on approved
mode. This option defaults to 'disabled' when 'fips' feature is disabled,
which is by default. This option defaults to 'non-strict' when 'fips'
feature is enabled. Possible values are: non-strict, strict. Default:
disabled.
Bootstrap Admin:
--bootstrap-admin-client-id <client id>
Client id for the temporary bootstrap admin service account. Used only when
the master realm is created. Available only when bootstrap admin client
secret is set. Default: temp-admin.
--bootstrap-admin-client-secret <client secret>
Client secret for the temporary bootstrap admin service account. Used only
when the master realm is created. Use a non-CLI configuration option for
this option if possible.
--bootstrap-admin-password <password>
Temporary bootstrap admin password. Used only when the master realm is
created. Use a non-CLI configuration option for this option if possible.
--bootstrap-admin-username <username>
Temporary bootstrap admin username. Used only when the master realm is
created. Available only when bootstrap admin password is set. Default:
temp-admin.

34
quarkus/tests/junit5/src/main/java/org/keycloak/it/utils/RawKeycloakDistribution.java
View File

@ -99,7 +99,7 @@ public final class RawKeycloakDistribution implements KeycloakDistribution {
private ExecutorService outputExecutor;
private boolean inited = false;
private final Map<String, String> envVars = new HashMap<>();
private OutputConsumer outputConsumer;
private final OutputConsumer outputConsumer;
public RawKeycloakDistribution(boolean debug, boolean manualStop, boolean enableTls, boolean reCreate, boolean removeBuildOptionsAfterBuild, int requestPort) {
this(debug, manualStop, enableTls, reCreate, removeBuildOptionsAfterBuild, requestPort, new DefaultOutputConsumer());
@ -215,7 +215,6 @@ public final class RawKeycloakDistribution implements KeycloakDistribution {
keycloak.destroy();
keycloak.waitFor(DEFAULT_SHUTDOWN_TIMEOUT_SECONDS, TimeUnit.SECONDS);
exitCode = keycloak.exitValue();
} catch (Exception cause) {
destroyDescendantsOnWindows(keycloak, true);
keycloak.destroyForcibly();
@ -224,6 +223,10 @@ public final class RawKeycloakDistribution implements KeycloakDistribution {
}
}
if (keycloak != null) {
exitCode = keycloak.exitValue();
}
shutdownOutputExecutor();
}
@ -394,12 +397,7 @@ public final class RawKeycloakDistribution implements KeycloakDistribution {
}
private HostnameVerifier createInsecureHostnameVerifier() {
return new HostnameVerifier() {
@Override
public boolean verify(String s, SSLSession sslSession) {
return true;
}
};
return (s, sslSession) -> true;
}
private SSLSocketFactory createInsecureSslSocketFactory() throws IOException {
@ -511,7 +509,7 @@ public final class RawKeycloakDistribution implements KeycloakDistribution {
private void readOutput(Process process, OutputConsumer outputConsumer) {
try (
BufferedReader outStream = new BufferedReader(new InputStreamReader(process.getInputStream()));
BufferedReader errStream = new BufferedReader(new InputStreamReader(process.getErrorStream()));
BufferedReader errStream = new BufferedReader(new InputStreamReader(process.getErrorStream()))
) {
while (process.isAlive()) {
readStream(outStream, outputConsumer, false);
@ -574,22 +572,12 @@ public final class RawKeycloakDistribution implements KeycloakDistribution {
@Override
public void removeProperty(String name) {
updateProperties(new Consumer<Properties>() {
@Override
public void accept(Properties properties) {
properties.remove(name);
}
}, distPath.resolve("conf").resolve("keycloak.conf").toFile());
updateProperties(properties -> properties.remove(name), distPath.resolve("conf").resolve("keycloak.conf").toFile());
}
@Override
public void setQuarkusProperty(String key, String value) {
updateProperties(new Consumer<Properties>() {
@Override
public void accept(Properties properties) {
properties.put(key, value);
}
}, getQuarkusPropertiesFile());
updateProperties(properties -> properties.put(key, value), getQuarkusPropertiesFile());
}
@Override
@ -648,7 +636,7 @@ public final class RawKeycloakDistribution implements KeycloakDistribution {
if (propertiesFile.exists()) {
try (
FileInputStream in = new FileInputStream(propertiesFile);
FileInputStream in = new FileInputStream(propertiesFile)
) {
properties.load(in);
@ -709,7 +697,7 @@ public final class RawKeycloakDistribution implements KeycloakDistribution {
}
if (type.isInstance(this)) {
return (D) this;
return type.cast(type);
}
throw new IllegalArgumentException("Not a " + type + " type");