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|\fIfilename\fR>
   6 .br
   7 .B lfs setstripe \fR{\fB--component-end\fR|\fB-E \fIend1\fR} [\fISTRIPE_OPTIONS\fR]
   8 [{\fB--component-end\fR|\fB-E \fIend2\fR} [\fISTRIPE_OPTIONS\fR] ...] <\fIfilename\fR>
   9 .br
  10 .B lfs setstripe --component-add \fR{\fB--component-end\fR|\fB-E \fIend1\fR}
  11 [\fISTRIPE_OPTIONS\fR] [{\fB--component-end\fR|\fB-E \fIend2\fR} [\fISTRIPE_OPTIONS\fR]
  12 \&...] <\fIfilename\fR>
  13 .br
  14 .B lfs setstripe --component-del \fR{\fB--component-id\fR|\fB-I \fIcomp_id\fR|
  15 .B --component-flags=\fIcomp_flags\fR} <\fIfilename\fR>
  16 .br
  17 .B lfs setstripe --component-set \fR{\fB--component-id\fR|\fB-I \fIcomp_id\fR|
  18 .B --component-flags=\fIcomp_flags\fR} <\fIfilename\fR>
  19 .br
  20 .B lfs setstripe -d \fR<\fIdirectory\fR>
  21 .br
  22 .B lfs setstripe --yaml=<yaml_template_file> <filename>
  23 .br
  24 .SH DESCRIPTION
  25 .TP
  26 .B lfs setstripe \fR[\fISTRIPE_OPTIONS\fR] <\fIdirectory\fR|\fIfilename\fR>
  27 Create a file with specified layout, or set or replace the default file
  28 layout on an existing directory.  If the default file layout is set on
  29 the filesystem root directory, it will be used as the filesystem-wide
  30 default layout for all files that do not explicitly specify a layout and
  31 do not have a default layout on the parent directory.  The default layout
  32 set on a directory will be copied to any new subdirectories created within
  33 that directory at the time they are created.
  34 .TP
  35 .B lfs setstripe \fR{\fB--component-end\fR|\fB-E \fIend1\fR} [\fISTRIPE_OPTIONS\fR] \
  36 [{\fB--component-end\fR|\fB-E \fIend2\fR} [\fISTRIPE_OPTIONS\fR] ...] <\fIfilename\fR>
  37 .br
  38 Create a file with the specified composite layout. Each component defines the
  39 stripe pattern of the file in the range of
  40 .RI [ start ", " end ].
  41 The first component implicitly starts at offset 0, and all later components
  42 start at the end of previous extent.  The
  43 .B -E
  44 option is used to specify the end offset of each component, and it also
  45 indicates the following \fISTRIPE_OPTIONS\fR are for this component. The end
  46 offset of
  47 .B -1
  48 or
  49 .B eof
  50 indicates the component extends to the end of file.
  51 .TP
  52 .B lfs setstripe --component-add \fR{\fB--component-end\fR|\fB-E \fIend1\fR} [\fISTRIPE_OPTIONS\fR] \
  53 [{\fB--component-end\fR|\fB-E \fIend2\fR} [\fISTRIPE_OPTIONS\fR] ...] <\fIfilename\fR>
  54 .br
  55 Add components to an existing composite file. The extent start of the first
  56 component to be added is equal to the extent end of last component in existing
  57 file, and all components to be added must be adjacent with each other.  It is
  58 not possible to add components incrementally to the default directory layout,
  59 since the entire default layout can be replaced with one
  60 .B lfs setstripe
  61 call.
  62 .br
  63 Adding a component to FLR files is not allowed.
  64 .TP
  65 .B lfs setstripe --component-del \fR{\fB--component-id\fR|\fB-I \fIcomp_id\fR | \
  66 \fB--component-flags \fIcomp_flags\fR} <\fIfilename\fR>
  67 .br
  68 Remove the component(s) specified by component ID or flags from an existing
  69 file. The ID specified by the
  70 .B -I
  71 option is the numerical unique ID of the component, it can be obtained using
  72 the
  73 .B lfs getstripe
  74 command.  It is not possible to delete components from a default directory
  75 layout, since the entire default layout can be replaced with one
  76 .B lfs setstripe
  77 call.
  78 The \fB--component-flags\fR option is used to specify certain type of
  79 components, such as all instantiated ones. Available component flags for
  80 deleting a component would be:
  81 .RS
  82 .TP
  83 .B init
  84 instantiated component.
  85 .LP
  86 A leading '^' in front of the \fIflags\fR means inverted flags.
  87 .br
  88 Deleting a component from FLR files is not allowed.
  89 .RE
  90 .TP
  91 .B lfs setstripe --component-set \fR{\fB--component-id\fR|\fB-I \fIcomp_id\fR | \
  92 \fB--component-flags \fIcomp_flags\fR} <\fIfilename\fR>
  93 Set or clear \fIflags\fR to the specified component. This command can be only
  94 be applied to FLR files. Available \fIflags\fR are:
  95 .RS
  96 .TP
  97 .B stale
  98 indicates the data in the corresponding component is not available for I/O.
  99 Once a component is set to stale, a \fBlfs-mirror-resync\fR(1) is required to
 100 clear the flag.
 101 .TP
 102 .B prefer
 103 set this flag to the corresponding component so that Lustre would prefer to
 104 choose the specified component for I/O.
 105 .LP
 106 A leading '^' means to clear the corresponding flag. It doesn't allow to clear
 107 \fBstale\fR flag.
 108 .RE
 109 .TP
 110 .B lfs setstripe -d \fR<\fIdirectory\fR>
 111 .br
 112 Delete the default layout on the specified directory.  It is not necessary
 113 to delete the default layout on a directory before replacing it.  This is
 114 only needed if the directory should revert from a directory-specific layout
 115 to using the global filesystem default layout stored on the root directory.
 116 .TP
 117 .B lfs setstripe --yaml=<yaml_template_file> <filename>
 118 .br
 119 Create a file with layout information specified by a YAML format template
 120 file, the template file can be obtained using the
 121 .B lfs getstripe --yaml <anotherfile>
 122 command.
 123 .SH STRIPE_OPTIONS
 124 The various 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. \fB0\fR
 133 means to use the filesystem-wide default stripe_size (default 4MB).
 134 .TP
 135 .B -i\fR, \fB--stripe-index \fR<\fIstart_ost_index\fR>
 136 The OST index (starting at 0) on which to start striping for this file. \fB-1\fR
 137 allows the MDS to choose the starting index and it is strongly recommended, as
 138 this allows space and load balancing to be done by the MDS as needed.
 139 .TP
 140 .B -o\fR, \fB--ost-list \fR<\fIost_indices\fR>
 141 Used to specify the exact stripe layout on the file system. \fIost_indices\fR
 142 is a list of OSTs referenced by their indices, which are specified in decimal
 143 or hex form and can be obtained using the
 144 .B lfs osts
 145 command. The list format consists of individual OST indices and index ranges
 146 separated by commas, e.g. 1,2-4,7. The
 147 .B -o
 148 option may be specified multiple times to stripe across the union of all listed
 149 OSTs. If the
 150 .B -c
 151 option is combined with
 152 .B -o
 153 the
 154 .I stripe_count
 155 must agree with the number of OSTs in
 156 .IR ost_indices .
 157 If the
 158 .B -i
 159 option is combined with
 160 .B -o
 161 the
 162 .I start_ost_index
 163 must be in the OST list, and it will be used as the index on which to start
 164 striping the file. Otherwise the striping will occur in the order specified in
 165 .IR ost_indices .
 166 .TP
 167 .B -p\fR, \fB--pool \fR<\fIpool_name\fR>
 168 The name of a predefined pool of OSTs (see
 169 .BR lctl (8))
 170 that will be used for striping. The
 171 .IR stripe_count ,
 172 .IR stripe_size ,
 173 and
 174 .I start_ost_index
 175 will be used as well; the
 176 .I start_ost_index
 177 must be part of the pool or an error will be returned.
 178 If <\fIpool_name\fR> is
 179 .BR none
 180 , then the OST pool name will be cleared and inherit from parent directory.
 181 .TP
 182 .B -L, --layout <\fIlayout type\fB>\fR
 183 The type of stripe layout, can be
 184 .BR raid0 ", " released " or " mdt ".
 185 It is
 186 .BR raid0
 187 by default. The
 188 .BR mdt
 189 type allows place the first component of the file on the MDT where the inode
 190 is located. This is used with composite file layouts and can be defined as
 191 first component only. The
 192 .IR stripe_size
 193 of MDT part is always equal to the component size. There is also per-MDT
 194 parameter
 195 .IR lod.dom_stripesize
 196 to limit maximum size of DoM stripe which can be changed with
 197 .BR lctl\ set_param
 198 command, (e.g.
 199 .IR lctl\ set_param\ lod.*.dom_stripesize=0
 200 , see
 201 .BR lctl (8))
 202 .TP
 203 There are two options available only for \fBlfs migrate\fR:
 204 .TP
 205 .BR -b , --block
 206 Block file access during data migration (default).
 207 .TP
 208 .BR -n , --non-block
 209 Abort migrations if concurrent access is detected.
 210 .SH COMPONENT_OPTIONS
 211 The various component related options are listed and explained below:
 212 .TP
 213 .B -E\fR,\fB--component-end \fR< \fIend\fR>
 214 The end offset of the component,
 215 .I end
 216 is specified in bytes, or using a suffix (kMGTP),
 217 such as 256M. \fB-1\fR means the end of file.
 218 .TP
 219 .B -I\fR, \fB--component-id \fR<\fIcomp_id\fR>
 220 The numerical unique component id.
 221 .TP
 222 .B --component-flags \fR<\fIflags\fR>
 223 Component flags. Available \fIflags\fR:
 224 .RS
 225 .RS
 226 .B init\fR: instantiated component.
 227 .RE
 228 .RS
 229 .B prefer\fR: preferred component, for FLR only.
 230 .RE
 231 .RS
 232 .B stale\fR: stale component, for FLR only.
 233 .RE
 234 .LP
 235 A leading '^' means inverted flag. Multiple flags can be separated by comma(s).
 236 .RE
 237 .TP
 238 .B --component-add
 239 Add specified components to an existing composite file.
 240 .TP
 241 .B --component-del
 242 Delete specified the components from an existing file. Deletion must start
 243 with the last component.
 244 .SH EXAMPLES
 245 .TP
 246 .B $ lfs setstripe -S 128k -c 2 /mnt/lustre/file1
 247 This creates a file striped on two OSTs with 128kB on each stripe.
 248 .TP
 249 .B $ lfs setstripe -d /mnt/lustre/dir
 250 This deletes a default stripe pattern on dir. New files created in that
 251 directory will use the filesystem global default instead.
 252 .TP
 253 .B $ lfs setstripe -E 4M -c 1 -E 64M -c 4 -E -1 -c -1 /mnt/lustre/file1
 254 This creates a file with composite layout, the component has 1 stripe and \
 255 covers [0, 4M), the second component has 4 stripes and covers [4M, 64M), the \
 256 last component stripes over all available OSTs and covers [64M, EOF).
 257 .TP
 258 .B $ lfs setstripe --component-add -E -1 -c 4  /mnt/lustre/file1
 259 This add a component which start from the end of last existing component to \
 260 the end of file.
 261 .TP
 262 .B $ lfs setstripe --component-del -I 1 /mnt/lustre/file1
 263 This deletes the component with ID equals 1 from an existing file.
 264 .TP
 265 .B $ lfs setstripe --component-set -I 1 --component-flags=^prefer,stale /mnt/lustre/file1
 266 This command will clear the \fBprefer\fR flag and set the \fBstale\fR to
 267 component with ID 1.
 268 .TP
 269 .B $ lfs setstripe -E 1M -L mdt -E -1 /mnt/lustre/file1
 270 This created file with Data-on-MDT layout. The first 1M is placed on MDT and \
 271 rest of file is placed on OST with default striping.
 272 .TP
 273 .B $ lfs setstripe --yaml=/tmp/layout_yaml /mnt/lustre/file2
 274 This creates a file with layout specified by a layout template which can be \
 275 obtained with \fBlfs getstripe --yaml\fR command.
 276
 277 .SH SEE ALSO
 278 .BR lfs (1),
 279 .BR lfs-migrate (1),
 280 .BR lustre (7)