Automatic UNIX Documentation with unixdoc

Roman Marxer

There's no need to spend days documenting your servers. I've written a program that can help. unixdoc collects all the configuration files and other information about your computers into an HTML file and sends it to a display server where it can be viewed with a browser. It works on Solaris 2.6/7/8 and on HP-UX 10.20. On the display server, you can see an overview page with all your systems as shown in Figure 1. By selecting a computer, the unixdoc HTML page of this computer will be displayed as shown in Figure 2.

The unixdoc HTML file of a Solaris computer consists of the following 18 sections:

1. Hardware
2. Eeprom
3. Kernel
4. Networking
5. Software
6. Nameservices
7. Bootup
8. Disk
9. Disk Hardware
10. Users
11. dmesg
12. Printers
13. Cron
14. Rhosts
15. Quota
16. Syslog
17. Xntpd
18. Sendmail

The information in these sections consists of either config files or the output of a command. With unixdoc, it is easy to compare the configuration of two servers. You just have to open the two unixdoc HTML pages of the servers and compare the content, section after section. You don't have to do a login on the two servers, or to remember all those commands to display the configuration. I find subsection 4.1.1 ifinfo helpful, because it provides a good overview of all the network interfaces (speed, mode, etc.). (Subsection 4.1.1 is shown in Figure 3.) The information in this subsection is very useful when verifying the speed/mode settings between your switches and servers. An example of the entire unixdoc HTML page can be found at:

http://www.net.li/article

Installation and Configuration

unixdoc consists of two parts -- the client part and the server part. The client part is responsible for creating the documentation and sending it to the display server by email. The server part is installed on the display server. The display server is responsible for collecting the emails and putting them on the Web. I will first describe the client software and its configuration, and then the server software and its configuration.

Client Software

The client software is in package format and is available for Solaris 2.6/7/8 and HP-UX 10.20. The package is called RTCdoc.pkg for the Solaris version, and RTCDOC.DEPOT for the HP-UX version. It installs in /opt/RTCdoc on Solaris, and in /opt/rtcdoc on HP-UX. In this article, I will describe the Solaris version; the HP-UX version is similar. To install the software, do:

pkgadd -d RTCdoc.pkg (on solaris)
swinstall -s /tmp/RTCDOC.DEPOT (on hpux)

Remember to use absolute pathnames with swinstall. This installs the necessary software and a crontab entry, which will launch the documentation script. To establish the client configuration, you must perform two steps. First, you must put the email address of the Web server into the configuration file /opt/RTCdoc/etc/makesuninfo.conf:

SERVERMAIL=suninfohtml@put.your.webserver.name.here

The email is described later in the display server section. The second step is to put the following lines at the beginning of the /etc/hosts file:

#Beschreibung: the description of the server
#Seriennummer: 3MX86
#
# internet host table

The first line is the description of the computer, and the second line is the serial number of the computer. The description will be displayed at the overview page of the display server. The serial number is useful if you have to call the support line.

What does the software do? The documentation script is started by cron at 3 a.m. on all computers where you have it installed. The documentation script creates the documentation in two files -- one in ASCII format and the other in HTML format. The ASCII file is saved on the local computer in /opt/RTCdoc/log/<hostname>.log. The last 30 copies are kept there. The HTML file is also saved on the local computer in /opt/RTCdoc/log/index.html. The HTML file is then sent to the central display server, where it is put in the Web space.

Server Part

In this section, I will describe the software for the display server, how it works, and the configuration of the software. The software for the display server is in tar format and is called server.tar. It consists of two parts -- the first part is the script that takes the email and puts it into the Web space, and the second part displays the overview on the Web server. For the display server, you need a computer with Sendmail, Perl, and a Web server software with php3 support (see http://www.php.net). I use a Solaris 2.6 with Apache.

How It Works

The first script takes the file from the email and saves it in the documentation directory. The name of the file is the hostname of the documented computer, which was sent in the subject of the email messages. Now, if you point your browser to the php3 HTML file on the display server, it reads all the descriptions in the directory and displays an overview of all computers with their descriptons. On this page, you can click on a computer to see its documentation.

Three steps have to be performed for the display server:

1. Untar the server.tar in /export on your display server.

2. Put the following entries in the /etc/aliases file and launch the newaliases command:

suninfohtml: "|/export/infosrv/bin/sunmailhtml"
hpinfohtml:  "|/export/infosrv/bin/hpmailhtml"

3. Web server documentroot = /export/infosrv/http.

4. Make sure the directory /export/infosrv/http/sunbeschreibung and hpbeschreibung are writeable to the mail user (chown mail *beschreibung).

Advanced Configuration of the Display Server

If you have more information for each computer in HTML format, or figures of the computers in image format, you can put these documents on the display server. If you put the HTML documents in /export/infosrv/http/sunspcl/<computer name>/index.html on the display server, a link will appear on the overview page pointing to the document.

Create a directory for each computer on the display server as following:

/export/infosrv/http/images/<computer name>

You must replace the "<computer name>" expression with the name of your computers. The directories and filenames have to be written in small letters.

Security Concerns

The documentation of your servers is now on the Web. From a security point of view, you must protect this information. You can do this by configuring the use of a username/password for the page access. Add the following lines in the httpd.conf file of your Apache Web server. This allows only the unixdoc user to access the unixdoc Web pages.

<Directory /export/infosrv/http>
AuthType Basic
AuthName admin
AuthUserFile /etc/httpd/users
require user unixdoc
</Directory>

To set up the unixdoc user, enter the following command, which will prompt you for a password:

# htpasswd -c /etc/httpd/users unixdoc
New password:
Re-type new password:
Adding password for user unixdoc

After restarting your Web server, you can only access the page by providing the username and password.Other security concerns focus on the unixdoc HTML file transmission from the client to the display server. For the transmission, you don't need any rhosts entry on either side. You don't even need a direct connection between the client and the display server. As long as the client reaches the display server by email, everything is fine because the client sends the unixdoc HTML file by email. For example, if you have a computer in a DMZ and if you don't allow any direct connection to your display server, just configure your Internet mailserver as the default mail relay on your DMZ computer. The DMZ computer will send the email to the gateway, which will send it to the display server. As explained previously, the way the client sends the unixdoc HTML files to the display server is very flexible and opens no security hole.

It is important to remember that the information displayed by the unixdoc display server is exactly the kind of detailed system data that an Internet intruder may be looking for. You must take every precaution to ensure that the display server and any related unixdoc files are well protected from attack. Password protection is only part of that security. The display server should not be accessible from the Internet and should only be used behind a secure firewall. Also, make sure the display server is configured securely and contains the latest Apache patches. unixdoc HTML files and other related files on the clients should also receive appropriate protections.

Conclusion

I wrote unixdoc a year ago at my job as UNIX systems administrator. We have more than 150 UNIX servers, and unixdoc was very useful for debugging. A future release will incorporate the following improvements:

View of the last 30 versions on the Web page
Linux support
Rearrangements of the index

The software can be found at:

http://www.net.li/article

Roman Marxer lives in Bern, Switzerland. He received a computer science degree from the University of Fribourg, Switzerland, in 1996. When not climbing the mountains, he is working as a UNIX systems administrator at Real-Time Center Bern. He can be reached at: roman@net.li.