2013 Quest Software, Inc. ALL RIGHTS RESERVED.

Transcription

1 2.3 User Guide

2 2013 Quest Software, Inc. ALL RIGHTS RESERVED. This guide contains proprietary information protected by copyright. The software described in this guide is furnished under a software license or nondisclosure agreement. This software may be used or copied only in accordance with the terms of the applicable agreement. No part of this guide may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording for any purpose other than the purchaser s personal use without the written permission of Quest Software, Inc. The information in this document is provided in connection with Quest products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Quest products. EXCEPT AS SET FORTH IN QUEST'S TERMS AND CONDITIONS AS SPECIFIED IN THE LICENSE AGREEMENT FOR THIS PRODUCT, QUEST ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL QUEST BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, BUSINESS INTERRUPTION OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF QUEST HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Quest makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and product descriptions at any time without notice. Quest does not make any commitment to update the information contained in this document. If you have any questions regarding your potential use of this material, contact: Quest Software World Headquarters LEGAL Dept 5 Polaris Way Aliso Viejo, CA [email protected] Refer to our Web site ( for regional and international office information. Patents Protected by U.S. Patent # 7,979,494 and 8,185,598. Additional patents pending. TRADEMARKS Quest, Quest Software, the Quest Software logo, Simplicity at Work are trademarks and registered trademarks of Quest Software, Inc. For a complete list of Quest Software's trademarks, please see Other trademarks and registered trademarks are property of their respective owners. InTrust for Syslog Version 2.3 Last updated February 21, 2013

3 Contents About This Guide... 4 Overview... 4 Conventions... 4 Introduction... 5 Why InTrust for Syslog?... 5 How It Works... 6 Working with InTrust for Syslog... 8 Installation Requirements... 8 Setting Up the Windows Part... 9 Initial Configuration of InTrust for Syslog... 9 Preparing Syslog Reconfiguring Solaris Syslog Reconfiguring Cisco Syslog Using InTrust for Syslog Manager Starting Quest InTrust for Syslog Manager Connecting to Another Computer Configuring the Quest InTrust for Syslog Service Setting Up the Quest InTrust for Syslog Service Properties Working with Chains Using the Syslog Knowledge Pack for InTrust Gathering Syslog Audit Data with InTrust Manager Viewing the Report in Quest Knowledge Portal Customizing Parsers Understanding Parsers Parser Programming Overview Generic Syslog Parser Appendix A: InTrust for Syslog Service Events Appendix B Appendix B-a: Message Facility Appendix B-b: Message Priority Appendix B-c: Message Logging Keywords and Levels (Cisco Routers) About Quest Software, Inc Contacting Quest Software Contacting Quest Support Third Party Contributions

4 About This Guide Overview This document explains how the Quest InTrust framework incorporates InTrust for Syslog and how to organize Syslog auditing and reporting. It is intended for InTrust administrators who work with Syslog audit data. Conventions In order to help you get the most out of this guide, we have used specific formatting conventions. These conventions apply to procedures, icons, keystrokes and crossreferences. ELEMENT Select Bolded text Italic text Bold Italic text Blue text CONVENTION This word refers to actions such as choosing or highlighting various interface elements, such as files and radio buttons. Interface elements that appear in Quest products, such as menus and commands. Used for comments. Introduces a series of procedures. Indicates a cross-reference. When viewed in Adobe Acrobat, this format can be used as a hyperlink. Used to highlight additional information pertinent to the process being described. Used to provide Best Practice information. A best practice details the recommended course of action for the best result. Used to highlight processes that should be performed with care. + A plus sign between two keystrokes means that you must press them at the same time. A pipe sign between elements means that you must select the elements in that particular sequence. 4

5 Introduction Why InTrust for Syslog? How It Works Why InTrust for Syslog? In a heterogeneous environment where InTrust is deployed, auditing and real-time monitoring capabilities are provided for Syslog. This is ensured by installing InTrust agents on audited computers. However, it is not always possible to install an agent on a Syslogenabled host or device for the following reasons: The agent package is not available for the platform. The platform is supported, but installation of the agent on the host is not approved. For example, there are no agent packages for Cisco routers, which use Syslog for auditing. On the other hand, the environment may have Solaris hosts running businesscritical services, and policies may prohibit installation of software such as the InTrust agent on those hosts. In these situations, two courses of action are possible: 1. Redirect Syslog messages from an agentless system to a Syslog-enabled host that has an InTrust agent. 2. Capture Syslog messages with the InTrust for Syslog solution. Regular redirection of messages among hosts is a proven method that requires only configuration changes. Using InTrust for Syslog also involves message redirection, but the target is not a true Syslog daemon. The InTrust for Syslog service is at the receiving end, running on a Windows computer and acting as a Syslog proxy. Incoming messages are converted to Windows events. The following table helps compare the two methods: METHOD PROS CONS Regular redirection of messages Production-proven Does not require additional software or hardware Uses message parsing, which brings additional load on the InTrust agent 5

6 METHOD PROS CONS InTrust for Syslog Better method for InTrust auditing and real-time monitoring Provides the advantages of event logs Requires a dedicated Windows computer for best results. How It Works The InTrust for Syslog Service receives Syslog messages forwarded to it, converts them to Windows events and writes them to the InTrust for Syslog event log locally. The resulting log can be processed by InTrust similarly to any other Windows event log: you can gather InTrust for Syslog events, monitor them in real time and make reports on them. The InTrust for Syslog solution is made up of two components: 1. InTrust for Syslog Service This service accepts forwarded Syslog messages, runs them through parsers and writes the result into the InTrust for Syslog event log. 2. InTrust for Syslog Manager This is an MMC snap-in that controls InTrust for Syslog activity. For best performance, install the InTrust for Syslog Service on a dedicated Windows computer. Deploy an InTrust agent on this computer to enable audit data gathering and real-time monitoring. For gathering, an agent is not a requirement InTrust also supports collections of audit data from Windows computers without agents. However, using agents is the recommended method with additional benefits, and agentless gathering will not be considered in this document. For real-time monitoring, agents are required. The InTrust for Syslog Manager snap-in can be installed on any Windows computer that can connect to the InTrust for Syslog Service. Installing it alongside the InTrust Manager snap-in helps control both InTrust for Syslog operation and the processing of InTrust for Syslog events. The following figure shows how InTrust for Syslog components fit into the InTrust framework: 6

