]> git.ipfire.org Git - thirdparty/mdadm.git/blame - ReadMe.c
Add failfast support.
[thirdparty/mdadm.git] / ReadMe.c
CommitLineData
64c4757e 1/*
9a9dab36 2 * mdadm - manage Linux "md" devices aka RAID arrays.
64c4757e 3 *
c61b1c0b 4 * Copyright (C) 2001-2016 Neil Brown <neilb@suse.com>
64c4757e
NB
5 *
6 *
7 * This program is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation; either version 2 of the License, or
10 * (at your option) any later version.
11 *
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
16 *
17 * You should have received a copy of the GNU General Public License
18 * along with this program; if not, write to the Free Software
19 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20 *
21 * Author: Neil Brown
fffdbe5e 22 * Email: <neilb@suse.de>
64c4757e
NB
23 */
24
9a9dab36 25#include "mdadm.h"
64c4757e 26
b379508e 27#ifndef VERSION
c61b1c0b 28#define VERSION "3.4"
b379508e
N
29#endif
30#ifndef VERS_DATE
c61b1c0b 31#define VERS_DATE "28th January 2016"
b379508e 32#endif
d56dd607 33char Version[] = "mdadm - v" VERSION " - " VERS_DATE "\n";
4b1ac34b 34
64c4757e
NB
35/*
36 * File: ReadMe.c
37 *
38 * This file contains general comments about the implementation
9a9dab36 39 * and the various usage messages that can be displayed by mdadm
64c4757e 40 *
64c4757e
NB
41 */
42
43/*
dd0781e5 44 * mdadm has 7 major modes of operation:
64c4757e 45 * 1/ Create
5787fa49 46 * This mode is used to create a new array with a superblock
64c4757e
NB
47 * 2/ Assemble
48 * This mode is used to assemble the parts of a previously created
49 * array into an active array. Components can be explicitly given
58380584 50 * or can be searched for. mdadm (optionally) checks that the components
5787fa49 51 * do form a bona-fide array, and can, on request, fiddle superblock
64c4757e
NB
52 * version numbers so as to assemble a faulty array.
53 * 3/ Build
54 * This is for building legacy arrays without superblocks
55 * 4/ Manage
e0d19036
NB
56 * This is for doing something to one or more devices
57 * in an array, such as add,remove,fail.
58 * run/stop/readonly/readwrite are also available
59 * 5/ Misc
60 * This is for doing things to individual devices.
61 * They might be parts of an array so
62 * zero-superblock, examine might be appropriate
63 * They might be md arrays so
64 * run,stop,rw,ro,detail might be appropriate
65 * Also query will treat it as either
66 * 6/ Monitor
67 * This mode never exits but just monitors arrays and reports changes.
dd0781e5
NB
68 * 7/ Grow
69 * This mode allows for changing of key attributes of a raid array, such
70 * as size, number of devices, and possibly even layout.
58380584
N
71 * 8/ Incremental
72 * Is assembles an array incrementally instead of all at once.
73 * As devices are discovered they can be passed to "mdadm --incremental"
74 * which will collect them. When enough devices to for an array are
75 * found, it is started.
64c4757e
NB
76 */
77
866f509f 78char short_options[]="-ABCDEFGIQhVXYWZ:vqbc:i:l:p:m:n:x:u:c:d:z:U:N:sarfRSow1tye:";
024768c4 79char short_bitmap_options[]=
5d500228 80 "-ABCDEFGIQhVXYWZ:vqb:c:i:l:p:m:n:x:u:c:d:z:U:N:sarfRSow1tye:";
8382f19b 81char short_bitmap_auto_options[]=
5d500228 82 "-ABCDEFGIQhVXYWZ:vqb:c:i:l:p:m:n:x:u:c:d:z:U:N:sa:rfRSow1tye:";
773135f5 83
64c4757e 84struct option long_options[] = {
1c7a808c
N
85 {"manage", 0, 0, ManageOpt},
86 {"misc", 0, 0, MiscOpt},
64c4757e
NB
87 {"assemble", 0, 0, 'A'},
88 {"build", 0, 0, 'B'},
89 {"create", 0, 0, 'C'},
90 {"detail", 0, 0, 'D'},
91 {"examine", 0, 0, 'E'},
52826846 92 {"follow", 0, 0, 'F'},
dd0781e5 93 {"grow", 0, 0, 'G'},
8382f19b 94 {"incremental",0,0, 'I'},
f7d3febc 95 {"zero-superblock", 0, 0, KillOpt}, /* deliberately not a short_option */
e0d19036 96 {"query", 0, 0, 'Q'},
c82f047c 97 {"examine-bitmap", 0, 0, 'X'},
1f48664b 98 {"auto-detect", 0, 0, AutoDetect},
4cce4069 99 {"detail-platform", 0, 0, DetailPlatform},
33414a01 100 {"kill-subarray", 1, 0, KillSubarray},
aa534678 101 {"update-subarray", 1, 0, UpdateSubarray},
20b60dcd 102 {"udev-rules", 2, 0, UdevRules},
08ca2adf 103 {"offroot", 0, 0, OffRootOpt},
6d388a88 104 {"examine-badblocks", 0, 0, ExamineBB},
52826846 105
74db60b0
N
106 {"dump", 1, 0, Dump},
107 {"restore", 1, 0, Restore},
108
52826846
NB
109 /* synonyms */
110 {"monitor", 0, 0, 'F'},
aba69144 111
64c4757e 112 /* after those will normally come the name of the md device */
58380584 113
64c4757e 114 {"help", 0, 0, 'h'},
1c7a808c 115 {"help-options",0,0, HelpOptions},
64c4757e
NB
116 {"version", 0, 0, 'V'},
117 {"verbose", 0, 0, 'v'},
dab6685f 118 {"quiet", 0, 0, 'q'},
64c4757e
NB
119
120 /* For create or build: */
1c7a808c
N
121 {"chunk", 1, 0, ChunkSize},
122 {"rounding", 1, 0, ChunkSize}, /* for linear, chunk is really a
123 * rounding number */
98c6faba 124 {"level", 1, 0, 'l'}, /* 0,1,4,5,6,linear */
1c7a808c
N
125 {"parity", 1, 0, Layout}, /* {left,right}-{a,}symmetric */
126 {"layout", 1, 0, Layout},
64c4757e 127 {"raid-disks",1, 0, 'n'},
b83d95f3 128 {"raid-devices",1, 0, 'n'},
64c4757e 129 {"spare-disks",1,0, 'x'},
b83d95f3 130 {"spare-devices",1,0, 'x'},
dd0781e5 131 {"size", 1, 0, 'z'},
1c7a808c 132 {"auto", 1, 0, Auto}, /* also for --assemble */
997aed5d 133 {"assume-clean",0,0, AssumeClean },
f9ce90ba 134 {"metadata", 1, 0, 'e'}, /* superblock format */
1c7a808c 135 {"bitmap", 1, 0, Bitmap},
997aed5d
NB
136 {"bitmap-chunk", 1, 0, BitmapChunk},
137 {"write-behind", 2, 0, WriteBehind},
1c7a808c 138 {"write-mostly",0, 0, WriteMostly},
71574efb
N
139 {"failfast", 0, 0, FailFast},
140 {"nofailfast",0, 0, NoFailFast},
997aed5d
NB
141 {"re-add", 0, 0, ReAdd},
142 {"homehost", 1, 0, HomeHost},
38098016 143 {"symlinks", 1, 0, Symlinks},
40c9a66a 144 {"data-offset",1, 0, DataOffset},
7e6e839a 145 {"nodes",1, 0, Nodes}, /* also for --assemble */
7716570e 146 {"home-cluster",1, 0, ClusterName},
cc1799c3 147 {"write-journal",1, 0, WriteJournal},
64c4757e
NB
148
149 /* For assemble */
150 {"uuid", 1, 0, 'u'},
1c7a808c 151 {"super-minor",1,0, SuperMinor},
947fd4dd 152 {"name", 1, 0, 'N'},
1c7a808c 153 {"config", 1, 0, ConfigFile},
64c4757e 154 {"scan", 0, 0, 's'},
1c7a808c 155 {"force", 0, 0, Force},
5787fa49 156 {"update", 1, 0, 'U'},
b76b30e0 157 {"freeze-reshape", 0, 0, FreezeReshape},
dfd4d8ee 158
64c4757e 159 /* Management */
1c7a808c 160 {"add", 0, 0, Add},
f33a71f1 161 {"add-spare", 0, 0, AddSpare},
01290056 162 {"add-journal", 0, 0, AddJournal},
1c7a808c
N
163 {"remove", 0, 0, Remove},
164 {"fail", 0, 0, Fail},
165 {"set-faulty",0, 0, Fail},
70c55e36
N
166 {"replace", 0, 0, Replace},
167 {"with", 0, 0, With},
64c4757e
NB
168 {"run", 0, 0, 'R'},
169 {"stop", 0, 0, 'S'},
170 {"readonly", 0, 0, 'o'},
171 {"readwrite", 0, 0, 'w'},
997aed5d 172 {"no-degraded",0,0, NoDegraded },
1c7a808c 173 {"wait", 0, 0, WaitOpt},
1770662b 174 {"wait-clean", 0, 0, Waitclean },
a740cf64 175 {"action", 1, 0, Action },
4de90913 176 {"cluster-confirm", 0, 0, ClusterConfirm},
52826846 177
cd29a5c8 178 /* For Detail/Examine */
1c7a808c 179 {"brief", 0, 0, Brief},
54bad364 180 {"export", 0, 0, 'Y'},
997aed5d 181 {"sparc2.2", 0, 0, Sparc22},
feb716e9 182 {"test", 0, 0, 't'},
c2ecf5f6 183 {"prefer", 1, 0, Prefer},
cd29a5c8 184
52826846 185 /* For Follow/monitor */
1c7a808c
N
186 {"mail", 1, 0, EMail},
187 {"program", 1, 0, ProgramOpt},
188 {"alert", 1, 0, ProgramOpt},
189 {"increment", 1, 0, Increment},
52826846 190 {"delay", 1, 0, 'd'},
1c7a808c
N
191 {"daemonise", 0, 0, Fork},
192 {"daemonize", 0, 0, Fork},
aa88f531 193 {"oneshot", 0, 0, '1'},
b5e64645 194 {"pid-file", 1, 0, 'i'},
90cf1ddd 195 {"syslog", 0, 0, 'y'},
edde9560
AC
196 {"no-sharing", 0, 0, NoSharing},
197
06b0d786 198 /* For Grow */
997aed5d 199 {"backup-file", 1,0, BackupFile},
87f26d14 200 {"invalid-backup",0,0,InvalidBackup},
84e11361 201 {"array-size", 1, 0, 'Z'},
2dddadb0 202 {"continue", 0, 0, Continue},
8382f19b
NB
203
204 /* For Incremental */
1c7a808c 205 {"rebuild-map", 0, 0, RebuildMapOpt},
950bc344
PC
206 {"path", 1, 0, IncrementalPath},
207
64c4757e
NB
208 {0, 0, 0, 0}
209};
210
211char Usage[] =
9a9dab36 212"Usage: mdadm --help\n"
64c4757e
NB
213" for help\n"
214;
215
216char Help[] =
e5a5d81e
NB
217"mdadm is used for building, managing, and monitoring\n"
218"Linux md devices (aka RAID arrays)\n"
9a9dab36 219"Usage: mdadm --create device options...\n"
e5a5d81e 220" Create a new array from unused devices.\n"
9a9dab36 221" mdadm --assemble device options...\n"
e968ba60 222" Assemble a previously created array.\n"
9a9dab36 223" mdadm --build device options...\n"
e5a5d81e 224" Create or assemble an array without metadata.\n"
e0d19036 225" mdadm --manage device options...\n"
e968ba60 226" make changes to an existing array.\n"
e0d19036 227" mdadm --misc options... devices\n"
e968ba60 228" report on or modify various md related devices.\n"
8382f19b
NB
229" mdadm --grow options device\n"
230" resize/reshape an active array\n"
231" mdadm --incremental device\n"
29ba4804 232" add/remove a device to/from an array as appropriate\n"
e0d19036 233" mdadm --monitor options...\n"
e968ba60 234" Monitor one or more array for significant changes.\n"
9a9dab36 235" mdadm device options...\n"
e968ba60 236" Shorthand for --manage.\n"
e5a5d81e
NB
237"Any parameter that does not start with '-' is treated as a device name\n"
238"or, for --examine-bitmap, a file name.\n"
239"The first such name is often the name of an md device. Subsequent\n"
240"names are often names of component devices.\n"
241"\n"
56eedc1a 242" For detailed help on the above major modes use --help after the mode\n"
e0d19036 243" e.g.\n"
9a9dab36 244" mdadm --assemble --help\n"
56eedc1a
NB
245" For general help on options use\n"
246" mdadm --help-options\n"
247;
248
249char OptionHelp[] =
64c4757e 250"Any parameter that does not start with '-' is treated as a device name\n"
c82f047c 251"or, for --examine-bitmap, a file name.\n"
e0d19036 252"The first such name is often the name of an md device. Subsequent\n"
e5a5d81e 253"names are often names of component devices.\n"
52826846 254"\n"
e0d19036 255"Some common options are:\n"
56eedc1a 256" --help -h : General help message or, after above option,\n"
64c4757e 257" mode specific help message\n"
56eedc1a 258" --help-options : This help message\n"
9a9dab36 259" --version -V : Print version information for mdadm\n"
64c4757e 260" --verbose -v : Be more verbose about what is happening\n"
dab6685f 261" --quiet -q : Don't print un-necessary messages\n"
e0d19036 262" --brief -b : Be less verbose, more brief\n"
e50cf220
MN
263" --export -Y : With --detail, --detail-platform or --examine use\n"
264" key=value format for easy import into environment\n"
e0d19036
NB
265" --force -f : Override normal checks and be more forceful\n"
266"\n"
267" --assemble -A : Assemble an array\n"
e5a5d81e 268" --build -B : Build an array without metadata\n"
e0d19036
NB
269" --create -C : Create a new array\n"
270" --detail -D : Display details of an array\n"
5787fa49 271" --examine -E : Examine superblock on an array component\n"
c82f047c 272" --examine-bitmap -X: Display the detail of a bitmap file\n"
6d388a88 273" --examine-badblocks: Display list of known bad blocks on device\n"
e0d19036 274" --monitor -F : monitor (follow) some arrays\n"
8382f19b 275" --grow -G : resize/ reshape and array\n"
29ba4804 276" --incremental -I : add/remove a single device to/from an array as appropriate\n"
e0d19036
NB
277" --query -Q : Display general information about how a\n"
278" device relates to the md driver\n"
1f48664b 279" --auto-detect : Start arrays auto-detected by the kernel\n"
e0d19036
NB
280;
281/*
64c4757e
NB
282"\n"
283" For create or build:\n"
c82f047c 284" --bitmap= -b : File to store bitmap in - may pre-exist for --build\n"
64c4757e 285" --chunk= -c : chunk size of kibibytes\n"
5787fa49 286" --rounding= : rounding factor for linear array (==chunk size)\n"
58380584
N
287" --level= -l : raid level: 0,1,4,5,6,10,linear, or mp for create.\n"
288" : 0,1,10,mp,faulty or linear for build.\n"
98c6faba 289" --parity= -p : raid5/6 parity algorithm: {left,right}-{,a}symmetric\n"
58380584 290" --layout= : same as --parity, for RAID10: [fno]NN \n"
b83d95f3 291" --raid-devices= -n : number of active devices in array\n"
58380584 292" --spare-devices= -x: number of spare (eXtra) devices in initial array\n"
e5329c37 293" --size= -z : Size (in K) of each drive in RAID1/4/5/6/10 - optional\n"
52826846
NB
294" --force -f : Honour devices as listed on command line. Don't\n"
295" : insert a missing drive for RAID5.\n"
58380584 296" --assume-clean : Assume the array is already in-sync. This is dangerous for RAID5.\n"
c82f047c
NB
297" --bitmap-chunk= : chunksize of bitmap in bitmap file (Kilobytes)\n"
298" --delay= -d : seconds between bitmap updates\n"
dfd4d8ee 299" --write-behind= : number of simultaneous write-behind requests to allow (requires bitmap)\n"
947fd4dd 300" --name= -N : Textual name for array - max 32 characters\n"
64c4757e
NB
301"\n"
302" For assemble:\n"
c82f047c 303" --bitmap= -b : File to find bitmap information in\n"
64c4757e
NB
304" --uuid= -u : uuid of array to assemble. Devices which don't\n"
305" have this uuid are excluded\n"
52826846
NB
306" --super-minor= -m : minor number to look for in super-block when\n"
307" choosing devices to use.\n"
947fd4dd 308" --name= -N : Array name to look for in super-block.\n"
64c4757e
NB
309" --config= -c : config file\n"
310" --scan -s : scan config file for missing information\n"
311" --force -f : Assemble the array even if some superblocks appear out-of-date\n"
cbfbcb0b 312" --update= -U : Update superblock: try '-A --update=?' for list of options.\n"
b8a8ccf9 313" --no-degraded : Do not start any degraded arrays - default unless --scan.\n"
64c4757e 314"\n"
cd29a5c8
NB
315" For detail or examine:\n"
316" --brief -b : Just print device name and UUID\n"
317"\n"
52826846
NB
318" For follow/monitor:\n"
319" --mail= -m : Address to mail alerts of failure to\n"
320" --program= -p : Program to run when an event is detected\n"
321" --alert= : same as --program\n"
322" --delay= -d : seconds of delay between polling state. default=60\n"
323"\n"
64c4757e
NB
324" General management:\n"
325" --add -a : add, or hotadd subsequent devices\n"
58380584 326" --re-add : re-add a recently removed device\n"
64c4757e 327" --remove -r : remove subsequent devices\n"
58380584 328" --fail -f : mark subsequent devices as faulty\n"
64c4757e 329" --set-faulty : same as --fail\n"
70c55e36 330" --replace : mark a device for replacement\n"
64c4757e 331" --run -R : start a partially built array\n"
5787fa49 332" --stop -S : deactivate array, releasing all resources\n"
64c4757e
NB
333" --readonly -o : mark array as readonly\n"
334" --readwrite -w : mark array as readwrite\n"
9a9dab36 335" --zero-superblock : erase the MD superblock from a device.\n"
b90c0e9a 336" --wait -W : wait for recovery/resync/reshape to finish.\n"
64c4757e 337;
e0d19036 338*/
64c4757e
NB
339
340char Help_create[] =
b83d95f3 341"Usage: mdadm --create device -chunk=X --level=Y --raid-devices=Z devices\n"
64c4757e 342"\n"
aa88f531
NB
343" This usage will initialise a new md array, associate some\n"
344" devices with it, and activate the array. In order to create an\n"
345" array with some devices missing, use the special word 'missing' in\n"
346" place of the relevant device name.\n"
64c4757e 347"\n"
aa88f531 348" Before devices are added, they are checked to see if they already contain\n"
e0d19036 349" raid superblocks or filesystems. They are also checked to see if\n"
64c4757e 350" the variance in device size exceeds 1%.\n"
aa88f531
NB
351" If any discrepancy is found, the user will be prompted for confirmation\n"
352" before the array is created. The presence of a '--run' can override this\n"
64c4757e
NB
353" caution.\n"
354"\n"
e0d19036
NB
355" If the --size option is given then only that many kilobytes of each\n"
356" device is used, no matter how big each device is.\n"
682c7051 357" If no --size is given, the apparent size of the smallest drive given\n"
e0d19036
NB
358" is used for raid level 1 and greater, and the full device is used for\n"
359" other levels.\n"
682c7051 360"\n"
e0d19036 361" Options that are valid with --create (-C) are:\n"
c82f047c 362" --bitmap= : Create a bitmap for the array with the given filename\n"
58380584
N
363" : or an internal bitmap is 'internal' is given\n"
364" --chunk= -c : chunk size in kibibytes\n"
5787fa49 365" --rounding= : rounding factor for linear array (==chunk size)\n"
58380584 366" --level= -l : raid level: 0,1,4,5,6,10,linear,multipath and synonyms\n"
98c6faba 367" --parity= -p : raid5/6 parity algorithm: {left,right}-{,a}symmetric\n"
58380584 368" --layout= : same as --parity, for RAID10: [fno]NN \n"
b83d95f3 369" --raid-devices= -n : number of active devices in array\n"
58380584 370" --spare-devices= -x: number of spare (eXtra) devices in initial array\n"
e5329c37 371" --size= -z : Size (in K) of each drive in RAID1/4/5/6/10 - optional\n"
40c9a66a
N
372" --data-offset= : Space to leave between start of device and start\n"
373" : of array data.\n"
e0d19036
NB
374" --force -f : Honour devices as listed on command line. Don't\n"
375" : insert a missing drive for RAID5.\n"
aa88f531 376" --run -R : insist of running the array even if not all\n"
e0d19036 377" : devices are present or some look odd.\n"
aa88f531 378" --readonly -o : start the array readonly - not supported yet.\n"
947fd4dd 379" --name= -N : Textual name for array - max 32 characters\n"
c82f047c
NB
380" --bitmap-chunk= : bitmap chunksize in Kilobytes.\n"
381" --delay= -d : bitmap update delay in seconds.\n"
28d74446 382" --write-journal= : Specify journal device for RAID-4/5/6 array\n"
64c4757e
NB
383"\n"
384;
385
386char Help_build[] =
b83d95f3 387"Usage: mdadm --build device -chunk=X --level=Y --raid-devices=Z devices\n"
64c4757e
NB
388"\n"
389" This usage is similar to --create. The difference is that it creates\n"
e0d19036 390" a legacy array without a superblock. With these arrays there is no\n"
64c4757e
NB
391" different between initially creating the array and subsequently\n"
392" assembling the array, except that hopefully there is useful data\n"
393" there in the second case.\n"
394"\n"
58380584 395" The level may only be 0, 1, 10, linear, multipath, or faulty.\n"
64c4757e 396" All devices must be listed and the array will be started once complete.\n"
e0d19036 397" Options that are valid with --build (-B) are:\n"
c82f047c 398" --bitmap= : file to store/find bitmap information in.\n"
e0d19036 399" --chunk= -c : chunk size of kibibytes\n"
5787fa49 400" --rounding= : rounding factor for linear array (==chunk size)\n"
58380584 401" --level= -l : 0, 1, 10, linear, multipath, faulty\n"
c82f047c
NB
402" --raid-devices= -n : number of active devices in array\n"
403" --bitmap-chunk= : bitmap chunksize in Kilobytes.\n"
404" --delay= -d : bitmap update delay in seconds.\n"
64c4757e
NB
405;
406
407char Help_assemble[] =
9a9dab36
NB
408"Usage: mdadm --assemble device options...\n"
409" mdadm --assemble --scan options...\n"
64c4757e
NB
410"\n"
411"This usage assembles one or more raid arrays from pre-existing\n"
412"components.\n"
e0d19036 413"For each array, mdadm needs to know the md device, the identity of\n"
52826846
NB
414"the array, and a number of sub devices. These can be found in a number\n"
415"of ways.\n"
416"\n"
58380584
N
417"The md device is given on the command line, is found listed in the\n"
418"config file, or can be deduced from the array identity.\n"
419"The array identity is determined either from the --uuid, --name, or\n"
420"--super-minor commandline arguments, from the config file,\n"
52826846 421"or from the first component device on the command line.\n"
64c4757e 422"\n"
52826846
NB
423"The different combinations of these are as follows:\n"
424" If the --scan option is not given, then only devices and identities\n"
425" listed on the command line are considered.\n"
e0d19036 426" The first device will be the array device, and the remainder will be\n"
52826846
NB
427" examined when looking for components.\n"
428" If an explicit identity is given with --uuid or --super-minor, then\n"
e0d19036 429" only devices with a superblock which matches that identity is considered,\n"
52826846 430" otherwise every device listed is considered.\n"
64c4757e 431"\n"
52826846
NB
432" If the --scan option is given, and no devices are listed, then\n"
433" every array listed in the config file is considered for assembly.\n"
e0d19036 434" The identity of candidate devices are determined from the config file.\n"
58380584
N
435" After these arrays are assembled, mdadm will look for other devices\n"
436" that could form further arrays and tries to assemble them. This can\n"
437" be disabled using the 'AUTO' option in the config file.\n"
64c4757e 438"\n"
52826846
NB
439" If the --scan option is given as well as one or more devices, then\n"
440" Those devices are md devices that are to be assembled. Their identity\n"
441" and components are determined from the config file.\n"
64c4757e 442"\n"
b8a8ccf9
NB
443" If mdadm can not find all of the components for an array, it will assemble\n"
444" it but not activate it unless --run or --scan is given. To preserve this\n"
445" behaviour even with --scan, add --no-degraded. Note that \"all of the\n"
446" components\" means as many as were present the last time the array was running\n"
447" as recorded in the superblock. If the array was already degraded, and\n"
448" the missing device is not a new problem, it will still be assembled. It\n"
449" is only newly missing devices that cause the array not to be started.\n"
450"\n"
e0d19036 451"Options that are valid with --assemble (-A) are:\n"
58380584 452" --bitmap= : bitmap file to use with the array\n"
e0d19036
NB
453" --uuid= -u : uuid of array to assemble. Devices which don't\n"
454" have this uuid are excluded\n"
455" --super-minor= -m : minor number to look for in super-block when\n"
456" choosing devices to use.\n"
947fd4dd 457" --name= -N : Array name to look for in super-block.\n"
e0d19036
NB
458" --config= -c : config file\n"
459" --scan -s : scan config file for missing information\n"
460" --run -R : Try to start the array even if not enough devices\n"
461" for a full array are present\n"
462" --force -f : Assemble the array even if some superblocks appear\n"
463" : out-of-date. This involves modifying the superblocks.\n"
cbfbcb0b 464" --update= -U : Update superblock: try '-A --update=?' for option list.\n"
b8a8ccf9 465" --no-degraded : Assemble but do not start degraded arrays.\n"
0ea8f5b1 466" --readonly -o : Mark the array as read-only. No resync will start.\n"
e0d19036
NB
467;
468
469char Help_manage[] =
470"Usage: mdadm arraydevice options component devices...\n"
471"\n"
472"This usage is for managing the component devices within an array.\n"
473"The --manage option is not needed and is assumed if the first argument\n"
474"is a device name or a management option.\n"
58380584 475"The first device listed will be taken to be an md array device, any\n"
e0d19036
NB
476"subsequent devices are (potential) components of that array.\n"
477"\n"
478"Options that are valid with management mode are:\n"
479" --add -a : hotadd subsequent devices to the array\n"
58380584
N
480" --re-add : subsequent devices are re-added if there were\n"
481" : recent members of the array\n"
e0d19036
NB
482" --remove -r : remove subsequent devices, which must not be active\n"
483" --fail -f : mark subsequent devices a faulty\n"
484" --set-faulty : same as --fail\n"
70c55e36
N
485" --replace : mark device(s) to be replaced by spares. Once\n"
486" : replacement completes, device will be marked faulty\n"
487" --with : Indicate which spare a previous '--replace' should\n"
488" : prefer to use\n"
e0d19036 489" --run -R : start a partially built array\n"
5787fa49 490" --stop -S : deactivate array, releasing all resources\n"
e0d19036
NB
491" --readonly -o : mark array as readonly\n"
492" --readwrite -w : mark array as readwrite\n"
493;
494
495char Help_misc[] =
496"Usage: mdadm misc_option devices...\n"
497"\n"
498"This usage is for performing some task on one or more devices, which\n"
499"may be arrays or components, depending on the task.\n"
500"The --misc option is not needed (though it is allowed) and is assumed\n"
501"if the first argument in a misc option.\n"
502"\n"
503"Options that are valid with the miscellaneous mode are:\n"
504" --query -Q : Display general information about how a\n"
505" device relates to the md driver\n"
506" --detail -D : Display details of an array\n"
4cce4069 507" --detail-platform : Display hardware/firmware details\n"
5787fa49 508" --examine -E : Examine superblock on an array component\n"
c82f047c 509" --examine-bitmap -X: Display contents of a bitmap file\n"
6d388a88 510" --examine-badblocks: Display list of known bad blocks on device\n"
e0d19036
NB
511" --zero-superblock : erase the MD superblock from a device.\n"
512" --run -R : start a partially built array\n"
5787fa49 513" --stop -S : deactivate array, releasing all resources\n"
e0d19036
NB
514" --readonly -o : mark array as readonly\n"
515" --readwrite -w : mark array as readwrite\n"
feb716e9 516" --test -t : exit status 0 if ok, 1 if degrade, 2 if dead, 4 if missing\n"
b90c0e9a 517" --wait -W : wait for resync/rebuild/recovery to finish\n"
a740cf64 518" --action= : initiate or abort ('idle' or 'frozen') a 'check' or 'repair'.\n"
e0d19036
NB
519;
520
521char Help_monitor[] =
522"Usage: mdadm --monitor options devices\n"
523"\n"
524"This usage causes mdadm to monitor a number of md arrays by periodically\n"
525"polling their status and acting on any changes.\n"
526"If any devices are listed then those devices are monitored, otherwise\n"
527"all devices listed in the config file are monitored.\n"
528"The address for mailing advisories to, and the program to handle\n"
529"each change can be specified in the config file or on the command line.\n"
58380584
N
530"There must be at least one destination for advisories, whether\n"
531"an email address, a program, or --syslog\n"
e0d19036 532"\n"
dd0781e5 533"Options that are valid with the monitor (-F --follow) mode are:\n"
e0d19036
NB
534" --mail= -m : Address to mail alerts of failure to\n"
535" --program= -p : Program to run when an event is detected\n"
536" --alert= : same as --program\n"
237d8790 537" --syslog -y : Report alerts via syslog\n"
9a36a9b7 538" --increment= -r : Report RebuildNN events in the given increment. default=20\n"
e0d19036
NB
539" --delay= -d : seconds of delay between polling state. default=60\n"
540" --config= -c : specify a different config file\n"
541" --scan -s : find mail-address/program in config file\n"
d013a55e 542" --daemonise -f : Fork and continue in child, parent exits\n"
b5e64645 543" --pid-file= -i : In daemon mode write pid to specified file instead of stdout\n"
aa88f531 544" --oneshot -1 : Check for degraded arrays, then exit\n"
98c6faba 545" --test -t : Generate a TestMessage event against each array at startup\n"
e0d19036
NB
546;
547
dd0781e5
NB
548char Help_grow[] =
549"Usage: mdadm --grow device options\n"
550"\n"
551"This usage causes mdadm to attempt to reconfigure a running array.\n"
552"This is only possibly if the kernel being used supports a particular\n"
58380584 553"reconfiguration.\n"
dd0781e5 554"\n"
891d2994 555"Options that are valid with the grow (-G --grow) mode are:\n"
58380584 556" --level= -l : Tell mdadm what level to convert the array to.\n"
00be0b12 557" --layout= -p : For a FAULTY array, set/change the error mode.\n"
58380584 558" : for other arrays, update the layout\n"
dd0781e5
NB
559" --size= -z : Change the active size of devices in an array.\n"
560" : This is useful if all devices have been replaced\n"
0083584d
N
561" : with larger devices. Value is in Kilobytes, or\n"
562" : the special word 'max' meaning 'as large as possible'.\n"
58380584
N
563" --assume-clean : When increasing the --size, this flag will avoid\n"
564" : a resync of the new space\n"
565" --chunk= -c : Change the chunksize of the array\n"
e5669f40 566" --raid-devices= -n : Change the number of active devices in an array.\n"
58380584
N
567" --add= -a : Add listed devices as part of reshape. This is\n"
568" : needed for resizing a RAID0 which cannot have\n"
569" : spares already present.\n"
00be0b12 570" --bitmap= -b : Add or remove a write-intent bitmap.\n"
58380584 571" --backup-file= file : A file on a different device to store data for a\n"
e5669f40 572" : short time while increasing raid-devices on a\n"
58380584
N
573" : RAID4/5/6 array. Also needed throughout a reshape\n"
574" : when changing parameters other than raid-devices\n"
84e11361
N
575" --array-size= -Z : Change visible size of array. This does not change\n"
576" : any data on the device, and is not stable across restarts.\n"
40c9a66a 577" --data-offset= : Location on device to move start of data to.\n"
dd0781e5 578;
e0d19036 579
8382f19b 580char Help_incr[] =
29ba4804 581"Usage: mdadm --incremental [-Rqrsf] device\n"
8382f19b
NB
582"\n"
583"This usage allows for incremental assembly of md arrays. Devices can be\n"
584"added one at a time as they are discovered. Once an array has all expected\n"
585"devices, it will be started.\n"
586"\n"
29ba4804
N
587"Optionally, the process can be reversed by using the fail option.\n"
588"When fail mode is invoked, mdadm will see if the device belongs to an array\n"
589"and then both fail (if needed) and remove the device from that array.\n"
590"\n"
591"Options that are valid with incremental assembly (-I --incremental) are:\n"
592" --run -R : Run arrays as soon as a minimal number of devices are\n"
7e6140e6
N
593" : present rather than waiting for all expected.\n"
594" --quiet -q : Don't print any information messages, just errors.\n"
595" --rebuild-map -r : Rebuild the 'map' file that mdadm uses for tracking\n"
596" : partial arrays.\n"
597" --scan -s : Use with -R to start any arrays that have the minimal\n"
598" : required number of devices, but are not yet started.\n"
58380584
N
599" --fail -f : First fail (if needed) and then remove device from\n"
600" : any array that it is a member of.\n"
8382f19b 601;
e0d19036
NB
602
603char Help_config[] =
604"The /etc/mdadm.conf config file:\n\n"
605" The config file contains, apart from blank lines and comment lines that\n"
58380584
N
606" start with a hash(#), array lines, device lines, and various\n"
607" configuration lines.\n"
608" Each line is constructed of a number of space separated words, and can\n"
609" be continued on subsequent physical lines by indenting those lines.\n"
e0d19036
NB
610"\n"
611" A device line starts with the word 'device' and then has a number of words\n"
612" which identify devices. These words should be names of devices in the\n"
613" filesystem, and can contain wildcards. There can be multiple words or each\n"
614" device line, and multiple device lines. All devices so listed are checked\n"
615" for relevant super blocks when assembling arrays.\n"
616"\n"
617" An array line start with the word 'array'. This is followed by the name of\n"
618" the array device in the filesystem, e.g. '/dev/md2'. Subsequent words\n"
619" describe the identity of the array, used to recognise devices to include in the\n"
620" array. The identity can be given as a UUID with a word starting 'uuid=', or\n"
621" as a minor-number stored in the superblock using 'super-minor=', or as a list\n"
622" of devices. This is given as a comma separated list of names, possibly\n"
5787fa49 623" containing wildcards, preceded by 'devices='. If multiple critea are given,\n"
e0d19036
NB
624" than a device must match all of them to be considered.\n"
625"\n"
58380584
N
626" Other configuration lines include:\n"
627" mailaddr, mailfrom, program used for --monitor mode\n"
628" create, auto used when creating device names in /dev\n"
629" homehost, policy, part-policy used to guide policy in various\n"
630" situations\n"
64c4757e
NB
631"\n"
632;
682c7051 633
5187a385
N
634char *mode_help[mode_count] = {
635 [0] = Help,
636 [ASSEMBLE] = Help_assemble,
637 [BUILD] = Help_build,
638 [CREATE] = Help_create,
639 [MANAGE] = Help_manage,
640 [MISC] = Help_misc,
641 [MONITOR] = Help_monitor,
642 [GROW] = Help_grow,
643 [INCREMENTAL] = Help_incr,
644};