LFS-SETSTRIPE(1)

NAME
lfs-setstripe - set striping pattern of a file or directory default

SYNOPSIS
lfs setstripe [STRIPE_OPTIONS] <directory|file>
lfs setstripe -E end1 [STRIPE_OPTIONS] ... <directory|file>
lfs setstripe --comp-add -E end1 [STRIPE_OPTIONS] ... <file>
lfs setstripe --comp-del {-I comp_id|--comp-flags=comp_flags} <file>
lfs setstripe --comp-set {-I comp_id|--comp-flags=comp_flags} <file>
lfs setstripe -N[mirror_count] [STRIPE_OPTIONS] <directory|filename>
lfs setstripe -d <directory>
lfs setstripe --yaml=<yaml_template_file.lyl> <file>
lfs setstripe --copy=<source_template_file> <file>
lfs setstripe --foreign[=<foreign_type>] [--flags=<hex>] --xattr=<layout_string> <file>

DESCRIPTION
The lfs setstripe command is used to create a new file in a Lustre filesystem with the specified layout, or to specify the default layout for new files created in directory, or anywhere in the filesystem if directory is the filesystem root and no other layout takes precedence.

Files with composite layouts allow different STRIPE_OPTIONS to be specified for non-overlapping extents of the file. Files will inherit options not explicitly specified on the command line either from the default layout on the parent directory, or from the filesystem-wide default. New subdirectories created under root directory will not explicitly copy the default layout at creation time, but will implicitly inherit the default layout at runtime. The default layout set on a non-root directory will be copied to any new subdirectories created within that directory at the time they are created.

lfs setstripe [STRIPE_OPTIONS ...] <directory|file>
    Create a new file with specified plain layout using the specified STRIPE_OPTIONS, or replace the default file layout on an existing directory.

lfs setstripe -E end [STRIPE_OPTIONS] ... <directory|file>
    Create a new composite file with one or more component layouts (where end marks the end of the current component), or set or replace the default file layout on an existing directory.

lfs setstripe --component-add -E end1 [STRIPE_OPTIONS] ... <file>
    Add one or more components after the last component of an existing composite file that does not yet have a component at eof.

lfs setstripe --comp-del {-I comp_id | --comp-flags comp_flags} <file>
    Remove the component(s) specified by component ID or flags from file.

lfs setstripe --comp-set {-I comp_id | --comp-flags comp_flags} <file>
    Set or clear flags on the specified component. This command can be only be applied to mirrored files.

lfs setstripe -N [mirror_count] [COMPONENT_OPTIONS] <directory|file>
    Create a new file with the specified number of mirrors and other specified layout options, or set or replace the default file layout on an existing directory.

lfs setstripe -d <directory>
    Delete the default layout on the specified directory. It is not necessary to delete the default layout on a directory before replacing it, only if the directory should revert from a directory-specific default layout to using the global filesystem default layout stored on the root directory.

lfs setstripe --yaml=<yaml_template_file.lyl> <file>
    Create a new file using the Lustre YAML Layout template yaml_template_file.lyl, created from existing_file via:
    lfs getstripe --yaml <existing_file> > <yaml_template_file.lyl>
    yaml_template_file.lyl is a plain-text file that may be saved and/or modified after creation. This allows complex file layouts to be created once and re-used later.

lfs setstripe --copy=<source_template_file> <file>
    Create a new file using the same layout as an existing source_template_file. This is similar to the --yaml option but avoids the need for the intermediate .lyl file.

lfs setstripe --foreign[=<foreign_type>] [--flags=<hex>] --xattr=<layout_string> <file>
    Create a new file with a foreign/non-lustre layout of type foreign_type (none, symlink, ...) with flags hex and a free-format layout value of layout_string.

STRIPE_OPTIONS
The various OST stripe related options are listed and explained below:

-c, --stripe-count <stripe_count>
    The number of OSTs to stripe a file over. 0 means to use the filesystem-wide default stripe count (default 1), and -1 means to stripe over all available OSTs.

-C, --overstripe-count <stripe_count>
    The number of stripes to create, creating > 1 stripe per OST if count exceeds the number of OSTs in the file system. 0 means to use the filesystem-wide default stripe count (default 1), and -1 means to stripe over all available OSTs.

-S, --stripe-size <stripe_size>
    The number of bytes to store on each OST before moving to the next OST. A stripe size of 0 means the file should use the filesystem-wide default stripe_size (default 1MiB). An optional suffix can be used to specify the units in Kibi-, Mebi-, or Gibibytes. The stripe_size must be a multiple of 64KiB. Values below 4096 are assumed to be in KiB units.

-i, --stripe-index <start_ost_index>
    The OST index (starting at 0) on which to start striping for this file. A start_ost_index of -1 allows the MDS to choose the starting index and it is strongly recommended, as this allows space and load balancing to be done by the MDS as needed.

-L, --layout <layout_type>
    The type of layout for that component, which can be one of:
    raid0 - stripe the file data across stripe_count OST objects in units of stripe_size chunks. This is the default layout if not specified.
    mdt - place the first component of the file data on the MDT for faster access where the inode is located. This can be used for small files, and with composite file layouts. The mdt type may only be used for first component of a file. The stripe_size of the MDT component is always equal to the component size. There is also a per-MDT tunable parameter lod.dom_stripesize that limits the maximum size of a DoM stripe. It can be changed on the MDS via lctl set_param lod.*.dom_stripesize=<stripe_size> , where stripe_size must be a multiple of 64KiB in size, see also lctl(8) for details.

-o, --ost <ost_indices>
    Used to specify the exact stripe layout on the file system. ost_indices is a list of OSTs referenced by their indices, which are specified in decimal or hex form and can be obtained using the lfs osts command. The list format consists of individual OST indices and index ranges separated by commas, e.g. 1,2-4,7. The -o option may be specified multiple times to stripe across the union of all listed OSTs. If the -c option is combined with -o the stripe_count must agree with the number of OSTs in ost_indices. If the -i option is combined with -o the start_ost_index must be in the OST list, and it will be used as the index on which to start striping the file. Otherwise the striping will occur in the order specified in ost_indices.

-p, --pool <pool_name>
    Allocate objects from the predefined OST pool pool_name for the layout of this file or component. The stripe_count, stripe_size, and start_ost_index can be used to select a subset of the OSTs within the pool; the start_ost_index must be part of the pool or an error will be returned. It is possible to specify a different pool for each component of a file. If no pool is specified, it will be inherited from the previous component (for later components of a composite layout) or the parent or root directory (for plain raid0 layouts, or the first component of a composite file). Use pool_name=ignore to force a component without a pool set (no inheritance from last component, root or parent). Use pool_name='' or pool_name=inherit (since Lustre 2.15) to force a component to inherit the pool from the parent or root directory instead of the previous component.

--foreign [<foreign_type>]
    file layout is non-lustre/free-format and of type < foreign_type >, if specified (see also --xattr and --flags options). Current known types are none and symlink , default is none -x, --xattr <layout_string> Mandatory non-lustre/free-format layout/LOV EA content for foreign file.

-F, --flags <hex>
    Optional bitmap of flags for foreign type.

COMPONENT_OPTIONS
The various component related options are listed and explained below. The --component-* options can be shortened to --comp-* if desired.

-E, --component-end <end>
    Add a new component to a file using the STRIPE_OPTIONS following the -E argument. These options apply to the component ending at offset end in bytes, or by using a suffix (KMGTP) to specify base-two units, such as 256M for 2^28 bytes. An offset of -1 or eof means the following options extend to the end of the file. The first component starts at offset 0, and each subsequent component starts at the end of the previous component, so they must be specified in increasing file offset order, and must be a multiple of 64KiB to align with the minimum stripe_size value. Values below 4096 are assumed to be in KiB units.

    The first component specified will inherit default parameters from the parent directory or the root directory like a plain layout, as specified above. Later components will inherit the default layout parameters from the previous component. Multiple -E options are used to separate the STRIPE_OPTIONS parameters for different regions of the file.

    If a file does not have a component extending to eof it will generate an error when trying to write beyond the last component end. This can be useful to limit the size of a file to the end of the last specified component, or use --component-add to add more components to the end of the file.