7 7

8 Working with InTrust for Syslog Installation Requirements Setting Up the Windows Part Preparing Syslog Using InTrust for Syslog Manager Using the Syslog Knowledge Pack for InTrust Installation Requirements InTrust for Syslog Service PLATFORM OPERATING SYSTEM MEMORY HARD DISK SPACE Intel x86, EM64T Any of the following: Microsoft Windows NT 4.0 Service Pack 6 or higher Microsoft Windows 2000 Microsoft Windows XP Microsoft Windows Server 2003 Microsoft Windows Vista Microsoft Windows Server 2008 Microsoft Windows Server 2008 R2 Microsoft Windows 7 Min. 64Mbytes (128Mbytes recommended) Min. 4 Mbytes Quest InTrust for Syslog Manager PLATFORM OPERATING SYSTEM Intel x86, EM64T Any of the following: Microsoft Windows 2000 Microsoft Windows XP Microsoft Windows Server 2003 Microsoft Windows Vista Microsoft Windows Server 2008 Microsoft Windows Server 2008 R2 Microsoft Windows 7 8

9 MEMORY HARD DISK SPACE Min. 64Mbytes (128 Mbytes recommended) Min. 2 Mbytes InTrust for Syslog setup requires Windows Installer 2.0. Earlier versions of Windows Installer are automatically upgraded during installation, so you may have to reboot your computer after the installation is finished. Setting Up the Windows Part Installing the InTrust for Syslog Service and the InTrust for Syslog Manager console is the first step in InTrust for Syslog deployment. This is followed by configuring your Syslogenabled systems to forward messages to InTrust for Syslog. Run the installation program and select the component you want to install: InTrust for Syslog Service, InTrust for Syslog Manager, or both. To upgrade InTrust for Syslog, simply launch the installation program. If you are upgrading from EventAdmin Syslog Proxy 1.0 and install only InTrust for Syslog Manager, all your EventAdmin Syslog Proxy Service settings and parser chains will be lost. To avoid this, upgrade the EventAdmin Syslog Proxy Service as well. Initial Configuration of InTrust for Syslog After you have installed InTrust for Syslog Manager, start it by clicking Start Programs Quest Software InTrust for Syslog. When the program starts, it first checks if the InTrust for Syslog Service is installed locally. If not, connect to the computer where the service is installed by right-clicking the Quest InTrust for Syslog node in the left pane and selecting Connect to another computer. If use InTrust for Syslog Manager to connect to a remote InTrust for Syslog Service, and save the MMC settings, the next time you run InTrust for Syslog Manager it tries to reestablish the connection. This may take some time, especially if the connection attempts fail (for example, the remote computer is offline). Setting Up the Working Account The InTrust for Syslog Service runs under the LOCAL SYSTEM account by default. In most cases, this is optimal. However, if you want to use a different account for the service, you can change it in InTrust for Syslog Manager. To change the working account 1. In InTrust for Syslog Manager, connect to the InTrust for Syslog Service. 2. Right-click the Quest InTrust for Syslog node in the left pane and select Configure Service. 3. In the dialog box that opens, click Modify. 9

10 For the account changes to take effect, restart the service using the Stop and Start buttons. Troubleshooting DCOM Security If you have problems connecting to the InTrust for Syslog Service, check your DCOM application permissions with the dcomcnfg utility. DCOM application permissions must always be configured for remote connections to the InTrust for Syslog Service. Changing permissions requires stopping Quest InTrust for Syslog Service and closing all Quest InTrust for Syslog consoles. Permissions Required for the User Account DCOM APPLICATION LAUNCH PERMISSION ACCESS PERMISSION WHERE TO SET Quest Unsecured Apartment Windows 2000: Allow launch Windows Server 2003, 2008, or Windows XP: Allow local launch No configuration necessary Computer with InTrust for Syslog Manager Quest InTrust for Syslog Configuration Windows 2000: Allow launch Windows Server 2003, 2008, or Windows XP: Allow local launch Windows 2000: Allow access Windows Server 2003, 2008, or Windows XP: Allow local access Computer with InTrust for Syslog Service Aelita ICC Library No configuration necessary Windows 2000: Allow access Windows Server 2003, 2008, or Windows XP: Allow local access Computer with InTrust for Syslog Service To configure DCOM application properties 1. Run dcomcnfg.exe: In Windows Server 2003, 2008, or Windows XP, the Component Services snap-in opens. Select the Component Services Computers My Computer DCOM Config node. In Windows 2000, the Distributed COM Configuration Properties dialog box opens. 2. Select the DCOM application you need and open its properties. 3. On the Security tab, configure launch and access permissions as required. To edit permissions, select Use custom access permissions (in Windows 2000) or Customize (in Windows Server 2003, 2008, or Windows XP) and click Edit. For details about how to manage InTrust for Syslog, see the Using InTrust for Syslog Manager section further in this document. 10

