Welcome to the sysklogd package for Linux.  All the utility
documentation has now been moved into the man pages.  Please review
these carefully before proceeding.

Version 1.3 of the package is the culmination of about two years of
experience and bug reports on the 1.2 version from both the INTERNET
and our corporate Linux networks.  The utilities in this package should
provide VERY reliable system logging.  Klogd and syslogd have both
been stress tested in kernel development environments where literally
hundreds of megabytes of kernel messages have been blasted through
them.  If either utility should fail the development team would
appreciate debug information so that the bug can be reproduced and
squashed.

Both utilities (syslogd, klogd) can be either run from init or started
as part of the rc.* sequence.  Caution should be used when starting
these utilities from init since the default configuration is for both of
these utilities to auto-background themselves.  Depending on the
version of init being used this could either result in the process
table being filled or at least 10 copies of the daemon being started.
If auto-backgrounding is NOT desired the command line option -n should
be used to disable the auto-fork feature.

I have found work on the sysklogd package to be an interesting example
of the powers of the INTERNET.  Stephen, Juha, Shane, Martin and
myself have successfully collaborated on the development of this
package without ever having met each other, in fact we could pass on
the street without realizing it.  What I have developed is a profound
respect for the personal capabilities of each one of these
individuals.  Perhaps the greatest `Linux Legacy' will be that its
development/enhancement is truly an example of the powers of
international cooperation through the worldwide INTERNET.

We would be interested in keeping track of any and all bug
fixes/changes that are made.  At the time that work was started on the
sysklogd package the syslog(d) sources seemed to have fallen into
neglect.  This work started with and continues the believe that it is
important to maintain consistent standardized system utilities
sources.  Hopefully the Linux community will find these sources to be
a useful addition to the software gene pool.

There is a mailing list covering this package and syslog in general.
The lists address is sysklogd@Infodrom.North.DE .  To subscribe send a
mail to Majordomo@Infodrom.North.DE with a line "subscribe sysklogd"
in the message body.

New versions of this package will be available at Joey's server.
  http://www.infodrom.org/projects/sysklogd/

Best regards,

Dr. Wettstein
Oncology Research Division Computing Facility
Roger Maris Cancer Center
Fargo, ND
greg@wind.enjellic.com

Stephen Tweedie
Department of Computer Science
Edinburgh University, Scotland

Juha Virtanen
jiivee@hut.fi

Shane Alderton
shane@ion.apana.org.au

Martin Schulze
Infodrom Oldenburg
joey@infodrom.org

And a host of bug reporters whose contributions cannot be underestimated.


Very important information before using version 1.3
---------------------------------------------------

The included version of syslogd behaves in a slightly different manner
to the one in former releases.  Please review the following important
differences:

* By default the syslog daemon doesn't accept any message from the
  syslog/udp port. To enable this add "-r" to the command-line
  arguments. You _have to_ add this on every host that should run as a
  centralized network log server.

  You also should take a look at other new command-line arguments:
  "-l" and "-s".

  The syslog daemon by default does not forward to a remote host any
  log messages which it received from a remote host.  This is an
  attempt to prevent syslog loops.  If you desire this behavior the
  -h command-line switch can be used to enable this behavior.

* Syslogd was designed to strip off the local domain from every
  message that comes from any host in the same domain. Unfortunately
  this feature didn't work in every cases. This is now corrected. So
  you might not get the fqdn anymore.

  If you use any scripts that analyze logfiles, please bare this in
  mind.

* Syslogd doesn't touch the filemode of any logfile. If it has to
  create one, it will be world-readable. If you do not want this
  (i.e. if auth.* is logged) you have to create the file by hand and
  change permissions.

* If you notice that some of your programs make heavy use of the
  syslog facility and your disks get loud you might want to turn
  fsync()ing after each line off. But note that in doing so you
  increase the likelihood of lost information in the event of a
  system crash.

* If you're going to start klogd or syslogd by init(8), you don't have
  to hack the code anymore. Instead add "-n" to the command-line
  arguments.

* Klogd can now be used to decode EIP addresses if it can determine a
  System.map file (command-line argument "-k"). This is a very useful
  feature if your system crashes, but its usability depends on an
  actual and correct System.map file.

* Both system utilities now check for and respect the existence of .pid
  files.  If the utilities are started by configuration scripts on
  stable systems there is the potential that the process ID numbers of
  the utilities will be identical from one system boot to another.
  This will cause both klogd and syslogd to terminate.

  Both klogd and syslogd will attempt to remove their .pid files when
  they receive termination signals.  The difficulty noted above
  typically occurs when a system crash occurs or an uncatchable signal
  (kill -9) is used to stop the daemons.

  The cleanest solution to this problem is to insure that the system
  configuration scripts (rc.*) provide a clean working environment for
  a freshly booted system.  As part of the initialization process
  these scripts should remove all old .pid files found in /var/run.
  This will insure that klogd and syslogd start properly even if prior
  executions have been terminated harshly.


The following important changes have been reported by the developers:

Version 1.3 Patch Level 3

General. ------------------------------------------------------------------
Update to documentation including klogd.8 manpage to reflect new features.

Included patch for modules-2.0.0 package to provide support for signalling
klogd of changes in kernel module status.

klogd ---------------------------------------------------------------------
Provided support for signalling klogd to reload static and kernel module
symbol information via SIGUSR1 and SIGUSR2.

Implemented -p switch to cause a reload of kernel module symbol information
whenever a protection fault is detected.

Informative message is printed whenever klogd state change occurs.

Added -i and -I switches to signal the currently executing klogd daemon
to reload symbold information.


Version 1.3 Patch Level 2

General. ------------------------------------------------------------------
Added oops.c and oops_test.c.  Oops.c implements a kernel loadable module
which will generate a general protection fault.  The oops_test.c program
generates a test program for exercising the loadable module.

syslogd ------------------------------------------------------------------
Fixed bug resulting in file descriptors being orphaned when syslogd was
initialized via signal handler.

klogd ---------------------------------------------------------------------
Bug fix to prevent errors when reading symbol tables with 64 bit addresses.

Added support for debugging of protection faults occuring in kernel
loadable modules.


Version 1.3 Patch Level 1

General. ------------------------------------------------------------------
Cleanups in the Makefile.

Patches to support compilation in the ALPHA environment.  I have not
been able to test these personally so if anyone has any feedback I
would be interested in hearing from the Linux ALPHA community.

Spelling and grammar corrections in the man pages.

syslogd ------------------------------------------------------------------
Patch to fix parsing of hostnames in syslogd.c.

The return value of gethostbyname is now properly checked.  This should
fix the problems with core dumps when name resolution failed.

Bounds error fixed when setting the file descriptors for UNIX domain
sockets.

klogd ---------------------------------------------------------------------
Error checking and reporting enhanced.  I have a couple of reports
that klogd is experiencing errors when reading the /proc filesystem.
Any additional information would be appreciated.

The sys_syslog function has been renamed to ksyslog.  This was in a
set patches for ALPHA support so I am assuming that this is necessary
for that environment


Version 1.3 

Numerous changes, performance enhancements, code cleanups and bug fixes.
Too many to individually summarize.  Have a look at the top of each
source file for more information.

** Default behavior of sysklogd is not to accept any message that
is sent via syslog/udp.  To allow remote reception add -r to the
command-line arguments.

** Spaces are now accepted in the syslog configuration file.  This
should be a real crowd pleaser.

syslogd now uses dynamic allocation of logging output descriptors.
There is no longer a static limit on the number of log destinations
that can be defined.

klogd supports on-the-fly kernel address to symbol translations.
This requires that a valid kernel symbol map be found at execution.

** The default level for console log messages was changed to 6.  This
means that kernel messages with a priority less than or equal to 5
(KERN_NOTICE) will be logged to the console.

	This item has been flagged because it results in a behavior
	change which will be different if version 1.3 replaces an
	existing 1.2 binary.  Linus strongly suggested that this
	behavior be changed and in the 1.3.3x kernels Linus in fact
	made it impossible to set the console log level lower than
	about 5.

	There were good reasons from his perspective for doing so.
	The most troublesome being that user's of packaged
	distributions were not able to generate register dumps with
	the kernel debugging keys, most notably altgr-SCRLCK.

	If a kernels prior to 1.3.3x are being used the klogd daemon
	invocation must be changed to something like: klogd -c 1
	
	This will turn off logging of kernel messages to the console.
	If you understand the ramifications of this the 1.3.3x kernels
	can be patched to allow the suppression of console log
	messages.  It is important to be cognizant of the effects of
	these changes.  None the least of which is that Linus and Alan
	will yell at you if you complain about not being able to
	generate kernel debugging information.. :-)

---------------------------------------------------------------------------
Version 1.2
Fixes to both klogd and syslogd so that the package will compile without
errors due to the vararg procedures.

Modified pid files produced so that the names of the files are
klogd.pid and syslogd.pid respectively.

Fixed bug in klogd which prevented output from being directed to a file
when the program was compiled to auto-background itself.  In the
auto-backgrounding configuration the forked process was closing all its
file descriptors which was causing the errant behavior.

Modified signal handling in klogd so that all signal are set to ignored
before establishing specific signal handlers.

Fixed bug in syslogd which was causing a delay in opening of the /dev/log
UNIX domain socket.  This should correct the race condition which was
preventing klogd from properly logging kernel messages when the two
daemons were started in rapid succession.

Modified the closing/opening of file descriptors when syslogd was
compiled with auto-backgrounding support.  Closes the potential for
a somewhat obscure bug caused by the /dev/log socket being opened on
fd 0.

Changed the names of the man pages from an extension of 1 to 8.
---------------------------------------------------------------------------
Version 1.1
Extensive changes and additional functionality added to klogd.  Please
see sources and man-pages for documentation.

Fixed bugs in both syslogd and klogd with respect to fragmented
message re-assembly.  Bootup messages should now be display properly.

Fixed bug in syslogd which prevented proper logging of messages with
priority classes of none and emerg.

Fixed bug which caused core dump when messages were logged to users.
Also fixed bug with messages to login type of LOGIN.

Fixed problem with zombies being left when messages were logged to
multiple users.

Enhanced functionality of syslog_tst program.

Added man-pages.
---------------------------------------------------------------------------

---------------------------------------------------------------------------
Version 1.0

Initial release.
---------------------------------------------------------------------------

Additional information about system logging
-------------------------------------------

 . When logging into a fifo syslogd will stop loggin into this
   logfile if no process is reading it and thus the buffer is filled
   up.  Buffer size can be adjusted through the kernel.

 . When using the Perl5 Sys::Syslog module (use Sys::Syslog;) to
   provide logging to your Perl programs, please notice that since it
   will open a UDP connection to the local syslogd you'll need to have
   remote receiption enabled.

   Joey Hess teaches us how to change this behaviour and switch to
   using the Unix domain socket.  After the opening with "use" you
   have to add "Sys::Syslog::setlogsock('unix');".

   The default behaviour might change in future releases of Perl.

Modifying the kernel console log level
--------------------------------------

  There are two ways to alter the kernel console log level.  This
  setting controls whether log messages from the kernel should appear
  on the system console or not.

  In the past, klogd had to do this with the -c parameter.  Using '-c
  4' will set the log level of console messages to 4 and only display
  warnings and errors but not regular debug or information messages.

  This behaviour is deprecated and hencely not enforced anymore via
  the RC script of klogd.  Instead sysctl(8) should be used as
  interface to various kernel variables.  These can be stored
  non-volatile in /etc/sysctl.conf.

  The prevent the kernel to flood the system console and to achieve
  the same behaviour of '-c 4' simply add the following to the
  configuration file and let sysctl set this kernel parameter upon
  system boot.

  kernel/printk = 4 4 1 7


