UltraLog3 HSPI User’s Guide

A HomeSeer HS3 plug-in to store and retrieve HomeSeer and syslog events

Copyright © 2016

ultrajones@hotmail.com

Revised 02/25/2016

This document contains proprietary and copyrighted information and may not be copied, reproduced, translated, or reduced to any electronic medium without prior consent, in writing, from ultrajones@hotmail.com.

2

Table of Contents Introduction .................................................................................................................................................. 4

Intended Audience .................................................................................................................................... 4

UltraLog3 HSPI Overview .............................................................................................................................. 4

How It Works ............................................................................................................................................ 4

Features .................................................................................................................................................... 4

Requirements ............................................................................................................................................ 4

UltraLog3 HSPI Installation ........................................................................................................................... 5

Downloading and Installing the HomeSeer Plug-in .................................................................................. 5

UltraLog3 HSPI Configuration ....................................................................................................................... 5

Web Page Layout ...................................................................................................................................... 5

UltraLog3 HSPI Options ............................................................................................................................. 5

Database Options .................................................................................................................................. 6

Syslog Options ....................................................................................................................................... 6

Database Search Options ...................................................................................................................... 6

Web Page Access .................................................................................................................................. 6

Application Options .............................................................................................................................. 6

UltraLog3 HSPI Plug-in Devices ................................................................................................................. 6

Syslog Logger Device ............................................................................................................................. 6

Log Debug [Last 15 Mins] ...................................................................................................................... 6

Log Errors [Last 15 Mins]....................................................................................................................... 6

Log Info [Last 15 Mins] .......................................................................................................................... 6

Log Warnings [Last 15 Mins] ................................................................................................................. 7

Syslog Debug [Last 15 Mins] ................................................................................................................. 7

Syslog Errors [Last 15 Mins] .................................................................................................................. 7

Syslog Info [Last 15 Mins] ..................................................................................................................... 7

Syslog Warnings [Last 15 Mins] ............................................................................................................ 7

UltraLog3 HSPI Database Queries ................................................................................................................. 7

UltraLog3 Log Queries ............................................................................................................................... 7

Screenshot ............................................................................................................................................ 8

3

UltraLog3 Syslog Queries .......................................................................................................................... 8

Screenshot ............................................................................................................................................ 9

UltraLog3 HSPI Triggers ................................................................................................................................. 9

UltraLog3 Log Match ................................................................................................................................. 9

Screenshot .......................................................................................................................................... 10

UltraLog3 Syslog Match .......................................................................................................................... 10

Screenshot .......................................................................................................................................... 11

UltraLog3 HSPI Trigger Actions ................................................................................................................... 11

UltraLog3 Export Logs ............................................................................................................................. 11

Screenshot .......................................................................................................................................... 11

UltraLog3 HSPI Trigger Conditions .............................................................................................................. 12

UltraLog3 HSPI Regular Expression Captures ............................................................................................. 12

Non-named Capture ............................................................................................................................... 12

Example HomeSeer Event ....................................................................................................................... 12

UltraLog3 HSPI API Reference ..................................................................................................................... 14

4

Introduction UltraLog3 is a HomeSeer HS3 plug-in that stores HomeSeer and syslog events to an underlying database

in real-time. The built in web interface allows you to query the data making it easier to turn your home

automation log data into useful information.

Intended Audience This document is intended for the HomeSeer user that has chosen to install and configure the UltraLog3

HomeSeer Plug-in.

UltraLog3 HSPI Overview

How It Works

The UltraLog3 plug-in listens for HomeSeer events and inserts the log data into the database in real-

time. The log data can be filtered for display purposes and the search results can be sorted and

further searched to narrow down the log entries you are interested in.

The UltraLog3 plug-in adds a log trigger to HomeSeer that can be used to trigger a HomeSeer event

based on the type or content of a log entry. When an event triggers, the UltraLog3 plug-in updates

HomeSeer variables providing the ability for other scripts to access the log contents.

UltraLog3 can also listen for syslog events sent by Linux/Unix devices and supports similar features

available for HomeSeer log events.

Features

Multiple threading allows UltraLog3 to process HomeSeer and syslog events without disrupting

the performance of HomeSeer.

Supports HomeSeer triggers based on text or regular expression matches on HomeSeer log

events.

Supports syslog triggers based on text or regular expression matches on syslog log events.

Error Try/Catch logic to ensure plug-in doesn't fail with an unhandled exception.

Requirements Homeseer 3 or greater

5

UltraLog3 HSPI Installation

Downloading and Installing the HomeSeer Plug-in 1. From your HomeSeer web page, select PLUG-INS > Manage.

2. Click the + icon next to Additional Interfaces to expand the list of available HomSeer3 plug-ins.

3. Click the + icon next to the “Utilities” category, then click the checkbox next to the UltraGCIR3

plug-in package to mark the plug-in for installation.

4. Under “Pending Updates/Installs”, click the Download and Install button.

