LU-13750 lnet: Fix peer add command

[fs/lustre-release.git] / lustre / doc / lfs-setstripe.1

diff --git a/lustre/doc/lfs-setstripe.1 b/lustre/doc/lfs-setstripe.1
index ec9d342..97f74e5 100644 (file)
--- a/lustre/doc/lfs-setstripe.1
+++ b/lustre/doc/lfs-setstripe.1
@@ -2,159 +2,207 @@
 .SH NAME
 lfs setstripe \- set striping pattern of a file or directory default
 .SH SYNOPSIS
 .SH NAME
 lfs setstripe \- set striping pattern of a file or directory default
 .SH SYNOPSIS

-.B lfs setstripe \fR[\fISTRIPE_OPTIONS\fR] <\fIdirectory\fR|\fIfilename\fR>
+.B lfs setstripe \fR[\fISTRIPE_OPTIONS\fR] <\fIdirectory\fR|\fIfile\fR>

 .br
 .br

-.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>
+.B lfs setstripe -E \fIend1\fR [\fISTRIPE_OPTIONS\fR] ... \
+<\fIdirectory\fR|\fIfile\fR>

 .br
 .br

-.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>
+.B lfs setstripe --comp-add -E \fIend1\fR [\fISTRIPE_OPTIONS\fR] ... \
+<\fIfile\fR>

 .br
 .br

-.B lfs setstripe --component-del \fR{\fB--component-id\fR|\fB-I \fIcomp_id\fR|
-.B --component-flags=\fIcomp_flags\fR} <\fIfilename\fR>
+.B lfs setstripe --comp-del \fR{\fB-I \fIcomp_id\fR|\
+\fB--comp-flags=\fIcomp_flags\fR} <\fIfile\fR>

 .br
 .br

-.B lfs setstripe --component-set \fR{\fB--component-id\fR|\fB-I \fIcomp_id\fR|
-.B --component-flags=\fIcomp_flags\fR} <\fIfilename\fR>
-.br
-.B lfs setstripe -d \fR<\fIdirectory\fR>
+.B lfs setstripe --comp-set \fR{-I \fIcomp_id\fR|\
+\fB--comp-flags=\fIcomp_flags\fR} <\fIfile\fR>

 .br
 .B lfs setstripe -N\fR[\fImirror_count\fR] \fR[\fISTRIPE_OPTIONS\fR] <\fIdirectory\fR|\fIfilename\fR>
 .br
 .br
 .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>
+.B lfs setstripe -d \fR<\fIdirectory\fR>

 .br
 .br

-.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 \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>
+.B lfs setstripe --yaml=\fR<\fIyaml_template_file.lyl\fR> <\fIfile\fR>

 .br
 .br

-Create a file with the specified composite layout. Each component defines the
-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. The end
-offset of
-.B -1
-or
-.B eof
-indicates the component extends to the end of file.
-.TP
-.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>
+.B lfs setstripe --copy=\fR<\fIsource_template_file\fR> <\fIfile\fR>

 .br
 .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.  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 --foreign[=\fR<\fIforeign_type\fR>\fB] \
+[--flags=\fR<\fIhex\fR>\fB] --xattr=\fR<\fIlayout_string\fR> <\fIfile\fR>
+.SH DESCRIPTION
+The

 .B lfs setstripe
 .B lfs setstripe

-call.
+command is used to create a new
+.I file
+in a Lustre filesystem with the specified layout, or to specify the default
+layout for new files created in
+.IR directory ,
+or anywhere in the filesystem if
+.I directory
+is the filesystem root and no other layout takes precedence.
+.PP
+Files with composite layouts allow different
+.I STRIPE_OPTIONS
+to be specified for non-overlapping extents of the file. Files will
+inherit options not explicitly specified on the command line either from
+the default layout on the parent directory, or from the filesystem-wide
+default. New subdirectories created under root directory will not explicitly
+copy the default layout at creation time, but will implicitly inherit the
+default layout at runtime. The default layout set on a non-root directory
+will be copied to any new subdirectories created within that directory
+at the time they are created.
+.TP
+.B lfs setstripe \fR[\fISTRIPE_OPTIONS\fR ...] <\fIdirectory\fR|\fIfile\fR>
+Create a new
+.I file
+with specified plain layout using the specified
+.IR STRIPE_OPTIONS ,
+or replace the default file layout on an existing
+.IR directory .
+.TP
+.B lfs setstripe -E \fIend\fR [\fISTRIPE_OPTIONS\fR] ... \
+<\fIdirectory\fR|\fIfile\fR>

 .br
 .br

-Adding a component to FLR files is not allowed.
-.TP
-.B lfs setstripe --component-del \fR{\fB--component-id\fR|\fB-I \fIcomp_id\fR | \
-\fB--component-flags \fIcomp_flags\fR} <\fIfilename\fR>
+Create a new composite
+.I file
+with one or more component layouts (where \fIend\fR marks the end of the
+current component), or set or replace the default file layout on an existing
+.IR directory.
+.TP
+.B lfs setstripe --component-add -E \fIend1\fR [\fISTRIPE_OPTIONS\fR] \
+... <\fIfile\fR>

 .br
 .br

-Remove the component(s) specified by component ID or flags from an existing
-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
+Add one or more components after the last component of an existing composite
+file that does not yet have a component at
+.BR eof .
+.TP
+.B lfs setstripe --comp-del \fR{\fB-I \fIcomp_id\fR | \
+\fB--comp-flags \fIcomp_flags\fR} <\fIfile\fR>
+Remove the component(s) specified by component ID or flags from
+.IR file .
+.TP
+.B lfs setstripe --comp-set \fR{\fB-I \fIcomp_id\fR | \
+\fB--comp-flags \fIcomp_flags\fR} <\fIfile\fR>
+Set or clear
+.I flags
+on the specified component. This command can be only
+be applied to mirrored files.
+.TP
+.B lfs setstripe -N \fR[\fImirror_count\fR] \fR[\fICOMPONENT_OPTIONS\fR] <\fIdirectory\fR|\fIfile\fR>
+Create a new
+.I file
+with the specified number of mirrors and other specified layout options, or
+set or replace the default file layout on an existing
+.IR directory .

 .TP
 .B lfs setstripe -d \fR<\fIdirectory\fR>
 .br
 Delete the default layout on the specified directory.  It is not necessary
 .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 delete the default layout on a directory before replacing it, only if
+the directory should revert from a directory-specific default layout

 to using the global filesystem default layout stored on the root directory.
 .TP
 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>
+.B lfs setstripe --yaml=\fR<\fIyaml_template_file.lyl\fR> <\fIfile\fR>

 .br
 .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.
+Create a new
+.I file
+using the Lustre YAML Layout template
+.IR yaml_template_file.lyl ,
+created from
+.I existing_file
+via:

 .br
 .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>
+.B lfs getstripe --yaml \fR<\fIexisting_file\fR> > <\fIyaml_template_file.lyl\fR>

 .br
 .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 yaml_template_file.lyl
+is a plain-text file that may be saved and/or modified after creation.
+This allows complex file layouts to be created once and re-used later.
+.TP
+.B lfs setstripe --copy=\fR<\fIsource_template_file\fR> <\fIfile\fR>
+.br
+Create a new
+.I file
+using the same layout as an existing
+.IR source_template_file .
+This is similar to the
+.B --yaml
+option but avoids the need for the intermediate
+.B .lyl
+file.
+.TP
+.B lfs setstripe --foreign[=\fR<\fIforeign_type\fR>\fB] \
+[--flags=\fR<\fIhex\fR>\fB] --xattr=\fR<\fIlayout_string\fR> <\fIfile\fR>
+.br
+Create a new
+.I file
+with a foreign/non-lustre layout of type
+.I foreign_type \fR(\fBnone\fR, \fBdaos\fR, ...)
+with flags
+.I hex
+and a free-format layout value of
+.I layout_string.

 .SH STRIPE_OPTIONS
 .SH STRIPE_OPTIONS

-The various stripe related options are listed and explained below:
+The various OST stripe related options are listed and explained below:

 .TP
 .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
 .TP
 .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 -C\fR, \fB--overstripe-count \fR<\fIstripe_count\fR>
+The number of stripes to create, creating > 1 stripe per OST if count exceeds
+the number of OSTs in the file system. \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\fR, \fB--stripe-size \fR<\fIstripe_size\fR>
 .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).
+The number of bytes to store on each OST before moving to the next OST. A
+stripe size of
+.B 0
+means the file should use the filesystem-wide default stripe_size
+(default 1MiB).  An optional suffix can be used to specify the units in
+.BR K ibi-,
+.BR M "ebi-, or"
+.BR G ibibytes.
+The
+.I stripe_size
+must be a multiple of 64KiB in size.

 .TP
 .B -i\fR, \fB--stripe-index \fR<\fIstart_ost_index\fR>
 .TP
 .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
+The OST index (starting at 0) on which to start striping for this file.  A
+.I start_ost_index
+of
+.B -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.
 .TP
 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\fR, \fB--ost-list \fR<\fIost_indices\fR>
+.B -L\fR, \fB--layout \fR<\fIlayout_type\fR>
+The type of layout for that component, which can be one of:
+.RS
+.B raid0\fR - stripe the file data across
+.B stripe_count
+OST objects in units of
+.B stripe_size
+chunks.  This is the default layout if not specified.
+.RE
+.RS
+.B mdt\fR - place the first component of the file data on the MDT for faster
+access where the inode is located. This can be used for small files, and with
+composite file layouts.  The
+.B mdt
+type may only be used for first component of a file. The
+.IR stripe_size
+of the MDT component is always equal to the component size. There is also a
+per-MDT tunable parameter
+.IR lod.dom_stripesize
+that limits the maximum size of a DoM stripe.  It can be changed on the MDS via
+.B lctl set_param lod.*.dom_stripesize=\fR<\fIstripe_size\fR> ,
+where
+.I stripe_size
+must be a multiple of 64KiB in size,
+see also
+.BR lctl (8)
+for details.
+.RE
+.TP
+.B -o\fR, \fB--ost \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
 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


@@ -182,81 +230,227 @@ striping the file. Otherwise the striping will occur in the order specified in
 .IR ost_indices .
 .TP
 .B -p\fR, \fB--pool \fR<\fIpool_name\fR>
 .IR ost_indices .
 .TP
 .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
+Allocate objects from the predefined OST pool
+.I pool_name
+for the layout of this file or component. The

 .IR stripe_count ,
 .IR stripe_size ,
 and
 .I start_ost_index
 .IR stripe_count ,
 .IR stripe_size ,
 and
 .I start_ost_index

-will be used as well; the
+can be used to select a subset of the OSTs within the pool; the

 .I start_ost_index
 must be part of the pool or an error will be returned.
 .I start_ost_index
 must be part of the pool or an error will be returned.

-If <\fIpool_name\fR> is
+It is possible to specify a different pool for each component of a file.  If
+no pool is specified, it will be inherited from the previous component (for
+later components of a composite layout) or the parent or root directory (for
+plain
+.B raid0
+layouts, or the first component of a composite file).
+Use
+.BR pool_name='' ,
+or
+.BR pool_name=none
+(since Lustre 2.11) to force a component to inherit the pool from the parent
+or root directory instead of the previous component.
+.TP
+.B --foreign \fR[<\fIforeign_type\fR>]
+file layout is non-lustre/free-format and of type <
+.IR foreign_type
+>, if specified (see also
+.IR --xattr
+and
+.IR --flags
+options).
+Current known types are

 .BR none
 .BR none

