1---
2layout: docs
3page_title: operator migrate - Command
4description: >-
5  The "operator migrate" command copies data between storage backends to
6  facilitate
7
8  migrating Vault between configurations. It operates directly at the storage
9
10  level, with no decryption involved.
11---
12
13# operator migrate
14
15The `operator migrate` command copies data between storage backends to facilitate
16migrating Vault between configurations. It operates directly at the storage
17level, with no decryption involved. Keys in the destination storage backend will
18be overwritten, and the destination should _not_ be initialized prior to the
19migrate operation. The source data is not modified, with the exception of a small lock
20key added during migration.
21
22This is intended to be an offline operation to ensure data consistency, and Vault
23will not allow starting the server if a migration is in progress.
24
25## Examples
26
27Migrate all keys:
28
29```shell-session
30$ vault operator migrate -config migrate.hcl
31
322018-09-20T14:23:23.656-0700 [INFO ] copied key: data/core/seal-config
332018-09-20T14:23:23.657-0700 [INFO ] copied key: data/core/wrapping/jwtkey
342018-09-20T14:23:23.658-0700 [INFO ] copied key: data/logical/fd1bed89-ffc4-d631-00dd-0696c9f930c6/31c8e6d9-2a17-d98f-bdf1-aa868afa1291/archive/metadata
352018-09-20T14:23:23.660-0700 [INFO ] copied key: data/logical/fd1bed89-ffc4-d631-00dd-0696c9f930c6/31c8e6d9-2a17-d98f-bdf1-aa868afa1291/metadata/5kKFZ4YnzgNfy9UcWOzxxzOMpqlp61rYuq6laqpLQDnB3RawKpqi7yBTrawj1P
36...
37```
38
39Migration is done in a consistent, sorted order. If the migration is halted or
40exits before completion (e.g. due to a connection error with a storage backend),
41it may be resumed from an arbitrary key prefix:
42
43```shell-session
44$ vault operator migrate -config migrate.hcl -start "data/logical/fd"
45```
46
47## Configuration
48
49The `operator migrate` command uses a dedicated configuration file to specify the source
50and destination storage backends. The format of the storage stanzas is identical
51to that used to [configure Vault](/docs/configuration/storage),
52with the only difference being that two stanzas are required: `storage_source` and `storage_destination`.
53
54```hcl
55storage_source "mysql" {
56  username = "user1234"
57  password = "secret123!"
58  database = "vault"
59}
60
61storage_destination "consul" {
62  address = "127.0.0.1:8500"
63  path    = "vault"
64}
65```
66
67## Migrating to integrated raft storage
68
69### Example Configuration
70
71The below configuration will migrate away from Consul storage to integrated
72raft storage. The raft data will be stored on the local filesystem in the
73defined `path`. `node_id` can optionally be set to identify this node.
74[cluster_addr](/docs/configuration#cluster_addr) must be set to the
75cluster hostname of this node. For more configuration options see the [raft
76storage configuration documentation](/docs/configuration/storage/raft).
77
78If the original configuration uses "raft" for `ha_storage` a different
79`path` needs to be declared for the path in `storage_destination` and the new
80configuration for the node post-migration.
81
82```hcl
83storage_source "consul" {
84  address = "127.0.0.1:8500"
85  path    = "vault"
86}
87
88storage_destination "raft" {
89  path = "/path/to/raft/data"
90  node_id = "raft_node_1"
91}
92cluster_addr = "http://127.0.0.1:8201"
93```
94
95### Run the migration
96
97Vault will need to be offline during the migration process. First, stop Vault.
98Then, run the migration on the server you wish to become a the new Vault node.
99
100```shell-session
101$ vault operator migrate -config migrate.hcl
102
1032018-09-20T14:23:23.656-0700 [INFO ] copied key: data/core/seal-config
1042018-09-20T14:23:23.657-0700 [INFO ] copied key: data/core/wrapping/jwtkey
1052018-09-20T14:23:23.658-0700 [INFO ] copied key: data/logical/fd1bed89-ffc4-d631-00dd-0696c9f930c6/31c8e6d9-2a17-d98f-bdf1-aa868afa1291/archive/metadata
1062018-09-20T14:23:23.660-0700 [INFO ] copied key: data/logical/fd1bed89-ffc4-d631-00dd-0696c9f930c6/31c8e6d9-2a17-d98f-bdf1-aa868afa1291/metadata/5kKFZ4YnzgNfy9UcWOzxxzOMpqlp61rYuq6laqpLQDnB3RawKpqi7yBTrawj1P
107...
108```
109
110After migration has completed, the data is stored on the local file system. To
111use the new storage backend with Vault, update Vault's configuration file as
112described in the [raft storage configuration
113documentation](/docs/configuration/storage/raft). Then start and unseal the
114vault server.
115
116### Join additional nodes
117
118After migration the raft cluster will only have a single node. Additional peers
119should be joined to this node.
120
121If the cluster was previously HA-enabled using "raft" as the `ha_storage`, the
122nodes will have to re-join to the migrated node before unsealing.
123
124## Usage
125
126The following flags are available for the `operator migrate` command.
127
128- `-config` `(string: <required>)` - Path to the migration configuration file.
129
130- `-start` `(string: "")` - Migration starting key prefix. Only keys at or after this value will be copied.
131
132- `-reset` - Reset the migration lock. A lock file is added during migration to prevent
133  starting the Vault server or another migration. The `-reset` option can be used to
134  remove a stale lock file if present.
135