11 Preparing Syslog To make your Syslog-enabled hosts redirect messages to InTrust for Syslog, edit their local Syslog configuration files. The procedure varies from platform to platform, but this section describes two common scenarios: Reconfiguring Solaris Syslog Reconfiguring Cisco Syslog You should have no difficulty adapting them to your particular Syslog-enabled systems. Reconfiguring Solaris Syslog By default, Solaris servers log all messages locally. To specify a different location for syslog messages to be sent to, edit the syslog.conf file found in the /etc directory. The following is an example of a syslog.conf file: ################################################ # Syslog configuration file. # *.err;kern.notice;auth.notice /dev/console *.err;kern.debug;daemon.notice;mail.crit /var/adm/messages *.alert;kern.err;daemon.err operator *.alert root ################################################ In line 5 of the example all errors, kernel debug, all daemon notices and critical mail server information are written to the messages file in /var/adm/. To specify a different location for the syslog messages, replace /var/adm/messages Here is an example: - OR - To specify the types of messages to be sent to the remote host, tell the server what facility (Appendix B-a) to log and the priority of the message to log (Appendix B-b). The previous example will log to remote the following: All error messages from any facility (*.err) All Kernel debug messages (kern.debug) and anything more severe than debug, which is everything Daemon notices and anything more severe than notice (daemon.notice) Critical mail server messages (mail.crit), which also encompass ALERT and EMERG You can also specify to log just the critical mail messages by typing mail.=crit. 11

12 As a security measure, avoid sending AUTHPRIV information to a remote host. You can disable this by specifying authpriv.none in the syslog.conf file as follows: After modifying the syslog.conf file, you should have the syslogd daemon re-read the configuration, by supplying the following command: kill -HUP `cat /etc/syslog.pid` Only root can perform this command. Backquotes must be used. If the changes didn t take effect, reboot the host. Reconfiguring Cisco Syslog 1. Telnet to the router or connect via the console and enter enable mode. 2. Enter the following commands from the enable prompt on the router: config t[erminal] logging on logging Facility Local7 Or any other facility that syslogd is listening to. Some versions of Cisco IOS require the following command to produce the same results: logging Facility Local20. Local7 is the default. logging trap [Level0 Level7] Level 7 will log all events including debug. It is recommended that you use level 6 or lower. logging [IP Address or Hostname running InTrust for Syslog Service] The logging level will determine what types of events are logged by InTrust for Syslog. This is similar to the UNIX Syslog, but numbers are used instead of keywords. For example, if you specify Logging trap 3, all errors, critical, alerts and emergencies will be logged. Cisco Catalyst switches use the same method to enable logging but each line is preceded by the SET command. Cisco concentrators have a web interface to configure and enable remote logging. Using InTrust for Syslog Manager Starting Quest InTrust for Syslog Manager Connecting to Another Computer Configuring the Quest InTrust for Syslog Service Setting Up the Quest InTrust for Syslog Service Properties Working with Chains 12

13 Starting Quest InTrust for Syslog Manager To start Quest InTrust for Syslog manager, click Start Quest Software InTrust for Syslog. The main window will appear. If you do not have the Quest InTrust for Syslog service running locally on the computer where you start the manager, you should either install and start the service on your current computer or connect to another machine running this service. For more information, refer to the related topics. Connecting to Another Computer To connect to another computer, right-click the Quest InTrust for Syslog node, and select Connect to another computer. 13

14 The Select Computer dialog box is displayed. Select the computer you want to connect to, and click OK when ready. Connecting to the Quest InTrust for Syslog service on the remote computers requires administrative rights. Configuring the Quest InTrust for Syslog Service You can configure the Quest InTrust for Syslog Service by launching Services from the Control Panel. 14

15 It is better, however, to access the service configuration directly from Quest InTrust for Syslog Manager. For that, right-click the Quest InTrust for Syslog node, and select Configure Service. The Configure Service dialog box is displayed. In this dialog box, only the essential configuration options for the Quest InTrust for Syslog Service are available, rather than all the configuration options Windows Service Properties dialog box. The Reload Configuration button is added to the standard options. It lets you apply the changes immediately. You can: Start, Stop, Pause or Resume the execution of the service. Use the Modify button to specify the user account to run the service. 15

16 Connecting to the Quest InTrust for Syslog Service on remote computers requires administrative rights. By default, the Quest InTrust for Syslog Service runs under the LocalSystem account. If you want to change this, launch the Configure Service dialog box, click Modify, and enter the new user name and password. The supplied account is immediately validated. If validation fails, you are prompted for credentials again. For the account changes to take effect, restart the service using the Stop and Start buttons. Setting Up the Quest InTrust for Syslog Service Properties To access the Quest InTrust for Syslog Service properties: Select the desired snap-in in the left pane of the console window. Click on the toolbar. You can also right-click the selected snap-in to bring up the shortcut menu and select Properties. In the Port # field you can specify the number of the port that the Quest InTrust for Syslog Service will listen to. By default, UDP port 514 is used. The Maximum buffer size option lets you specify the size of the buffer in which to keep the incoming Syslog messages. You also have to specify what should be done when the maximum buffer size is reached. Select the Overwrite as needed option to overwrite messages when the buffer is full. Select the Drop messages option to discard the incoming messages which do not fit into the buffer. 16

17 Working with Chains Chains help you quickly process Syslog messages by filtering out irrelevant addresses and organizing parser hierarchy. In other words, a chain determines which parsers to apply on which sources. Creating a New Chain To create a new chain, right-click the Quest InTrust for Syslog node and select New Chain. A new chain is created with the default name. Renaming a Chain You can rename a chain, if necessary. Select the chain you want to rename. Press the F2 key Enter the new name. You can also right-click the selected chain and select Rename. Duplicate names are not allowed. If a duplicate name is supplied, you will be prompted accordingly. It is a good idea to supply meaningful names and useful descriptions for your chains. Deleting a Chain Select the chain you want to delete. Press the DELETE key or click on the toolbar. You can also right-click the selected chain and select Delete. 17

