diff --git a/docs/en/commands/index.asciidoc b/docs/en/commands/index.asciidoc index 69811a9fc8d..2bdc5ec6645 100644 --- a/docs/en/commands/index.asciidoc +++ b/docs/en/commands/index.asciidoc @@ -8,6 +8,7 @@ {xpack} includes commands that help you configure security: * <> +* <> * <> * <> * <> @@ -15,6 +16,7 @@ -- include::certgen.asciidoc[] +include::migrate-tool.asciidoc[] include::setup-passwords.asciidoc[] include::syskeygen.asciidoc[] include::users-command.asciidoc[] diff --git a/docs/en/security/authentication/migrate-tool.asciidoc b/docs/en/commands/migrate-tool.asciidoc similarity index 53% rename from docs/en/security/authentication/migrate-tool.asciidoc rename to docs/en/commands/migrate-tool.asciidoc index 1e23be99e65..373f4cb61d0 100644 --- a/docs/en/security/authentication/migrate-tool.asciidoc +++ b/docs/en/commands/migrate-tool.asciidoc @@ -1,28 +1,84 @@ +[role="xpack"] [[migrate-tool]] -==== Migrating File-based Users and Roles to the Native Realm +== migrate -From 5.0 onward, you should use the `native` realm to manage roles and local -users. To migrate existing file-based users and roles to the native realm, use -the `migrate` tool that's included with the X-Pack plugin. +The `migrate` command migrates existing file-based users and roles to the native +realm. From 5.0 onward, you should use the `native` realm to manage roles and +local users. + + +[float] +=== Synopsis + +[source,shell] +-------------------------------------------------- +bin/x-pack/migrate +(native (-U, --url ) +[-h, --help] [-E ] +[-n, --users ] [-r, --roles ] +[-u, --username ] [-p, --password ] +[-s, --silent] [-v, --verbose]) +-------------------------------------------------- + +[float] +=== Description NOTE: When migrating from Shield 2.x, the `migrate` tool should be run prior to upgrading to ensure all roles can be migrated as some may be in a deprecated format that {xpack} cannot read. The `migrate` tool is available in Shield 2.4.0 and higher. -The `migrate` tool loads the existing file-based users and roles and calls the -user and roles APIs to add them to the native realm. You can migrate all users -and roles, or specify the ones you want to migrate. Users and roles that -already exist in the `native` realm are not replaced or overridden. If -the names you specify with the `--users` and `--roles` options don't +The `migrate` tool loads the existing file-based users and roles and calls the +user and roles APIs to add them to the native realm. You can migrate all users +and roles, or specify the ones you want to migrate. Users and roles that +already exist in the `native` realm are not replaced or overridden. If +the names you specify with the `--users` and `--roles` options don't exist in the `file` realm, they are skipped. +[float] +[[migrate-tool-options]] +=== Parameters +The `native` subcommand supports the following options: + +`-E `:: +Configures a setting. + +`-h, --help`:: +Returns all of the command parameters. + +`-n`, `--users`:: +Comma-separated list of the users that you want to migrate. If this parameter is +not specified, all users are migrated. + +`-p`, `--password`:: +Password to use for authentication with {es}. +//TBD: What is the default if this isn't specified? + +`-r`, `--roles`:: +Comma-separated list of the roles that you want to migrate. If this parameter is +not specified, all roles are migrated. + +`-s, --silent`:: Shows minimal output. + +`-U`, `--url`:: +Endpoint URL of the {es} cluster to which you want to migrate the +file-based users and roles. This parameter is required. + +`-u`, `--username`:: +Username to use for authentication with {es}. +//TBD: What is the default if this isn't specified? + +`-v, --verbose`:: Shows verbose output. + +[float] +=== Examples + Run the migrate tool after you install the X-Pack plugin. For example: [source, sh] ---------------------------------------------------------------------- -$ bin/x-pack/migrate native -U http://localhost:9200 -u elastic -p x-pack-test-password --n lee,foo -r role1,role2,role3,role4,foo +$ bin/x-pack/migrate native -U http://localhost:9200 -u elastic +-p x-pack-test-password -n lee,foo -r role1,role2,role3,role4,foo starting migration of users and roles... importing users from [/home/es/config/shield/users]... found existing users: [test_user, joe3, joe2] @@ -30,9 +86,9 @@ migrating user [lee] {"user":{"created":true}} no user [foo] found, skipping importing roles from [/home/es/config/shield/roles.yml]... -found existing roles: [marvel_user, role_query_fields, admin_role, role3, admin, -remote_marvel_agent, power_user, role_new_format_name_array, role_run_as, -logstash, role_fields, role_run_as1, role_new_format, kibana4_server, user, +found existing roles: [marvel_user, role_query_fields, admin_role, role3, admin, +remote_marvel_agent, power_user, role_new_format_name_array, role_run_as, +logstash, role_fields, role_run_as1, role_new_format, kibana4_server, user, transport_client, role1.ab, role_query] migrating role [role1] {"role":{"created":true}} @@ -43,31 +99,11 @@ no role [foo] found, skipping users and roles imported. ---------------------------------------------------------------------- -[[migrate-tool-options]] -The `native` subcommand supports the following options: - -`-U`, `--url`:: -Endpoint URL of the Elasticsearch cluster to which you want to migrate the -file-based users and roles. Required. - -`-u`, `--username`:: -Username to use for authentication. - -`-p`, `--password`:: -Password to use for authentication. - -`-n`, `--users`:: -Comma-separated list of the users you want to migrate. If not specified, all -users are migrated. - -`-r`, `--roles`:: -Comma-separated list of the roles you want to migrate. If not specified, all -roles are migrated. - Additionally, the `-E` flag can be used to specify additional settings. For example to specify a different configuration directory, the command would look like: [source, sh] ---------------------------------------------------------------------- -$ bin/x-pack/migrate native -U http://localhost:9200 -u elastic -p x-pack-test-password --path.conf /etc/elasticsearch +$ bin/x-pack/migrate native -U http://localhost:9200 -u elastic +-p x-pack-test-password -E path.conf=/etc/elasticsearch ---------------------------------------------------------------------- diff --git a/docs/en/security/authentication/native-realm.asciidoc b/docs/en/security/authentication/native-realm.asciidoc index 1bd05a49f05..f417d60e9e5 100644 --- a/docs/en/security/authentication/native-realm.asciidoc +++ b/docs/en/security/authentication/native-realm.asciidoc @@ -92,7 +92,7 @@ You manage users in the `native` realm through the [[migrating-from-file]] NOTE: To migrate file-based users to the `native` realm, use the -<> tool. +{ref}/migrate-tool.html[migrate tool]. [float] [[native-add]]