Friday, July 21, 2006

sudo documentation is the worst ever

The prize for worst documentation ever goes to sudo.

(Of course many projects have no documentation at all. Those projects aren't in the running for the worst-documentation-ever prize.)

The sudo documentation spends the first few hundred lines telling us how the documentation is going to present the syntax for sudo in BNF. Then the documentation gives us the BNF in all it's tedious glory. We wade through symbol soup, trying to build a mental model of how /etc/sudoers works, but we can never be sure we get it because there isn't a single example in the entire section.

Finally, towards the end of the document, we get to examples. Unfortunately, examples start with an advanced topic, how to define aliases. It seems to me that 99% of all users never need to know how to create aliases.

Finally, finally, we get to some simple examples that implicitely explain how the whole thing works. It's really not so difficult, despite the documentation trying to make it seem that way.

The next section tells you most of what you need to know about configuring /etc/sudoers.

sudo for dummies (like me)

This /etc/sudoers file illustrates all you need to know to configure sudo for the most common use cases:
josh,timkay ALL=(ALL) ALL
%eng ALL=/usr/bin/less
%eng ALL=(timkay) /usr/bin/killall
These lines specify who is allowed to run what as whom. Lines are of the form
user-list host-list=(as-user-list) command
The user-list lists the users that can issue the specified command. A percent sign is used to specify a group rather than a user. Multiple users and groups can be listed, separated by commas.

Presumably a single /etc/sudoers file will be copied to many hosts. The host-list allows the granting of different privileges on different hosts. For simple use cases, host-list is always ALL, meaning that each line applies to all hosts.

The as-user-list indicates as what user the command will run. If ommitted, it defaults to root.

That's probably all you need to know.


more details

Let's interpret who can do what. /etc/sudoers starts with
josh,timkay ALL=(ALL) ALL
Josh and Tim Kay can, on any host (the first ALL), run as any user (the second ALL), and can run all commands (the third ALL). Josh or Tim Kay would issue commands like these:
sudo -u prod crontab -l (see prod's crontab)
sudo su - (get a root shell)
Before running the command (as prod or root), sudo asks the user for their password. sudo is asking for Josh or Tim Kay's password (not root's or prod's password).

Next, /etc/sudoers has
%eng ALL=/usr/bin/less
says that anybody in group eng can, on any host, run /usr/bin/less as root:
sudo less /var/log/apache2/error_log
This way, users writing CGI scripts can see the error messages. (A better way is to change the relevant permissions in logrotate.d.) Finally, /etc/sudoers has
%eng ALL=(timkay) /usr/bin/killall
says anybody in group eng can, on any host, run killall as user timkay (can kill any of timkay's processes):
sudo -u timkay killall sleep

sudo settings

The main purpose of /etc/sudoers is to specify who can do what as whom. It's also possible to change some settings, to modify how sudo behaves. These changes are optional; sudo will work just fine without them.
Default lecture=never
Default timestamp_timeout=0
By default, prior to executing a command, sudo does two things: it lectures the user to behave, and it prompts a user for their password (not root's password, of course). sudo asks for the user's password to prevent others from doing nasty things at the user's keyboard while the user is away.

The default is to give the lecture to each user once ever. I prefer to turn off the feature by setting lecture=never.

The default is to ask the user for their password once every 5 minutes. The timestamp_timeout setting specifies, in minutes, how often the user is prompted for their password. This feature is potentially useful but also very confusing to new users. I changed
timestamp_timeout=0, so that users are prompted for a password every time they use sudo.

Alternatively, you can turn off the password prompt altogether with
Default !authenticate
or you can add the tag NOPASSWORD: before the name of the command.

Quadra Island is an Excellent Vacation Destination

We spent two weeks on Quadra Island. It's a small island off the coast of Vancouver island in British Columbia.

We could have flown to Victoria, rented a car, driven to Campbell River, and caught the ferry to the island. However, fares to Seattle are less expensive, and driving across the border is fun. (We got caught in an hour-and-a-half wait at the border because we were crossing the weekend of both July 4th and Canada Day.) We drove 2 hours to Tsawwassen, caught the ferry to Nanaimo, drove another 2 hours to Campbell River, and caught a second ferry to Quadra Island.

I thought the kids would go stir crazy, being on an island for two weeks, but it was much better than expected.

The greatest strength of this island is a variety of interesting places to go swimming. The obvious swimming destination is Rebecca Spit. It's a long, thin sliver of land with rocky beach on both sides. The water is very warm, go figure; I thought Canadian beaches would be cold, but it was warmer than our unheated above ground pool.

There are also a variety of gorgeous lakes. Each one seems to have a perfect rock outcrop that extends into the water for perfect swimming. The water was warm and inviting.

We went on a 4-hour whale watch trip. We didn't see any whales, but the trip was terrific nonetheless. It was a bit pricey though. Next time, we'll save the whale watching for Victoria, where the whales are more dependable, and the trip is less expensive.

The island was overrun by ripe, delicious raspberries. The backyard of our rental house (on Quadra Loop) was fenced by raspberries. We made raspberry shortcakes with vanilla ice cream. We made raspberry smoothies. We ate raspberries plain. What a delight. It's surprising that the locals think of the raspberry brambles as a nuisance.

The greatest weakness is
Niko’s Sushi Bar & Grill. The sushi was terrible and terribly expensive. The sushi rice was wrong. The miso soup was wrong. The portions of fish was generous, but the fish wasn't that good. Avoid this restaurant.

Next time on the island, we'll rent bicycles. The price list makes them look expensive, but the dealers seem willing to bargain.

We took a day trip to Coombs. It's a fantastic place with numerous wildlife facilities. The butterfly gardens is interesting. Make sure you stop at the World Parrot Refuge. The
North Island Wildlife Recovery center is also interesting. And of course, don't miss a restaurant named Goat's on the Roof. There is a pie bakery across from and North of Goat's on the Roof, that makes excellent pies.

At the end of the trip, we spent two days in Victoria, which is very nice. The castle is worth visiting. The downtown is a great place to walk around. Make sure to leave at least two hours to see the street performers, who are fabulous.

We stayed at the Holiday Inn, which was fine, but I think we could have done better.

We finished with a couple of nights in Seattle and returned home.