18 Copying a Chain Select the chain you want to copy. Copy the chain to the clipboard. Paste the chain where you want. Using the Cut menu command instead of Copy allows you to remove the chain from the selected snap-in and place it to the Clipboard. Setting Up Chain Properties To access the properties of a chain, right-click the chain and select Properties. The properties dialog box opens; this dialog box has two tabs: General The General tab lets you supply a descriptive name for your chain and an optional description. You can also specify whether the Quest InTrust for Syslog Service should consider the selected chain when processing Syslog messages. When the Enabled check box is selected, the chain is active, and its parsers are applied to process Syslog messages. To temporarily bypass a chain, clear this option. Though a parser can process messages for all addresses, it is much quicker to filter out irrelevant sources at the chain level. 18

19 To do this, enable the Filter Addresses option. You can either Include or Exclude specific computers from which Syslog messages can arrive. Use the Add, Remove, and Edit buttons to work with the address filter. In place of computer names, you can supply IP addresses as well. Parsing The configuration options presented on this tab let you specify which parsers should be applied and how to invoke them. The Parsers, in order of use list displays all active parsers, which are activated one by one in the order defined here. To change the precedence, click the and buttons. You can add as many parsers as you want. Click New to display the Add Syslog Parser dialog box where you can supply a valid CLSID or a ProgID. Note that a parser must be registered as a COM object. To learn how to implement, register and unregister your own parsers, refer to the Customizing Parsers chapter. You can also click Browse to display the list of registered parsers so that you can choose the parser you want. Use Edit and Remove to change the selected parser CLSID or remove the selected parser from the list. 19

20 Using the Syslog Knowledge Pack for InTrust The Syslog Knowledge Pack for InTrust contains objects for working with audit data collected by InTrust for Syslog. After installation, the necessary objects are available in InTrust Manager. These objects let you do the following: Configure auditing and reporting workflows Monitor activity that goes into Syslog in real-time InTrust Objects in the Knowledge Pack The Knowledge Pack provides the following objects: InTrust for Syslog Log data source All ITFS hosts in the domain site All Syslog events gathering policy All Syslog events import policy Syslog: Scheduled log gathering task, containing a gathering job Report Pack The InTrust for Syslog report pack includes only the All Syslog Events report. After you have completed the InTrust installation, download the report pack from the Quest Software Web site at and install this report pack. Then the InTrust for Syslog reports appears in the new InTrust InTrust for Servers and Applications Syslog report set in Knowledge Portal. Gathering Syslog Audit Data with InTrust Manager The Syslog: Scheduled log gathering task is pre-configured for to collect Syslog data. You can use this task directly by configuring its schedule. However, it is recommended that you use a copy of this task. This gives you a configuration reference in case you inadvertently make undesirable changes to the task, and allows Quest to overwrite the object during upgrade in case the update to the object is needed. To configure gathering 1. Create a copy of the Syslog: Scheduled log gathering task. 2. Set the schedule for the new task as necessary, and enable the schedule. 3. If necessary, create a reporting job within the task and include the All Syslog Events report in it. For details about working with reporting jobs, see the InTrust User Guide. 4. Optionally, add a notification job that informs you of task completion. Detailed instructions on these steps follow: To schedule and activate the task 1. Open the properties of the task. 2. In the properties dialog box, click Modify. 20

21 3. In the dialog box that appears, change the schedule of the task. 4. Select Schedule enabled. 5. Click the Commit button on the InTrust Manager toolbar. To add a notification job InTrust for Syslog User Guide 1. With the task selected in the treeview, click in the right pane and select New Job. 2. In the New Job Wizard, select Notification on the Job Type step. 3. Complete the wizard. 4. Click the reporting job and drag a line from it to your new notification job. Alternatively, right-click your new job, select Dependencies and move the reporting job to the list of parent jobs. This makes the notification job start after the reporting job has completed. Now your report storage will contain a detailed report prepared automatically on schedule. Viewing the Report in Quest Knowledge Portal Check that the InTrust for Syslog report pack is installed. To make up the InTrust for Syslog report using Knowledge Portal, perform the following: 1. Click the Reports tab in the left tabbed pane in the Knowledge Portal console and select the InTrust InTrust for Servers and Applications Syslog report set. 2. Select the report you need from the treeview and configure the report setting in the right pane. 3. Then click the View Report option. For detailed information, see the InTrust Installation and Configuration Guide and Quest Knowledge Portal documentation. 21

22 Customizing Parsers Understanding Parsers Parser Programming Overview Generic Syslog Parser Understanding Parsers In InTrust for Syslog, parsers are building blocks of chains. They are found in the properties of chains on the Parsing tab. Outside the InTrust for Syslog Manager snap-in, they exist as COM objects registered with the system. A parser is where the InTrust for Syslog Service message processing functionality is implemented. Each parser defines what operations will be executed when a Syslog message is received. Typically, such operations include some analysis of the message contents and one or more sets of further message processing instructions. A specific set of operations that will be executed when a Syslog message arrives may depend on the contents of this specific message. That is, the function of a parser is to analyze the contents of the received message and possibly take specific actions based on the results. In complex heterogeneous environments, the messages that come from completely different systems are likely to contain different data that is sent in different formats and requires different actions upon receipt. To provide maximum flexibility in such environments, parsers are combined into ordered processing chains. For each individual chain, filters may be defined so that the chain is applied only to the messages received from specific source computers or devices on the network. A chain itself defines which parsers in what order will be used to process the Syslog messages that the chain receives. Each parser informs the InTrust for Syslog Service if the execution of the next parser in the chain is required for the current Syslog message or if no further processing is required. Clearly, the InTrust for Syslog Service cannot be designed to be aware of the Syslog messaging specifics in all environments. Instead, it knows how to pass the message to a parser, no matter which one is used. To provide for this, all parsers are designed as COM objects that provide a unified interface to the service. That is, once the parser COM object is properly registered in your system, your InTrust for Syslog Service can use it to process the Syslog messages, no matter what functionality is implemented in its code. The parsers that come with InTrust for Syslog are implemented as Windows Script Components using VBScript or JScript as the programming language. You can find these parsers in the Parsers subfolder of the InTrust for Syslog installation folder. If you are going to write your own parsers to handle some Syslog messages in a way that best 22