5. Once the installer finishes, find the UltraLog3 plug-in under Installed Plug-Ins, then enable it.

UltraLog3 HSPI Configuration

Web Page Layout The UltraLog3 plug-in has five web pages that provide access the available features of the plug-in.

The available web pages are as follows:

1. Status – Displays the plug-in status and database statistics.

2. Options – Displays and allows you to change the options associated with the plug-in.

3. Log – Provide the ability to quickly filter and display the data stored in the HomeSeer log

database.

4. Syslog – Provide the ability to quickly filter and display the data stored in the Syslog database.

UltraLog3 HSPI Options All options are set from the Options web page. The following options are supported:

6

Database Options

Retention – Specify the number of months’ worth of data to keep in the database.

Syslog Options

Enable Syslog On Startup – If set to Yes, this will start the syslog server when the plug-in starts.

The default is No.

Logging Severity – The option specifies which log level severity you want to direct to the

database. The logging severity will allow the selected level and higher events into the database.

The default logging severity is Informational.

IP Address – The IP address you want to bind to the syslog server. The default is an empty string

which allows the syslog server to listen on all interfaces.

UDP Port – Allows you to specify a custom syslog UDP port. The default is UDP port 514.

Database Search Options

Sort Order – Specifies the default sort order for filter queries. The default is descending.

Records Per Page – Specifies the number of records to display when performing filter queries.

The default is 25.

Web Page Access

Authorized User Roles – The HomeSeer users authorized to access the web page. This option

does not override the default HomeSeer web server settings.

Application Options

Trigger Loop Protection – Trigger loop protection ignores duplicate event log entries. This

option allows you to disable the built in HomeSeer event loop protection (not recommend).

Logging Level – Select the level of application logging.

Note: This option may produce a lot of output and should only be used when debugging.

UltraLog3 HSPI Plug-in Devices

Syslog Logger Device

This HomeSeer device allows you to enable or disable the syslog server. If you need to stop or start the

syslog server for any reason, simply select Enable or Disable from the HomeSeer Status web page.

Log Debug [Last 15 Mins]

This HomeSeer device tracks the number of debug log entries for the previous 15 minutes. The device is

updated every 15 minutes starting at the top of the hour.

Log Errors [Last 15 Mins]

This HomeSeer device tracks the number of error log entries for the previous 15 minutes. The device is

updated every 15 minutes starting at the top of the hour.

Log Info [Last 15 Mins]

This HomeSeer device tracks the number of informational log entries for the previous 15 minutes. The

device is updated every 15 minutes starting at the top of the hour.

7

Log Warnings [Last 15 Mins]

This HomeSeer device tracks the number of warning log entries for the previous 15 minutes. The device

is updated every 15 minutes starting at the top of the hour.

Syslog Debug [Last 15 Mins]

This HomeSeer device tracks the number of debug syslog entries for the previous 15 minutes. The

device is updated every 15 minutes starting at the top of the hour.

Syslog Errors [Last 15 Mins]

This HomeSeer device tracks the number of error syslog entries for the previous 15 minutes. The device

is updated every 15 minutes starting at the top of the hour.

Syslog Info [Last 15 Mins]

This HomeSeer device tracks the number of information syslog entries for the previous 15 minutes. The

device is updated every 15 minutes starting at the top of the hour.

Syslog Warnings [Last 15 Mins]

This HomeSeer device tracks the number of warning syslog entries for the previous 15 minutes. The

device is updated every 15 minutes starting at the top of the hour.

UltraLog3 HSPI Database Queries

UltraLog3 Log Queries The Log web page provides the ability to quickly filter and display the data stored in the HomeSeer log

database.

8

Screenshot

UltraLog3 Syslog Queries The Syslog web page provides the ability to quickly filter and display the data stored in the Syslog

database.

9

Screenshot

UltraLog3 HSPI Triggers

UltraLog3 Log Match This option allows you to trigger a HomeSeer event based on a text or regular expression match within a

HomeSeer log event. The following plug-in specific triggers are supported:

1. Look In Log – Specifies which part of the HomeSeer log event to search. a. Type – Search the HomeSeer log type (e.g. Info, Warning, Error, etc). b. Message – Search the HomeSeer message (e.g. Web Server Authorized login).

2. Match Type – Specifies what type of string comparison to perform. a. Contains b. Starts With c. Ends With d. Regular Expression

10

3. Match Value – Specifies the text string or regular expression used to trigger the HomeSeer event.

4. Notes – Enter text to help you remember what the UltraLog3 Log Match trigger does. When the UltraLog3 Log Match triggers, the following HomeSeer variables are updated:

1. LogType – Contents the HomeSeer log type. 2. LogMessage – Contents the HomeSeer log message.

If you specify named or parenthesized regular expression captures, then HomeSeer variables are automatically created based on your regular expression. See UltraLog3 HSPI Named Captures for more information.