-z, --extension-size, ext-size <ext_size>
    This option modifies the -E option, components which have this option specified are created as pairs of components, extendable and extension ones.

    The extendable component starts at offset 0 if this is the first component of the file. In this case it ends at offset ext_size and it gets the flag init (initialized). The extendable component starts at the end of the previous component if this is not the first component of the file. In this case it ends at the same offset (0-length component).

    The extension component covers the rest of the specified region up to the end specified by -E option and gets the flag extension. This component covers the space reserved for the extendable component but not used immediately, the later extension of the extendable component is done by ext_size each time until the extension component is used up. This is used to control the space on OSTs the stripe is located on, in case one of them is low on space, the remaining extension component region is added to the next component.

--component-add
    Add components to the end an existing composite file. It is not possible to add components incrementally to the default directory layout, since the entire default layout can be replaced with a single lfs setstripe command. Adding components to mirrored files is not currently allowed.

--component-del
    Delete specified the components from an existing file using either the --component-id|-I or --component-flags. Deletion must start with the last component. The ID specified by the -I option is the numerical unique ID of the component, it can be obtained using the lfs getstripe -I command. It is not possible to delete components from a default directory layout, since the entire default layout can be replaced with a single lfs setstripe call. The --component-flags option is used to specify certain type of components. The only allowed component flag for deleting a component is ^init to indicate an uninstantiated component. Deleting a single component from mirrored files is not currently allowed, see the lfs-mirror-split(1) command.

--component-flags <flags>
    Find, set, or clear flags on a specific component. Allowed flags are:
    * init - component is initialized (has allocated objects). Used with --component-del --component-flags ^init to find uninitialized components.
    * prefer - component preferred for read/write in a mirrored file
    * stale - component has outdated data in a mirrored file. This flag is not allowed to be set on a component of the last non-stale mirror. Once a component is marked stale, it isn't permitted to clear this flag directly. lfs-mirror-resync(1) is required to clear the flag.
    * nosync - mirror components will not be resynched by default when the lfs-mirror-resync(1) command is run. This option is useful to freeze a file mirror as an old version or snapshot of the file.
    A leading '^' before flags clears the flags, or finds components not matching the flags. Multiple flags can be separated by comma(s).

-I, --component-id <comp_id>
    The numerical unique component ID to identify a component to be modified.

-N[mirror_count], --mirror-count="[mirror_count]
    Create a file with mirror_count identical replicas on the file or directory. The mirror_count argument is optional and defaults to 1 if it's not specified; if specified, it must follow the -N option without a space.
    The STRIPE_OPTIONS specify the specific layout for the mirror. It can be a plain layout with specific striping pattern or a composite layout. If not specified, the stripe options are inherited from the previous component. If there is no previous component, the stripe_count and stripe_size options are inherited from filesystem-wide default values, and OST pool_name will be inherited from the parent directory.
    Multiple -N options may be specified, each with its own STRIPE_OPTIONS if there is a reason to have different layouts for the replicas, such as flash pools and archive pools (see lfs-mirror-create(1) for full details).
    NOTE that in the current client implementation, only one replica will be written by client nodes, and the other replicas need to be resynched using the lfs mirror resync command, or an external resync agent.

EXAMPLES

lfs setstripe -S 128K -c 2 /mnt/lustre/file1
    This creates a file striped on two OSTs with 128KiB on each stripe.

lfs setstripe -d /mnt/lustre/dir
    This deletes a default stripe pattern on dir. New files created in that directory will use the filesystem global default instead.

