documentation fixes

[John Leach <john@xxxxxxxxxxxxxxx>]

Hi Gianni,

I send you this patch in order to have your advice.

It fixes some typos, speeling errors, and, horror or horrors, some
illegally formed xml!

I also changed the docbook header thing, I'm not so sure if this is
totally correct but both jade and 4Suite tools are happy with it like
this.

John.
-- 
GPG KEY: B89C D450 5B2C 74D8 58FB A360 9B06 B5C2 26F0 3047
   HTTP: http://www.johnleach.co.uk

Index: firestorm-doc.xml
===================================================================
RCS file: /home/cvs/firestorm/doc/firestorm-doc.xml,v
retrieving revision 1.14
diff -u -r1.14 firestorm-doc.xml
--- firestorm-doc.xml	24 Jan 2003 14:00:35 -0000	1.14
+++ firestorm-doc.xml	29 Jan 2003 22:51:56 -0000
@@ -1,8 +1,10 @@
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[]>
+<?xml version='1.0'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd";>
 
 <book id="firestorm">
 <bookinfo>
-<title>Firestorm Network Intrustion Detection System</title>
+<title>Firestorm Network Intrusion Detection System</title>
   
 <authorgroup>
 	<author>
@@ -42,18 +44,17 @@
 <title>Introduction</title>
 <para>
  Firestorm is an extremely high performance network intrusion detection
- system (NIDS). At the moment it just a sensor but plans are to include
- real support for analysis, reporting, remote console and on-the-fly
- sensor configuration. It is fully pluggable and hence extremely
- flexible.
+ system (NIDS). At the moment it is just a sensor but plans are to include real
+ support for analysis, reporting, remote console and on-the-fly sensor
+ configuration. It is fully pluggable and hence extremely flexible.
 </para>
 <para>
- At the moment firestorm is still in early development, but a lot of the
+ At the moment Firestorm is still in early development, but a lot of the
  features you would expect of a sensor are already there.
 </para>
 <para>
- This guide aims to help you configure and use the firestorm intrusion
- detection system. It is the official and definitive source of firestorm
+ This guide aims to help you configure and use the Firestorm intrusion
+ detection system. It is the official and definitive source of Firestorm
  documentation. Accept no substitutes!
 </para>
 
@@ -104,9 +105,9 @@
 <title>Stateful Analysis</title>
 <para>
  Firestorm can analyse state information on the network. For now just IP
- fragements and TCP streams are analysed. Application layer state
- tracking, TCP stream reassembly and related stream tracking (eg:
- ftp-data connections) are planned for the near future.
+ fragments and TCP streams are analysed. Application layer state tracking, TCP
+ stream reassembly and related stream tracking (e.g: ftp-data connections) are
+ planned for the near future.
 </para>
 </sect3>
 <sect3>
@@ -148,7 +149,7 @@
 </para>
 <para>
  Firestorm (unlike other systems) can usually achieve full disk
- throughput when alerting. In fact, firestorm can saturate many
+ throughput when alerting. In fact, Firestorm can saturate many
  spindles simultaneously by balancing alerts between multiple spools.
 </para>
 <para>
@@ -163,8 +164,8 @@
 <title>Stormwall</title>
 <para>
  Stormwall is as yet unfinished. Its purpose is to monitor alert spools
- and perform actions when new elog files appear. The firestorm sensor
- notifies stormwall of changes to the spool. This program will
+ and perform actions when new elog files appear. The Firestorm sensor
+ notifies Stormwall of changes to the spool. This program will
  facilitate push-style remote logging. Both push and pull logging will
  be supported by version 1.0.0.
 </para>
@@ -191,7 +192,7 @@
 <para>
  The firestorm-nids program has one optional command line argument to
  specify the path to the configuration file. If firestorm-nids is run
- with no arguments it will default to /etc/firestorm.conf. The firestorm
+ with no arguments it will default to /etc/firestorm.conf. The Firestorm
  configuration file is an ASCII text file with UNIX line terminators. If
  a line is empty of begins with a hash (#) character it is ignored. It
  consists of zero or more lines of the format:
@@ -215,9 +216,9 @@
 <sect2>
 <title>firestorm_root</title>
 <para>
- This directive tells firestorm which directory to move to when run.
+ This directive tells Firestorm which directory to move to when run.
  All paths mentioned in the config file are relative to this path. You
- shouldn't run firestorm inside some directory which you later hope to
+ shouldn't run Firestorm inside some directory which you later hope to
  unmount ;)
 </para>
 <screen>
@@ -229,7 +230,7 @@
 <title>chroot</title>
 <para>
  Firestorm can run inside a so-called <quote>chroot jail</quote>, this
- prevents firestorm from being able to read files located outside the
+ prevents Firestorm from being able to read files located outside the
  jail. You will usually want to say yes to this for security reasons.
  Note that technically it is actually possible for a skilled attacker
  to break out of a chroot jail, nothing can replace code audit...
@@ -254,10 +255,10 @@
 </screen>
 <para>
  I will briefly enumerate the capture types currently supported by