-, then the OST pool name will be cleared and inherit from parent directory.
-.TP
-.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
+and
+.BR daos
+, default is
+.BR none
+.
+.B -x\fR, \fB--xattr \fR<\fIlayout_string\fR>
+Mandatory non-lustre/free-format layout/LOV EA content for
+.I foreign
+file.
+.TP
+.B -F\fR, \fB--flags \fR<\fIhex\fR>
+Optional bitmap of flags for foreign type.

 .SH COMPONENT_OPTIONS
 .SH COMPONENT_OPTIONS

-The various component related options are listed and explained below:
+The various component related options are listed and explained below.  The
+.B --component-*
+options can be shortened to
+.B --comp-*
+if desired.

 .TP
 .B -E\fR, \fB--component-end \fR<\fIend\fR>
 .TP
 .B -E\fR, \fB--component-end \fR<\fIend\fR>

-The end offset of the component,
+Add a new component to a file using the
+.I STRIPE_OPTIONS
+following the
+.B -E
+argument.  These options apply to the component ending at offset

 .I end
 .I end

-is specified in bytes, or using a suffix (kMGTP),
-such as 256M. \fB-1\fR means the end of file.
+in bytes, or by using a suffix (KMGTP) to specify base-two units,
+such as 256M for 2^28 bytes. An offset of
+.B -1
+or
+.B eof
+means the following options extend to the end of the file.  The first
+component starts at offset 0, and each subsequent component starts at
+the end of the previous component, so they must be specified in increasing
+file offset order.
+.PP
+.RS
+The first component specified will inherit default parameters from the
+parent directory or the root directory like a plain layout, as specified
+above.  Later components will inherit the default layout parameters from
+the previous component.  Multiple
+.B -E
+options are used to separate the
+.I STRIPE_OPTIONS
+parameters for different regions of the file.
+.RE
+.PP
+.RS
+If a file does not have a component extending to
+.B eof
+it will generate an error when trying to write beyond the last component
+.IR end .
+This can be useful to limit the size of a file to the end of the last
+specified component, or use
+.B --component-add
+to add more components to the end of the file.
+.RE

 .TP
 .TP

-.B -I\fR, \fB--component-id \fR<\fIcomp_id\fR>
-The numerical unique component id.
+.B -z, --extension-size, ext-size\fR <\fIext_size\fR>
+This option modifies the \fB-E\fR option, components which have this
+option specified are created as pairs of components, extendable and
+extension ones.
+.PP
+.RS
+The extendable component starts at offset 0 if this is the first
+component of the file. In this case it ends at offset \fIext_size\fR and
+it gets the flag \fBinit\fR (initialized). The extendable component starts
+at the end of the previous component if this is not the first component of
+the file. In this case it ends at the same offset (0-length component).
+.PP
+The extension component covers the rest of the specified region up to
+the \fIend\fR specified by \fB-E\fR option and gets the flag \fBextension\fR.
+This component covers the space reserved for the extendable component but
+not used immediately, the later extension of the extendable component is done
+by \fIext_size\fR each time until the extension component is used up. This is
+used to control the space on OSTs the stripe is located on, in case one of
+them is low on space, the remaining extension component region is added to the
+next component.
+.RE
+.TP
+.B --component-add
+Add components to the end an existing composite file.  It is not possible
+to add components incrementally to the default directory layout, since the
+entire default layout can be replaced with a single
+.B lfs setstripe
+command.  Adding components to mirrored files is not currently allowed.
+.TP
+.B --component-del
+Delete specified the components from an existing file using either the
+.BR --component-id | -I
+or
+.BR --component-flags .
+Deletion must start with the last component.  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 -I
+command.  It is not possible to delete components from a default directory
+layout, since the entire default layout can be replaced with a single
+.B lfs setstripe
+call.
+The \fB--component-flags\fR option is used to specify certain type of
+components. The only allowed component flag for deleting a component is
+.B ^init
+to indicate an uninstantiated component.  Deleting a single component from
+mirrored files is not currently allowed, see the
+.BR lfs-mirror-split (1)
+command.

 .TP
 .B --component-flags \fR<\fIflags\fR>
 .TP
 .B --component-flags \fR<\fIflags\fR>

