Improving Online Documentation on Linux

Caldera OpenLinux 2.3 comes with the Apache httpd server as a standard component. However, by default, the Netscape home page, which leads to on-line documentation, is configured to load using a file:// URL, rather than being loaded through the web server. This has always struck me as disappointing; it means that one misses out on the ability to run CGI scripts to do things like searching the online documentation, or viewing the online documentation on a second machine while working at the first.

All of which led me to investigate the contents of the /home/httpd/cgi-bin directory. What's this? A file called man2html? Another called info2www? And what about accessing the online guides - the HOW-TO's, Network Administration Guide, and the rest - which give an access denied error when you try to access them using an http:// URL?

Let's deal with each of these in turn:

man2html is a program which can convert man pages to HTML. Running it from the command line produces an error message, but the solution is simple:

mkdir /var/man2html

chown nobody:nobody /var/man2html

creates the required working directory.

info2www does the same thing for GNU info pages.

Now, to get access to these two utilities, you need to modify one of the pages on the server. I edited the home page, /home/httpd/html/index.html, and added these lines:

<ul> <li><a href="/cgi-bin/man2html">On-line man pages</a>
<li><a href="/cgi-bin/info2www">On-line GNU info</a>
<li><a href="/java/">JDK 1.1.8 Documentation</a>
<li><a href="/cgi-bin/rpm_query">RPM Info</a>
</ul>

(The JDK Documentation is something that I added).

Now, what about those errors in getting to the other online docs? It turns out that Apache is configured not to follow the symbolic links which make the various documentation directories appear to be under /home/httpd/html/openlinux_help. This is a security precaution, to avoid local users exploiting a security vulnerability. In practice, there is a workaround which will allow Apache to follow the symbolic links without weakening security significantly. Edit /etc/httpd/apache/conf/access.conf and scroll down to the stanza that begins <Directory /home/httpd/html>. Now add a line under that one, that reads

Options SymLinksIfOwnerMatch

This means that Apache will follow the symbolic link if the owner of the target directory is the same as the owner of the symbolic link. Now stop and restart Apache, with the commands:

/etc/rc.d/init.d/httpd stop

/etc/rc.d/init.d/httpd start

and you should now be able to read the online documentation by going to the URL http://localhost and following the links. You should also be able to look up man pages and browse the GNU info documentation. The only remaining problem is a broken symbolic link to the mini-HOWTOs - you can fix this with the following commands:

cd /home/httpd/html/openlinux_help/HOWTO

rm mini

ln -s /homr/httpd/html/localdoc/HOWTO/other-formats/html/mini

The mini-HOWTOs should now be accessible

This technique will work for Caldera OpenLinux 2.2, but it will not work for OpenLinux eDesktop 2.4, where the httpd cgi-bin directory is empty. man2html is provided in the /usr/sbin directory, but info2www is no longer supplied. However, info2www can be obtained from http://www.math.psu.edu/info2www/info2www.html.

A cautionary note: the info2www script has turned up in the list of files that some CGI vulnerability scanners look for, so obviously somebody thinks that it represents a vulnerability. For this reason, you probably don't want to use this technique on Internet-accessible hosts.
Page last updated: 15/May/2001 Back to Home Copyright © 1987-2010 Les Bell and Associates Pty Ltd. All rights reserved. webmaster@lesbell.com.au

...........................