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