Re: mdadm 2.1: command line option parsing bug?
I found myself typing IMHO after writing up just about each comment. I've dropped that and you'll just have to know that all this is IMHO and not an attack on your ways if they happen to be different ^_^. Neil Brown wrote: I like the suggestion of adding one-line descriptions to this. How about: I'll first comment each command/description (general feedback later): Usage: mdadm --create device options... Create a new array from unused devices. mdadm --assemble device options... reassemble a previously created array I like 'em! mdadm --build device options... create or assemble an array without metadata Oh, that's what it's for, operating without metadata. Good to know. It would help a lot (for me) if the above also had a brief note about why I would ever want to use --build. Otherwise I'll just be confused about when I should use assemble and when I should use build and why it even exists. What's the logic behind having split create/assemble commands but a joined command for creating/assembling when there's no metadata? (I'm sure there is one, I'm just confused as always.) mdadm --manage device options... Make changes to an active array Nice. mdadm --misc options... devices report information or perform miscellaneous tasks. Get rid of the misc section or rename it to something meaningful.. mdadm --monitor options... monitor one or more arrays and report any changes in status Nice. mdadm device options... same as --manage Oh, so that's what it does. A bit confusing for a newbie like me that we're not sticking to _1_ syntax. Since the above is a side note about a convenient syntax hack, I think that (in the event that you find that it is not confusing [which I do :-] and decide to keep it), there should be at least a blank line between the very important --cmd descriptions and this rarely relevant note. General stuff: The note: * use --help in combination with --cmd for further help is missing. I think it would be good to retain it. I find it very unhelpful to have a --misc section. Every time I'm looking for some command, besides from having to guess in which section it's located, I have to check --misc also, since misc can cover anything. Yes, I can see how that is confusing. The difference between 'manage' and 'misc' is that manage will only apply to a single array, while misc can apply to multiple arrays. This is really a distinction that is mostly relevant in the implementation. I should try to hide it in the documentation. That would be good :-). Renaming --misc to something which relates to the fact that this is about multi md device commands and giving it an appropriate description line (I don't think your --misc description was any good, sorry, hehe) would also be *a lot* better.. And btw, why mention device and options for each and every section/command set/command when it's obvious that you need more parameters to do something fruitful? In my opinion it would be better to rid the general --help screen of them and instead specify in brief what functionality the sections are meant to cover. well. it is device options for all but misc, which has options ... devices... Yes, okay, I think that would be explained better by a description line for misc saying that it's about multiple devices (by the way, are we talking multiple MD or multiple component devices?) but I agree that it is probably unnecessary repetition. Also completely useless since there's no mention of what any of the options /are/, no? Just adds to confusion, so better to snip it. I keep typing mdadm --help --assemble which unfortunately gets me nowhere. A lot of the times it's because the general help text has scrolled out of view because I've just done an '--xxx --help' for some other command. Maybe it's just me, but a minor improvement could be to allow '--help --xxx'. That's a fair comment. I currently print the help message as soon as I see the --help option. But that could change to: if I see '--help', set a flag, then for every option, print the appropriate help. That would be really swell! Then mdadm --help --size could even give something useful... Yup :-). Hmm. Not bad at all. Would be good for the extreme newbie and confused ppl like me ;). ... snip ... For general help on options use mdadm --help-options ... snip ... Like misc, I think this is an odd section. Let's explore it's contents: $ mdadm --help-options Any parameter that does not start with '-' is treated as a device name ... snip ... To me, the above is very interesting information about mdadm's syntax and thus should be presented at the start of the general --help screen. ... snip ... The first such name is often the name of an md device. Subsequent names are
Re: mdadm 2.1: command line option parsing bug?
mdadm's command line arguments seem arcane and cryptic and unintuitive. It's difficult to grasp what combinations will actually do something worthwhile and what combinations will just yield a 'you cannot do that' output. I find myself spending 20 minutes with mdadm --help and experimenting with different commands (which shouldn't be the case when doing RAID stuff) just to do simple things like create an array or make MD assemble the devices that compose an array. Thanks strange. They seem very regular and intuitive to me (but I find it very hard to be objective). Maybe you have a mental model of what the task involves that differs from how md actually does things. Can you say anything more about the sort of mistakes you find yourself making. That might help either improve the help pages or the error messages (revamping all the diagnostic messages to make the more helpful is slowly climbing to the top of my todo list). I can, but I suck at putting these things down in writing, which is why my initial description was intentionally vague and shallow :-). Now, I'll try anyway. It'll be imprecise and I'll miss some things and show up late with major points etc., but at least I will have tried =). Ok.. Starting with the usage output: $ mdadm Usage: mdadm --help for help Nothing wrong with that. Good, concise stuff. Great. The --help output, however...: $ mdadm --help Usage: mdadm --create device options... mdadm --assemble device options... mdadm --build device options... ... snip ... ... I find confusing. Try and read the words create, assemble and build as an outsider or a child would read them, as regular english words, not with MD development in mind. All three words mean just about the same thing in plain english (something like taking smaller parts and constructing something bigger with them or some such). That confuses me. To make things worse, I now have to type in 3 commands (--help --cmd) and compare the output of each just to get a grasp on what each of the 3 individual commands do. The proces is laborious. Well, I'll live, but it's annoying to have to scroll up and down perhaps 5-6 screens of text whilst comparing options just to figure out which command I would like to use. I would much prefer if the 'areas of utility' that mdadm commands are divided in were self explanatory. I'm not saying that these 'areas of utility' (--create etc.) are not grouped in a logical fashion. Just that it's not always easy to comprehend what they cover. Perhaps it's enough just to add a small description per line of 'mdadm --help' output. After 'mdadm --create' it would fx. say 'creates a new RAID array based on multiple devices.' or so. Just a one-liner. Moving right along: ... snip ... mdadm --manage device options... mdadm --misc options... devices mdadm --monitor options... ... snip ... I find it very unhelpful to have a --misc section. Every time I'm looking for some command, besides from having to guess in which section it's located, I have to check --misc also, since misc can cover anything. ... snip ... mdadm device options... ... snip ... Where does that syntax suddenly come from? Is it a special no-command mode? What does it do? Hmm. Confusing. And btw, why mention device and options for each and every section/command set/command when it's obvious that you need more parameters to do something fruitful? In my opinion it would be better to rid the general --help screen of them and instead specify in brief what functionality the sections are meant to cover. ... snip ... mdadm is used for building, managing, and monitoring Linux md devices (aka RAID arrays) ... snip ... Probably belongs in the top of the output, but that's a small nit... ... snip ... For detailed help on the above major modes use --help after the mode e.g. mdadm --assemble --help ... snip ... I keep typing mdadm --help --assemble which unfortunately gets me nowhere. A lot of the times it's because the general help text has scrolled out of view because I've just done an '--xxx --help' for some other command. Maybe it's just me, but a minor improvement could be to allow '--help --xxx'. ... snip ... For general help on options use mdadm --help-options ... snip ... Like misc, I think this is an odd section. Let's explore it's contents: $ mdadm --help-options Any parameter that does not start with '-' is treated as a device name ... snip ... To me, the above is very interesting information about mdadm's syntax and thus should be presented at the start of the general --help screen. ... snip ... The first such name is often the name of an md device. Subsequent names are often names of component devices. ... snip ... This too. What's with the often btw? It is somewhat more helpful to me if
Re: mdadm 2.1: command line option parsing bug?
On Thursday December 15, [EMAIL PROTECTED] wrote: I can, but I suck at putting these things down in writing, which is why my initial description was intentionally vague and shallow :-). Now, I'll try anyway. It'll be imprecise and I'll miss some things and show up late with major points etc., but at least I will have tried =). Thanks for trying. Ok.. Starting with the usage output: $ mdadm Usage: mdadm --help for help Nothing wrong with that. Good, concise stuff. Great. The --help output, however...: $ mdadm --help Usage: mdadm --create device options... mdadm --assemble device options... mdadm --build device options... ... snip ... ... I find confusing. I like the suggestion of adding one-line descriptions to this. How about: Usage: mdadm --create device options... Create a new array from unused devices. mdadm --assemble device options... reassemble a previously created array mdadm --build device options... create or assemble an array without metadata mdadm --manage device options... Make changes to an active array mdadm --misc options... devices report information or perform miscellaneous tasks. mdadm --monitor options... monitor one or more arrays and report any changes in status mdadm device options... same as --manage Moving right along: ... snip ... mdadm --manage device options... mdadm --misc options... devices mdadm --monitor options... ... snip ... I find it very unhelpful to have a --misc section. Every time I'm looking for some command, besides from having to guess in which section it's located, I have to check --misc also, since misc can cover anything. Yes, I can see how that is confusing. The difference between 'manage' and 'misc' is that manage will only apply to a single array, while misc can apply to multiple arrays. This is really a distinction that is mostly relevant in the implementation. I should try to hide it in the documentation. ... snip ... mdadm device options... ... snip ... Where does that syntax suddenly come from? Is it a special no-command mode? What does it do? Hmm. Confusing. And btw, why mention device and options for each and every section/command set/command when it's obvious that you need more parameters to do something fruitful? In my opinion it would be better to rid the general --help screen of them and instead specify in brief what functionality the sections are meant to cover. well. it is device options for all but misc, which has options ... devices... but I agree that it is probably unnecessary repetition. I keep typing mdadm --help --assemble which unfortunately gets me nowhere. A lot of the times it's because the general help text has scrolled out of view because I've just done an '--xxx --help' for some other command. Maybe it's just me, but a minor improvement could be to allow '--help --xxx'. That's a fair comment. I currently print the help message as soon as I see the --help option. But that could change to: if I see '--help', set a flag, then for every option, print the appropriate help. Then mdadm --help --size could even give something useful... ... snip ... For general help on options use mdadm --help-options ... snip ... Like misc, I think this is an odd section. Let's explore it's contents: $ mdadm --help-options Any parameter that does not start with '-' is treated as a device name ... snip ... To me, the above is very interesting information about mdadm's syntax and thus should be presented at the start of the general --help screen. ... snip ... The first such name is often the name of an md device. Subsequent names are often names of component devices. ... snip ... This too. What's with the often btw? mdadm --examine /dev/md1 /dev/md2 /dev/md3 subsequent names are names of other md devices, not component devices. It is somewhat more helpful to me if parameters is an exact science. Eg. the above could say, for commands affecting whole arrays, the first device name is the name of the MD device while subsequent device names refer to component devices. Or preferably something a little more concise. ... snip ... Some common options are: --help-h : General help message or, after above option, mode specific help message --help-options : This help message ... snip ... Those are not interesting at all, we've already used those to get here. And both are mentioned in the general --help screen. Snip 'em if you ask me. Fair comment. They are there for completeness, but not really needed. Next on the agenda, I find the messages that I get from mdadm when I make syntactic blunders confusing.
Re: mdadm 2.1: command line option parsing bug?
On Tuesday November 22, [EMAIL PROTECTED] wrote: Neil Brown wrote: [] I would like it to take an argument in contexts where --bitmap was meaningful (Create, Assemble, Grow) and not where --brief is meaningful (Examine, Detail). but I don't know if getopt_long will allow the 'short_opt' string to be changed half way through processing... getopt allows you to change both long and short options set before every call (provided argvargc are intact). But. Please, pretty please, don't implement the same options with different meaning. It's confusing at best. Assign short options to frequently-used commands, and leave only long options for the rest. I dunno whichever of --brief or --bitmap is more frequent, I'd say both can be long-only, but since -b already stands for --brief, don't use it for --bitmap. At the very least, I can print a message if '-b' is being interpreted as as --brief, but the option argument is present. -a has the same problem (--add vs --auto). And this is also bad. In my opinion anyway. I'm afraid it is a bit late... -f == --force or --fail or --daemonise (think 'fork') -m == --super-minor --mail -p == --parity or --program -c == --config or --chunk Think of mdadm as a number of separate program (A, B, C, D, E, G :-) Each has an independent, though sometimes overlapping, set of options. It looks like I can get getopt_long to work quite nicely to e.g. '-b' taking an arg in some contexts, and not in others. so expect that to be fixed in 2.2. NeilBrown - To unsubscribe from this list: send the line unsubscribe linux-raid in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: mdadm 2.1: command line option parsing bug?
On Tuesday November 22, [EMAIL PROTECTED] wrote: Neil Brown wrote: I would like it to take an argument in contexts where --bitmap was meaningful (Create, Assemble, Grow) and not where --brief is meaningful (Examine, Detail). but I don't know if getopt_long will allow the 'short_opt' string to be changed half way through processing... Here's an honest opinion from a regular user. Honest is always nice! mdadm's command line arguments seem arcane and cryptic and unintuitive. It's difficult to grasp what combinations will actually do something worthwhile and what combinations will just yield a 'you cannot do that' output. I find myself spending 20 minutes with mdadm --help and experimenting with different commands (which shouldn't be the case when doing RAID stuff) just to do simple things like create an array or make MD assemble the devices that compose an array. Thanks strange. They seem very regular and intuitive to me (but I find it very hard to be objective). Maybe you have a mental model of what the task involves that differs from how md actually does things. To create an array, you need: the array to create, the list of devices to hold the data the level the number of devices (consistency check) and maybe some other parameters like chunksize or parity mode. So that is what you give 'mdadm --create' Providing you give the array to be created first, the rest can come in any order. mdadm --create /dev/md0 /dev/sda /dev/sdb --level=5 --raid-disks=3 /dev/sdc Can you say anything more about the sort of mistakes you find yourself making. That might help either improve the help pages or the error messages (revamping all the diagnostic messages to make the more helpful is slowly climbing to the top of my todo list). I know. Not very constructive, but a POV anyway. Maybe I just do not use MD enough, and so I shouldn't complain, because the interface is really not designed for the absolute newbie. If so, then I apologize. I don't have any constructive suggestions, except to say that the way the classic Cisco interface does things works very nicely. A lot of other manufacturers has also started doing things the Cisco way. If you don't have a Cisco router available, you can fx. use a Windows XP box. Type 'netsh' in a command prompt, then 'help'. Or alternatively 'netsh help'. You get the idea :-). Is this and interactive interface where you have hit 'tab' at anytime and it either completes the current word, or lists options? (For me, that is the 'kermit' interface, as kermit was the first program I used which had it). This is certainly a nice interface when learning a system, but I don't think it belongs in a tool like mdadm. Rather it might make sense to create an 'mdassist' tool which works like this and build mdadm commands for you... NeilBrown - To unsubscribe from this list: send the line unsubscribe linux-raid in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: mdadm 2.1: command line option parsing bug?
On Thu, Nov 24, 2005 at 04:25:01PM +1100, Neil Brown wrote: Can you say anything more about the sort of mistakes you find yourself making. That might help either improve the help pages or the error messages (revamping all the diagnostic messages to make the more helpful is slowly climbing to the top of my todo list). I've been using mdadm from the very beginning, but the one thing I still don't have a great handle on is the difference between querying devices vs. arrays, and when to query what to find out what I want to know. Partly, I'm not familiar with it because it's not like I run mdadm everyday. It's the kind of thing that's run once, configured once, put into a script somewhere and then forgotten about. A lot of other manufacturers has also started doing things the Cisco way. If you don't have a Cisco router available, you can fx. use a Windows XP box. Type 'netsh' in a command prompt, then 'help'. Or alternatively 'netsh help'. You get the idea :-). Is this and interactive interface where you have hit 'tab' at anytime and it either completes the current word, or lists options? (For me, that is the 'kermit' interface, as kermit was the first program I used which had it). I'd have to vote with Neil on this. mdadm is going to be used in lots of scripts. System startup/shutdown scripts especially. It's current form is awesome for that. Throw the right args together and you can do anything. As soon as it's interative, we might as well use a mouse... ::-P -- Ross Vandegrift [EMAIL PROTECTED] The good Christian should beware of mathematicians, and all those who make empty prophecies. The danger already exists that the mathematicians have made a covenant with the devil to darken the spirit and to confine man in the bonds of Hell. --St. Augustine, De Genesi ad Litteram, Book II, xviii, 37 - To unsubscribe from this list: send the line unsubscribe linux-raid in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: mdadm 2.1: command line option parsing bug?
Neil Brown wrote: [] I would like it to take an argument in contexts where --bitmap was meaningful (Create, Assemble, Grow) and not where --brief is meaningful (Examine, Detail). but I don't know if getopt_long will allow the 'short_opt' string to be changed half way through processing... getopt allows you to change both long and short options set before every call (provided argvargc are intact). But. Please, pretty please, don't implement the same options with different meaning. It's confusing at best. Assign short options to frequently-used commands, and leave only long options for the rest. I dunno whichever of --brief or --bitmap is more frequent, I'd say both can be long-only, but since -b already stands for --brief, don't use it for --bitmap. At the very least, I can print a message if '-b' is being interpreted as as --brief, but the option argument is present. -a has the same problem (--add vs --auto). And this is also bad. In my opinion anyway. /mjt - To unsubscribe from this list: send the line unsubscribe linux-raid in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: mdadm 2.1: command line option parsing bug?
Neil Brown wrote: I would like it to take an argument in contexts where --bitmap was meaningful (Create, Assemble, Grow) and not where --brief is meaningful (Examine, Detail). but I don't know if getopt_long will allow the 'short_opt' string to be changed half way through processing... Here's an honest opinion from a regular user. mdadm's command line arguments seem arcane and cryptic and unintuitive. It's difficult to grasp what combinations will actually do something worthwhile and what combinations will just yield a 'you cannot do that' output. I find myself spending 20 minutes with mdadm --help and experimenting with different commands (which shouldn't be the case when doing RAID stuff) just to do simple things like create an array or make MD assemble the devices that compose an array. I know. Not very constructive, but a POV anyway. Maybe I just do not use MD enough, and so I shouldn't complain, because the interface is really not designed for the absolute newbie. If so, then I apologize. I don't have any constructive suggestions, except to say that the way the classic Cisco interface does things works very nicely. A lot of other manufacturers has also started doing things the Cisco way. If you don't have a Cisco router available, you can fx. use a Windows XP box. Type 'netsh' in a command prompt, then 'help'. Or alternatively 'netsh help'. You get the idea :-). - To unsubscribe from this list: send the line unsubscribe linux-raid in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: mdadm 2.1: command line option parsing bug?
On 10:21, Neil Brown wrote: -a has the same problem (--add vs --auto). I'll see what I can do, gengetopt? (http://www.gnu.org/software/gengetopt/) Andre -- Jesus not only saves, he also frequently makes backups - To unsubscribe from this list: send the line unsubscribe linux-raid in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: mdadm 2.1: command line option parsing bug?
On Friday November 18, [EMAIL PROTECTED] wrote:
-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1
Hi!
I just upgraded to mdadm-2.1 from mdadm-1.12.0 and noticed
that the following command (which is even mentioned in the
manual page) doesn't work anymore:
[EMAIL PROTECTED]:~ {838} $ mdadm -Ebsc partitions
mdadm: cannot open partitions: No such file or directory
No I guess I should fix the man page, and maybe the code :-(
In mdadm-2 we've added --bitmap= and use '-b' as a short version.
So sometimes -b takes an argument (--bitmap) and sometimes not
(--brief). So getopt is told that it takes an optional argument.
This explains the observed behaviour.
Possibly this was a mistake
I would like it to take an argument in contexts where --bitmap was
meaningful (Create, Assemble, Grow) and not where --brief is
meaningful (Examine, Detail). but I don't know if getopt_long will
allow the 'short_opt' string to be changed half way through
processing...
At the very least, I can print a message if '-b' is being interpreted
as as --brief, but the option argument is present.
-a has the same problem (--add vs --auto).
I'll see what I can do,
Thanks.
I also noticed that there is now an additional newline between
the ARRAY lines. Is that intentional? IMHO there should only
by one newline after each line here.
Oh yes. That blank line gets filled with 'spares=' if there are
any spares, and =devices=' if --verbose. But I should remove it in
other cases. Thanks.
NeilBrown
-
To unsubscribe from this list: send the line unsubscribe linux-raid in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
mdadm 2.1: command line option parsing bug?
-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1
Hi!
I just upgraded to mdadm-2.1 from mdadm-1.12.0 and noticed
that the following command (which is even mentioned in the
manual page) doesn't work anymore:
[EMAIL PROTECTED]:~ {838} $ mdadm -Ebsc partitions
mdadm: cannot open partitions: No such file or directory
(I always use this command to create my mdadm.conf file,
so I found the problem very quickly after upgrading ;-)
After playing a little bit with the available commandline
options I found that the following commands do work:
[EMAIL PROTECTED]:~ {839} $ mdadm -Eb -sc partitions
ARRAY /dev/md/1 level=raid1 num-devices=3
UUID=c2c22b31:909b7973:0e4224bb:19cf529d
ARRAY /dev/md/0 level=raid5 num-devices=3
UUID=7abbd703:643ffe8e:d6ae4d0e:1b0908aa
as well as the following variations:
[EMAIL PROTECTED]:~ {840} $ mdadm -Eb -s -c partitions
ARRAY /dev/md/1 level=raid1 num-devices=3
UUID=c2c22b31:909b7973:0e4224bb:19cf529d
ARRAY /dev/md/0 level=raid5 num-devices=3
UUID=7abbd703:643ffe8e:d6ae4d0e:1b0908aa
[EMAIL PROTECTED]:~ {841} $ mdadm --examine --brief --scan --config=partitions
ARRAY /dev/md/1 level=raid1 num-devices=3
UUID=c2c22b31:909b7973:0e4224bb:19cf529d
ARRAY /dev/md/0 level=raid5 num-devices=3
UUID=7abbd703:643ffe8e:d6ae4d0e:1b0908aa
So it looks like the commandline option parsing algorithm
in mdadm.c (which is way too complicated for me to find out
quickly what is going wrong here... ;-) has some problem with
the -Ebsc partitions variant.
Seems to be a bug?
I also noticed that there is now an additional newline between
the ARRAY lines. Is that intentional? IMHO there should only
by one newline after each line here.
HTH
- - andreas
- --
Andreas Haumer | mailto:[EMAIL PROTECTED]
*x Software + Systeme | http://www.xss.co.at/
Karmarschgasse 51/2/20 | Tel: +43-1-6060114-0
A-1100 Vienna, Austria | Fax: +43-1-6060114-71
-BEGIN PGP SIGNATURE-
Version: GnuPG v1.4.2 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org
iD8DBQFDfiy0xJmyeGcXPhERAp9KAKCfQru5tViXFM3I+MGwEfTfSS7zwACgxD0C
ExjRVCIUb3ik5x1zCFYslFo=
=Rc7n
-END PGP SIGNATURE-
-
To unsubscribe from this list: send the line unsubscribe linux-raid in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
