Documentation forKiwi Syslog Server

Add an action to run a script

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

You can add an action to run a script to filter or parse the current message.

You can use the Run script action to run a parsing script that breaks the syslog message down into various sub-fields. The values can then be assigned to custom fields and logged to a database. Because each device manufacturer creates syslog messages in a different format, it is not possible to create a generic parser that breaks up the message text into separate fields. You must write a custom script to parse the message text and then place it in the custom database fields. Example parsing scripts can be found in the \Scripts sub-directory in the Kiwi Syslog Server installation directory.

  1. From the Kiwi Syslog Service Manager, choose File > Setup.
  2. Add a rule, or locate an existing rule.
  3. Right-click Actions below the rule, and choose Add Action.
  4. Replace the default name with a descriptive name.

  5. From the Action menu, select Run Script.

  6. Specify the following options.

    Script file name

    Enter the path and file name of an existing script file or of the file to be created.
    Script description Describe the purpose or function or the script.
    Script language

    Select the scripting language.

    Windows Script provides two script engine languages, Visual Basic Scripting Edition and Microsoft JScript.

    Both languages offer similar functionality and speed, so the choice on which to use is up to personal preference. However, SolarWinds recommends the use of JScript if your script is performing mainly string manipulation. JScript appears to perform faster during string manipulation in most cases.

    It is also possible to use additional scripting languages, such as Perl or Python. To use one of the following languages, you must install the Active Scripting engine for that language:

    • PerlScript
    • Python

      Python extensions for Microsoft Windows includes access to the Win32 API. For more information see the Python for Windows Extension website (© 2018 Python Software Foundation, available at https://pypi.org/, obtained on December 20, 2018).

      Disclaimer: Please note, any content posted herein is provided as a suggestion or recommendation to you for your internal use. This is not part of the SolarWinds software or documentation that you purchased from SolarWinds, and the information set forth herein may come from third parties. Your organization should internally review and assess to what extent, if any, such custom scripts or recommendations will be incorporated into your environment. You elect to use third party content at your own risk, and you will be solely responsible for the incorporation of the same, if any.

    • RubyScript
    Edit script

    Click to open the script in a text editor. If the specified file does not exist, it is created.

    Modify the script and save your changes.

    Script file rules

    The script must always contain a function called Main(). No parameters are passed to the function, but a return value of OK must be passed back to indicate that the script ran successfully. If any value other than OK is returned, Syslog assumes an error has occurred in the script and place an entry in the error log. The value returned from the script function is included in the error log for later diagnoses.

    Each of the available script variables can be accessed from the Fields object.

    Example (VBScript):

    Function Main()
    ' Your code goes here 
    ' Set the return value 
    Main = "OK" 
    End Function

    Additional information on scripting

    For examples, descriptions of variables and functions, dictionaries, and a tutorial, see Scripting resources. Sample scripts are located in the \Scripts subdirectory in the Kiwi Syslog Server installation directory.
    Field Read/Write permissions

    Select the groups of fields that Kiwi Syslog Server can access:

    • When you grant read access to a group of fields, their values are copied into the script variables and are readable from within the script.
    • When you grant write access to a group of fields, their values are copied from the script variables and will replace the equivalent program fields.

    Each time a script runs, the available message fields are copied to the script variables and back again upon completion of the script. The copying takes time and uses CPU cycles. To improve script performance, SolarWinds recommends granting read and write access only to the variables used in the script.

    For more information about the fields in each group, see Script variables.

    A
  7. Test the action.
    1. Select if you want to see any changes that the script makes to the variables.
    2. Kiwi Syslog Server attempts to run the specified script.

      If an error occurs, a message displays the error description and the line number on which it occurred.

    3. If you select the Show test results option and the script runs successfully, a dialog shows the variable values before and after the script ran. Use this to see what variable values the script changed.
  8. Click Apply.

Script file caching

During normal operation, the script files are cached after they have been read from disk. This improves the program speed and prevents additional I/O. If you modify the script externally and save it back to disk, the changes do not take effect until the file is reloaded.

When running Kiwi Syslog Server as an application, do either of the following to reload the file:

  • Flush the cache. Choose File > Debug options > Clear the script file cache, or press Ctrl+F8 from the Service Manager console.
  • Restart the application.

When running Kiwi Syslog Server as a service, stop and restart the service to reload the file.

When you test a script from the Kiwi Syslog Server Setup window, the script is not cached. Each script is freshly loaded before it is run.

Triggering a script on a regular basis

To trigger a script on a regular basis, you can: