README

NEWSYSLOG -- A portable and enhanced version of this old standard

This file:  Copyright (C) by Planix, Inc.
	    see COPYING for details

This is an updated version of a package put together by Theodore Ts'o ,
of MIT Project Athena (which is included in NetBSD, FreeBSD, OpenBSD,
and probably other OS' too).

What does this version of newsyslog have to offer over others?

	- It is more portable (using GNU Autoconf) and it can be
	  compiled and installed on most any modern Unix or Unix-like
	  system.

	- It has support for fixed time-of-day daily archiving with a
	  command-line option to identify the daily roll-over invocation
	  (which may be at midnight, or at any other regular daily time).

	- It supports the FreeBSD feature that allows specification of
	  the log roll-over time as a daily, weekly, or monthly interval
	  (with optional time-of-day specification for the last two).
	  [The other overly flexible, ISO 8601 interpretation of the
	  interval "@" option is not supported -- it is too generic and
	  not meaningful enough in the context of log file management.]

	- It supports optional PID files so that non-standard daemons
	  can be told to re-open their logfiles after archiving has
	  taken place.  (Including /dev/null which disables signalling
	  of any daemon when the specified log file is rolled over.)

	- It can send a signal other than SIGHUP to the daemon
	  associated with a given log file.

	- It can leave the most recently archived log file uncompressed,
	  which is necessary for daemons like httpd and smail because
	  they continue to write to the current log file until their
	  current jobs have completed.  (This also makes it much easier
	  to review recent log data with normal Unix tools.)  [NetBSD
	  now has this feature.]

	- It supports the FreeBSD feature of being able to restrict
	  processing to just those log files specified on the command
	  line.

	- Unlike the NetBSD version it first parses the config file
	  before taking any action, meaning that if any errors are
	  encountered it will report them and quit without doing
	  anything.

	- Unlike the FreeBSD version, it will roll a log file if
	  *either* the interval or size limits have been reached
	  (FreeBSD's version makes it too easy to have a rapidly growing
	  log file overflow the filesystem).

	- Unlike the NetBSD version it always creates any missing log
	  file (though this can be disabled on a per-file basis).

	- It uses an advisory lock on the current configuration file to
	  prevent multiple invocations from tripping over each other.

	- The documentation is far better!

(For more specific details and recent changes see the NEWS file.)


TO BUILD NEWSYSLOG

Normally you should just follow the instructions in the INSTALL file
unless special instructions below apply.


TO BUILD NEWSYSLOG on *BSD SYSTEMS

If you are building newsyslog on a BSD-based system you can also use
"Makfile.BSD".  This is in fact necessary if your system requires
installation of pre-formatted manual pages (otherwise you'll have to
install them by hand).  The simplest way to do this is to run the
"newsyslog2netbsd.sh" script, then go into the "import.d" directory
created by the script, check the Makefile and possibly update the
default options in it, and finaly then simply run "make".  Note that if
you want to change the location of the install, or other pathnames then
you should change them in the "newsyslog2netbsd.sh" script *before* you
run it:

	# inspect and/or edit newsyslog2netbsd.sh
	sh newsyslog2netbsd.sh
	cd import.d
	# inspect and/or edit Makefile
	make
	make install

The same procedure should work fine for FreeBSD if you add
"__FreeBSD__=1" to the make commands above.  OpenBSD may masquerade well
enough as NetBSD, w.r.t. how makefiles work anyway, for OpenBSD users to
pretend while running make that they are using NetBSD.  :-)

If you actually do copy the contents of the import.d directory into your
system source tree to replace your native newsyslog then you should add
the appropriate __*BSD__ definition to the Makefile.

Of course newsyslog can also be built using the GNU Autoconf based build
system and a ``normal'' (i.e. Unix compatible) "make".

Please see the file "INSTALL" for overall instructions on how to
configure and build this package using the GNU Autoconf generated
"configure" script.

In general you need only run the following command sequence:

	./configure && make && make install

(see "CUSTOM CONFIGURATION OPTIONS" below for other "configure" options)


BUILDING ON SYSTEMS WITHOUT TROFF "doc" MACROS (including Solaris)

On systems without the "doc" macros (or without "nroff", or even with
just an incompatible version of "soelim"), you can still install and
read the distributed 'cat'-table manual pages.

For example if you get an error during the first "make" that says
something like "nroff: Cannot find library -mdoc", or "nroff: not
found", or "-I: No such file or directory", then run the following
command instead of running "make install":

	make copy-dist-mans install

This does not guarantee your "man" command will be able to find and
present the resulting files, of course.  If you really get into a bind
over this the best I can suggest is to write a small "wrapper" manual
page using the old-style man(7) macros that directs readers to view the
pre-formatted file in whatever location it gets installed in.  On some
systems you might be able to fool the "man" command into displaying the
pre-formatted version if you supply a dummy nroff source file that has
an older timestamp than the pre-formatted file.  Fooling "catman" to get
a proper index entry for "apropos" ("man -k") might be harder, but on
most systems the index file is just plain text (though in some
particular sorted order and with each line having a specific format).
If anyone wants to contribute a "mdoc" to "man" translator, I'm all for
it, but I will not try to maintain documents in both formats
simultaneously -- whatever support for "man" there is, it must be
completely mechanical and automatable.


CUSTOM CONFIGURATION OPTIONS

You may choose to use GNU Zip in preference to the default compress
program as the archive compression too with:

	./configure --with-gzip

WARNING:  If you have previously configured newsyslog without the above
option and now wish to add it you will have to remove ./config.cache
first to prevent the wrong program pathname from being used.

Beware that you may need to specify exactly where your syslogd keeps
it's PID file.  This can be done either by specifying an alternate
directory prefix to ./configure in this way ("/run/syslog.pid" will be
appended to the directory name given):

	./configure --localstatedir=/var

or by specifying an explicit pathname to ./configure in this way:

	./configure --with-syslog_pid=/var/run/mysyslog.pid

The default configuration file location can be modified by specifying an
alternate directory to ./configure in this way ("/newsyslog.conf will be
appended to the directory name given):

	./configure --sysconfdir=/etc

or by specifying an explicit pathname to ./configure in this way:

	./configure --with-newsyslog_conf=/etc/newsyslog.conf

Try './configure --help' for more options.


FOR MORE INFORMATION

If you have any troubles, questions, or feature requests, please send
mail to <bugs@robohack.planix.com>.  The lastest version of this
software is available at:

	<URL:ftp://ftp.planix.com/pub/Planix/newsyslog.tar.gz>

or:

	<URL:ftp://ftp.weird.com/pub/local/newsyslog.tar.gz>


-- 
						Greg A. Woods
						<woods-newsyslog@planix.com>
						<woods-newsyslog@robohack.ca>
						<woods-newsyslog@weird.com>


#ident	"@(#)newsyslog:README:$Format:%D:%ci:%cN:%h$"