]>
Commit | Line | Data |
---|---|---|
52826846 NB |
1 | .\" -*- nroff -*- |
2 | .TH mdctl 8 | |
3 | .SH NAME | |
4 | mdctl \- a single program that can be used to control Linux md devices | |
5 | .SH SYNOPSIS | |
6 | ||
7 | .BI mdctl | |
8 | [mode] <raiddevice> [options] | |
9 | ||
10 | .SH DESCRIPTION | |
11 | RAID devices are virtual devices created from two or more | |
12 | real block devices. This allows multiple disks to be combined into a single | |
13 | filesystem, possibly with integrated redundancy to survive drive failure.. Linux RAID devices | |
14 | are implemented through the md device driver. | |
15 | ||
16 | If you're using the | |
17 | .B /proc | |
18 | filesystem, | |
19 | .B /proc/mdstat | |
20 | gives you informations about md devices status. | |
21 | ||
22 | Currently, Linux supports linear md devices, RAID0 (striping), RAID1 | |
23 | (mirrroring), RAID4 and RAID5. For information on the various levels of | |
24 | RAID, check out: | |
25 | ||
26 | http://ostenfeld.dk/~jakob/Software-RAID.HOWTO/ | |
27 | ||
28 | for new releases of the RAID driver check out: | |
29 | ||
30 | ftp://ftp.kernel.org/pub/linux/kernel/people/mingo/raid-patches | |
31 | ||
32 | .B mdctl | |
33 | is a single program that can be used to control Linux md devices. It | |
34 | is intended to provide all the functionality (and more) of the mdtools | |
35 | and raidtools but with a very different interface. | |
36 | ||
37 | mdctl can perform all functions without a configuration file. There is the | |
38 | option of using a configuration file, but not in the same way that raidtools | |
39 | uses one. raidtools uses a configuration file to describe how to create a | |
40 | RAID array, and also uses this file partially to start a previously created | |
41 | RAID array. Further, raidtools requires the configuration file for such | |
42 | things as stopping a raid array which needs to know nothing about the array. | |
43 | ||
44 | The configuration file that can be used by mdctl lists two different things: | |
45 | ||
46 | .IP "\fB\-\fP" | |
47 | a list of md devices and information about how to identify each. The | |
48 | identity can consist of a UUID, and minor-number as recorded on the | |
49 | superblock, or a list of devices. | |
50 | ||
51 | .IP "\fB\-\fP" | |
52 | a list of devices that should be scanned for md sub-devices. | |
53 | ||
54 | .SH MODES | |
55 | mdctl has 4 major modes of operation: | |
56 | .IP "\fBCreate\fP" | |
57 | This mode is used to create a new array with a superblock. It can progress | |
58 | in several step create-add-add-run or it can all happen with one command. | |
59 | ||
60 | .IP "\fBAssemble\fP" | |
61 | This mode is used to assemble the parts of a previously created | |
62 | array into an active array. Components can be explicitly given | |
63 | or can be searched for. | |
64 | .B mdctl | |
65 | (optionally) checks that the components | |
66 | do form a bonafide array, and can, on request, fiddle superblock | |
67 | version numbers so as to assemble a faulty array. | |
68 | ||
69 | .IP "\fBBuild\fP" | |
70 | This is for building legacy arrays without superblocks. | |
71 | ||
72 | .IP "\fBManage\fP" | |
73 | This is for odd bits an pieces like hotadd, hotremove, setfaulty, stop, | |
74 | readonly,readwrite If an array is only partially setup by the | |
75 | Create/Assemble/Build command, subsequent Manage commands can finish the | |
76 | job. | |
77 | ||
78 | .SH OPTIONS | |
79 | ||
80 | Available options are: | |
81 | ||
82 | .IP "\fB\-C\fP, \fB\-\-create\fP" | |
83 | Create a new array | |
84 | ||
85 | .IP "\fB-A\fP, \fB\-\-assemble\fP" | |
86 | Assemble an existing array | |
87 | ||
88 | .IP "\fB\-B\fP, \fB\-\-build\fP" | |
89 | Build a legacy array without superblock | |
90 | ||
91 | .IP "\fB\-D\fP, \fB\-\-detail\fP" | |
92 | Print detail of a given md array | |
93 | ||
94 | .IP "\fB\-E\fP, \fB\-\-examine\fP" | |
95 | Print content of md superblock on device | |
96 | ||
97 | .IP "\fB\-h\fP, \fB\-\-help\fP" | |
98 | This help message or, after above option, mode specific help message | |
99 | ||
100 | .IP "\fB\-V\fP, \fB\-\-version\fP" | |
101 | Print version information for mdctl | |
102 | ||
103 | .IP "\fB\-v\fP, \fB\-\-verbose\fP" | |
104 | Be more verbose about what is happening | |
105 | ||
106 | .SH For create or build: | |
107 | ||
108 | .IP "\fB\-c\fP, \fB\-\-chunk=\fP" | |
109 | chunk size of kibibytes | |
110 | ||
111 | .IP "\fB\-\-rounding=\fP" | |
112 | rounding factor for linear array (==chunk size) | |
113 | ||
114 | .IP "\fB\-l\fP, \fB\-\-level=\fP" | |
115 | raid level: 0,1,4,5,linear. 0 or linear for build | |
116 | ||
117 | .IP "\fB\-p\fP, \fB\-\-parity=\fP" | |
118 | raid5 parity algorithm: {left,right}-{,a}symmetric | |
119 | ||
120 | .IP "\fB\-\-layout=\fP" | |
121 | same as --parity | |
122 | ||
123 | .IP "\fB\-n\fP, \fB\-\-raid-disks=\fP" | |
124 | number of active devices in array | |
125 | ||
126 | .IP "\fB\-x\fP, \fB\-\-spare-disks=\fP" | |
127 | number of spares (eXtras) to allow space for | |
128 | ||
129 | .IP "\fB\-z\fP, \fB\-\-size=\fP" | |
130 | Size (in K) of each drive in RAID1/4/5 - optional | |
131 | ||
132 | .SH For assemble: | |
133 | ||
134 | .IP "\fB\-u\fP, \fB\-\-uuid=\fP" | |
135 | uuid of array to assemble. Devices which don't have this uuid are excluded | |
136 | ||
137 | .IP "\fB\-c\fP, \fB\-\-config=\fP" | |
138 | config file | |
139 | ||
140 | .IP "\fB\-s\fP, \fB\-\-scan\fP" | |
141 | scan config file for missing information | |
142 | ||
143 | .IP "\fB\-f\fP, \fB\-\-force\fP" | |
144 | Assemble the array even if some superblocks appear out-of-date | |
145 | ||
146 | .SH General management | |
147 | ||
148 | .IP "\fB\-a\fP, \fB\-\-add\fP" | |
149 | add, or hotadd subsequent devices | |
150 | ||
151 | .IP "\fB\-r\fP, \fB\-\-remove\fP" | |
152 | remove subsequent devices | |
153 | ||
154 | .IP "\fB\-f\fP, \fB\-\-fail\fP" | |
155 | mark subsequent devices a faulty | |
156 | ||
157 | .IP "\fB\-\-set-faulty\fP" | |
158 | same as --fail | |
159 | ||
160 | .IP "\fB\-R\fP, \fB\-\-run\fP" | |
161 | start a partially built array | |
162 | ||
163 | .IP "\fB\-S\fP, \fB\-\-stop\fP" | |
164 | deactivate array, releasing all resources | |
165 | ||
166 | .IP "\fB\-o\fP, \fB\-\-readonly\fP" | |
167 | mark array as readonly | |
168 | ||
169 | .IP "\fB\-w\fP, \fB\-\-readwrite\fP" | |
170 | mark array as readwrite | |
171 | ||
172 | .SH CREATE MODE | |
173 | ||
174 | Usage: | |
175 | ||
176 | .B mdctl | |
177 | --create device --chunk=X --level=Y --raid-disks=Z devices | |
178 | ||
179 | This usage will initialise a new md array and possibly associate some | |
180 | devices with it. If enough devices are given to complete the array, the | |
181 | array will be activated. Otherwise it will be left inactive to be completed | |
182 | and activated by subsequent management commands. | |
183 | ||
184 | As devices are added, they are checked to see if they contain raid | |
185 | superblocks or filesystems. They are also check to see if the variance in | |
186 | device size exceeds 1%. | |
187 | ||
188 | If any discrepancy is found, the array will not automatically be run, though | |
189 | the presence of a | |
190 | .B --run | |
191 | can override this caution. | |
192 | ||
193 | If the | |
194 | .B --size | |
195 | option is given, it is not necessary to list any subdevices in this command. | |
196 | They can be added later, before a | |
197 | .B --run. | |
198 | If no | |
199 | .B --size | |
200 | is given, the apparent size of the smallest drive given is used. | |
201 | ||
202 | The General management options that are valid with --create are: | |
203 | .IP "\fB\-\-run\fP" | |
204 | insist of running the array even if not all devices are present or some look | |
205 | odd. | |
206 | ||
207 | .IP "\fB\-\-readonly\fP" | |
208 | start the array readonly - not supported yet. | |
209 | ||
210 | .SH ASSEMBLY MODE | |
211 | ||
212 | Usage: | |
213 | ||
214 | .B mdctl | |
215 | --assemble device options... | |
216 | ||
217 | .B mdctl | |
218 | --assemble --scan options... | |
219 | ||
220 | This usage assembles one or more raid arrays from pre-existing components. | |
221 | For each array, mdctl needs to know the md device, the uuid, and a number of | |
222 | sub devices. These can be found in a number of ways. | |
223 | ||
224 | The md device is either given before | |
225 | .B --scan | |
226 | or is found from the config file. In the latter case, multiple md devices | |
227 | can be started with a single mdctl command. | |
228 | ||
229 | The uuid can be given with the | |
230 | .B --uuid | |
231 | option, or can be found in in the config file, or will be taken from the | |
232 | super block on the first subdevice listed on the command line or in a | |
233 | subsequent | |
234 | .B --add | |
235 | command. | |
236 | ||
237 | Devices can be given on the | |
238 | .B --assemble | |
239 | command line, on subsequent | |
240 | .B 'mdctl --add' | |
241 | command lines, or from the config file. Only devices which have an md | |
242 | superblock which contains the right uuid will be considered for any device. | |
243 | ||
244 | The config file is only used if explicitly named with | |
245 | .B --config | |
246 | or requested with | |
247 | .B --scan. | |
248 | In the later case, | |
249 | .B /etc/md.conf | |
250 | is used. | |
251 | ||
252 | If | |
253 | .B --scan | |
254 | is not given, then the config file will only be used to find uuids for md | |
255 | arrays. | |
256 | ||
257 | The format of the config file is: | |
258 | not yet documented | |
259 | ||
260 | .SH BUILD MDOE | |
261 | ||
262 | Usage: | |
263 | ||
264 | .B mdctl | |
265 | --build device -chunk=X --level=Y --raid-disks=Z devices | |
266 | ||
267 | This usage is similar to | |
268 | .B --create. | |
269 | The difference is that it creates a legacy array without a superblock. With | |
270 | these arrays there is no different between initially creating the array and | |
271 | subsequently assembling the array, except that hopefully there is useful | |
272 | data there in the second case. | |
273 | ||
274 | The level may only be 0 or linear. All devices must be listed and the array | |
275 | will be started once complete. | |
276 | ||
277 | .SH BUGS | |
278 | no known bugs. | |
279 | ||
280 | .SH TODO | |
281 | ||
282 | ||
283 | .SH SEE ALSO | |
284 | .IR raidtab (5), | |
285 | .IR raid0run (8), | |
286 | .IR raidstop (8), | |
287 | .IR mkraid (8) |