Automatic UNIX Documentation with unixdoc
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
9. Disk Hardware
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:
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.
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:
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
#Beschreibung: the description of the server
# 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.
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
2. Put the following entries in the /etc/aliases file and
launch the newaliases command:
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
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
You must replace the "<computer name>" expression
with the name of your computers. The directories and filenames have
to be written in small letters.
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
require user unixdoc
To set up the unixdoc user, enter the following command, which will
prompt you for a password:
# htpasswd -c /etc/httpd/users unixdoc
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.
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:
The software can be found at:
- View of the last 30 versions on the Web page
- Linux support
- Rearrangements of the index
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: email@example.com.