.TH LFS-SETSTRIPE 1 2017-08-23 "Lustre" "Lustre Utilities"
.SH NAME
-lfs setstripe \- set striping pattern of a file or directory default
+lfs-setstripe \- set striping pattern of a file or directory default
.SH SYNOPSIS
-.B lfs setstripe \fR[\fISTRIPE_OPTIONS\fR] <\fIdirectory\fR|\fIfile\fR>
+.B lfs setstripe \fR[\fISTRIPE_OPTIONS\fR] \fIDIRECTORY\fR|\fIFILENAME\fR
.br
-.B lfs setstripe -E \fIend1\fR [\fISTRIPE_OPTIONS\fR] ... \
-<\fIdirectory\fR|\fIfile\fR>
+.B lfs setstripe -E \fICOMP_END\fR [\fISTRIPE_OPTIONS\fR] ... \
+\fIDIRECTORY\fR|\fIFILENAME\fR
.br
-.B lfs setstripe --comp-add -E \fIend1\fR [\fISTRIPE_OPTIONS\fR] ... \
-<\fIfile\fR>
+.B lfs setstripe --comp-add -E \fICOMP_END\fR [\fISTRIPE_OPTIONS\fR] ... \
+\fIFILENAME\fR
.br
-.B lfs setstripe --comp-del \fR{\fB-I \fIcomp_id\fR|\
-\fB--comp-flags=\fIcomp_flags\fR} <\fIfile\fR>
+.B lfs setstripe --comp-del \fR[\fB-I \fICOMP_ID\fR|\
+\fB--comp-flags=\fICOMP_FLAGS\fR] \fIFILENAME\fR
.br
-.B lfs setstripe --comp-set \fR{-I \fIcomp_id\fR|\
-\fB--comp-flags=\fIcomp_flags\fR} <\fIfile\fR>
+.B lfs setstripe --comp-set \fR[\fB-I \fICOMP_ID\fR|\
+\fB--comp-flags=\fICOMP_FLAGS\fR] \fIFILENAME\fR
.br
-.B lfs setstripe -N\fR[\fImirror_count\fR] \fR[\fISTRIPE_OPTIONS\fR] <\fIdirectory\fR|\fIfilename\fR>
+.B lfs setstripe -N\fR[\fIMIRROR_COUNT\fR] \fR[\fISTRIPE_OPTIONS\fR] \fIDIRECTORY\fR|\fIFILENAME\fR
.br
-.B lfs setstripe -d \fR<\fIdirectory\fR>
+.B lfs setstripe -d \fR\fIDIRECTORY\fR
.br
-.B lfs setstripe --yaml=\fR<\fIyaml_template_file.lyl\fR> <\fIfile\fR>
+.B lfs setstripe --yaml=\fR\fIYAML_TEMPLATE_FILE.LYL\fR \fIFILENAME\fR
.br
-.B lfs setstripe --copy=\fR<\fIsource_template_file\fR> <\fIfile\fR>
+.B lfs setstripe --copy=\fR\fISOURCE_TEMPLATE_FILE\fR \fIFILENAME\fR
.br
-.B lfs setstripe --foreign[=\fR<\fIforeign_type\fR>\fB] \
-[--flags=\fR<\fIhex\fR>\fB] --xattr=\fR<\fIlayout_string\fR> <\fIfile\fR>
+.B lfs setstripe --foreign\fR[\fB=\fR\fIFOREIGN_TYPE\fR] \
+\fR[\fB--flags=\fR\fIHEX\fR] \fB--xattr=\fR\fILAYOUT_STRING\fR \fIFILENAME\fR
.SH DESCRIPTION
+.nh
+.ad l
The
.B lfs setstripe
command is used to create a new
-.I file
+.I FILENAME
in a Lustre filesystem with the specified layout, or to specify the default
layout for new files created in
-.IR directory ,
+.IR DIRECTORY ,
or anywhere in the filesystem if
-.I directory
+.I DIRECTORY
is the filesystem root and no other layout takes precedence.
.PP
Files with composite layouts allow different
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>
+.B lfs setstripe \fR[\fISTRIPE_OPTIONS\fR ...] \fIDIRECTORY\fR|\fIFILENAME\fR
Create a new
-.I file
+.I FILENAME
with specified plain layout using the specified
.IR STRIPE_OPTIONS ,
or replace the default file layout on an existing
-.IR directory .
+.IR DIRECTORY .
.TP
-.B lfs setstripe -E \fIend\fR [\fISTRIPE_OPTIONS\fR] ... \
-<\fIdirectory\fR|\fIfile\fR>
+.B lfs setstripe -E \fIEND_OFFSET\fR [\fISTRIPE_OPTIONS\fR] ... \
+\fIDIRECTORY\fR|\fIFILENAME\fR
.br
Create a new composite
-.I file
-with one or more component layouts (where \fIend\fR marks the end of the
+.I FILENAME
+with one or more component layouts (where \fIEND_OFFSET\fR marks the end of the
current component), or set or replace the default file layout on an existing
-.IR directory.
+.IR DIRECTORY.
.TP
-.B lfs setstripe --component-add -E \fIend1\fR [\fISTRIPE_OPTIONS\fR] \
-... <\fIfile\fR>
+.B lfs setstripe --component-add -E \fIEND_OFFSET\fR [\fISTRIPE_OPTIONS\fR] \
+... \fIFILENAME\fR
.br
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>
+.B lfs setstripe --comp-del \fR[\fB-I \fICOMP_ID\fR | \
+\fB--comp-flags \fICOMP_FLAGS\fR] \fIFILENAME\fR
Remove the component(s) specified by component ID or flags from
-.IR file .
+.IR FILENAME .
.TP
-.B lfs setstripe --comp-set \fR{\fB-I \fIcomp_id\fR | \
-\fB--comp-flags \fIcomp_flags\fR} <\fIfile\fR>
+.B lfs setstripe --comp-set \fR[\fB-I \fICOMP_ID\fR | \
+\fB--comp-flags \fICOMP_FLAGS\fR] \fIFILENAME\fR
Set or clear
-.I flags
+.I COMP_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>
+.B lfs setstripe -N \fR[\fIMIRROR_COUNT\fR] \fR[\fICOMPONENT_OPTIONS\fR] \fIDIRECTORY\fR|\fIFILENAME\fR
Create a new
-.I file
+.I FILENAME
with the specified number of mirrors and other specified layout options, or
set or replace the default file layout on an existing
-.IR directory .
+.IR DIRECTORY .
.TP
-.B lfs setstripe -d \fR<\fIdirectory\fR>
+.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, 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
-.B lfs setstripe --yaml=\fR<\fIyaml_template_file.lyl\fR> <\fIfile\fR>
+.B lfs setstripe --yaml=\fR\fIYAML_TEMPLATE_FILE.LYL\fR \fIFILENAME\fR
.br
Create a new
-.I file
+.I FILENAME
using the Lustre YAML Layout template
-.IR yaml_template_file.lyl ,
+.IR YAML_TEMPLATE_FILE.LYL ,
created from
-.I existing_file
+.I EXISTING_FILE
via:
.br
-.B lfs getstripe --yaml \fR<\fIexisting_file\fR> > <\fIyaml_template_file.lyl\fR>
+.B lfs getstripe --yaml \fR\fIEXISTING_FILE\fR > \fIYAML_TEMPLATE_FILE.LYL\fR
.br
-.I yaml_template_file.lyl
+.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>
+.B lfs setstripe --copy=\fR\fISOURCE_TEMPLATE_FILE\fR \fIFILENAME\fR
.br
Create a new
.I file
using the same layout as an existing
-.IR source_template_file .
+.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>
+.B lfs setstripe --foreign[=\fR\fIFOREIGN_TYPE\fR\fB] \
+[--flags=\fR\fIHEX\fR\fB] --xattr=\fR\fILAYOUT_STRING\fR \fIFILENAME\fR
.br
Create a new
-.I file
+.I FILENAME
with a foreign/non-lustre layout of type
-.I foreign_type \fR(\fBnone\fR, \fBdaos\fR, ...)
+.I FOREIGN_TYPE \fR(\fBnone\fR, \fBdaos\fR, ...)
with flags
-.I hex
+.I HEX
and a free-format layout value of
-.I layout_string.
+.I LAYOUT_STRING.
.SH STRIPE_OPTIONS
The various OST stripe related options are listed and explained below:
.TP
-.B -c\fR, \fB--stripe-count \fR<\fIstripe_count\fR>
+.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>
+.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. 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
+means the file should use the filesystem-wide default stripe size
+(default 4MiB). 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.
+.I STRIPE_SIZE
+must be a multiple of 64KiB. Values below 4096 are assumed to be in KiB units.
.TP
-.B -i\fR, \fB--stripe-index \fR<\fIstart_ost_index\fR>
+.B -i\fR, \fB--stripe-index \fR\fISTART_OST_IDX\fR
The OST index (starting at 0) on which to start striping for this file. A
-.I start_ost_index
+.I START_OST_IDX
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
-.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.
+\fISTRIPE_COUNT\fR OST objects in units of
+\fISTRIPE_SIZE\fR 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
+composite file layouts. The
.B mdt
type may only be used for first component of a file. The
-.IR stripe_size
+.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> ,
+.B lctl set_param lod.*.dom_stripesize=\fR\fISTRIPE_SIZE\fR ,
where
-.I stripe_size
+.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
+.B -o\fR, \fB--ost \fR\fIOST_IDX\fR
+Used to specify the exact stripe layout on the file system. \fIOST_IDX\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
option is combined with
.B -o
the
-.I stripe_count
+.I STRIPE_COUNT
must agree with the number of OSTs in
-.IR ost_indices .
+.IR OST_IDX .
If the
.B -i
option is combined with
.B -o
the
-.I start_ost_index
+.I START_OST_IDX
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 .
+.IR OST_IDX .
.TP
-.B -p\fR, \fB--pool \fR<\fIpool_name\fR>
+.B -p\fR, \fB--pool \fR\fIPOOL_NAME\fR
Allocate objects from the predefined OST pool
-.I pool_name
+.I POOL_NAME
for the layout of this file or component. The
-.IR stripe_count ,
-.IR stripe_size ,
+.IR STRIPE_COUNT ,
+.IR STRIPE_SIZE ,
and
-.I start_ost_index
+.I START_OST_IDX
can be used to select a subset of the OSTs within the pool; the
-.I start_ost_index
+.I START_OST_IDX
must be part of the pool or an error will be returned.
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
.B raid0
layouts, or the first component of a composite file).
Use
-.BR pool_name='' ,
+.BR pool_name=ignore
+to force a component without a pool set (no inheritance from last component,
+root or parent).
+Use
+.BR pool_name=''
or
-.BR pool_name=none
-(since Lustre 2.11) to force a component to inherit the pool from the parent
+.BR pool_name=inherit
+(since Lustre 2.15) 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
+.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
Current known types are
.BR none
and
-.BR daos
+.BR symlink
, default is
.BR none
.
-.B -x\fR, \fB--xattr \fR<\fIlayout_string\fR>
+.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>
+.B -F\fR, \fB--flags \fR\fIHEX\fR
Optional bitmap of flags for foreign type.
.SH COMPONENT_OPTIONS
The various component related options are listed and explained below. The
.B --comp-*
if desired.
.TP
-.B -E\fR, \fB--component-end \fR<\fIend\fR>
+.B -E\fR, \fB--component-end \fR\fIEND_OFFSET\fR
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_OFFSET
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
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.
+file offset order, and must be a multiple of 64KiB to align with the
+minimum
+.I STRIPE_SIZE
+value. Values below 4096 are assumed to be in KiB units.
.PP
.RS
The first component specified will inherit default parameters from the
to add more components to the end of the file.
.RE
.TP
-.B -z, --extension-size, ext-size\fR <\fIext_size\fR>
+.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
+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.
+the \fIEND_OFFSET\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
+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.
.BR lfs-mirror-split (1)
command.
.TP
-.B --component-flags \fR<\fIflags\fR>
+.B --component-flags \fR\fICOMP_FLAGS\fR
Find, set, or clear
.B flags
on a specific component. Allowed
.B * prefer\fR - component preferred for read/write in a mirrored file
.RE
.RS
-.B * stale\fR - component has outdated data in a mirrored file. Once a
-component is marked
+.B * prefrd\fR - component preferred for read in a mirrored file
+.RE
+.RS
+.B * prefwr\fR - component preferred for write in a mirrored file
+.RE
+.RS
+.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.
matching the flags. Multiple flags can be separated by comma(s).
.RE
.TP
-.B -I\fR, \fB--component-id \fR<\fIcomp_id\fR>
+.B -I\fR, \fB--component-id \fR\fICOMP_ID\fR
The numerical unique component ID to identify a component to be modified.
.TP
-.BR -N "[\fImirror_count\fR], " --mirror-count=" [\fImirror_count\fR]
+.BR -N, \fB--mirror-count \fR[\fIMIRROR_COUNT\fR]
Create a file with
-.I mirror_count
+.I MIRROR_COUNT
identical replicas on the file or directory. The
-.I mirror_count
+.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.
+option without a space. The maximum possible value for the mirror count is 16.
.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
+.I STRIPE_COUNT
and
-.I stripe_size
+.I STRIPE_SIZE
options are inherited from filesystem-wide default values, and OST
-.I pool_name
+.I POOL_NAME
will be inherited from the parent directory.
.br
Multiple
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 shortended again.
+extension component is shortened again.
.RE
.TP
.B lfs setstripe -E 1G -z 64M -E 100G -z 256M -E -1 -z 1G /mnt/lustre/file1
.B lfs getstripe --yaml
command.
.TP
-.B lfs setstripe --foreign=daos --flags=0xda08 \
+.B lfs setstripe --foreign=symlink --flags=0xda08 \
--xattr=PUUID:CUUID /mnt/lustre/file1
This creates foreign
.BR file1
of type
-.BR daos
+.BR symlink
with non-lustre/free-format
.BR PUUID:CUUID
layout/LOV EA and flags
git://git.whamcloud.com / fs / lustre-release.git / blobdiff