-.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|\fIfile\fR>
.br
-.B lfs setstripe -d <directory>
+.B lfs setstripe -E \fIend1\fR [\fISTRIPE_OPTIONS\fR] ... \
+<\fIdirectory\fR|\fIfile\fR>
.br
-.B lfs setstripe <--component-end|-E end1> [\fISTRIPE_OPTIONS\fR] \
-[<--component-end|-E end2> [\fISTRIPE_OPTIONS\fR] ...] <filename>
+.B lfs setstripe --comp-add -E \fIend1\fR [\fISTRIPE_OPTIONS\fR] ... \
+<\fIfile\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 --comp-del \fR{\fB-I \fIcomp_id\fR|\
+\fB--comp-flags=\fIcomp_flags\fR} <\fIfile\fR>
.br
-.B lfs setstripe --component-del <--component-id|-I comp_id | \
---component-flags comp_flags> <filename>
+.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
+.B lfs setstripe -d \fR<\fIdirectory\fR>
+.br
+.B lfs setstripe --yaml=\fR<\fIyaml_template_file.lyl\fR> <\fIfile\fR>
+.br
+.B lfs setstripe --copy=\fR<\fIsource_template_file\fR> <\fIfile\fR>
.SH DESCRIPTION
+The
+.B lfs setstripe
+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. 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[\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 [\fISTRIPE_OPTIONS\fR] <directory|filename>
-Create a file with specified striping pattern, or set default stripping pattern
-to a directory.
+.B lfs setstripe -E \fIend\fR [\fISTRIPE_OPTIONS\fR] ... \
+<\fIdirectory\fR|\fIfile\fR>
.br
+Create a new composite
+.I file
+with one or more component layouts, or set or replace the default file layout
+on an existing
+.IR directory .
.TP
-.B lfs setstripe -d <directory>
+.B lfs setstripe --component-add -E \fIend1\fR [\fISTRIPE_OPTIONS\fR] \
+... <\fIfile\fR>
.br
-Delete the default striping on the specified directory.
+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 <--component-end|-E end1> [\fISTRIPE_OPTIONS\fR] \
-[<--component-end|-E end2> [\fISTRIPE_OPTIONS\fR] ...] <filename>
+.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
-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
-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.
+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 --component-add <--component-end|-E end1> [\fISTRIPE_OPTIONS\fR] \
-[<--component-end|-E end2> [\fISTRIPE_OPTIONS\fR] ...] <filename>
+.B lfs setstripe --yaml=\fR<\fIyaml_template_file.lyl\fR> <\fIfile\fR>
+.br
+Create a new
+.I file
+using the Lustre YAML Layout template
+.IR yaml_template_file.lyl ,
+created from
+.I existing_file
+via:
.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.
+.B lfs getstripe --yaml \fR<\fIexisting_file\fR> > <\fIyaml_template_file.lyl\fR>
+.br
+.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 --component-del <--component-id|-I comp_id | \
---component-flags comp_flags> <filename>
+.B lfs setstripe --copy=\fR<\fIsource_template_file\fR> <\fIfile\fR>
.br
-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
-the
-.B lfs getstripe
-command.
-.I --component-flags
-option is used to specify certain type of components, such as all instantiated
-ones.
+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.
.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, --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. 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, --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. 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
-.B -o, --ost-list <\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
striping the file. Otherwise the striping will occur in the order specified in
.IR ost_indices .
.TP
-.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
+.B -p\fR, \fB--pool \fR<\fIpool_name\fR>
+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
-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.
-.TP
-There are two options available only for \fBlfs migrate\fR:
-.TP
-.B -b, --block
-Block file access during data migration (default).
-.TP
-.B -n, --non-block
-Abort migrations if concurrent access is detected.
+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.
.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, --component-end <\fIend\fR>
-The end offset of the component,
+.B -E\fR, \fB--component-end \fR<\fIend\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
-is specified in bytes, or using a suffix (kMGTP),
-such as 256M. -1 means the end of file.
-.TP
-.B -I, --component-id <\fIcomp_id\fR>
-The numerical unique component id.
-.TP
-.B --component-flags <\fIflags\fR>
-Component flags. Available flags: \fBinit\fR: instatiated component.
+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
.B --component-add
-Add specified components to an existing composite file.
+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. Deletion must start
-with the last component.
+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>
+Find, set, or clear
+.B flags
+on a specific component. Allowed
+.I flags
+are:
+.RS
+.B * init\fR - component is initialized (has allocated objects). Used with
+.B --component-del --component-flags ^init
+to find uninitialized components.
+.RE
+.RS
+.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
+.BR stale ,
+it isn't permitted to clear this flag directly. \fBlfs-mirror-resync\fR(1)
+is required to clear the flag.
+.RE
+.RS
+.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
+.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
+.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]
+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
-.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
+.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
-.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 -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 -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 --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 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 --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
-.B $ lfs setstripe --component-del -I 1 /mnt/lustre/file1
-This deletes the component with ID equals 1 from an existing file.
+.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.
.SH SEE ALSO
+.BR lctl (1),
.BR lfs (1),
.BR lfs-migrate (1),
+.BR lfs-mirror-create (1),
+.BR lfs-mirror-split (1),
.BR lustre (7)
git://git.whamcloud.com / fs / lustre-release.git / blobdiff