Published on (
 See this if you're having trouble printing code examples

FreeBSD Bag of Tricks

by Dru Lavigne, author of BSD Hacks

As a software junkie, I'm always coming across new programs to experiment with. As I find programs I like, I add them to my mental bag of tricks so they're ready whenever a client asks, "What's the best program to do x?" In this article, I'll demonstrate how I used an old favorite as a lightweight webmail program as well as a new favorite I just ran across.

Webmail with Usermin

On one of my routine visits to a network I administer, the owner mentioned he was thinking of adding webmail functionality. Since he had only a dozen or so users, he didn't want anything too complicated, just a small program with which people could check their mail while away from the office. If he had to, he could take the time to write and test a few scripts himself, but he preferred not to spend his time reinventing the wheel.

We went to the Mail section of FreeBSD's ports collection to see the available options. Things looked hopeful, as more than half a dozen webmail programs were there. We took a closer look at each program to see which best suited his particular network. A few required Apache 1.x and wouldn't work with his server running Apache 2.x. Still others needed an IMAP server. His server has happily run popa3d for the past few years, and he was hesitant to learn, install, and test an IMAP server on a production system. (I know IMAP4 is more secure than POP3; I also know better than to tempt the network gods by replacing working software with something "better.") This narrowed our choices down to two applications.

We looked at the smaller application, but the owner didn't like the interface. The larger one's interface looked quite nice, judging from the web site's screenshots, so we agreed to install the application on a test system to see how easy it was to configure. That was when the fun began.

The install itself resulted in hundreds of SUID scripts, which started my heart going. Even the owner couldn't believe how big the program was. We then started wading through reams of documentation, soon followed by scouring the Internet for error messages when the scripts refused to run. After a couple of hours of this, the owner teetered between "Why did I even want a webmail program?" and "Forget this, let's try that IMAP thing."

That's when I began to mentally scan through my toolkit. I've used Webmin on many an occasion to check email as an administrator. I like Webmin so much, I wrote about it in An Introduction to Webmin. Obviously Webmin wouldn't help here, as it's a remote administration tool. However, Webmin does have a user equivalent--called, not surprisingly, Usermin.

Installing Usermin

While the owner took a break, I did this:

# cd /usr/ports/sysutils/usermin
# make install clean

When the install finished, I followed the instructions left by the pkg-message:

# /usr/local/lib/usermin/
 *            Welcome to the Usermin setup script, version 1.080       *
 Usermin is a web-based interface that allows Unix-like operating
 systems and common Unix services to be easily administered.
 Installing Usermin in /usr/local/lib/usermin ...
 Usermin uses separate directories for configuration files and log files.
 Unless you want to run multiple versions of Usermin at the same time
 you can just accept the defaults.

 Config file directory [/usr/local/etc/usermin]: 
 Log file directory [/var/log/usermin]: 
 Usermin is written entirely in Perl. Please enter the full path to the
 Perl 5 interpreter on your system.
 Full path to perl (default /usr/bin/perl): 
 Testing Perl ...
 Perl seems to be installed ok
 Operating system name:    FreeBSD
 Operating system version: 5.2
 Usermin uses its own password protected web server to provide access
 to the administration programs. The setup script needs to know :
 - What port to run the web server on. There must not be another
   web server already using this port.
 - If the webserver should use SSL (if your system supports it).
 Web server port (default 20000): 8080
 Use SSL (y/n): y
 Creating web server config files..
 Attempting to start Usermin mini web server..
 Usermin has been installed and started successfully. Use your web
 browser to go to

 and login as any Unix user on your system.

 Because Usermin uses SSL for encryption only, the certificate
 it uses is not signed by one of the recognized CAs such as
 Verisign. When you first connect to the Usermin server, your
 browser will ask you if you want to accept the certificate
 presented, as it does not recognize the CA. Say yes.

Note that I chose a random port of 8080, which users must specify in their browser in order to connect. Since I also chose SSL, users must use https in their URL. They will have the added bonus of encrypted connections, so accessing their mail with Usermin will be more secure than doing so with a POP3 client.

Note that while this particular client had an Apache web server, that's not a requirement in order to use Webmin or Usermin.

Before configuring Usermin, I also added this line to /etc/rc.conf:


to ensure that Usermin will restart should the system ever reboot.

Pruning Usermin

When the owner returned from his break, I had him type in the URL and log in with his username in order to check out the Usermin interface. You can do the same at the Usermin screenshots page or examine Usermin's standard modules list.

We went through the modules together and agreed to keep our installation very simple and lightweight. The only modules we retained were Read Mail and Change Password. Since Usermin is a user program and you don't want users mucking about with each other's settings, you actually need Webmin to configure Usermin. If you don't already have Webmin and wish to configure Usermin, install Webmin with:

# cd /usr/ports/sysutils/webmin
# make install clean

Related Reading

BSD Hacks
100 Industrial Tip & Tools
By Dru Lavigne

At the end of the install, run the /usr/local/lib/webmin/ script. Be sure to choose a different port number and choose a unique username and password for the administrative account. Open a second tab in your browser and open your URL using the Webmin port number. This will allow you to test your changes from the user's perspective as you make them in the other tab of your browser.

On Webmin's main page is an icon for Usermin Configuration. You can then click on Usermin Modules to delete the modules you don't want to use. Use the Ctrl key to select multiple modules to delete. Note that once a module is deleted, you have to reinstall it before you can use it again. (If you mistakenly delete a module you intended to keep, retrieve it from the Usermin modules page.)

After I configured the site, I still had an extra module I didn't want: Running Processes wouldn't delete, as Change Password depended upon it. However, I went into Available Modules and unchecked Running Processes. Note that this screen won't actually delete the module but it will hide its existence from users.

Now that we were down to the two desired modules, we took a closer look at each. The owner didn't like the banner on the mail page that advertised the version of Usermin and the operating system. To remove that, I clicked on User Interface (in Webmin's Usermin configuration) and selected No for "Show version, hostname and OS on main menu?"

