Documenting NST

Background

There are many types of documents associated with the NST project.

• The NST Wiki (http://wiki.networksecuritytoolkit.org/) contains a lot of the documentation related to the project and is the easiest to maintain.
• The NST Web User Interface (WUI) contains a lot of documentation within the tools used to manage the NST. These are found in the nstwui package on a NST system.
• The DocBook documents associated with each NST script. These are primarily used for man page and HTML rendered output.
• The static HTML web pages resembling the NST WUI. These are found on the Internet at: http://www.networksecuritytoolkit.org/. These are also found on a NST system in the nstweb package.
• The static DocBook documents (found under the docs sub-directory on a development system). These documents tend not be maintained and become outdated.

Requirements

Building NST Documentation

In order to build the static NST documentation, you need to run the top level configure script with the --on-line-docs option:

./configure --on-line-docs

The above command will make the following changes to your build system:

• It will change the way the nstweb package is built.
• It will enable the building of the DocBook documents found under the docs/ sub-directory.

After configuring your development environment for the purpose of building the NST documentation, you should be able to run the following command to build the static NST documents:

make docs

By default, the documents will be placed under the directories tmp/public_html/nst and tmp/public_html/nstwui under the source directory.

After you are done building documentation, make sure you run a top-level ./configure to reset the system so that the nstweb and nstwui packages will be built correctly for inclusion on a ISO build.

Viewing The Documents

To view the results of a local build of the Documentation, you will need to add a Apache configuration file /etc/httpd/conf.d/nstweb.conf. You will need to set the Directory and Alias values to match the output directory of your build. The example below is for a output directory of /opt/trunk/tmp/public_html/nst:

# nstweb - A snapshot (typically reduced) of the 
# www.networksecurity.toolkit web site.
# 
# Requires NST authentication and SSL access if not on localhost

#<Directory /usr/share/nstweb/>
<Directory /opt/trunk/tmp/public_html/nst/>
  DirectoryIndex index.php index.html
  Options Indexes FollowSymLinks -ExecCGI -Includes
  Order allow,deny
  Allow from all
</Directory>

Alias /nst /opt/trunk/tmp/public_html/nst
Alias /nstweb /opt/trunk/tmp/public_html/nst

After creating the above configuration file, you will need to restart the web server:

[root@dhcp132 ~]# service httpd restart
Stopping httpd:                                            [  OK  ]
Starting httpd:                                            [  OK  ]
[root@dhcp132 ~]# 

At this point you should be able to review the documentation using a web browser. Use the URL of "http://IP_ADDRESS/nst" where IP_ADDRESS is the IP address of your development system.

Building Just DocBook Documents

You can build portions of the documentation individually.

To build JUST the DocBook documents:

[root@dhcp132 trunk]# cd docs
[root@dhcp132 docs]# make
... Lots of output as documents are built ...
[root@dhcp132 docs]# 

As the DocBook documents can take a long time to build, you may find yourself in the situation where you're saying "Dang, I wish there was a way to just build this one document!" Well, your lucky day has come. You can invoke "make help" under the docs directory (be prepared to pipe this into less) to see all of the individual documents that can be built. To use this feature, you should run: "make setup" at least once (this will install the shared files for you). For example, to build JUST the HTML version of the wepquest document:

[root@dhcp132 trunk]# cd docs
[root@dhcp132 docs]# make setup
... Lots of output to screen ...
[root@dhcp132 docs]# make wepquest.html
(cd /opt/trunk/tmp/public_html/nst/docs/wepquest && /usr/bin/xsltproc /opt/trunk/docs/chunk.xsl "/opt/trunk/docs/wepquest/book.xml" >| "/opt/trunk/tmp/public_html/nst/docs/wepquest/index.html")
Writing ar01s02.html for section
Writing ar01s03.html for section
Writing ar01s04.html for section
Writing bi01.html for bibliography
Writing index.html for article
[root@dhcp132 docs]# firefox ../tmp/public_html/nst/docs/wepquest/index.html

Building Just The HTML Documents

If your development environment is set up correctly, you can build and view just the static HTML documents using the following commands:

[root@dhcp132 trunk]# cd html
[root@dhcp132 html]# make
... Lots of output ...
[root@dhcp132 html]# firefox http://127.0.0.1/nst

Tweaking the DocBook HTML Output

It took a long time to figure this out, but we finally managed to adjust the output of the HTML pages generated when compiling DocBook files. In order to do this, we needed to:

• Create a custom chunk.xsl style sheet.
• Create a custom docbook.css file - which controls how the various parts of a document are rendered.
• Create and install auxiliary files (bitmaps) referenced by the above two files.

The docs/chunk.xsl File

In order to tweak the HTML produced by our DocBook source files, we needed to create a custom XSL style sheet. This custom file includes the normal DocBook formatting rules, and then adjusts a few settings to our liking (we were particularily interested in the inclusion of a custom CSS file). The docs/chunk.xsl is built from code within the docs/configure shell script. If you want to make permanent changes, you will need to modify docs/configure. The following shows the contents of docs/chunk.xsl at the time this document was created:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>


 <xsl:import href="file:///usr/share/sgml/docbook/xsl-stylesheets-1.75.2/xhtml/chunk.xsl"/>


 <xsl:param name="html.stylesheet">../docbook.css</xsl:param>


 <xsl:param name="header.rule" select="0"></xsl:param>
 <xsl:param name="footer.rule" select="0"></xsl:param>


 <xsl:param name="make.graphic.viewport" select="1"></xsl:param>
 <xsl:param name="ignore.image.scaling" select="1"></xsl:param>


 <xsl:param name="ulink.target" select="'_self'"></xsl:param>


 <xsl:param name="entry.propogates.style" select="1" />
 <xsl:param name="emphasis.propogates.style" select="1" />
 <xsl:param name="para.propogates.style" select="1" />
 <xsl:param name="phrase.propogates.style" select="1" />


 <xsl:param name="html.cleanup" select="1" />
 <xsl:param name="make.valid.html" select="1" />


 <xsl:param name="callout.graphics" select="'1'" />
 <xsl:param name="callouts.extension" select="'1'" />
 <xsl:param name="callout.graphics.path" select="'../images/callouts/'" />

 <xsl:template name="user.head.content">
    <meta xmlns="http://www.w3.org/1999/xhtml" http-equiv="Content-Type"
                           content="text/html; charset=UTF-8" />
 </xsl:template>

</xsl:stylesheet>

There are many "dials" that can be adjusted in the docs/chunk.xsl file. To learn more about these various settings, read the DocBook HTML Parameter Reference. Also, you may want to try searching Google for Customizing DocBook XSL stylesheets.

The docs/docbook.css File

If you examine the docs/chunk.xsl, you'll notice that it specifies a custom html.stylesheet. This CSS file is found at docs/docbook.css and controls the colors, fonts and formatting of the HTML pages.

There are several things that should be noted in the docs/docbook.css file:

• Colors can be applied based upon the original DocBook type. For example, the pre.screen adjusts the color settings for <pre> sections of the resulting HTML documents, but only if they are given the class of screen. To find the class of DocBook output, one needs to review the raw HTML produced by DocBook. Hint: Try viewing the source of this page and then search for the string programlisting.
• The pre.programlisting defines a bitmap to be used for the background. The reference to the bitmap is relative to the location of the docbook.css file. Hence, the developer needs to be careful when adding bitmaps. It involves not only creating the actual bitmap, but also updating the make rules such that it will be installed in the proper location.

Adding New DocBook Documents

Since the DocBook generated documents tend to be static, they tend to become dated very quickly. Because of this, our general philosophy has been towards moving away from DocBook generated documents and creating new documents within the NST Wiki. So, the general rule of thumb is: "Don't create new DocBook documents".

If you find yourself in a unique situation and really need to introduce a new DocBook document to the Network Security Toolkit project, there are a few basic steps to follow:

• Create a new sub-directory for your document under the docs directory.
• Create the DocBook file book.xml and place it in your new sub-directory.
• Install any supporting XML or image files for your document into the new sub-directory.
• Run the configure script found in the docs directory to update the Makefile rules for your new document.
• Run make setup to prepare the system to build your new document.