[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

PROPOSAL: dpkg-logger and related



This is my official proposal in regards to the dpkg-logger program and
related info.

-- 
-----    -- - -------- --------- ----  -------  -----  - - ---   --------
Ben Collins <b.m.collins@larc.nasa.gov>                  Debian GNU/Linux
UnixGroup Admin - Jordan Systems Inc.                 bcollins@debian.org
------ -- ----- - - -------   ------- -- The Choice of the GNU Generation

                                           Ben Collins <bcollins@debian.org>
                                                             January 7, 1998
                                                Rev 1.0.2 (Initial Proposal)

----------------------------------------------------------------------------
          Proposal for Logging Features in Debian Package System
----------------------------------------------------------------------------

Purpose:
To establish guidelines and methods that allow our current, as well as any
future package system, to log output for archiving and later use by the
admins and users of Debian's distributions.

Where we are now:
Currently we have no means of directing output from the package system to a
log file for later perusing or archival. This results in missed messages
from large installations and updates, as well as forcing the user installing
Debian to monitor all the package system activity for possible problems.
This lack of logging is also a set back for future plans of a non-
interactive installation.

What this proposal hopes to accomplish:
The guidelines and methods proposed in this document are intended to serve
as a starting point to solve the problems outlined above. It is not the
intention of the author to promote this as the end all solution. However,
the methods outlined below are intended to give the package scripts a one
time interface to logging, so that only the logging back-end (later referred
to as dpkg-logger) should ever need modifying. Thus this method, if
implemented properly, will be the most extensible, with the least amount of
effort.

----------------------------------------------------------------------------

What is it?
The system revolves around a single program, dpkg-logger. Currently this is
a perl script, but could be replaced by a binary or other script language
at any time during it's life as a Debian tool. The program is intended for
use by the package scripts (postinst, postrm, prerm, preinst) to log
information that would normally be sent to the screen during package
installation, removal, or updating. The user could then later scan the log
for interesting occurrences and be able to resolve any issues from the
action.

How it works:
The dpkg-logger program can be used in several ways. The primary intention
is to replace the 'echo' command normally used in package scripts to
convey information to the user. This information could be configuration
defaults that the user may wish to change later, or warnings of a possible
problem. Either way it is important that the user retain this information
without having to manually retain it by memory or special methods.

Example pre-logging script:
# postinst for package foo
if [ -f /etc/foo.conf ]
then
	echo Configuration file already present, you may wish to check \
        	it's contents
fi
#end postinst for package foo

Example logging script (modifed from the one above):
# postinst for package foo
if [ -f /etc/foo.conf ]
then
        dpkg-logger --stdout 'foo' 'info' Configuration file already \
        	present, you may wish to check it's contents
fi
#end postinst for package foo

The second script will do 2 things, add the message to the logging facility
provided by dpkg-logger and send the output to stdout for the user to see.
The --stdout option supplies the stdout feature, --stderr is also an
option. The first argument, 'foo', is the name of the package. This allows
the dpkg-logger to attribute this message with the originating package. The
second argument, 'info', is the level of importance for this message.
Possible levels are:

info	Used for informational purposes. These messages are not necessarily
	problems, but the user may be interested to know about it.

warn	Used for when problems occur that may affect the usability of the
	package being installed. The error may or may not be important, but
	the package would like to make sure the user checks into it
        manually.

error	If something happens during the install script that is considered a
	failure to make the package usable, it should be logged with this
        level. The user will have to review this message and resolve the
        problem manually (as well as possibly reporting a bug for the
	failure). If an output option is specified, it should be --stderr.

debug	This is strictly for internal use by the package maintainer and
	should not be present in released packages

The levels make it easy for the user to configure the back-end system to
only log the type of messages they consider usable. This is why it is very
important for the level usage guidelines to be adhered to by the package
maintainers.

Where does this info go?
The current dpkg-logger (v1.0.5 at the time of this proposal's writing)
which is not available in the distribution yet, utilizes the syslog facility
in order to keep messages from packages. Each message is output with the tag
"pkg:foo" where foo is the package name. This allows for easily discerning
a "syslog" log message from a "pkg:syslog" message. The program makes use of
the 'logger' program as an interface to syslog.

Users can also use this  feature to add log messages of their own. For
example if a package has an error during configuration and the user is able
to resolve issue, she/he can use the dpkg-logger program like so:

# dpkg-logger 'user1' 'info' I was able to fix package foo's problem

Note the use of the username in place of the package name. Using it in this
manner can also provide some sort of accounting (although not well
trusted).

Why use syslog?
Syslog provides a level of features perfectly suited for tracking package
messages. All messages are automatically time stamped as well as tagged.
Syslog allows the user to modify which file these messages will be sent to
without affecting the dpkg-logger system. The user can also optionally
change the level of logging that is recoded by simply modifying the
syslog.conf defaults, or have syslog drop package messages altogether.

Syslog is already a proven and stable package, so there is little to no
development needed for this logging back-end. Users and package maintainers
are already familiar with syslog's features and configuration setup, so
the learning curve will be greatly enhanced over any 'from-scratch'
alternatives.

Why let packages do the logging?
Currently there is no way for the package system to gain any usable
information from the packages. Doing so would require a major rewrite in
dpkg and other package maintenance systems (apt, dselect). With the huge
changes already burdening the dpkg developers, as well as the (dwindling)
number of bugs that need to be addressed, it will prove to much easier a
task implementing this on the package end. Also the fact that only the
maintainer of the package really knows what needs to be logged and when.
There is no way for the package programs to be intelligent about this
without major dpkg<->package interfaces.

What about the package systems logging?
With the initial use of syslog, it would be easy for the package management
programs to later follow suit by adding syslog calls in addition to the
stdout/stderr messages they already have. Simply adding a new function such
as, print_message_log(), that would replace printf() and fprintf() would
serve to allow minimal changes. The function merely has to send the message
to the screen as well as the log. Since most of the important messages come
from package scripts (except for script errors that dpkg catches), it is
best it be implemented there first.

NOTE: A better way of package programs to use the logging feature may be to
exec dpkg-logger in order to use any alternatives installed for it. The
author has chosen to leave this as a decision to the package system
maitainers.

What do we need to do to implement this?
There are a few things this proposal makes assumptions about. One is the
use of LOG_LOCAL6 as the syslog facility to log to. This would need to be
approved, as it locks this level down to use by only packaging systems. The
second is the log file, which is assumed to be best placed at
/var/log/dpkg.log for consistency with other logs. It is the opinion of the
author that this be an administration log file with perms 'root.adm' 644.
There should be no security related info put into the log file (ie.
passwords)

Regardless of the above assumptions, the syslog package would need to be
modified. This only needs to be a modification of the config file, adding
this line:

local4.info  		/var/log/dpkg.log

This file must also be created when syslog is installed. As mentioned above
it should be owned root.adm and set 644. It will also need to be added to
the list of adm files so that it gets rotated appropriately.

The dpkg-logger has been developed using dpkg-divert as a template. This is
in order to have it drop in the dpkg/scripts directory for inclusion in the
dpkg package.

A little more on extending the back-end:
By using dpkg-divert or alternatives it would be possible to allow other
packages to replace the dpkg-logging program. Cases where this might be
useful is administration programs that want to send the logs to a central
server (without using syslog's ability to do this). Also there may come a
day when an alternate syslog program exists that may need other front-ends
in order for dpkg-logger to use it.

The program replacing dpkg-logger would only have to implement the same
usage, dpkg-logger pkg level message, in order to replace it. Some things
it must consider and implement:

1) The --stdout and --stderr options should act accordingly
2) The log levels must conform to info, warn, error and debug. It must not
introduce any new levels nor should it drop messages sent to one of the
existing ones. Trying to produce a message to a non-supported level should
exit with an error.
3) The configurability of the logging facility should not lose any
functionality in comparison to the standard facility (syslog) as it
pertains to package logging.

----------------------------------------------------------------------------

Conclusion:
Hopefully this proposal has given some credible backing to this idea and
why it should be considered a Good Thing. If there are any further
suggestions, they need to be discussed in an informative and rational sense
so as to weed out any changes and modifications before implementing these
features. "Measure twice, cut once"

----------------------------------------------------------------------------

The latest version of this proposal can be obtained from
http://www.debian.org/~bcollins/dpkg-logger/. The current dpkg-logger used
in conjunction with this proposal is also available here.

Attachment: pgpmYcCMaz2EC.pgp
Description: PGP signature


Reply to: