[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
This commit is contained in:
Lisa Cawley
GitHub
parent
a7456cd87d
commit
9f59ef6697
|
|
@ -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[]
|
||||
|
|
|
|||
|
|
@ -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 <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
|
||||
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 <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]
|
||||
|
|
@ -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
|
||||
----------------------------------------------------------------------
|
||||
|
|
@ -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]]
|
||||
|
|
|
|||
Loading…
Reference in New Issue