Whamcloud - gitweb
LU-11213 doc: update lfs-setdirstripe man 'space' hash
[fs/lustre-release.git] / 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-cdDHioTx\fR] \fIDIR\fR...
6 .br
7 .SH DESCRIPTION
8 Create a striped directory with specified striping pattern. This lfs utility
9 is similar to
10 .BR lfs setstripe
11 , but is used to create striped directory.
12 Can also be used to create directory with a foreign (free format) striping pattern (see
13 .BR --foreign
14 and
15 .BR --xattr
16 options).
17 .B lfs mkdir
18 is an alias for this command.
19 .SH OPTIONS
20 .TP
21 .BR \-c ", " \-T ", " \-\-mdt\-count =\fICOUNT\fR
22 Stripe the new directory over
23 .I COUNT
24 MDTs.
25 .TP
26 .BR \-i ", " \-\-mdt\-index =\fISTART_MDT_INDEX\fR[,\fIMDT_INDEX ...]
27 Use the MDT whose index is
28 .I START_MDT_INDEX
29 as the master/starting MDT for the directory. If multiple
30 .I MDT_INDEX
31 values are given, then the stripes will be allocated on the specified
32 MDT indices.  If index -1 (default) is used, it will randomly pick
33 .I COUNT
34 less full MDTs.
35 .TP
36 .BR \-H ", " \-\-mdt-hash =\fIHASH_TYPE\fR
37 Use
38 .I hash_type
39 for the striped directory.
40 .RS 1.2i
41 .TP
42 .B fnv_1a_64
43 Fowler-Noll-Vo (FNV-1a) hash algorithm.  This provides
44 reasonably uniform, but not cryptographically strong,
45 hashing of the filename. (default)
46 .TP
47 .B space
48 This can only be set on plain directory default striping.
49 Newly created sub-directories will be distributed on all
50 MDTs by MDT space usage. Note that this is suggested to
51 be set on lustre ROOT, so that all sub-directories under
52 lustre ROOT are distributed among all MDTs.
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 not
74 recommended at this time, as the clients will have to do more RPCs to
75 create and access each directory, hurting performance rather than
76 improving it.  Default striped directories are preferred for cases
77 where large subdirectories will be created (e.g. file-per-process
78 job output directories).
79 .TP
80 .BR \-o ", " \-\-mode =\fIMODE\fR
81 Set the file access permissions of the new directory to the specified
82 numeric
83 .I MODE
84 (typically octal), as with
85 .BR chmod (1).
86 It is not affected by the current
87 .BR umask (1p).
88 .TP
89 .BR \-\-foreign[=type]
90 Create a directory with a foreign (non-Lustre/free format, see
91 .BR \-\-xattr
92 option) striping. Where
93 .BR type
94 specifies a known foreign type (like
95 .BR none
96 ,
97 .BR daos
98 , ...) or a 32-bit numeric type.
99 .TP
100 .BR \-\-flags =\fI<hex>\fR
101 Specify a bitmask of flags.
102 .TP
103 .BR \-x ", " \-\-xattr =\fISTRING\fR
104 Specify a string to be used as a foreign (free format) striping.
105 .SH NOTE
106 .PP
107 The
108 .B lfs setdirstripe
109 command is only executable by root unless
110 .B "mdt.*.enable_remote_dir_gid"
111 is set on the MDS via
112 .B lctl set_param
113 to be either a non-zero GID to limit it to a single group
114 (e.g. "operator" or "admin"), or "-1" to allow any group
115 to create remote directories.
116
117 The root of the file system is on MDT0000, and directories and files inherit the
118 MDT of their parent directory unless a different MDT is specified with this
119 command.
120
121 By default, only directories on MDT0000 can contain directories that are not on
122 the same MDT.  However, if "mdt.*.enable_remote_dir" is set non-zero on an MDT
123 then it will allow creating remote directories that have parents other than
124 MDT0000. This is restricted to avoid creating directory trees that have
125 intermediate path components on a series different MDTs and become unavailable
126 if any of the intermediate MDTs are offline.
127 .SH EXAMPLES
128 .TP
129 .B $ lfs setdirstripe -c 2 -i 1 -H all_char /mnt/lustre/dir1
130 This creates a directory striped on two MDTs, whose first stripe is on
131 .B MDT0001
132 (MDT index 1), and whose hash type is
133 .BR all_char .
134 .TP
135 .B $ lfs mkdir --foreign=daos --xattr PUUID:CUUID /mnt/lustre/dir1
136 This creates
137 .B dir1
138 with foreign (non-lustre/free format)
139 .B PUUID:CUUID
140 striping/LMV EA.
141 .SH AVAILABILITY
142 The
143 .B lfs setdirstripe
144 command is part of the Lustre filesystem.
145 .SH SEE ALSO
146 .BR lctl (8),
147 .BR lfs (1),
148 .BR lfs-getdirstripe (1),
149 .BR lfs-setstripe (1),
150 .BR lustre (7)