Documentation forKiwi Syslog Server

Script functions — Legacy

This documentation is for legacy Kiwi Syslog Server versions 9.8.3 and older.

When you write scripts for use with Kiwi Syslog Server, you can find several built in functions available from the Fields object.

Built-in functions of the Fields object

To use a built in function, access the function name prefixed with the Fields object. Pass any parameters needed and the result is returned.

Fields.IsValidIPAddress(IPAddress as string) as Boolean

Details This function verifies the string passed to the Field object and returns true if the string has a valid IP address format.
Input parameters IPAddress as string
Return value Boolean (true/false)
Example

If Fields.IsValidIPAddress(Fields.VarPeerAddress) = True then

Fields.VarCustom01 = Fields.VarPeerAddress

End if

Fields.ConvertIPtoHex(IPAddress As String) As String

Details This function converts an IP address to 8 byte hex value.
Input parameters IPAddress as string
Return value 8 byte hex value
Example

If Fields.IsValidIPAddress(Fields.VarPeerAddress) = True then

Fields.VarCustom01 = Fields.ConvertIPToHex(Fields.VarPeerAddress)

End if

Fields.GetDailyStatistics() As String

Details This function returns the daily statistics page as a CRLF delimited string. The string can then be written to a file or e-mailed.
Input parameters None
Return value String
Example

MyStats = Fields.GetDailyStatistics()

Fields.ConvertPriorityToText(PriorityValue)

Details This function converts a message priority value to a text representation of the facility level. For example, a value of 191 returns Local7.Debug.
Input parameters Priority value
Range 0 to 191
Return value Facility.Level as text string
Example

Filename = "C:\Programfiles\Syslogd\Logs\TestLog.txt"

' Use the date and time from the current message

With Fields

MsgDate = .VarDate & " " & .VarTime

MsgText = "This is a test message from the scripting action"

Data = MsgDate & vbtab & .ConvertPriorityToText(.VarPriority) & vbtab & _

.VarPeerAddress & vbtab & MsgText Call .ActionLogToFile(Filename, Data)

End with

Fields.ActionPlaySound(SoundFilename As String, RepeatCount as Long)

Details This function plays a beep or .wav file. You can set a number of times to repeat or until canceled.
Input parameters SoundFilename as string, RepeatCount as long
Return value None. Specifying a empty string ("") for SoundFilename results in the system beep sound.
RepeatCount options
  • 0 = repeat until canceled (press the flashing bell on the main display window to cancel).
  • 1 to 100 = repeat a set number of times, or until canceled manually

When the repeat count is greater than 1, the wav file or beep sound plays at 5 second intervals.

Example

For example, to play the squeak sound 5 times:

Call Fields.ActionPlaySound("C:\Program Files\Syslogd\Sounds\Squeak.wav", 5)

To play the squeak sound until canceled:

Call Fields.ActionPlaySound("C:\Program Files\Syslogd\Sounds\Squeak.wav", 0)

Fields.ActionSendEmail(MailTo, MailFrom, MailSubject, MailMessage , [MailImportance] , [MailPriority] , [MailSensitivity] )

Details This function sends an e-mail to the addresses you specify.
Return value None

E-mail Delivery Options

Importance, Priority, and Sensitivity E-mail Delivery Option parameters are optional. These parameters allow you to specify the importance, priority, and sensitivity flags of the e-mail message.

Email recipients receive the messages with the MailImportance, MailPriority, or MailSensitivity level you set.

MailImportance

0 - Unspecified (Default)

1 - High

2 - Normal

3 - Low

MailPriority

0 - Unspecified (Default)

1 - Normal

2 - Urgent

3 - Non-Urgent

MailSensitivity

0 - Unspecified (Default)

1 - Personal

2 - Private

3 - Confidential

To send the message to multiple addresses, separate each address with a comma. For example: MailTo = "user1@company.com,user2@company.com,user3@company.com"

This first example shows you how to send an e-mail to joe@company.com, with default importance, priority, and sensitivity.

MailTo = "joe@company.com"

MailFrom = "server@company.com"

MailSubject = "This is a test of the scripting action"

MailMessage = "This is a test mail message" & vbCrLf & "Multiple lines."

Call Fields.ActionSendEmail(MailTo, MailFrom, MailSubject, MailMessage)