23 meets the specific needs of your IT system, you can do it in any programming language, interpreted or compiled, that supports COM programming. For details, see the following sections. Parser Programming Overview A parser COM object designed for use with the InTrust for Syslog Service can be implemented in any language suitable for COM programming. The COM object must be designed to support the following interface: [ uuid(64b13612-cb14-40c1-97fb-283d3bd30a1d), helpstring("dsyslogmessageparser Interface") ] dispinterface DSyslogMessageParser { properties: methods: [id(1), helpstring("parses syslog message")] ParseResult Parse( [in] BSTR message, [in] BSTR messagetime, [in] BSTR messagehost, [in] ISyslogServiceObject* psyslogserviceobject ); } The following data type is defined for the returned value: [ uuid(64b13614-cb14-40c1-97fb-283d3bd30a1d), helpstring("syslog message parsing result") ] typedef enum ParseResult { StopMessageParsing = 0, ContinueMessageParsing = 1 } ParseResult; In programming languages that do not support enumerated data types, the variables StopMessageParsing and ContinueMessageParsing of the short data type must be returned, with the value of 0 and 1 respectively assigned in the parser code. Below is a sample parser implemented in VBScript that illustrates the basics of writing InTrust for Syslog parsers. The code is commented so that you can better understand the parser implementation. Everything in bold must be replaced with actual data that is valid for your specific parser. <?xml version="1.0"?> <package> <component> <registration > progid="<syslog Parser ProgID>" classid="{<syslog Parser CLSID>}" version="<syslog Parser Version>" description="<syslog Parser Description>" remotable="true" 23

24 description InTrust for Syslog User Guide <script language="vbscript"> <![CDATA[ CLSID = "{<Syslog Parser CLSID>}" 'Don't edit the lines below description = "Syslog Parser" CATID = "{BC5A9CA4-F B-B1BF-234C3549AD00}" Function register() Set CatReg = CreateObject("AeCatReg.AeCatRegister") CatReg.RegisterCategory CATID, GetLocale(), CatReg.RegisterClassImplCategory CLSID, CATID End Function Function unregister() Set CatReg = CreateObject("AeCatReg.AeCatRegister") CatReg.UnRegisterClassImplCategory CLSID, CATID End Function ]]> </script> </registration> By using the CATID value, InTrust for Syslog Manager recognizes parsers it can use among the other COM objects registered in the system. This takes place when a user is adding a parser to a chain and clicks the Browse button to select one from the list of available parsers. Only parsers with the CATID value of {BC5A9CA4-F B-B1BF- 234C3549AD00} will be listed to select from. Any other parser, however, can still be added to chains by typing its name in the Add Syslog Parser dialog box without the use of browsing. Before you can add a parser to an InTrust for Syslog processing chain you should register it in your system. For details, see Registering a parser later in this guide. The other lines above (starting with the warning comment) must not be changed unless you are absolutely sure you know what you are doing. Changing any of these can make your parser unusable. The parser object has the Parse method that is invoked every time a new Syslog message is received and starts the execution of the parser implementation code. Four parameters are passed to the Parse function when it is called: <public> 'This method is called when the parser is invoked 'to process the incoming Syslog message <method name="parse"> <parameter name="message"/> 'The received Syslog 'message <parameter name="messagetime"/> 'The time when the message 'was received by the 'Quest InTrust Syslog 'Service <parameter name="messagehost"/> 'The IP address of the 'computer that sent the 'message <parameter name="syslogserviceobject"/> 'The reference to the 'SyslogServiceObject </method> </public> 24

25 As you can see, the first three are taken from the current Syslog message, while the last one is a reference to some object that provides for logging functionality to your parser through its properties and/or methods. The Parse function receives all four parameters automatically, so you do not have to take care of this. Parse makes these parameters accessible from the code of the parser, where they may be addressed by name as variables of the following data types: PARAMETER DATA TYPE VBSCRIPT DATA TYPE C/C++ COMMENT message String BSTR The body of the received Syslog message messagetime String BSTR Date and time when the message was received by the InTrust for Syslog Service Date/Time format: %b %d %H:%M:%S %b - Abbreviated month name %d - Day of month as decimal number (01 31). In numbers beginning with 0 it is replaced by space symbol. %H - Hour in 24-hour format (00 23) %M - Minute as decimal number (00 59) %S - Second as decimal number (00 59) Jan 20 09:10:00 messagehost String BSTR The IP address of the computer that sent a message psyslogservice Object Object ISyslogServiceObject The reference to the SyslogServiceObject As InTrust for Syslog is geared for use in the InTrust framework, the parser programming interface is optimized for writing Syslog messages into Windows event logs. This is exactly what the Generic Syslog Parser does: it generates an event in the InTrust for Syslog event log for which the raw text of the received Syslog message is written as an insertion string. You may write more sophisticated code that parses the message text, breaks it into data fields and makes each a separate insertion string in the event. Although the parsers you develop may produce no writing into event logs at all, if they do, we would recommend using the ReportEvent method of the SyslogServiceObject. For more details, see the SyslogServiceObject.ReportEvent Method section below. This function is optimized for maximum performance and can make your parser work much faster due to extended event caching mechanisms implemented in its code. 25

