[DOCS] Move migrate tool reference (elastic/x-pack-elasticsearch#3011)

* [DOCS] Move migrate tool reference

* [DOCS] Fixed link to migration tool

* [DOCS] Small edits to the migrate tool parameters

* [DOCS] Fixed migrate tool example

Original commit: elastic/x-pack-elasticsearch@0ff40ebdcc

docs/en/commands/index.asciidoc

@@ -8,6 +8,7 @@
 {xpack} includes commands that help you configure security:
 
 * <<certgen>>
+* <<migrate-tool>>
 * <<setup-passwords>>
 * <<syskeygen>>
 * <<users-command>>
@@ -15,6 +16,7 @@
 --
 
 include::certgen.asciidoc[]
+include::migrate-tool.asciidoc[]
 include::setup-passwords.asciidoc[]
 include::syskeygen.asciidoc[]
 include::users-command.asciidoc[]

docs/en/commands/migrate-tool.asciidoc

@@ -1,9 +1,27 @@
+[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 <url>)
+[-h, --help] [-E <KeyValuePair>]
+[-n, --users <uids>] [-r, --roles <roles>]
+[-u, --username <uid>] [-p, --password <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
@@ -17,12 +35,50 @@ 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 <KeyValuePair>`::
+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]
@@ -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
 ----------------------------------------------------------------------

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
-<<migrate-tool, migrate>> tool.
+{ref}/migrate-tool.html[migrate tool].
 
 [float]
 [[native-add]]