Added to repository.

1 files changed, 221 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..c95480e
--- /dev/null
+++ b/README
@@ -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|
+              +----------------+