26 SyslogServiceObject.ReportEvent Method ReportEvent is the only method of the SyslogServiceObject that you can use. Seven parameters can be passed to this function when it is called. The first three parameters are required, while the next four are optional: PARAMETER DATA TYPE VBSCRIPT DATA TYPE C/C++ COMMENT sourcename String BSTR The name of the event source registered for use with the Windows event logs. This name is written to the event logs for each event and appears in the Source column when you browse them with the Windows Event Viewer. Registering a source associates it with a specific event log to which all events generated by this source will be written. eventtype Number short 1 Error If you call the ReportEvent method with a text string that is not a name of any registered event source as a value of the sourcename parameter, the generated event is written to the Application event log with this string included as the event source. Registering new event sources is a separate programming task and is not covered in this brief overview. 2 Warning 4 Information 8 Success audit 16 Failure audit eventid Number long Specifies the event. If you use a registered custom event source, this number specifies the message that goes with this event as an entry in the message file associated with the event source. And even if you use an unregistered event source name, you probably have or would like to have a policy or a convention established in your corporate IT system for numbering events generated by various software developed in-house. Technically, any numeric value can be used as a value of this parameter. insertionstrings Array VARIANT An array of string values that you want to be written to the event log as insertion strings included into the record of the current event. The size of each string is limited to 32K characters. 26

27 PARAMETER DATA TYPE VBSCRIPT DATA TYPE C/C++ COMMENT eventcategory Array VARIANT There may be a policy or a convention in force for your IT system that defines specific categories for system events generated by the software developed in-house, or you can use your own system of meaningful event categories. Technically, any numeric value can be used as a value of this parameter. useraccount Array VARIANT The name of the Windows user account under which the event will be generated. It may be specified as one of the following: Account name in Domain_Name\User_name notation Account SID provided as a text string rawdata Array VARIANT Any raw binary data provided as an array of one-byte elements. The value of any element that is longer than one byte will be cut to the value of its lower byte. ReportEvent is implemented so that it caches the sourcename and useraccount parameters used since the InTrust for Syslog Service was started. That is, the user account information provided in text form is resolved into a binary SID only once and then reused. The same is true for receiving the handle for each registered event source. This allows you to significantly increase the performance of parser execution, which makes the use of the SyslogServiceObject.ReportEvent method preferable everywhere in your parser code where you want it to write anything into Windows event logs. Parse = StopMessageParsing 'No further parsers in chain 'will be used for the current 'Syslog message 'OR Parse = ContinueMessageParsing 'Next parser in chain 'will be run for the 'current Syslog mesage, too End Function ]]> </script> </component> </package> Depending on your need to have the current Syslog message processed with next parser in the chain after the execution of the current parser is finished, you must choose the value that the Parse method will return to the InTrust for Syslog Service. To apply next parser to the processed message, Parse must return ContinueMessageParsing. To stop processing the message by subsequent parsers in chain, StopMessageParsing must be returned. Since VBScript does not support the enumerated data types, the explicit assignment of the respective values 1 and 0 to the ContinueMessageParsing and StopMessageParsing variables was made in this example. 27

28 Registering a Parser After you implement a parser of your own, you should register it in your system. Save the file that contains your parser code with the *.wsc extension (so that the system recognizes it as a Windows Script Component). Right-click it to bring up the shortcut menu and click Register. To unregister a parser, right-click the file that contains your parser code and click Unregister. Generic Syslog Parser The Generic Syslog Parser program receives the raw text of the Syslog messages as the input, converts all Syslog messages to Windows event records (the entire unmodified message is written to the Description field), and writes them to the InTrust for Syslog event log. It also tries to find the values of the standard data fields (priority, time, host and tag) in the message text. If this data cannot be found, the default values are used: priority = 14 time = messagetime* host = messagehost* tag = "" *The messagetime and messagehost parameters are explained in Parser programming overview section earlier in this Guide. The value assigned to priority is then used to calculate Syslog message facility and severity. The value of facility is further mapped into event category and the value of severity is mapped into the event type and then passed to the ReportEvent method as eventcategory and eventtype respectively. Here is how this functionality is implemented: <?xml version="1.0"?> <package> <component> <registration progid="syslogparse.genericsyslogparser" classid="{d3b6444d-0ba a473-90a9335dff99}" version="1" description="syslog message parser" remotable="true"> <script language="vbscript"> <![CDATA[ description = "Syslog Parser" 28

29 CLSID = "{D3B6444D-0BA A473-90A9335DFF99}" CATID = "{BC5A9CA4-F B-B1BF-234C3549AD00}" InTrust for Syslog User Guide Function register() Set CatReq = CreateObject("AeCatReg.AeCatRegister") CatReq.RegisterCategory CATID, GetLocale(), description CatReq.RegisterClassImplCategory CLSID, CATID End Function Function unregister() Set CatReq = CreateObject("AeCatReg.AeCatRegister") CatReq.UnRegisterClassImplCategory CLSID, CATID End Function ]]> </script> </registration> <public> <method name="parse"> <parameter name="message"/> <parameter name="messagetime"/> <parameter name="messagehost"/> <parameter name="syslogserviceobject"/> </method> </public> <script language="vbscript"> <![CDATA[ StopMessageParsing = 0 ContinueMessageParsing = 1 Function Parse( message, messagetime, messagehost, SyslogServiceObject ) 'The event source name sourcename = "Generic Syslog" 'All Syslog messages are assigned the EventID = &ha000000c 'For your own parser, you can make the EventID to depend on 'parsing result eventid = &ha000000c 'The patterns below are used to extract specific strings from 'the Syslog message PriorityPattern = "^<(\d{1,2} 1[0-8]\d 19[01])>" TimeStampPattern = "^((Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec) ( \d [12]\d 3[01]) ([01]\d 2[0-3]):[0-5][0-9]:[0-5][0-9]) " HostnamePattern = "^((\d{1,3}\.){3}\d{1,3} ([a-za-z]([a-za- Z\d]* [a-za-z\d\-]*[a-za-z\d]))?) " TagPattern = "^([a-za-z\d]{1,32})[^a-za-z\d]" Dim priority, time, host, tag Dim re Set re = new RegExp 'Search Priority field re.pattern = PriorityPattern Set parsed = re.execute(message) If parsed.count Then priority = parsed.item(0) priority = Mid( priority, 2, Len(priority)-2) message = Mid(message, Len(priority)+3) 'Search time field re.pattern = TimeStampPattern Set parsed = re.execute(message) If parsed.count Then time = parsed.item(0) time = Mid( time, 1, Len(time)-1) message = Mid(message, Len(time)+2) 'Search hostname field re.pattern = HostnamePattern 29

30 message) Set parsed = re.execute(message) If parsed.count Then host = parsed.item(0) host = Mid( host, 1, Len(host)-1) message = Mid(message, Len(host)+2) 'Search tag field re.pattern = TagPattern Set parsed = re.execute(message) If parsed.count Then tag = parsed.item(0) tag = Mid( tag, 1, Len(tag)-1) InTrust for Syslog User Guide 'Extract Syslog message body message = Mid(message, Len(tag)+1) End If End If End If End If 'If there are no fields in the message, 'the default values are used If IsEmpty(Tag) Then tag = "" If IsEmpty(host) Then host = messagehost If IsEmpty(time) Then time = messagetime If IsEmpty(priority) Then priority = "14" End If End If End If End If 'Calculate the event type severity = priority mod 8 Select Case severity Case 0,1,2,3 eventtype = 1 'EVENTLOG_ERROR_TYPE; Case 4 eventtype = 2 'EVENTLOG_WARNING_TYPE; Case Else eventtype = 4 'EVENTLOG_INFORMATION_TYPE; End Select eventcategory = (priority\8)*8 'Make insertion strings insertionstrings = Array(priority, time, host, tag, 'Write event to the event log 'Other optional parameters are omitted SyslogServiceObject.ReportEvent sourcename, _eventtype, _eventid, _insertionstrings Parse = ContinueMessageParsing End Function ]]> </script> </component> </package> 30

31 Appendix A: InTrust for Syslog Service Events In case of errors and problems with message processing, the InTrust for Syslog Service writes Error and Warning events to the Windows Application event log, thus providing you with help in locating trouble spot(s). Some routine information about the service execution is reported to the Application event log as well. The table below lists and explains the most useful InTrust for Syslog Service events. EVENT TYPE EVENT ID MESSAGE EXPLANATION 8 Cannot create parser (CLSID = %1; ProgID = %2). %3 9 No processing chain(s) 10 Cannot find parser %1. The InTrust for Syslog Service could not create the instance of the parser COM object registered with the specified CLSID and ProgID. The execution of the service is not terminated. Insertion strings: %1 - CLSID registered for the parser COM object; %2 - ProgID registered for the parser COM object. %3 - the reason for the failure as returned by your OS. This event indicates that the InTrust for Syslog Service has started successfully but could not find any chains in the processing configuration. The service keeps running until you stop or restart it. In this case, if you add some chain(s), you have to either restart the service, or pause and resume it for the new configuration to be loaded. The CLSID for the parser COM object cannot be found for the given ProgID. The COM object for the parser is registered incorrectly. Insertion strings: %1 - ProgID registered for the parser COM object. 31

32 EVENT TYPE EVENT ID MESSAGE EXPLANATION 13 Quest InTrust for Syslog Service started 14 Quest InTrust for Syslog Service stopped 15 Quest InTrust for Syslog Service unexpectedly terminated at %1 16 Syslog listening started 17 Syslog listening stopped 18 Cannot load configuration. %1 19 Empty configuration loaded. The InTrust for Syslog Service has been successfully loaded into memory and its execution has been started. No attempt to load parser chains for processing has been made yet. The execution of the InTrust for Syslog Service has been stopped correctly. All parsers have been closed and unloaded. This event is written to the event log when the InTrust for Syslog Service starts after an abnormal termination. Unlike the events 22 and 23 that indicate problems with parsers the service uses, this event is generated when the service itself cannot shut down correctly. For example, if a power failure happens on the computer where the InTrust for Syslog Service is running, event 15 will be written to the event log the next time you start this service. Insertion strings: %1 - date and time of the process abnormal termination in the ddd MMM dd HH:mm:ss yyyy format. Indicates that the service has started to listen for Syslog messages (for example, after it has been started or resumed after pausing). Indicates that the service has stopped listening for Syslog messages (for example, the service has been paused or stopped). The InTrust for Syslog Service failed to load and start processing the parsing chains defined for it. The configuration database may be corrupt, the account under which the service is run may have insufficient access permissions to the configuration file or to the registry key that defines it, or some other problem of this kind may exist. Insertion strings: %1 - the description of the reason for the failure as returned by your OS or an application involved. The InTrust for Syslog Service has found and loaded the configuration that contains some chain definition(s), but no parsers are defined for any chain. 32

33 EVENT TYPE EVENT ID MESSAGE EXPLANATION 22 Quest InTrust for Syslog Service hung at %1 while creating object (CLSID = %2; ProgID = %3). 23 Quest InTrust for Syslog Service hung at %1 using object (CLSID = %2; ProgID = %3). 24 Message is discarded. Time: %1; Host: %2; Message: %3 This event is generated when the InTrust for Syslog Service starts after abnormal termination caused by the failed attempt to create an instance of the COM object for some parser. The problem is not with the service itself, but with the parser it tried to process. Insertion strings: %1 - date and time of the failure in the ddd MMM dd HH:mm:ss yyyy format; %2 - CLSID registered for the parser COM object; %3 - ProgID registered for the parser COM object. This event is generated when the InTrust for Syslog Service starts after abnormal termination caused by a failed attempt to use a parser for an instance of a COM object which has been successfully created. The problem is not with the service itself, but with the parser it tried to process. Insertion strings: %1 - date and time of the failure in the ddd MMM dd HH:mm:ss yyyy format; %2 - CLSID registered for the parser COM object; %3 - ProgID registered for the parser COM object. Indicates that the size of the 'Maximum message buffer' defined in the service properties has been exceeded, and one specific message has been lost from the buffer. If the service is configured to override messages as needed, the oldest messages in the buffer are discarded, while the newest ones are added to it. Otherwise, the old messages are kept in the buffer and newlyarriving messages are discarded and lost. Insertion strings: %1 - time when the discarded message was received (in MMM dd HH:mm:ss format); %2 - IP address of the message source computer; %3 - the text of the discarded message EVENT TYPES - information; - warning; - error. 33

34 Appendix B Appendix B-a: Message Facility Appendix B-b: Message Priority Appendix B-c: Message Logging Keywords and Levels (Cisco Routers) Appendix B-a: Message Facility FACILITY EXPLANATION AUTH AUTHPRIV CRON DAEMON FTP KERN LPR MAIL NEWS SYSLOG USER UUCP LOCAL0 LOCAL7 The authorization system The same as LOG_AUTH, but logged to a file readable only by selected individuals. The cron daemon (Scheduler) System daemons (Services) that are not provided for explicitly by other facilities. The file transfer protocol daemon Messages generated by the kernel. These cannot be generated by any user processes. The line printer spooling system The mail system The network news system Messages generated internally by syslogd (Like the Windows System Events) Messages generated by random user processes. This is the default facility identifier if none is specified The uucp system Reserved for local use * All facilities 34

35 Appendix B-b: Message Priority SEVERITY EMERG ALERT CRIT ERR WARNING NOTICE INFO DEBUG EXPLANATION A panic condition. This is normally broadcast to all users. A condition that should be corrected immediately, such as a corrupted system database. Critical conditions, e.g., hard device errors. Errors. Warning messages. Conditions that are not error conditions, but should possibly be handled specially. Informational messages. Messages that contain information normally of use only when debugging a program. EMERG is the most severe message while DEBUG is the least severe message. Appendix B-c: Message Logging Keywords and Levels (Cisco Routers) LEVEL KEYWORD DESCRIPTION SYSLOG DEFINITION 0 Emergencies System is unusable. LOG_EMERG 1 Alerts Immediate action is needed. LOG_ALERT 2 Critical Critical conditions exist. LOG_CRIT 3 Errors Error conditions exist. LOG_ERR 4 Warnings Warning conditions exist. LOG_WARNING 5 Notification Normal, but significant, conditions exist. LOG_NOTICE 6 Informational Informational messages. LOG_INFO 7 Debugging Debugging messages. LOG_DEBUG 35

36 About Quest Software, Inc. Established in 1987, Quest Software (Nasdaq: QSFT) provides simple and innovative IT management solutions that enable more than 100,000 global customers to save time and money across physical and virtual environments. Quest products solve complex IT challenges ranging from database management, data protection, identity and access management, monitoring, user workspace management to Windows management. For more information, visit Contacting Quest Software Mail Web site Quest Software, Inc. World Headquarters 5 Polaris Way Aliso Viejo, CA USA Refer to our Web site for regional and international office information. Contacting Quest Support Quest Support is available to customers who have a trial version of a Quest product or who have purchased a Quest product and have a valid maintenance contract. Quest Support provides unlimited 24x7 access to our Support Portal at From our Support Portal, you can do the following: Retrieve thousands of solutions from our online Knowledge Base Download the latest releases and service packs Create, update and review Support cases View the Global Support Guide for a detailed explanation of support programs, online services, contact information, policies and procedures. The guide is available at: 36

37 Third Party Contributions InTrust, version 10.6 contains some third party components (listed below). Copies of their licenses may be found at COMPONENT LICENSE OR ACKNOWLEDGEMENT boost Boost License version 1.0 CLucene 0.9 Apache version 1.1 This product includes software developed by the Apache Software Foundation ( expat MIT flex 2.5.4, , flex /27 GNU standard C++ class library 3* Net-SNMP GPL 2.0 with the "runtime exception" Net-SNMP OpenSSL 0.9.6g OpenSSL 1.0 This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit ( SpiderMonkey 1.5* Netscape Public License ("NPL") 1.1 Stanford SRP Windows Installer XML toolset (WIX) Stanford SRP This product includes software developed by Tom Wu and Eugene Jhong for the SRP Distribution ( This product uses the "Secure Remote Password' cryptographic authentication system developed by Tom Wu Common Public License 1.0 ZLib zlib Copyright Jean-loup Gailly and Mark Adler libiconv 1.1 LGPL (GNU Lesser General Public License) 2.1 NLog 2.0 BSD - Kowalski 2011 * a copy of the source code for this component is available at License agreement texts are provided in the Third Party Licenses HTML document. 37