| 1 |
Unix::Syslog -- Perl interface to the UNIX system logger |
| 2 |
======================================================== |
| 3 |
|
| 4 |
Copyright (c) 1999,2000,2001,2002,2007 Marcus Harnisch |
| 5 |
|
| 6 |
Disclaimer |
| 7 |
========== |
| 8 |
|
| 9 |
The text below hasn't really changed in ages and unless someone points |
| 10 |
me to outdated or otherwise wrong information, I will not re-verify |
| 11 |
the statements. What you find here is historic and may or may not have |
| 12 |
any value to you. In particular statements about Sys::Syslog may be |
| 13 |
completely outdated -- or not. |
| 14 |
|
| 15 |
Introduction |
| 16 |
============ |
| 17 |
|
| 18 |
This Module provides access to the system logger available on most |
| 19 |
UNIX system via Perl's XSUBs (Perl's C interface). |
| 20 |
|
| 21 |
I wrote this module because of some features I missed in Sys::Syslog |
| 22 |
(see FAQ below) and also to do my first steps into the secrets of |
| 23 |
Perl's XSUBs. |
| 24 |
|
| 25 |
Copyright and distribution |
| 26 |
========================== |
| 27 |
|
| 28 |
This program is free software; you can redistribute it and/or modify |
| 29 |
it under the terms of the Artistic License 2.0 (see file Artistic in |
| 30 |
this directory). |
| 31 |
|
| 32 |
Check clause (4) for your rights to distribute this software. |
| 33 |
|
| 34 |
Installation |
| 35 |
============ |
| 36 |
|
| 37 |
Unix::Syslog is a Perl module that makes use of XSUBs and hence |
| 38 |
requires a working C compiler and library. Execute the following |
| 39 |
commands to install this package (`make test' prints the results of a |
| 40 |
test suite. Execute `make install' only if the required tests finished |
| 41 |
successfully or if you know what you are doing): |
| 42 |
|
| 43 |
perl Makefile.PL |
| 44 |
make test |
| 45 |
make install |
| 46 |
|
| 47 |
Notes about the test suite |
| 48 |
========================== |
| 49 |
|
| 50 |
Some of the tests may fail because the respective constants are not |
| 51 |
available on certain systems. You should be able to distinguish these |
| 52 |
tests from those that fail because of a malfunction by carefully |
| 53 |
reading the output of the test routines. |
| 54 |
|
| 55 |
The tests that write messages to syslog cannot return a success status |
| 56 |
since the underlying libc functions don't return appropriate |
| 57 |
information. To verify that these tests work correctly, you should |
| 58 |
configure syslogd so that the facility `local7' and priority `info' |
| 59 |
will be written to a file. |
| 60 |
|
| 61 |
OS dependent behaviour and portability |
| 62 |
====================================== |
| 63 |
|
| 64 |
This package uses system specific functions. Programs that uses this |
| 65 |
package may not be portable in any case. If you plan to write portable |
| 66 |
code using this package, please consult the manuals of the systems you |
| 67 |
wish to run the software on. Then modify your program accordingly. |
| 68 |
|
| 69 |
As of version 0.99 Unix::Syslog provides two functions priorityname() |
| 70 |
and facilityname() that return the names of priority and facility, |
| 71 |
respectively. This functionality is only enabled if an according |
| 72 |
`#define' is enabled through Makefile.PL. By default this statement is |
| 73 |
commented out. |
| 74 |
|
| 75 |
Known bugs |
| 76 |
========== |
| 77 |
|
| 78 |
OS Description Workaround |
| 79 |
--------------------------------------------------------------------------- |
| 80 |
Linux On systems using glibc2 (<= version 2.1), None possible. |
| 81 |
setting the log mask has no effect. |
| 82 |
|
| 83 |
Frequently Asked Questions |
| 84 |
========================== |
| 85 |
|
| 86 |
1. What is the benefit of using this module instead of Sys::Syslog? |
| 87 |
|
| 88 |
Sys::Syslog always opens a network connection to the syslog |
| 89 |
service. At least on Linux systems this may lead to some |
| 90 |
trouble, because |
| 91 |
|
| 92 |
o Linux syslogd (from package sysklogd) does not listen to the |
| 93 |
network by default. Most people working on stand-alone |
| 94 |
machines (including me) didn't see any reason why to |
| 95 |
enable this option. Others didn't enable it for security |
| 96 |
reasons. |
| 97 |
|
| 98 |
OS-independent, some sysadmins may run a firewall on |
| 99 |
their network that blocks connections to port 514/udp. |
| 100 |
|
| 101 |
o By default Linux syslogd doesn't forward messages which have |
| 102 |
already already received from the network to other log |
| 103 |
hosts. There are reasons not to enable this option |
| 104 |
unless it is really necessary. Looping messages |
| 105 |
resulting from a misconfiguration may break down your |
| 106 |
(log-)system. |
| 107 |
|
| 108 |
Peter Stamfest pointed out some other advantages of Unix::Syslog, |
| 109 |
I didn't came across my self. |
| 110 |
|
| 111 |
o LOG_PERROR works. |
| 112 |
|
| 113 |
o works with perl -Tw without warnings and problems due to |
| 114 |
tainted data as it is the case for Sys::Syslog in some |
| 115 |
special applications. [Especially when running a script |
| 116 |
as root] |
| 117 |
|
| 118 |
2. Well, is there any reason to use Sys::Syslog any longer? |
| 119 |
|
| 120 |
Yes! In contrary to Unix::Syslog, Sys::Syslog works even if |
| 121 |
you don't have a syslog daemon running on your system as |
| 122 |
long as you are connected to a log host via a network and |
| 123 |
have access to the syslog.h header file of your log host to |
| 124 |
generate the initial files for Sys::Syslog (see |
| 125 |
Sys::Syslog(3) for details). Unix::Syslog only logs to your |
| 126 |
local syslog daemon which in turn may be configured to |
| 127 |
distribute the message over the network. |
| 128 |
|
| 129 |
3. Are calls to the functions provided by Unix::Syslog compatible |
| 130 |
to those of Sys::Syslog? |
| 131 |
|
| 132 |
Currently not. Sys::Syslog requires strings to specify many |
| 133 |
of the arguments to the functions, while Unix::Syslog uses |
| 134 |
numeric constants accessed via macros as defined in |
| 135 |
syslog.h. Although the strings used by Sys::Syslog are also |
| 136 |
defined in syslog.h, it seems that most people got used to |
| 137 |
the numeric arguments. I will implement the string based |
| 138 |
calls if there are enough people ($min_people > 10**40) |
| 139 |
complaining about the lack of compatibility. |
| 140 |
|
| 141 |
Comments, Bug reports and Suggestions |
| 142 |
===================================== |
| 143 |
|
| 144 |
Please direct anything you wish to tell me about this package to the |
| 145 |
address given below. |
| 146 |
|
| 147 |
Have fun, |
| 148 |
Marcus Harnisch <[email protected]> |