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|\fIfile\fR>
   6 .br
   7 .B lfs setstripe -E \fIend1\fR [\fISTRIPE_OPTIONS\fR] ... \
   8 <\fIdirectory\fR|\fIfile\fR>
   9 .br
  10 .B lfs setstripe --comp-add -E \fIend1\fR [\fISTRIPE_OPTIONS\fR] ... \
  11 <\fIfile\fR>
  12 .br
  13 .B lfs setstripe --comp-del \fR{\fB-I \fIcomp_id\fR|\
  14 \fB--comp-flags=\fIcomp_flags\fR} <\fIfile\fR>
  15 .br
  16 .B lfs setstripe --comp-set \fR{-I \fIcomp_id\fR|\
  17 \fB--comp-flags=\fIcomp_flags\fR} <\fIfile\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> <\fIfile\fR>
  24 .br
  25 .B lfs setstripe --copy=\fR<\fIsource_template_file\fR> <\fIfile\fR>
  26 .br
  27 .B lfs setstripe --foreign[=\fR<\fIforeign_type\fR>\fB] \
  28 [--flags=\fR<\fIhex\fR>\fB] --xattr=\fR<\fIlayout_string\fR> <\fIfile\fR>
  29 .SH DESCRIPTION
  30 The
  31 .B lfs setstripe
  32 command is used to create a new
  33 .I file
  34 in a Lustre filesystem with the specified layout, or to specify the default
  35 layout for new files created in
  36 .IR directory ,
  37 or anywhere in the filesystem if
  38 .I directory
  39 is the filesystem root and no other layout takes precedence.
  40 .PP
  41 Files with composite layouts allow different
  42 .I STRIPE_OPTIONS
  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.
  51 .TP
  52 .B lfs setstripe \fR[\fISTRIPE_OPTIONS\fR ...] <\fIdirectory\fR|\fIfile\fR>
  53 Create a new
  54 .I file
  55 with specified plain layout using the specified
  56 .IR STRIPE_OPTIONS ,
  57 or replace the default file layout on an existing
  58 .IR directory .
  59 .TP
  60 .B lfs setstripe -E \fIend\fR [\fISTRIPE_OPTIONS\fR] ... \
  61 <\fIdirectory\fR|\fIfile\fR>
  62 .br
  63 Create a new composite
  64 .I file
  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
  67 .IR directory.
  68 .TP
  69 .B lfs setstripe --component-add -E \fIend1\fR [\fISTRIPE_OPTIONS\fR] \
  70 ... <\fIfile\fR>
  71 .br
  72 Add one or more components after the last component of an existing composite
  73 file that does not yet have a component at
  74 .BR eof .
  75 .TP
  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
  79 .IR file .
  80 .TP
  81 .B lfs setstripe --comp-set \fR{\fB-I \fIcomp_id\fR | \
  82 \fB--comp-flags \fIcomp_flags\fR} <\fIfile\fR>
  83 Set or clear
  84 .I flags
  85 on the specified component. This command can be only
  86 be applied to mirrored files.
  87 .TP
  88 .B lfs setstripe -N \fR[\fImirror_count\fR] \fR[\fICOMPONENT_OPTIONS\fR] <\fIdirectory\fR|\fIfile\fR>
  89 Create a new
  90 .I file
  91 with the specified number of mirrors and other specified layout options, or
  92 set or replace the default file layout on an existing
  93 .IR directory .
  94 .TP
  95 .B lfs setstripe -d \fR<\fIdirectory\fR>
  96 .br
  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.
 101 .TP
 102 .B lfs setstripe --yaml=\fR<\fIyaml_template_file.lyl\fR> <\fIfile\fR>
 103 .br
 104 Create a new
 105 .I file
 106 using the Lustre YAML Layout template
 107 .IR yaml_template_file.lyl ,
 108 created from
 109 .I existing_file
 110 via:
 111 .br
 112 .B lfs getstripe --yaml \fR<\fIexisting_file\fR> > <\fIyaml_template_file.lyl\fR>
 113 .br
 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.
 117 .TP
 118 .B lfs setstripe --copy=\fR<\fIsource_template_file\fR> <\fIfile\fR>
 119 .br
 120 Create a new
 121 .I file
 122 using the same layout as an existing
 123 .IR source_template_file .
 124 This is similar to the
 125 .B --yaml
 126 option but avoids the need for the intermediate
 127 .B .lyl
 128 file.
 129 .TP
 130 .B lfs setstripe --foreign[=\fR<\fIforeign_type\fR>\fB] \
 131 [--flags=\fR<\fIhex\fR>\fB] --xattr=\fR<\fIlayout_string\fR> <\fIfile\fR>
 132 .br
 133 Create a new
 134 .I file
 135 with a foreign/non-lustre layout of type
 136 .I foreign_type \fR(\fBnone\fR, \fBsymlink\fR, ...)
 137 with flags
 138 .I hex
 139 and a free-format layout value of
 140 .I layout_string.
 141 .SH STRIPE_OPTIONS
 142 The various OST stripe related options are listed and explained below:
 143 .TP
 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.
 148 .TP
 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
 153 available OSTs.
 154 .TP
 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
 157 stripe size of
 158 .B 0
 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
 161 .BR K ibi-,
 162 .BR M "ebi-, or"
 163 .BR G ibibytes.
 164 The
 165 .I stripe_size
 166 must be a multiple of 64KiB.  Values below 4096 are assumed to be in KiB units.
 167 .TP
 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
 170 .I start_ost_index
 171 of
 172 .B -1
 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.
 175 .TP
 176 .B -L\fR, \fB--layout \fR<\fIlayout_type\fR>
 177 The type of layout for that component, which can be one of:
 178 .RS
 179 .B raid0\fR - stripe the file data across
 180 .B stripe_count
 181 OST objects in units of
 182 .B stripe_size
 183 chunks.  This is the default layout if not specified.
 184 .RE
 185 .RS
 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
 189 .B mdt
 190 type may only be used for first component of a file. The
 191 .IR stripe_size
 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> ,
 197 where
 198 .I stripe_size
 199 must be a multiple of 64KiB in size,
 200 see also
 201 .BR lctl (8)
 202 for details.
 203 .RE
 204 .TP
 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
 209 .B lfs osts
 210 command. The list format consists of individual OST indices and index ranges
 211 separated by commas, e.g. 1,2-4,7. The
 212 .B -o
 213 option may be specified multiple times to stripe across the union of all listed
 214 OSTs. If the
 215 .B -c
 216 option is combined with
 217 .B -o
 218 the
 219 .I stripe_count
 220 must agree with the number of OSTs in
 221 .IR ost_indices .
 222 If the
 223 .B -i
 224 option is combined with
 225 .B -o
 226 the
 227 .I start_ost_index
 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
 230 .IR ost_indices .
 231 .TP
 232 .B -p\fR, \fB--pool \fR<\fIpool_name\fR>
 233 Allocate objects from the predefined OST pool
 234 .I pool_name
 235 for the layout of this file or component. The
 236 .IR stripe_count ,
 237 .IR stripe_size ,
 238 and
 239 .I start_ost_index
 240 can be used to select a subset of the OSTs within the pool; the
 241 .I start_ost_index
 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
 246 plain
 247 .B raid0
 248 layouts, or the first component of a composite file).
 249 Use
 250 .BR pool_name='' ,
 251 or
 252 .BR pool_name=none
 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.
 255 .TP
 256 .B --foreign \fR[<\fIforeign_type\fR>]
 257 file layout is non-lustre/free-format and of type <
 258 .IR foreign_type
 259 >, if specified (see also
 260 .IR --xattr
 261 and
 262 .IR --flags
 263 options).
 264 Current known types are
 265 .BR none
 266 and
 267 .BR symlink
 268 , default is
 269 .BR none
 270 .
 271 .B -x\fR, \fB--xattr \fR<\fIlayout_string\fR>
 272 Mandatory non-lustre/free-format layout/LOV EA content for
 273 .I foreign
 274 file.
 275 .TP
 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
 280 .B --component-*
 281 options can be shortened to
 282 .B --comp-*
 283 if desired.
 284 .TP
 285 .B -E\fR, \fB--component-end \fR<\fIend\fR>
 286 Add a new component to a file using the
 287 .I STRIPE_OPTIONS
 288 following the
 289 .B -E
 290 argument.  These options apply to the component ending at offset
 291 .I end
 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
 294 .B -1
 295 or
 296 .B eof
 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
 300 file offset order, and must be a multiple of 64KiB to align with the
 301 minimum
 302 .I stripe_size
 303 value.  Values below 4096 are assumed to be in KiB units.
 304 .PP
 305 .RS
 306 The first component specified will inherit default parameters from the
 307 parent directory or the root directory like a plain layout, as specified
 308 above.  Later components will inherit the default layout parameters from
 309 the previous component.  Multiple
 310 .B -E
 311 options are used to separate the
 312 .I STRIPE_OPTIONS
 313 parameters for different regions of the file.
 314 .RE
 315 .PP
 316 .RS
 317 If a file does not have a component extending to
 318 .B eof
 319 it will generate an error when trying to write beyond the last component
 320 .IR end .
 321 This can be useful to limit the size of a file to the end of the last
 322 specified component, or use
 323 .B --component-add
 324 to add more components to the end of the file.
 325 .RE
 326 .TP
 327 .B -z, --extension-size, ext-size\fR <\fIext_size\fR>
 328 This option modifies the \fB-E\fR option, components which have this
 329 option specified are created as pairs of components, extendable and
 330 extension ones.
 331 .PP
 332 .RS
 333 The extendable component starts at offset 0 if this is the first
 334 component of the file. In this case it ends at offset \fIext_size\fR and
 335 it gets the flag \fBinit\fR (initialized). The extendable component starts
 336 at the end of the previous component if this is not the first component of
 337 the file. In this case it ends at the same offset (0-length component).
 338 .PP
 339 The extension component covers the rest of the specified region up to
 340 the \fIend\fR specified by \fB-E\fR option and gets the flag \fBextension\fR.
 341 This component covers the space reserved for the extendable component but
 342 not used immediately, the later extension of the extendable component is done
 343 by \fIext_size\fR each time until the extension component is used up. This is
 344 used to control the space on OSTs the stripe is located on, in case one of
 345 them is low on space, the remaining extension component region is added to the
 346 next component.
 347 .RE
 348 .TP
 349 .B --component-add
 350 Add components to the end an existing composite file.  It is not possible
 351 to add components incrementally to the default directory layout, since the
 352 entire default layout can be replaced with a single
 353 .B lfs setstripe
 354 command.  Adding components to mirrored files is not currently allowed.
 355 .TP
 356 .B --component-del
 357 Delete specified the components from an existing file using either the
 358 .BR --component-id | -I
 359 or
 360 .BR --component-flags .
 361 Deletion must start with the last component.  The ID specified by the
 362 .B -I
 363 option is the numerical unique ID of the component, it can be obtained using
 364 the
 365 .B lfs getstripe -I
 366 command.  It is not possible to delete components from a default directory
 367 layout, since the entire default layout can be replaced with a single
 368 .B lfs setstripe
 369 call.
 370 The \fB--component-flags\fR option is used to specify certain type of
 371 components. The only allowed component flag for deleting a component is
 372 .B ^init
 373 to indicate an uninstantiated component.  Deleting a single component from
 374 mirrored files is not currently allowed, see the
 375 .BR lfs-mirror-split (1)
 376 command.
 377 .TP
 378 .B --component-flags \fR<\fIflags\fR>
 379 Find, set, or clear
 380 .B flags
 381 on a specific component. Allowed
 382 .I flags
 383 are:
 384 .RS
 385 .B * init\fR - component is initialized (has allocated objects).  Used with
 386 .B --component-del --component-flags ^init
 387 to find uninitialized components.
 388 .RE
 389 .RS
 390 .B * prefer\fR - component preferred for read/write in a mirrored file
 391 .RE
 392 .RS
 393 .B * stale\fR - component has outdated data in a mirrored file. This flag is
 394 not allowed to be set on a component of the last non-stale mirror.
 395 Once a component is marked
 396 .BR stale ,
 397 it isn't permitted to clear this flag directly. \fBlfs-mirror-resync\fR(1)
 398 is required to clear the flag.
 399 .RE
 400 .RS
 401 .B * nosync\fR - mirror components will not be resynched by default when the
 402 .BR lfs-mirror-resync (1)
 403 command is run. This option is useful to freeze a file mirror as an old
 404 version or snapshot of the file.
 405 .RE
 406 .RS
 407 A leading '^' before \fIflags\fR clears the flags, or finds components not
 408 matching the flags.  Multiple flags can be separated by comma(s).
 409 .RE
 410 .TP
 411 .B -I\fR, \fB--component-id \fR<\fIcomp_id\fR>
 412 The numerical unique component ID to identify a component to be modified.
 413 .TP
 414 .BR -N "[\fImirror_count\fR], " --mirror-count=" [\fImirror_count\fR]
 415 Create a file with
 416 .I mirror_count
 417 identical replicas on the file or directory.  The
 418 .I mirror_count
 419 argument is optional and defaults to 1 if it's not specified; if specified,
 420 it must follow the
 421 .B -N
 422 option without a space.
 423 .br
 424 The \fISTRIPE_OPTIONS\fR specify the specific layout for the mirror. It
 425 can be a plain layout with specific striping pattern or a composite layout.
 426 If not specified, the stripe options are inherited from the previous
 427 component. If there is no previous component, the
 428 .I stripe_count
 429 and
 430 .I stripe_size
 431 options are inherited from filesystem-wide default values, and OST
 432 .I pool_name
 433 will be inherited from the parent directory.
 434 .br
 435 Multiple
 436 .B -N
 437 options may be specified, each with its own
 438 .I STRIPE_OPTIONS
 439 if there is a reason to have different layouts for the replicas, such as
 440 flash pools and archive pools (see
 441 .BR lfs-mirror-create (1)
 442 for full details).
 443 .br
 444 .B NOTE
 445 that in the current client implementation, only
 446 .B one
 447 replica will be written by client nodes, and the other replicas need to
 448 be resynched using the
 449 .B lfs mirror resync
 450 command, or an external resync agent.
 451 .SH EXAMPLES
 452 .TP
 453 .B lfs setstripe -S 128K -c 2 /mnt/lustre/file1
 454 This creates a file striped on two OSTs with 128KiB on each stripe.
 455 .TP
 456 .B lfs setstripe -d /mnt/lustre/dir
 457 This deletes a default stripe pattern on dir. New files created in that
 458 directory will use the filesystem global default instead.
 459 .TP
 460 .B lfs setstripe -N2 -E 1M -E eof -c -1 /mnt/lustre/dir1
 461 This sets a default mirror layout on a directory with 2 PFL mirrors. Each mirror
 462 has the same specified PFL layout.
 463 .TP
 464 .B lfs setstripe -N -E 1M -L mdt -E eof --component-flags=prefer -p flash \
 465     -N -E 1G -c 1 -p disk -E eof -c -1 /mnt/lustre/file1
 466 This creates a mirrored file with 2 replicas. The first replica is using the
 467 MDT for files smaller than 1MB, and the remainder of the file is on the
 468 .B flash
 469 OST pool with filesystem-wide default values.  The second replica is on the
 470 .B disk
 471 OST pool, with 1 stripe for the first 1GB of the file, and striped across
 472 all OSTs in the
 473 .B disk pool for the remainder of the file.  Clients will
 474 .B prefer
 475 the first (flash) replica for both reads and writes.
 476 .TP
 477 .B lfs setstripe -E 4M -c 1 -E 64M -c 4 -E -1 -c -1 /mnt/lustre/file1
 478 This creates a file with composite layout, the component has 1 stripe and
 479 covers [0, 4MiB), the second component has 4 stripes and covers [4MiB, 64MiB),
 480 the last component stripes over all available OSTs and covers [64MiB, EOF).
 481 .TP
 482 .B lfs setstripe -E -1 -z 64M /mnt/lustre/file1
 483 This creates a file with a composite layout, the component one covers [0, 64MiB)
 484 and the second component the rest [64MiB, EOF) originally. Once written beyond
 485 64MiB the component one is extended to [0, 128MiB), once written beyond 128MiB
 486 it is extended to [0, 192MiB), etc; the second component is shortened
 487 appropriately.
 488 .PP
 489 .RS
 490 When one of the OSTs of the first component layout is low on space, e.g. while
 491 writing beyond 192MiB, the first component is left as [0, 192MiB), and a new
 492 component is allocated between them, its layout repeats the first component
 493 layout but initialized on different OSTs so that the full OSTs are avoided.
 494 It is allocated and immediately extended to [192MiB, 256MiB), the following
 495 extension component is shortened again.
 496 .RE
 497 .TP
 498 .B lfs setstripe -E 1G -z 64M -E 100G -z 256M -E -1 -z 1G /mnt/lustre/file1
 499 This creates a file with a composite layout, the component one covers [0,
 500 64MiB), the third component covers [1G, 1G), the fifth component covers
 501 [100GiB, 100GiB) originally. The second, fourth and sixth extension components
 502 cover the left space accordingly. The process of writing is similar to above,
 503 but when one of the OSTs of the first component layout is low on space, e.g.
 504 while writing beyond 192MiB in the example above, the first component is left
 505 as [0, 192MiB), the second (extension) component is removed, and its range
 506 spills over to the third and the fourth components - they are moved left to
 507 start at 192MiB instead of 100GiB; the third component is immediately extended
 508 and becomes [192MiB, 448MiB), the fourth (the extension one) component becomes
 509 [448MiB, 100GiB).
 510 .TP
 511 .B lfs setstripe --component-add -E eof -c 4  /mnt/lustre/file1
 512 This add a component which starts at the end of last existing component to
 513 the end of file.
 514 .TP
 515 .B lfs setstripe --component-del -I 1 /mnt/lustre/file1
 516 This deletes the component with ID equal to 1 from an existing file.
 517 .TP
 518 .B lfs setstripe --comp-set -I 1 --comp-flags=^prefer,stale /mnt/lustre/file1
 519 This command will clear the \fBprefer\fR flag and set the \fBstale\fR flag on
 520 .B file1
 521 component ID 1.
 522 .TP
 523 .B lfs setstripe -E 1M -L mdt -E -1 /mnt/lustre/file1
 524 Create
 525 .B file1
 526 with Data-on-MDT layout. The first 1MiB of the file data is placed on the
 527 MDT and rest of file is placed on OST(s) with default striping.
 528 .TP
 529 .B lfs setstripe --yaml=/tmp/layout_yaml /mnt/lustre/file2
 530 This creates
 531 .B file2
 532 with layout stored in the layout template
 533 file
 534 .B layout_yaml
 535 which can be created with the
 536 .B lfs getstripe --yaml
 537 command.
 538 .TP
 539 .B lfs setstripe --foreign=symlink --flags=0xda08 \
 540         --xattr=PUUID:CUUID /mnt/lustre/file1
 541 This creates foreign
 542 .BR file1
 543 of type
 544 .BR symlink
 545 with non-lustre/free-format
 546 .BR PUUID:CUUID
 547 layout/LOV EA and flags
 548 .BR 0xda08
 549 .
 550 .SH SEE ALSO
 551 .BR lctl (1),
 552 .BR lfs (1),
 553 .BR lfs-migrate (1),
 554 .BR lfs-mirror-create (1),
 555 .BR lfs-mirror-split (1),
 556 .BR lustre (7)