
Installation instructions for NSYSLOGD
======================================

Welcome. This is nsyslogd, which stands for new syslogd, a new, enhanced
system logging daemon, capable of running under the following platforms:

  - Linux
  - BSD
  - SunOS/Solaris

Getting NSYSLOGD
================
Since nsyslogd has not yet been released to the public, and I haven't
decided distribution method yet, I can't write anything here. If you are
reading this message you have nsyslogd anyway...

Unpacking the distribution
==========================

The distribution arrives in .tar.gz format though OS/distribution packaging
is possible. The file is named:

  nsyslogd-x.xx.tar.gz

where x.xx stands for the version number. The first released version is
3.00b. You must have tar and gzip to unpack the distribution (sorry,
compress is not supported). If you have GNU tar simply execute the following
command:

	tar xvfz nsyslogd-x.xx.tar.gz

If your version of tar doesn't support z (most non-GNU tars), you should
execute this one:

	gunzip -c nsyslogd-x.xx.tar.gz | tar xvf -

After this, you'll get a directory named nsyslogd-x.xx, where the source for
nsyslogd will be unpacked.

Compiling the program:
======================
Cd to the nsyslogd-x.xx/src directory, and edit the Makefile & config.h
files for your platform. As soon as I have some time, I'll create an
autoconf script which automates this task, but you'll have to wait for that.
Both files are heavily commented, so you shouldn't have problem figuring the
necessary settings out.

After you made the necessary changes, issue "make" in the src dir. As the make
cycle finishes, you'll get three executables in the src directory:

   nsyslogd		- the main binary
   genh0		- generates initial hashes for log files
   checkhash		- checks if a given log file was modified or not

Now do a "make install" and you are done.

Configuration file:
===================
You can use nsyslogd with the old configuration file, though it will not
show you its more advanced features if you stick to that format. There's an
example perl script in the doc/ subdirectory which will convert your
existing config files to the new format, or you can write your own version.
The manpage for nsyslogd.conf(8) contains a reference about keywords and
syntax which can be used in the config file. For now I only explain system
dependencies.

Every unix version has a slightly different way of routing log messages, and
since nsyslogd gives you the power of choosing your log-sources, you have to
be aware some of the internals.

  Linux:
  ------
  Linux has a dedicated unix socket called /dev/log, where log messages are
  written to, and read from. It is of type SOCK_STREAM. So the correct source
  statement for standard linux log messages is:

      source stdlog { unix-stream /dev/log; };

  BSD:
  ----
  BSD is similar to Linux (or vice-versa Linux is similar to BSD, but this is
  another issue), so BSD has also a unix socket for log communication, but
  it's of type SOCK_DGRAM, and it is located at /var/run/log. So the source
  statement you are looking for is:

      source stdlog { unix-dgram /var/run/log; };

  Solaris (2.5.1 or below):
  -----------------------
  SunOS/Solaris has a universal means of communications called STREAMS. It is
  used in both kernel-mode and kernel-user interface. You'll need to feed the
  following statement to nsyslogd to accept all messages:

      source stdlog { sun-stream /dev/log; };

  Solaris (2.6 or up)
  -------------------
  Sun has added a new method to the pool of possible IPC mechanisms, and it
  is called door. NSYSLOGD supports this method with the sun-door keyword. A
  door is a special file in the filesystem, and is called /etc/.syslog_door.
  So your correct source statement would be:

      source stdlog { sun-door /etc/.syslog_door; };

Hashing:
========
nsyslogd supports hashing when transmitting messages via network, and when
storing messages on disk, so that any modifications made to the logfiles can
be detected. Currently nsyslogd uses the SHA1 hash algorithm.

  Network hashing:
  ----------------
  The traffic between two nsyslogd's can be protected by a hash. It is _NOT_
  encryption, it just prevents modifications. Hashing is only used if you
  are using TCP connections. Before transferring, the SHA1-sum of the
  to-be-transferred log message and a secret is calculated. This hash is
  then sent to the remote site after the log message, where the sum is
  recalculated, and checked for validity. If the check fails a warning is
  printed, but the log message is _not_ swallowed.

  As you can see both sides will need the shared secret which is stored in a
  0600 file named /etc/nsyslogd/secret.xxx.xxx.xxx.xxx where xxx.xxx.xxx.xxx
  denotes the remote IP address.

  Logfile digital signatures
  --------------------------
  NSYSLOGD keeps track of newly written messages to files, and calculates
  and stores SHA1 sum for them. This prevents modification of the logfile.

  Instead of one single file you'll have 4 files when using digital
  signatures:

      logfile      - stores log messages
      logfile.sha1 - stores hash values for each message
      logfile.H0   - last hast value
      logfile.salt - used when generating the first .H0

  Here is an outline how hashing works: the new hash will be the sha1-sum of
  the previous hash, the line number and the log message itself, this is
  then is saved to disk, and it will become the previous hash for the
  following line. The initial hash is the sha1-sum of a 128 byte salt, and a
  secret password. This way, the deletion of the log message and the hash
  value will still be detected! To detect unauthorized modification use the
  checkhash utility.

