Syslog
Interface to the PI System
Version 1.0.0.6
How to Contact Us
Phone
(510) 297-5800
(510) 297-5828
Fax
(510) 357-8136
E-mail
techsupport@osisoft.com
World Wide Web
http://www.osisoft.com
Mail
OSIsoft
P.O. Box 727
San Leandro, CA 94577-0427
USA
OSIsoft (Australia)
Level3 Septimus Roe Square
256 Adelaide Terrace
Perth WA 6000
OSI Software GmbH
Hauptstrae 30
D-63674 Altenstadt 1
Deutschland
OSI Software, Asia Pte Ltd
152 Beach Road
#09-06 Gateway East
Singapore, 189721
(main number)
(technical support)
Unpublished – rights reserved under the copyright laws of the United States.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Trademark statement—PI is a registered trademark of OSIsoft, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and
Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. HP-UX is
a registered trademark of Hewlett Packard Corp.. IBM AIX RS/6000 is a registered trademark of the IBM Corporation. DUX, DEC
VAX and DEC Alpha are registered trademarks of the Digital Equipment Corporation.
PI_Syslog.doc
 2003-2005 OSIsoft, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577
ii
Table of Contents
Introduction ................................................................................................................... 1
Reference Manuals ..................................................................................................... 1
Supported Features ..................................................................................................... 2
Diagram of Hardware Connection ............................................................................... 4
Principles of Operation ................................................................................................ 5
Performance ................................................................................................................ 5
Syslog Format and Contents ....................................................................................... 6
Syslog Interface Message Types ................................................................................. 7
PIX........................................................................................................................... 7
Cisco IOS ................................................................................................................ 8
Syslog General ........................................................................................................ 9
Message Formatting .................................................................................................... 9
Installation Checklist .................................................................................................. 15
Interface Installation ................................................................................................... 17
Naming Conventions and Requirements ................................................................... 17
Interface Directories .................................................................................................. 17
The PIHOME Directory Tree .................................................................................. 17
Interface Installation Directory ............................................................................... 18
Interface Installation Procedure ................................................................................. 18
Installing the Interface as an NT Service ................................................................... 18
Installing the Interface Service with PI-Interface Configuration Utility..................... 18
Installing the Interface Service Manually ................................................................ 20
PointSource ................................................................................................................. 23
PI Point Configuration ................................................................................................ 25
Point Attributes .......................................................................................................... 25
Tag ........................................................................................................................ 25
PointSource ........................................................................................................... 25
PointType .............................................................................................................. 25
Location1 ............................................................................................................... 25
Syslog Interface to the PI System
iii
iii
Location2 ............................................................................................................... 25
Location3 ............................................................................................................... 26
Location4 ............................................................................................................... 27
Location5 ............................................................................................................... 27
InstrumentTag ....................................................................................................... 27
ExDesc .................................................................................................................. 27
Scan ...................................................................................................................... 29
Shutdown ............................................................................................................... 30
I/O Rate Tag Configuration......................................................................................... 31
Monitoring I/O Rates on the Interface Node .............................................................. 31
Configuring I/O Rate Tags with PI-ICU (NT-Intel) ...................................................... 31
Configuring I/O Rate Tags Manually .......................................................................... 32
Configuring the PI Point on the PI Server .............................................................. 32
Configuration on the Interface Node ...................................................................... 33
Startup Command File ................................................................................................ 35
Configuring the Interface with PI-ICU ........................................................................ 35
syslog Interface Tab .............................................................................................. 37
Command-line Parameters ........................................................................................ 39
Sample PISyslog.bat File........................................................................................... 42
Interface Node Clock .................................................................................................. 43
Security........................................................................................................................ 45
Starting / Stopping the Interface ................................................................................ 47
Starting Interface as a Service .................................................................................. 47
Stopping Interface Running as a Service ................................................................... 47
Buffering ...................................................................................................................... 49
Configuring Buffering with PI-ICU (NT-Intel) .............................................................. 49
Configuring Buffering Manually.................................................................................. 53
Example piclient.ini File ............................................................................................. 54
Appendix A: Error and Informational Messages ....................................................... 55
Message Logs ........................................................................................................... 55
Messages .................................................................................................................. 55
Interface Startup Errors ......................................................................................... 55
Point Loading Errors .............................................................................................. 55
Point Debugging Messages ................................................................................... 56
iv
iv
Run-time Error ....................................................................................................... 56
Interface-level Debugging ...................................................................................... 56
Syslog Error Message............................................................................................ 57
System Errors and PI Errors ...................................................................................... 57
APPENDIX B: PI-PIX Firewall Interface Compatibility .............................................. 59
Migration ................................................................................................................... 59
Manual Migration ................................................................................................... 59
Migration Using the PI ICU .................................................................................... 59
Compatibility .............................................................................................................. 62
Count, Rate and User Points ................................................................................. 62
Appendix C: Extract from RFC3164 – 4.1.1 PRI ........................................................ 65
Revision History.......................................................................................................... 67
Syslog Interface to the PI System
v
v
Introduction
The syslog protocol is a standard for logging system events over a network. It
provides a transport to allow a machine to send event notification messages across IP
networks to event message collectors (also known as syslog servers). OSIsoft’s PISyslog Interface works as a syslog server for one or more devices. The interface
listens on the syslog port (UDP port 514) and collects the syslog messages sent by the
devices. The interface then matches each message with the appropriate PI Point and
sends the required part or parts of the messages to this Point.
A standard format for the syslog messages is recommended by the syslog protocol.
However, there are no set requirements on the contents of the syslog packet as it is
originally sent from a device. Therefore, the PI-Syslog Interface considers any packet
received from the syslog port a valid syslog message and records the information to
the corresponding PI points. In addition, the interface supports the specific syslog
message formats of devices such as Cisco PIX Firewall and other Cisco devices. PISyslog can recognize the device-specific syslog messages, parse the received packet
accordingly and store appropriate information to the corresponding PI points.
The PI-Syslog interface runs on Windows NT 4.0, Windows 2000 or Windows XP
operating systems. Unless otherwise noted, the remainder of this document uses the
term “Windows NT” to refer to all three.
PI-Syslog interface requires:

PI Server

PI-SDK/API

Internet Explorer 4.0 or greater (The interface uses the Internet Explorer
Regular Expression Engine to parse the syslog messages)
No special hardware is required by this interface.
The direction of data flow is uni-directional; that is, from the device(s) sending out
the syslog messages to the PI Server.
Reference Manuals
OSIsoft

UniInt End User Document

PI Server Manuals

PI-SDK Manual

Regular Expressions Tutorial
Cisco Systems

Cisco Systems, Inc Cisco PIX Firewall System Log Messages
Syslog Interface to the PI System
1
1
Introduction

Cisco – Setting Up PIX Syslog

Cisco-System Error Messages Overview
Other

The BSD Syslog Protocol http://www.ietf.org/rfc/rfc3164.txt
Supported Features
Feature
2
Support
Part Number
PI-IN-OS-SYSLOG-NT
Platforms
Windows NT 4.0 / W2K / XP
APS Connector
No
Point Builder Utility
No
ICU Control
Yes
PI Point Types
Float16 / float32 / float64 / int16 / int32 /
digital / string
Sub-second Timestamps
Yes
Sub-second Scan Classes
No
Automatically Incorporates PI Point
Attribute Changes
Yes
Exception Reporting
Yes
Outputs from PI
No
Inputs to PI: Scan-Based / Unsolicited /
Event Tags
Unsolicited
Maximum Point Count
Point count of PI Server
Uses PI-SDK
Yes - Requires PI-SDK v1.3.1 (or higher)
PINet to PI 3 String Support
Not applicable
* Source of Timestamps
PI Server
History Recovery
No
Failover
No
* UniInt-based
Yes
Vendor Software Required on PI-API /
PINet Node
No
Vendor Software Required on Foreign
Device
No
Vendor Hardware Required
No
* Additional PI Software Included with
Interface
Yes
2
Device Point Types
Not applicable
* See paragraphs below for further explanation.
Source of Timestamps
The clock on the computer running the PI Server provides the source of the
timestamps for the data sent by PI-Syslog. The interface writes a timestamp that
reflects the time at which it processed the Syslog packet.
UniInt-based
UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an
OSIsoft-developed template used by our developers and is integrated into many
interfaces, such as the PI-Syslog interface. The purpose of UniInt is to keep a
consistent feature set and behavior across as many of our interfaces as possible. It
also allows for the very rapid development of new interfaces. In any UniInt-based
interface, the interface uses some of the UniInt-supplied configuration parameters and
some interface-specific parameters. UniInt is constantly being upgraded with new
options and features.
The UniInt End User Document is a supplement to this manual.
Note: The interface does not use UniInt functions to write data to the PI server. For
this reason UniInt parameters related to writing data (for example /q and /sn) have no
effect on the interface. The interface uses the PI-API function pisn_sendexceptionqx
to write data to PI.
Additional PI Software
A utility for testing regular expressions (RegExpTester.exe) is included in the install
of this interface. This utility is useful for testing the syntax of regular expressions
before using them in a PI Point.
Syslog Interface to the PI System
3
3
Introduction
Diagram of Hardware Connection
Windows NT
PI Server
PI-API
(Windows NT or Unix)
PI-SDK
PI-Syslog Interface
UDP
Device(s)
4
4
Principles of Operation
The PI-Syslog Interface functions as a syslog server: It listens to either UDP port 514
(the syslog port) or any other specified port and collects the syslog messages sent by
one or more devices. The Interface continuously reads the syslog port in a dedicated
process thread, upon receiving each syslog packet; the interface checks the length of
the received message. Because the length of a syslog packet should not exceed 1024
bytes, if a packet longer than 1024 bytes is received, the interface will truncate it to fit
this limit before processing the message (see /stsp). The interface adds each message
to an internal queue to be processed. The interface checks each PI Point loaded by the
interface, with each syslog message. Where the syslog message matches the filter
expression of this point the messages sent to PI in the format dictated by the Points
Location3.
Performance
If the syslog port is receiving messages at a high rate, the interface may not be able to
process the messages quickly in which case it is possible to overflow the interface’s
internal queue. If the internal queue were to grow without bound, the interface would
eventually consume all available memory causing the interface to crash. In order to
prevent this, the interface monitors the size of the internal queue and if this size
exceeds the maximum allowed, the interface will discard new messages coming in to
the interface up to the time the queue has recovered. If the size of the internal queue
length causes the interface to stop reading syslog messages, the interface writes the
system digital state I/O Timeout to all its tags after the internal queue is processed.
The interface uses a timestamp of one second after the last syslog message was read.
This maximum queue size has a default size of 50,000, but may be adjusted by using
the /mxQ=x command-line parameter. The size of the queue should be large enough
to prevent transient periods of high message loads from causing messages to be lost.
Three performance counters are provided to assist in monitoring the interface load:
1. Syslog Message Queue Length: This provides the current length of the
internal queue.
2. Syslog Message Process Rate: This is the approximated rate in
messages/minute at which the interface processes messages. The rate the interface
processes messages depends on the number of points in the interface, the type and
complexity of the filter expressions in each point, the number of messages that
require writing values to PI and the CPU load of the interface machine. If this rate
is close to the rate messages are being sent to the syslog port, then Interface
performance may be a problem. Note: This rate is approximate and may decrease
as the message rate increases.
3. Syslog Message Rate: This is the rate syslog messages are being read by the
interface in messages/minute.
Syslog Interface to the PI System
5
5
Principles of Operation
Syslog Format and Contents
A syslog packet is a string of printable and non-printable ASCII characters. The total
length of the packet must be 1024 bytes or less. Typically a syslog packet contains
three discernable parts:

