<div dir="ltr"><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Mar 17, 2015 at 7:43 AM, Joe Julian <span dir="ltr"><<a href="mailto:joe@julianfamily.org" target="_blank">joe@julianfamily.org</a>></span> wrote:<br><br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<div bgcolor="#FFFFFF" text="#000000">I'll split this out as I think you're unaware of the admin guide
that's pretty detailed and is, at least, published with the source
code (it may be on the <a href="http://gluster.org" target="_blank">gluster.org</a> site somewhere, but I'm too tired
right now to look). The source can readily be found on <a href="https://github.com/GlusterFS/glusterfs/tree/master/doc/admin-guide/en-US/markdown" target="_blank">github</a>.<span class=""><br></span></div></blockquote><div><br></div><div>I really think that this github doc (administrator's guide) should be used directly on <a href="http://gluster.org">gluster.org</a> replacing most, but not all, of the existing doc because it's clearly more useful (IMHO) than the doc available on site. It just needs some additions like this - <a href="http://www.gluster.org/community/documentation/index.php/Gluster_3.2:_Setting_Volume_Options">http://www.gluster.org/community/documentation/index.php/Gluster_3.2:_Setting_Volume_Options</a> - which sysadmins love ! A comprehensive list of options/directives, their meaning and their default values.<br><br></div><div>There is useful documentation on <a href="http://gluster.org">gluster.org</a>, mainly the howto's but for example, I don't think this kind or stuff - <a href="http://www.gluster.org/documentation/architecture/internals/Dougw:A_Newbie%27s_Guide_to_Gluster_Internals/#Configuration_and_Vol_Files">http://www.gluster.org/documentation/architecture/internals/Dougw:A_Newbie%27s_Guide_to_Gluster_Internals/#Configuration_and_Vol_Files</a> - can help anyone. A bunch of "sample" configs and no pointers to how to fill them with useful values.<br><br></div><div>Hint: When you have to use a search engine and type "site:<a href="http://gluster.org">gluster.org</a> nfs" to reach the link in the first paragraph, something is clearly wrong on how the documentation is built on site.<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="#FFFFFF" text="#000000">As I said before, I currently have *no* *clue* of all
the options and directives I can use in the main
configuration file /etc/glusterfs/glusterd.vol for
example! <span class=""><blockquote type="cite"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">
</div>
</div>
</div>
</blockquote>
</span>
Right. There's nearly no need to mess with that except under the
lesser circumstance that an unprivileged user needs access to the
management port.<span class=""><br></span></div></blockquote><div><br></div><div>If you read my first post - <a href="http://www.gluster.org/pipermail/gluster-users/2015-March/021070.html">http://www.gluster.org/pipermail/gluster-users/2015-March/021070.html</a> - especially the point "1/", you'll *why* I had to mess with it. BTW, I also pointed the inconvenience of using "transport.socket.bind-address" which is needed in my case but unusable in the current state.<br><br></div><div>And sorry but "You don't need to mess with that" is not a good answer, this something for Apple users who "don't want and don't need to know what's under the hood" :-)<br><br></div><div>For example, I have no use for "rdma" in my case and want to disable it to avoid adding bloat to my logs (already huge by default) complaining about not being able to initialize it.<br></div><div><br> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="#FFFFFF" text="#000000"><span class="">
</span>
That is the way it's done, btw. The developers are required to
document their features before a release.<span class=""><br></span></div></blockquote><div><br></div><div>Ok so where's the doc for the features for "glusterd.vol" ? :-)<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="#FFFFFF" text="#000000"><span class="">
<blockquote type="cite">
<div dir="ltr">
<div class="gmail_extra">
<div class="gmail_quote">
<div>Let me take 2 real world examples to get the general
idea : Postfix and NGinX! They are flexible enough to
provide a quite large set of use cases. Their
documentation is impeccable from my point of view. They
provide an exhaustive documentation of their inner options
like this - <a href="http://www.postfix.org/postconf.5.html" target="_blank">http://www.postfix.org/postconf.5.html</a>
- and this - <a href="http://nginx.org/en/docs/dirindex.html" target="_blank">http://nginx.org/en/docs/dirindex.html</a><br>
</div>
</div>
</div>
</div>
</blockquote>
<br></span>
Postfix, 16 years old, and hasn't always had very detailed
documentation. Do you also remember when it was worse than
sendmail's?<br></div></blockquote><div><br></div><div>I used postfix when its version was 1999MMDD :-) It took these examples to demonstrate that they are comprehensive despite their visual awfulness. Docs like Apache or PHP or Python are way more appealing for the eye of the reader. The point was : First provide exhaustive documentation, then add eye candy.<br><br></div><div>For instance, the markdown docs available on GitHub are a very good balance between these goals.<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="#FFFFFF" text="#000000">
<br>
I could counter with any of the myriad of horrible documentation for
some of the most popular software systems out there only to point
out that Gluster's isn't all that bad by comparison to a great many
of its peers.<span class=""><br></span></div></blockquote><div><br></div><div>I'm not putting a trial on gluster, don't take me wrong. The biggest issue I have is with the way documentation is available. Now that I browsed a lot of it I get a clearer view of the big picture. Currently, it is available at 3 distinct places, here - <a href="http://www.gluster.org/documentation/">http://www.gluster.org/documentation/</a> - here - <a href="http://www.gluster.org/community/documentation/index.php/Gluster_3.2_Filesystem_Administration_Guide">http://www.gluster.org/community/documentation/index.php/Gluster_3.2_Filesystem_Administration_Guide</a> and finally here - <a href="https://github.com/gluster/glusterfs/tree/master/doc/admin-guide/en-US/markdown">https://github.com/gluster/glusterfs/tree/master/doc/admin-guide/en-US/markdown</a> which does not really help anyone discovering the project.<br><br></div><div>Mixing various information available on each site allowed me to get GlusterFS work reasonably well for my needs except for the SSL part (but given the SSL markdown doc, I think I know how to solve my issue, I still have to test)<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="#FFFFFF" text="#000000"><span class=""><blockquote type="cite"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div>To the very specific case of "--remote-host" option,
there's a design problem in "gluster" command. Launching
it without arguments and you get a prompt and the command
completion helps a bit. Now, try "gluster -h" (or --help
or -? or whatever) and you end up with "unrecognized
option --XXX". This is counter intuitive again. You can't
experiment by trial and error to figure out things when
you're in the dark, that's why I had to take a peek to the
source code and find out the existence of other options.<br>
</div>
</div>
</div>
</div>
</blockquote>
<br></span>
"gluster help" is pretty intuitive, imho, as is<br>
<br>
# gluster<br>
gluster> help<br>
<br>
and the more detailed than any other software I can think of,
"gluster volume set help" which has all the settings you can tweak
in your volume along with their description equivalent to that
postfix document.<span class=""><br></span></div></blockquote><div><br></div><div>You missed the point here. Yep, "gluster help" works nicely and is quite helpful but I was talking about the options for "gluster" itself, independently of any command!<br></div><div><br></div><div>You *HAVE* to look here - <a href="https://github.com/gluster/glusterfs/blob/master/cli/src/cli.c#L303">https://github.com/gluster/glusterfs/blob/master/cli/src/cli.c#L303</a> - to find out that "gluster" accepts "--version", "--print-logdir", "--remote-host=", etc, etc. This is not documented elsewhere AFAIK.<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="#FFFFFF" text="#000000"><span class="">
<blockquote type="cite">
<div dir="ltr">
<div class="gmail_extra">
<div class="gmail_quote">
<div>If you spend so much time trying to find information
instead of experimenting with a project, you may grow
bored and leave.</div>
</div>
</div>
</div>
</blockquote>
<br></span>
Agreed, and that's something that the <a href="http://gluster.org" target="_blank">gluster.org</a> web site's been
failing at since the last 1 or 2 web site revamps.<span class=""><br></span></div></blockquote><div><br></div><div>I think a third (maybe the right one this time) is need to gather all scattered documentation, remove the not-so-useful stuff and add documentation for what's missing.<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="#FFFFFF" text="#000000"><span class=""><blockquote type="cite"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div>For example, I can't get SSL to work with my 3.6.2
setup and there's not a single bit of doc about it.
There's only <a href="http://blog.gluster.org/author/zbyszek/" target="_blank">http://blog.gluster.org/author/zbyszek/</a>
but even after following the necessary steps, I end up
with a cryptic log entry "Cannot authenticate client from
fs-00-22666-2015/03/16-11:42:54:167984-Data-client-0-0-0
3.6.2" and repeated for all the replicas :-( I don't know
what GlusterFS expects in this case so I can't solve the
problem for now.<br>
</div>
</div>
</div>
</div>
</blockquote>
<br>
</span><a href="https://github.com/GlusterFS/glusterfs/blob/master/doc/admin-guide/en-US/markdown/admin_ssl.md" target="_blank">https://github.com/GlusterFS/glusterfs/blob/master/doc/admin-guide/en-US/markdown/admin_ssl.md</a>
<-- not a blog<span class=""><br></span></div></blockquote><div><br></div><div>That's the result of scattered information. I spent so much time searching for glusterd.vol information, and had to deal with the "transport.socket.bind-address" issue that I simply missed that one. I confess having spent most of my time within here - <a href="http://www.gluster.org/community/documentation/index.php/Gluster_3.2_Filesystem_Administration_Guide">http://www.gluster.org/community/documentation/index.php/Gluster_3.2_Filesystem_Administration_Guide</a> - and here - <a href="http://www.gluster.org/documentation/">http://www.gluster.org/documentation/</a><br><br></div><div>Trust me to thoroughly read this SSL markdown doc to try to solve my issue :-)<br></div><div><br> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="#FFFFFF" text="#000000"><span class="">
</span>
Useful and eloquent perspectives and bits that infra is looking at
rectifying. The web site is covered in too many words. The "Getting
Started" entry has 13 sub-entries. That's not "getting started"
that's "tl;dr". A new vision is being put together that will try to
not just build a fancy web thingy, but will define goals such as
usability, engagement, community interfacing, that kind of stuff -
and measure the effectiveness of the changes that are made. It'll be
change for the sake of improvement rather than just change for the
sake of change.<span class=""><br></span></div></blockquote><div><br></div><div>I wish you the best of luck on that because I know what writing doc means, it's an unfair job. I sometimes have to write doc, mainly tutorials with screen captures, for users who never read it and complain the usual "it doesn't work" BS. At least you'll be luckier with GlusterFS because your target audience is technically skilled people who know they have to actually read docs to make things work :-)<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="#FFFFFF" text="#000000"><span class="">
</span>
But I still say you should still document things you find in the
source if they aren't documented - since you're in there anyway. <span><span> :-D </span></span><br>
</div>
</blockquote></div><br></div><div class="gmail_extra">As mentioned earlier, I indeed had to browse the source code to find the options of the "gluster" command. I agree there are obvious options and it's no rocket science to guess what their arguments are but for others, I wouldn't roll the dice to "guess" what it does. Documentation is far too important to be messed with :-D<br></div><div class="gmail_extra"><br clear="all"><br>-- <br><div class="gmail_signature">Unix _IS_ user friendly, it's just selective about who its friends are.</div>
</div></div>