Hack 89 How'd He Know That?
Make the most of your available resources.
Unless you've achieved Unix guru status, you probably find yourself asking "how did he know that?" whenever you're around other Unix users or read a really cool snippet in a book. Here's a little secret: he probably had to look it up. As I tell my students, "No one knows everything. Make sure the one thing you do know is where to go to get the information you need."
9.2.1 Online Resources
If you're using FreeBSD, there is no shortage of well-written documentation. If you haven't already, bookmark the FreeBSD Documentation page at http://www.freebsd.org/docs.
There you'll find hyperlinks to the four handbooks, the FAQ, how-to articles, online manpages, as well as other sources of information. There's a very good chance that someone else has already documented what you want to do.
9.2.2 Keeping Offline Resources Up-to-Date
Online resources are great, but what if you don't always have access to an Internet connection? If you installed the doc distribution, you already have most of those resources on your hard drive. You'll find the handbooks, FAQ, and articles in /usr/share/doc. That directory contains symlinks so you can quickly navigate to the desired resource.
The online resources receive daily updates, so be sure to update your docs when you use cvsup. Make sure your cvsup file includes this line:
As cvsup retrieves the latest docs, it will write them to /usr/doc. This will not overwrite or update existing files in /usr/share/doc. Also, if you've ever poked about /usr/doc, you probably noticed that the resources themselves are written in SGML, making them a bit hard to read (unless you enjoy wading through tags).
How do you merge in those new changes? It's going to require a conversion of SGML to HTML. To achieve that, first install the docproj-nojadetex port:
# cd /usr/ports/textproc/docproj-nojadetex # make install clean
# cd /usr/doc # make install clean
This will merge all of the changes into the HTML files in /usr/share/doc. If you add this step to your cvsup routine, your offline resources will always be up-to-date.
9.2.3 What Did the Manpage Forget to Say?
Have you ever read a manpage and been unclear on how a certain switch worked? Perhaps you thought you understood the syntax until you tried it out and only managed to produce syntax error messages? Even more maddeningly, you might scour the Internet for concrete examples only to find endless links to the same manpage!
When this happens to me, I consider the program's source as a possible answer. If you're thinking, "I'm not a programmer; I couldn't read source code if my life depended on it," don't just skip to the next hack. You can still read comments, and most source in the FreeBSD core is very well commented.
Here's an example. I was reading through man mac_portacl, which indicates that the rule MIB takes this syntax:
but didn't give a specific example of a working rule. Since this particular MAC policy doesn't do anything until you successfully create a rule, I was looking for a more concrete example of an effective rule. And, since this module is fairly new, there weren't any tutorials or how-tos on the Internet. So, before hitting the mailing lists, I took a peek at the source.
To locate any C source file, use the locate command. Pass it the name of what you're looking for, followed by a .c. For example:
% locate mac_portacl.c /usr/src/sys/security/mac_portacl/mac_portacl.c
You must have src installed in order for this to work, and, as indicated, it will only find source code written in C. Happily, that's most of the FreeBSD core. You can use /sys/sysinstall to install all of the src distributions. If disk space is an issue or it's not appropriate to install source on the system you're logged into, you can read the source online at http://minnie.tuhs.org/FreeBSD-srctree/FreeBSD.html.
If you have src installed but don't see any results or do receive an error message that your database is too small, update the database and try again:
% su Password: # /usr/libexec/locate.updatedb >>> WARNING >>> Executing updatedb as root. This WILL reveal all filenames >>> on your machine to all login users, which is a security risk. # exit
Once you've located the source file, skim through its comments:
% grep '*' /usr/src/sys/security/mac_portacl/mac_portacl.c | tail +30
Here, I told grep to search for an asterisk (*), since C comments always include one. If you forget to enclose the asterisk within single quotes (''), you won't receive any results, as it is also a shell wildcard. You may want to adjust tail +30 for your own purposes. Source code begins with anywhere from 25 to 40 lines of copyright and licensing comments. Here I've told tail to ignore the first (+) 30 lines of comments.
In this particular case, the comments included the example I hoped for:
* # sysctl security.mac.portacl.rules="uid:425:tcp:80,uid:425:tcp:79" * * This ruleset, for example, permits uid 425 to bind TCP ports 80 (http) * and 79 (finger). User names and group names can't be used directly * because the kernel only knows about uids and gids.
Your mileage will vary, but source is definitely another resource at your disposal.
9.2.4 See Also