- firestorm, and the usage of each. Note that although filenames are
+ Firestorm, and the usage of each. Note that although filenames are
  relative to the firestorm_root, you can still access files outside
- of the chroot. Also note that none of these plugins set promiscouous
- mode by themselves. You must enable promiscous mode yourself if you
+ of the chroot. Also note that none of these plugins set promiscuous
+ mode by themselves. You must enable promisucous mode yourself if you
  require it. This may be as simple as 'ifconfig ifname up promisc',
  see your OS vendors documentation for more details.
 </para>
@@ -266,7 +267,7 @@
 <para>
 Most people will want to capture from the live network with
 libpcap.  This plugin has only one option 'if' which is used to specify
-which interface to listen on. (eg: if='eth0' or if='any' to listen on
+which interface to listen on. (e.g: if='eth0' or if='any' to listen on
 all interfaces).
 </para>
 </sect3>
@@ -275,7 +276,7 @@
 <para>
  Firestorm can also capture from libpcap files, such as those created
  by  tcpdump or ethereal. This plugin also has only one argument 'file'
- to specify the filename. (eg: file='./captures/mynetwork.cap').
+ to specify the filename. (e.g: file='./captures/mynetwork.cap').
 </para>
 </sect3>
 <sect3>
@@ -287,8 +288,8 @@
  where 'if' is an interface to listen on and blocks is a number
  specifying how many blocks to use in the ringbuffer. Generally the
  higher this number the more memory is used and the less packets will
- be dropped - you can look in the firestorm log output to get an idea
- of how much memory (in kilobytes) it translates to. (eg: if='any'
+ be dropped - you can look in the Firestorm log output to get an idea
+ of how much memory (in kilobytes) it translates to. (e.g: if='any'
  blocks=128).
 </para>
 </sect3>
@@ -298,12 +299,12 @@
  This plugin is a hi-speed alternative to the pcapfile plugin and
  doesn't depend on libpcap. This plugin is recommended over and above
  pcapfile, although your mileage may vary. It takes the same arguments
- as pcapfile (eg: file='./myfile.cap').
+ as pcapfile (e.g: file='./myfile.cap').
 </para>
 <para>
  Actually most operating systems (including Linux) don't actually do
- readahead on mmap() accesses so if the data isn't being served up from
- your page cache (ie: actually being read in from disk) this will be
+ read-ahead on mmap() accesses so if the data isn't being served up from
+ your page cache (i.e: actually being read in from disk) this will be
  slower.
 </para>
 </sect3>
@@ -312,8 +313,8 @@
 <sect2>
 <title>effective_uid / effective_gid</title>
 <para>
- These directives are ignored unless firestorm is run as root, their
- purpose is to prevent firestorm from actually processing any data
+ These directives are ignored unless Firestorm is run as root, their
+ purpose is to prevent Firestorm from actually processing any data
  while running with a privileged EUID (effective user id). They take
  precisely one argument which is a numeric UID or GID respectively.
 </para>
@@ -329,7 +330,7 @@
  Firestorm is totally plugin based and cannot function without loading
  the required plugins. This directive allows you to specify paths to
  directories full of plugins to load. Note that you can load plugins
- from outside the chroot. For each directory specified firestorm will
+ from outside the chroot. For each directory specified Firestorm will
  attempt to load all plugin files contained therein, directories are NOT
  recursed.
 </para>
@@ -368,13 +369,13 @@
 <sect2>
 <title>logfile</title>
 <para>
- This directive is perhaps a misnomer. It essentially tells firestorm
- to daemonize and send all diagnostic messages to a logfile. The single
- argument is the path to the logfile. You will nearly always want to
- set this directive. Note that the logfile is overwritten every time
- that firestorm is run. It is only intended as a record of what happened
- last time firestorm was run for diagnostic purposes. If you do not set
- this directive, firestorm will not daemonize and output messages to
+ This directive is perhaps a misnomer. It essentially tells Firestorm
+ to daemonize and send all diagnostic messages to a log file. The single
+ argument is the path to the log file. You will nearly always want to
+ set this directive. Note that the log file is overwritten every time
+ that Firestorm is run. It is only intended as a record of what happened
+ last time Firestorm was run for diagnostic purposes. If you do not set
+ this directive, Firestorm will not daemonize and output messages to
  standard out (screen).
 </para>
 <screen>
@@ -387,20 +388,20 @@
 <para>
  Firestorm outputs alerts in elog format to a spool directory whose path
  is specified by the output directive. Firestorm can do automatic log
- rotation when the logs reach a specified filesize, or a certian amount
- of time has elapsed. Firestorm never rotates empty logs. Logfiles that
+ rotation when the logs reach a specified file size, or a certain amount
+ of time has elapsed. Firestorm never rotates empty logs. Log files that
  have been successfully spooled have names beginning with '@', they are
- guaranteed to be written to disk, and not-corrupt. The current logfile
+ guaranteed to be written to disk, and not-corrupt. The current log file
  takes the name 'alert.elog'. You should not read from or use this file
  it is not guaranteed to be in any particular state.
 </para>
 <para>
  The arguments for this directive are pretty self explanatory from the
  example below. One thing to take note of is that if the 'minutes'
- parameter is set to 0, firestorm won't rotate by time and if the 'size'
- directive is set to 0, firestorm won't rotate by size. If both are set
- firestorm rotates on whichever comes first. The buf parameter is more
- thoroughly explained in <xref linkend="hiperf-spool">.
+ parameter is set to 0, Firestorm won't rotate by time and if the 'size'
+ directive is set to 0, Firestorm won't rotate by size. If both are set
+ Firestorm rotates on whichever comes first. The buf parameter is more
+ thoroughly explained in <xref linkend="hiperf-spool"/>.
 </para>
 <screen>
 	output dir='log' minutes=60 size=512K stormwall=none buf=16k
@@ -410,10 +411,10 @@
 <sect2>
 <title>signatures</title>
 <para>
- The signatures directive tells firestorm where to load signatures from,
+ The signatures directive tells Firestorm where to load signatures from,
  you may load as many signature files as you wish. Currently the only
  supported signature format is snort. You can't put signatures, variables
- or anything snort related directly in to firestorm.conf.
+ or anything snort related directly in to Firestorm.conf.
 </para>
 <screen>
 	signatures snort ./snort-rules/classification.config
@@ -427,7 +428,7 @@
 <title>Advanced Configuration</title>
 
 <sect2 id="ipfrag">
-<title>IP Defragmentation</title>
+<title>IP De-fragmentation</title>
 <para>
  This plugin has two roles, the first is the de-fragmentation of
  fragmented IP datagrams and the second is to statefully detect IP
@@ -444,7 +445,7 @@
  In order to prevent denial-of-service attacks, the ipfrag module
  requires specifying an upper boundary on the amount of memory used to
  remember fragmented packets. Firestorm will allocate up to 'mem_hi'
- bytes of memory, when this threshold is hit, firestorm will prune the
+ bytes of memory, when this threshold is hit, Firestorm will prune the
  oldest packets until only 'mem_lo' bytes are used. This strategy is
  identical to that used in the BSD/Linux derived IP stacks. The default
  values are 1MB and 768KB respectively. These are very conservative
@@ -455,9 +456,9 @@
 <sect3>
 <title>minttl</title>
 <para>
- If firestorm is not sniffing directly from the same network as your
+ If Firestorm is not sniffing directly from the same network as your
  protected hosts then it is possible for an attacker to send IP
- fragments with low TTLs which the IDS will see but the target sytem
+ fragments with low TTLs which the IDS will see but the target system
  will not (as the packet gets dropped when the TTL expires). Setting
  this value will make ipfrag ignore packets with TTLs lower than the
  value. You will usually want to keep this as 0 (the default).
@@ -480,7 +481,7 @@
 <title>TCP Stateful Inspection and Stream Reassembly</title>
 <para>
  Firestorm can perform stateful inspection of TCP packets to avoid DoS
- attacks such as stick and snot. When enabled firestorm tracks TCP
+ attacks such as stick and snot. When enabled Firestorm tracks TCP
  sessions and maintains state information (including support for window
  tracking, PAWS, window-scaling, and many other TCP protocol options).
 </para>
@@ -504,8 +505,8 @@
 <sect3>
 <title>minttl</title>
 <para>
- Sets the minimum ttl value for which firestorm will examine TCP
- segments. See the discussion in <xref linkend="ipfrag"> for more
+ Sets the minimum ttl value for which Firestorm will examine TCP
+ segments. See the discussion in <xref linkend="ipfrag"/> for more
  information. By default this value is 0, don't fiddle with it
  unless you understand what your are doing.
 </para>
@@ -537,7 +538,7 @@
  The output directives in your firestorm.conf can make a massive impact
  on performance if applied well. You should be able to log almost
  anything and not worry about destroying sensor performance. The
- firestorm analysts approach should be to log anything that might matter
+ Firestorm analysts approach should be to log anything that might matter
  and just use the console to filter away the chaff. This goal is a long
  way off yet, but one component is already in place, world-class alert
  spooling performance. To configure this correctly you must first pay
@@ -546,15 +547,15 @@
 <para>
  The buf parameter sets how large the output buffer should be in bytes.
  The higher this value, the higher the throughput of alerts, and the
- less succeptible to denial-of-service attacks you become. The cost of
+ less susceptible to denial-of-service attacks you become. The cost of
  a high value however is reliability, there is a longer period of time
- where the logs are not written to disk and are lost if firestorm
+ where the logs are not written to disk and are lost if Firestorm
  crashes or is killed forcefully. However, the relatively small
- detrement to reliability can be amortized by setting log rotation size
+ detriment to reliability can be amortised by setting log rotation size
  or time limit.
 </para>
 <para>
- With firestorm it is possible to scale your alerting throughput right
+ With Firestorm it is possible to scale your alerting throughput right
  up to 'enterprise level' with very little hardware investment. Simply
  place one alert spool on each hard disk in your sensor - alerts will
  be balanced between them meaning that you only need add a couple of