change --help to only show "supported" options (#13304)

* Unsupported options only shown when using help-all
* reworked impl based on comment in #13284
* Also fixes minor things of #13284 as unused imports

Closes #13283

Co-authored-by: Pedro Igor <pigor.craveiro@gmail.com>
This commit is contained in:
Dominik Guhr 2022-07-25 19:34:10 +02:00 committed by GitHub
parent 7158e781be
commit 878e3e0cbc
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
29 changed files with 1947 additions and 522 deletions

View file

@ -19,5 +19,6 @@ public class AllOptions {
ALL_OPTIONS.addAll(ProxyOptions.ALL_OPTIONS);
ALL_OPTIONS.addAll(TransactionOptions.ALL_OPTIONS);
ALL_OPTIONS.addAll(VaultOptions.ALL_OPTIONS);
ALL_OPTIONS.addAll(StorageOptions.ALL_OPTIONS);
}
}

View file

@ -46,6 +46,7 @@ public class StorageOptions {
String.join(",", String.join(", ", Arrays.stream(StorageType.values()).map(StorageType::name).collect(Collectors.toList())))))
.expectedValues(StorageType.values())
.defaultValue(Optional.empty())
.hidden()
.buildTime(true)
.build();

View file

@ -96,10 +96,10 @@ CLASSPATH_OPTS="'$DIRNAME'/../lib/quarkus-run.jar"
JAVA_RUN_OPTS="$JAVA_OPTS $SERVER_OPTS -cp $CLASSPATH_OPTS io.quarkus.bootstrap.runner.QuarkusEntryPoint ${CONFIG_ARGS#?}"
if [[ (! $CONFIG_ARGS = *"--optimized"*) ]] && [[ ! "$CONFIG_ARGS" == " build"* ]]; then
if [[ (! $CONFIG_ARGS = *"--optimized"*) ]] && [[ ! "$CONFIG_ARGS" == " build"* ]] && [[ ! "$CONFIG_ARGS" == *"-h" ]] && [[ ! "$CONFIG_ARGS" == *"--help"* ]]; then
eval "$JAVA" -Dkc.config.build-and-exit=true $JAVA_RUN_OPTS
JAVA_RUN_OPTS="-Dkc.config.built=true $JAVA_RUN_OPTS"
EXIT_CODE=$?
JAVA_RUN_OPTS="-Dkc.config.built=true $JAVA_RUN_OPTS"
if [ $EXIT_CODE != 0 ]; then
exit $EXIT_CODE
fi

View file

