Documentation forKiwi Syslog Server

Add an action to run a script in KSS NG

KSS NG only supports PowerShell scripts.

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.

Create the script

You will need to create the script file before you can add an action to run it.

To create the script file:

  1. Write your script in a simple text editor such as Notepad to save it as a PowerShell file with a .ps1 extension.

    Choose a relevant name and include the .ps1 extension in the file name. For example, name a script file that replaces text as replace_text.ps1.

    See the following example script:

    # Replace cat with dog within the message text field
# Case insensitive replace
$Common.VarCleanMessageText = $Common.VarCleanMessageText -replace "cat", "dog"
					
# OR 
# Case sensitive replace
$Common.VarCleanMessageText = $Common.VarCleanMessageText.Replace('Message','LOG(replaced)')

# Return OK to indicate that the script ran correctly.
$Main = "OK"

  2. Test the script locally. Open the PowerShell application and navigate to the directory containing your script. Run the following command, using the same file name you created in step 1:

    .\replace_text.ps1

  3. Open the KSS NG web console and log in. From the navigation bar, choose Setup > Scripts.

  4. Click Add Script and select your script file to upload it to KSS NG.

Create the rule action to run a script

  1. From the KSS NG navigation bar, choose Setup > Rules.
  2. Locate an existing rule. If the rule does not exist, add a rule and start the New Rule wizard.
  3. If you are adding an action to an existing rule, select the rule and click Edit. If you are creating a new rule, navigate to the Actions step of the New Rule wizard.
  4. Click Add Action. Define the action name in the provided field.

  5. In the Action drop down, select Run script.

  6. Select the script you previously uploaded and review the read and write permissions.

    Field Read/Write permissions

    Select the groups of fields that KSS NG 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.

  7. If you are using the New Rule wizard, click Next.

    If you are adding the action to an existing rule, click Add. Review your changes, then click Apply.

Arrange the order of your rules to ensure the Run script rule action executes before actions that log the parsed messages. If the rules are not in the correct order, your messages will not be parsed before they are logged to files or a display. For details, see How rules, filters, and actions work.

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 KSS NG as a service, stop and restart the service to reload the file.

When running KSS NG 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.

Application mode is no longer supported as of KSS NG version 1.1. Uninstall and reinstall KSS NG to switch to Service mode.

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

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.