ultralog3 hspi user s guide - automated home...
TRANSCRIPT
UltraLog3 HSPI User’s Guide
A HomeSeer HS3 plug-in to store and retrieve HomeSeer and syslog events
Copyright © 2016
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 [email protected].
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: