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