Pfl2-lfs-setstripe.1

From Lustre Wiki
Revision as of 17:41, 11 January 2017 by Adilger (talk | contribs) (→‎EXAMPLES: add to PFL category)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

NAME

lfs setstripe - set striping pattern of a file.
lfs migrate - migrate file data between OSTs, or directory inodes between MDTs  

SYNOPSIS

lfs setstripe [OPTIONS] {directory|filename}
lfs setstripe -d directory
lfs setstripe {--component-end|-E end1} [component1_OPTIONS] [{--component-end|-E end2} [component2_OPTIONS] ...] {directory|filename}
lfs setstripe {--component-del|-d} [--component-id|-I comp_id] [--component-flags|-F flags] filename
lfs setstripe --component-set [--component-id|-I comp_id] {--component-flags|-F flags} filename
lfs migrate [--component-id|-I comp_id] [OPTIONS] filename
lfs migrate [--mdt-index|-m mdt_idx] {directory|filename}  

DESCRIPTION

lfs setstripe [OPTIONS] {directory|filename}

Create a new plain file (one with only a single layout to cover the entire file), or set default striping template on an existing directory, with the specified striping pattern as described in the OPTIONS section below.

lfs setstripe -d directory

Delete the default striping layout template on the specified directory.

lfs setstripe {--component-end|-E end1} [component1_OPTIONS] [{--component-end|-E end2} [component2_OPTIONS] ...] {directory|filename}

Create a new composite file, add one or more layout components to an existing composite file, or set or extend the default template on an existing directory. Each component defines the stripe pattern of the file in the range of [start, end) bytes from the start of the file, where start is implicitly always equal to the end of the previous component. The first component starts at byte offset 0, and all components must be adjacent with each other. The -E option is used to specify the end offset of each component, and it also indicates the following OPTIONS are for this component. Specifying --component-end=0, or not specifying any -E option at all, indicates the component covers the rest of the file. NOTE: the maximum size of objects on ldiskfs OSTs is 16TB, which means the maximum addressable file size is 16 TB * stripe_count for each component. In this case, the component end must not be larger than this limit. This size limitation does not apply for ZFS OSTs.

lfs setstripe {--component-del|-d} [--component-id|-I comp_id] [--component-flags|-F flags] filename

Remove the component(s) matching the specified component ID or component flags from an existing file. The ID specified by the -I option is the numerical unique ID of the component, it can be obtained using lfs getstripe -I filename. The -F option is used to specify certain classes of components, such as all uninitialized components.

lfs setstripe --component-set [--component-id|-I component_id] {--component-flags|-F flags}

Set the component flag(s) for the component(s) specified by component_id of an existing file. If -I is not given, then flags will be set on all components of the file.

lfs setstripe --component-clear [--component-id|-I component_id] {--component-flags|-F flags}

Clear the component flag(s) for the component(s) specified by component_id of an existing file. If -I is not given, then flags will be cleared on all components of the file.

lfs migrate [--component-id|-I comp_id] [OPTIONS] filename

Migrate file from one OST layout to another (may be not safe with concurrent writes). If the component ID is specified, then only that component should be migrated, and the new component should use the same start and end offsets as the source.

lfs migrate [--mdt-index|-m mdt_idx] {directory|filename}

Migrate the specified file, or the specified directory and its contents from the current MDT to the MDT with index mdt_idx.

OPTIONS

The various layout related options are listed and explained below:

-c, --stripe-count stripe_count

The number of OSTs to stripe a file over. --stripe_count=0 means to use the filesystem-wide default stripe count (default 1), and --stripe_count=-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. --stripe-size=0 means to use the filesystem-wide default stripe_size (default 1MB).

-i, --stripe-index start_ost_index

The OST index (starting at 0) on which to start striping for this file. --stripe-index=-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.

-o, --ost-list ost_index[,ost_index ...]

Specify the exact OSTs on which the the file will store data. ost_indices is a comma-separated 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 separated by commas, and OST index ranges specified by a dash, e.g. 1,2-5,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

The name of a predefined pool of OSTs (see lctl(8)) that will be used for striping the file. The stripe_count, stripe_size, and start_ost_index will be used as well. The start_ost_index must be part of the pool or an error will be returned. The various component related options are listed and explained below:

-E, --component-end end

The offset of the component's end is specified in bytes, or using a binary suffix (KMGTP), such as 256M to indicate 256MiB. --component-end=-1 indicates the end of file. All options specified after this option will apply to this component until another -E option is given. The component end must be strictly larger than the previous component and be a multiple of the previous component's --stripe-size, or an error will be returned.

-I, --component-id component_id

The numerical unique component identifier to be selected. The component ID is unique within a file and is automatically assigned at file creation time, and cannot be specified by the user. No relationship between component IDs and component offset within a file should be assumed. If the specified component does not exist, an error is returned.

-F, --component-flags flags

Component flags that can be set on a file at file creation time, or using --component-set, or used to select components for --component-del. Available flags are uninit to indicate that the component does not have any OST objects allocated yet. If no component matching the specified flags exists, an error is returned.

-d, --component-del

Delete the components selected by --component-id or --component-flags from an existing file or the directory layout template. The component(s) to be deleted must not have been initialized yet.

--component-set

Modify the attributes of the component selected by --component-id. Only the component flags can be changed currently. There are two options available only for lfs migrate:

-b, --block

Block file access during data migration (default).

-n, --non-block

Abort migrations if concurrent access is detected.

EXAMPLES

This creates a file striped on two OSTs with 128KiB on each stripe.

$ lfs setstripe -S 128k -c 2 /mnt/lustre/file1

This deletes a default stripe pattern on dir. New files will use the default striping pattern created therein.

$ lfs setstripe -d /mnt/lustre/dir

This creates a file with composite layout. The first component has a single stripe that covers [0, 4MiB) and is allocated from an OST in the flash pool. The second component has four stripes that cover [4MiB, 64MiB) and has a stripe size of 4MiB. The last component covers [64MiB, EOF), has a stripe size of 16MiB, and uses all available OSTs in the archive pool.

$ lfs setstripe -E 4M -c 1 --pool flash -E 64M -c 4 -S 4M -E -1 -c -1 -S 16M --pool archive /mnt/lustre/file1

This deletes the component with an ID of 1 from an existing file.

$ lfs setstripe -d -I 1 /mnt/lustre/file1

This deletes the component(s) from an existing file that have not yet been initialized (i.e. no OST objects allocated), and allows them to be specified in a different way or left unset to save space in the inode.

$ lfs setstripe -d -F uninit /mnt/lustre/file1

This migrate the file into a new layout with 2 stripes.

$ lfs migrate -c 2 /mnt/lustre/file1

This migrate the file onto MDT 1 from the original MDT.

$ lfs migrate -m 1 /mnt/lustre/file1

This migrate the component with ID 2 of the file into a new layout with eight stripes in the archive OST pool.

$ lfs migrate -I 2 -c 8 --pool archive /mnt/lustre/file1