-Component flags. Available \fIflags\fR:
+Find, set, or clear
+.B flags
+on a specific component. Allowed
+.I flags
+are:

 .RS
 .RS

+.B * init\fR - component is initialized (has allocated objects).  Used with
+.B --component-del --component-flags ^init
+to find uninitialized components.
+.RE

 .RS
 .RS

-.B init\fR: instantiated component.
+.B * prefer\fR - component preferred for read/write in a mirrored file

 .RE
 .RS
 .RE
 .RS

-.B prefer\fR: preferred component, for FLR only.
+.B * stale\fR - component has outdated data in a mirrored file. This flag is
+not allowed to be set on a component of the last non-stale mirror.
+Once a component is marked
+.BR stale ,
+it isn't permitted to clear this flag directly. \fBlfs-mirror-resync\fR(1)
+is required to clear the flag.

 .RE
 .RS
 .RE
 .RS

-.B stale\fR: stale component, for FLR only.
+.B * nosync\fR - mirror components will not be resynched by default when the
+.BR lfs-mirror-resync (1)
+command is run. This option is useful to freeze a file mirror as an old
+version or snapshot of the file.

 .RE
 .RE

-.LP
-A leading '^' means inverted flag. Multiple flags can be separated by comma(s).
+.RS
+A leading '^' before \fIflags\fR clears the flags, or finds components not
+matching the flags.  Multiple flags can be separated by comma(s).

 .RE
 .TP
 .RE
 .TP

-.B --component-add
-Add specified components to an existing composite file.
+.B -I\fR, \fB--component-id \fR<\fIcomp_id\fR>
+The numerical unique component ID to identify a component to be modified.

 .TP
 .TP

-.B --component-del
-Delete specified the components from an existing file. Deletion must start
-with the last component.
+.BR -N "[\fImirror_count\fR], " --mirror-count=" [\fImirror_count\fR]
+Create a file with
+.I mirror_count
+identical replicas on the file or directory.  The
+.I mirror_count
+argument is optional and defaults to 1 if it's not specified; if specified,
+it must follow the
+.B -N
+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 not specified, the stripe options are inherited from the previous
+component. If there is no previous component, the
+.I stripe_count
+and
+.I stripe_size
+options are inherited from filesystem-wide default values, and OST
+.I pool_name
+will be inherited from the parent directory.
+.br
+Multiple
+.B -N
+options may be specified, each with its own
+.I STRIPE_OPTIONS
+if there is a reason to have different layouts for the replicas, such as
+flash pools and archive pools (see
+.BR lfs-mirror-create (1)
+for full details).
+.br
+.B NOTE
+that in the current client implementation, only
+.B one
+replica will be written by client nodes, and the other replicas need to
+be resynched using the
+.B lfs mirror resync
+command, or an external resync agent.

 .SH EXAMPLES
 .TP
 .SH EXAMPLES
 .TP

-.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 -S 128K -c 2 /mnt/lustre/file1
+This creates a file striped on two OSTs with 128KiB on each stripe.

 .TP
 .TP

-.B $ lfs setstripe -d /mnt/lustre/dir
+.B lfs setstripe -d /mnt/lustre/dir

 This deletes a default stripe pattern on dir. New files created in that
 directory will use the filesystem global default instead.
 .TP
 This deletes a default stripe pattern on dir. New files created in that
 directory will use the filesystem global default instead.
 .TP


@@ -264,37 +458,96 @@ directory will use the filesystem global default instead.
 This sets a default mirror layout on a directory with 2 PFL mirrors. Each mirror
 has the same specified PFL layout.
 .TP
 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 \