This second example shows you how to send an e-mail to joe@company.com, with high importance, urgent priority, and confidential sensitivity.

MailTo = "joe@company.com"

MailFrom = "server@company.com"

MailSubject = "This is a test of the scripting action"

MailMessage = "This is a test mail message" & vbCrLf & "Multiple lines." MailImportance = 1

MailPriority = 2

MailSensitivity = 3

Call Fields.ActionSendEmail(MailTo, MailFrom, MailSubject, MailMessage, MailImportance, MailPriority, MailSensitivity)

Fields.ActionLogToFile(Filename, Data, [RotateLogFile] , [RotationType] , [NumLogFiles] , [Amount] , [Unit])

Details This function opens the log file you specify and appends the Data to the end of the file. Use this function to log messages to file in your format. You can also use AutoSplit syntax values in the filename. For example, to have the filename contain the current hour of the day, use %TimeHH: Filename = "C:\Program files\Syslogd\Logs\TestLog%TimeHH.txt"
Return value None
Example

Filename = "C:\Program files\Syslogd\Logs\TestLog.txt" MsgPriority = "Local7.Info"

MsgHostAddress = Fields.VarPeerAddress

' Use the date and time from the current message MsgDate = Fields.VarDate & " " & Fields.VarTime

MsgText = "This is a test message from the scripting action"

Data = MsgDate & vbtab & MsgPriority & vbtab & MsgHostAddress & vbtab & MsgText

Call Fields.ActionLogToFile(Filename, Data)

This example requires you enable Read permission for Other fields. This gives the script read access to the VarDate and VarTime variables.

Log File Rotation:

For more information on Log File Rotation in Kiwi Syslog Server, see Log File Rotation.

The parameters RotateLogFile, RotationType, NumLogFiles, Amount, and Unit are optional and you only need to specify if logging to a rotated log file.

RotateLogFile

0 = Do not rotate log file

1 = Rotate log file

RotationType

0 = Rotate log files when log file size exceeds the amount specified by Amount and Unit

1 = Rotate log files when log file age exceeds the amount specified by Amount and Unit

NumLogFiles

The number of log files used in the rotation.

Amount

For RotationType=0 : Amount is a file size

For RotationType=1 : Amount is a file age

Unit For RotationType=0

Unit relates to the size of the file and specifies whether the Amount is Bytes, KB, MB, and so on.

0 = Bytes

1 = Kilobytes

2 = Megabytes

3 = Gigabytes

Unit For RotationType=1

Unit relates to the age of the file and specifies whether the Amount is Minutes, Days, Weeks, and so on.

0 = Minutes

1 = Hours

2 = Days

3 = Weekdays

4 = Weeks

5 = Months

6 = Quarters

7 = Years

Example usage

This example shows you how to create an ActionLogToFile script.

Filename = "C:\Program files\Syslogd\Logs\TestLog.txt" MsgPriority = "Local7.Info"

MsgHostAddress = Fields.VarPeerAddress

' Use the date and time from the current message MsgDate = Fields.VarDate & " " & Fields.VarTime

MsgText = "This is a test message from the scripting action"

Data = MsgDate & vbtab & MsgPriority & vbtab & MsgHostAddress & vbtab & MsgText

RotateLogFile = 1 'Rotate this log

RotationType = 0 'Using File size rotation -

NumLogFiles = 4 'Use up to 4 log files

Amount = 1000 'Each log file no more than 1000

Unit = 0 'bytes in length

Call Fields.ActionLogToFile(Filename, Data, RotateLogFile, RotationType, NumLogFiles, Amount, Unit)

Fields.ActionSendSyslog(Hostname, Message, Port, Protocol)

Details

This function sends a syslog Message to Hostname on Port via Protocol. Use this function to send syslog messages to another syslog host via the UDP or TCP protocol.

Return value None
Hostname

Text string containing the host name or IP address of the remote host.

Message Text string containing the priority tag and syslog message text
Port Integer between 1 and 65535 (514 is the standard syslog port)
Protocol Integer between 0 and 1 (0=UDP, 1=TCP)
Example

Hostname = "10.0.0.1" ' Remote syslog host

Priority = 191 ' Local7.Debug

Port = 514 0 ' Use the standard syslog port

