[mdlug] /etc/sudoers -A rant and an attempt at better documentation

[Aaron Kulkis]

Raymond McLaughlin wrote:
> LUG nuts:
> 
> It is often bandied about that using 'sudo' is a good way to avoid
> having to login as root, for example, and for giving certain users
> greater privilege *for certain commands*. A little looking into this
> wonderful command quickly reveals that to use 'sudo' to dole out
> privileges effectively an administrator must edit the /etc/sudoers file,
> and therein lies the rub. The manual page for the sudoers file.
> 
> <rant>
> It may be that I'm just dense, but I find the man page 'man sudoers' to
> be the most insanely, obscenely incomprehensible excuse for
> documentation that I can recall ever encountering. I don't want to sound
> ungrateful to the programmers who wrote this, no doubt excellent
> program, but the man page is a quintessential example of documentation
> written by programmers for the benefit of people who already know the
> answers.
> 
>>From the man page
>>> The sudoers grammar will be described below in Extended Backus-Naur
>>> Form (EBNF). Don't despair if you don't know what EBNF is...
> 
> Clearly the implication is "don't despair *YET*, it gets worse..."
> 
>>> EBNF is a concise and exact way of describing the grammar of a language.
> 
> OK, so not only do I need to learn a new language to understand the
> explanation that's to come, but I need to learn a new way of thinking
> about language in order to learn this language, in which the explanation
> will be given.
> 
> Rrrrriiiight.
> 

When I return... on leave... if it's a LUG weekend, I'll give a
brief talk on BNF.

BNF is actually quite standard.  Most Computer Science textbooks
(as opposed to just "introduction to language X" books) will
cover BNF notation.

Also, any book on compilers will describe BNF notation.

It's easy to learn... in my interpreters and compilers class, I
think the prof spent 1 hour on it.

Most of your man-page syntax summaries (you know, the ones that
indicate the command line arguments, and what can go with what,
and what can be repeated, etc) *IS* Bachus-Naur Format.  (and
Perl pattern-matching syntax is *ALSO* BNF)

So, don't despair... you probably already know BNF, you just
never realized what it was called.

> The man page then starts in talking about "production rules" and
> "symbols" with out defining either term. There are examples, but no
> definitions. Are these terms, like from data-base theory or something,
> that they think *everybody* understands, or are we expected to surmise
> their meaning from their usage? OK, so at this point I'm trying to
> intuit these undefined terms in order to understand a new way of
> thinking about language in order to learn this new language in which
> sudoers files will be explained.

Production rules are the syntax diagrams that you see in some
programming language textbooks, ESPECIALLY Pascal textbooks

> 
> My puny mortal mind is just too weak, too many nested abstractions. I
> experience buffer overflow, the main symptom of which is an intense
> desire to just go do something else. Persistence past this point results
> in watery eyes, shortness of breath, random twitching and muttering,
> while reading the the same paragraphs over and over.
> </rant>

Yeah.. I can understand that.

I actually lost the ability to program while on the other side of
the problem... writing code to IMPLEMENT the production rules.
I forget what it was exactly...I believe the mutual-recursion of

Factor ;= Term '+'|'-' Term
Term   := Factor '*' | '/' Factor

It kind of put my mind in an endless loop, as I couldn't see how
it would bottom out on even trivial equations ( A = B + C * D)


> 
> Maybe I'm just dense. I first ran into this over five years ago, and it
> still makes no sense. I'm not posting this just to complain, I would
> like to help myself, and maybe others, with some better documentation.
> Not a better man page, I wouldn't touch that, but a verbose, human
> readable sample sudoers file chock full of comments written in nice
> friendly complete sentences. It could have most of its lines commented
> out so sudo wouldn't act any different. But there would be sample lines
> that could be uncommented for easy access. If there are potential
> conflicts or dependencies among the lines, explain them a simply as
> possible. I don't doubt that there are complex usages that would go far
> beyond what I'm proposing. But I also think that a half dozen or so
> simple examples could cover most common usages.

I think what's needed is a man page on BNF, because it is so commonly
used in one form or another.