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