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

[Raymond McLaughlin]

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.

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.

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>

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.

Below is a copy of the default SuSE sudoers file, which seems as good a
starting point as any, along with my proposed changes, and my
commentary. But first a couple of comments about comments. The *first*
comment related comment: in the ever lovin' man page we find this gem:

>> The pound sign ('#') is used to indicate a comment (unless it occurs
>> in the context of a user name and is followed by one or more digits,
>> in which case it is treated as a uid).

Ok, so a '#' indicates a comment except when it doesn't. A smooth move
if ever I've stepped in one, but if that's how the program works we'll
have to deal with it. The SuSE default file contains none of these '#'
exceptions, I'll add none if I can help it, and if I do I will clearly
explain the situation in a comment preceding the usage.

The *second* comment related comment: the default file contains some
comments, most on the line above the line(s) they comment on. The SuSE
comments (other distros I've looked at are no better) are pathologically
terse, and of some very little use. I've left them as they are for now.
If we get a good working sample sudoers file going here, I expect these
SuSE comments to eventually go away. For now they will be the comments
with a single '#'.

The *third* comment related comment: my comments proposed for inclusion
in this new improved sample sudoers file will begin the '##' to
distinguish them from the SuSE supplied comment. These will also precede
the line(s) to which they refer.

The *last* comment related comment: my own /commentary/ will begin with
'###' and will come *after* the lines they refer to. This commentary
will be addressed to any one who might want to help with this little
project, and will describe what I'm trying to do in a given line or what
I think is right or wrong with a the line. They would not be included in
a "finished" sample sudoers file.

And now, with my proposed improvements and commentary, an new, improved
/etc/sudoers:


# sudoers file.
#
# This file MUST be edited with the 'visudo' command as root.

### Not true, any editor will do. visudo will check your syntax for you,
### but only when you try to quit, not, as the man page might lead you
### to believe, when you save changes. Strictly speaking changes are
### only saved to a temp file until you quit, then changes are written
### to the real file.

### This limits the usefulness of visudo to quick edits where you know
### exactly what you want to do. If you are making numerous changes with
### visudo you have to exit after each edit, both to test the syntax,
### and before you can run 'sudo' to test for functionality.
### Testing like this is recommended unless you know *exactly* what you
### are doing. Lack of improper syntax doesn't mean expected function.
### If you are going to test in this manner 'sudo' will tell you of any
### syntax errors. So you may as well just keep the file open in plain
### old vi which will write changes directly to the sudoers file.
### But do keep a functioning backup copy of the file because if 'sudo'
### finds *any* syntax error 'sudo' will fail to function *AT ALL*.

# See the sudoers man page for the details on how to write a sudoers file.
#

# Host alias specification

# User alias specification

# Cmnd alias specification

# Defaults specification
## If 'Defaults targetpw' is not set sudo will ask the invoking user for
## *their own* password
Defaults targetpw    # ask for the password of the target user i.e. root

## With this line all members of the group 'users' will be able to run,
## on ALL hosts (that read this file) as ALL users (any user) ALL
## commands
#%users ALL=(ALL) ALL   # WARNING! Only use this together with 'Defaults
                        # targetpw'!

### With sample lines with so many 'ALL's it's hard to tell which
### instance of 'ALL' refers to the allowed hosts, the allowed target
### users, and the allowed commands, respectively. I think I got it
### right here.

## The 'Default timestamp_timeout' setting determines how long a period,
## in minutes, must pass before sudo requires, by default, a given user
## in a given shell needs to reenter the password. A value of '0' means
## users are always asked for a password, negative values mean
## never again (in current shell). If not declared the value defaults to
## 5 minutes.
Defaults timestamp_timeout=0

# Runas alias specification

# User privilege specification
root    ALL=(ALL) ALL

# Uncomment to allow people in group wheel to run all commands
# %wheel        ALL=(ALL)       ALL

# Same thing without a password
# %wheel        ALL=(ALL)       NOPASSWD: ALL

# %users  ALL=/sbin/mount /cdrom,/sbin/umount /cdrom

##This line allows user 'driveray', on any host, to execute /bin/mount
## and /bin/umount with root privileges without having to give a
## password.
driveray ALL = NOPASSWD: /bin/mount, /bin/umount
### This was the line that busted my nuts for hours! I work with a lot
### of ISO images, and want my regular user to be able to mount them
### without having to give the root password. The problem was that I
### kept trying to put the NOPASSWD parameter at or near the end of the
### line. I'm still not certain if the 'ALL' refers to "on all hosts' or
### 'as all users'

# Samples

# %users  ALL=/sbin/mount /cdrom,/sbin/umount /cdrom
# %users  localhost=/sbin/shutdown -h now