Protocol = ' 0=UDP, 1=TCP

' Construct the syslog message by adding <PRI> value to the front of the text Message = "<" + Cstr(Priority) + ">" + "This is an example of a syslog message"

Call Fields.ActionSendSyslog(Hostname, Message, Port, Protocol)

Fields.ActionSpoofSyslog(AdapterAddress, SrcAddress, DstAddress, DstPort, Message)

Details This function sends a spoofed Syslog Message (UDP only) to DstAddress on Port DstPort. Use this function to send syslog messages to another syslog host via the UDP protocol.
Return value None
AdapterAddress

Text string containing the IP address or MAC address of the network adapter that the message is sent from.

SrcAddress Text string containing the host name or IP address of the source of the message (actual or spoofed).
DstAddress Text string containing the host name or IP address of the remote (receiving) host.
DstPort Integer between 1 and 65535 (514 is the standard syslog port)
Message

Text string containing the priority tag and syslog message text

Example

AdapterAddress = "192.168.1.100" ' Adapter Address (this can be IP Address or MAC address)

SrcAddress = "192.10.10.1" ' Source of message

DstAddress = "10.0.0.1" ' Destination of message

DstPort = 514 ' Use the standard syslog port

Priority = 191 ' Local7.Debug

Construct the syslog message by adding the<pri> value to the front of the text Message = "<" + Cstr(Priority) + ">" + "This is an example of a syslog message"

Call Fields.ActionSpoofSyslog(AdapterAddress, SrcAddress, DstAddress, DstPort, Message)

You must install Windows Packet Capture library (WinPcap) version 4.1 or later to access the SPOOFSYSLOG field. See WinPcap, The Packet Capture and Network Monitoring Library for Windows to download.

Fields.ActionLogToFileWithCache(Filename, Data, [RotateLogFile] , [RotationType] , [NumLogFiles] , [Amount] , [Unit])

Details

This function writes data to the log you specify. This function uses a write cache to improve performance. The cache is flushed either every 100 messages or every 5 seconds. Use registry settings to adjust the cache settings. SolarWinds recommends that you use the write cache function if you receive more than 10 messages per second.

Use this function to log messages to a file in your format. You can also use AutoSplit syntax values in the filename.

For example, to have the filename contain the current hour of the day, use %TimeHH: Filename = "C:\Program files\Syslogd\Logs\TestLog%TimeHH.txt"

Return value None
Example usage

Filename = "C:\Program files\Syslogd\Logs\TestLog.txt" MsgPriority = "Local7.Info"

MsgHostAddress = Fields.VarPeerAddress

' Use the date and time from the current message MsgDate = Fields.VarDate & " " & Fields.VarTime

MsgText = "This is a test message from the scripting action"

Data = MsgDate & vbtab & MsgPriority & vbtab & MsgHostAddress & vbtab & MsgText

Call Fields.ActionLogToFileWithCache(Filename, Data)

This example requires that you enable Read permission for Other fields. This gives the script read access to the VarDate and VarTime variables.

Log File Rotation:

The parameters RotateLogFile, RotationType, NumLogFiles, Amount, and Unit are optional and you only need to specify if logging to a rotated log file.

RotateLogFile

0 = Do not rotate log file

1 = Rotate log file

RotationType

0 = Rotate log files when log file size exceeds the amount specified by Amount and Unit

1 = Rotate log files when log file age exceeds the amount specified by Amount and Unit

NumLogFiles The number of log files to be used in the rotation.
Amount

For RotationType=0 : Amount is a file size

For RotationType=1 : Amount is a file age

Unit For RotationType=0

Unit relates to the size of the file and specifies whether the Amount is Bytes, KB, MB, and so on.

0 = Bytes

1 = Kilobytes

2 = Megabytes

3 = Gigabytes

Unit For RotationType=1

Unit relates to the age of the file and specifies whether the Amount is Minutes, Days, Weeks, and so on.

0 = Minutes

1 = Hours

2 = Days

3 = Weekdays

4 = Weeks

5 = Months

6 = Quarters

7= Years

Example usage

This example shows you how to create an ActionLogToFileWithCache script.

Filename = "C:\Program files\Syslogd\Logs\TestLog.txt" MsgPriority = "Local7.Info"

