-.TH LFS-SETSTRIPIE 1 2015-11-06 "Lustre" "Lustre Utilities"
+.TH LFS-SETSTRIPE 1 2017-08-23 "Lustre" "Lustre Utilities"
.SH NAME
-lfs setstripe \- set striping pattern of a file.
+lfs setstripe \- set striping pattern of a file or directory default
.SH SYNOPSIS
-.B lfs setstripe [\fISTRIPE_OPTIONS\fR] <directory|filename>
+.B lfs setstripe \fR[\fISTRIPE_OPTIONS\fR] <\fIdirectory\fR|\fIfilename\fR>
.br
-.B lfs setstripe -d <directory>
+.B lfs setstripe \fR{\fB--component-end\fR|\fB-E \fIend1\fR} [\fISTRIPE_OPTIONS\fR]
+[{\fB--component-end\fR|\fB-E \fIend2\fR} [\fISTRIPE_OPTIONS\fR] ...] <\fIfilename\fR>
.br
-.B lfs setstripe <--component-end|-E end1> [\fISTRIPE_OPTIONS\fR] \
-[<--component-end|-E end2> [\fISTRIPE_OPTIONS\fR] ...] <filename>
+.B lfs setstripe --component-add \fR{\fB--component-end\fR|\fB-E \fIend1\fR}
+[\fISTRIPE_OPTIONS\fR] [{\fB--component-end\fR|\fB-E \fIend2\fR} [\fISTRIPE_OPTIONS\fR]
+\&...] <\fIfilename\fR>
.br
-.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 \fR{\fB--component-id\fR|\fB-I \fIcomp_id\fR|
+.B --component-flags=\fIcomp_flags\fR} <\fIfilename\fR>
.br
-.B lfs setstripe --component-del <--component-id|-I comp_id | \
---component-flags comp_flags> <filename>
+.B lfs setstripe --component-set \fR{\fB--component-id\fR|\fB-I \fIcomp_id\fR|
+.B --component-flags=\fIcomp_flags\fR} <\fIfilename\fR>
.br
-.SH DESCRIPTION
-.TP
-.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 \fR<\fIdirectory\fR>
.br
-.TP
-.B lfs setstripe -d <directory>
+.B lfs setstripe -N\fR[\fImirror_count\fR] \fR[\fISTRIPE_OPTIONS\fR] <\fIdirectory\fR|\fIfilename\fR>
+.br
+.B lfs setstripe --yaml=<yaml_template_file> <filename>
.br
-Delete the default striping on the specified directory.
+.SH DESCRIPTION
+.TP
+.B lfs setstripe \fR[\fISTRIPE_OPTIONS\fR] <\fIdirectory\fR|\fIfilename\fR>
+Create a file with specified layout, or set or replace the default file
+layout on an existing directory. If the default file layout is set on
+the filesystem root directory, it will be used as the filesystem-wide
+default layout for all files that do not explicitly specify a layout and
+do not have a default layout on the parent directory. The default layout
+set on a directory will be copied to any new subdirectories created within
+that directory at the time they are created.
.TP
-.B lfs setstripe <--component-end|-E end1> [\fISTRIPE_OPTIONS\fR] \
-[<--component-end|-E end2> [\fISTRIPE_OPTIONS\fR] ...] <filename>
+.B lfs setstripe \fR{\fB--component-end\fR|\fB-E \fIend1\fR} [\fISTRIPE_OPTIONS\fR] \
+[{\fB--component-end\fR|\fB-E \fIend2\fR} [\fISTRIPE_OPTIONS\fR] ...] <\fIfilename\fR>
.br
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.
-The
-.I -E
+stripe pattern of the file in the range of
+.RI [ start ", " end ].
+The first component implicitly starts at offset 0, and all later components
+start at the end of previous extent. The
+.B -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.
+indicates the following \fISTRIPE_OPTIONS\fR are for this component. The end
+offset of
+.B -1
+or
+.B eof
+indicates the component extends to the end of file.
.TP
-.B lfs setstripe --component-add <--component-end|-E end1> [\fISTRIPE_OPTIONS\fR] \
-[<--component-end|-E end2> [\fISTRIPE_OPTIONS\fR] ...] <filename>
+.B lfs setstripe --component-add \fR{\fB--component-end\fR|\fB-E \fIend1\fR} [\fISTRIPE_OPTIONS\fR] \
+[{\fB--component-end\fR|\fB-E \fIend2\fR} [\fISTRIPE_OPTIONS\fR] ...] <\fIfilename\fR>
.br
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.
+file, and all components to be added must be adjacent with each other. It is
+not possible to add components incrementally to the default directory layout,
+since the entire default layout can be replaced with one
+.B lfs setstripe
+call.
+.br
+Adding a component to FLR files is not allowed.
.TP
-.B lfs setstripe --component-del <--component-id|-I comp_id | \
---component-flags comp_flags> <filename>
+.B lfs setstripe --component-del \fR{\fB--component-id\fR|\fB-I \fIcomp_id\fR | \
+\fB--component-flags \fIcomp_flags\fR} <\fIfilename\fR>
.br
Remove the component(s) specified by component ID or flags from an existing
-file. The ID specified by
-.I -I
+file. The ID specified by the
+.B -I
option is the numerical unique ID of the component, it can be obtained using
the
.B lfs getstripe
+command. It is not possible to delete components from a default directory
+layout, since the entire default layout can be replaced with one
+.B lfs setstripe
+call.
+The \fB--component-flags\fR option is used to specify certain type of
+components, such as all instantiated ones. Available component flags for
+deleting a component would be:
+.RS
+.TP
+.B init
+instantiated component.
+.LP
+A leading '^' in front of the \fIflags\fR means inverted flags.
+.br
+Deleting a component from FLR files is not allowed.
+.RE
+.TP
+.B lfs setstripe --component-set \fR{\fB--component-id\fR|\fB-I \fIcomp_id\fR | \
+\fB--component-flags \fIcomp_flags\fR} <\fIfilename\fR>
+Set or clear \fIflags\fR to the specified component. This command can be only
+be applied to FLR files. Available \fIflags\fR are:
+.RS
+.TP
+.B stale
+indicates the data in the corresponding component is not available for I/O.
+Once a component is set to stale, a \fBlfs-mirror-resync\fR(1) is required to
+clear the flag.
+.TP
+.B prefer
+set this flag to the corresponding component so that Lustre would prefer to
+choose the specified component for I/O.
+.LP
+A leading '^' means to clear the corresponding flag. It doesn't allow to clear
+\fBstale\fR flag.
+.RE
+.TP
+.B lfs setstripe -d \fR<\fIdirectory\fR>
+.br
+Delete the default layout on the specified directory. It is not necessary
+to delete the default layout on a directory before replacing it. This is
+only needed if the directory should revert from a directory-specific layout
+to using the global filesystem default layout stored on the root directory.
+.TP
+.B lfs setstripe -N\fR[\fImirror_count\fR] \fR[\fISTRIPE_OPTIONS\fR] <\fIdirectory\fR|\fIfilename\fR>
+.br
+The -N option indicates how many mirrors that have the same layout will be set
+on a file or directory (see \fBlfs-mirror-create\fR(1)). The \fImirror_count\fR
+argument is optional and defaults to 1 if it's not specified; if specified,
+it must follow the option without a space.
+.br
+The \fISTRIPE_OPTIONS\fR specify the specific layout for the mirror. It can
+be a plain layout with specific striping pattern or a composite layout.
+If they are not specified, the stripe options inherited from the previous
+component will be used. If there is no previous component, the
+\fIstripe_count\fR and \fIstripe_size\fR options inherited from filesystem-wide
+default values will be used, and OST \fIpool_name\fR inherited from parent
+directory will be used.
+.TP
+.B lfs setstripe --yaml=<yaml_template_file> <filename>
+.br
+Create a file with layout information specified by a YAML format template
+file, the template file can be obtained using the
+.B lfs getstripe --yaml <anotherfile>
command.
-.I --component-flags
-option is used to specify certain type of components, such as all instantiated
-ones.
.SH STRIPE_OPTIONS
The various stripe related options are listed and explained below:
.TP
-.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
-OSTs.
+.B -c\fR, \fB--stripe-count \fR<\fIstripe_count\fR>
+The number of OSTs to stripe a file over. \fB0 \fRmeans to use the
+filesystem-wide default stripe count (default 1), and \fB-1 \fRmeans to stripe
+over all available OSTs.
.TP
-.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 -S\fR, \fB--stripe-size \fR<\fIstripe_size\fR>
+The number of bytes to store on each OST before moving to the next OST. \fB0\fR
+means to use the filesystem-wide default stripe_size (default 1MB).
.TP
-.B -i, --stripe-index <\fIstart_ost_index\fR>
-The OST index (starting at 0) on which to start striping for this file. -1
+.B -i\fR, \fB--stripe-index \fR<\fIstart_ost_index\fR>
+The OST index (starting at 0) on which to start striping for this file. \fB-1\fR
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.
.TP
-.B -o, --ost-list <\fIost_indices\fR>
+.B -o\fR, \fB--ost-list \fR<\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
striping the file. Otherwise the striping will occur in the order specified in
.IR ost_indices .
.TP
-.B -p, --pool <\fIpool_name\fR>
+.B -p\fR, \fB--pool \fR<\fIpool_name\fR>
The name of a predefined pool of OSTs (see
.BR lctl (8))
that will be used for striping. The
will be used as well; the
.I start_ost_index
must be part of the pool or an error will be returned.
+If <\fIpool_name\fR> is
+.BR none
+, then the OST pool name will be cleared and inherit from parent directory.
.TP
-There are two options available only for \fBlfs migrate\fR:
-.TP
-.B -b, --block
-Block file access during data migration (default).
+.B -L\fR, \fB--layout \fR<\fIlayout type\fR>
+The type of stripe layout, can be
+.BR raid0 ", " released " or " mdt ".
+It is
+.BR raid0
+by default. The
+.BR mdt
+type allows place the first component of the file on the MDT where the inode
+is located. This is used with composite file layouts and can be defined as
+first component only. The
+.IR stripe_size
+of MDT part is always equal to the component size. There is also per-MDT
+parameter
+.IR lod.dom_stripesize
+to limit maximum size of DoM stripe which can be changed with
+.BR lctl\ set_param
+command, (e.g.
+.IR lctl\ set_param\ lod.*.dom_stripesize=0
+, see
+.BR lctl (8))
.TP
-.B -n, --non-block
-Abort migrations if concurrent access is detected.
.SH COMPONENT_OPTIONS
The various component related options are listed and explained below:
.TP
-.B -E, --component-end <\fIend\fR>
+.B -E\fR, \fB--component-end \fR<\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.
+such as 256M. \fB-1\fR means the end of file.
.TP
-.B -I, --component-id <\fIcomp_id\fR>
+.B -I\fR, \fB--component-id \fR<\fIcomp_id\fR>
The numerical unique component id.
.TP
-.B --component-flags <\fIflags\fR>
-Component flags. Available flags: \fBinit\fR: instantiated component.
-\fB^init\fR: uninstantiated component.
+.B --component-flags \fR<\fIflags\fR>
+Component flags. Available \fIflags\fR:
+.RS
+.RS
+.B init\fR: instantiated component.
+.RE
+.RS
+.B prefer\fR: preferred component, for FLR only.
+.RE
+.RS
+.B stale\fR: stale component, for FLR only.
+.RE
+.LP
+A leading '^' means inverted flag. Multiple flags can be separated by comma(s).
+.RE
.TP
.B --component-add
Add specified components to an existing composite file.
This creates a file striped on two OSTs with 128kB on each stripe.
.TP
.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.
+This deletes a default stripe pattern on dir. New files created in that
+directory will use the filesystem global default instead.
+.TP
+.B lfs setstripe -N2 -E 1M -E eof -c -1 /mnt/lustre/dir1
+This sets a default mirror layout on a directory with 2 PFL mirrors. Each mirror
+has the same specified PFL layout.
+.TP
+.B lfs setstripe -N2 /mnt/lustre/file1
+This creates a mirrored file with 2 mirrors. Each mirror has the same default
+striping pattern with \fIstripe_count\fR and \fIstripe_size\fR inherited from
+filesystem-wide default values, and OST \fIpool_name\fR inherited from parent
+directory.
.TP
.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 \
.TP
.B $ lfs setstripe --component-del -I 1 /mnt/lustre/file1
This deletes the component with ID equals 1 from an existing file.
+.TP
+.B $ lfs setstripe --component-set -I 1 --component-flags=^prefer,stale /mnt/lustre/file1
+This command will clear the \fBprefer\fR flag and set the \fBstale\fR to
+component with ID 1.
+.TP
+.B $ lfs setstripe -E 1M -L mdt -E -1 /mnt/lustre/file1
+This created file with Data-on-MDT layout. The first 1M is placed on MDT and \
+rest of file is placed on OST with default striping.
+.TP
+.B $ lfs setstripe --yaml=/tmp/layout_yaml /mnt/lustre/file2
+This creates a file with layout specified by a layout template which can be \
+obtained with \fBlfs getstripe --yaml\fR command.
+
.SH SEE ALSO
.BR lfs (1),
.BR lfs-migrate (1),