Whamcloud - gitweb
LU-17743 o2iblnd: fix privileged port check in passive_connect
[fs/lustre-release.git] / lustre / doc / lfs-setstripe.1
1 .TH LFS-SETSTRIPE 1 2017-08-23 "Lustre" "Lustre Utilities"
2 .SH NAME
3 lfs-setstripe \- set striping pattern of a file or directory default
4 .SH SYNOPSIS
5 .B lfs setstripe \fR[\fISTRIPE_OPTIONS\fR] \fIDIRECTORY\fR|\fIFILENAME\fR
6 .br
7 .B lfs setstripe -E \fICOMP_END\fR [\fISTRIPE_OPTIONS\fR] ... \
8 \fIDIRECTORY\fR|\fIFILENAME\fR
9 .br
10 .B lfs setstripe --comp-add -E \fICOMP_END\fR [\fISTRIPE_OPTIONS\fR] ... \
11 \fIFILENAME\fR
12 .br
13 .B lfs setstripe --comp-del \fR[\fB-I \fICOMP_ID\fR|\
14 \fB--comp-flags=\fICOMP_FLAGS\fR] \fIFILENAME\fR
15 .br
16 .B lfs setstripe --comp-set \fR[\fB-I \fICOMP_ID\fR|\
17 \fB--comp-flags=\fICOMP_FLAGS\fR] \fIFILENAME\fR
18 .br
19 .B lfs setstripe -N\fR[\fIMIRROR_COUNT\fR] \fR[\fISTRIPE_OPTIONS\fR] \fIDIRECTORY\fR|\fIFILENAME\fR
20 .br
21 .B lfs setstripe -d \fR\fIDIRECTORY\fR
22 .br
23 .B lfs setstripe --yaml=\fR\fIYAML_TEMPLATE_FILE.LYL\fR \fIFILENAME\fR
24 .br
25 .B lfs setstripe --copy=\fR\fISOURCE_TEMPLATE_FILE\fR \fIFILENAME\fR
26 .br
27 .B lfs setstripe --foreign\fR[\fB=\fR\fIFOREIGN_TYPE\fR] \
28 \fR[\fB--flags=\fR\fIHEX\fR] \fB--xattr=\fR\fILAYOUT_STRING\fR \fIFILENAME\fR
29 .SH DESCRIPTION
30 .nh
31 .ad l
32 The
33 .B lfs setstripe
34 command is used to create a new
35 .I FILENAME
36 in a Lustre filesystem with the specified layout, or to specify the default
37 layout for new files created in
38 .IR DIRECTORY ,
39 or anywhere in the filesystem if
40 .I DIRECTORY
41 is the filesystem root and no other layout takes precedence.
42 .PP
43 Files with composite layouts allow different
44 .I STRIPE_OPTIONS
45 to be specified for non-overlapping extents of the file. Files will
46 inherit options not explicitly specified on the command line either from
47 the default layout on the parent directory, or from the filesystem-wide
48 default. New subdirectories created under root directory will not explicitly
49 copy the default layout at creation time, but will implicitly inherit the
50 default layout at runtime. The default layout set on a non-root directory
51 will be copied to any new subdirectories created within that directory
52 at the time they are created.
53 .TP
54 .B lfs setstripe \fR[\fISTRIPE_OPTIONS\fR ...] \fIDIRECTORY\fR|\fIFILENAME\fR
55 Create a new
56 .I FILENAME
57 with specified plain layout using the specified
58 .IR STRIPE_OPTIONS ,
59 or replace the default file layout on an existing
60 .IR DIRECTORY .
61 .TP
62 .B lfs setstripe -E \fIEND_OFFSET\fR [\fISTRIPE_OPTIONS\fR] ... \
63 \fIDIRECTORY\fR|\fIFILENAME\fR
64 .br
65 Create a new composite
66 .I FILENAME
67 with one or more component layouts (where \fIEND_OFFSET\fR marks the end of the
68 current component), or set or replace the default file layout on an existing
69 .IR DIRECTORY.
70 .TP
71 .B lfs setstripe --component-add -E \fIEND_OFFSET\fR [\fISTRIPE_OPTIONS\fR] \
72 ... \fIFILENAME\fR
73 .br
74 Add one or more components after the last component of an existing composite
75 file that does not yet have a component at
76 .BR eof .
77 .TP
78 .B lfs setstripe --comp-del \fR[\fB-I \fICOMP_ID\fR | \
79 \fB--comp-flags \fICOMP_FLAGS\fR] \fIFILENAME\fR
80 Remove the component(s) specified by component ID or flags from
81 .IR FILENAME .
82 .TP
83 .B lfs setstripe --comp-set \fR[\fB-I \fICOMP_ID\fR | \
84 \fB--comp-flags \fICOMP_FLAGS\fR] \fIFILENAME\fR
85 Set or clear
86 .I COMP_FLAGS
87 on the specified component. This command can be only
88 be applied to mirrored files.
89 .TP
90 .B lfs setstripe -N \fR[\fIMIRROR_COUNT\fR] \fR[\fICOMPONENT_OPTIONS\fR] \fIDIRECTORY\fR|\fIFILENAME\fR
91 Create a new
92 .I FILENAME
93 with the specified number of mirrors and other specified layout options, or
94 set or replace the default file layout on an existing
95 .IR DIRECTORY .
96 .TP
97 .B lfs setstripe -d \fR\fIDIRECTORY\fR
98 .br
99 Delete the default layout on the specified directory.  It is not necessary
100 to delete the default layout on a directory before replacing it, only if
101 the directory should revert from a directory-specific default layout
102 to using the global filesystem default layout stored on the root directory.
103 .TP
104 .B lfs setstripe --yaml=\fR\fIYAML_TEMPLATE_FILE.LYL\fR \fIFILENAME\fR
105 .br
106 Create a new
107 .I FILENAME
108 using the Lustre YAML Layout template
109 .IR YAML_TEMPLATE_FILE.LYL ,
110 created from
111 .I EXISTING_FILE
112 via:
113 .br
114 .B lfs getstripe --yaml \fR\fIEXISTING_FILE\fR > \fIYAML_TEMPLATE_FILE.LYL\fR
115 .br
116 .I YAML_TEMPLATE_FILE.LYL
117 is a plain-text file that may be saved and/or modified after creation.
118 This allows complex file layouts to be created once and re-used later.
119 .TP
120 .B lfs setstripe --copy=\fR\fISOURCE_TEMPLATE_FILE\fR \fIFILENAME\fR
121 .br
122 Create a new
123 .I file
124 using the same layout as an existing
125 .IR SOURCE_TEMPLATE_FILE .
126 This is similar to the
127 .B --yaml
128 option but avoids the need for the intermediate
129 .B .lyl
130 file.
131 .TP
132 .B lfs setstripe --foreign[=\fR\fIFOREIGN_TYPE\fR\fB] \
133 [--flags=\fR\fIHEX\fR\fB] --xattr=\fR\fILAYOUT_STRING\fR \fIFILENAME\fR
134 .br
135 Create a new
136 .I FILENAME
137 with a foreign/non-lustre layout of type
138 .I FOREIGN_TYPE \fR(\fBnone\fR, \fBdaos\fR, ...)
139 with flags
140 .I HEX
141 and a free-format layout value of
142 .I LAYOUT_STRING.
143 .SH STRIPE_OPTIONS
144 The various OST stripe related options are listed and explained below:
145 .TP
146 .B -c\fR, \fB--stripe-count \fR\fISTRIPE_COUNT\fR
147 The number of OSTs to stripe a file over. \fB0 \fRmeans to use the
148 filesystem-wide default stripe count (default 1), and \fB-1 \fRmeans to stripe
149 over all available OSTs.
150 .TP
151 .B -C\fR, \fB--overstripe-count \fR\fISTRIPE_COUNT\fR
152 The number of stripes to create, creating > 1 stripe per OST if count exceeds
153 the number of OSTs in the file system. \fB0 \fRmeans to use the filesystem-wide
154 default stripe count (default 1), and \fB range -1 to -32\fRmeans to stripe
155 over all available OSTs in multiple of OST count. For example, \fB-1\fR means
156 one stripe per OST, -2 means two stripes per OST, and so on.
157 .TP
158 .B -S\fR, \fB--stripe-size \fR\fISTRIPE_SIZE\fR
159 The number of bytes to store on each OST before moving to the next OST. A
160 stripe size of
161 .B 0
162 means the file should use the filesystem-wide default stripe size
163 (default 4MiB).  An optional suffix can be used to specify the units in
164 .BR K ibi-,
165 .BR M "ebi-, or"
166 .BR G ibibytes.
167 The
168 .I STRIPE_SIZE
169 must be a multiple of 64KiB.  Values below 4096 are assumed to be in KiB units.
170 .TP
171 .B -i\fR, \fB--stripe-index \fR\fISTART_OST_IDX\fR
172 The OST index (starting at 0) on which to start striping for this file.  A
173 .I START_OST_IDX
174 of
175 .B -1
176 allows the MDS to choose the starting index and it is strongly recommended, as
177 this allows space and load balancing to be done by the MDS as needed.
178 .TP
179
180 The type of layout for that component, which can be one of:
181 .RS
182 .B raid0\fR - stripe the file data across
183 \fISTRIPE_COUNT\fR OST objects in units of
184 \fISTRIPE_SIZE\fR chunks. This is the default layout if not specified.
185 .RE
186 .RS
187 .B mdt\fR - place the first component of the file data on the MDT for faster
188 access where the inode is located. This can be used for small files, and with
189 composite file layouts. The
190 .B mdt
191 type may only be used for first component of a file. The
192 .IR STRIPE_SIZE
193 of the MDT component is always equal to the component size. There is also a
194 per-MDT tunable parameter
195 .IR lod.dom_stripesize
196 that limits the maximum size of a DoM stripe.  It can be changed on the MDS via
197 .B lctl set_param lod.*.dom_stripesize=\fR\fISTRIPE_SIZE\fR ,
198 where
199 .I STRIPE_SIZE
200 must be a multiple of 64KiB in size,
201 see also
202 .BR lctl (8)
203 for details.
204 .RE
205 .TP
206 .B -o\fR, \fB--ost \fR\fIOST_IDX\fR
207 Used to specify the exact stripe layout on the file system. \fIOST_IDX\fR
208 is a list of OSTs referenced by their indices, which are specified in decimal
209 or hex form and can be obtained using the
210 .B lfs osts
211 command. The list format consists of individual OST indices and index ranges
212 separated by commas, e.g. 1,2-4,7. The
213 .B -o
214 option may be specified multiple times to stripe across the union of all listed
215 OSTs. If the
216 .B -c
217 option is combined with
218 .B -o
219 the
220 .I STRIPE_COUNT
221 must agree with the number of OSTs in
222 .IR OST_IDX .
223 If the
224 .B -i
225 option is combined with
226 .B -o
227 the
228 .I START_OST_IDX
229 must be in the OST list, and it will be used as the index on which to start
230 striping the file. Otherwise the striping will occur in the order specified in
231 .IR OST_IDX .
232 .TP
233 .B -p\fR, \fB--pool \fR\fIPOOL_NAME\fR
234 Allocate objects from the predefined OST pool
235 .I POOL_NAME
236 for the layout of this file or component. The
237 .IR STRIPE_COUNT ,
238 .IR STRIPE_SIZE ,
239 and
240 .I START_OST_IDX
241 can be used to select a subset of the OSTs within the pool; the
242 .I START_OST_IDX
243 must be part of the pool or an error will be returned.
244 It is possible to specify a different pool for each component of a file.  If
245 no pool is specified, it will be inherited from the previous component (for
246 later components of a composite layout) or the parent or root directory (for
247 plain
248 .B raid0
249 layouts, or the first component of a composite file).
250 Use
251 .BR pool_name=ignore
252 to force a component without a pool set (no inheritance from last component,
253 root or parent).
254 Use
255 .BR pool_name=''
256 or
257 .BR pool_name=inherit
258 (since Lustre 2.15) to force a component to inherit the pool from the parent
259 or root directory instead of the previous component.
260 .TP
261 .B --foreign \fR[\fIFOREIGN_TYPE\fR]
262 file layout is non-lustre/free-format and of type
263 .IR FOREIGN_TYPE
264 , if specified (see also
265 .IR --xattr
266 and
267 .IR --flags
268 options).
269 Current known types are
270 .BR none
271 and
272 .BR symlink
273 , default is
274 .BR none
275 .
276 .B -x\fR, \fB--xattr \fR\fILAYOUT_STRING\fR
277 Mandatory non-lustre/free-format layout/LOV EA content for
278 .I foreign
279 file.
280 .TP
281 .B -F\fR, \fB--flags \fR\fIHEX\fR
282 Optional bitmap of flags for foreign type.
283 .SH COMPONENT_OPTIONS
284 The various component related options are listed and explained below.  The
285 .B --component-*
286 options can be shortened to
287 .B --comp-*
288 if desired.
289 .TP
290 .B -E\fR, \fB--component-end \fR\fIEND_OFFSET\fR
291 Add a new component to a file using the
292 .I STRIPE_OPTIONS
293 following the
294 .B -E
295 argument.  These options apply to the component ending at offset
296 .I END_OFFSET
297 in bytes, or by using a suffix (KMGTP) to specify base-two units,
298 such as 256M for 2^28 bytes. An offset of
299 .B -1
300 or
301 .B eof
302 means the following options extend to the end of the file.  The first
303 component starts at offset 0, and each subsequent component starts at
304 the end of the previous component, so they must be specified in increasing
305 file offset order, and must be a multiple of 64KiB to align with the
306 minimum
307 .I STRIPE_SIZE
308 value.  Values below 4096 are assumed to be in KiB units.
309 .PP
310 .RS
311 The first component specified will inherit default parameters from the
312 parent directory or the root directory like a plain layout, as specified
313 above.  Later components will inherit the default layout parameters from
314 the previous component.  Multiple
315 .B -E
316 options are used to separate the
317 .I STRIPE_OPTIONS
318 parameters for different regions of the file.
319 .RE
320 .PP
321 .RS
322 If a file does not have a component extending to
323 .B eof
324 it will generate an error when trying to write beyond the last component
325 .IR end .
326 This can be useful to limit the size of a file to the end of the last
327 specified component, or use
328 .B --component-add
329 to add more components to the end of the file.
330 .RE
331 .TP
332 .B -z, --extension-size, --ext-size\fR \fIEXT_SIZE\fR
333 This option modifies the \fB-E\fR option, components which have this
334 option specified are created as pairs of components, extendable and
335 extension ones.
336 .PP
337 .RS
338 The extendable component starts at offset 0 if this is the first
339 component of the file. In this case it ends at offset \fIEXT_SIZE\fR and
340 it gets the flag \fBinit\fR (initialized). The extendable component starts
341 at the end of the previous component if this is not the first component of
342 the file. In this case it ends at the same offset (0-length component).
343 .PP
344 The extension component covers the rest of the specified region up to
345 the \fIEND_OFFSET\fR specified by \fB-E\fR option and gets
346 the flag \fBextension\fR.
347 This component covers the space reserved for the extendable component but
348 not used immediately, the later extension of the extendable component is done
349 by \fIEXT_SIZE\fR each time until the extension component is used up. This is
350 used to control the space on OSTs the stripe is located on, in case one of
351 them is low on space, the remaining extension component region is added to the
352 next component.
353 .RE
354 .TP
355 .B --component-add
356 Add components to the end an existing composite file.  It is not possible
357 to add components incrementally to the default directory layout, since the
358 entire default layout can be replaced with a single
359 .B lfs setstripe
360 command.  Adding components to mirrored files is not currently allowed.
361 .TP
362 .B --component-del
363 Delete specified the components from an existing file using either the
364 .BR --component-id | -I
365 or
366 .BR --component-flags .
367 Deletion must start with the last component.  The ID specified by the
368 .B -I
369 option is the numerical unique ID of the component, it can be obtained using
370 the
371 .B lfs getstripe -I
372 command.  It is not possible to delete components from a default directory
373 layout, since the entire default layout can be replaced with a single
374 .B lfs setstripe
375 call.
376 The \fB--component-flags\fR option is used to specify certain type of
377 components. The only allowed component flag for deleting a component is
378 .B ^init
379 to indicate an uninstantiated component.  Deleting a single component from
380 mirrored files is not currently allowed, see the
381 .BR lfs-mirror-split (1)
382 command.
383 .TP
384 .B --component-flags \fR\fICOMP_FLAGS\fR
385 Find, set, or clear
386 .B flags
387 on a specific component. Allowed
388 .I flags
389 are:
390 .RS
391 .B * init\fR - component is initialized (has allocated objects).  Used with
392 .B --component-del --component-flags ^init
393 to find uninitialized components.
394 .RE
395 .RS
396 .B * prefer\fR - component preferred for read/write in a mirrored file
397 .RE
398 .RS
399 .B * prefrd\fR - component preferred for read in a mirrored file
400 .RE
401 .RS
402 .B * prefwr\fR - component preferred for write in a mirrored file
403 .RE
404 .RS
405 .B * stale\fR - component has outdated data in a mirrored file. This flag is
406 not allowed to be set on a component of the last non-stale mirror.
407 Once a component is marked
408 .BR stale ,
409 it isn't permitted to clear this flag directly. \fBlfs-mirror-resync\fR(1)
410 is required to clear the flag.
411 .RE
412 .RS
413 .B * nosync\fR - mirror components will not be resynched by default when the
414 .BR lfs-mirror-resync (1)
415 command is run. This option is useful to freeze a file mirror as an old
416 version or snapshot of the file.
417 .RE
418 .RS
419 A leading '^' before \fIflags\fR clears the flags, or finds components not
420 matching the flags.  Multiple flags can be separated by comma(s).
421 .RE
422 .TP
423 .B -I\fR, \fB--component-id \fR\fICOMP_ID\fR
424 The numerical unique component ID to identify a component to be modified.
425 .TP
426 .BR -N, \fB--mirror-count  \fR[\fIMIRROR_COUNT\fR]
427 Create a file with
428 .I MIRROR_COUNT
429 identical replicas on the file or directory.  The
430 .I MIRROR_COUNT
431 argument is optional and defaults to 1 if it's not specified; if specified,
432 it must follow the
433 .B -N
434 option without a space. The maximum possible value for the mirror count is 16.
435 .br
436 The \fISTRIPE_OPTIONS\fR specify the specific layout for the mirror. It
437 can be a plain layout with specific striping pattern or a composite layout.
438 If not specified, the stripe options are inherited from the previous
439 component. If there is no previous component, the
440 .I STRIPE_COUNT
441 and
442 .I STRIPE_SIZE
443 options are inherited from filesystem-wide default values, and OST
444 .I POOL_NAME
445 will be inherited from the parent directory.
446 .br
447 Multiple
448 .B -N
449 options may be specified, each with its own
450 .I STRIPE_OPTIONS
451 if there is a reason to have different layouts for the replicas, such as
452 flash pools and archive pools (see
453 .BR lfs-mirror-create (1)
454 for full details).
455 .br
456 .B NOTE
457 that in the current client implementation, only
458 .B one
459 replica will be written by client nodes, and the other replicas need to
460 be resynched using the
461 .B lfs mirror resync
462 command, or an external resync agent.
463 .SH EXAMPLES
464 .TP
465 .B lfs setstripe -S 128K -c 2 /mnt/lustre/file1
466 This creates a file striped on two OSTs with 128KiB on each stripe.
467 .TP
468 .B lfs setstripe -d /mnt/lustre/dir
469 This deletes a default stripe pattern on dir. New files created in that
470 directory will use the filesystem global default instead.
471 .TP
472 .B lfs setstripe -N2 -E 1M -E eof -c -1 /mnt/lustre/dir1
473 This sets a default mirror layout on a directory with 2 PFL mirrors. Each mirror
474 has the same specified PFL layout.
475 .TP
476 .B lfs setstripe -N -E 1M -L mdt -E eof --component-flags=prefer -p flash \
477     -N -E 1G -c 1 -p disk -E eof -c -1 /mnt/lustre/file1
478 This creates a mirrored file with 2 replicas. The first replica is using the
479 MDT for files smaller than 1MB, and the remainder of the file is on the
480 .B flash
481 OST pool with filesystem-wide default values.  The second replica is on the
482 .B disk
483 OST pool, with 1 stripe for the first 1GB of the file, and striped across
484 all OSTs in the
485 .B disk pool for the remainder of the file.  Clients will
486 .B prefer
487 the first (flash) replica for both reads and writes.
488 .TP
489 .B lfs setstripe -E 4M -c 1 -E 64M -c 4 -E -1 -c -1 /mnt/lustre/file1
490 This creates a file with composite layout, the component has 1 stripe and
491 covers [0, 4MiB), the second component has 4 stripes and covers [4MiB, 64MiB),
492 the last component stripes over all available OSTs and covers [64MiB, EOF).
493 .TP
494 .B lfs setstripe -E -1 -z 64M /mnt/lustre/file1
495 This creates a file with a composite layout, the component one covers [0, 64MiB)
496 and the second component the rest [64MiB, EOF) originally. Once written beyond
497 64MiB the component one is extended to [0, 128MiB), once written beyond 128MiB
498 it is extended to [0, 192MiB), etc; the second component is shortened
499 appropriately.
500 .PP
501 .RS
502 When one of the OSTs of the first component layout is low on space, e.g. while
503 writing beyond 192MiB, the first component is left as [0, 192MiB), and a new
504 component is allocated between them, its layout repeats the first component
505 layout but initialized on different OSTs so that the full OSTs are avoided.
506 It is allocated and immediately extended to [192MiB, 256MiB), the following
507 extension component is shortened again.
508 .RE
509 .TP
510 .B lfs setstripe -E 1G -z 64M -E 100G -z 256M -E -1 -z 1G /mnt/lustre/file1
511 This creates a file with a composite layout, the component one covers [0,
512 64MiB), the third component covers [1G, 1G), the fifth component covers
513 [100GiB, 100GiB) originally. The second, fourth and sixth extension components
514 cover the left space accordingly. The process of writing is similar to above,
515 but when one of the OSTs of the first component layout is low on space, e.g.
516 while writing beyond 192MiB in the example above, the first component is left
517 as [0, 192MiB), the second (extension) component is removed, and its range
518 spills over to the third and the fourth components - they are moved left to
519 start at 192MiB instead of 100GiB; the third component is immediately extended
520 and becomes [192MiB, 448MiB), the fourth (the extension one) component becomes
521 [448MiB, 100GiB).
522 .TP
523 .B lfs setstripe --component-add -E eof -c 4  /mnt/lustre/file1
524 This add a component which starts at the end of last existing component to
525 the end of file.
526 .TP
527 .B lfs setstripe --component-del -I 1 /mnt/lustre/file1
528 This deletes the component with ID equal to 1 from an existing file.
529 .TP
530 .B lfs setstripe --comp-set -I 1 --comp-flags=^prefer,stale /mnt/lustre/file1
531 This command will clear the \fBprefer\fR flag and set the \fBstale\fR flag on
532 .B file1
533 component ID 1.
534 .TP
535 .B lfs setstripe -E 1M -L mdt -E -1 /mnt/lustre/file1
536 Create
537 .B file1
538 with Data-on-MDT layout. The first 1MiB of the file data is placed on the
539 MDT and rest of file is placed on OST(s) with default striping.
540 .TP
541 .B lfs setstripe --yaml=/tmp/layout_yaml /mnt/lustre/file2
542 This creates
543 .B file2
544 with layout stored in the layout template
545 file
546 .B layout_yaml
547 which can be created with the
548 .B lfs getstripe --yaml
549 command.
550 .TP
551 .B lfs setstripe --foreign=symlink --flags=0xda08 \
552         --xattr=PUUID:CUUID /mnt/lustre/file1
553 This creates foreign
554 .BR file1
555 of type
556 .BR symlink
557 with non-lustre/free-format
558 .BR PUUID:CUUID
559 layout/LOV EA and flags
560 .BR 0xda08
561 .
562 .SH SEE ALSO
563 .BR lctl (1),
564 .BR lfs (1),
565 .BR lfs-migrate (1),
566 .BR lfs-mirror-create (1),
567 .BR lfs-mirror-split (1),
568 .BR lustre (7)