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, or set or replace the default file layout
  66 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, \fBdaos\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 -S\fR, \fB--stripe-size \fR<\fIstripe_size\fR>
 150 The number of bytes to store on each OST before moving to the next OST. A
 151 stripe size of
 152 .B 0
 153 means the file should use the filesystem-wide default stripe_size
 154 (default 1MiB).  An optional suffix can be used to specify the units in
 155 .BR K ibi-,
 156 .BR M "ebi-, or"
 157 .BR G ibibytes.
 158 The
 159 .I stripe_size
 160 must be a multiple of 64KiB in size.
 161 .TP
 162 .B -i\fR, \fB--stripe-index \fR<\fIstart_ost_index\fR>
 163 The OST index (starting at 0) on which to start striping for this file.  A
 164 .I start_ost_index
 165 of
 166 .B -1
 167 allows the MDS to choose the starting index and it is strongly recommended, as
 168 this allows space and load balancing to be done by the MDS as needed.
 169 .TP
 170 .B -L\fR, \fB--layout \fR<\fIlayout_type\fR>
 171 The type of layout for that component, which can be one of:
 172 .RS
 173 .B raid0\fR - stripe the file data across
 174 .B stripe_count
 175 OST objects in units of
 176 .B stripe_size
 177 chunks.  This is the default layout if not specified.
 178 .RE
 179 .RS
 180 .B mdt\fR - place the first component of the file data on the MDT for faster
 181 access where the inode is located. This can be used for small files, and with
 182 composite file layouts.  The
 183 .B mdt
 184 type may only be used for first component of a file. The
 185 .IR stripe_size
 186 of the MDT component is always equal to the component size. There is also a
 187 per-MDT tunable parameter
 188 .IR lod.dom_stripesize
 189 that limits the maximum size of a DoM stripe.  It can be changed on the MDS via
 190 .B lctl set_param lod.*.dom_stripesize=\fR<\fIstripe_size\fR> ,
 191 where
 192 .I stripe_size
 193 must be a multiple of 64KiB in size,
 194 see also
 195 .BR lctl (8)
 196 for details.
 197 .RE
 198 .TP
 199 .B -o\fR, \fB--ost \fR<\fIost_indices\fR>
 200 Used to specify the exact stripe layout on the file system. \fIost_indices\fR
 201 is a list of OSTs referenced by their indices, which are specified in decimal
 202 or hex form and can be obtained using the
 203 .B lfs osts
 204 command. The list format consists of individual OST indices and index ranges
 205 separated by commas, e.g. 1,2-4,7. The
 206 .B -o
 207 option may be specified multiple times to stripe across the union of all listed
 208 OSTs. If the
 209 .B -c
 210 option is combined with
 211 .B -o
 212 the
 213 .I stripe_count
 214 must agree with the number of OSTs in
 215 .IR ost_indices .
 216 If the
 217 .B -i
 218 option is combined with
 219 .B -o
 220 the
 221 .I start_ost_index
 222 must be in the OST list, and it will be used as the index on which to start
 223 striping the file. Otherwise the striping will occur in the order specified in
 224 .IR ost_indices .
 225 .TP
 226 .B -p\fR, \fB--pool \fR<\fIpool_name\fR>
 227 Allocate objects from the predefined OST pool
 228 .I pool_name
 229 for the layout of this file or component. The
 230 .IR stripe_count ,
 231 .IR stripe_size ,
 232 and
 233 .I start_ost_index
 234 can be used to select a subset of the OSTs within the pool; the
 235 .I start_ost_index
 236 must be part of the pool or an error will be returned.
 237 It is possible to specify a different pool for each component of a file.  If
 238 no pool is specified, it will be inherited from the previous component (for
 239 later components of a composite layout) or the parent or root directory (for
 240 plain
 241 .B raid0
 242 layouts, or the first component of a composite file).
 243 Use
 244 .BR pool_name='' ,
 245 or
 246 .BR pool_name=none
 247 (since Lustre 2.11) to force a component to inherit the pool from the parent
 248 or root directory instead of the previous component.
 249 .TP
 250 .B --foreign \fR[<\fIforeign_type\fR>]
 251 file layout is non-lustre/free-format and of type <
 252 .IR foreign_type
 253 >, if specified (see also
 254 .IR --xattr
 255 and
 256 .IR --flags
 257 options).
 258 Current known types are
 259 .BR none
 260 and
 261 .BR daos
 262 , default is
 263 .BR none
 264 .
 265 .B -x\fR, \fB--xattr \fR<\fIlayout_string\fR>
 266 Mandatory non-lustre/free-format layout/LOV EA content for
 267 .I foreign
 268 file.
 269 .TP
 270 .B -F\fR, \fB--flags \fR<\fIhex\fR>
 271 Optional bitmap of flags for foreign type.
 272 .SH COMPONENT_OPTIONS
 273 The various component related options are listed and explained below.  The
 274 .B --component-*
 275 options can be shortened to
 276 .B --comp-*
 277 if desired.
 278 .TP
 279 .B -E\fR, \fB--component-end \fR<\fIend\fR>
 280 Add a new component to a file using the
 281 .I STRIPE_OPTIONS
 282 following the
 283 .B -E
 284 argument.  These options apply to the component ending at offset
 285 .I end
 286 in bytes, or by using a suffix (KMGTP) to specify base-two units,
 287 such as 256M for 2^28 bytes. An offset of
 288 .B -1
 289 or
 290 .B eof
 291 means the following options extend to the end of the file.  The first
 292 component starts at offset 0, and each subsequent component starts at
 293 the end of the previous component, so they must be specified in increasing
 294 file offset order.
 295 .PP
 296 .RS
 297 The first component specified will inherit default parameters from the
 298 parent directory or the root directory like a plain layout, as specified
 299 above.  Later components will inherit the default layout parameters from
 300 the previous component.  Multiple
 301 .B -E
 302 options are used to separate the
 303 .I STRIPE_OPTIONS
 304 parameters for different regions of the file.
 305 .RE
 306 .PP
 307 .RS
 308 If a file does not have a component extending to
 309 .B eof
 310 it will generate an error when trying to write beyond the last component
 311 .IR end .
 312 This can be useful to limit the size of a file to the end of the last
 313 specified component, or use
 314 .B --component-add
 315 to add more components to the end of the file.
 316 .RE
 317 .TP
 318 .B --component-add
 319 Add components to the end an existing composite file.  It is not possible
 320 to add components incrementally to the default directory layout, since the
 321 entire default layout can be replaced with a single
 322 .B lfs setstripe
 323 command.  Adding components to mirrored files is not currently allowed.
 324 .TP
 325 .B --component-del
 326 Delete specified the components from an existing file using either the
 327 .BR --component-id | -I
 328 or
 329 .BR --component-flags .
 330 Deletion must start with the last component.  The ID specified by the
 331 .B -I
 332 option is the numerical unique ID of the component, it can be obtained using
 333 the
 334 .B lfs getstripe -I
 335 command.  It is not possible to delete components from a default directory
 336 layout, since the entire default layout can be replaced with a single
 337 .B lfs setstripe
 338 call.
 339 The \fB--component-flags\fR option is used to specify certain type of
 340 components. The only allowed component flag for deleting a component is
 341 .B ^init
 342 to indicate an uninstantiated component.  Deleting a single component from
 343 mirrored files is not currently allowed, see the
 344 .BR lfs-mirror-split (1)
 345 command.
 346 .TP
 347 .B --component-flags \fR<\fIflags\fR>
 348 Find, set, or clear
 349 .B flags
 350 on a specific component. Allowed
 351 .I flags
 352 are:
 353 .RS
 354 .B * init\fR - component is initialized (has allocated objects).  Used with
 355 .B --component-del --component-flags ^init
 356 to find uninitialized components.
 357 .RE
 358 .RS
 359 .B * prefer\fR - component preferred for read/write in a mirrored file
 360 .RE
 361 .RS
 362 .B * stale\fR - component has outdated data in a mirrored file.  Once a
 363 component is marked
 364 .BR stale ,
 365 it isn't permitted to clear this flag directly. \fBlfs-mirror-resync\fR(1)
 366 is required to clear the flag.
 367 .RE
 368 .RS
 369 .B * nosync\fR - mirror components will not be resynched by default when the
 370 .BR lfs-mirror-resync (1)
 371 command is run. This option is useful to freeze a file mirror as an old
 372 version or snapshot of the file.
 373 .RE
 374 .RS
 375 A leading '^' before \fIflags\fR clears the flags, or finds components not
 376 matching the flags.  Multiple flags can be separated by comma(s).
 377 .RE
 378 .TP
 379 .B -I\fR, \fB--component-id \fR<\fIcomp_id\fR>
 380 The numerical unique component ID to identify a component to be modified.
 381 .TP
 382 .BR -N "[\fImirror_count\fR], " --mirror-count=" [\fImirror_count\fR]
 383 Create a file with
 384 .I mirror_count
 385 identical replicas on the file or directory.  The
 386 .I mirror_count
 387 argument is optional and defaults to 1 if it's not specified; if specified,
 388 it must follow the
 389 .B -N
 390 option without a space.
 391 .br
 392 The \fISTRIPE_OPTIONS\fR specify the specific layout for the mirror. It
 393 can be a plain layout with specific striping pattern or a composite layout.
 394 If not specified, the stripe options are inherited from the previous
 395 component. If there is no previous component, the
 396 .I stripe_count
 397 and
 398 .I stripe_size
 399 options are inherited from filesystem-wide default values, and OST
 400 .I pool_name
 401 will be inherited from the parent directory.
 402 .br
 403 Multiple
 404 .B -N
 405 options may be specified, each with its own
 406 .I STRIPE_OPTIONS
 407 if there is a reason to have different layouts for the replicas, such as
 408 flash pools and archive pools (see
 409 .BR lfs-mirror-create (1)
 410 for full details).
 411 .br
 412 .B NOTE
 413 that in the current client implementation, only
 414 .B one
 415 replica will be written by client nodes, and the other replicas need to
 416 be resynched using the
 417 .B lfs mirror resync
 418 command, or an external resync agent.
 419 .SH EXAMPLES
 420 .TP
 421 .B lfs setstripe -S 128K -c 2 /mnt/lustre/file1
 422 This creates a file striped on two OSTs with 128KiB on each stripe.
 423 .TP
 424 .B lfs setstripe -d /mnt/lustre/dir
 425 This deletes a default stripe pattern on dir. New files created in that
 426 directory will use the filesystem global default instead.
 427 .TP
 428 .B lfs setstripe -N2 -E 1M -E eof -c -1 /mnt/lustre/dir1
 429 This sets a default mirror layout on a directory with 2 PFL mirrors. Each mirror
 430 has the same specified PFL layout.
 431 .TP
 432 .B lfs setstripe -N -E 1M -L mdt -E eof --component-flags=prefer -p flash \
 433     -N -E 1G -c 1 -p disk -E eof -c -1 /mnt/lustre/file1
 434 This creates a mirrored file with 2 replicas. The first replica is using the
 435 MDT for files smaller than 1MB, and the remainder of the file is on the
 436 .B flash
 437 OST pool with filesystem-wide default values.  The second replica is on the
 438 .B disk
 439 OST pool, with 1 stripe for the first 1GB of the file, and striped across
 440 all OSTs in the
 441 .B disk pool for the remainder of the file.  Clients will
 442 .B prefer
 443 the first (flash) replica for both reads and writes.
 444 .TP
 445 .B lfs setstripe -E 4M -c 1 -E 64M -c 4 -E -1 -c -1 /mnt/lustre/file1
 446 This creates a file with composite layout, the component has 1 stripe and
 447 covers [0, 4MiB), the second component has 4 stripes and covers [4MiB, 64MiB),
 448 the last component stripes over all available OSTs and covers [64MiB, EOF).
 449 .TP
 450 .B lfs setstripe --component-add -E eof -c 4  /mnt/lustre/file1
 451 This add a component which starts at the end of last existing component to
 452 the end of file.
 453 .TP
 454 .B lfs setstripe --component-del -I 1 /mnt/lustre/file1
 455 This deletes the component with ID equal to 1 from an existing file.
 456 .TP
 457 .B lfs setstripe --comp-set -I 1 --comp-flags=^prefer,stale /mnt/lustre/file1
 458 This command will clear the \fBprefer\fR flag and set the \fBstale\fR flag on
 459 .B file1
 460 component ID 1.
 461 .TP
 462 .B lfs setstripe -E 1M -L mdt -E -1 /mnt/lustre/file1
 463 Create
 464 .B file1
 465 with Data-on-MDT layout. The first 1MiB of the file data is placed on the
 466 MDT and rest of file is placed on OST(s) with default striping.
 467 .TP
 468 .B lfs setstripe --yaml=/tmp/layout_yaml /mnt/lustre/file2
 469 This creates
 470 .B file2
 471 with layout stored in the layout template
 472 file
 473 .B layout_yaml
 474 which can be created with the
 475 .B lfs getstripe --yaml
 476 command.
 477 .TP
 478 .B lfs setstripe --foreign=daos --flags=0xda08 \
 479         --xattr=PUUID:CUUID /mnt/lustre/file1
 480 This creates foreign
 481 .BR file1
 482 of type
 483 .BR daos
 484 with non-lustre/free-format
 485 .BR PUUID:CUUID
 486 layout/LOV EA and flags
 487 .BR 0xda08
 488 .
 489 .SH SEE ALSO
 490 .BR lctl (1),
 491 .BR lfs (1),
 492 .BR lfs-migrate (1),
 493 .BR lfs-mirror-create (1),
 494 .BR lfs-mirror-split (1),
 495 .BR lustre (7)