Whamcloud - gitweb
LU-8998 docs: man pages for tools of PFL
authorNiu Yawei <yawei.niu@intel.com>
Wed, 24 Feb 2016 07:28:30 +0000 (02:28 -0500)
committerJinshan Xiong <jinshan.xiong@intel.com>
Thu, 6 Apr 2017 04:52:59 +0000 (21:52 -0700)
Added new options to 'lfs find' and 'lfs getstripe' for composite
files. Moved "lfs setstripe/migrate" into separate man page, and
added new options for the operations to composite file.

Signed-off-by: Niu Yawei <yawei.niu@intel.com>
Change-Id: I9cafde834be5c3d890bf04a3efb2ea973364596a
Reviewed-on: https://review.whamcloud.com/25741
Tested-by: Jenkins
Reviewed-by: Bobi Jam <bobijam@hotmail.com>
Tested-by: Maloo <hpdd-maloo@intel.com>
Reviewed-by: James Nunez <james.a.nunez@intel.com>
Reviewed-by: Jinshan Xiong <jinshan.xiong@intel.com>
lustre/doc/lfs-setstripe.1 [new file with mode: 0644]

index d3e2111..7a8609d 100644 (file)
@@ -36,6 +36,7 @@ For the case of OST object migration:
 .B [--ost-list|-o \fIost_indices\fR]
 .B [--block|-b]
 .B [--non-block|-n] \fIfile|directory\fR
+.B [--component-end|-E \fIcomp_end\fR]
 Migrate can also be used for OST objects by omitting \fI-m\fR option. In this
 mode, the command has identical options to
