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