MsgHostAddress = Fields.VarPeerAddress

' Use the date and time from the current message MsgDate = Fields.VarDate & " " & Fields.VarTime

MsgText = "This is a test message from the scripting action"

Data = MsgDate & vbtab & MsgPriority & vbtab & MsgHostAddress & vbtab & MsgText

RotateLogFile = 1 'Rotate this log

RotationType = 0 'Using File size rotation -

NumLogFiles = 4 'Use up to 4 log files

Amount = 1000 'Each log file no more than 1000

Unit = 0 'bytes in length

Call Fields.ActionLogToFileWithCache(Filename, Data, RotateLogFile, RotationType, NumLogFiles, Amount, Unit)

Fields.ActionDeleteFile(Filename)

Details This function attempts to delete the file you specify. Use this function to delete a log file to ensure a fresh start. This function does not support wildcards. You must specify a file name. No confirmation is required, so use caution when using this function.
Return value None
Example usage

Filename = "C:\Program files\Syslogd\Logs\TestLog.txt"

Call Fields.ActionDeleteFile(Filename)

Fields.ActionDisplay(DisplayNumber, TabDelimitedMessage)

Details This function displays a message to the specified virtual display number. This function can be used to display messages on the screen in your format. The TabDelimitedMessage must contain 5 tab delimited fields. The contents of each field can be anything. The normal display fields are: Date TAB Time TAB Priority TAB Hostname TAB Message.
Return value None
Example usage

With Fields

MsgPriority = ConvertPriorityToText(.VarPriority)

MsgHostAddress = .VarPeerAddress

' Use the date and time from the current message MsgDate = .VarDate & " " & .VarTime

MsgText = "This is a test message from the scripting action"

Display = MsgDate & vbtab & MsgTime & vbtab & MsgPriority & vbtab &_

MsgHostAddress & vbtab & MsgText

Call .ActionDisplay(0, Display)

End with

Fields.ActionLogToODBC(DSNString, TableName, InsertStatement, Timeout)

Details

This function passes the InsertStatement to the database specified by DSNString and TableName. The timeout specifies how many seconds to keep the database connection open when idle.

Use this function to log messages to a database in your format. The connection to the database remains open internally to the program. This avoids the overhead of creating and breaking the connection each time a device sends data to the database. If no further data is sent to the database, after the timeout period elapses, the connection closes. The next time data is sent, the connection reopens.

Return value After successful execution, the field returns an empty string. Otherwise, the error passes back a string value.
Example usage

In this example, you create a System DSN called "KiwiSyslog" that points to a MS Access database. The SQL insert statement syntax changes depending on the database type that is written to.

This example:

  1. Requires you to enable Read permission for Other fields. This gives the script read access to the VarDate and VarTime variables.
  2. Assumes that you have created a table called "Syslogd" and that it contains the required fields.
  3. Has only been tested on MS Access 97 and MS Access 2000.

MyDSN = "DSN=KiwiSyslog;"

MyTable = "Syslogd"

MyFields = "MsgDate,MsgTime,MsgPriority,MsgHostname,MsgText"

' MS Access DB SQL INSERT command example:

' INSERT INTO Syslogd (MsgDate,MsgTime,MsgPriority,MsgHostname,MsgText)

' VALUES ('2004-08-08','13:26:26','Local7.Debug','host.company.com',

' 'This is a test message from Kiwi Syslog Server')

With Fields

' Construct the insert statement

SQLcmd = "INSERT INTO " & MyTable & " (" & MyFields & ") VALUES (" & _

Quote(.VarDate) & "," & Quote(.VarTime) & "," & _

Quote(.ConvertPriorityToText(.VarPriority)) & "," & _

Quote(.VarPeerAddress) & "," & Quote(.VarCleanMessageText) & ")"

' Log the data to database using DSN, Table, SQLcmd and Timeout of 30 seconds

.VarCustom01 = .ActionLogToODBC(MyDSN, MyTable, SQLcmd, 30)

' VarCustom01 now holds the return value from the function.

End with

Function Quote(Data)

' Replace all occurrences of ' with '' to escape existing quotes

' Wrap data with single quotes

Quote = "'" & Replace(Data, "'", "''") & "'"

End Function

Find additional example scripts in the \Scripts sub folder.