@@ -116,12 +116,21 @@ OPTIONS
-e::
--reconfig=::
- Reconfigure an existing namespace (change the mode, sector size,
- etc...). All namespace parameters, save uuid, default to the
- current attributes of the specified namespace. The namespace is
- then re-created with the specified modifications. The uuid is
- refreshed to a new value by default whenever the data layout of
- a namespace is changed, see --uuid= to set a specific uuid.
+ Reconfigure an existing namespace. This option is a shortcut for
+ the following sequence:
+
+ - Read all parameters from @victim_namespace
+ - Destroy @victim_namespace
+ - Create @new_namespace merging old parameters with new ones
+::
+ Note that the major implication of a destroy-create cycle is
+ that data from @victim_namespace is not preserved in
+ @new_namespace. The attributes transferred from
+ @victim_namespace are the geometry, mode, and name (not uuid
+ without --uuid=). No attempt is made to preserve the data and
+ any old data that is visible in @new_namespace is by coincidence
+ not convention. "Backup and restore" is the only reliable method
+ to populate @new_namespace with data from @victim_namespace.
-u::
--uuid=::
The 'reconfigure' option to create-namespace is simply a shortcut for the following flow: - Read all parameters from @victim_namespace - Destroy @victim_namespace - Create @new_namespace merging old parameters with new ones Critically this process makes no attempt to preserve data. In fact previous data is almost always destroyed except for cases where the mode remains 'raw' over the transition. Even there the create step may choose new free space for @new_namespace that was not previously allocated to @victim_namespace. For reconfigurations where the target mode is 'fsdax' or 'devdax' any size increase may increase the size of metadata needed at the start of the namespace and overwrite previous data from @victim_namespace. Highlight these details in the man page to preclude assumptions that the a namespace can be reconfigured while keeping existing data intact. Reported-by: Seema Pandit <seema.pandit@intel.com> Reported-by: Bharath Venkatesh <bharath.venkatesh@intel.com> Signed-off-by: Dan Williams <dan.j.williams@intel.com> --- Documentation/ndctl/ndctl-create-namespace.txt | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-)