lfs setstripe -N2 -E 1M -E eof -c -1 /mnt/lustre/dir1
    This sets a default mirror layout on a directory with 2 PFL mirrors. Each mirror has the same specified PFL layout.

lfs setstripe -N -E 1M -L mdt -E eof --component-flags=prefer -p flash -N -E 1G -c 1 -p disk -E eof -c -1 /mnt/lustre/file1
    This creates a mirrored file with 2 replicas. The first replica is using the MDT for files smaller than 1MB, and the remainder of the file is on the flash OST pool with filesystem-wide default values. The second replica is on the disk OST pool, with 1 stripe for the first 1GB of the file, and striped across all OSTs in the disk pool for the remainder of the file. Clients will prefer the first (flash) replica for both reads and writes.

lfs setstripe -E 4M -c 1 -E 64M -c 4 -E -1 -c -1 /mnt/lustre/file1
    This creates a file with composite layout, the component has 1 stripe and covers [0, 4MiB), the second component has 4 stripes and covers [4MiB, 64MiB), the last component stripes over all available OSTs and covers [64MiB, EOF).

lfs setstripe -E -1 -z 64M /mnt/lustre/file1
    This creates a file with a composite layout, the component one covers [0, 64MiB) and the second component the rest [64MiB, EOF) originally. Once written beyond 64MiB the component one is extended to [0, 128MiB), once written beyond 128MiB it is extended to [0, 192MiB), etc; the second component is shortened appropriately.

    When one of the OSTs of the first component layout is low on space, e.g. while writing beyond 192MiB, the first component is left as [0, 192MiB), and a new component is allocated between them, its layout repeats the first component layout but initialized on different OSTs so that the full OSTs are avoided. It is allocated and immediately extended to [192MiB, 256MiB), the following extension component is shortened again.

lfs setstripe -E 1G -z 64M -E 100G -z 256M -E -1 -z 1G /mnt/lustre/file1
    This creates a file with a composite layout, the component one covers [0, 64MiB), the third component covers [1G, 1G), the fifth component covers [100GiB, 100GiB) originally. The second, fourth and sixth extension components cover the left space accordingly. The process of writing is similar to above, but when one of the OSTs of the first component layout is low on space, e.g. while writing beyond 192MiB in the example above, the first component is left as [0, 192MiB), the second (extension) component is removed, and its range spills over to the third and the fourth components - they are moved left to start at 192MiB instead of 100GiB; the third component is immediately extended and becomes [192MiB, 448MiB), the fourth (the extension one) component becomes [448MiB, 100GiB).

lfs setstripe --component-add -E eof -c 4 /mnt/lustre/file1
    This add a component which starts at the end of last existing component to the end of file.

lfs setstripe --component-del -I 1 /mnt/lustre/file1
    This deletes the component with ID equal to 1 from an existing file.

lfs setstripe --comp-set -I 1 --comp-flags=^prefer,stale /mnt/lustre/file1
    This command will clear the prefer flag and set the stale flag on file1 component ID 1.

lfs setstripe -E 1M -L mdt -E -1 /mnt/lustre/file1
    Create file1 with Data-on-MDT layout. The first 1MiB of the file data is placed on the MDT and rest of file is placed on OST(s) with default striping.

lfs setstripe --yaml=/tmp/layout_yaml /mnt/lustre/file2
    This creates file2 with layout stored in the layout template file layout_yaml which can be created with the lfs getstripe --yaml command.

lfs setstripe --foreign=symlink --flags=0xda08 --xattr=PUUID:CUUID /mnt/lustre/file1
    This creates foreign file1 of type symlink with non-lustre/free-format PUUID:CUUID layout/LOV EA and flags 0xda08

SEE ALSO
lctl(1), lfs(1), lfs-migrate(1), lfs-mirror-create(1), lfs-mirror-split(1), lustre(7)