<#import "/templates/guide.adoc" as tmpl> <#import "/templates/kc.adoc" as kc> <#import "/templates/links.adoc" as links> <@tmpl.guide title="Importing and Exporting Realms" summary="An overview about how to import and export realms"> In this guide, you are going to understand the different approaches for importing and exporting realms using JSON files. == Providing options for database connection parameters When using the `export` and the `import` commands below, Keycloak needs to know how to connect to the database where the information about realms, clients, users and other entities is stored. As described in <@links.server id="configuration"/> that information can be provided as command line parameters, environment variables or a configuration file. Use the `--help` command line option for each command to see the available options. Some of the configuration options are build time configuration options. As default, Keycloak will re-build automatically for the `export` and `import` commands if it detects a change of a build time parameter. If you have built an optimized version of Keycloak with the `build` command as outlined in <@links.server id="configuration"/>, use the command line option `--optimized` to have Keycloak skip the build check for a faster startup time. When doing this, remove the build time options from the command line and keep only the runtime options. == Exporting a Realm to a Directory To export a realm, you can use the `export` command. Your Keycloak server instance must not be started when invoking this command. <@kc.export parameters="--help"/> To export a realm to a directory, you can use the `--dir ` option. <@kc.export parameters="--dir "/> When exporting realms to a directory, the server is going to create separate files for each realm being exported. === Configuring how users are exported You are also able to configure how users are going to be exported by setting the `--users ` option. The values available for this option are: * *different_files*: Users export into different json files, depending on the maximum number of users per file set by `--users-per-file`. This is the default value. * *skip*: Skips exporting users. * *realm_file*: Users will be exported to the same file as the realm settings. For a realm named "foo", this would be "foo-realm.json" with realm data and users. * *same_file*: All users are exported to one explicit file. So you will get two json files for a realm, one with realm data and one with users. If you are exporting users using the `different_files` strategy, you can set how many users per file you want by setting the `--users-per-file` option. The default value is `50`. <@kc.export parameters="--dir --users different_files --users-per-file 100"/> == Exporting a Realm to a File To export a realm to a file, you can use the `--file ` option. <@kc.export parameters="--file "/> When exporting realms to a file, the server is going to use the same file to store the configuration for all the realms being exported. == Exporting a specific realm If you do not specify a specific realm to export, all realms are exported. To export a single realm, you can use the `--realm` option as follows: <@kc.export parameters="[--dir|--file] --realm my-realm"/> == Importing a Realm from a Directory To import a realm, you can use the `import` command. Your Keycloak server instance must not be started when invoking this command. <@kc.import parameters="--help"/> After exporting a realm to a directory, you can use the `--dir ` option to import the realm back to the server as follows: <@kc.import parameters="--dir "/> When importing realms using the `import` command, you are able to set if existing realms should be skipped, or if they should be overridden with the new configuration. For that, you can set the `--override` option as follows: <@kc.import parameters="--dir --override false"/> By default, the `--override` option is set to `true` so that realms are always overridden with the new configuration. == Importing a Realm from a File To import a realm previously exported in a single file, you can use the `--file ` option as follows: <@kc.import parameters="--file "/> == Importing a Realm during Startup You are also able to import realms when the server is starting by using the `--import-realm` option. <@kc.start parameters="--import-realm"/> When you set the `--import-realm` option, the server is going to try to import any realm configuration file from the `data/import` directory. Only regular files using the `.json` extension are read from this directory, sub-directories are ignored. NOTE: For the https://quay.io/keycloak/keycloak[published containers], the import directory is `/opt/keycloak/data/import` If a realm already exists in the server, the import operation is skipped. The main reason behind this behavior is to avoid re-creating realms and potentially loose state between server restarts. To re-create realms you should explicitly run the `import` command prior to starting the server. Importing the `master` realm is not supported because as it is a very sensitive operation. === Using Environment Variables within the Realm Configuration Files When importing a realm at startup, you are able to use placeholders to resolve values from environment variables for any realm configuration. .Realm configuration using placeholders [source, bash] ---- { "realm": "${r"${MY_REALM_NAME}"}", "enabled": true, ... } ---- In the example above, the value set to the `MY_REALM_NAME` environment variable is going to be used to set the `realm` property.