Odds and Ends

One of the reasons I look forward to the holiday season is that it provides the opportunity to get reacquainted with the inner workings of my FreeBSD system. During the rush of the rest of the year it seems that everything I learn is on a need-to-know basis. So with the excitement of a four year old on Christmas Eve, I break open the eggnog, pump up the volume on the PC speakers, and start reading through the notes I've made to myself over the past year.

It always reminds me of how I felt after my first successful FreeBSD install. After the initial "omg, I just installed Unix!", I sorta sat there in a stunned daze and wondered "now what?" There was just so much to learn, so many man pages to read, so many commands to try out. Not to mention the fact that I kept getting lost and couldn't remember where I was and where I had saved things.

Keeping Track

It was then that I acquired two habits which helped me scale the initial learning curve. The first was to subscribe to the freebsd questions mailing list. This is a fairly high volume list, but the information that can be learned from it is invaluable. In the beginning I'd set aside an hour a day to read through the responses. If something sounded interesting, I would try it out on my own system. If I couldn't get it to work, I appended that particular post to an ever-growing file of things to try again at a later date.

Related Reading The Unix CD Bookshelf By O'Reilly Media, Inc.

At first that file seemed huge; everything I read sounded interesting, and I wasn't very good yet at getting things to work. But after a few months of persistence, I noticed that I was making progress. It was like getting used to a new language. As I'd read through that file, the information in it seemed less strange and started to make more sense. Pieces were starting to fit together. One day as I was reading through the mailing list, someone asked a question and I actually knew the answer. That was a very good feeling.

The second habit I acquired was taking the time to document everything. I bought two notebooks. The first I labeled "stuff I tried"; the second I labeled "stuff that works". Since I have a knack for discovering all of the wrong ways to do something before I stumble upon a way that works, my first notebook filled up very quickly. I was, however, left with a record of all possible error messages and how I managed to get past them to a working solution. This became an invaluable troubleshooting tool. Knowing how to reproduce an error is as important as knowing how to accomplish something without errors.

The second notebook eventually turned into my little black book of accomplishments. Once I figured out how to do something, I didn't have to reinvent the wheel when I needed to do it again six months later. I could simply look it up and follow my own step-by-step instructions. It was also an excellent way to chart my progress as those empty pages slowly transformed into the stuff I knew how to do on a Unix system.

At some point, I retired those notebooks and started to maintain notes in my home directory. There are several ways to keep track of your own experimentations. The first is to record your input and resulting output using the script command. For example, I can keep track of the date I did some experiments with snort:

$ script snort.dec.28.2002

This command tells the script utility to copy all input and output to a file called snort.dec.28.2002. When you use the script command, you'll receive a message stating the script has started and the name of the output file you specified. You will also be presented with a fortune, if you normally receive a fortune when you login. At this point, you can carry on as usual. Once you've finished recording what you set out to do, end the script by pressing Ctrl-d. You'll see a message like this:

Script done, output file is snort.dec.28.2002

The script utility is an excellent way to record how you accomplished something; it also creates a file that is handy to send to someone else so they can see what errors you are running across. It has its limitations, though, since it records everything, including escape characters. For example, here is the first line from one of my script files:

←[1mdlavigne6@~←[m: cd /s•←[K/ysr/•←[K•←[K•←[K•←[K•←
[Kusr/ports/security/sn•o•rt

It's a bit hard to tell, but this is what script was recording:

$ cd /usr/ports/security/snort

The resulting output is unreadable for several reasons. One, I use a customized prompt which contains control characters. Second, I had problems typing that day. Instead of /usr, I typed /s and had to backspace a character; than I typed /ysr and had to backspace three characters. Finally, I use tab completion; you can see that I tried to tab at sn but received a beep; I then tried to tab at sno and had my input completed to snort.

The file utility does warn that this happens:

$ file snort.dec.28.2002

   snort.dec.28.2002: ASCII English text, with CRLF, CR, LF line terminators, 
   with escape sequences

All is not lost, though. This command will get rid of most of the garbage characters:

$ more snort.dec.28.2002 | col -b > snort.dec.28.2002.clean

The result is much more readable:

 1mdlavigne6@~m: cd /usr/ports/security/snort

	file snort.dec.28.2002.clean
	snort.dec.28.2002.clean: ASCII English text

You'll find that if you use an editor during a script session, the results from the edit will be a bit messy when you re-read your script file. For this reason, I tend to use the echo command to send little comments to myself:

$ echo #once you open up /etc/rc.conf
   echo #change this line: linux_enable="NO"
   echo # to this: linux_enable="YES"
   echo # and add this line: sshd_enable="YES"

These comments help me to remember why I opened certain files and what I did when I was in there.

Another way of recording a session is to open an interactive shell:

$ csh -i | & tee acid.dec.29.2002

Again, you'll receive a fortune and everything you type will be recorded to the file name specified after the word tee. When you are finished, either press Ctrl-c or Ctrl-d or type the word exit. I find that this method produces less garbage then script so I don't need to clean up the file using the col -b command. However, if I try to use vi from an interactive shell, I'll receive this message:

ex/vi: Vi's standard input and output must be a terminal.

The pico editor will work, but the results will still be very messy when I read the resulting session file.

One of the cool things about recording to a file with either script or csh -i is that the results can be watched "live" from another terminal. For example, another user on the system can use the tail command to watch the file as it is created:

$ tail -f acid.dec.29.2002

This can be very handy if you are troubleshooting a problem and need another user's input on the error messages you are receiving.

Finding Commands

So where do you go about finding all the commands on your FreeBSD system so you have something to try out? At least once a year I like to play with the apropos command to see which commands are on the FreeBSD system. For example, to see all of the built-in general commands, try:

$ apropos '(1)'

If you happen to be half as curious as I am, give yourself a chunk of time before you try that command. If one of the descriptions piques your interest, read the associated man page. No matter how little or how much experience you have in Unix, you will always find commands you either haven't heard of or would like to learn more about. For example, this year I came across systat, one of those commands I can't believe I've lived without.

If you just type systat at a prompt, you probably won't be impressed. The full power of this command comes from having the man page open in one terminal and systat running from another. Any man page that includes a pigs switch has to be worth checking out. Since pigs is the default, type :icmp once you've started systat, then try a ping from another terminal. Once you've ended your ping, try :ip or :tcp or :swap or :mbufs. I'll leave it to you to try your own experiments so you can discover which switches are the most useful for your own needs.

Playing Around

I also remember to take the time to see which games come with the system:

$ apropos '(6)'

I discovered grdc just in time for my New Year's resolution of remembering to step away from the computer at least once a day in order to do some aerobic activity. The display is large enough for me to see what time it is from across the room, despite my myopia.

I also rediscovered quiz, a game I had forgotten about in the last few years. To see what quizzes are available, simply type quiz for a list. Each quiz type is on a line of its own and consists of at least two words. For example, if I type:

$ quiz male female
lad?

I'll be given a male term and should type in the female equivalent. If I'm correct, I get a "Right!" and the next term. If I'm incorrect, I get a "What?" and another chance. If I give up and want to know the answer, I simply press enter. Pressing Ctrl-c ends the game. The game can also be played the other way around by typing this instead:

$ quiz female male

This utility includes quizzes for Latin, Greek, arithmetic, capitals, poetry, number sequences, and even Middle-Earth and Star Trek trivia.

Browsing Documentation

Some of the games on your system supplement the man page with additional documentation. This is a good time to mention that the documentation that comes in the /usr/share/doc directory is truly awesome when you are ready to delve deeper into the inner mysteries of Unix. You can also read and see the general layout of this documentation.

The documentation contains a who's who of Unix and many of the classic, "everybody should have a chance to read at least once" documents. It really is something to be able to read documentation from the very people who created Unix, the C programming language, the Fast File System, Sendmail, the Bourne shell, the C shell, vi, and so on. It's a good way to find out how things came to be and why they are the way they are. One of the many things I'm looking forward to in FreeBSD Release 5.0 is that some of the formerly encumbered documents will become available in the documentation. A list of those upcoming documents can be found in the CURRENT release notes.

Let's take a look at the contents of the documents directory:

$ ls -F /usr/share/doc
IPv6/   bind/   ncurses/   ntp/   papers/   psd/   smm/   usd/

You'll note that it is composed of several subdirectories. The psd is the Programmer's Supplementary Documents, the smm is the System Manager's Manual, and the usd is the User's Supplementary Documents. Those three subdirectories and the papers subdirectory each contain a file called contents.ascii.gz which gives a description of the documentation found in the associated subdirectory.

You may remember that a gz extension indicates a zipped file. You don't have to unzip a file in order to read it. For example, to see the contents of the psd, simply use the zmore utility instead of more:

$ zmore /usr/share/doc/psd/contents.ascii.gz

And if one of the documents looks interesting:

$ zmore /usr/share/doc/psd/12.make/paper.ascii.gz

Over the holidays, I always find time to reread portions of the documentation. I also go through my extensive bookmark collection and revisit the homepages of some of the authors of that documentation. If you're unfamiliar with some of the who's who, you may enjoy these links:

• Dennis M. Ritchie
• Ken Thompson
• Kirk McKusick
• Brian Kernighan
• Eric Allman
• Unixica

Between those URLs and the documentation, you should have plenty of quality reading to keep you busy and learning about your FreeBSD system for quite a while.

If you happen to be in the Ottawa area on January 25 and 26, check out the Open Source Weekend. Dan Langille and I will be manning the FreeBSD booth on Saturday, so drop by to say "hi" and show your support for FreeBSD. See you there.

Copyright © 2009 O'Reilly Media, Inc.