Whamcloud - gitweb
LU-3531 doc: update lfs migrate and mkdir documentation. 92/17392/14
authorRichard Henwood <richard.henwood@intel.com>
Mon, 30 Nov 2015 17:55:00 +0000 (11:55 -0600)
committerOleg Drokin <oleg.drokin@intel.com>
Fri, 5 Feb 2016 23:12:42 +0000 (23:12 +0000)
lfs mkdir command has it's own man page. Update lfs main man page
to point directly at that page. lfs migrate is updated to accurately
record usage and limitations.

Signed-off-by: Richard Henwood <richard.henwood@intel.com>
Change-Id: Ie247f1f267a4d55a43ce5aaa734c8b8da487771c
Reviewed-on: http://review.whamcloud.com/17392
Reviewed-by: wangdi <di.wang@intel.com>
Tested-by: Jenkins
Reviewed-by: Andreas Dilger <andreas.dilger@intel.com>
Tested-by: Andreas Dilger <andreas.dilger@intel.com>
Reviewed-by: Oleg Drokin <oleg.drokin@intel.com>
lustre/doc/lfs-migrate.1 [new file with mode: 0644]

diff --git a/lustre/doc/lfs-migrate.1 b/lustre/doc/lfs-migrate.1
new file mode 100644 (file)
index 0000000..d3e2111
--- /dev/null
@@ -0,0 +1,66 @@
+.TH LFS-MIGRATE 1 2015-12-07 "Lustre" "Lustre Utilities"
+lfs migrate \- migrate files or directories between MDTs or OSTs.
+.B lfs migrate
+\fI-m mdt_idx\fR [-v|--verbose] \fI<directory>\fR
+.B lfs migrate
+.RI [OPTIONS] ... <file|directory>\fR...
+Migrate MDT inodes or OST objects between MDTs and OSTs respectively. For the
+case of MDT inode migration:
+.B migrate -m|--mdt-index <mdt_idx> \fIdirectory\fR
+Move the file metadata (inode) from one MDT to MDT with index \fBmdt_idx\fR.
+Migration of striped directories or individual files between MDTs is not
+currently supported. Only the root user can migrate directories.  Files that
+have been archived by HSM or are currently open are skipped by MDT inode
+migration. Access to files within the directory is blocked until migration is
+A migrated file or directory will have a new inode number and FID.  As
+a consequence, files archieved by Lustre HSM cannot currently be migrated
+and migrated files that have a new inode number may confuse backup tools.
+For the case of OST object migration:
+.B migrate
+.B [--stripe-count|-c \fIstripe_count\fR]
+.B [--stripe-index|-i \fIstart_ost_idx\fR]
+.B [--stripe-size|-S \fIstripe_size\fR]
+.B [--pool|-p \fIpool_name\fR]
+.B [--ost-list|-o \fIost_indices\fR]
+.B [--block|-b]
+.B [--non-block|-n] \fIfile|directory\fR
+Migrate can also be used for OST objects by omitting \fI-m\fR option. In this
+mode, the command has identical options to
+.BR lfs-setstripe (1).
+The difference between migrate and setstripe is that \fImigrate\fR will
+re-layout the data in existing files using the new layout parameter by copying
+the data from the existing OST(s) to the new OST(s). In contrast,
+\fIsetstripe\fR is used for creating new files with the specified layout.  For
+more information, see setstripe in lfs(1).
+NOTE: lfs migrate has a complementary script
+.B lfs_migrate
+which is used to provide extra functionality when migrating file data
+between OSTs and has a separate man page.
+Move the inodes contained in ./testremote from their current MDT to the
+MDT with index 0:
+.B $ lfs migrate -m 0 ./testremote
+The lfs command is part of the Lustre filesystem.
+.BR lfs (1),
+.BR lfs-setdirstripe (1),
+.BR lfs-getdirstripe (1),
+.BR lfs-mkdir (1),
+.BR lfs_migrate (1),
+.BR lctl (8),
index 6c1e5a3..0eda194 100644 (file)
@@ -11,6 +11,8 @@ lfs \- Lustre utility to create a file with specific striping pattern, find the
 .B lfs check <mds|osts|servers>
