Script functions
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 |
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:
To play the squeak sound until canceled:
|
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 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 |
| 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 = SrcAddress = DstAddress = DstPort = Priority = Construct the syslog message by adding the |
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 |
| 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 |
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 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 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:
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. |