PRI (Facility and Severity)

HEADER

MSG
It is recommended that a syslog packet have all three parts. But there are no set
requirements on the contents of the syslog packet as it is originally sent from a
device. For example a syslog packet may have only the MSG part or have any part
missing. The order of the parts, however, can not be interchanged.
PRI (Facility and Severity)
The PRI part starts with a leading “<”, followed by a number, which is followed by a
“>”. The number contained within these angle brackets is known as the Priority value
and represents both the Facility and Severity.
All syslog messages have a logging Facility and a Severity level. The logging
Facility can be thought of as “where” and the Severity level can be thought of “what.”
The Facilities and Severities of the messages are numerically coded with decimal
values. The PRI part that contains a Priority value is included in a syslog packet and
represents both the Facility and Severity. The Priority value is calculated by first
multiplying the Facility number by 8 and then adding the numerical value of the
Severity.
HEADER
The HEADER part typically contains two fields called the TIMESTAMP and the
HOSTNAME. The TIMESTAMP is the local time and is in the format of
Mmm dd hh:mm:ss
where:
Mmm is the English language abbreviation for the month of the year with the
first character in uppercase and the other two characters in lowercase. The
following are the only acceptable values: Jan, Feb, Mar, Apr, May, Jun, Jul,
Aug, Sep, Oct, Nov, Dec.
dd is the day of the month. If the day of the month is less than 10, then it
must be represented as a space and then the number.
hh:mm:ss is the local time. The hour (hh) is represented in a 24-hour
format. Valid entries are between 00 and 23. The minute (mm) and second
(ss) entries are between 00 and 59.
The HOSTNAME field contains either the hostname or the IP address of the
originator of the message.
6
6
MSG
The MSG part usually contains some additional information of the process that
generated the message, and then the text of the message. It has two fields known as
the TAG field and the CONTENT field. The value in the TAG field may be the name
of the program or process that generated the message. The CONTENT contains the
details of the message.
As an example, a valid syslog message is as follows:
<34>Dec 18 17:58:26 mymachine su: ‘su root” failed for lonvick on /dev/pts/8
Thus

PRI: 34 (Facility 4 Severity 2)

Header: Dec 18 17:58:26 mymachine

MSG: su: ‘su root” failed for lonvick on /dev/pts/8
But as discussed previously, the aforementioned format of the syslog messages is
recommended, but not required. Therefore, different programs, processes and devices
can send out syslog packets with different formats. For example, the MSG part of a
System log packet sent by the PIX Firewall always begins with a percent sign (%) and
is structured as follows:
%PIX-Level-Message_number: Message_text
Syslog Interface Message Types
To facilitate the correct interpretation of each message, points in this interface can be
configured to treat a syslog message as one of four categories.
PIX
Syslog messages sent by a Cisco PIX Firewall contain information about the status of
connections within this firewall. Typically these messages have the form:
<PRI>TimeStamp Host %PIX-Level-Message_number: Message_text
For example:
<164>Jul 16 2003 17:15:32 OSIFirewall001 : %PIX-4-400024 IDS: 2151 Large ICMP Traffic
from 10.4.1.2 to 10.2.1.1 on interface dmz
Syslog Interface to the PI System
7
7
Principles of Operation
Where:
<PRI>
Timestamp
The PRI (facility and severity)
The time the message was generated
Host
The Host Name or IP address of the originating device
PIX
Identifies the message facility code for message generated by the PIX
Firewall. This value is always PIX.
Level
Message_number
Message_text
The level reflects the severity of the condition described by the message.
The lower the number, the more severe the condition.
A unique 6-digit number that identifies the message.
A text string describing the condition. This portion of the message
sometimes includes IP addresses, port numbers or usernames.
The interface will attempt to parse out the following fields from a syslog message:

Facility number (from the PRI)

Severity number (from the PRI)

TimeStamp

Host

Level

MSG
Cisco IOS
Cisco devices may provide IOS messages to a syslog server. These syslog messages
include messages in a standardized format (often called system error messages) and
output from debug commands. Messages are of the form:
%facility-severity-mnemonic: message-text
These messages are often preceded with additional information like time and
sequence-number, for example:
000013: Mar 18 14:52:10.039:%LINK-5-CHANGED: Interface Serial3/3, changed state to
administratively down
The message may also be preceded by a PRI.
Syslog messages with the message component starting with %name-number-name are
suitable to be considered type Cisco IOS. This does not exclude PIX type messages.
Facility Name
Level
mnemonic
Message_text
Identifies the message facility code, in this case LINK
The level reflects the severity of the condition described by the message.
The lower the number, the more severe the condition.
General description of message type
A text string describing the condition.
The interface will attempt to parse out the following fields from a syslog message

8
Facility: (from PRI)
8

Severity: (from PRI)

TimeStamp: Any valid time before the first %

Host

Level

MSG: The entire message after the fist %

Facility Name: This is the facility after the first %
Syslog General
Although the Syslog standard does not impose requirements on a syslog message
format, RFC 3164 – The BSD syslog protocol guidelines, provides a recommended
format for syslog messages. Points of this category will treat the syslog message as if
it were in this recommended format. That is, the message will typically be of the
form:
<PRI>TimeStamp Host Message
where the PRI, if it exists, is at the start of the message and is enclosed in the “<’ and
“>” characters, and other fields are separated by spaces or other non-alphanumeric
characters. The interface will make its best guess at parsing out the fields if the packet
does not comply with the above format.
The Interface will attempt to parse out the following fields from a syslog message:

Facility number: (from PRI)

Severity number: (from PRI)

TimeStamp: Any valid time at the start of the header

Host: The first field after the time, or if the time is not found, the field after the PRI

MSG: The entire message following the TimeStamp field
Note: The timestamp field is usually expected to immediately follow the PRI. This
interface will accept the first valid timestamp within two fields of the start of the syslog
message. This is to accommodate additional fields like the sequence number of the
Cisco IOS message type. A field is delimited by a space or a non-printable character.
Note: In Syslog messages that do not include a host field, the Host will be equal to the
first field in the MSG part. In order to ensure no part of the message is missing when
written to the PI Point, the Syslog general MSG is the entire message after the
TimeStamp.
Message Formatting
The PI points associated with the PI-Syslog Interface can be categorized as one of the
above types: PIX, General and IOS. Each point category (Location2) treats the
syslog message as described above. Messages that satisfy the filtering criteria in the
point’s ExDesc attribute are written to the PI Point. The part of the syslog message
sent to each point is determined by the PI Point’s Location3.
Syslog Interface to the PI System
9
9
Principles of Operation
Category
(Location2)
0
PIX
Point Value
This type of point should only be used for syslog messages from Cisco PIX
firewalls with the message format described in the previous section. If the
packet qualifies the filtering rules in the PI Point’s Extended Descriptor,
then the interface writes the following to this PI Point:
Location3=0 The PI Point contains all the components of the syslog
packet (Facility, Severity, TIMESTAMP, HOSTNAME and MSG)
separated by the pipe character “|”.
Location3=1 The PI Point contains only the MSG part of the syslog
message.
Location3=2 The PI Point contains the Facility.
Location3=3 The PI Point Contains the Severity.
Location3=4 The PI Point Contains the IP of the device that sends the
syslog message.
Location3=5 The PI Point contains the count of syslog messages
satisfying the filtering rules in the ExDesc attribute.
Location3=6 The PI Point contains the Rate (messages per second) of
syslog messages satisfying the filtering rules in the Exdesc attribute.
Loctaion3=7 The PI Point contains the part of the syslog messages
extracted by a user-defined Regular expression - Substitution pair.
1
Retained for backward compatibility with the PI-PIX interface
2
Retained for backward compatibility with the PI-PIX interface
3
Retained for backward compatibility with the PI-PIX interface
4
This type of point should only be used for Cisco IOS syslog messages with
the message format described in the previous section. If the packet qualifies
the filtering rules in the PI Point’s Extended Descriptor, then the interface
writes the following to the PI Point:
IOS
Location3=0 The PI point contains all the components of the syslog
packet (Facility, Severity, TIMESTAMP, HOSTNAME and MSG)
separated by the pipe character “|”.
Location3=1 Point contains only the MSG part of the syslog message.
Location3=2 Point contains the Facility number.
Location3=3 Point Contains the Severity number.
Location3=4 Point Contains the IP of the device that sends the syslog
message.
Location3=5 Point contains the count of syslog messages satisfying the
filtering rules in the ExDesc attribute.
Location3=6 Point contains the Rate (messages per second) of syslog
messages satisfying the filtering rules in the ExDesc attribute.
Loctaion3=7 The PI Point contains the part of the syslog messages
extracted by a user-defined Regular expression - Substitution pair.
10
10
Category
(Location2)
5
General
Point Value
This type of point can be used for syslog messages in any format that
complies with the Syslog protocol. If the packet qualifies the filtering rules
in the PI Point’s Extended Descriptor, then the interface writes the
following to the PI Point:
Location3=0 The PI point contains all the components of the syslog
packet (Facility, Severity, TIMESTAMP, HOSTNAME and MSG)
separated by the pipe character “|”.
Location3=1 Point contains only the MSG part of the syslog message.
Location3=2 Point contains the Facility number.
Location3=3 Point Contains the Severity number.
Location3=4 Point Contains the IP of the device that sends the syslog
message.
Location3=5 Point contains the count of syslog messages satisfying the
filtering rules in the ExDesc attribute.
Location3=6 Point contains the Rate (messages per second) of syslog
messages satisfying the filtering rules in the ExDesc attribute.
Loctaion3=7 The PI Point contains the part of the syslog messages
extracted by a user-defined Regular expression - Substitution pair.
Examples
The interface receives the following packets in the last 10 seconds from a PIX
Firewall (IP address 162.98.12.1) that is configured to have the Facility as 20 and
to display the timestamp and the device ID (OSIFirewall001) in all syslog packets:
<164>Jul 16 2003 17:15:32 OSIFirewall001 : %PIX-4-400024 IDS: 2151 Large ICMP Traffic
from 10.4.1.2 to 10.2.1.1 on interface dmz
<163>Jul 16 2003 17:15:35 OSIFirewall001 : %PIX-3-106010: Deny inbound tcp src
outside:201.123.2.10/6404 dst outside:210.164.1.1/32123
<28> Jul 16 2003 17:15:35 named[29356]: [ID 295310 daemon.warning] owner name
"gc._msdcs.wiredigital.com" IN (secondary) is invalid - proceeding anyway
<164>Jul 16 2003 17:15:42 OSIFirewall001 : %PIX-4-400013 IDS: 2003 ICMP redirect from
108.14.8.1 to 128.1.5.11 on interface dmz
Syslog Interface to the PI System
11
11
Principles of Operation
If the user creates PI points with the following configurations:
PI Point Name
Firewall_Attack_Log
Category
Output
Filtering Rules
Location2
Location3
ExDesc
PIX
0
0
Firewall_Warning_Count
Severity=4
1_Filter=-400024
PIX
5
0
Severity: 4
Counting interval:
Location5=10 (seconds)
Severity4_Warning_Count
General
5
5
Severity: 4
Location5=10 (seconds)
...then the values of these PI points written by the PI-Syslog interface are:
PI Point Name
Firewall_Attack_Log
PI Point Value
20|4|Jul 16 2003 17:15:32|OSIFirewall001| %PIX-4400024 IDS: 2151 Large ICMP Traffic from 10.4.1.2 to
10.2.1.1 on interface dmz
Firewall_Warning_Count
2
Severity4_Warning_Count
3
For Firewall_Attack_Log, only the first packet satisfies the filtering rules. The
components of this syslog packet are stored in a single string tag, separated by the
pipe character (|), in the order listed below:
1. Facility
2. Severity
3. TIMESTAMP
4. HOSTNAME
5. MSG
If the PIX Firewall is not set to display the device ID, then this point would have the
following value:
20|4|Jul 16 2003 17:15:32||%PIX-4-400024 IDS: 2151 Large ICMP Traffic from 10.4.1.2
to 10.2.1.1 on interface dmz
For Firewall_Warning_Count, the first, third, and fourth packets have Severity 4,
however only the first and fourth are of type PIX. Thus Firewall_Warning_Count
is 2 and Severity4_Warning_Count is 3.
12
12
Points can also be configured so that the interface records other details of Syslog
messages such as Facility, Severity, IP address of the message originator, and the
MSG part of the PIX Firewall. Thus, for the previous example, the PI-Syslog
Interface can write the respective values to the following PI points of PIX type:
Firewall_Attack_Log_Facility : 20
Firewall_Attack_Log_Severity : 4
Firewall_Attack_Log_Device : 162.98.12.1
Firewall_Attack_Log_Msg : %PIX-4-400024 IDS: 2151 Large ICMP
Traffic from 10.4.1.2 to 10.2.1.1 on interface dmz
...assuming that they have the same filtering rules as Firewall_Attack_Log.
Syslog Interface to the PI System
13
13
Installation Checklist
For those users who are familiar with running PI data collection interface programs,
this checklist helps you get the PI-Syslog Interface running. If you are not familiar
with PI interfaces, you should return to this section after reading the rest of the
manual in detail.
1. Install the PI-Interface Configuration Utility (which installs PI-SDK and PI-API)
2. Verify that PI-API has been installed.
3. Install the interface.
4. Choose a unique point source.
5. Configure PI points.
Location1 is the interface instance.
Location2 is the point category.
Location3 is the output style.
Location4 is zero for all points..
Location5 defines the counting interval (seconds) for Count and Rate types
of PI Points.
ExDesc contains the filtering rules and Regular Expression matching and
substitution rules.
InstrumentTag is not used.
6. Configure I/O Rate tag.
7. Configure the interface using the PI-ICU utility or edit startup command file
manual. It is recommended to use PI-ICU whenever possible..
8. Set interface node clock.
9. Set up security.
10. Start the interface without buffering.
11. Verify data.
12. Stop interface, start buffering, start interface.
Syslog Interface to the PI System
15
15
Interface Installation
OSIsoft recommends that interfaces be installed on PI Interface Nodes instead of directly
on the PI Server node. A PI Interface Node is any node other than the PI Server node
where the PI Application Programming Interface (PI-API) has been installed (see the
PI-API Installation Instructions manual). With this approach, the PI Server need not
compete with interfaces for the machine’s resources. The primary function of the
PI Server is to archive data and to service clients that request data.
After the interface has been installed and tested, Bufserv should be enabled on the PI
Interface Node (once again, see the PI-API Installation Instructions manual). Bufserv is
distributed with the PI-API. It is a utility program that provides the capability to store and
forward events to a PI Server, allowing continuous data collection when communication
to the PI Server is lost. Communication will be lost when there are network problems or
when the PI Server is shut down for maintenance, upgrades, backups, or unexpected
failures.
In most cases, interfaces on PI Interface Nodes should be installed as automatic services .
Services keep running after the user logs off. Automatic services automatically restart
when the computer is restarted, which is useful in the event of a power failure.
The guidelines are different if an interface is installed on the PI Server node . In this case,
the typical procedure is to install the PI Server as an automatic service and interfaces as
manual services that are launched by site-specific command files when the PI Server is
started. Interfaces that are started as manual services are also stopped in conjunction with
the PI Server by site-specific command files. Bufserv can be enabled on the PI Server
node so that interfaces on the PI Server node do not need to be started and stopped in
conjunction with PI, but it is not standard practice to enable buffering on the PI Server
node. See the UniInt End User Document for special procedural information.
Naming Conventions and Requirements
In the installation procedure below, it is assumed that the name of the interface
executable is PIsyslog.exe and that the startup command file is called
PIsyslog.bat.
It is customary for the user to rename the executable and the startup command file when
multiple copies of the interface are run. For example, one would typically use
PIsyslog1.exe and PIsyslog1.bat for interface number 1, PIsyslog2.exe and
PIsyslog2.bat for interface number 2 and so on. When an interface is run as a service,
the executable and the command file must have the same root name because the service
looks for its command-line arguments in a file that has the same root name.
Interface Directories
The PIHOME Directory Tree
The PIHOME directory tree is defined by the PIHOME entry in the
pipc.ini configuration file. This pipc.ini file is an ASCII text file, which is located
in the WinNT directory. A typical pipc.ini file contains the following lines:
[PIPC]
Syslog Interface to the PI System
17
17
Interface Installation
PIHOME=c:\pipc
The above lines define the \pipc directory as the root of the PIHOME directory tree on
the C: drive. OSIsoft recommends using \pipc as the root directory name. The
PIHOME directory does not need to be on the C: drive.
Interface Installation Directory
Place all copies of the interface into a single directory. The suggested directory is:
PIHOME\interfaces\Syslog\
Replace PIHOME with the corresponding entry in the pipc.ini file.
Interface Installation Procedure
The PI-Syslog interface setup program uses the services of the Microsoft Windows
Installer. Windows Installer is a standard part of Windows 2000. When running on
Windows NT 4.0 systems, the PI-Syslog setup program will install the Windows Installer
itself if necessary. To install, run the PI_syslog_x.x.x.x.exe installation kit.
Installing the Interface as an NT Service
The PI-Syslog interface service can be created with the PI-Interface Configuration
Utility, or can be created manually.
Installing the Interface Service with PI-Interface Configuration Utility
The PI-Interface Configuration Utility provides a user interface for creating, editing, and
deleting the interface service:
18
18
Service Configuration
Service name
The Service to Add box shows the name of the current interface service. This service
name is obtained from the interface executable.
Display name
The Display Name text box shows the current Display Name of the interface service. If
there is currently no service for the selected interface, the default Display Name is the
service name with a “PI-” prefix. Users may specify a different Display Name. OSIsoft
suggests that the prefix “PI-” be appended to the beginning of the interface to indicate
that the service is part of the OSI suite of products.
Startup Type
The Startup Type indicates whether the interface service will start automatically or need
to be started manually on reboot.

If the Auto option is selected, the service will be installed to start automatically
when the machine reboots.

If the Manual option is selected, the interface service will not start on reboot, but
will require someone to manually start the service.

If the Disabled option is selected, the service will not start at all.
Generally, interface services are set to start automatically.
Dependencies
The Installed services list is a list of the services currently installed on this machine.
Services upon which this Interface is dependant should be moved into the Dependencies
list using the
button. For example, if API Buffering is running, then “bufserv”
should be selected from the list at the right and added to the list on the left.
To remove a service from the list of dependencies, use the
name will be removed from the “Dependencies” list.
button, and the service
When the PI Interface is started (as a service), the services listed in the dependency list
will be verified as running (or an attempt will be made to start them). If the dependent
service(s) cannot be started for any reason, then the PI interface service will not run.
Note: Please see the PI Log and Operating System Event Logger for messages that may
indicate the cause for any server not running as expected.
- Add button
To add a dependency from the list of Installed services, select the dependency name, and
click the Add button.
- Remove button
To remove a selected dependency, highlight the service name in the Dependencies list,
and click the Remove button.
Syslog Interface to the PI System
19
19
Interface Installation
The full name of the service selected in the Installed services list is displayed below the
Installed services list box.
Create
The Create button adds the displayed service with the specified Dependencies and with
the specified Startup Type.
Remove
The Remove button removes the displayed service. If the service is not currently
installed, or if the service is currently running, this button will be grayed out.
Start or Stop Service
To Start or Stop an interface service, use the Start button
and a Stop button
on
the ICU toolbar. If this interface service is not currently installed, these buttons will
remain grayed out until the service is added. If this interface service is running, the Stop
button is available. If this service is not running, the Start button is available.
The status of the Interface service is indicated in the lower portion of the PI-ICU dialog.
Status of
the ICU
Status of the
Interface
Service
Service
installed or
uninstalled
Installing the Interface Service Manually
One can get help for installing the interface as a service at any time with the command:
PI_syslog.exe –help
Change to the directory where the PIsyslog1.exe executable is located. Then, consult
the following table to determine the appropriate service installation command.
NT Service Installation Commands on a PI Interface Node or a PI Server node
with Bufserv implemented
Manual service
PIsyslog.exe –install –depend “tcpip bufserv”
Automatic service
PIsyslog.exe –install –auto –depend “tcpip bufserv”
NT Service Installation Commands on a PI Interface Node or a PI Server node
without Bufserv implemented
Manual service
PIsyslog.exe –install –depend tcpip
Automatic service
PIsyslog.exe –install –auto –depend tcpip
When the interface is installed as a service on the PI Server node and when Bufserv is
not implemented, a dependency on the PI network manager is not necessary because the
interface will repeatedly attempt to connect to the PI Server until it is successful .
20
20
Note: Interfaces are typically not installed as automatic services when the interface is
installed on the PI Server node.
Check the Microsoft Windows NT services control panel to verify that the service was
added successfully. One can use the services control panel at any time to change the
interface from an automatic service to a manual service or vice versa .
Syslog Interface to the PI System
21
21
PointSource
The PointSource is a single, unique character that is used to identify the PI point as a
point that belongs to a particular interface. For example, one may choose the letter S to
identify points that belong to the PI-Syslog interface. To implement this, one would set
the PointSource attribute to S for every PI Point that is configured for the PI-Syslog
interface. Then, if one uses /ps=S on the startup-command line of the PI-Syslog
interface, the PI-Syslog interface will search the PI Point Database upon startup for every
PI point that is configured with a PointSource of S. Before an interface loads a point, the
interface usually performs further checks by examining additional PI point attributes to
determine whether a particular point is valid for the interface. For additional information,
see the /ps and /ID argument.
Case-sensitivity for PointSource Attributes
If the interface is running on a PINet node and the Server node is a PI 3 system, use a
capital letter (or a case-insensitive character such as a number, a question mark, etc.) for
the PointSource attribute when defining points. For all other scenarios, one does not need
to be careful with the case of the PointSource.
In all cases, the point source character that is supplied with the /ps command-line
argument is not case sensitive. That is, /ps=S and /ps=s are equivalent. One only needs
to be careful with the case of the PointSource during point definition, and only if the
interface will be running on a PINet node communicating to a PI 3 Server.
PI 3 Server Nodes
No point source table exists on a PI 3 Server, which means that points can be
immediately created on PI 3 with any point source character. Several subsystems and
applications that ship with PI 3 are associated with default point source characters. The
Totalizer Subsystem uses the point source character T, the Alarm Subsystem uses G and
@, Random uses R, RampSoak uses 9, and the Performance Equations Subsystem uses C.
You can either not use these point source characters or change the default point source
characters for these applications. Also, if one does not specify a point source character
when creating a PI point, the point is assigned a default point source character of L.
Therefore, it would be confusing to use L as the point source character for an interface.
Syslog Interface to the PI System
23
23
PI Point Configuration
The PI point is the basic building block for controlling data flow to and from the
PI Server. A single point is configured for each measurement value that needs to be
archived. Use the point attributes below to define what data to transfer.
Point Attributes
Tag
A tag is a label or name for a point. Any tag name can be used in accordance to the
normal PI point naming conventions.
PointSource
The PointSource is a single, unique character that is used to identify the PI point as a
point that belongs to a particular interface. For additional information, see the
/ps command-line argument and the “Point Source” section.
PointType
Typically, device point types do not need to correspond to PI point types. For example,
integer values from a device can be sent to floating point or digital PI tags. Similarly, a
floating-point value from the device can be sent to integer or digital PI tags, although the
values will be truncated.
Specifically for this interface, create float or integer PI points for storing Count, Rate
Facility and Severity values. String PI points are suitable for all other output values,
however Location3=7 type points where the string returned is guaranteed to represent a
number can be created as a float, integer or digital type.
Location1
Location1 indicates to which copy of the interface the point belongs.
Location2
Location2 is used to specify the category of the PI points. The meanings of the
Location2 codes are:
Location2
0
PI Point
Category
PIX
Syslog Interface to the PI System
Description
This type of point should be only used for syslog messages
from Cisco PIX firewalls with the MSG format described in
the previous section.
Normally the complete syslog packet is recorded to a single PI
point with the components of the syslog packet (Facility,
Severity, TIMESTAMP, HOSTNAME and MSG) separated
by the pipe character “|” if the packet qualifies the filtering
rules specified by PI point attribute ExDesc. It can also be
configured to record other details of the syslog packets such as
Facility, Severity and IP address of the PIX Firewall, and the
25 25
PI Point Configuration
MSG part (%PIX-Level-Message_number: Message_text) to a
PI point.
1-3
4
Retained for backward compatibility with the PI-PIX interface
(see Appendix B).
IOS
This type of point should be only used for Cisco IOS syslog
messages with the MSG format described in the previous
section.
Normally the complete syslog packet is recorded to a single PI
point with the components of the syslog packet (Facility,
Severity, TIMESTAMP, HOSTNAME and MSG) separated
by the pipe character “|” if the packet qualifies the filtering
rules specified by PI point attribute ExDesc. It can also be
configured to record other details of the syslog packets such as
Facility, Severity and IP address of the PIX Firewall, and the
MSG part (%PIX-Level-Message_number: Message_text) to a
PI point.
5
General
This type of points should be used with other non Cisco syslog
messages
Normally the complete syslog packet is recorded to a single PI
point with the components of the syslog packet (Facility,
Severity, TIMESTAMP, HOSTNAME and MSG) separated
by the pipe character “|” if the packet qualifies the filtering
rules specified by PI point attribute ExDesc. It can also be
configured to record other details of the syslog packets such as
Facility, Severity and IP address of the PIX Firewall, and the
MSG part (%PIX-Level-Message_number: Message_text) to a
PI point.
Location3
Location3 used to determine what is written to the PI server, if the received syslog packet
satisfies the filtering rule specified by PI point attribute ExDesc.
Location3
26
Description
0
The complete syslog packet with the components (Facility, Severity,
TIMESTAMP, HOSTNAME and MSG) separated by |.
1
The MSG part (%PIX-Level-Message_number: Message_text) contained in the
syslog packet is recorded to the PI tag.
2
The Facility number of the syslog message is written to the PI tag.
3
The Severity number is recorded.
4
The IP address of the device from which the interface receives the syslog
packets is stored.
5
Count - The number of the syslog messages satisfying the filtering criteria
specified by ExDesc is counted over a user-defined interval and is stored as the
point value into the PI server.
6
- The rate (messages per second) of the syslog messages satisfying the filtering
criteria specified by ExDesc is calculated over a user-defined interval and is
stored to a PI point
26
Location3
7
Description
User - The PI Point contains the part of the syslog messages extracted by a user
defined Regular expression - Substitution pair (see ExDesc)
Location4
Location 4 is not used for this interface. Set this to zero.
Location5
The data collection of PI-Syslog Interface is unsolicited. This means, the interface
collects data upon receiving syslog packets on the syslog port.
Location5 should be set to zero for all PI points associated with PI-Syslog interface,
except for the Count and Rate types of points. For Count and Rate Points
Location5 specifies the interval in seconds, over which the number of packets qualifying
the filtering criteria defined in the ExDesc is counted. At the end of this period the
Count or Rate is written to PI
InstrumentTag
InstrumentTag is not currently used for the PI-Syslog interface.
ExDesc
This is the extended descriptor attribute. PI-Syslog interface uses ExDesc to define the
filtering criteria and rules that determine if a syslog message belongs to this tag. That is,
the interface checks the filtering criteria against the syslog message, treating the syslog
message as if it where the type defined in Location2. Filter keywords should be
separated by a semicolon “;”.
The Syslog message must match each filter criteria for it to be input to PI. That is, each
filter field is combined with a logical AND.
As described in the “Principles of Operation” section, a syslog packet can be filtered
using the following keywords.
Standard Filtering Expressions

Facility= specifies Facility contained in the PRI part of the syslog packet. The
Facility can be an integer or a range of integers.

FacilityName= specifies the facility name in the %Facility-Level-mnemonic part
of an IOS message (not case sensitive, IOS only).

Severity= specifies Severity contained in the PRI.

Level= specifies Level (Severity) contained in the %Facility-Level-mnemonic part
of an IOS message (PIX and IOS only).

Host= specifies the HOSTNAME contained in the header part of a syslog packet
(not case insensitive).

Device= specifies the IP address of the device that sends the syslog messages.
Syslog Interface to the PI System
27
27
PI Point Configuration
n_Filter
In addition to the above standard filtering expressions, the interface is able to filter the
syslog message using one or more Regular Expression (RegExp) via the n_Filter
keyword. Thus if a syslog packet contains the contents specified by each n_Filter,
then this packet qualifies the filtering rule.
In the keyword n_Filter, the n is a number that corresponds to the particular rule
number and must increase continuously. If a PI point has filtering rules specified as:
1_Filter=…; 2_Filter=…; 4_Filter=…;
The filtering rules defined by 1_Filter and 2_Filter are considered, but the filtering
rule in 4_Filter is ignored because 3_Filter is missing.
RegExp and Sub
User type tags (Location3=7) have the additional ExDesc filters, RegExp and Sub.
RegExp defines the searching pattern to be found in the syslog packets and Sub specifies
what to extract out of the packets from within the string defined by RegExp. Sub must
come with RegExp as a pair. If no Sub is defined, whatever matches the searching
pattern defined in RegExp is returned and written to the corresponding PI point. If an
empty string is returned from the RegExp-Sub pair, then an empty string is written to PI.
Regular Expression is used for n_Filter and RegExp Sub, thus the specifications for
them must follow the Regular Expression requirements. For details about how to
configure RegExp and Sub, refer to the Regular Expression Tutorial document.
If any of these filtering and extracting keywords are omitted, the specification is the
same as “any.”
Note that for a PI 3 Server, the extended descriptor is limited to 1024 characters.
Point-level Debug
Point-level debugging can be enabled by including the string /db in the ExDesc
attribute. Point-level debugging prints a message to the log file for each Syslog message
received by the interface, indicating the reason the messages is rejected or written to this
point. In systems with a high rate of syslog messages this may cause the PIPC.log file to
become large quickly.
Example 1 – Cisco PIX Firewall
If the PI-Syslog interface is to record the syslog packets from a Cisco PIX firewall that
meets the following filtering criteria:
Facility: 20
Severity: 4
Host: Corporate-Firewall
Device: 128.10.22.111
...and the message part includes the substring “IDS” and a message number of
“400013”
Then the ExDesc should be specified as:
Facility=20; Severity=4; Host=Corporate-Firewall;
Device=128.10.22.111; 1_Filter=IDS; 2_Filter=400013;
Also
28
28
Location2=0 (PIX)
Location3=0 (complete syslog packet)
PointType=string
Example 2 -- MotherBoard Monitor
A device sends CPU temperature information in the following packet:
<29>Feb 20 15:04:37 PC112 MBM[CPU Temp]: C=46 LA=5 HA=70 L=1 H=49 A=47
If the interface is to record the temperature (46 in this case) for any messages from host
PC112 about CPU Temp, the ExDesc should be specified as:
Host= PC112; 1_Filter=MBM\[ CPU Temp \]; RegExp=C=(\d+); Sub=$1
Also
Location2=5 (General)
Location3=7 (User)
PointType=float32
Note: In regular expression syntax the “[“ and “]” characters have special meanings. We
need to “escape” these special characters with the “\” (see the Regular Expressions
Tutorial or other documentation for a list of reserved characters and other tips for using
Regular Expressions). Also note that as the string returned from the syslog message is
guaranteed to be a number, we can make this tag a real or integer PointType.
Example 3 – Number of Syslog Packets Each Minute
If the interface is to record the number of syslog packets each minute from any devices
that meet the following filter criteria:
Facility: 16, 18, 20-22
Severity: 0-3, 5, 7
Then the ExDesc should be:
Facility=16,18,20-22; Severity=0-3,5,7;
Also
Location2=5(Generic)
Location3=5(count)
Location5=60
Example 4 – Record All Syslog Messages
If the interface is to record all syslog messages to a single PI point; this is useful when
initially configuring tags in the interface.
ExDesc=<blank>
Location2=5(Generic)
Location3=7(User)
Scan
By default, the Scan attribute has a value of 1, which means that scanning is turned on
for the point. Setting the scan attribute to 0 turns scanning off. If the scan attribute is 0
when the interface starts, SCAN OFF will be written to the PI point. If the scan attribute
Syslog Interface to the PI System
29
29
PI Point Configuration
is changed from 1 to 0 while the interface is running, SCAN OFF will also be written to
the PI point after the point edit is detected by the interface.
There is one other situation, which is independent of the Scan attribute, where UniInt
will write SCAN OFF to a PI point. If a point that is currently loaded by the interface is
edited so that the point is no longer valid for the interface, the point will be removed
from the interface, and SCAN OFF will be written to the point. For example, if the
PointSource of a PI point that is currently loaded by the interface is changed, the point
will be removed from the interface and SCAN OFF will be written to the point.
Shutdown
The shutdown attribute is used only if the server node is a PI 3 system.
The Shutdown attribute is 1 (true) by default. The default behavior of the PI Shutdown
subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The
timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by
the Snapshot Subsystem. The timestamp is usually updated every 15 minutes, which
means that the timestamp for the SHUTDOWN events will be accurate to within 15 minutes
in the event of a power failure. For additional information on shutdown events, refer to
PI Server manuals.
Note: The SHUTDOWN events that are written by the PI Shutdown subsystem are
independent of the SHUTDOWN events that are written by the interface when the
/stopstat=Shutdown command-line argument is specified.
One can disable SHUTDOWN events from being written to PI when PI is restarted by
setting the Shutdown attribute to 0 for each point. Alternatively, one can change the
default behavior of the PI Shutdown Subsystem to write SHUTDOWN events only for
PI points that have their Shutdown attribute set to 0. To change the default behavior, edit
the \PI\dat\Shutdown.dat file, as discussed in PI Server manuals.
Bufserv
It is undesirable to write shutdown events when Bufserv is being used. Bufserv is a
utility program that provides the capability to store and forward events to a PI Server,
allowing continuous data collection when the Server is down for maintenance, upgrades,
backups, and unexpected failures. That is, when PI is shut down, Bufserv will continue
to collect data for the interface, making it undesirable to write SHUTDOWN events to
the PI points for this interface.
30
30
I/O Rate Tag Configuration
An I/O Rate point can be configured to receive 10-minute averages of the total number of
exceptions per minute that are sent to PI by the interface. An exception is a value that has
passed the exception specifications for a given PI point. Since 10-minute averages are
taken, the first average is not written to PI until 10 minutes after the interface has started.
One I/O Rate tag can be configured for each copy of the interface that is in use.
Monitoring I/O Rates on the Interface Node
For NT and UNIX nodes, the 10-minute rate averages (in events/minute) can be
monitored with a client application such as ProcessBook.
Configuring I/O Rate Tags with PI-ICU (NT-Intel)
The PI-Interface Configuration Utility (PI-ICU) provides a user interface for creating and
managing IORates Tags.
PI-ICU currently allows for one I/O Rate tag to be configured for each copy of the
interface that is in use. Some interfaces allow for multiple I/O Rates tags.
Enable IORates for this Interface
The Enable IORates for this interface check box enables or disables IORates for the
current interface. To disable IORates for the selected interface, uncheck this box. To
enable IORates for the selected interface, check this box.
Tag Status
The Tag Status column indicates whether the IORates tag exists in PI. The possible states
are:

Created – This status indicates that the tag exist in PI

Not Created – This status indicates that the tag does not yet exist in PI

Deleted – This status indicates that the tag has just been deleted

Unknown – This status indicates that the ICU is not able to access the PI Server
In File
The In File column indicates whether the IORates tag listed in the tag name and the
event counter is in the IORates.dat file. The possible states are:
Syslog Interface to the PI System
31
31
I/O Rate Tag Configuration

Yes – This status indicates that the tag name and event counter are in the
IORates.dat file

No – This status indicates that the tag name and event counter are not in the
IORates.dat file
Event Counter
The Event Counter correlates a tag specified in the iorates.dat file with this copy of the
interface. The command line equivalent is /ec=x, where x is the same number that is
assigned to a tag name in the iorates.dat file.
Tagname
The tag name listed under the Tagname column is the name of the IORates tag.
Snapshot
The Snapshot column holds the snapshot value of the IORates tag, if the IORates tag
exists in PI. The Snapshot column is updated when the IORates/Status Tags tab is
clicked, and when the interface is first loaded.
Right Mouse Button Menu Options
Create
Create the suggested IORates tag with the tag name indicated in the Tagname column.
Delete
Delete the IORates tag listed in the Tagname column.
Rename
Allows the user to specify a new name for the IORates tag listed in the Tagname column.
Add to File
Adds the tag to the IORates.dat file with the event counter listed in the Event Counter
Column.
Search
Allows the user to search the PI Server for a previously defined IORates tag.
Configuring I/O Rate Tags Manually
There are two configuration steps:
Configuring the PI Point on the PI Server
Create an I/O Rate Tag with the following point attribute values.
Attribute
32
Value
PointSource
L
PointType
float32
Compressing
0
32
Attribute
ExcDev
Value
0
Configuration on the Interface Node
For the following examples, assume that the name of the PI tag is syslog001, and that
the name of the I/O Rate on the home node is sy_io_syslog001.
1. Edit/Create a file called iorates.dat in the PIHOME\dat directory. The
PIHOME directory is defined either by the PIPCSHARE entry or the PIHOME entry in
the pipc.ini file, which is located in the \WinNT directory. If both are specified,
the PIPCSHARE entry takes precedence.
Since the PIHOME directory is typically C:\PIPC, the full name of the
iorates.dat file will typically be C:\PIPC\dat\iorates.dat.
Add a line in the iorates.dat file of the form:
sy_io_syslog001, x
where sy_io_syslog001 is the name of the I/O Rate Tag and x corresponds to the
first instance of the /ec=x flag in the startup command file. X can be any number
between 2 and 34 or between 51 and 200, inclusive. To specify additional rate
counters for additional copies of the interface, create additional I/O Rate tags and
additional entries in the iorates.dat file. The event counter, /ec=x, should be
unique for each copy of the interface.
2. Set the /ec=x flag on the startup command file of the interface to match the event
counter in the iorates.dat file.
The interface must be stopped and restarted in order for the I/O Rate tag to take effect.
I/O Rates will not be written to the tag until 10 minutes after the interface is started.
Syslog Interface to the PI System
33
33
Startup Command File
Command-line arguments can begin with a / or with a -. For example, the /ps=M and –
ps=M command-line arguments are equivalent.
For NT, command file names have a .bat extension. The NT continuation character (^)
allows one to use multiple lines for the startup command. The maximum length of each
line is 1024 characters (1 kilobyte). The number of flags is unlimited, and the maximum
length of each flag is 1024 characters.
The PI-Interface Configuration Utility (PI-ICU) provides a tool specifically for
configuring this interface startup command file.
Configuring the Interface with PI-ICU
Note: PI-ICU requires PI 3.3 or greater.
The PI-Interface Configuration Utility provides a graphical user interface for configuring
PI interfaces. If the interface is configured by the PI-ICU, the batch file of the interface
(PISyslog.bat) will be maintained by the PI-ICU and all configuration changes will be
kept in that file. The procedure below describes the necessary steps for using PI-ICU to
configure the PI-Syslog Interface.
From the PI-ICU menu, select Interface, New, and then Browse to the PISyslog.exe
executable file. Then, enter values for Point Source and Interface ID#. A window such
as the following results:
“Interface name as displayed in the ICU (optional)” will have PI- pre-pended to this
name and it will be the display name in the services menu.
Click on Add.
You should then see a display such as the following:
Syslog Interface to the PI System
35
35
Startup Command File
Note that in this example the Host PI System is localhost, which means that the interface
will be configured to communicate with the local PI Server. However, if you want the
interface to communicate with a remote PI Server, you can do this by selecting
‘Connections…’ item from PI-ICU menu and make it your default server. If you do not
see the remote node in the list of servers, you can add that in.
Once you add the interface to PI-ICU, near the top of the main PI-ICU screen, the
Interface Type should be syslog. If not, use the drop-down box to change the Interface
Type to be syslog.
Click on Apply to enable the PI-ICU to manage this copy of the PI-Syslog Interface.
The next step is to make selections in the interface-specific tab (i.e. “syslog”) that allow
you to enter values for the startup parameters that are particular to the PI-Syslog
Interface.
36
36
Since the PI-Syslog Interface is a UniInt-based interface, in some cases the user will need
to make appropriate selections in the UniInt tab. This tab allows the user to access
UniInt features through the PI-ICU and to make changes to the behavior of the interface.
If you want to set up the interface as a Windows Service, you can do that by using the
Service tab. This tab allows you to configure the interface to run as a service as well as
to start and stop the interface. You can also run the interface interactively from the PIICU. To do that go to menu, select the Interface item and then Start Interactive.
For more detailed Information on how to use the above-mentioned and other PI-ICU tabs
and selections, please refer to the PI-Interface Configuration Utility User Manual. In the
next section we will describe the selections that are available from the syslog tab. After
you have made your selections on the PI-ICU GUI, you will need to press the Apply
button in order for PI-ICU to make these changes to the interface’s startup file.
syslog Interface Tab
Since the startup file of the PI-Syslog Interface is maintained automatically by the PIICU, you should use the syslog tab to configure the startup parameters and not make
changes in the file manually. The following is the description of interface configuration
parameters used in the PI-ICU Control and corresponding manual parameters.
Syslog Interface to the PI System
37
37
Startup Command File
syslog
The PI-Syslog control for PI-ICU has 5 sections. A yellow text box indicates that an
invalid value has been entered, or that a required value has not been entered.
Communication

Port: The Interface listens on one UDP port. This port can be set here. The default
is 514.

Max Queue Length: The maximum number of messages allowed to accumulate in
the internal message queue. The default is 50000.
Time
38

Sub-Second timestamps: Values can be sent to PI with timestamps either
rounded to the nearest second or with sub-second precision.

Unique timestamps: Time will be added to the timestamp so that each message
has a unique timestamp in the PI server. Setting this flag will enable Sub-Second
timestamps.
38
System digital state
The interface is capable of writing a digital state to all points at startup. This is useful to
differentiate times when the interface is stopped to times when no messages are received
from a device.
The dropdown box is used to select a system digital state to send for each tag on startup.
Debug
Debug messages are written to the PIPC.log file with each new message the interface
receives. Use this only when debugging as large log files can result.
Additional Parameters
This box is used to add command line parameters which are not currently supported by
the ICU Control. Parameters should be separated by a space.
Command-line Parameters
Parameter
/port=n
Optional
Default: /port=514
/db
Optional
/sst
Optional
/sds=”State”
Optional, strongly
recommended
/uTimes
Optional
/mxq=n
Optional
Description
The parameter specifies the UDP port number on which the interface
listens for syslog messages from the devices. If not specified, the
default syslog port 514 is used. Of course, this number must match the
one specified as the destination port in the configuration of logging host
for the devices.
If /db is present in the command line, the interface will write
additional debugging messages to the PIPC.log file. Note: Debug
messages about the matching of each syslog message with a PI Point is
enabled through point-level debugging (see ExDesc)
By default the timestamp of values written to PI are rounded to the
nearest second. If /sst is present, values are sent with sub-second
precision.
Write this system digital state to all interface Points at interface startup.
This is very useful because it may be a long time after startup before any
message is detected.
Unique Time Stamps: Each Syslog message is given a unique
timestamp. Messages are time-stamped as they are read from the syslog
port. If the time between messages is less than the time resolution of the
PI server, 1/65536 seconds, then time will be added to the timestamp so
that each message has a unique timestamp in the PI server. Setting this
flag will enable /sst.
Maximum number of messages allowed in the internal queue waiting to
be processed. When this maximum is reached the interface temporarily
stops reading new messages.
Default:
/mxq=50000
Syslog Interface to the PI System
39
39
Startup Command File
Parameter
/ps=x
Required
Description
The /ps flag specifies the point source for the interface. X is not case
sensitive and can be any single character. For example, /ps=S and /ps=s
are equivalent.
The point source that is assigned with the /ps flag corresponds to the
PointSource attribute of individual PI Points. The interface will attempt
to load only those PI points with the appropriate point source.
/id=n
The /id flag is used to specify the interface identifier.
Required
The interface identifier is a string that is no longer than 9 characters in
length. UniInt concatenates this string to the header that is used to
identify error messages as belonging to a particular interface. See the
section called “Error and Informational Messages” for more
information.
UniInt always uses the /id flag in the fashion described above. This
interface also uses the /id flag to identify a particular interface copy
number that corresponds to an integer value that is assigned to
Location1. For this interface, one should use only numeric characters in
the identifier. For example,
/id=1
/host=host:port
Optional
The /host flag is used to specify the PI Home node. Host is the IP
address of the PI Server node or the domain name of the PI Server node.
Port is the port number for TCP/IP communication. The port is always
5450 for a PI 3 Server and 545 for a PI 2 Server. It is recommended to
explicitly define the host and port on the command line with the /host
flag. Nevertheless, if either the host or port is not specified, the interface
will attempt to use defaults.
Defaults:
The default port name and server name is specified in the pilogin.ini or
piclient.ini file. The piclient.ini file is ignored if a pilogin.ini file is
found. Refer to the PI-API Installation Instructions manual for more
information on the piclient.ini and pilogin.ini files.
Examples:
The interface is running on a PI Interface Node, the domain name of the
PI 3 home node is Marvin, and the IP address of Marvin is
206.79.198.30. Valid /host flags would be:
/host=marvin
/host=marvin:5450
/host=206.79.198.30
/host=206.79.198.30:5450
40
40
Parameter
/stopstat
or
/stopstat=
digstate
Default:
/stopstat=
”Intf shut”
Optional
Description
If the /stopstat flag is present on the startup command line, then the
digital state Intf shut will be written to each PI Point when the interface
is stopped.
If /stopstat=digstate is present on the command line, then the
digital state, digstate, will be written to each PI Point when the interface
is stopped. For a PI 3 Server, digstate must be in the system digital state
table. For a PI 2 Server, where there is only one digital state table
available, digstate must simply be somewhere in the table. UniInt uses
the first occurrence in the table.
If neither /stopstat nor /stopstat=digstate is specified on
the command line, then no digital states will be written when the
interface is shut down.
Examples:
/stopstat=”Intf shut”
The entire parameter is enclosed within double quotes when there is a
space in digstate.
/ec=x
Optional
Default: /ec=1
/stsp
Optional
The first instance of the /ec flag on the command line is used to specify
a counter number, x, for an I/O Rate point. If x is not specified, then the
default event counter is 1. Also, if the /ec flag is not specified at all,
there is still a default event counter of 1 associated with the interface. If
there is an I/O Rate point that is associated with an event counter of 1,
each copy of the interface that is running without /ec=x explicitly
defined will write to the same I/O Rate point. This means that one
should either explicitly define an event counter other than 1 for each
copy of the interface or one should not associate any I/O Rate points
with event counter 1. Configuration of I/O Rate points is discussed in
the section called “I/O Rate Tag Configuration.”
The /stsp parameter tells the interface to show all truncated Syslog
packets. If this parameter is omitted, the interface shows only the first 5
truncated Syslog messages for each device.
See Appendix A: Error and Informational Messages for more
information on truncated syslog packets.
Syslog Interface to the PI System
41
41
Startup Command File
Sample PISyslog.bat File
The following is an example file:
rem
rem
rem
rem
rem
rem
rem
rem
rem
rem
rem
rem
rem
rem
rem
rem
rem
rem
rem
rem
Sample startup command file for the PISyslog Interface
Required Parameters
/ps=x
/id=n
Point source character
Interface identifcation number
Recommended Parameters
/host=<hostname>:port#
/ec=n
PI server host name and port #
Event counter for I/O rate tag
Optional Parameters
/port=514
/db
/stsp
/sds=”Scan On”
/stopstat="Intf Shut"
/mxq=n
/uTimes
Port to read
Enable debug messages
Enable logging truncated syslog packets
Write Scan On to tags at startup
Write Intf Shut points when Interface shuts down
Limit to # of messages in internal msg queue
Each Syslog message is given a unique timestamp
Sample startup command line
.\PISyslog.exe /ps=f /id=1 /host=pimachine:5450 /stopstat="Intf Shut" /sds="Scan On" /db
The above command line tells the Interface to:
42

service PI points whose PointSource is f and Location1 is 1,

send values to the PI 3 Server named pimachine,

write Intf Shut to its list of points upon exit,

write Scan On to all points at interface startup,

as default, listen for Syslog messages on UDP port 514,

print the interface debugging messages.
42
Interface Node Clock
The correct settings for the time and time zone should be set in the Date/Time control
panel. If local time participates in Daylight Savings, from the control panel, configure the
time to be automatically adjusted for Daylight Savings Time. The correct local settings
should be used even if the interface node runs in a different time zone than the PI Server
node.
Make sure that the TZ environment variable is not defined. The currently defined
environment variables can be listed by going to Start | Settings | Control Panel, double
clicking on the system icon, and selecting the environment tab on the resulting dialog
box. Also, make sure that the TZ variable is not defined in an autoexec.bat file. When
the TZ variable is defined in an autoexec.bat file, the TZ variable may not appear as
being defined in the System control panel even though the variable is defined.
Admittedly, autoexec.bat files are not typically used on NT, but this does not prevent
a rogue user from creating such a file and defining the TZ variable unbeknownst to the
System Administrator.
Syslog Interface to the PI System
43
43
Security
If the home node is a PI 3 Server, the PI Firewall Database and the PI Proxy Database
must be configured so that the interface is allowed to write data to the PI Server. See
“Modifying the Firewall Database” and “Modifying the Proxy Database” in the PI Server
manuals. Note that the Trust Database, which is maintained by the Base Subsystem,
replaces the Proxy Database used prior to PI version 3.3. The Trust Database maintains
all the functionality of the proxy mechanism while being more secure.
See “Trust Login Security” in the chapter “PI System Management” of the PI Universal
Data Server System Management Guide.
If the interface cannot write data to a PI 3 Server because it has insufficient privileges, a
–10401 error will be reported in the pipc.log file. If the interface cannot send data to a
PI2 Server, it writes a –999 error. See the section “Appendix A: Error and Informational
Messages” for additional information on error messaging.
Syslog Interface to the PI System
45
45
Starting / Stopping the Interface
This section describes starting and stopping the interface once it has been installed as a
service. See the UniInt End User Document to run the interface interactively.
Starting Interface as a Service
If the interface was installed a service, it can be started from PI-ICU, the services control
panel or with the command:
PIsyslog.exe –start
To start the interface service with PI-ICU, use the
button on the PI-ICU toolbar.
A message will be echoed to the screen informing the user whether or not the interface
has been successfully started as a service. Even if the message indicates that the service
started successfully, make sure that the service is still running by checking in the services
control panel. There are several reasons that a service may immediately terminate after
startup. One is that the service may not be able to find the command-line arguments in
the associated .bat file. For this to succeed, the root name of the .bat file and the
.exe file must be the same, and the .bat file and the .exe file must be in the same
directory. If the service terminates prematurely for whatever reason, no error messages
will be echoed to the screen. The user must consult the pipc.log file for error
messages. See the section “Appendix A: Error and Informational Messages,” for
additional information.
Stopping Interface Running as a Service
If the interface was installed a service, it can be stopped at any time from PI-ICU, the
services control panel or with the command:
PIsyslog.exe –stop
The service can be removed by:
PIsyslog.exe –remove
To stop the interface service with PI-ICU, use the
Syslog Interface to the PI System
button on the PI-ICU toolbar.
47
47
Buffering
For complete information on buffering, please refer to the PI API Installation
Instructions.
PI Interface Node buffering consists of a buffering process which runs continuously on
the local node, a PI-API library whose calls can send data to this buffering process, and a
utility program for examining the state of buffering and controlling the buffering process.
Note: Change the Local Security Policy on Windows XP.
1. Open “Administrative Tools” from the control panel.
2. Open “Local Security Policy” from administrative tools.
3. Browse to “Security Options” under “Local Policies.”
4. Double click on “System Objects: Default owner for objects created by members of the
Administrators group.”
5. Change the dropdown from “Object Creator” to “Administrators group.”
The behavior of Bufserv should now be the same on XP as it was for NT4 and 2000.
Configuring Buffering with PI-ICU (NT-Intel)
Buffering is enabled through the PI-Interface Configuration Utility’s Tools>API
Buffering… menu. Unless buffering is explicitly enabled, the PI-API will not buffer data,
sending data directly to the home node.
The API Buffering… dialog allows the user to view and configure the parameters
associated with the API Buffering (bufserv) process. The user can start and stop the API
Buffering process from the Service tab:
Syslog Interface to the PI System
49
49
Buffering
Service Tab
The Service tab allows for some API Buffering service configuration. For further
configuration changes, use the Services applet.
Service Name
The Service name displays the name of the API Buffering Service.
Display Name
The Display name displays the full name associated with the API Buffering service.
Log On As
Log on as indicates the Windows user account under which the API Buffering service is
setup to start automatically on reboot, or manually.
Password
Password is the name of the password for the Windows user account entered in the Log
on as:above.
Confirm password
You must reenter the password again to verify you have typed it correctly both times.
Dependencies
The Dependencies lists the Windows services on which the API Buffering service is
dependent.
Dependent Services
The Dependent services area lists the Windows services that depend on bufserv to
function correctly.
Start / Stop Service
The Start / Stop buttons allow for the API Buffering service to be started and stopped. If
the service is not created this box will show Not Installed.
After a change is made to any of the settings on the Settings tab, the OK button must be
clicked to save these settings, and then the service must be stopped and restarted for the
changes to be picked up by bufserv.
Service Startup Type
The Startup Type indicates whether the API Buffering service is setup to start
automatically on reboot or manually on reboot, or is disabled.

If the Auto option is selected, the service will be installed to start automatically
when the machine reboots.

If the Manual option is selected, the interface service will not start on reboot, but
will require someone to manually start the service.

If the Disabled option is selected, the service will not start at all.
Generally, the API Buffering service is set to start automatically.
50
50
Create/Remove Service
The Create / Remove buttons allow for the creation or removal of the API Buffering
service. Clicking the Create button will cause the service to be created using the Log on
as and passwords given. Once the service is created the Start / Stop buttons will be
activated.
Settings Tab
The Settings tab allows for configuration of the 7 configurable settings used by API
Buffering. Default values are used if no other value is provided.
Enable Buffering
Enables the API Buffering feature.
Maximum File Size
Maximum buffer file size in kilobytes before buffering fails and discards events. Default
value is 100,000. Range is 1 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value,
click the Apply button.
Send Rate
Send rate is the time to wait between sending up to MAXTRANSFEROBJS to the server
(milliseconds). Default value is 100. Range is 0 to 2,000,000.
Syslog Interface to the PI System
51
51
Buffering
The Use Default button places the default value into the text box. To keep this value,
click the Apply button.
Primary Memory Buffer Size
Primary memory buffer size is the size in bytes of the Primary memory buffer. Default
value is 32768. Range is 64 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value,
click the Apply button.
Secondary Memory Buffer Size
Secondary memory buffer size is the size in bytes of the Secondary memory buffer.
Default value is 32768. Range is 64 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value,
click the Apply button.
Max Transfer Objects
Max transfer objects is the maximum number of events to send between each
SENDRATE pause. Default value is 500. Range is 1 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value,
click the Apply button.
Pause Rate
When buffers are empty the buffering process will wait for this number of seconds
before attempting to send more data to the home node. Default value is 2. Range is 0 to
2,000,000.
The Use Default button places the default value into the text box. To keep this value,
click the Apply button.
Retry Rate
When the buffering process discovers the home node is unavailable it will wait this
number of seconds before attempting to reconnect. Default value is 120. Range is 0 to
2,000,000.
The Use Default button places the default value into the text box. To keep this value,
click the Apply button.
Max Theoretical Send Rate
This is the theoretical max send rate which is calculated like this:
max = MAXTRANSFEROBJS / SENDRATE * 1000
Default value is 5000. This value is automatically calculated for the user and can not be
changed.
There are no additional steps needed to install buffering after installing the PI-API. The
delivered PI-API library supports both buffered and un-buffered calls.
52
52
Configuring Buffering Manually
Buffering is enabled through the use of a configuration file, piclient.ini. Unless this
file is modified to explicitly enable buffering, the PI-API will not buffer data, sending
data directly to the home node.
There are no additional steps needed to install buffering after installing the PI-API. The
delivered PI-API library supports both buffered and un-buffered calls.
Note: When buffering is configured to be on, the bufserv process must be started
before other programs using the PI-API, so that these programs can access the shared
buffering resources. Any program that makes a connection to a PI Server has this
requirement even if it does not write to PI.
Configuration of buffering is achieved through entries in the piclient.ini file. The
file is found in the dat subdirectory of the PIHOME directory (typically c:\pipc\dat)
under Windows NT. This file follows the conventions of Microsoft Windows
initialization files with sections, keywords within sections and values for keywords. All
buffering settings are entered in a section called [APIBUFFER]. To modify settings,
simply edit the piclient.ini file in a text editor (Notepad on Windows) to the
desired values.
The following settings are available for buffering configuration:
Keywords
Values
Default
Description
BUFFERING
0,1
0
Turn off/on buffering. OFF = 0, ON = 1,
PAUSERATE
0 – 2,000,000
2
When buffers are empty the buffering process
will wait for this long before attempting to
send more data to the home node (seconds)
RETRYRATE
0 – 2,000,000
120
When the buffering process discovers the
home node is unavailable it will wait this long
before attempting to reconnect (seconds)
MAXFILESIZE
1 – 2,000,000
100,000
Maximum buffer file size before buffering
fails and discards events. (Kbytes)
MAXTRANSFEROBJS
1 – 2,000,000
500
Maximum number of events to send between
each SENDRATE pause.
BUF1SIZE
64 – 2,000,000
32768
Primary memory buffer size. (bytes)
BUF2SIZE
64 – 2,000,000
32768
Secondary memory buffer size. (bytes)
SENDRATE
0 – 2,000,000
100
The time to wait between sending up to
MAXTRANSFEROBJS to the server
(milliseconds)
In addition to the [APIBUFFER] section, the [PISERVER] section may be used to
define the default PI server and an optional time offset change that may occur between
the client and server.
Keywords
PIHOMENODE
Syslog Interface to the PI System
Values
String
Default
none
Description
Windows default server is in pilogin.ini
53
53
Buffering
Keywords
DSTMISMATCH
Values
0 – 2,000,000
Default
0
Description
The time that the server and client local time
offset is allowed to jump. Typically, 3600 if
the nodes are in time zones whose DST rules
differ (seconds)
Example piclient.ini File
On Windows NT the default server information is stored in the pilogin.ini file so the
piclient.ini would only have the [APIBUFFER] section. The BUFFERING=1
indicates that buffering is on. The MAXFILESIZE entry in Kbytes of 100000 allows up to
100 Megabytes of data storage. Do not use commas or other separators in the numeric
entries. The retry rate is set to 600 seconds meaning wait 10 minutes after losing a
connection before retrying.
On NT a piclient.ini file might look like:
[APIBUFFER]
BUFFERING=1
MAXFILESIZE=100000
; The PI-API connection routines have a 1 minute default timeout.
RETRYRATE=600
54
54
Appendix A:
Error and Informational Messages
A string PI-Syslog ID is pre-pended to error messages written to the message log. ID
is the interface instance number and is the value given by the /id flag on the startup
command line.
Message Logs
Messages are written to PIHOME\dat\pipc.log at the following times. PIHOME is
specified in the pipc.ini file in the system directory.

When the interface starts many informational messages are written to the log. These
include the version of the interface, the version of UniInt, the command-line
parameters used and the number of points.

As the interface loads points, messages are sent to the log if there are problems with
the configuration of any points.

If /db is used on the command line, then various additional informational messages
are written to the log file both during interface startup and during normal operation.

If /db is part of a tags ExDesc then additional messages are written to the log when
this tag is processed
Messages
Interface Startup Errors
If the interface immediately exits upon startup, the most likely cause is that required
command line parameters are not specified. PI-Syslog requires both of the following
command line parameters:
/ps= (point source character)
/id= (interface identifaction number)
If you omit either of these parameters, the interface exits.
There are other reasons for the interface exiting upon startup. For example, the
following messages may be found in the log file:

Interface id (-2) must be a positive integer

Port number (-514) must be a positive integer
Point Loading Errors
A PI point may be refused by the interface if it has some attributes that are not supported
or are mutually exclusive, messages will be of the form
Tag test_tag(1201) refused: Description
The point will be unloaded from the interface and the digital state Configure will be
written to the point.
Syslog Interface to the PI System
55
55
Appendix A: Error and Informational Messages
For example:

Tag test_tag(1201) refused: incorrect Facility specification.
If a PI point is defined to store the syslog message with some specific facility
numbers, the ExDesc attribute of this point must specify the Facility filter. The
Facility filter can specify a single number and/or a range of values. But if the range
is something like “8-4”, the error message will be printed because the lower bound of
the range is greater than the upper bound i.e. the range must be like “4-8”.

Tag test_tag(1201) refused: incorrect Severity specification.
Similarly as the previous message, the range specification for Severity must have a
format such as “3-5” instead of “5-3”.

Tag test_tag(1201) refused: Facility specification out of range
(must be in [0, 23])
Point Debugging Messages
Any PI point can be configured so that some additional debugging messages can be
printed for this individual point via the Extended Descriptor switch /db. Examples of the
debugging messages are:

Tag test_tag(1201) refused: -id(1)/Location1(2) mismatch

Tag test_tag(1201) has point-level debugging set

Tag test_tag has Location2=1, Location3=0 and Location5=1

Tag test_tag has ExDesc as: Facility=10, Severity=4, Host=any;
Device=any; Level=any; FacilityName=PIX;

Writing to tag test_tag From:127.0.0.1 Message: <84>KLOG: %CDP-4DUPLEXMISMATCH:Full/half duplex mismatch d
(This message will be truncated after 80 characters)
Run-time Error
There are occasions when the interface is not capable of processing messages as fast as
they come in. In such a case, the interface can eat up memory until the interface crashes.
No customer has reported this problem, but the interface was tested with the following:
2K messages/minute for a total of 20 points to record those messages, on a machine w/
128 MB memory, crashed the interface after 5 hours.
A message will now get printed if the queue grows beyond 1000 messages.
Interface-level Debugging
The interface can be set to write to the log additional informational messages at startup.
This is done by setting the /db flag in the interface command line file. In addition to
information written during the startup phase, the interface writes to the log each time it
processes its internal queue of syslog messages. Examples of the debugging messages
are:

56
PI-Syslog 1> Processing syslog message queue 1 of 8.
Device:127.0.0.1 Message: <84> Jan 1 03:02:25 named[29356]: [ID
295310 daemon.warning] owner name gc._msdcs.wiredigital.com IN
secondary) is invalid – proceeding anyway
56

PI-Syslog 1> Message 1 no match for Tag syslogtest

PI-Syslog 1> Message 1 no match for Tag syslogtest1

PI-Syslog 1> Message 1 match found for Tag syslogtest2

PI-Syslog 1> Message 1 match found for Tag syslogtest3
Syslog Error Message
Syslog packet should not exceed 1024 bytes. Therefore, if a packet longer than 1024
bytes is received, the interface truncates the message and prints a warning message and
the received message.
For example, if the message log file contains entries such as:
PI-Syslog 1> Syslog warning: The packet from 122.128.8.22 exceeds
the limit of 1024 bytes:
PI-Syslog 1> <80>Oct 10
This is a long message!
message! This is a long
long message! This is a
is a long message! This
This is a long message!
message! This is a long
long message! This is a
is a long message! This
This is a long message!
message! This is a long
long message! This is a
is a long message! This
This is a long message!
message! This is a long
long message
2003 18:18:18 Test Machine: %PIX-4-166666:
This is a long message! This is a long
message! This is a long message! This is a
long message! This is a long message! This
is a long message! This is a long message!
This is a long message! This is a long
message! This is a long message! This is a
long message! This is a long message! This
is a long message! This is a long message!
This is a long message! This is a long
message! This is a long message! This is a
long message! This is a long message! This
is a long message! This is a long message!
This is a long message! This is a long
message! This is a long message! This is a
PI-Syslog 1> Truncated to 1024 bytes
it means that the interface receives a packet longer than 1024 bytes from device
122.128.8.22 and the packet is truncated to fit the 1024 bytes limit.
PI-Syslog prints only the first 5 truncated syslog packets that it receives from one device.
If you want the interface to print all truncated messages, use the /stsp (“show truncated
syslog packet”) command-line parameter.
System Errors and PI Errors
System errors are associated with positive error numbers. Errors related to PI are
associated with negative error numbers.
On NT, descriptions of system and PI errors can be obtained with the pidiag utility:
\PI\adm\pidiag –e error_number
Syslog Interface to the PI System
57
57
APPENDIX B:
PI-PIX Firewall Interface Compatibility
This interface is designed to replace the PI-PIX firewall interface with little or no
modifications to existing configuration.
Migration
To replace an installation of the PI PIX interface with the PI Syslog interface the
following procedure should be followed.
Manual Migration
1. Install the PI Syslog interface using the install kit provided.
2. Locate the directory the PI PIX interface is installed (typically
PIPC\interfaces\Cisco PIX).
3. Identify and open with notepad the PI PIX interface startup file (typically pipix.bat)
4. Identify and open the example startup file for the PI Syslog interface (Typically
PIPC\interfaces\Syslog\PISyslog.bat.new).
5. Copy the startup command line from the PIX startup file to the Syslog startup file,
overwriting the Syslog startup file command line. The exception, however, is that the
first command parameter should remain the name and path of the syslog executable
rather than the name and path of the PI PIX interface executable.
6. Add the following two command line switches /sds=“Scan On” /sst (see the
Compatibility section below).
7. Save the PI Syslog startup file as PISyslog.bat.
8. From the services applet in control panel, stop the PI PIX interface service.
9. Start the PI Syslog Interface service.
10. Edit the PI PIX interface service to “Manual” startup.
11. Confirm the Syslog interface is operating correctly.
12. Optionally, uninstall the PI PIX interface.
Migration Using the PI ICU
If the PI PIX interface has been configured using the PI ICU the above procedure can be
performed also using the PI ICU.
1. Install the PI Syslog interface using the install kit provided.
Syslog Interface to the PI System
59
59
Appendix B: PI-PIX Firewall Interface Compatibility
2. Open the PI ICU and select the PI PIX interface from the “Interface” drop down text
box
3. Take note of the following settings
a. General Tab
i. Point Source
ii. Interface ID #
iii. Host
b. Uniint
i. Maximum stop time
ii. SDK timeout
iii. Initial SDK connection timeout
c. CiscoPixFire
i. Port
d. Service
i. Startup Type
ii. Log on as
iii. Dependencies
e. I\O Rates
i. Enable I\O Rates
ii. Tag Status (If “not created” you can ignore the I\O Rates
configuration)
iii. Event Counter
iv. TagName
4. Create a new interface (Ctrl+N)
60
60
5. Browse to the Syslog executable
6. Add the Point Source and Interface ID #(from above Step 3)
7. Copy the values from above to each ICU Tab in the following order
a. General
b. Uniint
c. Syslog – in addition to the Port value copied from the PIX Tab; the System
Digital State and the Time settings need to be configured as shown (see
compatibility section).
Syslog Interface to the PI System
61
61
Appendix B: PI-PIX Firewall Interface Compatibility
d. I\O Rates
e. Service
8. At the Service Tab confirm the service is installed, do not start the service until the
PI PIX interface service is stopped.
9. Start the Syslog interface and review the data.
10. Optionally, uninstall the PI PIX interface.
Compatibility
The PI PIX Interface would, by default, write Scan On to all points at interface startup,
The PI syslog interface requires the command-line parameter /sds=“Scan On” to
maintain this functionality.
The PI PIX Firewall Interface timestamped data with a sub-second component. The PI
syslog interface requires the command line parameter /sst to enable the sub-second
portion of the time to be sent to PI. It is not recommended to store times with the subsecond precision.
Count, Rate and User Points
The PIX Firewall Interface used Location2 to indicate User, Count and Rate points. To
these points the interface would apply filters like Host as if the syslog message was from
a PIX device.
Severity and Facility filters would, however, work for any syslog message. PI points
configured with these location codes will still work with this interface, however, it is not
recommended that Location2 = 1, 2 or 3 be used for new points. The current behavior
of the Location2 = 1, 2 or 3 is similar to compatible Location3 values with “General”
category points.
Type
Location2
1
User
Description
This type of point can be used to record syslog messages in
any format.
The specific information interesting to a user is extracted out
of the log messages and is written to a PI tag. A regular
expression (RegExp) matching pattern and substitution pattern
specified in ExDesc is used to search through the log messages
and select the data.
Equivalent to:
Location2=5
Location3=7
2
Count
(provided for
backward
compatibility
with the PIX
Firewall
Interface)
62
The number of the syslog messages satisfying the filtering
criteria specified by ExDesc is counted over a user-defined
interval and is stored as the point value into the PI server.
Equivalent to:
Location2=5
Location3=5
62
Type
Location2
3
Rate
(provided for
backward
compatibility
with the PIX
Firewall
Interface)
Syslog Interface to the PI System
Description
The rate of the syslog messages satisfying the filtering criteria
specified by ExDesc is calculated over a user-defined interval
and is stored to a PI point.
Equivalent to:
Location2=5
Location3=6
63
63
Appendix C:
Extract from RFC3164 – 4.1.1 PRI
The PRI part MUST have three, four or five characters and will be bound with angle
brackets as the first and last characters. The PRI part starts with a leading “<” (‘lessthan’ character) followed by a number, which is then followed by a “>” (‘greater-than’
character). The code set used in this part MUST be seven-bit ASCII in an eight-bit field
as described in RFC 2234 [2]. These are the ASCII codes as defined in “USA Standard
Code for Information Interchange” [3]. In this, the “<” character is defined as the
Augmented Backus-Naur Form (ABNF) %d60, and the “>” character has ABNF value
%d62. The number contained within these angle brackets is known as the Priority value
and represents both the Facility and Severity as described below. The Priority value
consists of one, two, or three decimal integers (ABNF DIGITS) using values of %d48
(for “0”) through %d57 (for “9”).
The Facilities and Severities of the messages are numerically coded with decimal values.
Some of the operating system daemons and processes have been assigned Facility values.
Processes and daemons that have not been explicitly assigned a Facility may use any of
the “local use” facilities or they may use the “user-level” Facility. Those Facilities that
have been designated are shown in the following table along with their numerical code
values.
Numerical Code
Facility
0
Kernel messages
1
User-level messages
2
Mail system
3
System daemons
4
Security/authorization messages*
5
Messages generated internally by syslogd
6
Line printer subsystem
7
Network news subsystem
8
UUCP subsystem
9
Clock daemon**
10
Security/authorization messages*
11
FTP daemon
12
NTP subsystem
13
Log audit*
14
Log alert*
15
Clock daemon**
16
Local use 0 (local0)
17
Local use 1 (local1)
18
Local use 2 (local2)
Syslog Interface to the PI System
65
65
Appendix C: Extract from RFC3164 – 4.1.1 PRI
Numerical Code
Facility
19
Local use 3 (local3)
20
Local use 4 (local4)
21
Local use 5 (local5)
22
Local use 6 (local6)
23
Local use 7 (local7)

Various operating systems have been found to utilize Facilities 4, 10, 13 and 14 for
security/authorization, audit and alert messages which seem to be similar.
** Various operating systems have been found to utilize both Facilities 9 and 15 for
clock (cron/at) messages.
There are also different degrees of importance attached to the syslog packets. A device
can be set to send messages at different Severities:
Numerical Code
66
Severity
Description
0
Emergency
System unusable
1
Alert
Immediate action needed
2
Critical
Critical condition
3
Error
Error condition
4
Warning
Warning condition
5
Notice
Normal but significant condition
6
Informational
Informational message
7
Debug
Debug-level messages
66
Revision History
Date
Author
Comments
03-Jun-03
DC
Initial draft using Skeleton version 1.12
31-Mar-04
MD
Initial release of Syslog Interface manual
02-Apr-04
MD
Included Syslog ICU Control
29-Apr-04
MD
Modified Appendix2 Migration Procedure
12-May-04
CG
1.0.0.0 Rev B: changed pi_syslog to pisyslog; added
periods; formatted tables; fixed sections, headers &
footers, and page numbers; removed editing marks.
28-May-04
CG
1.0.0.1 Rev A: increased version; added
troubleshooting note regarding potentially
overflowing the queue
24-Jun-04
MD
1.0.0.3 Modified Principals of Operations to include
internal queue; added 3 new performance counters;
added /mxq
22-Jul-04
CG
1.0.0.3 Rev B: Added screenshot of new ICU control
with /mxq and added its description; reworded
information about the internal queue and the new
performance counters; updated sample bat file;
renamed performance counter to Syslog Message
Queue length.
11-Oct-04
MD
1.0.0.5: Added note that now /sn and /q are not used;
modified example startup file and removed /q from
startup parameter table
20-Oct-04
CG
1.0.0.5 Rev B: Fixed a heading style in principles;
fixed comptxtinline in parameters table; note about
/sn and /q no longer refers to a specific version of the
interface.
26-Oct-04
MD
1.0.0.5 Rev C: Replaced example bat to match bat
file distributed with the interface
26-Oct-04
MPK
1.0.0.5 Rev C: Replaced section on Configuring
Buffering with PI-ICU with updated information,
added APS availability to the supported features
chart, replaced screen shot of ICU control showing
current version, fixed interface installation directory.
Make document final.
5-May-05
MD
1.0.0.6 Added uTimes to the command line
parameters. Added warning about point level
debugging and large log files added uTimes to ICU
image and section
26-May-05
MPK
Fixed TOC. Changed screenshot of ICU to show
current ICU screen for PI-ICU 1.4.0.0.
Syslog Interface to the PI System
67
67