+.B lfs data_version [-n] \fB<filename>\fR
 .B lfs df [-i] [-h] [--lazy] [--pool|-p <fsname>[.<pool>] [path]
 .B lfs fid2path [--link <linkno>] <fsname|rootpath> <fid> ...
@@ -29,17 +31,30 @@ lfs \- Lustre utility to create a file with specific striping pattern, find the
 .B lfs getname [-h]|[path ...]
-.B lfs getstripe [--obd|-O <uuid>] [--quiet|-q] [--verbose|-v] 
+.B lfs getstripe [--obd|-O <uuid>] [--quiet|-q] [--verbose|-v]
         \fB[--stripe-count|-c ] [--stripe-index|-i] [--mdt-index|-M]
         \fB[--stripe-size|-S] [--directory|-d]
         \fB[--pool|-p] [--recursive|-r] [--raw|-R] <dirname|filename> ...\fR
-.B lfs setstripe [--stripe-size|-S stripe_size] [--stripe-count|-c stripe_count]
-        \fB[--stripe-index|-i start_ost_index] [--pool|-p <poolname>]
-        \fB[--ost-list|-o <ost_indices>] <directory|filename>\fR
+.B lfs migrate \fB-m <mdt_index>\fR
+.IR directory
-.B lfs setstripe -d <dir>
+.B lfs migrate [\fB-c | --stripe-count <stripe_count>\fR]
+               [\fB-i | --stripe-index <start_ost_idx>\fR]
+               [\fB-S | --stripe-size <stripe_size>\fR]
+               [\fB-p | --pool <pool_name>\fR]
+               [\fB-o | --ost-list <ost_indices>\fR]
+               [\fB-b | --block\fR]
+               [\fB-n | --non-block\fR]
+.IR file|directory
+.B lfs mkdir [\fB-c | --count <stripe_count>\fR]
+             [\fB-i | --index <mdt_idx>\fR]
+             [\fB-h | --hash-type <hash_name>\fR]
+             [\fB-m | --mode <mode>\fR]
+             [\fB-D | --default\fR]
+.IR directory
 .B lfs osts
 .RB [ path ]
@@ -71,25 +86,29 @@ lfs \- Lustre utility to create a file with specific striping pattern, find the
 .B lfs setquota -t <-u|-g>
-             \fB[--block-grace <block-grace>]
-             \fB[--inode-grace <inode-grace>]
+             \fB[--block-grace <block-grace>]\fR
+             \fB[--inode-grace <inode-grace>]\fR
 .B lfs setquota -t <-u|-g>
-             \fB[-b <block-grace>] [-i <inode-grace>]
+             \fB[-b <block-grace>] [-i <inode-grace>]\fR
+.B lfs setstripe [--stripe-size|-S stripe_size] [--stripe-count|-c stripe_count]
+        \fB[--stripe-index|-i start_ost_index] [--pool|-p <poolname>]
+        \fB[--ost-list|-o <ost_indices>] <directory|filename>\fR
-.B lfs swap_layouts <filename1> <filename2>
-.B lfs data_version [-n] \fB<filename>\fR
+.B lfs setstripe -d <dir>
 .B lfs --version
 .B lfs help
 .B lfs
-can be used to create a new file with a specific striping pattern, determine the default striping pattern, gather the extended attributes (object numbers and location) for a specific file. It can be invoked interactively without any arguments or in a non-interactive mode with one of the arguements supported. 
+can be used to create a new file with a specific striping pattern, determine
+the default striping pattern, gather the extended attributes (object numbers
+and location) for a specific file. It can be invoked interactively without any
+arguments or in a non-interactive mode with one of the arguments supported.
 The various options supported by lfs are listed and explained below:
@@ -102,7 +121,7 @@ interest to a particular consumer <id>, potentially allowing the MDT to
 free up disk space. An <endrec> of 0 indicates the current last record.
 Changelog consumers must be registered on the MDT node using \fBlctl\fR.
-.B check 
+.B check
 Display the status of MDS or OSTs (as specified in the command) or all the servers (MDS and OSTs)
 .B df [-i] [-h] [--lazy] [--pool|-p <fsname>[.<pool>] [path]
@@ -116,7 +135,7 @@ The \fB--lazy\fR/\fB-l\fR option skips any OST that is currently disconnected
 from the client.  This avoids blocking the \fBdf\fR output if an OST is down,
 and only returns the space on the OSTs that can currently be accessed.
-.B find 
+.B find
 To search the directory tree rooted at the given dir/file name for the files that match the given parameters: \fB--atime\fR (file was last accessed N*24 hours ago), \fB--ctime\fR (file's status was last changed N*24 hours ago), \fB--mtime\fR (file's data was last modified N*24 hours ago), \fB--obd\fR (file has an object on a specific OST or OSTs), \fB--size\fR (file has size in bytes, or \fBk\fRilo-, \fBM\fRega-, \fBG\fRiga-, \fBT\fRera-, \fBP\fReta-, or \fBE\fRxabytes if a suffix is given), \fB--type\fR (file has the type: \fBb\fRlock, \fBc\fRharacter, \fBd\fRirectory, \fBp\fRipe, \fBf\fRile, sym\fBl\fRink, \fBs\fRocket, or \fBD\fRoor (Solaris)), \fB--uid\fR (file has specific numeric user ID), \fB--user\fR (file owned by specific user, numeric user ID allowed), \fB--gid\fR (file has specific group ID), \fB--group\fR (file belongs to specific group, numeric group ID allowed), \fB--layout\fR (file has a raid0 layout or is released). The option \fB--maxdepth\fR limits find to decend at most N levels of directory tree. The options \fB--print\fR and \fB--print0\fR print full file name, followed by a newline or NUL character correspondingly.  Using \fB!\fR before an option negates its meaning (\fIfiles NOT matching the parameter\fR).  Using \fB+\fR before a numeric value means \fIfiles with the parameter OR MORE\fR, while \fB-\fR before a numeric value means \fIfiles with the parameter OR LESS\fR.
 .B getname [-h]|[path ...]
@@ -125,13 +144,13 @@ instance. If one or more \fBpath\fR entries are provided, then only the
 Lustre instance for these mount points is returned. If the path given is not on
 a Lustre instance 'No such device' is reported.
-.B osts 
+.B osts
 .RB [ path ]
 List all the OSTs for all mounted filesystems. If a \fBpath\fR is provided
 that is located on a lustre mounted file system then only the OSTs belonging
 to that filesystem are displayed.
-.B getstripe [--obd|-O <uuid>] [--quiet|-q] [--verbose|-v] 
+.B getstripe [--obd|-O <uuid>] [--quiet|-q] [--verbose|-v]
         \fB[--count | -c ] [--index | -i | --offset | -o  ]
         \fB[--pool | -p ] [--size | -s ] [--directory | -d ]
         \fB[--layout | -L]
@@ -146,7 +165,7 @@ only want specific striping information then the options of
 .BR --offset ,
 .BR --layout ,
-.B --pool  
+.B --pool
 can be used to return only the specific fields.
 If the
@@ -256,7 +275,7 @@ line, tab-separated.
 .B pool_list
 .RI { filesystem }[ .poolname "] | {" pathname }
-List the pools in 
+List the pools in
 .I filesystem
 .IR pathname ,
@@ -301,32 +320,27 @@ Even without -n, race conditions are possible and data version should be
 checked before and after an operation to be confident the data did not change
 during it.
-.B mkdir <--index|-i mdt_index> <dir>
-Allocate a new directory on a specified MDT.  
-The "lfs mkdir" command is only executable by root unless
-"mdt.*.enable_remote_dir_gid" is set via "lctl set_param" to be either a
-non-zero GID to limit it to a single group (e.g. "operator" or "admin"),
-or "-1" to allow any group to create remote directories.
-The root of the file system is on MDT0000, and directories and files inherit the
-MDT of their parent directory unless a different MDT is specified with this
-By default, only directories on MDT0000 can contain directories that are not on
-the same MDT.  However, if "mdt.*.enable_remote_dir" is set non-zero on an MDT
-then it will allow creating remote directories that have parents other than
-MDT0000. This is restricted to avoid creating directory trees that have
-intermediate path components on a series different MDTs and become unavailable
-if any of the intermediate MDTs are offline.
+.B mkdir
+lfs mkdir is documented in the man page: lfs-mkdir(1). NOTE:
+.B lfs setdirstripe
+is an alias of the command
+.B lfs mkdir
+.B mv
+lfs mv is deprecated, use lfs
+.B migrate
+.B migrate
+See lfs-migrate(1).
 .B --version
 Output the build version of the lfs utility. Use "lctl lustre_build_version" to get the version of the Lustre kernel modules
-.B help 
+.B help
 Provides brief help on the various arguments
-.B exit/quit 
+.B exit/quit
 Quit the interactive lfs session
@@ -348,16 +362,16 @@ Recursively list all regular files in given directory more than 30 days old
 .B $ lfs find --obd OST2-UUID /mnt/lustre/
 Recursively list all files in a given directory that have objects on OST2-UUID.
-.B $ lfs check servers 
+.B $ lfs check servers
 Check the status of all servers (MDT, OST)
 .B $ lfs osts
 List all the OSTs
-.B $ lfs df -h 
+.B $ lfs df -h
 Lists space usage per OST and MDT in human readable format.
-.B $ lfs df -i 
+.B $ lfs df -i
 Lists inode usage per OST and MDT
 .B $ lfs df --pool <filesystem>[.<pool>] | <pathname>
@@ -396,5 +410,7 @@ The lfs command is part of the Lustre filesystem.
 .BR lfs-setdirstripe (1),
 .BR lfs-getdirstripe (1),
 .BR lfs-mkdir (1),
+.BR lfs_migrate (1),
+.BR lfs-migrate (1),
 .BR lctl (8),
 .BR lustre (7)
index e5370e9..9059890 100644 (file)
@@ -356,13 +356,29 @@ command_t cmdlist[] = {
        {"swap_layouts", lfs_swap_layouts, 0, "Swap layouts between 2 files.\n"
         "usage: swap_layouts <path1> <path2>"},
        {"migrate", lfs_setstripe, 0,
-        "migrate file/directory between MDTs, or migrate file from one OST "
+        "migrate a directory between MDTs.\n"
+        "usage: migrate --mdt-index <mdt_idx> [--verbose|-v] "
+        "<directory>\n"
+        "\tmdt_idx:      index of the destination MDT\n"},
+       {"migrate", lfs_setstripe, 0,
+        "migrate file objects from one OST "
         "layout\nto another (may be not safe with concurent writes).\n"
-        "usage: migrate   [--mdt-index|-m <mdt_idx>] [--verbose|-v] "
-        "<directory|filename>\n"
-        "\tmdt_idx:      MDT index to migrate to\n"
-        " or\n"
-        MIGRATE_USAGE},
+        "usage: migrate "
+        "[--stripe-count|-c] <stripe_count>\n"
+        "[--stripe-index|-i] <start_ost_index>\n"
+        "[--stripe-size|-S] <stripe_size>\n"
+        "[--pool|-p] <pool_name>\n"
+        "[--ost-list|-o] <ost_indices>\n"
+        "[--block|-b]\n"
+        "[--non-block|-n]\n"
+        "<file|directory>\n"
+        "\tstripe_count:     number of OSTs to stripe a file over\n"
+        "\tstripe_ost_index: index of the first OST to stripe a file over\n"
+        "\tstripe_size:      number of bytes to store before moving to the next OST\n"
+        "\tpool_name:        name of the predefined pool of OSTs\n"
+        "\tost_indices:      OSTs to stripe over, in order\n"
+        "\tblock:            wait for the operation to return before continuing\n"
+        "\tnon-block:        do not wait for the operation to return.\n"},
        {"mv", lfs_mv, 0,
         "To move directories between MDTs. This command is deprecated, "
         "use \"migrate\" instead.\n"