lustre/doc/lfs-setdirstripe.1

   1 .TH LFS-SETDIRSTRIPE 1 2017-11-07 "Lustre" "Lustre Utilities"
   2 .SH NAME
   3 lfs setdirstripe, mkdir \- set striping pattern of a directory.
   4 .SH SYNOPSIS
   5 .B lfs setdirstripe [\fR-cCdDhHioTxX\fR] \fIDIR\fR...
   6 .br
   7 .SH DESCRIPTION
   8 Create a striped directory with specified striping pattern. This
   9 .B lfs
  10 sub-command is similar to
  11 .BR "lfs setstripe" ,
  12 but is used to create a striped directory or set the default layout for
  13 subdirectories.
  14 Can also be used to create directory with a foreign (free format) striping pattern (see
  15 .BR --foreign
  16 and
  17 .BR --xattr
  18 options).
  19 .B lfs mkdir
  20 is an alias for this command.
  21 .SH OPTIONS
  22 .TP
  23 .BR \-c ", " \-T ", " \-\-mdt\-count =\fICOUNT\fR
  24 Stripe the new directory over
  25 .I COUNT
  26 MDTs.
  27 .TP
  28 .B -C\fR, \fB--overstripe-count \fISTRIPE_COUNT\fR
  29 The number of stripes to create, creating > 1 stripe MDT if \fISTRIPE_COUNT\fR
  30 exceeds the number of MDTs in the file system. \fB0 \fRmeans to use the
  31 filesystem-wide default stripe count (default 1), and \fB-1 \fRmeans to stripe
  32 over all available MDTs.  Max of 5 stripes/MDT.
  33 .TP
  34 .BR \-h ", " \-\-help
  35 Print usage message.
  36 .TP
  37 .BR \-i ", " \-\-mdt\-index =\fISTART_MDT_INDEX\fR[,\fIMDT_INDEX ...]
  38 Use the MDT whose index is
  39 .I START_MDT_INDEX
  40 as the master/starting MDT for the directory. If multiple
  41 .I MDT_INDEX
  42 values are given, then the stripes will be allocated on the specified
  43 MDT indices.  If
  44 .B -1
  45 (default) is used, the client will round-robin subdirectory creation
  46 across all MDTs if their free space is within
  47 .B lod.*.mdt_qos_threshold_rr
  48 percent of each other, otherwise the client will prefer to select
  49 .B COUNT
  50 MDT(s) proportional to the free space and inodes on each.
  51
  52 Providing mutiple
  53 .I MDT_INDEX
  54 values while trying to set the default striping pattern of subdirectories using
  55 .B -D
  56 will not load balance subdirectory creation amongst the MDTs. Instead, this
  57 will cause all new subdirectories to be striped across all of the specified
  58 MDTs. This is discouraged and can lead to filesystem problems if too many
  59 striped directories are created. To do this anyway,
  60 .B -c N
  61 must also be specified, where
  62 .B N
  63 matches the number of MDT indices given.
  64 .TP
  65 .BR \-H ", " \-\-mdt-hash =\fIHASH_TYPE\fR
  66 Use
  67 .I hash_type
  68 for the striped directory.
  69 .RS 1.2i
  70 .TP
  71 .B crush
  72 CRUSH hash algorithm.  This is a consistent hash
  73 algorithm, so minimum sub files need to relocate
  74 during directory restripe.
  75 .TP
  76 .B fnv_1a_64
  77 Fowler-Noll-Vo (FNV-1a) hash algorithm.  This provides
  78 reasonably uniform, but not cryptographically strong,
  79 hashing of the filename. (default)
  80 .TP
  81 .B all_char
  82 Sum of ASCII characters modulo number of MDTs. This
  83 provides weak hashing of the filename, and is suitable
  84 for only testing or when the input is known to have
  85 perfectly uniform distribution (e.g. sequential numbers).
  86 .RE
  87 .TP
  88 .BR \-d ", " \-\-delete
  89 Delete the default striping layout from the directory.  New subdirectories
  90 created in this directory will inherit the global default directory layout
  91 (by default they will not be striped).
  92 .TP
  93 .BR \-D ", " \-\-default
  94 Set the default striping pattern of subdirectories. Newly created
  95 sub-directories will use the new default striping pattern,
  96 but existing sub-directories will not be affected.  The newly
  97 created sub-directories will also inherit the specified default
  98 striping pattern.
  99
 100 Note that striping all directories across all MDTs by default is
 101 .B not
 102 recommended at this time, as the clients will have to do more RPCs to
 103 create and access each directory, hurting performance rather than
 104 improving it.  Default striped directories are preferred only for
 105 parent directories where large subdirectories will be created
 106 (e.g. file-per-process job output directories).  Instead, using
 107 .B -c 1 -i -1
 108 on top-level directories balances mkdir therein over MDTs automatically
 109 without causing all subdirectories to be remote by default.
 110 .TP
 111 .BR \-o ", " \-\-mode =\fIMODE\fR
 112 Set the file access permissions of the new directory to the specified
 113 numeric
 114 .I MODE
 115 (typically octal), as with
 116 .BR chmod (1).
 117 It is not affected by the current
 118 .BR umask (1p).
 119 .TP
 120 .BR \-\-foreign[=type]
 121 Create a directory with a foreign (non-Lustre/free format, see
 122 .BR \-\-xattr
 123 option) striping. Where
 124 .BR type
 125 specifies a known foreign type (like
 126 .BR none
 127 ,
 128 .BR symlink
 129 , ...) or a 32-bit numeric type.
 130 .TP
 131 .BR \-\-flags =\fI<hex>\fR
 132 Specify a numeric bitmask of type-specific layout flags for the foreign layout.
 133 .TP
 134 .BR \-x ", " \-\-xattr =\fISTRING\fR
 135 Specify a string to be used as a foreign (free format) striping.
 136 .TP
 137 .BR \-X ", " \-\-max-inherit = \fIMAX_INHERIT
 138 Set the inherit depth of default directory layout. If non-zero, then
 139 .I MAX_INHERIT
 140 is the number of subdirectory levels for which this default layout is inherited,
 141 up to a maximum of 250 levels, and is decremented by one when copying the
 142 default layout to each new subdirectory, until zero and the default layout is
 143 no longer copied. A
 144 .I MAX_INHERIT
 145 of -1 means the default layout is inherited for all subdirectories.
 146 .TP
 147 .BR \-\-max-inherit-rr = \fIMAX_INHERIT_RR
 148 Set the round-robin inherit depth of the default directory layout, only when
 149 .I START_MDT_INDEX
 150 is -1.  If
 151 .I MAX_INHERIT_RR
 152 is zero (unset), then new subdirectories are preferentially created on MDTs
 153 with more free space and inodes if the MDTs are imbalanced.  If non-zero, then
 154 .I MAX_INHERIT_RR
 155 is the number of subdirectory levels, up to a maximum of 250 levels, for which
 156 new subdirectories will be created in a round-robin manner across all available
 157 MDTs, rather than using MDT space balancing for new subdirectories.  Otherwise,
 158 .I MAX_INHERIT_RR
 159 is decremented by one when copying the default layout to each new subdirectory,
 160 until zero and round-robin is no longer used.  It may be useful to set
 161 .I MAX_INHERIT_RR
 162 to 2 or 3 when setting the default directory layout on the root of a
 163 .B new
 164 filesystem, so that top-level subdirectories are immediately spread
 165 across MDTs, rather than waiting for the MDTs to become imbalanced.
 166 Round-robin subdirectory creation is unlikely to be useful for existing
 167 filesystems that already have many files and imbalanced MDTs, since space
 168 balancing will already happen, and this will unnecessarily increase the number
 169 of remote subdirectories (increasing overhead) without any benefit.
 170 .SH NOTE
 171 .PP
 172 If neither
 173 .B -c
 174 or
 175 .B -i
 176 are specified,
 177 .B lfs mkdir
 178 will default to
 179 .B -c 1 -i -1
 180 and create the directory on an MDT that is less full than the others.
 181 .PP
 182 The
 183 .B lfs setdirstripe
 184 command is only usable by root unless the
 185 .B "mdt.*.enable_remote_dir_gid"
 186 is set on the MDS via
 187 .B lctl set_param
 188 to be either a non-zero numeric GID to limit it to a single group (e.g. the
 189 .BR "operator " or " admin"
 190 GID), or
 191 .B "-1"
 192 to allow any user/group to create remote directories.  By default, it is
 193 .B "0"
 194 to limit remote/striped directories to only the root user.
 195
 196 The root directory of the file system is on MDT0000, and a filesystem-wide
 197 default directory layout is set on it by default:
 198 .B lfs setdirstripe -D -i -1 -c 1 --max-inherit -1 --max-inherit-rr 3
 199 , which is a space balanced directory layout, therefore new directories will be
 200 created on all MDTs by inode and space usage, and the top three level of new
 201 directories will be created in roundrobin mode if system is balanced.  If user
 202 doesn't want automatic space balance, deleting this default directory layout
 203 won't work, because it will be recreated if not set, instead user can run
 204 .B lfs setdirstripe -D -i -1 -c 1 --max-inherit 1 <mountpoint>
 205 to limit space balance in the top level, or run
 206 .B lfs setdirstripe -D -i 0 -c 1 --max-inherit 1 <mountpoint>
 207 to disable it.
 208
 209 .SH EXAMPLES
 210 .TP
 211 .B $ lfs setdirstripe -c 2 -i 1 -H all_char /mnt/lustre/dir1
 212 This creates a directory striped on two MDTs, whose first stripe is on
 213 .B MDT0001
 214 (MDT index 1), and whose hash type is
 215 .BR all_char .
 216 .TP
 217 .B $ lfs mkdir --foreign=symlink --xattr PUUID/CUUID /mnt/lustre/dir1
 218 This creates
 219 .B dir1
 220 with foreign (non-lustre/free format)
 221 .B PUUID/CUUID
 222 striping/LMV EA value (symlink type).
 223 .SH AVAILABILITY
 224 The
 225 .B lfs setdirstripe
 226 command is part of the Lustre filesystem.
 227 .SH SEE ALSO
 228 .BR lctl (8),
 229 .BR lfs (1),
 230 .BR lfs-getdirstripe (1),
 231 .BR lfs-setstripe (1),
 232 .BR lustre (7)