-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 -N -E 1M -L mdt -E eof --component-flags=prefer -p flash \
+    -N -E 1G -c 1 -p disk -E eof -c -1 /mnt/lustre/file1
+This creates a mirrored file with 2 replicas. The first replica is using the
+MDT for files smaller than 1MB, and the remainder of the file is on the
+.B flash
+OST pool with filesystem-wide default values.  The second replica is on the
+.B disk
+OST pool, with 1 stripe for the first 1GB of the file, and striped across
+all OSTs in the
+.B disk pool for the remainder of the file.  Clients will
+.B prefer
+the first (flash) replica for both reads and writes.
+.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
+covers [0, 4MiB), the second component has 4 stripes and covers [4MiB, 64MiB),
+the last component stripes over all available OSTs and covers [64MiB, EOF).
+.TP
+.B lfs setstripe -E -1 -z 64M /mnt/lustre/file1
+This creates a file with a composite layout, the component one covers [0, 64MiB)
+and the second component the rest [64MiB, EOF) originally. Once written beyond
+64MiB the component one is extended to [0, 128MiB), once written beyond 128MiB
+it is extended to [0, 192MiB), etc; the second component is shortened
+appropriately.
+.PP
+.RS
+When one of the OSTs of the first component layout is low on space, e.g. while
+writing beyond 192MiB, the first component is left as [0, 192MiB), and a new
+component is allocated between them, its layout repeats the first component
+layout but initialized on different OSTs so that the full OSTs are avoided.
+It is allocated and immediately extended to [192MiB, 256MiB), the following
+extension component is shortened again.
+.RE

 .TP
 .TP

-.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 \
+.B lfs setstripe -E 1G -z 64M -E 100G -z 256M -E -1 -z 1G /mnt/lustre/file1
+This creates a file with a composite layout, the component one covers [0,
+64MiB), the third component covers [1G, 1G), the fifth component covers
+[100GiB, 100GiB) originally. The second, fourth and sixth extension components
+cover the left space accordingly. The process of writing is similar to above,
+but when one of the OSTs of the first component layout is low on space, e.g.
+while writing beyond 192MiB in the example above, the first component is left
+as [0, 192MiB), the second (extension) component is removed, and its range
+spills over to the third and the fourth components - they are moved left to
+start at 192MiB instead of 100GiB; the third component is immediately extended
+and becomes [192MiB, 448MiB), the fourth (the extension one) component becomes
+[448MiB, 100GiB).
+.TP
+.B lfs setstripe --component-add -E eof -c 4  /mnt/lustre/file1
+This add a component which starts at the end of last existing component to

 the end of file.
 .TP
 the end of file.
 .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.
+.B lfs setstripe --component-del -I 1 /mnt/lustre/file1
+This deletes the component with ID equal to 1 from an existing file.
+.TP
+.B lfs setstripe --comp-set -I 1 --comp-flags=^prefer,stale /mnt/lustre/file1
+This command will clear the \fBprefer\fR flag and set the \fBstale\fR flag on
+.B file1
+component ID 1.
+.TP
+.B lfs setstripe -E 1M -L mdt -E -1 /mnt/lustre/file1
+Create
+.B file1
+with Data-on-MDT layout. The first 1MiB of the file data is placed on the
+MDT and rest of file is placed on OST(s) with default striping.
+.TP
+.B lfs setstripe --yaml=/tmp/layout_yaml /mnt/lustre/file2
+This creates
+.B file2
+with layout stored in the layout template
+file
+.B layout_yaml
+which can be created with the
+.B lfs getstripe --yaml
+command.

 .TP
 .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.
-
+.B lfs setstripe --foreign=daos --flags=0xda08 \
+       --xattr=PUUID:CUUID /mnt/lustre/file1
+This creates foreign
+.BR file1
+of type
+.BR daos
+with non-lustre/free-format
+.BR PUUID:CUUID
+layout/LOV EA and flags
+.BR 0xda08
+.

 .SH SEE ALSO
 .SH SEE ALSO

+.BR lctl (1),

 .BR lfs (1),
 .BR lfs-migrate (1),
 .BR lfs (1),
 .BR lfs-migrate (1),

+.BR lfs-mirror-create (1),
+.BR lfs-mirror-split (1),

 .BR lustre (7)
 .BR lustre (7)