The plug-in has built in protection to prevent a trigger from creating an endless loop.

Screenshot

UltraLog3 Syslog Match This option allows you to trigger a HomeSeer event based on a text or regular expression match within a

syslog event. The following plug-in specific triggers are supported:

1. Look In Syslog – Specifies which part of the syslog event to search. a. Hostname – Search the syslog hostname or IP address. b. Message Tag – Search the syslog tag. c. Message Content – Searches the syslog message contents.

2. Match Type – Specifies what type of string comparison to perform. a. Contains b. Starts With c. Ends With d. Regular Expression

3. Match Value – Specifies the text string or regular expression used to trigger the HomeSeer event.

4. Notes – Enter text to help you remember what the UltraLog3 Syslog Match trigger does. When the UltraLog3 Syslog Match triggers, the following HomeSeer variables are updated:

1. SyslogHostname – The hostname that generated the syslog message. 2. SyslogMsgTag – The tag portion of the syslog message. This is usually the name of the process

that generated the syslog message. 3. SyslogMsgContent – The syslog message contents.

11

If you specify named or parenthesized regular expression captures, then HomeSeer variables are automatically created based on your regular expression. See UltraLog3 HSPI Named Captures for more information. The plug-in has built in protection to prevent a trigger from creating an endless loop.

Screenshot

UltraLog3 HSPI Trigger Actions

UltraLog3 Export Logs This action allows you to export the HomeSeer log or Syslog database to a file at regular intervals.

Simply setup an event that is triggered either manually or at a reoccurring interval to save the database

logs to a text file.

Screenshot

12

UltraLog3 HSPI Trigger Conditions This plug-in does not have any HomeSeer trigger conditions defined.

UltraLog3 HSPI Regular Expression Captures If you specify named or parenthesized regular expression captures, then HomeSeer variables are automatically created based on your regular expression.

Non-named Capture In the following example, the HomeSeer global variable “1” would contain the IP address and the

variable “2” would contain the user name.

HomeSeer Log Line: Web Server authorized local login successful from: 127.0.0.1 User: default MatchValue Regular Expression: (\d+\.\d+\.\d+\.\d+) User: (.+)

Named Capture In the following example, the HomeSeer global variable “Hostname” would contain the IP address and

the variable “User” would contain the user name.

HomeSeer Log Line: Web Server authorized local login successful from: 127.0.0.1 User: default MatchValue Regular Expression: (?'Hostname'\d+\.\d+\.\d+\.\d+) User: (?'User'.+)

Example HomeSeer Event The following example demonstrates how logging into your HomeSeer web page causes the UltraLog3

plug-in to populate 2 global HomeSeer variables “Hostname” and “User” based on the regular

expression specified below and allows you to access the variables via script.

1. Create a new script file called sandbox.vb and place the following contents into that file:

Sub Main(parm As Object) Try Dim Hostname As String = GetHomeSeerVariable("Hostname") Dim User As String = GetHomeSeerVariable("User") hs.WriteLog("Debug", String.Format("{0} logged in from {1}.", User, Hostname)) Catch pEx As Exception ' ' Process program exception ' hs.WriteLog("Error", pEx.Message) End Try

13

End Sub Function GetHomeSeerVariable(ByVal strVariableName As String) As String Dim strVariableValue As String = String.Empty Try Dim objObject As Object = hs.GetVar(strVariableName) If TypeOf objObject Is String Then strVariableValue = CStr(objObject) End If objObject = Nothing Catch pEx As Exception ' Ignore errors End Try Return strVariableValue End Function

2. Move the script created in step 1 into the HomeSeer3 script directory. This step is required to

allow you to select from the HomeSeer3 event.

3. From the Events web page, select an existing event group or create a new one by clicking the

icon.

4. From the Events Group, click the icon to create a new event, then name the event

“HomeSeer Web Access”.

5. From the “IF” dropdown menu, select “UltraLog3: Log Match”.

In the “(Select Field)” dropdown, select “Message”.

In the “(Select Match Type)” dropdown, select Regular Expression.

In the text box, enter: (?<Hostname>\d+\.\d+\.\d+\.\d+) User: (?<User>.+)

Note: This regular expression contains 2 named captures “Hostname” and “User”.

6. From the “Then” dropdown, select “Run a Script or Script Command”.

7. Click the Edit button to choose or change the script file to run and select the script you created

in step 1.

8. To view or edit the contents of the script, click the “Switch to Advanced View” by clicking the

icon.

9. Click Save Script Edits if you make any changes to the script.

10. Test the script by logging into your HomeSeer web server from a system outside your local

network. The default HomeSeer settings should cause the following log entry to be written to

the log:

14

Web Server authorized login successful from: {xxx.xxx.xxx.xxx} User: {username}

11. If the HomeSeer event triggers correctly, your HomeSeer log should contain the following text:

{username} logged in from {xxx.xxx.xxx.xxx}.

UltraLog3 HSPI API Reference To be determined.