samba - Aug 2005 - one opinion about searching samba docs for answers

It sure is hard to find info in the documentation/mailing list for a
specific error.  If an error log message was created by smbd, nmbd, or
winbind, shouldn't the documentation contain a description, cause, and
possible solution?

Specific case in point:
          [2005/08/05 11:31:22, 0]
nmbd/nmbd_browsesync.c:domain_master_node_status_fail(250)
          domain_master_node_status_fail:
          Doing a node status request to the domain master browser
          for workgroup MS at IP 192.168.40.20 failed.
          Cannot sync browser lists.

Searching the docs returned nothing for search strings:
   nmbd_browsesync
   domain_master_node_status_fail
   Cannot sync browser lists

The documents cover just about everything, except how to go from a log
message to the relevant areas of configuration.  On the other hand, the
documentation does a very good job of going from theory to high level
samba planning (with some configuration details).  Shouldn't the
documentation contain common error names, so that a search will direct
the reader to the proper place?

It might be nice if there was a good search-able mailing list archive at
samba.org, but the archive doesn't search well.  Maybe because too many
people abused the search tool because answers are not in the docs.

So I end up using an Internet Search Engine only to find many hits with
the same questions and no concise answers.  

I might be the only own who feels this way, but I would love to know how
to fix it.  Every time I go through this, I have these thoughts.

John,

I share your pain! I am the Samba Team documentation manager. I wrote much of 
the documentation. 

If you want to make me very happy just grant my wish that it might be easier 
to produce documentation that meets everyone's needs! 

After 18 months of near-full-time effort to create what we have it remains 
daunting to contemplate how much more effort it will take to complete just my 
short-list of things that "could be documented".

It would take a rather large book to document all the error and warning 
messages from the Samba source code. In fact, that is a project I have often 
contemplated, but backed away until someone will provide funding to make it 
possible to dedicate that time needed to systematically complete such an 
undertaking.

The only resource, other than the source code that you might refer to 
regarding the mechanics of the error conditions, why they are generated and 
how to solve them, is Chris Hertel's book that documents the entire CIFS 
protocol. Check on http://www.samba.org/samba/books for the link to this 
book.

Cheers,
John T.

On Friday 05 August 2005 15:13, John Stile wrote:
> It sure is hard to find info in the documentation/mailing list for a
> specific error.  If an error log message was created by smbd, nmbd, or
> winbind, shouldn't the documentation contain a description, cause, and
> possible solution?
>
> Specific case in point:
>           [2005/08/05 11:31:22, 0]
> nmbd/nmbd_browsesync.c:domain_master_node_status_fail(250)
> domain_master_node_status_fail:
>           Doing a node status request to the domain master browser
>           for workgroup MS at IP 192.168.40.20 failed.
>           Cannot sync browser lists.
>
> Searching the docs returned nothing for search strings:
>    nmbd_browsesync
>    domain_master_node_status_fail
>    Cannot sync browser lists
>
> The documents cover just about everything, except how to go from a log
> message to the relevant areas of configuration.  On the other hand, the
> documentation does a very good job of going from theory to high level
> samba planning (with some configuration details).  Shouldn't the
> documentation contain common error names, so that a search will direct
> the reader to the proper place?
>
> It might be nice if there was a good search-able mailing list archive at
> samba.org, but the archive doesn't search well.  Maybe because too many
> people abused the search tool because answers are not in the docs.
>
> So I end up using an Internet Search Engine only to find many hits with
> the same questions and no concise answers.
>
> I might be the only own who feels this way, but I would love to know how
> to fix it.  Every time I go through this, I have these thoughts.
-- 
John H Terpstra
Samba-Team Member
Phone: +1 (650) 580-8668

Author:
-------
2005:
	The Official Samba-3 HOWTO & Reference Guide, 
		Second Edition, ISBN: 0131882228
	Samba-3 by Example, Second Edition, ISBN: 013188221X

2004:
	Samba-3 by Example, ISBN: 0131472216
	Hardening Linux, ISBN: 0072254971

2003:
	The Official Samba-3 HOWTO & Reference Guide, 
		ISBN: 0131453556

Other books in production.

On Friday 05 August 2005 14:50, John H Terpstra wrote:
> It would take a rather large book to document all the error and warning
> messages from the Samba source code. In fact, that is a project I have
> often contemplated, but backed away until someone will provide funding to
> make it possible to dedicate that time needed to systematically complete
> such an undertaking.
Say, this is the kind of problem that maybe a samba errors wiki could solve?
People would have a structure to document errors.  And as the wiki grows it 
would become easier to search than mailing list archives.  To keep it from 
becoming simply a web-based discussion list, it would probably require 
moderation or volunteers to format information as articles. Maybe it would be 
possible to pre-load the site with known error messages from the source code.

John:

I agreee about the searchability of the samba list.
Using the "site" parameter of google helps by keeping your search 
results limited (mostly) to the samba list.
http://www.google.com/search?q=domain_master_node_status_fail+site%3Asamba.org&hl=en&lrdomain_master_node_status_fail
site:samba.org

I've often wondered why there isn't a "next by thread" link on
the
archived messages.
You can always take the extra click to get to the thread view, but often 
there's no reply, and there's a tedious succession of wasted clicks.

This probably isn't an immediate help, but the code can be browsed online:
http://websvn.samba.org/cgi-bin/viewcvs.cgi/*checkout*/branches/SAMBA_3_1_RELEASE/source/nmbd/nmbd_browsesync.c?rev=2563&content-type=text%2Fplain

Someone probably thought that error message was self explanatory.
It does mention the term "Master Browser", which might cause a person
to
look here:

How Browsing Functions
http://us4.samba.org/samba/docs/man/Samba-HOWTO-Collection/NetworkBrowsing.html#id2561439

It also contains the term/phrase: "node status request", which might 
prompt an aggressive google-jockey to try this search:
http://www.google.com/search?hl=en&q=node-status-request

Which (among other things) returns this link:
http://www.cpan.org/modules/by-module/Net/Net-NBName-0.25.readme

Which yields this info:
 > The node status request can be used to query the NetBIOS name table 
of a remote host

All this together is *probably* enough to put a sys-admin on the right 
track.

It's not always possible to direct a user to a single "relevant area of
configuration".
A lot depends on the circumstances of the application, and the intent of 
the user.
Link-rot is another problem. If the documentation gets a significant 
overhaul, then links (from error messages) into that documentation might 
break over time.

If the code that generates the error messages in SAMBA is consistent 
enough, it might be possible to generate a list of all the error messages.
 From there, it might be helpful to link all the buzzwords to glossary 
entries.

If we assume that the list can be generated easily enough, how many 
volunteers do you think might be available to identify terms, link to 
definitions, solutions, and/or documentation?

-Bill

From:
http://websvn.samba.org/cgi-bin/viewcvs.cgi/*checkout*/branches/SAMBA_3_1_RELEASE/source/nmbd/nmbd_browsesync.c?rev=2563&content-type=text%2Fplain
>
/****************************************************************************
>   Function called when a node status query to a domain master browser 
> IP fails.
>
****************************************************************************/
>
> static void domain_master_node_status_fail(struct subnet_record *subrec,
>                        struct response_record *rrec)
> {
>     struct userdata_struct *userdata = rrec->userdata;
>
>     if( DEBUGLVL( 0 ) ) {
>         dbgtext( "domain_master_node_status_fail:\n" );
>         dbgtext( "Doing a node status request to the domain master 
> browser\n" );
>         dbgtext( "for workgroup %s ", userdata ?
userdata->data :
> "NULL" );
>         dbgtext( "at IP %s failed.\n",
inet_ntoa(rrec->packet->ip) );
>         dbgtext( "Cannot sync browser lists.\n" );
>     }
> }


John Stile wrote:
>It sure is hard to find info in the documentation/mailing list for a
>specific error.  If an error log message was created by smbd, nmbd, or
>winbind, shouldn't the documentation contain a description, cause, and
>possible solution?
>
>Specific case in point:
>          [2005/08/05 11:31:22, 0]
nmbd/nmbd_browsesync.c:domain_master_node_status_fail(250)
>          domain_master_node_status_fail:
>          Doing a node status request to the domain master browser
>          for workgroup MS at IP 192.168.40.20 failed.
>          Cannot sync browser lists.
>
>Searching the docs returned nothing for search strings:
>   nmbd_browsesync
>   domain_master_node_status_fail
>   Cannot sync browser lists
>
>The documents cover just about everything, except how to go from a log
>message to the relevant areas of configuration.  On the other hand, the
>documentation does a very good job of going from theory to high level
>samba planning (with some configuration details).  Shouldn't the
>documentation contain common error names, so that a search will direct
>the reader to the proper place?
>
>It might be nice if there was a good search-able mailing list archive at
>samba.org, but the archive doesn't search well.  Maybe because too many
>people abused the search tool because answers are not in the docs.
>
>So I end up using an Internet Search Engine only to find many hits with
>the same questions and no concise answers.  
>
>I might be the only own who feels this way, but I would love to know how
>to fix it.  Every time I go through this, I have these thoughts.
>
>  
>