[role="xpack"]
[testenv="gold+"]
[[migrate-tool]]
== elasticsearch-migrate

The `elasticsearch-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/elasticsearch-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 `elasticsearch-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 `elasticsearch-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 <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 `elasticsearch-migrate` tool when {xpack} is installed. For example:

[source, sh]
----------------------------------------------------------------------
$ bin/elasticsearch-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]
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,
transport_client, role1.ab, role_query]
migrating role [role1]
{"role":{"created":true}}
migrating role [role2]
{"role":{"created":true}}
role [role3] already exists, skipping
no role [foo] found, skipping
users and roles imported.
----------------------------------------------------------------------

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/elasticsearch-migrate native -U http://localhost:9200 -u elastic
-p x-pack-test-password -E path.conf=/etc/elasticsearch
----------------------------------------------------------------------