Table of Contents
Table of Contents
This is another syslog for windows, it includes daemon and client. Features:
RFC 3164-compliant;
high performance;
message forwarding;
log rotation;
completely open-source.
Primarily it was written for myself to help to create portable software. So if you are:
porting existing UNIX software to native win32 platform,
writing portable software,
writing pure windows software but understanding that EventLog sucks and looking for an alternative
then I hope that this stuff will be useful for you too.
Of course, you may just use the daemon as the network message collector. But I think that any UNIX alternative is much better. Not because this stuff is not so good (I hope), just because the underlying system is better.
The source code of the daemon and the client library IS NOT COPYRIGHTED and is offered for use in the public domain. You may use, modify or distribute it freely.
However, the project includes syslog header file, logger utility and the test based on it. This stuff is distributed under the BSD license.
The daemon uses Glib, libiconv and libintl libraries and the binary distribution includes them under the LGPL license.
Table of Contents
You need Glib to compile this stuff.
Take the binary distribution or compile it
yourself (look into extras subdirectory for an example).
Run autogen.sh. I used automake 1.8.5, autoconf 2.59 and libtool 1.5.10. With earlier versions it may not work because some command line options aren't supported. Then use configure script as described below.
Just use configure && make.
Option --enable-relocatable affects the location of
configuration directory: if specified, sysconfdir
is prepended with “.”.
For example, if you run
./configure --sysconfdir=/etc --enable-relocateble
then syslogd.exe and client will read their
configuration file from etc subdirectory
located in the same directory with executable file.
You should have DocBook and DocBook Website installed in your system.
Go to doc/book directory and run, for example:
xmlto html-nochunks syslog-win32.xml
Go to doc/website directory and issue the following commands:
xsltproc --output autolayout.xml \ http://docbook.sourceforge.net/release/website/2.6/xsl/autolayout.xsl \ layout.xml xsltproc --stringparam output-root htdocs \ stylesheets/chunk-tabular.xsl \ autolayout.xml
At first, compile documentation in doc/book.
Then use build.sh. It does all you need.
You should have some packages — look into the script
to see which ones.
Also, you should have Inno Setup
with ISPP installed in your system.
You should have cross compiler and Wine installed. Wine is required to run Inno Setup Compiler and the directory in which you are going to build should be accessible via some drive letter.
Assuming target triplet is i686-pc-mingw32,
iscc is in its default directory c:\program files\inno setup 5
and required packages are in ./distfiles:
DISTFILES=distfiles \ ISCC=c:\\program\ files\\inno\ setup\ 5\\iscc.exe \ HOST=i686-pc-mingw32 \ ./build.sh
I've noticed that Msys has troubles running some native command-line applications. So you'll have to run Inno Setup by hand.
DISTFILES=<path to the directory with packages> \ ./build.sh
Table of Contents
The configuration file for client is optional.
Its name is syslog.host and it should contain host
name or IPv4 address optionally followed by the colon and the port number.
By default port is 514.
If the file is missing then localhost is assumed.
This may look a bit ugly but if you have a better idea, send me a patch. But keep in mind that client should not have any dependencies like daemon.
The concept is quite simple: there are message sources, message filters and destinations. Each item has its unique (among other items of the same kind) name. The logpath ties together source, filter and destination.
Only one of the items of each kind may be specified in logpath. But several logpaths may refer to the same source, filter or destination.
The configuration file for daemon has XML format. It is not so convinient as its counterpart for any UNIX syslog. Following the windows way I plan to implement GUI configuration tool. So its content is not intended to be convinient for human.
The root element should be conf. It is not checked by the parser however. Top-level elements and their attributes are described below.
Attributes
Required. The name of message source.
Required. There are two source types: internal and udp. Internal type corresponds to syslog daemon itself and udp defines a listening UDP socket.
Optional. If the source type is udp, it defines interface the socket will be bound to. Default is 0.0.0.0.
Optional. If source type is udp it defines listening port number. Default is 514.
Attributes
Required. The name of the destination. The type of destination may be either “file” or “relay”. It is determined by the presence of attributes “file” or “collector” respectively.
The presence of this attribute defines destination type as “file”. The value of attribute is a pattern for the file name. It may contain the following format characters:
| Format | Description |
|---|---|
| %Y | four-digit year |
| %M | two-digit month, 01...12 |
| %m | month, 1...12 |
| %D | two-digit day of month, 01...31 |
| %d | day of month, 1...31 |
| %W | day of week, 1...7, 1 for sunday |
| %F | facility name |
| %f | facility in numeric form |
| %L | priority level name |
| %l | priority level in numeric form |
| %H | source host name (a “device”, according to RFC 3164) |
| %h | sender host name (datagram sender, which may be device or relay) |
| %P | program name |
| %% | % character |
File-specific, optional. Rotate log files periodically. Possible values are: daily, weekly, monthly.
Note that if rotation is turned on then it is strongly recommended not to use format characters in the filename pattern.
File-specific, optional. Log files are rotated when they grow bigger then size bytes. If size is followed by M, the size if assumed to be in megabytes. If the k is used, the size is in kilobytes. So size 100, size 100k, and size 100M are all valid.
File-specific, optional. If rotation is turned on this attribute specifies the number of backlog files.
File-specific, optional. Rotate the log file even if it is empty. Possible values are: yes, no. Default is yes.
File-specific, optional. Logs are moved to this directory for rotation. If value is a relative path then this directory will be located in the same directory with syslogd executable.
File-specific, optional. Command to use to compress log file.
File-specific, optional. Command line options may be passed to the compression program, if one is in use. Options may contain $PATHNAME and $FILENAME substrings which will be replaced with backlog pathname and basename respectively.
The presence of this attribute defines destination type as “relay”. The value of attribute is a name or IPv4 address of the collector optionally followed by the colon and port number.
Relay-specific, optional. Do not include source hostname in the datagramm. Some syslog daemons by default do not rely on the hostname part of datagramm and insert actual sender hostname in the logged message. Note that ommiting hostname violates RFC 3164. Possible values are: yes, no. Default is no
Attributes
Required. The name of the filter.
This element may contain sub-elements facility and priority.
Attributes
Facility name. May be one of the following:
| kern |
| user |
| daemon |
| auth |
| syslog |
| lpr |
| news |
| uucp |
| cron |
| authpriv |
| ftp |
| local0 |
| local1 |
| local2 |
| local3 |
| local4 |
| local5 |
| local6 |
| local7 |
Alternatively, the facility may be given in the numeric form. Possible range is 0...23.
Attributes
Required. The name of the source.
Optional. The name of the filter.
Required. The name of the destination.
When destination file name contains format characters, this option is quite useful.
Attributes
Required. Directory to purge. Must be a relative path inside logdir (see configuration options below).
Required. How long to keep files.
Attributes
Required. Drectory for the log files. If value is a relative path then this directory will be located in the same directory with syslogd executable.
Optional. Use resolver to determine sender host name. Possible values are: yes, no. Default is yes.
Optional. Convert incoming messages from specified encoding to destination_encoding. Default is do not convert.
Required, if source_encoding is given.
Optional. Interval in second between emissions of mark message. Zero means do not emit mark messages and this is the default value.
Optional. The content of mark message. Default is “-- MARK --”.
Optional. Number of seconds to hold a single message in queue. During this time identical messages are coalesced. Minimum is 1, default is 3 seconds.
syslogd — service process (daemon)
syslogd [[-h] | [--help]] [[-i] | [--install]] [[-I] | [--instance]name] [[-p] | [--priority]name] [[-r] | [--remove]] [[-s] | [--shutdown]] [[-v] | [--verbose]]
-h | --help
Display help message.
-i | --install
Install and start service.
-I | --instancename
Specify instance name for the daemon. This option is useful to install and run multiple daemons in the system.
-p | --priorityname
Set priority class for the daemon. Name may be “normal”, “high” or “highest”. Default is “normal”.
-r | --remove
Stop and remove service.
-s | --shutdown
Gracefully shutdown service.
-v | --verbose
Increase verbosity level. This option may be specified multiple times.
logger — a shell command interface to the syslog daemon
logger [[-f]file] [-i] [[-p]pri] [-s] [[-t]tag]
Logger makes entries in the system log. It provides a shell command interface to the syslog daemon.
-ffile
Log the specified file.
-i
Log the process id of the logger process with each line.
-ppri
Enter the message with the specified priority.
The priority may be specified numerically or as a
“facility.level” pair.
For example, -p local3.info logs the message(s)
as informational level in the local3 facility.
The default is “user.notice”.
-s
Log the message to standard error, as well as the system log.
-ttag
Mark every line in the log with the specified tag.
The logger utility exits 0 on success, and >0 if an error occurs.
Valid facility names are: auth, authpriv (for security information of a sensitive nature), cron, daemon, ftp, kern, lpr, mail, news, security (deprecated synonym for auth), syslog, user, uucp, and local0 to local7, inclusive.
Valid level names are: alert, crit, debug, emerg, err, error (deprecated synonym for err), info, notice, panic (deprecated synonym for emerg), warning, warn (deprecated synonym for warning).
test — message generator
test [[-b]seconds] [[-i]number] [[-n]number] [[-p]pri] [[-s]seconds] [[-t]tag]
The test utility generates bursts of test messages. Each message has the following format:
test message <message number>
-bseconds
Duration of the burst in seconds. Default is 1.
-inumber
The maximum number of identical messages. This feature is useful to test coalescer. The implementation is simple but explanation is a bit difficult, just look at issued messages when this number is 3, for example:
test message 1 test message 2 test message 2 test message 3 test message 3 test message 3 test message 4 test message 5 test message 5 test message 6 test message 6 test message 6 ...
Default is 1.
-nnumber
The number of bursts. Default is 1.
-ppri
The priority of messages. It may be specified numerically or as a
“facility.level” pair.
For example, -p local3.info.
The default is “user.notice”.
-sseconds
Pause between bursts in seconds. Default is 1.
-ttag
Mark every line in the log with the specified tag.
There are three basic parts of daemon: UDP listener, message processor and message writer. All these parts run in separate threads: the listener receives messages as fast as possible and passes them to the message processor, the message processor performs time-consuming tasks and message writer performs asynchronous output to files.
Datagrams are received by the UDP listener. The listener emits raw messages (struct raw_message) which contain content of datagram, sender address and reference to a source described in configuration file.
Raw messages are passed to the main processing thread via queue. Message processing involves the following tasks:
parse datagram: pick out PRI, TIMESTAMP, HOSTNAME, TAG an CONTENT according to RFC 3164;
convert CONTENT's encoding if specified;
determine sender host name if usedns option is set or just
convert IP address to string;
the result is saved in hostname cache to speed up subsequent resolutions;
multiplex message to logpaths and apply filters in logpaths; in other words, messages are multiplexed to logpaths through filters; messages in logpaths are represented with references to message structure and message structure contains reference count;
Because destination file name may be a pattern, further multiplexing is performed. Messages with similar HOSTNAME, TAG and CONTENT are coalesced.
Log rotation is initiated at process startup or at writing thread startup.
Old log files are deleted by the purger which is launched at process startup or by the writing thread after file is closed.
mark message
+-------------------------------------------------+
| |
| +----------------+ +-----+ message +--------------+
+--->|internal sources|--->|queue|-------->| - - - - - |
| (log_internal) | +-----+ | \ |
+----------------+ | main loop \ |
| \| message
+------------+ raw message +-----+ | +------+ /|--------->
|UDP listener|------------>|queue|-------->|-|parser|- - |
+------------+ +-----+ | +------+ |
+--------------+
+-----------------+ +------+ +-----------+ +-----------+
--->|charset converter|--->|filter|--->|multiplexer|-+->|destination|+
+-----------------+ +------+ +-----------+ +->+-----------+|+
^ +-> +-----------+|
| +-----------+
+-------+
|logpath|+
+-------+|+
+-------+|
+-------+
file +-----------+ +-----+ +--------------+
destination: >--|multiplexer|-+->|queue|+ ---> |writing thread|+
+-----------+ +->+-----+|+ ---> +--------------+|+
^ +-> +-----+| ---> +--------------+|
| +-----+ +--------------+
+----------------+
|filename pattern|
+----------------+
relay +--------+
destination: >--|sendto()|
+--------+