From e6d3929b119dfd10cd83a932cc3337ffb9a04b97 Mon Sep 17 00:00:00 2001 From: yaworsky Date: Mon, 17 Oct 2005 19:22:16 +0000 Subject: Added to CVS. --- doc/src/compiling.xml | 93 ++++++++ doc/src/configuration.xml | 561 ++++++++++++++++++++++++++++++++++++++++++++++ doc/src/intro.xml | 58 +++++ doc/src/logger.xml | 103 +++++++++ doc/src/syslogd.xml | 112 +++++++++ doc/src/test.xml | 131 +++++++++++ 6 files changed, 1058 insertions(+) create mode 100644 doc/src/compiling.xml create mode 100644 doc/src/configuration.xml create mode 100644 doc/src/intro.xml create mode 100644 doc/src/logger.xml create mode 100644 doc/src/syslogd.xml create mode 100644 doc/src/test.xml (limited to 'doc') diff --git a/doc/src/compiling.xml b/doc/src/compiling.xml new file mode 100644 index 0000000..3d78701 --- /dev/null +++ b/doc/src/compiling.xml @@ -0,0 +1,93 @@ + + +You need Glib to compile this stuff. +Take the binary distribution or compile it +yourself (look into extras subdirectory for an example). + + + +
+ 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 affects the location of +configuration directory: if specified, +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 +with ISPP installed in 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'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 + +
+
+ +
+ Compiling documentation + +You should have DocBook and DocBook Website installed in your system. +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 + +
diff --git a/doc/src/configuration.xml b/doc/src/configuration.xml new file mode 100644 index 0000000..eddd098 --- /dev/null +++ b/doc/src/configuration.xml @@ -0,0 +1,561 @@ +
+ Syslog client + +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. + +
+ +
+ Syslog 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. + + +
+ +<source/> + + + + +Attributes + + + +name + + + +Required. +The name of message source. + + + + + +type + + + +Required. +There are two source types: internal +and udp. +Internal type corresponds to syslog daemon itself +and udp defines a listening UDP socket. + + + + + +interface + + + +Optional. +If the 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/> + + + + +Attributes + + + +name + + + +Required. +The name of the destination. + + + + + +file + + + +Required. +The pattern for the file name. +It may contain the following format characters: + + + FormatDescription + %Yfour-digit year + %Mtwo-digit month, 01...12 + %mmonth, 1...12 + %Dtwo-digit day of month, 01...31 + %dday of month, 1...31 + %Wday of week, 1...7, 1 for sunday + %Ffacility name + %ffacility in numeric form + %Lpriority level name + %lpriority level in numeric form + %Hsource host name (a device, according to RFC 3164) + %hsender host name (datagram sender, which may be device or relay) + %Pprogram name + %%% character + + + + + + +rotate + + + +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. + + + + + +size + + + +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. + + + + + +backlogs + + + +Optional. +If rotation is turned on this attribute specifies the number of backlog files. + + + + + +ifempty + + + +Optional. +Rotate the log file even if it is empty. +Possible values are: yes, no. +Default is yes. + + + + + +olddir + + + +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. + + + + + +compresscmd + + + +Optional. +Command to use to compress log file. + + + + + +compressoptions + + + +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. + + + + + +
+ +
+ +<filter/> + + + + +Attributes + + + +name + + + +Required. +The name of the filter. + + + + + + +This element may contain sub-elements facility +and priority. + +
+ + <facility/> + + + + +Attributes + + + +name + + + +Facility name. May be one of the following: + + kern + user + mail + daemon + auth + syslog + lpr + news + uucp + cron + authpriv + ftp + local0 + local1 + local2 + local3 + local4 + local5 + local6 + local7 + + + + + + +value + + + +Alternatively, the facility may be given in the numeric form. +Possible range is 0...23. + + + + + +
+
+ + <priority/> + + + + + Attributes + + + + name + + + +Priority name. May be one of the following: + + emerg + alert + crit + error + warning + notice + info + debug + + + + + + +value + + + +Alternatively, the priority may be given in the numeric form. +Possible range is 0...7. + + + + + +
+
+ +
+ +<logpath/> + + + + +Attributes + + + +source + + + +Required. +The name of the source. + + + + + +filter + + + +Optional. +The name of the filter. + + + + + +destination + + + +Required. +The name of the destination. + + + + + +
+ +
+ +<purge/> + + +When destination file name contains format characters, this option is quite useful. + + +Attributes + + + +directory + + + +Required. +Directory to purge. +Must be a relative path inside logdir +(see configuration options below). + + + + + +keep_days + + + +Required. +How long to keep files. + + + + + +
+ +
+ +<options/> + + + + +Attributes + + + +logdir + + + +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. + + + + + +dns + + + +Optional. +Use resolver to determine sender host name. +Possible values are: yes, no. +Default is yes. + + + + + +source_encoding + + + +Optional. +Convert incoming messages from specified encoding to +destination_encoding. +Default is do not convert. + + + + + +destination_encoding + + + +Required, if source_encoding is given. + + + + + +mark_interval + + + +Optional. +Interval in second between emissions of mark message. +Zero means do not emit mark messages and this is the +default value. + + + + + +mark_message + + + +Optional. +The content of mark message. +Default is -- MARK --. + + + + + +hold + + + +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. + + + + + +
+ +
diff --git a/doc/src/intro.xml b/doc/src/intro.xml new file mode 100644 index 0000000..0afbf96 --- /dev/null +++ b/doc/src/intro.xml @@ -0,0 +1,58 @@ +
+ What's this + +This is an implementation of syslog daemon and client for native win32 platform. +It complies to RFC 3164, +The BSD Syslog Protocol. + +
+ +
+ What for + +Maybe 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. + + + +I hope that in any of these cases this stuff will be useful for you. + + +Of course, you may just use the daemon as the network message collector. +But in this case you better look at UNIX. + +
+ +
+ Legal issues + +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. + +
diff --git a/doc/src/logger.xml b/doc/src/logger.xml new file mode 100644 index 0000000..af7d735 --- /dev/null +++ b/doc/src/logger.xml @@ -0,0 +1,103 @@ + + + + logger + + + + logger + 1 + + + + logger + a shell command interface to the syslog daemon + + + + + logger +-ffile +-i +-ppri +-s +-ttag + + + + + Description + +Logger makes entries in the system log. +It provides a shell command interface to the syslog daemon. + + + + + Options + + + + +file + + + +Log the specified file. + + + + + + + + + +Log the process id of the logger process with each line. + + + + + +pri + + + +Enter the message with the specified priority. +The priority may be specified numerically or as a +facility.level pair. +For example, logs the message(s) +as informational level in the local3 facility. +The default is user.notice. + + + + + +tag + + + +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). + + + + diff --git a/doc/src/syslogd.xml b/doc/src/syslogd.xml new file mode 100644 index 0000000..4093b51 --- /dev/null +++ b/doc/src/syslogd.xml @@ -0,0 +1,112 @@ + + + + syslogd + + + + syslogd + 1 + + + + syslogd + service process (daemon) + + + + + syslogd +-h--help +-i--install +-I--instancename +-p--priorityname +-r--remove +-s--shutdown +-v--verbose + + + + + Options + + + + + | + + + +Display help message. + + + + + + | + + + +Install and start service. + + + + + + | name + + + +Specify instance name for the daemon. +This option is useful to install and run multiple daemons in the system. + + + + + + | name + + + +Set priority class for the daemon. +Name may be normal, high or highest. +Default is normal. + + + + + + | + + + +Stop and remove service. + + + + + + | + + + +Gracefully shutdown service. + + + + + + | + + + +Increase verbosity level. +This option may be specified multiple times. + + + + + + + + diff --git a/doc/src/test.xml b/doc/src/test.xml new file mode 100644 index 0000000..2c6c6d5 --- /dev/null +++ b/doc/src/test.xml @@ -0,0 +1,131 @@ + + + + test + + + + test + 1 + + + + test + message generator + + + + + test +-bseconds +-inumber +-nnumber +-ppri +-sseconds +-ttag + + + + + Description + +The test utility generates bursts of test messages. +Each message has the following format: + +test message <message number> + + + + + Options + + + + +seconds + + + +Duration of the burst in seconds. +Default is 1. + + + + + +number + + + +The maximum number of identical messages. +This feature is useful to test coalescer. +The implementation is simple but explanation is a bit difficult, +just see 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. + + + + + +number + + + +The number of bursts. +Default is 1. + + + + + +pri + + + +The priority of messages. It may be specified numerically or as a +facility.level pair. +For example, . +The default is user.notice. + + + + + +seconds + + + +Pause between bursts in seconds. +Default is 1. + + + + + +tag + + + +Mark every line in the log with the specified tag. + + + + + + + + -- cgit v1.2.3