WARNING: Version 6.2 of Elasticsearch has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
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.
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])
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 X-Pack 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
exist in the file
realm, they are skipped.
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 Elasticsearch.
-
-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 Elasticsearch 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 Elasticsearch.
-
-v, --verbose
- Shows verbose output.
Run the migrate tool after you install the X-Pack plugin. For example:
$ 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] 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:
$ bin/x-pack/migrate native -U http://localhost:9200 -u elastic -p x-pack-test-password -E path.conf=/etc/elasticsearch