1 .TH LFS-SETSTRIPE 1 2017-08-23 "Lustre" "Lustre Utilities"
3 lfs setstripe \- set striping pattern of a file or directory default
5 .B lfs setstripe \fR[\fISTRIPE_OPTIONS\fR] <\fIdirectory\fR|\fIfile\fR>
7 .B lfs setstripe -E \fIend1\fR [\fISTRIPE_OPTIONS\fR] ... \
8 <\fIdirectory\fR|\fIfile\fR>
10 .B lfs setstripe --comp-add -E \fIend1\fR [\fISTRIPE_OPTIONS\fR] ... \
13 .B lfs setstripe --comp-del \fR{\fB-I \fIcomp_id\fR|\
14 \fB--comp-flags=\fIcomp_flags\fR} <\fIfile\fR>
16 .B lfs setstripe --comp-set \fR{-I \fIcomp_id\fR|\
17 \fB--comp-flags=\fIcomp_flags\fR} <\fIfile\fR>
19 .B lfs setstripe -N\fR[\fImirror_count\fR] \fR[\fISTRIPE_OPTIONS\fR] <\fIdirectory\fR|\fIfilename\fR>
21 .B lfs setstripe -d \fR<\fIdirectory\fR>
23 .B lfs setstripe --yaml=\fR<\fIyaml_template_file.lyl\fR> <\fIfile\fR>
25 .B lfs setstripe --copy=\fR<\fIsource_template_file\fR> <\fIfile\fR>
27 .B lfs setstripe --foreign[=\fR<\fIforeign_type\fR>\fB] \
28 [--flags=\fR<\fIhex\fR>\fB] --xattr=\fR<\fIlayout_string\fR> <\fIfile\fR>
32 command is used to create a new
34 in a Lustre filesystem with the specified layout, or to specify the default
35 layout for new files created in
37 or anywhere in the filesystem if
39 is the filesystem root and no other layout takes precedence.
41 Files with composite layouts allow different
43 to be specified for non-overlapping extents of the file. Files will
44 inherit options not explicitly specified on the command line either from
45 the default layout on the parent directory, or from the filesystem-wide
46 default. New subdirectories created under root directory will not explicitly
47 copy the default layout at creation time, but will implicitly inherit the
48 default layout at runtime. The default layout set on a non-root directory
49 will be copied to any new subdirectories created within that directory
50 at the time they are created.
52 .B lfs setstripe \fR[\fISTRIPE_OPTIONS\fR ...] <\fIdirectory\fR|\fIfile\fR>
55 with specified plain layout using the specified
57 or replace the default file layout on an existing
60 .B lfs setstripe -E \fIend\fR [\fISTRIPE_OPTIONS\fR] ... \
61 <\fIdirectory\fR|\fIfile\fR>
63 Create a new composite
65 with one or more component layouts (where \fIend\fR marks the end of the
66 current component), or set or replace the default file layout on an existing
69 .B lfs setstripe --component-add -E \fIend1\fR [\fISTRIPE_OPTIONS\fR] \
72 Add one or more components after the last component of an existing composite
73 file that does not yet have a component at
76 .B lfs setstripe --comp-del \fR{\fB-I \fIcomp_id\fR | \
77 \fB--comp-flags \fIcomp_flags\fR} <\fIfile\fR>
78 Remove the component(s) specified by component ID or flags from
81 .B lfs setstripe --comp-set \fR{\fB-I \fIcomp_id\fR | \
82 \fB--comp-flags \fIcomp_flags\fR} <\fIfile\fR>
85 on the specified component. This command can be only
86 be applied to mirrored files.
88 .B lfs setstripe -N \fR[\fImirror_count\fR] \fR[\fICOMPONENT_OPTIONS\fR] <\fIdirectory\fR|\fIfile\fR>
91 with the specified number of mirrors and other specified layout options, or
92 set or replace the default file layout on an existing
95 .B lfs setstripe -d \fR<\fIdirectory\fR>
97 Delete the default layout on the specified directory. It is not necessary
98 to delete the default layout on a directory before replacing it, only if
99 the directory should revert from a directory-specific default layout
100 to using the global filesystem default layout stored on the root directory.
102 .B lfs setstripe --yaml=\fR<\fIyaml_template_file.lyl\fR> <\fIfile\fR>
106 using the Lustre YAML Layout template
107 .IR yaml_template_file.lyl ,
112 .B lfs getstripe --yaml \fR<\fIexisting_file\fR> > <\fIyaml_template_file.lyl\fR>
114 .I yaml_template_file.lyl
115 is a plain-text file that may be saved and/or modified after creation.
116 This allows complex file layouts to be created once and re-used later.
118 .B lfs setstripe --copy=\fR<\fIsource_template_file\fR> <\fIfile\fR>
122 using the same layout as an existing
123 .IR source_template_file .
124 This is similar to the
126 option but avoids the need for the intermediate
130 .B lfs setstripe --foreign[=\fR<\fIforeign_type\fR>\fB] \
131 [--flags=\fR<\fIhex\fR>\fB] --xattr=\fR<\fIlayout_string\fR> <\fIfile\fR>
135 with a foreign/non-lustre layout of type
136 .I foreign_type \fR(\fBnone\fR, \fBdaos\fR, ...)
139 and a free-format layout value of
142 The various OST stripe related options are listed and explained below:
144 .B -c\fR, \fB--stripe-count \fR<\fIstripe_count\fR>
145 The number of OSTs to stripe a file over. \fB0 \fRmeans to use the
146 filesystem-wide default stripe count (default 1), and \fB-1 \fRmeans to stripe
147 over all available OSTs.
149 .B -C\fR, \fB--overstripe-count \fR<\fIstripe_count\fR>
150 The number of stripes to create, creating > 1 stripe per OST if count exceeds
151 the number of OSTs in the file system. \fB0 \fRmeans to use the filesystem-wide
152 default stripe count (default 1), and \fB-1 \fRmeans to stripe over all
155 .B -S\fR, \fB--stripe-size \fR<\fIstripe_size\fR>
156 The number of bytes to store on each OST before moving to the next OST. A
159 means the file should use the filesystem-wide default stripe_size
160 (default 1MiB). An optional suffix can be used to specify the units in
166 must be a multiple of 64KiB in size.
168 .B -i\fR, \fB--stripe-index \fR<\fIstart_ost_index\fR>
169 The OST index (starting at 0) on which to start striping for this file. A
173 allows the MDS to choose the starting index and it is strongly recommended, as
174 this allows space and load balancing to be done by the MDS as needed.
176 .B -L\fR, \fB--layout \fR<\fIlayout_type\fR>
177 The type of layout for that component, which can be one of:
179 .B raid0\fR - stripe the file data across
181 OST objects in units of
183 chunks. This is the default layout if not specified.
186 .B mdt\fR - place the first component of the file data on the MDT for faster
187 access where the inode is located. This can be used for small files, and with
188 composite file layouts. The
190 type may only be used for first component of a file. The
192 of the MDT component is always equal to the component size. There is also a
193 per-MDT tunable parameter
194 .IR lod.dom_stripesize
195 that limits the maximum size of a DoM stripe. It can be changed on the MDS via
196 .B lctl set_param lod.*.dom_stripesize=\fR<\fIstripe_size\fR> ,
199 must be a multiple of 64KiB in size,
205 .B -o\fR, \fB--ost \fR<\fIost_indices\fR>
206 Used to specify the exact stripe layout on the file system. \fIost_indices\fR
207 is a list of OSTs referenced by their indices, which are specified in decimal
208 or hex form and can be obtained using the
210 command. The list format consists of individual OST indices and index ranges
211 separated by commas, e.g. 1,2-4,7. The
213 option may be specified multiple times to stripe across the union of all listed
216 option is combined with
220 must agree with the number of OSTs in
224 option is combined with
228 must be in the OST list, and it will be used as the index on which to start
229 striping the file. Otherwise the striping will occur in the order specified in
232 .B -p\fR, \fB--pool \fR<\fIpool_name\fR>
233 Allocate objects from the predefined OST pool
235 for the layout of this file or component. The
240 can be used to select a subset of the OSTs within the pool; the
242 must be part of the pool or an error will be returned.
243 It is possible to specify a different pool for each component of a file. If
244 no pool is specified, it will be inherited from the previous component (for
245 later components of a composite layout) or the parent or root directory (for
248 layouts, or the first component of a composite file).
253 (since Lustre 2.11) to force a component to inherit the pool from the parent
254 or root directory instead of the previous component.
256 .B --foreign \fR[<\fIforeign_type\fR>]
257 file layout is non-lustre/free-format and of type <
259 >, if specified (see also
264 Current known types are
271 .B -x\fR, \fB--xattr \fR<\fIlayout_string\fR>
272 Mandatory non-lustre/free-format layout/LOV EA content for
276 .B -F\fR, \fB--flags \fR<\fIhex\fR>
277 Optional bitmap of flags for foreign type.
278 .SH COMPONENT_OPTIONS
279 The various component related options are listed and explained below. The
281 options can be shortened to
285 .B -E\fR, \fB--component-end \fR<\fIend\fR>
286 Add a new component to a file using the
290 argument. These options apply to the component ending at offset
292 in bytes, or by using a suffix (KMGTP) to specify base-two units,
293 such as 256M for 2^28 bytes. An offset of
297 means the following options extend to the end of the file. The first
298 component starts at offset 0, and each subsequent component starts at
299 the end of the previous component, so they must be specified in increasing
303 The first component specified will inherit default parameters from the
304 parent directory or the root directory like a plain layout, as specified
305 above. Later components will inherit the default layout parameters from
306 the previous component. Multiple
308 options are used to separate the
310 parameters for different regions of the file.
314 If a file does not have a component extending to
316 it will generate an error when trying to write beyond the last component
318 This can be useful to limit the size of a file to the end of the last
319 specified component, or use
321 to add more components to the end of the file.
324 .B -z, --extension-size, ext-size\fR <\fIext_size\fR>
325 This option modifies the \fB-E\fR option, components which have this
326 option specified are created as pairs of components, extendable and
330 The extendable component starts at offset 0 if this is the first
331 component of the file. In this case it ends at offset \fIext_size\fR and
332 it gets the flag \fBinit\fR (initialized). The extendable component starts
333 at the end of the previous component if this is not the first component of
334 the file. In this case it ends at the same offset (0-length component).
336 The extension component covers the rest of the specified region up to
337 the \fIend\fR specified by \fB-E\fR option and gets the flag \fBextension\fR.
338 This component covers the space reserved for the extendable component but
339 not used immediately, the later extension of the extendable component is done
340 by \fIext_size\fR each time until the extension component is used up. This is
341 used to control the space on OSTs the stripe is located on, in case one of
342 them is low on space, the remaining extension component region is added to the
347 Add components to the end an existing composite file. It is not possible
348 to add components incrementally to the default directory layout, since the
349 entire default layout can be replaced with a single
351 command. Adding components to mirrored files is not currently allowed.
354 Delete specified the components from an existing file using either the
355 .BR --component-id | -I
357 .BR --component-flags .
358 Deletion must start with the last component. The ID specified by the
360 option is the numerical unique ID of the component, it can be obtained using
363 command. It is not possible to delete components from a default directory
364 layout, since the entire default layout can be replaced with a single
367 The \fB--component-flags\fR option is used to specify certain type of
368 components. The only allowed component flag for deleting a component is
370 to indicate an uninstantiated component. Deleting a single component from
371 mirrored files is not currently allowed, see the
372 .BR lfs-mirror-split (1)
375 .B --component-flags \fR<\fIflags\fR>
378 on a specific component. Allowed
382 .B * init\fR - component is initialized (has allocated objects). Used with
383 .B --component-del --component-flags ^init
384 to find uninitialized components.
387 .B * prefer\fR - component preferred for read/write in a mirrored file
390 .B * stale\fR - component has outdated data in a mirrored file. This flag is
391 not allowed to be set on a component of the last non-stale mirror.
392 Once a component is marked
394 it isn't permitted to clear this flag directly. \fBlfs-mirror-resync\fR(1)
395 is required to clear the flag.
398 .B * nosync\fR - mirror components will not be resynched by default when the
399 .BR lfs-mirror-resync (1)
400 command is run. This option is useful to freeze a file mirror as an old
401 version or snapshot of the file.
404 A leading '^' before \fIflags\fR clears the flags, or finds components not
405 matching the flags. Multiple flags can be separated by comma(s).
408 .B -I\fR, \fB--component-id \fR<\fIcomp_id\fR>
409 The numerical unique component ID to identify a component to be modified.
411 .BR -N "[\fImirror_count\fR], " --mirror-count=" [\fImirror_count\fR]
414 identical replicas on the file or directory. The
416 argument is optional and defaults to 1 if it's not specified; if specified,
419 option without a space.
421 The \fISTRIPE_OPTIONS\fR specify the specific layout for the mirror. It
422 can be a plain layout with specific striping pattern or a composite layout.
423 If not specified, the stripe options are inherited from the previous
424 component. If there is no previous component, the
428 options are inherited from filesystem-wide default values, and OST
430 will be inherited from the parent directory.
434 options may be specified, each with its own
436 if there is a reason to have different layouts for the replicas, such as
437 flash pools and archive pools (see
438 .BR lfs-mirror-create (1)
442 that in the current client implementation, only
444 replica will be written by client nodes, and the other replicas need to
445 be resynched using the
447 command, or an external resync agent.
450 .B lfs setstripe -S 128K -c 2 /mnt/lustre/file1
451 This creates a file striped on two OSTs with 128KiB on each stripe.
453 .B lfs setstripe -d /mnt/lustre/dir
454 This deletes a default stripe pattern on dir. New files created in that
455 directory will use the filesystem global default instead.
457 .B lfs setstripe -N2 -E 1M -E eof -c -1 /mnt/lustre/dir1
458 This sets a default mirror layout on a directory with 2 PFL mirrors. Each mirror
459 has the same specified PFL layout.
461 .B lfs setstripe -N -E 1M -L mdt -E eof --component-flags=prefer -p flash \
462 -N -E 1G -c 1 -p disk -E eof -c -1 /mnt/lustre/file1
463 This creates a mirrored file with 2 replicas. The first replica is using the
464 MDT for files smaller than 1MB, and the remainder of the file is on the
466 OST pool with filesystem-wide default values. The second replica is on the
468 OST pool, with 1 stripe for the first 1GB of the file, and striped across
470 .B disk pool for the remainder of the file. Clients will
472 the first (flash) replica for both reads and writes.
474 .B lfs setstripe -E 4M -c 1 -E 64M -c 4 -E -1 -c -1 /mnt/lustre/file1
475 This creates a file with composite layout, the component has 1 stripe and
476 covers [0, 4MiB), the second component has 4 stripes and covers [4MiB, 64MiB),
477 the last component stripes over all available OSTs and covers [64MiB, EOF).
479 .B lfs setstripe -E -1 -z 64M /mnt/lustre/file1
480 This creates a file with a composite layout, the component one covers [0, 64MiB)
481 and the second component the rest [64MiB, EOF) originally. Once written beyond
482 64MiB the component one is extended to [0, 128MiB), once written beyond 128MiB
483 it is extended to [0, 192MiB), etc; the second component is shortened
487 When one of the OSTs of the first component layout is low on space, e.g. while
488 writing beyond 192MiB, the first component is left as [0, 192MiB), and a new
489 component is allocated between them, its layout repeats the first component
490 layout but initialized on different OSTs so that the full OSTs are avoided.
491 It is allocated and immediately extended to [192MiB, 256MiB), the following
492 extension component is shortened again.
495 .B lfs setstripe -E 1G -z 64M -E 100G -z 256M -E -1 -z 1G /mnt/lustre/file1
496 This creates a file with a composite layout, the component one covers [0,
497 64MiB), the third component covers [1G, 1G), the fifth component covers
498 [100GiB, 100GiB) originally. The second, fourth and sixth extension components
499 cover the left space accordingly. The process of writing is similar to above,
500 but when one of the OSTs of the first component layout is low on space, e.g.
501 while writing beyond 192MiB in the example above, the first component is left
502 as [0, 192MiB), the second (extension) component is removed, and its range
503 spills over to the third and the fourth components - they are moved left to
504 start at 192MiB instead of 100GiB; the third component is immediately extended
505 and becomes [192MiB, 448MiB), the fourth (the extension one) component becomes
508 .B lfs setstripe --component-add -E eof -c 4 /mnt/lustre/file1
509 This add a component which starts at the end of last existing component to
512 .B lfs setstripe --component-del -I 1 /mnt/lustre/file1
513 This deletes the component with ID equal to 1 from an existing file.
515 .B lfs setstripe --comp-set -I 1 --comp-flags=^prefer,stale /mnt/lustre/file1
516 This command will clear the \fBprefer\fR flag and set the \fBstale\fR flag on
520 .B lfs setstripe -E 1M -L mdt -E -1 /mnt/lustre/file1
523 with Data-on-MDT layout. The first 1MiB of the file data is placed on the
524 MDT and rest of file is placed on OST(s) with default striping.
526 .B lfs setstripe --yaml=/tmp/layout_yaml /mnt/lustre/file2
529 with layout stored in the layout template
532 which can be created with the
533 .B lfs getstripe --yaml
536 .B lfs setstripe --foreign=daos --flags=0xda08 \
537 --xattr=PUUID:CUUID /mnt/lustre/file1
542 with non-lustre/free-format
544 layout/LOV EA and flags
551 .BR lfs-mirror-create (1),
552 .BR lfs-mirror-split (1),