Unsolved
This post is more than 5 years old
1 Rookie
•
20.4K Posts
1
3100
xmcli built-in help and online documentation
I am curious to hear how other XtremIO customers feel about the xmcli documentation provided in the array as well as PDF file. I guess i have been very spoiled by the excellent documentation provided by Symmetrix team, even the block/file CLI documentation for VNX is pretty good. When i am trying to figure out how to do things in xmcli i am using a lot of profanity because it's horrible. Let's say i need to assign a tag to a volume.
xmcli (admin)> tag-object ?
Usage: tag-object property=value list
PROPERTY |MANDATORY |DESCRIPTION |VALUE
============== |========= |=========== |=================
cluster-id |No |Cluster ID |id: name or index
entity |Yes |Entity |string
entity-details |Yes |Entity ID |name or index
tag-id |Yes |Tag ID |name or index
does anyone think this is very helpful and intuitive ? How about provide an example that looks something like this:
tag-object tag-id="
tag-object tag-id="/Volume/oracle-prod01" entity=Volume entity-details="LUN0252"
Comments ?
echolaughmk
522 Posts
1
February 3rd, 2016 16:00
I would agree with you dynamox. This is a pain point in providing knowledge transfers at times.I have been bitten by values that are listed as not mandatory, being needed for the command to run and I think a better explanation like you have in the SE guides would improve the CLI portion of the user guide significantly. To provide all of this explanation and examples, it might be useful to separate the CLI documentation into its own document as well.
dynamox
1 Rookie
1 Rookie
•
20.4K Posts
0
February 4th, 2016 05:00
thank you. I am all about learning new ways of doing things but seems as if the help menu was written by an engineer and not by a technical writer. While i could play around and figure out how to assign tags, i am very hesitant do it with with commands that can do some real damage.
So Avi, how do we relay this feedback to the mothership in Hopkinton ? Any feedback from you side ?
scotthoward
64 Posts
1
February 4th, 2016 08:00
Very true - the help is (normally) great if you already know what you're doing and just need to know the option names, but not overly helpful if you're trying to learn how to use a command. The "tag" syntax that you've shown is definitely one of the worst as it's not even clear what the options are - I thought we called these out in the Users Guide but I just realized that we don't so I'll make sure that we get that fixed!
For that specific command, you can get a list of valid "entity" values by passing in an invalid one, in which case you'll get this error :
** Error: Command Syntax Error: entity property must have one of the following values: [InfinibandSwitch, DAE, Initiator, BatteryBackupUnit, Scheduler, StorageController, DataProtectionGroup, X-Brick, Volume, Cluster, InitiatorGroup, SSD, SnapshotSet, ConsistencyGroup, Target]
From that, you can probably work out that the command you need is something like :
tag-object entity="Volume" entity-details="MyVolume" tag-id="/Volumes/MyTag"
(show-tags will give you the exact value for the tag-id - you can't just use the raw tag name. And I hate to say it, but the entity= value is case sensitive - "volume" will not work, only "Volume")
Of course, it shouldn't be that difficult, and I'll make sure that as at least a first step we get the users guide updated to be a little more user friend...
If you've got specific examples of things that are wrong (echolaughmk - especially those you mentioned that showed options as not being mandatory where they were) then feel free to drop me an email as things like that can be fixed fairly easily.
The real solutions - better documentation for the CLI (and the REST API, which is what you really should be using if you're attempting to automate anything), and even a better CLI overall, are things that we're working towards - they will happen, but as with everything it's just a matter of priorities...
dynamox
1 Rookie
1 Rookie
•
20.4K Posts
0
February 4th, 2016 08:00
while i understand the whole shift to REST API, i am not there yet. Smaller tasks are much simpler to automate with bash/perl (at least for me). So please do not discriminate against the CLI, if you provide that capability it needs to be well supported and documented.
I can eventually "work out" how to do things in xmcli but i shouldn't have to. Your tech writers should look at Solutions Enabler manuals as the gold standard, those guys/gals have their stuff together. At this point XtremIO has been around a while, expectations are higher.
echolaughmk
522 Posts
0
February 4th, 2016 12:00
HI Scott,
I can do that if you want to shoot me a private message with your email. In my case, it was the power-off command during a planned shutdown where it said the cluster-name wasn't mandatory (had a NO in the column), but the command would fail without it.
I understand it is a dynamic product and I would agree with dynamox on the SE manuals as the gold standard (former EMC and Symm member) so any improvements to the docs would be greatly received by the field and customers.
-Keith
Kumar_A
727 Posts
0
February 4th, 2016 19:00
Thanks for the feedback folks. We will take it back to the documentation team.