diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 221 |
1 files changed, 221 insertions, 0 deletions
@@ -0,0 +1,221 @@ +This is an implementation of syslog daemon and client for native win32. +This stuff is dedicated to those who is writing portable software or +porting unix software to native win32. + +COMPILING +--------- + +You need Glib to compile this stuff. + +Compiling from CVS: + +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. + +Compiling from source tarball: + +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. + +Building binary distribution: + +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 (http://www.jrsoftware.org) with ISPP +installed on your system. + + on unix: + +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 + + on windows: + +I 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 + + +CONFIGURATION +------------- + +The configuration file for client is optional. Its name is syslog.host +and it should contain host name or address optionally followed by the +colon and the port number. By default, port is 514. +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 configuration file for daemon has XML format. It is not intended to be +convinient for human because should be generated by GUI configuration tool. +The root element is 'conf'. ++-------------+-----------+-------------------------------------------------+ +| Element | Attribute | Description | ++=============+===========+=================================================+ +| source | name | The name of message source. | +| | type | There are two source types: 'internal' and | +| | | 'udp'. Internal type corresponds to syslogd | +| | | itself and 'udp' defines a listening UDP socket.| +| | interface | Optional. If source type is udp, it defines | +| | | interface the socket will be bound to. Default | +| | | is 0.0.0.0. | +| | port | Optional. If source type is udp, it defines | +| | | listening port number. Default is 514. | ++-------------+-----------+-------------------------------------------------+ +| destination | name | The name of the destination. | +| | file | The pattern for the file name. See below. | +| | rotate | daily/weekly/monthly | +| | size | 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. | +| | backlogs | Number of backlog files. | +| | ifempty | yes/no: rotate the log file even if it is | +| | | empty; default is yes. | +| | olddir | 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. | +| | compresscmd Command (with options) to use to compress log | +| | | file. | +| | compressoptions 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 | +| | | basename respectively. | ++-------------+-----------+-------------------------------------------------+ +| filter | name | The name of the filter. | +| | | This element has a set of sub-elements | +| | | 'facility' and 'priority'. Each of them defines | +| | | one value with attribute 'value' in numeric | +| | | form or 'name' in verbose form. | ++-------------+-----------+-------------------------------------------------+ +| logpath | source | The name of the source. | +| | filter | Optional. The name of the filter. | +| | destination The name of the destination. | ++-------------+-----------+-------------------------------------------------+ +| purge | directory | Directory to purge. Must be a relative path | +| | | inside logdir (see configuration options below) | +| | keep_days | How long to keep files. | ++-------------+-----------+-------------------------------------------------+ +| options | See below | | ++-------------+-----------+-------------------------------------------------+ + +Format characters for the file name pattern: + + %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 RFC3164) + %h sender host name (datagram sender, which may be device + or relay) + %P program name + %% % character + +Attributes for the element 'options': + + logdir directory for the log files; if value is a relative + path then this directory will be located in the same + directory where syslogd executable is. + + dns yes/no: use resolver to determine sender host name; + default is yes. + + source_encoding convert incoming messages from specified encoding + to 'destination_encoding'; do not convert by default. + + destination_encoding see 'source_encoding' + + mark_interval interval in second between emissions of mark message; + 0 means do not emit mark messages, this is the + default value. + + mark_message content of mark message; "-- MARK --" by default. + + hold number of seconds to hold a single message in queue; + minimum is 1, default is 3 seconds. + During this time identical messages are coalesced. + + +IMPLEMENTATION +-------------- + +There are three basic parts of daemon: 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 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 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. + + ++--------+ raw message +-----+ +------+ message +-----------------+ +|listener|------------>|queue|--->|parser|-------->|charset converter|---> ++--------+ +-----+ +------+ +-----------------+ + + +------+ +-----------+ +-----------+ +--->|filter|--->|multiplexer|-+->|destination|+ + +------+ +-----------+ +->+-----------+|+ + ^ +-> +-----------+| + | +-----------+ + +-------+ + |logpath|+ + +-------+|+ + +-------+| + +-------+ + + + +-----------+ +-----+ +--------------+ +destination: >--|multiplexer|-+->|queue|+ ---> |writing thread|+ + +-----------+ +->+-----+|+ ---> +--------------+|+ + ^ +-> +-----+| ---> +--------------+| + | +-----+ +--------------+ + +----------------+ + |filename pattern| + +----------------+ |