[ndctl] ndctl/namespace: Clarify that 'reconfigure' == 'destroy+create'
diff mbox series

Message ID 157237178347.4146560.10127156903020487402.stgit@dwillia2-desk3.amr.corp.intel.com
State Accepted
Commit e7f04874e7575148cac7b7b1c0d9d321531c99de
Headers show
Series
  • [ndctl] ndctl/namespace: Clarify that 'reconfigure' == 'destroy+create'
Related show

Commit Message

Dan Williams Oct. 29, 2019, 5:56 p.m. UTC
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(-)

Patch
diff mbox series

diff --git a/Documentation/ndctl/ndctl-create-namespace.txt b/Documentation/ndctl/ndctl-create-namespace.txt
index e29a5e75e43c..45a4c4c2f408 100644
--- a/Documentation/ndctl/ndctl-create-namespace.txt
+++ b/Documentation/ndctl/ndctl-create-namespace.txt
@@ -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=::