Getting started

The simplest way to run Windows Syslog is to start it as a console application. It prints its configuration settings, which you can - and will later - configure, but they all have default values, what is sufficient by now. So it starts listening for inbound datagrams on the standard syslog port (UDP 514). Of course, you need to specify your workstation/server as a syslog destination on your network equipment. Also, if you use a firewall, you need to allow inbound UDP packets destined for your workstation/server's IP and that port. Each syslog message received will be immediately printed on the screen.
If you want to save syslog messages in a file instead of printing them on screen, you can use the standard > redirect operator with a filename of your choice or the -nostdout command-line option. In the former case, you may be interested in omitting the interactive output, supply the -nodump option to do this; in the latter case, simply look for a file named like syslog_2015-08-30.txt in the current directory. When you are done playing with the server, press Control+C to terminate it. And that's it, basically.

Moving forward

There are (of course) more parameters to control the behavior of the server. They can be supplied through the command line, the registry, or both. Command line parameters take precedence, so when a parameter is present both in the command line and the registry, the command line supplied value gets used. If a command line parameter requires a value, we'll call it, er... "parameter", it should be given as -parameter value; if it doesn't, let's call it "option" or "switch", it should be given as -option (without argument). The names of command line parameters are supposed to be more concise and can be different from the names of registry parameters, which are more "verbose". When supplied via the registry, parameters with string values should be of type REG_SZ, and parameters with numerical values, of type REG_DWORD. Registry parameters corresponding to command line options are given as a logical values of type REG_DWORD set to 0 to mean "off" or "false" and to 1 to mean "on" or "true". The default registry path is HKLM\Software\CodePlex\WindowsSysLog but you can override this with the -regpath command line parameter (supplied as a subkey under HKLM). You can also ignore the registry-supplied settings entirely by using the -noreg option. All this permits you to run several instances of the server simultaneously, each with its own configuration set. And as was already stated, all parameters have default values, so, while experimenting, specify only those that you really need to. On the other hand, in production it is recommended to configure all relevant values explicitly in case that in the future the defaults would change.

Let's look at the parameters that control the server's behavior in respect to the log files creation:

Command line parameter Registry parameter (REG_SZ) Value / Description
-logpath SysLogPath directory to store the logs, the default is . (current directory)
-logname SysLogName prefix to be prepended to the file name, the default is syslog_
-logext SysLogExtension extension to be appended to the file name, the default is .txt
-logrotate SysLogRotate how often to create a new log file; one of the following values: yearly, monthly, daily, hourly, minutely, the default is daily

It is recommended to set the -logpath (SysLogPath) explicitly. The -logrotate (SysLogRotate) parameter controls how often a new log file will be created. It also affects the names being generated, which are composed by concatenating a value given by the -logname (SysLogName) parameter with a string from the following table and finally with a suffix given by the -logext (SysLogExtension) parameter:

-logrotate (SysLogRotate) The middle part of the name Example
yearly YYYY syslog_2015.txt
monthly YYYY-MM syslog_2015-08.txt
daily YYYY-MM-DD syslog_2015-08-30.txt
hourly YYYY-MM-DD=HH syslog_2015-08-30=12.txt
minutely YYYY-MM-DD=HH-MM syslog_2015-08-30=12-00.txt

Here are some examples:
WindowsSysLog.exe -logpath D:\logs -logrotate monthly parameters other than the -logpath and -logrotate are taken from the registry, if present; those that are not, will receive default values
WindowsSysLog.exe -noreg -logpath C:\Temp\syslog parameters other than the -logpath will receive default values

These have been the parameters that control the "external aspect" of the log files, now let's look at those that rule the "inner side". A log file is composed of a set of different columns (this set is configurable) separated with a tabulation (ASCII code 9, this is not configurable). The columns are: the date, the time (with or without milliseconds), the IP address (of the device that sent the message), the facility, the severity and the syslog message itself. The first three can be disabled, but the last three can not. To configure the log file format use the following parameters:

Command line option Registry parameter (REG_DWORD) Registry value Description
-logdate LogDate 1 log the date in a format YYYY-MM-DD
-nodate LogDate 0 do not log the date
-logtime LogTime 1 log the time in a format HH-MM-SS
-notime LogTime 0 do not log the time
-logmsec LogMilliseconds 1 add the milliseconds to the time (three digits): HH-MM-SS.msec
-nomsec LogMilliseconds 0 do not log the milliseconds
-logip LogIP 1 log the IP address of the sender in a format A.B.C.D
-noip LogIP 0 do not log the IP

Also a log file can be viewed as a set of rows, because each message is stored as a separate line, or string of text. And this is where a question (and the answer) arises: how to terminate text strings in a log file? The thing is that different platforms have different tradition about how to do this. Unix systems terminate lines with a single special character - "line feed" (LF) (denoted as '\n', ASCII code 13) but Windows family uses two characters - "carriage return" (CR) (denoted as '\r', ASCII code 10) followed by the abovementioned "line feed". You have the option to choose either way, here is how:

Command line option Registry parameter (REG_DWORD) Registry value Description
-wineol WindowsNewLine 1 terminate lines the Windows way (this is the default)
-nixeol WindowsNewLine 0 terminate lines the Unix way

Sometimes It is necessary to reduce the number of rows in a file, that is, to filter out messages based on their severity level, here are the keys:

Command line parameter Registry parameter (REG_DWORD) Value Description
-filter SeverityFilter number from 0 to 8 filter out messages with severities greater than or equal to this value, the default is 7
-ownfilter SeverityOwnFilter number from 0 to 8 filter out messages generated internally by syslog, the default is 8

To suppress log records based on their content, Windows SysLog (since version 0.14) supports basic regular expressions (currently as command-line parameters only, no registry). The syntax is simple and similar to the one used by the cmd.exe shell, but somewhat better :). Accepted special symbols are: an asterisk *, which denotes zero or more (any) characters, a question mark ?, which denotes exactly one (any) character, and a set of (literal) characters supplied between square brackets [ ] (ranges of characters can be denoted by using a dash -, for example: [A-Za-z]). The command-line parameters are: -pass regex, -trim regex and -drop regex and they work as follows:
  • first, when the program is starting, a list of regular expressions and their corresponding actions is constructed from the command line - in the order given
  • second, while running the program, when a message arrives, it is checked against this list in order and depending on the result (matched or not matched) the actions are performed:
    • -pass matches: stop the search and log the message; otherwise, continue the search
    • -trim matches: continue the search; otherwise, drop the message
    • -drop matches: stop the search and drop the message; otherwise, continue the search
    • when the search is completed and there has been no match, log the message
The -pass and -drop options are straightforward, let's explain -trim: it is used to cast away unneeded messaged and continue inspecting the rest. By default, no regular expressions are set and so all the messages get logged. There are limits on the length and number of regular expressions allowed, namely, 127 characters and 12 expressions (total of all three kinds). These limits can be changed by modifying the source code, but bear in mind that the regular expressions are matched in a sequence, that is, a linear search is performed, so too many expressions can slow down message processing. But let's proceed to examples. Suppose that we want to accept messages from a Cisco ASA appliance and drop anything other, here is how:

SysLog_v014c_x64_static.exe -trim "*%ASA*"

Now let's suppose that we've configured the logging trap informational command on our ASA and now we are deluged with messages like this one:

local4 Informational Sep 24 2015 10:11:12: %ASA-6-302013: Built outbound TCP connection 12345 for outside:203.0.113.89/80 (203.0.113.89/80) to inside:192.168.1.123/1033 (192.168.1.123/1033)

so we agree to drop these messages but we want to keep other informational messages. One possible solution is:

SysLog_v014c_x64_static.exe -trim "*%ASA*" -drop "*%ASA-6-30201[3-6]:*"

You don't need a -pass * at the end, because it's the default.

Attention: Always test your regular expressions before putting them into production, because dropped syslog messages are really dropped - forever.

As was mentioned, it is possible - and perfectly acceptable - to run several instances of the server, they can have same or different parameters, the only requirement is that they must use different port numbers. To achieve this, use the -port parameter followed by numerical value of the desired port. Don't forget to configure your network equipment accordingly.

Command line parameter Registry parameter (REG_DWORD) Value Description
-port SysLogPort number from 1 to 65535 UDP port number to listen to, the default is 514

Tip: run the executable from the command line with (or without) desired parameters and specify -norun to only print settings that the server has determined without actually running it.

Getting serious

When playing with syslog, interactive mode can be enough or even the most suitable, but when it comes to production use, it is a must to run syslog as a service. To do this, you will need a bit of planning. First, decide where you are going to install the service's binary, where to store the logs and whether to use command-line or registry parameters, or both. Do not forget to configure the firewall appropriately, if present.
If you need to run several instances of Windows Syslog, you don't have to make multiple copies of the binary - simply register the same binary with different command-line parameters. Even if you decide to use the registry, you will have to use at least the -regpath command-line parameter to differentiate between configuration sets, or you can provide common parameters (SysLogPath and SysLogExtension, for example) through a common registry path, and then supply the individual settings in the command line (-port, -logname) when registering the service. To register a service in Windows, use the standard sc utility, for example:

MD D:\WindowsSysLog\bin
MD D:\WindowsSysLog\logs
COPY "%USERPROFILE%\Downloads\SysLog_v012b_x64_static.exe" D:\WindowsSysLog\bin\WindowsSysLog.exe
sc create syslog binPath= "D:\WindowsSysLog\bin\WindowsSysLog.exe -logpath D:\WindowsSysLog\logs"
net start syslog

...

(more instructions coming soon)

Last edited Sep 24, 2015 at 2:35 PM by SergioF, version 123