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 .SH DESCRIPTION
  27 The
  28 .B lfs setstripe
  29 command is used to create a new
  30 .I file
  31 in a Lustre filesystem with the specified layout, or to specify the default
  32 layout for new files created in
  33 .IR directory ,
  34 or anywhere in the filesystem if
  35 .I directory
  36 is the filesystem root and no other layout takes precedence.
  37 .PP
  38 Files with composite layouts allow different
  39 .I STRIPE_OPTIONS
  40 to be specified for non-overlapping extents of the file. Files will
  41 inherit options not explicitly specified on the command line either from
  42 the default layout on the parent directory, or from the filesystem-wide
  43 default. New subdirectories created under root directory will not explicitly
  44 copy the default layout at creation time, but will implicitly inherit the
  45 default layout at runtime. The default layout set on a non-root directory
  46 will be copied to any new subdirectories created within that directory
  47 at the time they are created.
  48 .TP
  49 .B lfs setstripe \fR[\fISTRIPE_OPTIONS\fR ...] <\fIdirectory\fR|\fIfile\fR>
  50 Create a new
  51 .I file
  52 with specified plain layout using the specified
  53 .IR STRIPE_OPTIONS ,
  54 or replace the default file layout on an existing
  55 .IR directory .
  56 .TP
  57 .B lfs setstripe -E \fIend\fR [\fISTRIPE_OPTIONS\fR] ... \
  58 <\fIdirectory\fR|\fIfile\fR>
  59 .br
  60 Create a new composite
  61 .I file
  62 with one or more component layouts, or set or replace the default file layout
  63 on an existing
  64 .IR directory .
  65 .TP
  66 .B lfs setstripe --component-add -E \fIend1\fR [\fISTRIPE_OPTIONS\fR] \
  67 ... <\fIfile\fR>
  68 .br
  69 Add one or more components after the last component of an existing composite
  70 file that does not yet have a component at
  71 .BR eof .
  72 .TP
  73 .B lfs setstripe --comp-del \fR{\fB-I \fIcomp_id\fR | \
  74 \fB--comp-flags \fIcomp_flags\fR} <\fIfile\fR>
  75 Remove the component(s) specified by component ID or flags from
  76 .IR file .
  77 .TP
  78 .B lfs setstripe --comp-set \fR{\fB-I \fIcomp_id\fR | \
  79 \fB--comp-flags \fIcomp_flags\fR} <\fIfile\fR>
  80 Set or clear
  81 .I flags
  82 on the specified component. This command can be only
  83 be applied to mirrored files.
  84 .TP
  85 .B lfs setstripe -N \fR[\fImirror_count\fR] \fR[\fICOMPONENT_OPTIONS\fR] <\fIdirectory\fR|\fIfile\fR>
  86 Create a new
  87 .I file
  88 with the specified number of mirrors and other specified layout options, or
  89 set or replace the default file layout on an existing
  90 .IR directory .
  91 .TP
  92 .B lfs setstripe -d \fR<\fIdirectory\fR>
  93 .br
  94 Delete the default layout on the specified directory.  It is not necessary
  95 to delete the default layout on a directory before replacing it, only if
  96 the directory should revert from a directory-specific default layout
  97 to using the global filesystem default layout stored on the root directory.
  98 .TP
  99 .B lfs setstripe --yaml=\fR<\fIyaml_template_file.lyl\fR> <\fIfile\fR>
 100 .br
 101 Create a new
 102 .I file
 103 using the Lustre YAML Layout template
 104 .IR yaml_template_file.lyl ,
 105 created from
 106 .I existing_file
 107 via:
 108 .br
 109 .B lfs getstripe --yaml \fR<\fIexisting_file\fR> > <\fIyaml_template_file.lyl\fR>
 110 .br
 111 .I yaml_template_file.lyl
 112 is a plain-text file that may be saved and/or modified after creation.
 113 This allows complex file layouts to be created once and re-used later.
 114 .TP
 115 .B lfs setstripe --copy=\fR<\fIsource_template_file\fR> <\fIfile\fR>
 116 .br
 117 Create a new
 118 .I file
 119 using the same layout as an existing
 120 .IR source_template_file .
 121 This is similar to the
 122 .B --yaml
 123 option but avoids the need for the intermediate
 124 .B .lyl
 125 file.
 126 .SH STRIPE_OPTIONS
 127 The various OST stripe related options are listed and explained below:
 128 .TP
 129 .B -c\fR, \fB--stripe-count \fR<\fIstripe_count\fR>
 130 The number of OSTs to stripe a file over. \fB0 \fRmeans to use the
 131 filesystem-wide default stripe count (default 1), and \fB-1 \fRmeans to stripe
 132 over all available OSTs.
 133 .TP
 134 .B -S\fR, \fB--stripe-size \fR<\fIstripe_size\fR>
 135 The number of bytes to store on each OST before moving to the next OST. A
 136 stripe size of
 137 .B 0
 138 means the file should use the filesystem-wide default stripe_size
 139 (default 1MiB).  An optional suffix can be used to specify the units in
 140 .BR K ibi-,
 141 .BR M "ebi-, or"
 142 .BR G ibibytes.
 143 The
 144 .I stripe_size
 145 must be a multiple of 64KiB in size.
 146 .TP
 147 .B -i\fR, \fB--stripe-index \fR<\fIstart_ost_index\fR>
 148 The OST index (starting at 0) on which to start striping for this file.  A
 149 .I start_ost_index
 150 of
 151 .B -1
 152 allows the MDS to choose the starting index and it is strongly recommended, as
 153 this allows space and load balancing to be done by the MDS as needed.
 154 .TP
 155 .B -L\fR, \fB--layout \fR<\fIlayout_type\fR>
 156 The type of layout for that component, which can be one of:
 157 .RS
 158 .B raid0\fR - stripe the file data across
 159 .B stripe_count
 160 OST objects in units of
 161 .B stripe_size
 162 chunks.  This is the default layout if not specified.
 163 .RE
 164 .RS
 165 .B mdt\fR - place the first component of the file data on the MDT for faster
 166 access where the inode is located. This can be used for small files, and with
 167 composite file layouts.  The
 168 .B mdt
 169 type may only be used for first component of a file. The
 170 .IR stripe_size
 171 of the MDT component is always equal to the component size. There is also a
 172 per-MDT tunable parameter
 173 .IR lod.dom_stripesize
 174 that limits the maximum size of a DoM stripe.  It can be changed on the MDS via
 175 .B lctl set_param lod.*.dom_stripesize=\fR<\fIstripe_size\fR> ,
 176 where
 177 .I stripe_size
 178 must be a multiple of 64KiB in size,
 179 see also
 180 .BR lctl (8)
 181 for details.
 182 .RE
 183 .TP
 184 .B -o\fR, \fB--ost \fR<\fIost_indices\fR>
 185 Used to specify the exact stripe layout on the file system. \fIost_indices\fR
 186 is a list of OSTs referenced by their indices, which are specified in decimal
 187 or hex form and can be obtained using the
 188 .B lfs osts
 189 command. The list format consists of individual OST indices and index ranges
 190 separated by commas, e.g. 1,2-4,7. The
 191 .B -o
 192 option may be specified multiple times to stripe across the union of all listed
 193 OSTs. If the
 194 .B -c
 195 option is combined with
 196 .B -o
 197 the
 198 .I stripe_count
 199 must agree with the number of OSTs in
 200 .IR ost_indices .
 201 If the
 202 .B -i
 203 option is combined with
 204 .B -o
 205 the
 206 .I start_ost_index
 207 must be in the OST list, and it will be used as the index on which to start
 208 striping the file. Otherwise the striping will occur in the order specified in
 209 .IR ost_indices .
 210 .TP
 211 .B -p\fR, \fB--pool \fR<\fIpool_name\fR>
 212 Allocate objects from the predefined OST pool
 213 .I pool_name
 214 for the layout of this file or component. The
 215 .IR stripe_count ,
 216 .IR stripe_size ,
 217 and
 218 .I start_ost_index
 219 can be used to select a subset of the OSTs within the pool; the
 220 .I start_ost_index
 221 must be part of the pool or an error will be returned.
 222 It is possible to specify a different pool for each component of a file.  If
 223 no pool is specified, it will be inherited from the previous component (for
 224 later components of a composite layout) or the parent or root directory (for
 225 plain
 226 .B raid0
 227 layouts, or the first component of a composite file).
 228 Use
 229 .BR pool_name='' ,
 230 or
 231 .BR pool_name=none
 232 (since Lustre 2.11) to force a component to inherit the pool from the parent
 233 or root directory instead of the previous component.
 234 .SH COMPONENT_OPTIONS
 235 The various component related options are listed and explained below.  The
 236 .B --component-*
 237 options can be shortened to
 238 .B --comp-*
 239 if desired.
 240 .TP
 241 .B -E\fR, \fB--component-end \fR<\fIend\fR>
 242 Add a new component to a file using the
 243 .I STRIPE_OPTIONS
 244 following the
 245 .B -E
 246 argument.  These options apply to the component ending at offset
 247 .I end
 248 in bytes, or by using a suffix (KMGTP) to specify base-two units,
 249 such as 256M for 2^28 bytes. An offset of
 250 .B -1
 251 or
 252 .B eof
 253 means the following options extend to the end of the file.  The first
 254 component starts at offset 0, and each subsequent component starts at
 255 the end of the previous component, so they must be specified in increasing
 256 file offset order.
 257 .PP
 258 .RS
 259 The first component specified will inherit default parameters from the
 260 parent directory or the root directory like a plain layout, as specified
 261 above.  Later components will inherit the default layout parameters from
 262 the previous component.  Multiple
 263 .B -E
 264 options are used to separate the
 265 .I STRIPE_OPTIONS
 266 parameters for different regions of the file.
 267 .RE
 268 .PP
 269 .RS
 270 If a file does not have a component extending to
 271 .B eof
 272 it will generate an error when trying to write beyond the last component
 273 .IR end .
 274 This can be useful to limit the size of a file to the end of the last
 275 specified component, or use
 276 .B --component-add
 277 to add more components to the end of the file.
 278 .RE
 279 .TP
 280 .B --component-add
 281 Add components to the end an existing composite file.  It is not possible
 282 to add components incrementally to the default directory layout, since the
 283 entire default layout can be replaced with a single
 284 .B lfs setstripe
 285 command.  Adding components to mirrored files is not currently allowed.
 286 .TP
 287 .B --component-del
 288 Delete specified the components from an existing file using either the
 289 .BR --component-id | -I
 290 or
 291 .BR --component-flags .
 292 Deletion must start with the last component.  The ID specified by the
 293 .B -I
 294 option is the numerical unique ID of the component, it can be obtained using
 295 the
 296 .B lfs getstripe -I
 297 command.  It is not possible to delete components from a default directory
 298 layout, since the entire default layout can be replaced with a single
 299 .B lfs setstripe
 300 call.
 301 The \fB--component-flags\fR option is used to specify certain type of
 302 components. The only allowed component flag for deleting a component is
 303 .B ^init
 304 to indicate an uninstantiated component.  Deleting a single component from
 305 mirrored files is not currently allowed, see the
 306 .BR lfs-mirror-split (1)
 307 command.
 308 .TP
 309 .B --component-flags \fR<\fIflags\fR>
 310 Find, set, or clear
 311 .B flags
 312 on a specific component. Allowed
 313 .I flags
 314 are:
 315 .RS
 316 .B * init\fR - component is initialized (has allocated objects).  Used with
 317 .B --component-del --component-flags ^init
 318 to find uninitialized components.
 319 .RE
 320 .RS
 321 .B * prefer\fR - component preferred for read/write in a mirrored file
 322 .RE
 323 .RS
 324 .B * stale\fR - component has outdated data in a mirrored file. This flag is
 325 not allowed to be set on a component of the last non-stale mirror.
 326 Once a component is marked
 327 .BR stale ,
 328 it isn't permitted to clear this flag directly. \fBlfs-mirror-resync\fR(1)
 329 is required to clear the flag.
 330 .RE
 331 .RS
 332 .B * nosync\fR - mirror components will not be resynched by default when the
 333 .BR lfs-mirror-resync (1)
 334 command is run. This option is useful to freeze a file mirror as an old
 335 version or snapshot of the file.
 336 .RE
 337 .RS
 338 A leading '^' before \fIflags\fR clears the flags, or finds components not
 339 matching the flags.  Multiple flags can be separated by comma(s).
 340 .RE
 341 .TP
 342 .B -I\fR, \fB--component-id \fR<\fIcomp_id\fR>
 343 The numerical unique component ID to identify a component to be modified.
 344 .TP
 345 .BR -N "[\fImirror_count\fR], " --mirror-count=" [\fImirror_count\fR]
 346 Create a file with
 347 .I mirror_count
 348 identical replicas on the file or directory.  The
 349 .I mirror_count
 350 argument is optional and defaults to 1 if it's not specified; if specified,
 351 it must follow the
 352 .B -N
 353 option without a space.
 354 .br
 355 The \fISTRIPE_OPTIONS\fR specify the specific layout for the mirror. It
 356 can be a plain layout with specific striping pattern or a composite layout.
 357 If not specified, the stripe options are inherited from the previous
 358 component. If there is no previous component, the
 359 .I stripe_count
 360 and
 361 .I stripe_size
 362 options are inherited from filesystem-wide default values, and OST
 363 .I pool_name
 364 will be inherited from the parent directory.
 365 .br
 366 Multiple
 367 .B -N
 368 options may be specified, each with its own
 369 .I STRIPE_OPTIONS
 370 if there is a reason to have different layouts for the replicas, such as
 371 flash pools and archive pools (see
 372 .BR lfs-mirror-create (1)
 373 for full details).
 374 .br
 375 .B NOTE
 376 that in the current client implementation, only
 377 .B one
 378 replica will be written by client nodes, and the other replicas need to
 379 be resynched using the
 380 .B lfs mirror resync
 381 command, or an external resync agent.
 382 .SH EXAMPLES
 383 .TP
 384 .B lfs setstripe -S 128K -c 2 /mnt/lustre/file1
 385 This creates a file striped on two OSTs with 128KiB on each stripe.
 386 .TP
 387 .B lfs setstripe -d /mnt/lustre/dir
 388 This deletes a default stripe pattern on dir. New files created in that
 389 directory will use the filesystem global default instead.
 390 .TP
 391 .B lfs setstripe -N2 -E 1M -E eof -c -1 /mnt/lustre/dir1
 392 This sets a default mirror layout on a directory with 2 PFL mirrors. Each mirror
 393 has the same specified PFL layout.
 394 .TP
 395 .B lfs setstripe -N -E 1M -L mdt -E eof --component-flags=prefer -p flash \
 396     -N -E 1G -c 1 -p disk -E eof -c -1 /mnt/lustre/file1
 397 This creates a mirrored file with 2 replicas. The first replica is using the
 398 MDT for files smaller than 1MB, and the remainder of the file is on the
 399 .B flash
 400 OST pool with filesystem-wide default values.  The second replica is on the
 401 .B disk
 402 OST pool, with 1 stripe for the first 1GB of the file, and striped across
 403 all OSTs in the
 404 .B disk pool for the remainder of the file.  Clients will
 405 .B prefer
 406 the first (flash) replica for both reads and writes.
 407 .TP
 408 .B lfs setstripe -E 4M -c 1 -E 64M -c 4 -E -1 -c -1 /mnt/lustre/file1
 409 This creates a file with composite layout, the component has 1 stripe and
 410 covers [0, 4MiB), the second component has 4 stripes and covers [4MiB, 64MiB),
 411 the last component stripes over all available OSTs and covers [64MiB, EOF).
 412 .TP
 413 .B lfs setstripe --component-add -E eof -c 4  /mnt/lustre/file1
 414 This add a component which starts at the end of last existing component to
 415 the end of file.
 416 .TP
 417 .B lfs setstripe --component-del -I 1 /mnt/lustre/file1
 418 This deletes the component with ID equal to 1 from an existing file.
 419 .TP
 420 .B lfs setstripe --comp-set -I 1 --comp-flags=^prefer,stale /mnt/lustre/file1
 421 This command will clear the \fBprefer\fR flag and set the \fBstale\fR flag on
 422 .B file1
 423 component ID 1.
 424 .TP
 425 .B lfs setstripe -E 1M -L mdt -E -1 /mnt/lustre/file1
 426 Create
 427 .B file1
 428 with Data-on-MDT layout. The first 1MiB of the file data is placed on the
 429 MDT and rest of file is placed on OST(s) with default striping.
 430 .TP
 431 .B lfs setstripe --yaml=/tmp/layout_yaml /mnt/lustre/file2
 432 This creates
 433 .B file2
 434 with layout stored in the layout template
 435 file
 436 .B layout_yaml
 437 which can be created with the
 438 .B lfs getstripe --yaml
 439 command.
 440 .SH SEE ALSO
 441 .BR lctl (1),
 442 .BR lfs (1),
 443 .BR lfs-migrate (1),
 444 .BR lfs-mirror-create (1),
 445 .BR lfs-mirror-split (1),
 446 .BR lustre (7)