@ -17,18 +17,16 @@
package org.keycloak.quarkus.runtime.cli;
import static org.keycloak.quarkus.runtime.configuration.Configuration.getMappedPropertyName;
import static org.keycloak.quarkus.runtime.configuration.MicroProfileConfigProvider.NS_KEYCLOAK_PREFIX;
import static org.keycloak.quarkus.runtime.configuration.mappers.PropertyMappers.getMapper;
import static picocli.CommandLine.Help.Column.Overflow.SPAN;
import static picocli.CommandLine.Help.Column.Overflow.WRAP;
import java.util.ArrayList;
import java.util.Comparator;
import java.util.Iterator;
import java.util.List;
import org.keycloak.quarkus.runtime.cli.command.Build;
import org.keycloak.quarkus.runtime.cli.command.StartDev;
import org.keycloak.quarkus.runtime.configuration.mappers.PropertyMapper;
import org.keycloak.quarkus.runtime.configuration.mappers.PropertyMappers;
import org.keycloak.utils.StringUtil;
import picocli.CommandLine;
@ -48,13 +46,39 @@ public final class Help extends CommandLine.Help {
configureUsageMessage(commandSpec);
}
@Override
public String optionList(Layout layout, Comparator<OptionSpec> optionSort, IParamLabelRenderer valueLabelRenderer) {
List<OptionSpec> visibleOptionsNotInGroups = excludeHiddenAndGroupOptions(commandSpec().options());
return optionListExcludingGroups(visibleOptionsNotInGroups, layout, optionSort, valueLabelRenderer) + optionListGroupSections();
}
private List<OptionSpec> excludeHiddenAndGroupOptions(List<OptionSpec> all) {
List<OptionSpec> result = new ArrayList<>(all);
for (ArgGroupSpec group : optionSectionGroups()) {
result.removeAll(group.allOptionsNested());
}
for (Iterator<OptionSpec> iter = result.iterator(); iter.hasNext(); ) {
OptionSpec optionSpec = iter.next();
if (!isVisible(optionSpec)) {
iter.remove();
}
}
return result;
}
@Override
public Layout createDefaultLayout() {
return new Layout(colorScheme(), createTextTable(), createDefaultOptionRenderer(), createDefaultParameterRenderer()) {
@Override
public void addOption(OptionSpec option, IParamLabelRenderer paramLabelRenderer) {
if (isVisible(option)) {
super.addOption(option, paramLabelRenderer);
public void addOptions(List<OptionSpec> options, IParamLabelRenderer paramLabelRenderer) {
for (OptionSpec optionSpec : options) {
if (isVisible(optionSpec)) {
addOption(optionSpec, paramLabelRenderer);
}
}
}
};
@ -129,35 +153,26 @@ public final class Help extends CommandLine.Help {
}
private boolean isVisible(OptionSpec option) {
if (allOptions) {
return true;
if (option.description().length == 0) {
// do not show options without a description
return false;
}
String optionName = option.longestName();
boolean isFeatureOption = optionName.startsWith("--feature");
String canonicalOptionName = NS_KEYCLOAK_PREFIX.concat(optionName.replace("--", ""));
String propertyName = getMappedPropertyName(canonicalOptionName);
PropertyMapper mapper = getMapper(propertyName);
PropertyMapper<?> mapper = getMapper(option.longestName());
if (mapper == null && !isFeatureOption) {
// only filter mapped and non-feature options
return true;
if (mapper == null) {
// only filter mapped options, defaults to the hidden marker
return !option.hidden();
}
String commandName = commandSpec().name();
boolean isBuildTimeProperty = isFeatureOption || mapper.isBuildTime();
boolean isUnsupportedOption = !PropertyMappers.isSupported(mapper);
if (Build.NAME.equals(commandName)) {
// by default, build command only shows build time props
return isBuildTimeProperty;
if (isUnsupportedOption) {
// unsupported options removed from help if all options are not requested
return allOptions;
}
if (StartDev.NAME.equals(commandName)) {
// by default, start-dev command only shows runtime props
return !isBuildTimeProperty;
}
return true;
return !option.hidden();
}
public void setAllOptions(boolean allOptions) {

View file

@ -21,7 +21,6 @@ import static org.keycloak.quarkus.runtime.Environment.isRebuildCheck;
import static org.keycloak.quarkus.runtime.Environment.isRebuilt;
import static org.keycloak.quarkus.runtime.cli.command.AbstractStartCommand.*;
import static org.keycloak.quarkus.runtime.cli.command.AbstractStartCommand.AUTO_BUILD_OPTION_LONG;
import static org.keycloak.quarkus.runtime.cli.command.AbstractStartCommand.AUTO_BUILD_OPTION_SHORT;
import static org.keycloak.quarkus.runtime.configuration.ConfigArgsConfigSource.parseConfigArgs;
import static org.keycloak.quarkus.runtime.configuration.Configuration.OPTION_PART_SEPARATOR;
import static org.keycloak.quarkus.runtime.configuration.Configuration.getBuildTimeProperty;
@ -36,6 +35,8 @@ import static picocli.CommandLine.Model.UsageMessageSpec.SECTION_KEY_COMMAND_LIS
import java.io.File;
import java.io.PrintWriter;
import java.util.ArrayList;
import java.util.Collections;
import java.util.EnumMap;
import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
@ -92,7 +93,7 @@ public final class Picocli {
}
private static void exitOnFailure(int exitCode, CommandLine cmd) {
if (exitCode != cmd.getCommandSpec().exitCodeOnSuccess() && !Environment.isTestLaunchMode()) {
if (exitCode != cmd.getCommandSpec().exitCodeOnSuccess() && !Environment.isTestLaunchMode() || isRebuildCheck()) {
// hard exit wanted, as build failed and no subsequent command should be executed. no quarkus involved.
System.exit(exitCode);
}
@ -127,11 +128,6 @@ public final class Picocli {
return false;
}
if(!isDevMode()) {
if (cmd != null) {
cmd.getOut().println("Changes detected in configuration. Updating the server image.");
}
}
return true;
}
@ -164,17 +160,16 @@ public final class Picocli {
}
private static int runReAugmentation(List<String> cliArgs, CommandLine cmd) {
if(!isDevMode() && cmd != null) {
cmd.getOut().println("Changes detected in configuration. Updating the server image.");
}
int exitCode = 0;
List<String> configArgsList = new ArrayList<>(cliArgs);
// remove this once auto-build option is removed
configArgsList.remove(AUTO_BUILD_OPTION_LONG);
configArgsList.remove(AUTO_BUILD_OPTION_SHORT);
configArgsList.remove(ImportRealmMixin.IMPORT_REALM);
configArgsList.replaceAll(Picocli::replaceStartWithBuild);
configArgsList.removeIf(Picocli::isRuntimeOption);
exitCode = cmd.execute(configArgsList.toArray(new String[0]));
@ -339,9 +334,12 @@ public final class Picocli {
.build());
}
addOption(spec, Start.NAME, isRebuilt(), true);
addOption(spec, StartDev.NAME, true, true);
addOption(spec, Build.NAME, true, isRebuildCheck());
addCommandOptions(cliArgs, getCurrentCommandSpec(cliArgs, spec));
if (isRebuildCheck()) {
// build command should be available when running re-aug
addCommandOptions(cliArgs, spec.subcommands().get(Build.NAME).getCommandSpec());
}
CommandLine cmd = new CommandLine(spec);
@ -354,28 +352,61 @@ public final class Picocli {
return cmd;
}
private static void addOption(CommandSpec spec, String command, boolean includeBuildTime, boolean includeRuntime) {
CommandSpec commandSpec = spec.subcommands().get(command).getCommandSpec();
List<PropertyMapper> mappers = new ArrayList<>();
private static void addCommandOptions(List<String> cliArgs, CommandSpec command) {
if (command != null) {
boolean includeBuildTime = false;
boolean includeRuntime = false;
if (Start.NAME.equals(command.name()) || StartDev.NAME.equals(command.name())) {
includeBuildTime = isRebuilt() || !cliArgs.contains(OPTIMIZED_BUILD_OPTION_LONG);
includeRuntime = true;
} else if (Build.NAME.equals(command.name())) {
includeBuildTime = true;
includeRuntime = isRebuildCheck();
}
addOptionsToCli(command, includeBuildTime, includeRuntime);
}
}
private static CommandSpec getCurrentCommandSpec(List<String> cliArgs, CommandSpec spec) {
for (String arg : cliArgs) {
CommandLine command = spec.subcommands().get(arg);
if (command != null) {
return command.getCommandSpec();
}
}
return null;
}
private static void addOptionsToCli(CommandSpec commandSpec, boolean includeBuildTime, boolean includeRuntime) {
Map<OptionCategory, List<PropertyMapper>> mappers = new EnumMap<>(OptionCategory.class);
if (includeRuntime) {
mappers.addAll(PropertyMappers.getRuntimeMappers());
mappers.putAll(PropertyMappers.getRuntimeMappers());
}
if (includeBuildTime) {
mappers.addAll(PropertyMappers.getBuildTimeMappers());
for (Map.Entry<OptionCategory, List<PropertyMapper>> entry : PropertyMappers.getBuildTimeMappers()
.entrySet()) {
List<PropertyMapper> result = new ArrayList<>(mappers.getOrDefault(entry.getKey(), Collections.emptyList()));
result.addAll(entry.getValue());
mappers.put(entry.getKey(), result);
}
}
addMappedOptionsToArgGroups(commandSpec, mappers);
}
private static void addMappedOptionsToArgGroups(CommandSpec cSpec, List<PropertyMapper> propertyMappers) {
private static void addMappedOptionsToArgGroups(CommandSpec cSpec, Map<OptionCategory, List<PropertyMapper>> propertyMappers) {
for(OptionCategory category : OptionCategory.values()) {
List<PropertyMapper> mappersInCategory = propertyMappers.stream()
.filter(m -> category.equals(m.getCategory()))
.collect(Collectors.toList());
List<PropertyMapper> mappersInCategory = propertyMappers.get(category);
if(mappersInCategory.isEmpty()){
if (mappersInCategory == null) {
//picocli raises an exception when an ArgGroup is empty, so ignore it when no mappings found for a category.
continue;
}
@ -385,9 +416,8 @@ public final class Picocli {
.order(category.getOrder())
.validate(false);
for(PropertyMapper mapper: mappersInCategory) {
for (PropertyMapper mapper: mappersInCategory) {
String name = mapper.getCliFormat();
String description = mapper.getDescription();
if (description == null || cSpec.optionsMap().containsKey(name) || name.endsWith(OPTION_PART_SEPARATOR)) {
@ -475,4 +505,13 @@ public final class Picocli {
}
return arg;
}
private static boolean isRuntimeOption(String arg) {
// remove this once auto-build option is removed
if (AUTO_BUILD_OPTION_LONG.equals(arg) || AUTO_BUILD_OPTION_SHORT.equals(arg)) {
return true;
}
return arg.startsWith(ImportRealmMixin.IMPORT_REALM);
}
}

View file

@ -29,6 +29,7 @@ import io.quarkus.bootstrap.runner.QuarkusEntryPoint;
import io.quarkus.bootstrap.runner.RunnerClassLoader;
import io.quarkus.runtime.configuration.ProfileManager;
import picocli.CommandLine;
import picocli.CommandLine.Command;
@Command(name = Build.NAME,
@ -55,6 +56,9 @@ public final class Build extends AbstractCommand implements Runnable {
public static final String NAME = "build";
@CommandLine.Mixin
HelpAllMixin helpAllMixin;
@Override
public void run() {
exitWithErrorIfDevProfileIsSetAndNotStartDev();

View file

@ -37,20 +37,16 @@ public final class ImportRealmMixin {
paramLabel = NO_PARAM_LABEL,
arity = "0")
public void setImportRealm(String realmFiles) {
StringBuilder filesToImport = new StringBuilder(Optional.ofNullable(realmFiles).orElse(""));
if (filesToImport.length() > 0) {
throw new CommandLine.ParameterException(spec.commandLine(), "Instead of manually specifying the files to import, just copy them to the 'data/import' directory.");
}
File importDir = Environment.getHomePath().resolve("data").resolve("import").toFile();
if (importDir.exists()) {
StringBuilder filesToImport = new StringBuilder();
for (File realmFile : importDir.listFiles()) {
filesToImport.append(realmFile.getAbsolutePath()).append(",");
}
}
System.setProperty("keycloak.import", filesToImport.toString());
System.setProperty("keycloak.import", filesToImport.toString());
}
}
}

View file

@ -54,11 +54,14 @@ public final class Start extends AbstractStartCommand implements Runnable {
description = "Use this option to achieve an optional startup time if you have previously built a server image using the 'build' command.",
paramLabel = NO_PARAM_LABEL,
order = 1)
Boolean noAutoConfig;
Boolean optimized;
@CommandLine.Mixin
ImportRealmMixin importRealmMixin;
@CommandLine.Mixin
HelpAllMixin helpAllMixin;
@Override
protected void doBeforeRun() {
devProfileNotAllowedError();

View file

@ -2,16 +2,21 @@ package org.keycloak.quarkus.runtime.configuration.mappers;
import io.smallrye.config.ConfigSourceInterceptorContext;
import io.smallrye.config.ConfigValue;
import org.keycloak.config.ConfigSupportLevel;
import org.keycloak.config.OptionCategory;
import org.keycloak.quarkus.runtime.Environment;
import org.keycloak.quarkus.runtime.configuration.ConfigArgsConfigSource;
import java.util.ArrayList;
import java.util.Collection;
import java.util.EnumMap;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.function.Function;
import java.util.function.Predicate;
import java.util.stream.Collectors;
public final class PropertyMappers {
@ -87,14 +92,12 @@ public final class PropertyMappers {
return name.startsWith("kc.features");
}
public static List<PropertyMapper> getRuntimeMappers() {
return MAPPERS.values().stream()
.filter(entry -> !entry.isBuildTime()).collect(Collectors.toList());
public static Map<OptionCategory, List<PropertyMapper>> getRuntimeMappers() {
return MAPPERS.getRuntimeMappers();
}
public static List<PropertyMapper> getBuildTimeMappers() {
return MAPPERS.values().stream()
.filter(PropertyMapper::isBuildTime).collect(Collectors.toList());
public static Map<OptionCategory, List<PropertyMapper>> getBuildTimeMappers() {
return MAPPERS.getBuildTimeMappers();
}
public static String formatValue(String property, String value) {
@ -127,6 +130,10 @@ public final class PropertyMappers {
return MAPPERS.values();
}
public static boolean isSupported(PropertyMapper mapper) {
return mapper.getCategory().getSupportLevel().equals(ConfigSupportLevel.SUPPORTED);
}
private static Optional<String> getPrefixedMapper(String name) {
return MAPPERS.entrySet().stream().filter(
new Predicate<Map.Entry<String, PropertyMapper>>() {
@ -148,15 +155,34 @@ public final class PropertyMappers {
private static class MappersConfig extends HashMap<String, PropertyMapper> {
private Map<OptionCategory, List<PropertyMapper>> buildTimeMappers = new EnumMap<>(OptionCategory.class);
private Map<OptionCategory, List<PropertyMapper>> runtimeTimeMappers = new EnumMap<>(OptionCategory.class);
public void addAll(PropertyMapper[] mappers) {
for (PropertyMapper mapper : mappers) {
super.put(mapper.getTo(), mapper);
super.put(mapper.getFrom(), mapper);
super.put(mapper.getCliFormat(), mapper);
super.put(mapper.getEnvVarFormat(), mapper);
if (mapper.isBuildTime()) {
addMapperByStage(mapper, buildTimeMappers);
} else {
addMapperByStage(mapper, runtimeTimeMappers);
}
}
}
private void addMapperByStage(PropertyMapper mapper, Map<OptionCategory, List<PropertyMapper>> mappers) {
mappers.computeIfAbsent(mapper.getCategory(),
new Function<OptionCategory, List<PropertyMapper>>() {
@Override
public List<PropertyMapper> apply(OptionCategory c) {
return new ArrayList<>();
}
}).add(mapper);
}
@Override
public PropertyMapper put(String key, PropertyMapper value) {
if (containsKey(key)) {
@ -164,6 +190,14 @@ public final class PropertyMappers {
}
return super.put(key, value);
}
public Map<OptionCategory, List<PropertyMapper>> getRuntimeMappers() {
return runtimeTimeMappers;
}
public Map<OptionCategory, List<PropertyMapper>> getBuildTimeMappers() {
return buildTimeMappers;
}
}
}

View file

@ -68,8 +68,8 @@ public class DatabaseContainer {
private JdbcDatabaseContainer createContainer() {
String POSTGRES_IMAGE = System.getProperty("kc.db.postgresql.container.image");
String MARIADB_IMAGE = System.getProperty("kc.db.mariadb.container.image");
String POSTGRES_IMAGE = System.getProperty("kc.db.postgresql.container.image", "postgres:alpine");
String MARIADB_IMAGE = System.getProperty("kc.db.mariadb.container.image", "mariadb:10.5.9");
DockerImageName POSTGRES = DockerImageName.parse(POSTGRES_IMAGE).asCompatibleSubstituteFor("postgres");
DockerImageName MARIADB = DockerImageName.parse(MARIADB_IMAGE).asCompatibleSubstituteFor("mariadb");

View file

@ -109,8 +109,10 @@ public final class RawKeycloakDistribution implements KeycloakDistribution {
throw new RuntimeException("Failed to start the server", cause);
} finally {
if (arguments.contains(Build.NAME) && removeBuildOptionsAfterBuild) {
for (PropertyMapper mapper : PropertyMappers.getBuildTimeMappers()) {
removeProperty(mapper.getFrom().substring(3));
for (List<PropertyMapper> mappers : PropertyMappers.getBuildTimeMappers().values()) {
for (PropertyMapper mapper : mappers) {
removeProperty(mapper.getFrom().substring(3));
}
}
}
if (!manualStop) {
@ -415,6 +417,10 @@ public final class RawKeycloakDistribution implements KeycloakDistribution {
builder.environment().put("KEYCLOAK_ADMIN", "admin");
builder.environment().put("KEYCLOAK_ADMIN_PASSWORD", "admin");
if (debug) {
builder.environment().put("DEBUG_SUSPEND", "y");
}
builder.environment().putAll(envVars);
keycloak = builder.start();

View file

@ -55,11 +55,26 @@ public class HelpCommandTest {
@Test
@Launch({ Start.NAME, "--help", OPTIMIZED_BUILD_OPTION_LONG})
void testStartOptimizedHelp(LaunchResult result) {
CLIResult cliResult = (CLIResult) result;
cliResult.assertHelp();
}
@Test
@Launch({ Start.NAME, "--help" })
void testStartHelp(LaunchResult result) {
CLIResult cliResult = (CLIResult) result;
cliResult.assertHelp();
}
@Test
@Launch({ Start.NAME, "--optimized", "--help-all" })
void testStartOptimizedHelpAll(LaunchResult result) {
CLIResult cliResult = (CLIResult) result;
cliResult.assertHelp();
cliResult.assertNoMessage("--storage");
}
@Test
@Launch({ StartDev.NAME, "--help" })
void testStartDevHelp(LaunchResult result) {
@ -74,6 +89,14 @@ public class HelpCommandTest {
cliResult.assertHelp();
}
@Test
@Launch({ Start.NAME, "--help-all" })
void testStartHelpAll(LaunchResult result) {
CLIResult cliResult = (CLIResult) result;
cliResult.assertHelp();
cliResult.assertMessage("--storage");
}
@Test
@Launch({ Build.NAME, "--help" })
void testBuildHelp(LaunchResult result) {

View file

@ -59,7 +59,7 @@ public class OptionValidationTest {
public void failUnknownOptionWhitespaceSeparatorNotShowingValue(LaunchResult result) {
CLIResult cliResult = (CLIResult) result;
assertEquals("Unknown option: '--db-pasword'\n" +
"Possible solutions: --db-username, --db-pool-min-size, --db-password, --db-url-database, --db-schema, --db-pool-initial-size, --db-pool-max-size, --db-url-port, --db-url, --db-url-host, --db-url-properties\n" +
"Possible solutions: --db-url, --db-url-host, --db-url-database, --db-url-port, --db-url-properties, --db-username, --db-password, --db-schema, --db-pool-initial-size, --db-pool-min-size, --db-pool-max-size, --db\n" +
"Try '" + KeycloakDistribution.SCRIPT_CMD + " start --help' for more information on the available options.", cliResult.getErrorOutput());
}
@ -68,7 +68,7 @@ public class OptionValidationTest {
public void failUnknownOptionEqualsSeparatorNotShowingValue(LaunchResult result) {
CLIResult cliResult = (CLIResult) result;
assertEquals("Unknown option: '--db-pasword'\n" +
"Possible solutions: --db-username, --db-pool-min-size, --db-password, --db-url-database, --db-schema, --db-pool-initial-size, --db-pool-max-size, --db-url-port, --db-url, --db-url-host, --db-url-properties\n" +
"Possible solutions: --db-url, --db-url-host, --db-url-database, --db-url-port, --db-url-properties, --db-username, --db-password, --db-schema, --db-pool-initial-size, --db-pool-min-size, --db-pool-max-size, --db\n" +
"Try '" + KeycloakDistribution.SCRIPT_CMD + " start --help' for more information on the available options.", cliResult.getErrorOutput());
}
@ -77,7 +77,7 @@ public class OptionValidationTest {
public void failWithFirstOptionOnMultipleUnknownOptions(LaunchResult result) {
CLIResult cliResult = (CLIResult) result;
assertEquals("Unknown option: '--db-pasword'\n" +
"Possible solutions: --db-username, --db-pool-min-size, --db-password, --db-url-database, --db-schema, --db-pool-initial-size, --db-pool-max-size, --db-url-port, --db-url, --db-url-host, --db-url-properties\n" +
"Possible solutions: --db-url, --db-url-host, --db-url-database, --db-url-port, --db-url-properties, --db-username, --db-password, --db-schema, --db-pool-initial-size, --db-pool-min-size, --db-pool-max-size, --db\n" +
"Try '" + KeycloakDistribution.SCRIPT_CMD + " start --help' for more information on the available options.", cliResult.getErrorOutput());
}
}

View file

@ -17,11 +17,31 @@
package org.keycloak.it.cli.dist;
import static org.junit.Assert.assertEquals;
import java.util.List;
import org.junit.jupiter.api.Test;
import org.keycloak.it.cli.HelpCommandTest;
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;
@DistributionTest
@RawDistOnly(reason = "Verifying the help message output doesn't need long spin-up of docker dist tests.")
public class HelpCommandDistTest extends HelpCommandTest {
@Test
public void testHelpDoesNotStartReAugJvm(KeycloakDistribution dist) {
for (String helpCmd : List.of("-h", "--help", "--help-all")) {
for (String cmd : List.of("", "start", "start-dev", "build")) {
CLIResult run = dist.run("--debug", cmd, helpCmd);
assertSingleJvmStarted(run);
}
}
}
private void assertSingleJvmStarted(CLIResult run) {
assertEquals(1, run.getOutputStream().stream().filter(s -> s.contains("Listening for transport dt_socket")).count());
}
}

View file

@ -61,10 +61,10 @@ public class ImportAtStartupDistTest {
@Test
@BeforeStartDistribution(CreateRealmConfigurationFile.class)
@Launch({"start-dev", "--import-realm", "some-file"})
@Launch({"start-dev", "--import-realm=some-file"})
void failSetValueToImportRealmOption(LaunchResult result) {
CLIResult cliResult = (CLIResult) result;
cliResult.assertError("Instead of manually specifying the files to import, just copy them to the 'data/import' directory.");
cliResult.assertError("option '--import-realm' should be specified without 'some-file' parameter");
}
public static class CreateRealmConfigurationFile implements Consumer<KeycloakDistribution> {

View file

@ -17,9 +17,10 @@
package org.keycloak.it.cli.dist;
import static org.junit.Assert.assertEquals;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.Test;
import org.keycloak.it.junit5.extension.CLITest;
import org.keycloak.it.junit5.extension.DistributionTest;
import io.quarkus.test.junit.main.Launch;
@ -33,4 +34,16 @@ public class OptionValidationDistTest {
public void failInvalidOptionValue(LaunchResult result) {
Assertions.assertTrue(result.getErrorOutput().contains("Invalid value for option '--db': invalid. Expected values are: dev-file, dev-mem, mariadb, mssql, mysql, oracle, postgres"));
}
@Test
@Launch({"start-dev", "--test=invalid"})
public void testServerDoesNotStartIfValidationFailDuringReAugStartDev(LaunchResult result) {
assertEquals(1, result.getErrorStream().stream().filter(s -> s.contains("Unknown option: '--test'")).count());
}
@Test
@Launch({"start", "--test=invalid"})
public void testServerDoesNotStartIfValidationFailDuringReAugStart(LaunchResult result) {
assertEquals(1, result.getErrorStream().stream().filter(s -> s.contains("Unknown option: '--test'")).count());
}
}

View file

@ -14,6 +14,7 @@ optimal runtime.
Options:
-h, --help This help message.
--help-all This same help message but with additional options.
Cache:
@ -28,10 +29,6 @@ Cache:
Define the default stack to use for cluster communication and node discovery.
This option only takes effect if 'cache' is set to 'ispn'. Default: udp.
Storage (Experimental):
--storage <type> Experimental: Sets a storage mechanism. Possible values are: jpa, chm.
Database:
--db <vendor> The database vendor. Possible values are: dev-file, dev-mem, mariadb, mssql,

View file

@ -1,105 +1,96 @@
Creates a new and optimized server image.
Usage:
kc.bat build [OPTIONS]
Creates a new and optimized server image based on the configuration options
passed to this command. Once created, the configuration will be persisted and
read during startup without having to pass them over again.
Consider running this command before running the server in production for an
optimal runtime.
Options:
-h, --help This help message.
Cache:
--cache <type> Defines the cache mechanism for high-availability. By default, a 'ispn' cache
is used to create a cluster between multiple server nodes. A 'local' cache
disables clustering and is intended for development and testing purposes.
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-stack <stack>
Define the default stack to use for cluster communication and node discovery.
This option only takes effect if 'cache' is set to 'ispn'. Default: udp.
Storage (Experimental):
--storage <type> Experimental: Sets a storage mechanism. Possible values are: jpa, chm.
Database:
--db <vendor> The database vendor. Possible values are: dev-file, dev-mem, mariadb, mssql,
mysql, oracle, postgres Default: dev-file.
Transaction:
--transaction-xa-enabled <true|false>
If set to false, Keycloak uses a non-XA datasource in case the database does
not support XA transactions. Default: true.
Feature:
--features <feature> Enables a set of one or more features.
--features-disabled <feature>
Disables a set of one or more features.
HTTP/TLS:
--http-relative-path <path>
Set the path relative to '/' for serving resources. Default: /.
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.
Metrics:
--metrics-enabled <true|false>
If the server should expose metrics. If enabled, metrics are available at the
'/metrics' endpoint. Default: false.
Vault:
--vault <provider> Enables a vault provider.
Examples:
Change the database vendor:
$ kc.bat build --db=postgres
Enable a feature:
$ kc.bat build --features=<feature_name>
Or alternatively, enable all tech preview features:
$ kc.bat build --features=preview
Enable health endpoints:
$ kc.bat build --health-enabled=true
Enable metrics endpoints:
$ kc.bat build --metrics-enabled=true
Change the relative path:
$ kc.bat build --http-relative-path=/auth
You can also use the "--auto-build" option when starting the server to avoid
running this command every time you change a configuration:
$ kc.bat start --auto-build <OPTIONS>
By doing that you have an additional overhead when the server is starting.
Creates a new and optimized server image.
Usage:
kc.bat build [OPTIONS]
Creates a new and optimized server image based on the configuration options
passed to this command. Once created, the configuration will be persisted and
read during startup without having to pass them over again.
Consider running this command before running the server in production for an
optimal runtime.
Options:
-h, --help This help message.
--help-all This same help message but with additional options.
Cache:
--cache <type> Defines the cache mechanism for high-availability. By default, a 'ispn' cache
is used to create a cluster between multiple server nodes. A 'local' cache
disables clustering and is intended for development and testing purposes.
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-stack <stack>
Define the default stack to use for cluster communication and node discovery.
This option only takes effect if 'cache' is set to 'ispn'. Default: udp.
Database:
--db <vendor> The database vendor. Possible values are: dev-file, dev-mem, mariadb, mssql,
mysql, oracle, postgres. Default: dev-file.
Transaction:
--transaction-xa-enabled <true|false>
If set to false, Keycloak uses a non-XA datasource in case the database does
not support XA transactions. Default: true.
Feature:
--features <feature> Enables a set of one or more features.
--features-disabled <feature>
Disables a set of one or more features.
HTTP/TLS:
--http-relative-path <path>
Set the path relative to '/' for serving resources. Default: /.
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.
Metrics:
--metrics-enabled <true|false>
If the server should expose metrics. If enabled, metrics are available at the
'/metrics' endpoint. Default: false.
Vault:
--vault <provider> Enables a vault provider.
Examples:
Change the database vendor:
$ kc.bat build --db=postgres
Enable a feature:
$ kc.bat build --features=<feature_name>
Or alternatively, enable all tech preview features:
$ kc.bat build --features=preview
Enable health endpoints:
$ kc.bat build --health-enabled=true
Enable metrics endpoints:
$ kc.bat build --metrics-enabled=true
Change the relative path:
$ kc.bat build --http-relative-path=/auth

View file

@ -14,8 +14,23 @@ Options:
--import-realm Import realms during startup by reading any realm configuration file from the
'data/import' directory.
Cache:
--cache <type> Defines the cache mechanism for high-availability. By default, a 'ispn' cache
is used to create a cluster between multiple server nodes. A 'local' cache
disables clustering and is intended for development and testing purposes.
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-stack <stack>
Define the default stack to use for cluster communication and node discovery.
This option only takes effect if 'cache' is set to 'ispn'. Default: udp.
Database:
--db <vendor> The database vendor. Possible values are: dev-file, dev-mem, mariadb, mssql,
mysql, oracle, postgres. Default: dev-file.
--db-password <password>
The password of the database user.
--db-pool-initial-size <size>
@ -42,6 +57,18 @@ Database:
--db-username <username>
The username of the database user.
Transaction:
--transaction-xa-enabled <true|false>
If set to false, Keycloak uses a non-XA datasource in case the database does
not support XA transactions. Default: true.
Feature:
--features <feature> Enables a set of one or more features.
--features-disabled <feature>
Disables a set of one or more features.
Hostname:
--hostname <hostname>
@ -70,6 +97,8 @@ HTTP/TLS:
Enables the HTTP listener. Default: false.
--http-host <host> The used HTTP Host. Default: 0.0.0.0.
--http-port <port> The used HTTP port. Default: 8080.
--http-relative-path <path>
Set the path relative to '/' for serving resources. Default: /.
--https-certificate-file <file>
The file path to a server certificate or certificate chain in PEM format.
--https-certificate-key-file <file>
@ -99,6 +128,19 @@ HTTP/TLS:
The type of the trust store file. If not given, the type is automatically
detected based on the file name.
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.
Metrics:
--metrics-enabled <true|false>
If the server should expose metrics. If enabled, metrics are available at the
'/metrics' endpoint. Default: false.
Proxy:
--proxy <mode> The proxy address forwarding mode if the server is behind a reverse proxy.
@ -106,6 +148,7 @@ Proxy:
Vault:
--vault <provider> Enables a vault provider.
--vault-dir <dir> If set, secrets can be obtained by reading the content of files within the
given directory.

View file

@ -1,159 +1,202 @@
Start the server in development mode.
Usage:
kc.bat start-dev [OPTIONS]
Use this command if you want to run the server locally for development or
testing purposes.
Options:
-h, --help This help message.
--help-all This same help message but with additional options.
--import-realm Import realms during startup by reading any realm configuration file from the
'data/import' directory.
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. If the
`db-url` option is set, this option is ignored.
--db-username <username>
The username of the database user.
Hostname:
--hostname <hostname>
Hostname for the Keycloak server.
--hostname-admin <hostname>
The hostname for accessing the administration console. Use this option if you
are exposing the administration console using a hostname other than the
value set to the 'hostname' option.
--hostname-path <path>
This should be set if proxy uses a different context-path for Keycloak.
--hostname-port <port>
The port used by the proxy when exposing the hostname. Set this option if the
proxy uses a port other than the default HTTP and HTTPS ports. Default: -1.
--hostname-strict <true|false>
Disables dynamically resolving the hostname from request headers. Should
always be set to true in production, unless proxy verifies the Host header.
Default: true.
--hostname-strict-backchannel <true|false>
By default backchannel URLs are dynamically resolved from request headers to
allow internal and external applications. If all applications use the public
URL this option should be enabled. Default: false.
HTTP/TLS:
--http-enabled <true|false>
Enables the HTTP listener. Default: false.
--http-host <host> The used HTTP Host. Default: 0.0.0.0.
--http-port <port> The used HTTP port. Default: 8080.
--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-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: 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 name.
--https-port <port> The used HTTPS port. Default: 8443.
--https-protocols <protocols>
The list of protocols to explicitly enable. Default: TLSv1.3.
--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 name.
Proxy:
--proxy <mode> The proxy address forwarding mode if the server is behind a reverse proxy.
Possible values are: edge,reencrypt,passthrough Default: none.
Vault:
--vault-dir <dir> If set, secrets can be obtained by reading the content of files within the
given directory.
Logging:
--log <handler> Enable one or more log handlers in a comma-separated list. Available log
handlers are: console,file,gelf Default: console.
--log-console-color <true|false>
Enable or disable colors when logging to console. Default: false.
--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.
--log-console-output <default|json>
Set the log output to JSON or default (plain) unstructured logging. Default:
default.
--log-file <path>/<file-name>.log
Set the log file path and filename. Default: data\log\keycloak.log.
--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.
--log-gelf-facility <name>
The facility (name of the process) that sends the message. Default: keycloak.
--log-gelf-host <hostname>
Hostname of the Logstash or Graylog Host. By default UDP is used, prefix the
host with 'tcp:' to switch to TCP. Example: 'tcp:localhost' Default:
localhost.
--log-gelf-include-location <true|false>
Include source code location. Default: true.
--log-gelf-include-message-parameters <true|false>
Include message parameters from the log event. Default: true.
--log-gelf-include-stack-trace <true|false>
If set to true, occuring stack traces are included in the 'StackTrace' field
in the gelf output. Default: true.
--log-gelf-max-message-size <size>
Maximum message size (in bytes). If the message size is exceeded, gelf will
submit the message in multiple chunks. Default: 8192.
--log-gelf-port <port>
The port the Logstash or Graylog Host is called on. Default: 12201.
--log-gelf-timestamp-format <pattern>
Set the format for the gelf timestamp field. Uses Java SimpleDateFormat
pattern. Default: yyyy-MM-dd HH:mm:ss,SSS.
--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.
Do NOT start the server using this command when deploying to production.
Use 'kc.bat start-dev --help-all' to list all available options, including
build options.
Start the server in development mode.
Usage:
kc.bat start-dev [OPTIONS]
Use this command if you want to run the server locally for development or
testing purposes.
Options:
-h, --help This help message.
--help-all This same help message but with additional options.
--import-realm Import realms during startup by reading any realm configuration file from the
'data/import' directory.
Cache:
--cache <type> Defines the cache mechanism for high-availability. By default, a 'ispn' cache
is used to create a cluster between multiple server nodes. A 'local' cache
disables clustering and is intended for development and testing purposes.
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-stack <stack>
Define the default stack to use for cluster communication and node discovery.
This option only takes effect if 'cache' is set to 'ispn'. Default: udp.
Database:
--db <vendor> The database vendor. Possible values are: dev-file, dev-mem, mariadb, mssql,
mysql, oracle, postgres. Default: dev-file.
--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. 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 false, Keycloak uses a non-XA datasource in case the database does
not support XA transactions. Default: true.
Feature:
--features <feature> Enables a set of one or more features.
--features-disabled <feature>
Disables a set of one or more features.
Hostname:
--hostname <hostname>
Hostname for the Keycloak server.
--hostname-admin <hostname>
The hostname for accessing the administration console. Use this option if you
are exposing the administration console using a hostname other than the
value set to the 'hostname' option.
--hostname-path <path>
This should be set if proxy uses a different context-path for Keycloak.
--hostname-port <port>
The port used by the proxy when exposing the hostname. Set this option if the
proxy uses a port other than the default HTTP and HTTPS ports. Default: -1.
--hostname-strict <true|false>
Disables dynamically resolving the hostname from request headers. Should
always be set to true in production, unless proxy verifies the Host header.
Default: true.
--hostname-strict-backchannel <true|false>
By default backchannel URLs are dynamically resolved from request headers to
allow internal and external applications. If all applications use the public
URL this option should be enabled. Default: false.
HTTP/TLS:
--http-enabled <true|false>
Enables the HTTP listener. Default: false.
--http-host <host> The used HTTP Host. Default: 0.0.0.0.
--http-port <port> The used HTTP port. Default: 8080.
--http-relative-path <path>
Set the path relative to '/' for serving resources. 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-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: 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 name.
--https-port <port> The used HTTPS port. Default: 8443.
--https-protocols <protocols>
The list of protocols to explicitly enable. Default: TLSv1.3.
--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 name.
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.
Metrics:
--metrics-enabled <true|false>
If the server should expose metrics. If enabled, metrics are available at the
'/metrics' endpoint. Default: false.
Proxy:
--proxy <mode> The proxy address forwarding mode if the server is behind a reverse proxy.
Possible values are: edge,reencrypt,passthrough Default: none.
Vault:
--vault <provider> Enables a vault provider.
--vault-dir <dir> If set, secrets can be obtained by reading the content of files within the
given directory.
Logging:
--log <handler> Enable one or more log handlers in a comma-separated list. Available log
handlers are: console,file,gelf Default: console.
--log-console-color <true|false>
Enable or disable colors when logging to console. Default: false.
--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.
--log-console-output <default|json>
Set the log output to JSON or default (plain) unstructured logging. Default:
default.
--log-file <path>/<file-name>.log
Set the log file path and filename. Default: data\log\keycloak.log.
--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.
--log-gelf-facility <name>
The facility (name of the process) that sends the message. Default: keycloak.
--log-gelf-host <hostname>
Hostname of the Logstash or Graylog Host. By default UDP is used, prefix the
host with 'tcp:' to switch to TCP. Example: 'tcp:localhost' Default:
localhost.
--log-gelf-include-location <true|false>
Include source code location. Default: true.
--log-gelf-include-message-parameters <true|false>
Include message parameters from the log event. Default: true.
--log-gelf-include-stack-trace <true|false>
If set to true, occuring stack traces are included in the 'StackTrace' field
in the gelf output. Default: true.
--log-gelf-max-message-size <size>
Maximum message size (in bytes). If the message size is exceeded, gelf will
submit the message in multiple chunks. Default: 8192.
--log-gelf-port <port>
The port the Logstash or Graylog Host is called on. Default: 12201.
--log-gelf-timestamp-format <pattern>
Set the format for the gelf timestamp field. Uses Java SimpleDateFormat
pattern. Default: yyyy-MM-dd HH:mm:ss,SSS.
--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.
Do NOT start the server using this command when deploying to production.
Use 'kc.bat start-dev --help-all' to list all available options, including
build options.

View file

@ -190,7 +190,7 @@ Logging:
--log-gelf-max-message-size <size>
Maximum message size (in bytes). If the message size is exceeded, gelf will
submit the message in multiple chunks. Default: 8192.
--log-gelf-port <PortNr>
--log-gelf-port <port>
The port the Logstash or Graylog Host is called on. Default: 12201.
--log-gelf-timestamp-format <pattern>
Set the format for the gelf timestamp field. Uses Java SimpleDateFormat
@ -203,4 +203,4 @@ Logging:
Do NOT start the server using this command when deploying to production.
Use 'kc.bat start-dev --help-all' to list all available options, including
build options.
build options.

View file

@ -14,13 +14,29 @@ Options:
starting the server. Use this configuration carefully in production as it
might impact the startup time.
-h, --help This help message.
--help-all This same help message but with additional options.
--import-realm Import realms during startup by reading any realm configuration file from the
'data/import' directory.
--optimized Use this option to achieve an optional startup time if you have previously
built a server image using the 'build' command.
Cache:
--cache <type> Defines the cache mechanism for high-availability. By default, a 'ispn' cache
is used to create a cluster between multiple server nodes. A 'local' cache
disables clustering and is intended for development and testing purposes.
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-stack <stack>
Define the default stack to use for cluster communication and node discovery.
This option only takes effect if 'cache' is set to 'ispn'. Default: udp.
Database:
--db <vendor> The database vendor. Possible values are: dev-file, dev-mem, mariadb, mssql,
mysql, oracle, postgres. Default: dev-file.
--db-password <password>
The password of the database user.
--db-pool-initial-size <size>
@ -47,6 +63,18 @@ Database:
--db-username <username>
The username of the database user.
Transaction:
--transaction-xa-enabled <true|false>
If set to false, Keycloak uses a non-XA datasource in case the database does
not support XA transactions. Default: true.
Feature:
--features <feature> Enables a set of one or more features.
--features-disabled <feature>
Disables a set of one or more features.
Hostname:
--hostname <hostname>
@ -75,6 +103,8 @@ HTTP/TLS:
Enables the HTTP listener. Default: false.
--http-host <host> The used HTTP Host. Default: 0.0.0.0.
--http-port <port> The used HTTP port. Default: 8080.
--http-relative-path <path>
Set the path relative to '/' for serving resources. Default: /.
--https-certificate-file <file>
The file path to a server certificate or certificate chain in PEM format.
--https-certificate-key-file <file>
@ -104,6 +134,19 @@ HTTP/TLS:
The type of the trust store file. If not given, the type is automatically
detected based on the file name.
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.
Metrics:
--metrics-enabled <true|false>
If the server should expose metrics. If enabled, metrics are available at the
'/metrics' endpoint. Default: false.
Proxy:
--proxy <mode> The proxy address forwarding mode if the server is behind a reverse proxy.
@ -111,6 +154,7 @@ Proxy:
Vault:
--vault <provider> Enables a vault provider.
--vault-dir <dir> If set, secrets can be obtained by reading the content of files within the
given directory.

View file

@ -1,168 +1,212 @@
Start the server.
Usage:
kc.bat start [OPTIONS]
Use this command to run the server in production.
Options:
-b, --auto-build (Deprecated) Automatically detects whether the server configuration changed
and a new server image must be built prior to starting the server. This
option provides an alternative to manually running the 'build' prior to
starting the server. Use this configuration carefully in production as it
might impact the startup time.
-h, --help This help message.
--import-realm Import realms during startup by reading any realm configuration file from the
'data/import' directory.
--optimized Use this option to achieve an optional startup time if you have previously
built a server image using the 'build' command.
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. If the
`db-url` option is set, this option is ignored.
--db-username <username>
The username of the database user.
Hostname:
--hostname <hostname>
Hostname for the Keycloak server.
--hostname-admin <hostname>
The hostname for accessing the administration console. Use this option if you
are exposing the administration console using a hostname other than the
value set to the 'hostname' option.
--hostname-path <path>
This should be set if proxy uses a different context-path for Keycloak.
--hostname-port <port>
The port used by the proxy when exposing the hostname. Set this option if the
proxy uses a port other than the default HTTP and HTTPS ports. Default: -1.
--hostname-strict <true|false>
Disables dynamically resolving the hostname from request headers. Should
always be set to true in production, unless proxy verifies the Host header.
Default: true.
--hostname-strict-backchannel <true|false>
By default backchannel URLs are dynamically resolved from request headers to
allow internal and external applications. If all applications use the public
URL this option should be enabled. Default: false.
HTTP/TLS:
--http-enabled <true|false>
Enables the HTTP listener. Default: false.
--http-host <host> The used HTTP Host. Default: 0.0.0.0.
--http-port <port> The used HTTP port. Default: 8080.
--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-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: 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 name.
--https-port <port> The used HTTPS port. Default: 8443.
--https-protocols <protocols>
The list of protocols to explicitly enable. Default: TLSv1.3.
--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 name.
Proxy:
--proxy <mode> The proxy address forwarding mode if the server is behind a reverse proxy.
Possible values are: edge,reencrypt,passthrough Default: none.
Vault:
--vault-dir <dir> If set, secrets can be obtained by reading the content of files within the
given directory.
Logging:
--log <handler> Enable one or more log handlers in a comma-separated list. Available log
handlers are: console,file,gelf Default: console.
--log-console-color <true|false>
Enable or disable colors when logging to console. Default: false.
--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.
--log-console-output <default|json>
Set the log output to JSON or default (plain) unstructured logging. Default:
default.
--log-file <path>/<file-name>.log
Set the log file path and filename. Default: data\log\keycloak.log.
--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.
--log-gelf-facility <name>
The facility (name of the process) that sends the message. Default: keycloak.
--log-gelf-host <hostname>
Hostname of the Logstash or Graylog Host. By default UDP is used, prefix the
host with 'tcp:' to switch to TCP. Example: 'tcp:localhost' Default:
localhost.
--log-gelf-include-location <true|false>
Include source code location. Default: true.
--log-gelf-include-message-parameters <true|false>
Include message parameters from the log event. Default: true.
--log-gelf-include-stack-trace <true|false>
If set to true, occuring stack traces are included in the 'StackTrace' field
in the gelf output. Default: true.
--log-gelf-max-message-size <size>
Maximum message size (in bytes). If the message size is exceeded, gelf will
submit the message in multiple chunks. Default: 8192.
--log-gelf-port <port>
The port the Logstash or Graylog Host is called on. Default: 12201.
--log-gelf-timestamp-format <pattern>
Set the format for the gelf timestamp field. Uses Java SimpleDateFormat
pattern. Default: yyyy-MM-dd HH:mm:ss,SSS.
--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.
By default, this command tries to update the server configuration by running a
'build' before starting the server. You can disable this behavior by using the
'--optimized' option:
$ kc.bat start '--optimized'
By doing that, the server should start faster based on any previous
configuration you have set when manually running the 'build' command.
Start the server.
Usage:
kc.bat start [OPTIONS]
Use this command to run the server in production.
Options:
-b, --auto-build (Deprecated) Automatically detects whether the server configuration changed
and a new server image must be built prior to starting the server. This
option provides an alternative to manually running the 'build' prior to
starting the server. Use this configuration carefully in production as it
might impact the startup time.
-h, --help This help message.
--help-all This same help message but with additional options.
--import-realm Import realms during startup by reading any realm configuration file from the
'data/import' directory.
--optimized Use this option to achieve an optional startup time if you have previously
built a server image using the 'build' command.
Cache:
--cache <type> Defines the cache mechanism for high-availability. By default, a 'ispn' cache
is used to create a cluster between multiple server nodes. A 'local' cache
disables clustering and is intended for development and testing purposes.
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-stack <stack>
Define the default stack to use for cluster communication and node discovery.
This option only takes effect if 'cache' is set to 'ispn'. Default: udp.
Database:
--db <vendor> The database vendor. Possible values are: dev-file, dev-mem, mariadb, mssql,
mysql, oracle, postgres. Default: dev-file.
--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. 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 false, Keycloak uses a non-XA datasource in case the database does
not support XA transactions. Default: true.
Feature:
--features <feature> Enables a set of one or more features.
--features-disabled <feature>
Disables a set of one or more features.
Hostname:
--hostname <hostname>
Hostname for the Keycloak server.
--hostname-admin <hostname>
The hostname for accessing the administration console. Use this option if you
are exposing the administration console using a hostname other than the
value set to the 'hostname' option.
--hostname-path <path>
This should be set if proxy uses a different context-path for Keycloak.
--hostname-port <port>
The port used by the proxy when exposing the hostname. Set this option if the
proxy uses a port other than the default HTTP and HTTPS ports. Default: -1.
--hostname-strict <true|false>
Disables dynamically resolving the hostname from request headers. Should
always be set to true in production, unless proxy verifies the Host header.
Default: true.
--hostname-strict-backchannel <true|false>
By default backchannel URLs are dynamically resolved from request headers to
allow internal and external applications. If all applications use the public
URL this option should be enabled. Default: false.
HTTP/TLS:
--http-enabled <true|false>
Enables the HTTP listener. Default: false.
--http-host <host> The used HTTP Host. Default: 0.0.0.0.
--http-port <port> The used HTTP port. Default: 8080.
--http-relative-path <path>
Set the path relative to '/' for serving resources. 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-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: 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 name.
--https-port <port> The used HTTPS port. Default: 8443.
--https-protocols <protocols>
The list of protocols to explicitly enable. Default: TLSv1.3.
--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 name.
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.
Metrics:
--metrics-enabled <true|false>
If the server should expose metrics. If enabled, metrics are available at the
'/metrics' endpoint. Default: false.
Proxy:
--proxy <mode> The proxy address forwarding mode if the server is behind a reverse proxy.
Possible values are: edge,reencrypt,passthrough Default: none.
Vault:
--vault <provider> Enables a vault provider.
--vault-dir <dir> If set, secrets can be obtained by reading the content of files within the
given directory.
Logging:
--log <handler> Enable one or more log handlers in a comma-separated list. Available log
handlers are: console,file,gelf Default: console.
--log-console-color <true|false>
Enable or disable colors when logging to console. Default: false.
--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.
--log-console-output <default|json>
Set the log output to JSON or default (plain) unstructured logging. Default:
default.
--log-file <path>/<file-name>.log
Set the log file path and filename. Default: data\log\keycloak.log.
--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.
--log-gelf-facility <name>
The facility (name of the process) that sends the message. Default: keycloak.
--log-gelf-host <hostname>
Hostname of the Logstash or Graylog Host. By default UDP is used, prefix the
host with 'tcp:' to switch to TCP. Example: 'tcp:localhost' Default:
localhost.
--log-gelf-include-location <true|false>
Include source code location. Default: true.
--log-gelf-include-message-parameters <true|false>
Include message parameters from the log event. Default: true.
--log-gelf-include-stack-trace <true|false>
If set to true, occuring stack traces are included in the 'StackTrace' field
in the gelf output. Default: true.
--log-gelf-max-message-size <size>
Maximum message size (in bytes). If the message size is exceeded, gelf will
submit the message in multiple chunks. Default: 8192.
--log-gelf-port <port>
The port the Logstash or Graylog Host is called on. Default: 12201.
--log-gelf-timestamp-format <pattern>
Set the format for the gelf timestamp field. Uses Java SimpleDateFormat
pattern. Default: yyyy-MM-dd HH:mm:ss,SSS.
--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.
By default, this command tries to update the server configuration by running a
'build' before starting the server. You can disable this behavior by using the
'--optimized' option:
$ kc.bat start '--optimized'
By doing that, the server should start faster based on any previous
configuration you have set when manually running the 'build' command.

View file

@ -0,0 +1,216 @@
Start the server.
Usage:
kc.sh start [OPTIONS]
Use this command to run the server in production.
Options:
-b, --auto-build (Deprecated) Automatically detects whether the server configuration changed
and a new server image must be built prior to starting the server. This
option provides an alternative to manually running the 'build' prior to
starting the server. Use this configuration carefully in production as it
might impact the startup time.
-h, --help This help message.
--help-all This same help message but with additional options.
--import-realm Import realms during startup by reading any realm configuration file from the
'data/import' directory.
--optimized Use this option to achieve an optional startup time if you have previously
built a server image using the 'build' command.
Cache:
--cache <type> Defines the cache mechanism for high-availability. By default, a 'ispn' cache
is used to create a cluster between multiple server nodes. A 'local' cache
disables clustering and is intended for development and testing purposes.
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-stack <stack>
Define the default stack to use for cluster communication and node discovery.
This option only takes effect if 'cache' is set to 'ispn'. Default: udp.
Storage (Experimental):
--storage <type> Experimental: Sets a storage mechanism. Possible values are: jpa, chm.
Database:
--db <vendor> The database vendor. Possible values are: dev-file, dev-mem, mariadb, mssql,
mysql, oracle, postgres. Default: dev-file.
--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. 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 false, Keycloak uses a non-XA datasource in case the database does
not support XA transactions. Default: true.
Feature:
--features <feature> Enables a set of one or more features.
--features-disabled <feature>
Disables a set of one or more features.
Hostname:
--hostname <hostname>
Hostname for the Keycloak server.
--hostname-admin <hostname>
The hostname for accessing the administration console. Use this option if you
are exposing the administration console using a hostname other than the
value set to the 'hostname' option.
--hostname-path <path>
This should be set if proxy uses a different context-path for Keycloak.
--hostname-port <port>
The port used by the proxy when exposing the hostname. Set this option if the
proxy uses a port other than the default HTTP and HTTPS ports. Default: -1.
--hostname-strict <true|false>
Disables dynamically resolving the hostname from request headers. Should
always be set to true in production, unless proxy verifies the Host header.
Default: true.
--hostname-strict-backchannel <true|false>
By default backchannel URLs are dynamically resolved from request headers to
allow internal and external applications. If all applications use the public
URL this option should be enabled. Default: false.
HTTP/TLS:
--http-enabled <true|false>
Enables the HTTP listener. Default: false.
--http-host <host> The used HTTP Host. Default: 0.0.0.0.
--http-port <port> The used HTTP port. Default: 8080.
--http-relative-path <path>
Set the path relative to '/' for serving resources. 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-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: 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 name.
--https-port <port> The used HTTPS port. Default: 8443.
--https-protocols <protocols>
The list of protocols to explicitly enable. Default: TLSv1.3.
--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 name.
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.
Metrics:
--metrics-enabled <true|false>
If the server should expose metrics. If enabled, metrics are available at the
'/metrics' endpoint. Default: false.
Proxy:
--proxy <mode> The proxy address forwarding mode if the server is behind a reverse proxy.
Possible values are: edge,reencrypt,passthrough Default: none.
Vault:
--vault <provider> Enables a vault provider.
--vault-dir <dir> If set, secrets can be obtained by reading the content of files within the
given directory.
Logging:
--log <handler> Enable one or more log handlers in a comma-separated list. Available log
handlers are: console,file,gelf Default: console.
--log-console-color <true|false>
Enable or disable colors when logging to console. Default: false.
--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.
--log-console-output <default|json>
Set the log output to JSON or default (plain) unstructured logging. Default:
default.
--log-file <path>/<file-name>.log
Set the log file path and filename. Default: data/log/keycloak.log.
--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.
--log-gelf-facility <name>
The facility (name of the process) that sends the message. Default: keycloak.
--log-gelf-host <hostname>
Hostname of the Logstash or Graylog Host. By default UDP is used, prefix the
host with 'tcp:' to switch to TCP. Example: 'tcp:localhost' Default:
localhost.
--log-gelf-include-location <true|false>
Include source code location. Default: true.
--log-gelf-include-message-parameters <true|false>
Include message parameters from the log event. Default: true.
--log-gelf-include-stack-trace <true|false>
If set to true, occuring stack traces are included in the 'StackTrace' field
in the gelf output. Default: true.
--log-gelf-max-message-size <size>
Maximum message size (in bytes). If the message size is exceeded, gelf will
submit the message in multiple chunks. Default: 8192.
--log-gelf-port <port>
The port the Logstash or Graylog Host is called on. Default: 12201.
--log-gelf-timestamp-format <pattern>
Set the format for the gelf timestamp field. Uses Java SimpleDateFormat
pattern. Default: yyyy-MM-dd HH:mm:ss,SSS.
--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.
By default, this command tries to update the server configuration by running a
'build' before starting the server. You can disable this behavior by using the
'--optimized' option:
$ kc.sh start '--optimized'
By doing that, the server should start faster based on any previous
configuration you have set when manually running the 'build' command.

View file

@ -0,0 +1,216 @@
Start the server.
Usage:
kc.bat start [OPTIONS]
Use this command to run the server in production.
Options:
-b, --auto-build (Deprecated) Automatically detects whether the server configuration changed
and a new server image must be built prior to starting the server. This
option provides an alternative to manually running the 'build' prior to
starting the server. Use this configuration carefully in production as it
might impact the startup time.
-h, --help This help message.
--help-all This same help message but with additional options.
--import-realm Import realms during startup by reading any realm configuration file from the
'data/import' directory.
--optimized Use this option to achieve an optional startup time if you have previously
built a server image using the 'build' command.
Cache:
--cache <type> Defines the cache mechanism for high-availability. By default, a 'ispn' cache
is used to create a cluster between multiple server nodes. A 'local' cache
disables clustering and is intended for development and testing purposes.
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-stack <stack>
Define the default stack to use for cluster communication and node discovery.
This option only takes effect if 'cache' is set to 'ispn'. Default: udp.
Storage (Experimental):
--storage <type> Experimental: Sets a storage mechanism. Possible values are: jpa, chm.
Database:
--db <vendor> The database vendor. Possible values are: dev-file, dev-mem, mariadb, mssql,
mysql, oracle, postgres. Default: dev-file.
--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. 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 false, Keycloak uses a non-XA datasource in case the database does
not support XA transactions. Default: true.
Feature:
--features <feature> Enables a set of one or more features.
--features-disabled <feature>
Disables a set of one or more features.
Hostname:
--hostname <hostname>
Hostname for the Keycloak server.
--hostname-admin <hostname>
The hostname for accessing the administration console. Use this option if you
are exposing the administration console using a hostname other than the
value set to the 'hostname' option.
--hostname-path <path>
This should be set if proxy uses a different context-path for Keycloak.
--hostname-port <port>
The port used by the proxy when exposing the hostname. Set this option if the
proxy uses a port other than the default HTTP and HTTPS ports. Default: -1.
--hostname-strict <true|false>
Disables dynamically resolving the hostname from request headers. Should
always be set to true in production, unless proxy verifies the Host header.
Default: true.
--hostname-strict-backchannel <true|false>
By default backchannel URLs are dynamically resolved from request headers to
allow internal and external applications. If all applications use the public
URL this option should be enabled. Default: false.
HTTP/TLS:
--http-enabled <true|false>
Enables the HTTP listener. Default: false.
--http-host <host> The used HTTP Host. Default: 0.0.0.0.
--http-port <port> The used HTTP port. Default: 8080.
--http-relative-path <path>
Set the path relative to '/' for serving resources. 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-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: 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 name.
--https-port <port> The used HTTPS port. Default: 8443.
--https-protocols <protocols>
The list of protocols to explicitly enable. Default: TLSv1.3.
--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 name.
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.
Metrics:
--metrics-enabled <true|false>
If the server should expose metrics. If enabled, metrics are available at the
'/metrics' endpoint. Default: false.
Proxy:
--proxy <mode> The proxy address forwarding mode if the server is behind a reverse proxy.
Possible values are: edge,reencrypt,passthrough Default: none.
Vault:
--vault <provider> Enables a vault provider.
--vault-dir <dir> If set, secrets can be obtained by reading the content of files within the
given directory.
Logging:
--log <handler> Enable one or more log handlers in a comma-separated list. Available log
handlers are: console,file,gelf Default: console.
--log-console-color <true|false>
Enable or disable colors when logging to console. Default: false.
--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.
--log-console-output <default|json>
Set the log output to JSON or default (plain) unstructured logging. Default:
default.
--log-file <path>/<file-name>.log
Set the log file path and filename. Default: data\log\keycloak.log.
--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.
--log-gelf-facility <name>
The facility (name of the process) that sends the message. Default: keycloak.
--log-gelf-host <hostname>
Hostname of the Logstash or Graylog Host. By default UDP is used, prefix the
host with 'tcp:' to switch to TCP. Example: 'tcp:localhost' Default:
localhost.
--log-gelf-include-location <true|false>
Include source code location. Default: true.
--log-gelf-include-message-parameters <true|false>
Include message parameters from the log event. Default: true.
--log-gelf-include-stack-trace <true|false>
If set to true, occuring stack traces are included in the 'StackTrace' field
in the gelf output. Default: true.
--log-gelf-max-message-size <size>
Maximum message size (in bytes). If the message size is exceeded, gelf will
submit the message in multiple chunks. Default: 8192.
--log-gelf-port <port>
The port the Logstash or Graylog Host is called on. Default: 12201.
--log-gelf-timestamp-format <pattern>
Set the format for the gelf timestamp field. Uses Java SimpleDateFormat
pattern. Default: yyyy-MM-dd HH:mm:ss,SSS.
--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.
By default, this command tries to update the server configuration by running a
'build' before starting the server. You can disable this behavior by using the
'--optimized' option:
$ kc.bat start '--optimized'
By doing that, the server should start faster based on any previous
configuration you have set when manually running the 'build' command.

View file

@ -0,0 +1,169 @@
Start the server.
Usage:
kc.sh start [OPTIONS]
Use this command to run the server in production.
Options:
-b, --auto-build (Deprecated) Automatically detects whether the server configuration changed
and a new server image must be built prior to starting the server. This
option provides an alternative to manually running the 'build' prior to
starting the server. Use this configuration carefully in production as it
might impact the startup time.
-h, --help This help message.
--help-all This same help message but with additional options.
--import-realm Import realms during startup by reading any realm configuration file from the
'data/import' directory.
--optimized Use this option to achieve an optional startup time if you have previously
built a server image using the 'build' command.
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. If the
`db-url` option is set, this option is ignored.
--db-username <username>
The username of the database user.
Hostname:
--hostname <hostname>
Hostname for the Keycloak server.
--hostname-admin <hostname>
The hostname for accessing the administration console. Use this option if you
are exposing the administration console using a hostname other than the
value set to the 'hostname' option.
--hostname-path <path>
This should be set if proxy uses a different context-path for Keycloak.
--hostname-port <port>
The port used by the proxy when exposing the hostname. Set this option if the
proxy uses a port other than the default HTTP and HTTPS ports. Default: -1.
--hostname-strict <true|false>
Disables dynamically resolving the hostname from request headers. Should
always be set to true in production, unless proxy verifies the Host header.
Default: true.
--hostname-strict-backchannel <true|false>
By default backchannel URLs are dynamically resolved from request headers to
allow internal and external applications. If all applications use the public
URL this option should be enabled. Default: false.
HTTP/TLS:
--http-enabled <true|false>
Enables the HTTP listener. Default: false.
--http-host <host> The used HTTP Host. Default: 0.0.0.0.
--http-port <port> The used HTTP port. Default: 8080.
--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-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: 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 name.
--https-port <port> The used HTTPS port. Default: 8443.
--https-protocols <protocols>
The list of protocols to explicitly enable. Default: TLSv1.3.
--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 name.
Proxy:
--proxy <mode> The proxy address forwarding mode if the server is behind a reverse proxy.
Possible values are: edge,reencrypt,passthrough Default: none.
Vault:
--vault-dir <dir> If set, secrets can be obtained by reading the content of files within the
given directory.
Logging:
--log <handler> Enable one or more log handlers in a comma-separated list. Available log
handlers are: console,file,gelf Default: console.
--log-console-color <true|false>
Enable or disable colors when logging to console. Default: false.
--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.
--log-console-output <default|json>
Set the log output to JSON or default (plain) unstructured logging. Default:
default.
--log-file <path>/<file-name>.log
Set the log file path and filename. Default: data/log/keycloak.log.
--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.
--log-gelf-facility <name>
The facility (name of the process) that sends the message. Default: keycloak.
--log-gelf-host <hostname>
Hostname of the Logstash or Graylog Host. By default UDP is used, prefix the
host with 'tcp:' to switch to TCP. Example: 'tcp:localhost' Default:
localhost.
--log-gelf-include-location <true|false>
Include source code location. Default: true.
--log-gelf-include-message-parameters <true|false>
Include message parameters from the log event. Default: true.
--log-gelf-include-stack-trace <true|false>
If set to true, occuring stack traces are included in the 'StackTrace' field
in the gelf output. Default: true.
--log-gelf-max-message-size <size>
Maximum message size (in bytes). If the message size is exceeded, gelf will
submit the message in multiple chunks. Default: 8192.
--log-gelf-port <port>
The port the Logstash or Graylog Host is called on. Default: 12201.
--log-gelf-timestamp-format <pattern>
Set the format for the gelf timestamp field. Uses Java SimpleDateFormat
pattern. Default: yyyy-MM-dd HH:mm:ss,SSS.
--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.
By default, this command tries to update the server configuration by running a
'build' before starting the server. You can disable this behavior by using the
'--optimized' option:
$ kc.sh start '--optimized'
By doing that, the server should start faster based on any previous
configuration you have set when manually running the 'build' command.

View file

@ -0,0 +1,169 @@
Start the server.
Usage:
kc.bat start [OPTIONS]
Use this command to run the server in production.
Options:
-b, --auto-build (Deprecated) Automatically detects whether the server configuration changed
and a new server image must be built prior to starting the server. This
option provides an alternative to manually running the 'build' prior to
starting the server. Use this configuration carefully in production as it
might impact the startup time.
-h, --help This help message.
--help-all This same help message but with additional options.
--import-realm Import realms during startup by reading any realm configuration file from the
'data/import' directory.
--optimized Use this option to achieve an optional startup time if you have previously
built a server image using the 'build' command.
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. If the
`db-url` option is set, this option is ignored.
--db-username <username>
The username of the database user.
Hostname:
--hostname <hostname>
Hostname for the Keycloak server.
--hostname-admin <hostname>
The hostname for accessing the administration console. Use this option if you
are exposing the administration console using a hostname other than the
value set to the 'hostname' option.
--hostname-path <path>
This should be set if proxy uses a different context-path for Keycloak.
--hostname-port <port>
The port used by the proxy when exposing the hostname. Set this option if the
proxy uses a port other than the default HTTP and HTTPS ports. Default: -1.
--hostname-strict <true|false>
Disables dynamically resolving the hostname from request headers. Should
always be set to true in production, unless proxy verifies the Host header.
Default: true.
--hostname-strict-backchannel <true|false>
By default backchannel URLs are dynamically resolved from request headers to
allow internal and external applications. If all applications use the public
URL this option should be enabled. Default: false.
HTTP/TLS:
--http-enabled <true|false>
Enables the HTTP listener. Default: false.
--http-host <host> The used HTTP Host. Default: 0.0.0.0.
--http-port <port> The used HTTP port. Default: 8080.
--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-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: 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 name.
--https-port <port> The used HTTPS port. Default: 8443.
--https-protocols <protocols>
The list of protocols to explicitly enable. Default: TLSv1.3.
--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 name.
Proxy:
--proxy <mode> The proxy address forwarding mode if the server is behind a reverse proxy.
Possible values are: edge,reencrypt,passthrough Default: none.
Vault:
--vault-dir <dir> If set, secrets can be obtained by reading the content of files within the
given directory.
Logging:
--log <handler> Enable one or more log handlers in a comma-separated list. Available log
handlers are: console,file,gelf Default: console.
--log-console-color <true|false>
Enable or disable colors when logging to console. Default: false.
--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.
--log-console-output <default|json>
Set the log output to JSON or default (plain) unstructured logging. Default:
default.
--log-file <path>/<file-name>.log
Set the log file path and filename. Default: data\log\keycloak.log.
--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.
--log-gelf-facility <name>
The facility (name of the process) that sends the message. Default: keycloak.
--log-gelf-host <hostname>
Hostname of the Logstash or Graylog Host. By default UDP is used, prefix the
host with 'tcp:' to switch to TCP. Example: 'tcp:localhost' Default:
localhost.
--log-gelf-include-location <true|false>
Include source code location. Default: true.
--log-gelf-include-message-parameters <true|false>
Include message parameters from the log event. Default: true.
--log-gelf-include-stack-trace <true|false>
If set to true, occuring stack traces are included in the 'StackTrace' field
in the gelf output. Default: true.
--log-gelf-max-message-size <size>
Maximum message size (in bytes). If the message size is exceeded, gelf will
submit the message in multiple chunks. Default: 8192.
--log-gelf-port <port>
The port the Logstash or Graylog Host is called on. Default: 12201.
--log-gelf-timestamp-format <pattern>
Set the format for the gelf timestamp field. Uses Java SimpleDateFormat
pattern. Default: yyyy-MM-dd HH:mm:ss,SSS.
--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.
By default, this command tries to update the server configuration by running a
'build' before starting the server. You can disable this behavior by using the
'--optimized' option:
$ kc.bat start '--optimized'
By doing that, the server should start faster based on any previous
configuration you have set when manually running the 'build' command.

View file

@ -0,0 +1,169 @@
Start the server.
Usage:
kc.sh start [OPTIONS]
Use this command to run the server in production.
Options:
-b, --auto-build (Deprecated) Automatically detects whether the server configuration changed
and a new server image must be built prior to starting the server. This
option provides an alternative to manually running the 'build' prior to
starting the server. Use this configuration carefully in production as it
might impact the startup time.
-h, --help This help message.
--help-all This same help message but with additional options.
--import-realm Import realms during startup by reading any realm configuration file from the
'data/import' directory.
--optimized Use this option to achieve an optional startup time if you have previously
built a server image using the 'build' command.
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. If the
`db-url` option is set, this option is ignored.
--db-username <username>
The username of the database user.
Hostname:
--hostname <hostname>
Hostname for the Keycloak server.
--hostname-admin <hostname>
The hostname for accessing the administration console. Use this option if you
are exposing the administration console using a hostname other than the
value set to the 'hostname' option.
--hostname-path <path>
This should be set if proxy uses a different context-path for Keycloak.
--hostname-port <port>
The port used by the proxy when exposing the hostname. Set this option if the
proxy uses a port other than the default HTTP and HTTPS ports. Default: -1.
--hostname-strict <true|false>
Disables dynamically resolving the hostname from request headers. Should
always be set to true in production, unless proxy verifies the Host header.
Default: true.
--hostname-strict-backchannel <true|false>
By default backchannel URLs are dynamically resolved from request headers to
allow internal and external applications. If all applications use the public
URL this option should be enabled. Default: false.
HTTP/TLS:
--http-enabled <true|false>
Enables the HTTP listener. Default: false.
--http-host <host> The used HTTP Host. Default: 0.0.0.0.
--http-port <port> The used HTTP port. Default: 8080.
--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-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: 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 name.
--https-port <port> The used HTTPS port. Default: 8443.
--https-protocols <protocols>
The list of protocols to explicitly enable. Default: TLSv1.3.
--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 name.
Proxy:
--proxy <mode> The proxy address forwarding mode if the server is behind a reverse proxy.
Possible values are: edge,reencrypt,passthrough Default: none.
Vault:
--vault-dir <dir> If set, secrets can be obtained by reading the content of files within the
given directory.
Logging:
--log <handler> Enable one or more log handlers in a comma-separated list. Available log
handlers are: console,file,gelf Default: console.
--log-console-color <true|false>
Enable or disable colors when logging to console. Default: false.
--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.
--log-console-output <default|json>
Set the log output to JSON or default (plain) unstructured logging. Default:
default.
--log-file <path>/<file-name>.log
Set the log file path and filename. Default: data/log/keycloak.log.
--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.
--log-gelf-facility <name>
The facility (name of the process) that sends the message. Default: keycloak.
--log-gelf-host <hostname>
Hostname of the Logstash or Graylog Host. By default UDP is used, prefix the
host with 'tcp:' to switch to TCP. Example: 'tcp:localhost' Default:
localhost.
--log-gelf-include-location <true|false>
Include source code location. Default: true.
--log-gelf-include-message-parameters <true|false>
Include message parameters from the log event. Default: true.
--log-gelf-include-stack-trace <true|false>
If set to true, occuring stack traces are included in the 'StackTrace' field
in the gelf output. Default: true.
--log-gelf-max-message-size <size>
Maximum message size (in bytes). If the message size is exceeded, gelf will
submit the message in multiple chunks. Default: 8192.
--log-gelf-port <port>
The port the Logstash or Graylog Host is called on. Default: 12201.
--log-gelf-timestamp-format <pattern>
Set the format for the gelf timestamp field. Uses Java SimpleDateFormat
pattern. Default: yyyy-MM-dd HH:mm:ss,SSS.
--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.
By default, this command tries to update the server configuration by running a
'build' before starting the server. You can disable this behavior by using the
'--optimized' option:
$ kc.sh start '--optimized'
By doing that, the server should start faster based on any previous
configuration you have set when manually running the 'build' command.

View file

@ -0,0 +1,169 @@
Start the server.
Usage:
kc.bat start [OPTIONS]
Use this command to run the server in production.
Options:
-b, --auto-build (Deprecated) Automatically detects whether the server configuration changed
and a new server image must be built prior to starting the server. This
option provides an alternative to manually running the 'build' prior to
starting the server. Use this configuration carefully in production as it
might impact the startup time.
-h, --help This help message.
--help-all This same help message but with additional options.
--import-realm Import realms during startup by reading any realm configuration file from the
'data/import' directory.
--optimized Use this option to achieve an optional startup time if you have previously
built a server image using the 'build' command.
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. If the
`db-url` option is set, this option is ignored.
--db-username <username>
The username of the database user.
Hostname:
--hostname <hostname>
Hostname for the Keycloak server.
--hostname-admin <hostname>
The hostname for accessing the administration console. Use this option if you
are exposing the administration console using a hostname other than the
value set to the 'hostname' option.
--hostname-path <path>
This should be set if proxy uses a different context-path for Keycloak.
--hostname-port <port>
The port used by the proxy when exposing the hostname. Set this option if the
proxy uses a port other than the default HTTP and HTTPS ports. Default: -1.
--hostname-strict <true|false>
Disables dynamically resolving the hostname from request headers. Should
always be set to true in production, unless proxy verifies the Host header.
Default: true.
--hostname-strict-backchannel <true|false>
By default backchannel URLs are dynamically resolved from request headers to
allow internal and external applications. If all applications use the public
URL this option should be enabled. Default: false.
HTTP/TLS:
--http-enabled <true|false>
Enables the HTTP listener. Default: false.
--http-host <host> The used HTTP Host. Default: 0.0.0.0.
--http-port <port> The used HTTP port. Default: 8080.
--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-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: 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 name.
--https-port <port> The used HTTPS port. Default: 8443.
--https-protocols <protocols>
The list of protocols to explicitly enable. Default: TLSv1.3.
--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 name.
Proxy:
--proxy <mode> The proxy address forwarding mode if the server is behind a reverse proxy.
Possible values are: edge,reencrypt,passthrough Default: none.
Vault:
--vault-dir <dir> If set, secrets can be obtained by reading the content of files within the
given directory.
Logging:
--log <handler> Enable one or more log handlers in a comma-separated list. Available log
handlers are: console,file,gelf Default: console.
--log-console-color <true|false>
Enable or disable colors when logging to console. Default: false.
--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.
--log-console-output <default|json>
Set the log output to JSON or default (plain) unstructured logging. Default:
default.
--log-file <path>/<file-name>.log
Set the log file path and filename. Default: data\log\keycloak.log.
--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.
--log-gelf-facility <name>
The facility (name of the process) that sends the message. Default: keycloak.
--log-gelf-host <hostname>
Hostname of the Logstash or Graylog Host. By default UDP is used, prefix the
host with 'tcp:' to switch to TCP. Example: 'tcp:localhost' Default:
localhost.
--log-gelf-include-location <true|false>
Include source code location. Default: true.
--log-gelf-include-message-parameters <true|false>
Include message parameters from the log event. Default: true.
--log-gelf-include-stack-trace <true|false>
If set to true, occuring stack traces are included in the 'StackTrace' field
in the gelf output. Default: true.
--log-gelf-max-message-size <size>
Maximum message size (in bytes). If the message size is exceeded, gelf will
submit the message in multiple chunks. Default: 8192.
--log-gelf-port <port>
The port the Logstash or Graylog Host is called on. Default: 12201.
--log-gelf-timestamp-format <pattern>
Set the format for the gelf timestamp field. Uses Java SimpleDateFormat
pattern. Default: yyyy-MM-dd HH:mm:ss,SSS.
--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.
By default, this command tries to update the server configuration by running a
'build' before starting the server. You can disable this behavior by using the
'--optimized' option:
$ kc.bat start '--optimized'
By doing that, the server should start faster based on any previous
configuration you have set when manually running the 'build' command.