He also didn't like the fact that users could see the entire directory structure when they clicked on Read Mail -> Manage Folders -> "Add an existing file or directory as a folder" and then clicked on the browse button next to "External mail file or directory." The fix for that one was a little less obvious, but I found it when I clicked on Access Control Options. Under "Root directory for file chooser" change the button to "User's home directory," and under "Users visible in user chooser" change the button to "No users."

Depending upon your needs, you can further tighten up Usermin's security. If, for example, you use Usermin to check your own mail from work and have a static IP, you can restrict connections to that IP in IP Access Control. If you or your users don't have static IPs, instead use Allowed Users and Groups to restrict who can connect. Users who don't match the list will receive the message "Login failed. Please try again."

Also consider reviewing the defaults in Authentication. For example, by default there are no password timeouts, and authentication failures go unlogged.

All in all, my client was pleased with how easy it was to configure Usermin and get a decent-looking and functional webmail program. Now I have a new trick to pull out of my sleeve the next time someone is shopping around for a similar solution.


The other piece of software I found made me glad I had a 2000 Pro install kicking around in my home network. How many times have you seen your Windows friends struggling with expensive yet often virus-ridden software? Yes, they'd love a more affordable solution, but they don't have the time, energy, or courage to take the Unix plunge. Perhaps they do, but they don't completely believe that they'll be as productive on a Unix system. Maybe they still think there's a catch to "free" software. Don't you wish they could just install some decent open source software on the operating system they most prefer?

Well, now there's an easy way to introduce open source software to a Microsoft operating system. It's TheOpenCD. I had a friend burn me an ISO--I do have to break down and buy myself a CD burner one of these days--so I could check it out.

The CD itself autoruns on a Windows system. However, TheOpenCD's web site breaks down the contents and layout of the CD so you can see for yourself what is available. The initial splash screen on the CD describes Software Freedom Day, August 28. You then continue to the programs themselves in the following categories:

Once the user clicks on a category, a slide appears for each program. Each slide contains a description of the program, screenshots, and a hyperlink to the program's web site. More importantly, the Install button invokes a Windows installer for the specified program.

I must admit that I took great joy in installing Gimp, AbiWord, PDFCreator, Blender, and FileZilla on a 2000 system. I also thoroughly enjoyed the Movies & Demos that came with the Blender 3D slide. I even discovered some new software that I hadn't previously known of.

While there were a few typos in this edition, which I assume the next version of the CD will fix, I found it easy to use with an attractive layout. The creators of the CD also have a form on their site where you can present the case for including additional software on the CD. I think this CD will make its way into quite a few conventions and installathons over the next year. Check it out for yourself, and maybe burn a few for your friends and family.

Dru Lavigne is a network and systems administrator, IT instructor, author and international speaker. She has over a decade of experience administering and teaching Netware, Microsoft, Cisco, Checkpoint, SCO, Solaris, Linux, and BSD systems. A prolific author, she pens the popular FreeBSD Basics column for O'Reilly and is author of BSD Hacks and The Best of FreeBSD Basics.

Return to BSD DevCenter

Copyright © 2009 O'Reilly Media, Inc.