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