@@ -44,21 +45,28 @@ 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).
+more information, see lfs-setstripe(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
+Move the inodes contained in ./testremote from their current MDT to the
+MDT with index 0.
+.B $ lfs migrate -c 2 /mnt/lustre/file1
+This migrate the file into a new layout with 2 stripes.
+.B $ lfs migrate -E 64M -c 1 -E 256M -c 4 -E -1 -c -1 /mnt/lustre/file1
+This migrate the file into a three components composite layout.
 The lfs command is part of the Lustre filesystem.
 .BR lfs (1),
+.BR lfs-setstripe (1),
 .BR lfs-setdirstripe (1),
 .BR lfs-getdirstripe (1),
 .BR lfs-mkdir (1),
diff --git a/lustre/doc/lfs-setstripe.1 b/lustre/doc/lfs-setstripe.1
new file mode 100644 (file)
index 0000000..9c9f68a
--- /dev/null
@@ -0,0 +1,169 @@
+.TH LFS-SETSTRIPIE 1 2015-11-06 "Lustre" "Lustre Utilities"
+lfs setstripe \- set striping pattern of a file.
+.B lfs setstripe [\fISTRIPE_OPTIONS\fR] <directory|filename>
+.B lfs setstripe -d <directory>
+.B lfs setstripe <--component-end|-E end1> [\fISTRIPE_OPTIONS\fR] \
+[<--component-end|-E end2> [\fISTRIPE_OPTIONS\fR] ...] <filename>
+.B lfs setstripe --component-add <--component-end|-E end1> [\fISTRIPE_OPTIONS\fR] \
+[<--component-end|-E end2> [\fISTRIPE_OPTIONS\fR] ...] <filename>
+.B lfs setstripe --component-del <--component-id|-I comp_id | \
+--component-flags comp_flags> <filename>
+.B lfs setstripe [\fISTRIPE_OPTIONS\fR] <directory|filename>
+Create a file with specified striping pattern, or set default stripping pattern
+to a directory.
+.B lfs setstripe -d <directory>
+Delete the default striping on the specified directory.
+.B lfs setstripe <--component-end|-E end1> [\fISTRIPE_OPTIONS\fR] \
+[<--component-end|-E end2> [\fISTRIPE_OPTIONS\fR] ...] <filename>
+Create a file with the specified composite layout. Each component defines the
+stripe pattern of the file in the range of [start, end). The first component
+must start from offset 0, and all components must be adjacent with each other,
+no holes are allowed, so each extent will start at the end of previous extent.
+.I -E
+option is used to specify the end offset of each component, and it also
+indicates the following \fISTRIPE_OPTIONS\fR are for this component. A -1 end
+offset indicates the EOF.
+.B lfs setstripe --component-add <--component-end|-E end1> [\fISTRIPE_OPTIONS\fR] \
+[<--component-end|-E end2> [\fISTRIPE_OPTIONS\fR] ...] <filename>
+Add components to an existing composite file. The extent start of the first
+component to be added is equal to the extent end of last component in existing
+file, and all components to be added must be adjacent with each other.
+.B lfs setstripe --component-del <--component-id|-I comp_id | \
+--component-flags comp_flags> <filename>
+Remove the component(s) specified by component ID or flags from an existing
+file. The ID specified by
+.I -I
+option is the numerical unique ID of the component, it can be obtained using
+.B lfs getstripe
+.I --component-flags
+option is used to specify certain type of components, such as all instantiated
+The various stripe related options are listed and explained below:
+.B -c, --stripe-count <\fIstripe_count\fR>
+The number of OSTs to stripe a file over. 0 means to use the filesystem-wide
+default stripe count (default 1), and -1 means to stripe over all available
+.B -S, --stripe-size <\fIstripe_size\fR>
+The number of bytes to store on each OST before moving to the next OST. 0 means
+to use the filesystem-wide default stripe_size (default 1MB).
+.B -i, --stripe-index <\fIstart_ost_index\fR>
+The OST index (starting at 0) on which to start striping for this file. -1
+allows the MDS to choose the starting index and it is strongly recommended, as
+this allows space and load balancing to be done by the MDS as needed.
+.B -o, --ost-list <\fIost_indices\fR>
+Used to specify the exact stripe layout on the file system. \fIost_indices\fR
+is a list of OSTs referenced by their indices, which are specified in decimal
+or hex form and can be obtained using the
+.B lfs osts
+command. The list format consists of individual OST indices and index ranges
+separated by commas, e.g. 1,2-4,7. The
+.B -o
+option may be specified multiple times to stripe across the union of all listed
+OSTs. If the
+.B -c
+option is combined with
+.B -o
+.I stripe_count
+must agree with the number of OSTs in
+.IR ost_indices .
+If the
+.B -i
+option is combined with
+.B -o
+.I start_ost_index
+must be in the OST list, and it will be used as the index on which to start
+striping the file. Otherwise the striping will occur in the order specified in
+.IR ost_indices .
+.B -p, --pool <\fIpool_name\fR>
+The name of a predefined pool of OSTs (see
+.BR lctl (8))
+that will be used for striping. The
+.IR stripe_count ,
+.IR stripe_size ,
+.I start_ost_index
+will be used as well; the
+.I start_ost_index
+must be part of the pool or an error will be returned.
+There are two options available only for \fBlfs migrate\fR:
+.B -b, --block
+Block file access during data migration (default).
+.B -n, --non-block
+Abort migrations if concurrent access is detected.
+The various component related options are listed and explained below:
+.B -E, --component-end <\fIend\fR>
+The end offset of the component,
+.I end
+is specified in bytes, or using a suffix (kMGTP),
+such as 256M. -1 means the end of file.
+.B -I, --component-id <\fIcomp_id\fR>
+The numerical unique component id.
+.B --component-flags <\fIflags\fR>
+Component flags. Available flags: \fBinit\fR: instatiated component.
+.B --component-add
+Add specified components to an existing composite file.
+.B --component-del
+Delete specified the components from an existing file. Deletion must start
+with the last component.
+.B $ lfs setstripe -S 128k -c 2 /mnt/lustre/file1
+This creates a file striped on two OSTs with 128kB on each stripe.
+.B $ lfs setstripe -d /mnt/lustre/dir
+This deletes a default stripe pattern on dir. New files will use the default \
+striping pattern created therein.
+.B $ lfs setstripe -E 4M -c 1 -E 64M -c 4 -E -1 -c -1 /mnt/lustre/file1
+This creates a file with composite layout, the component has 1 stripe and \
+covers [0, 4M), the second component has 4 stripes and covers [4M, 64M), the \
+last component stripes over all available OSTs and covers [64M, EOF).
+.B $ lfs setstripe --component-add -E -1 -c 4  /mnt/lustre/file1
+This add a component which start from the end of last existing component to \
+the end of file.
+.B $ lfs setstripe --component-del -I 1 /mnt/lustre/file1
+This deletes the component with ID equals 1 from an existing file.
+.BR lfs (1),
+.BR lfs-migrate (1),
+.BR lustre (7)
index ba93482..27c4657 100644 (file)
@@ -26,6 +26,10 @@ lfs \- Lustre utility to create a file with specific striping pattern, find the
         \fB[[!] --stripe-index|-i <index,...>]
         \fB[[!] --stripe-size|-S [+-]N[kMG]]
         \fB[[!] --layout|-L raid0,released]
+        \fB[[!] --component-count [+-]comp_cnt]
+        \fB[[!] --component-start [+-]N[kMGTPE]]
+        \fB[[!] --component-end|-E [+-]N[kMGTPE]]
+        \fB[[!] --component-flags <comp_flags>]
         \fB[--type |-t {bcdflpsD}] [[!] --gid|-g|--group|-G <gname>|<gid>]
         \fB[[!] --uid|-u|--user|-U <uname>|<uid>] [[!] --pool <pool>]\fR
@@ -34,6 +38,9 @@ lfs \- Lustre utility to create a file with specific striping pattern, find the
 .B lfs getstripe [--obd|-O <uuid>] [--quiet|-q] [--verbose|-v]
         \fB[--stripe-count|-c ] [--stripe-index|-i] [--mdt-index|-M] [--fid|-F]
         \fB[--stripe-size|-S] [--directory|-d] [--layout|-L] [--generation|-g]
+        \fB[--component-id|-I [comp_id]] [--component-flags [comp_flags]]
+        \fB[--component-count] [--component-start [+-][N][kMGTPE]]
+        \fB[--component-end|-E [+-][N][kMGTPE]]
         \fB[--pool|-p] [--recursive|-r] [--raw|-R] <dirname|filename> ...\fR
 .B lfs migrate \fB-m <mdt_index>\fR
@@ -48,6 +55,11 @@ lfs \- Lustre utility to create a file with specific striping pattern, find the
                [\fB-n | --non-block\fR]
 .IR file|directory
+.B lfs migrate <\fB-E | --component-end comp_end1\fR> [\fBSTRIPE_OPTIONS\fR]
+               <\fB-E | --component-end comp_end2\fR> [\fBSTRIPE_OPTIONS\fR]
+               \fB...\fR
+.IR filename
 .B lfs mkdir [\fB-c | --count <stripe_count>\fR]
              [\fB-i | --index <mdt_idx>\fR]
              [\fB-h | --hash-type <hash_name>\fR]
@@ -102,6 +114,14 @@ lfs \- Lustre utility to create a file with specific striping pattern, find the
 .B lfs setstripe -d <dir>
+.B lfs setstripe <--component-end|-E end1> [STRIPE_OPTIONS]
+       \fB<--component-end|-E end2> [STRIPE_OPTIONS] ... <filename>\fR
+.B lfs setstripe --component-add <--component-end|-E end1> [STRIPE_OPTIONS]
+       \fB<--component-end|-E end2> [STRIPE_OPTIONS] ... <filename>\fR
+.B lfs setstripe --component-del <--component-id|-I id | --component-flags flags> <filename>
 .B lfs --version
 .B lfs --list-commands
@@ -154,6 +174,10 @@ to that filesystem are displayed.
         \fB[--count | -c ] [--index | -i | --offset | -o  ]
         \fB[--pool | -p ] [--size | -s ] [--directory | -d ]
         \fB[--layout | -L ] [--fid | -F ] [--generation | -g ]
+        \fB[--component-id|-I [comp_id]]
+        \fB[--component-flags [comp_flags]]
+        \fB[--component-count] [--component-start [+-][N][kMGTPE]]
+        \fB[--component-end|-E [+-][N][kMGTPE]]
         \fB[--recursive | -r ] [--raw | -R ] <dirname|filename>\fR
 List the striping information for a given filename or directory tree.
@@ -166,6 +190,11 @@ only want specific striping information then the options of
 .BR --layout ,
 .BR --fid ,
 .BR --generation ,
+.BR --component-id ,
+.BR --component-flags ,
+.BR --component-count ,
+.BR --component-start ,
+.BR --component-end ,
 .B --pool
 can be used to return only the specific fields.
@@ -199,71 +228,13 @@ To show only the FID use
 The layout generation can be printed with the
 .B --generation
-.B setstripe [--stripe-count|-c stripe_count] [--stripe-size|-S stripe_size]
-        \fB[--stripe-index|-i start_ost_index] [--pool <poolname>]
-        \fB[--ost-index|-o <ost_indices>] <dirname|filename>\fR
-To create a new file, or set the directory default, with the specified striping
-parameters.  The
-.I stripe_count
-is the number of OSTs to stripe a file over. A
-.I stripe_count
-of 0 means to use the filesystem-wide default stripe count (default 1), and a
-.I stripe_count
-of -1 means to stripe over all available OSTs.  The
-.I stripe_size
-is the number of bytes to store on each OST before moving to the next OST.  A
-.I stripe_size
-of 0 means to use the filesystem-wide default stripe_size (default 1MB).  The
-.I start_ost_index
-is the OST index (starting at 0) on which to start striping for this file.  A
-.I start_ost_index
-of -1 allows the MDS to choose the starting index and it is strongly
-recommended, as this allows space and load balancing to be done by the MDS as
-needed. The
-.B -o
-option is used to specify the exact stripe layout on the file system.
-.I ost_indices
-is a list of OSTs referenced by their indices, which are specified in decimal
-or hex form and can be obtained using the
-.B lfs osts
-command. The list format consists of individual OST indices and index ranges
-separated by commas, e.g. 1,2-4,7. The
-.B -o
-option may be specified multiple times to stripe across the union of all listed
-OSTs. If the
-.B -c
-option is combined with
-.B -o
-.I stripe_count
-must agree with the number of OSTs in
-.IR ost_indices .
-If the
-.B -i
-option is combined with
-.B -o
-.I start_ost_index
-must be in the OST list, and it will be used as the index on which to start
-striping the file. Otherwise the striping will occur in the order specified in
-.IR ost_indices .
-.I poolname
-is the name of a predefined pool of OSTs (see
-.BR lctl (8))
-that will be used for striping. The
-.IR stripe_count ,
-.IR stripe_size ,
-.I start_ost_index
-will be used as well; the
-.I start_ost_index
-must be part of the pool or an error will be returned.
-.B setstripe -d
-Delete the default striping on the specified directory.
+You can limit the displayed content by specifing argument for
+.B --component-id
+.B --component-flags
+.B --component-start
+.B --component-end
+options. For example, "--component-id 1" will only display the information
+for component 1.
 .B fid2path [--link <linkno>] <fsname|rootpath> <fid> ...
 Print out the pathname(s) for the specified \fIfid\fR(s) from the filesystem
@@ -341,6 +312,9 @@ instead.
 .B migrate
 See lfs-migrate(1).
+.B setstripe
+See lfs-setstripe(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
@@ -354,15 +328,15 @@ Provides brief help on the various arguments
 Quit the interactive lfs session
-.B $ lfs setstripe -s 128k -c 2 /mnt/lustre/file1
-This creates a file striped on two OSTs with 128kB on each stripe.
-.B $ lfs setstripe -d /mnt/lustre/dir
-This deletes a default stripe pattern on dir. New files will use the default striping pattern created therein.
 .B $ lfs getstripe -v /mnt/lustre/file1
 Lists the detailed object allocation of a given file
+.B $ lfs getstripe -v --component-id 2 /mnt/lustre/file1
+Lists the detailed information of the component 2 in a given file
+.B $ lfs getstripe -E -64M /mnt/lustre/file1
+Lists the information of the components in a file which has at least 64M extent end
 .B $ lfs find /mnt/lustre
 Efficiently lists all files in a given directory and its subdirectories
@@ -371,7 +345,10 @@ 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 find --component-count +3 /mnt/lustre
+Recursively list all files that have at most 3 components.
 .B $ lfs check servers
 Check the status of all servers (MDT, OST)
@@ -404,7 +381,9 @@ Set quotas of user `bob': 1GB block quota hardlimit and 2 GB block quota softlim
 .B $ lfs setquota -t -u --block-grace 1000 --inode-grace 1w4d /mnt/lustre
 Set grace times for user quotas: 1000 seconds for block quotas, 1 week and 4 days for inode quotas
+The usage of \fBlfs hsm_*\fR, \fBlfs setstripe\fR, \fBlfs migrate\fR, \fBlfs setdirstripe\fR,
+\fBlfs getdirstripe\fR and \fBlfs mkdir\fR are explained in separated man pages.
 The \fBlfs find\fR command isn't as comprehensive as \fBfind\fR(1).
@@ -416,6 +395,7 @@ The lfs command is part of the Lustre filesystem.
 .BR lfs-getdirstripe (1),
 .BR lfs-mkdir (1),
 .BR lfs_migrate (1),
+.BR lfs-setstripe (1),
 .BR lfs-migrate (1),
 .BR lctl (8),
 .BR lustre (7)