Infrastructure Guide

ADMINISTRATION GUIDESAP BCM INFRASTRUCTURE

SOFTWARE VERSION 6.0 SP5

DOCUMENT VERSION 2.0 (23.4.2009)

COPYRIGHT

© Copyright 2008 SAP AG. All rights reserved.

No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice.

Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors.

Microsoft, Windows, Outlook, and PowerPoint are registered trademarks of Microsoft Corporation.

IBM, DB2, DB2 Universal Database, OS/2, Parallel Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390, OS/400, iSeries, pSeries, xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere, Netfinity, Tivoli, Informix, i5/OS, POWER, POWER5, OpenPower and PowerPC are trademarks or registered trademarks of IBM Corporation.

Adobe, the Adobe logo, Acrobat, PostScript, and Reader are either trademarks or registered trademarks of Adobe Systems Incorporated in the United States and/or other countries.

Oracle is a registered trademark of Oracle Corporation.

UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group.

Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, and MultiWin are trademarks or registered trademarks of Citrix Systems, Inc.

HTML, XML, XHTML and W3C are trademarks or registered trademarks of W3C®, World Wide Web Consortium, Massachusetts Institute of Technology.

Java is a registered trademark of Sun Microsystems, Inc.

JavaScript is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape.

MaxDB is a trademark of MySQL AB, Sweden.

SAP, R/3, mySAP, mySAP.com, xApps, xApp, SAP NetWeaver, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and in several other countries all over the world. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary.

These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.

ADMINISTRATION GUIDE TABLE OF CONTENTS

23.4.2009

TABLE OF CONTENTS1. Introduction ....................................................................................................................................................... 1

2. High Availability Controller (HAC) ................................................................................................................ 5

2.1. Installing and removing HAC instances.................................................................................. 52.2. Starting and stopping instances ............................................................................................... 62.3. Architecture ............................................................................................................................. 6

2.3.1. Management process................................................................................................... 72.3.2. Inter-HAC communications ........................................................................................ 7

2.4. Service parameters................................................................................................................... 82.5. Service application interfaces.................................................................................................. 9

2.5.1. Windows process......................................................................................................... 92.5.2. Windows service ......................................................................................................... 92.5.3. Web server monitoring................................................................................................ 92.5.4. Shell monitor and controller ..................................................................................... 10

2.6. External alarm interface ........................................................................................................ 112.6.1. Alarm format............................................................................................................. 112.6.2. Transportation methods............................................................................................. 13

2.6.2.1. Alarm log file................................................................................................ 132.6.2.2. HTTP alarm Destinations ............................................................................. 13

2.6.3. HAC alarms............................................................................................................... 132.6.3.1. Initialisation .................................................................................................. 142.6.3.2. Configuration................................................................................................ 142.6.3.3. Process .......................................................................................................... 142.6.3.4. Watchdog ...................................................................................................... 152.6.3.5. Interhac ......................................................................................................... 152.6.3.6. Elements ....................................................................................................... 152.6.3.7. Redundancy ................................................................................................. 16

3. Virtual Unit Administrator (VUA) ............................................................................................................... 17

3.1. Installing and starting VUA................................................................................................... 173.2. Using graphical user interface (GUI) .................................................................................... 183.3. Adding virtual units ............................................................................................................... 213.4. Adding software components ................................................................................................ 223.5. Adding hotfixes .................................................................................................................... 23

iSAP BCM INFRASTRUCTURE


23.4.2009

3.5.1. Adding hotfixes to base installation.......................................................................... 233.5.2. Adding hotfixes to software component................................................................... 23

3.6. Removing hotfixes ................................................................................................................ 243.6.1. Removing hotfixes from base installation ................................................................ 253.6.2. Removing hotfix from software component............................................................. 25

3.7. Changing base installation .................................................................................................... 263.8. Upgrading software components........................................................................................... 273.9. Updating configuration variables .......................................................................................... 283.10. Removing virtual units ........................................................................................................ 283.11. Removing software components ......................................................................................... 283.12. Committing all changes....................................................................................................... 293.13. Refreshing system view and clearing changes.................................................................... 293.14. Clearing log view and changing logging level.................................................................... 293.15. Using command line options............................................................................................... 29

4. Infrastructue Administrator (IA) .................................................................................................................. 31

4.1. Installing and starting IA....................................................................................................... 314.2. Using graphical user interface (GUI) .................................................................................... 314.3. Using system model .............................................................................................................. 34

4.3.1. System element ......................................................................................................... 344.3.2. HAC Nodes............................................................................................................... 344.3.3. Virtual units............................................................................................................... 354.3.4. Other software........................................................................................................... 364.3.5. Monitoring views...................................................................................................... 36

4.4. Using IA products ................................................................................................................. 374.4.1. Generic products ....................................................................................................... 374.4.2. Virtual Unit Products ................................................................................................ 384.4.3. Virtual Unit Component Products............................................................................. 384.4.4. Old Wicom Products................................................................................................. 394.4.5. Supported third-party products ................................................................................. 404.4.6. Customised products................................................................................................. 40

5. Alarm Server.................................................................................................................................................... 45

5.1. Installing and removing Alarm Server instances .................................................................. 455.2. Starting and stopping instances ............................................................................................. 46

SAP BCM INFRASTRUCTUREii


23.4.2009

5.3. Configuring Alarm Server ..................................................................................................... 465.3.1. Service parameters .................................................................................................... 465.3.2. Alarm adapters .......................................................................................................... 48

5.3.2.1. E-mail adapter............................................................................................... 485.3.2.2. SMS adapter ................................................................................................. 515.3.2.3. SNMP adapter............................................................................................... 525.3.2.4. Alarm Filtering (all adapters) ....................................................................... 53

6. HAC system model .......................................................................................................................................... 57

6.1. Managed system elements (MSE) ......................................................................................... 576.1.1. HA system element ................................................................................................... 586.1.2. Service element ......................................................................................................... 586.1.3. Software element....................................................................................................... 586.1.4. Computer system element ......................................................................................... 596.1.5. Redundant system element........................................................................................ 59

6.2. Basic element properties........................................................................................................ 596.2.1. Composition .............................................................................................................. 596.2.2. Dependency............................................................................................................... 606.2.3. Element status ........................................................................................................... 606.2.4. Element health........................................................................................................... 606.2.5. Element role .............................................................................................................. 616.2.6. Desired status of element .......................................................................................... 616.2.7. Operational mode...................................................................................................... 626.2.8. Location .................................................................................................................... 636.2.9. Element tag ............................................................................................................... 63

6.3. All element properties ........................................................................................................... 636.3.1. Common managed system element properties.......................................................... 636.3.2. Software element properties...................................................................................... 656.3.3. Service access point (IP address) properties ............................................................. 676.3.4. Service properties...................................................................................................... 686.3.5. Computer system properties...................................................................................... 696.3.6. Redundant system properties .................................................................................... 706.3.7. HA system properties................................................................................................ 72

6.4. Attachment element properties.............................................................................................. 726.4.1. Common attachment properties ................................................................................ 72

iiiSAP BCM INFRASTRUCTURE


23.4.2009

6.4.2. Element monitors...................................................................................................... 726.4.2.1. Windows process monitor ............................................................................ 726.4.2.2. Windows service monitor............................................................................. 736.4.2.3. Command line monitor................................................................................. 736.4.2.4. Web server monitor ...................................................................................... 73

6.4.3. Element controllers ................................................................................................... 746.4.3.1. Windows process controller ......................................................................... 746.4.3.2. Windows service controller .......................................................................... 746.4.3.3. Command line controller.............................................................................. 756.4.3.4. IIS site controller .......................................................................................... 75

6.5. Behaviour scenarios .............................................................................................................. 756.5.1. Activation scenarios.................................................................................................. 75

6.5.1.1. Starting up system ........................................................................................ 766.5.1.2. Activating service elements.......................................................................... 766.5.1.3. Activating redundant system elements......................................................... 76

6.5.2. Inactivation scenarios ............................................................................................... 776.5.2.1. Inactivating system elements........................................................................ 776.5.2.2. Inactivating local computer system element ................................................ 776.5.2.3. Inactivating service elements ....................................................................... 77

6.5.3. Recovery scenarios ................................................................................................... 776.5.3.1. Failure of software element.......................................................................... 786.5.3.2. Failure of computer system element ............................................................ 786.5.3.3. Silent failure of computer system................................................................. 786.5.3.4. Software element recovery from transient failure........................................ 786.5.3.5. Redundant system recovery.......................................................................... 796.5.3.6. Recovery from network failure .................................................................... 79

7. Administrative tasks........................................................................................................................................ 81

7.1. Backing up Server ................................................................................................................. 817.2. Backing up virtual unit instance............................................................................................ 827.3. Restoring virtual unit instance From Backup........................................................................ 827.4. Upgrading infrastructure software ........................................................................................ 827.5. Upgrading other software...................................................................................................... 837.6. Changing IP addresses .......................................................................................................... 84

7.6.1. Reconfiguring Databases .......................................................................................... 84

SAP BCM INFRASTRUCTUREiv


23.4.2009

7.6.2. Reconfiguring HAC system model ........................................................................... 847.6.3. Reconfiguring Virtual Unit Instances ....................................................................... 857.6.4. Reconfiguring PSTN gateways................................................................................. 857.6.5. Reconfiguring End-User Clients ............................................................................... 85

7.7. Changing passwords .............................................................................................................. 85

8. Troubleshooting ............................................................................................................................................... 87

8.1. HAC log files......................................................................................................................... 878.2. HAC element diagnostics ...................................................................................................... 888.3. Problem Scenarios ................................................................................................................. 89

8.0.1. Communication with node fails ................................................................................ 908.0.2. All elements in node stay in unknown health ........................................................... 908.0.3. All nodes are failed ................................................................................................... 908.0.4. Some virtual unit components fail immediately ....................................................... 908.0.5. Some software elements fail after a while ................................................................ 918.0.6. HAC log file displays system error code 12 ............................................................. 918.0.7. HAC fails to control or monitor IIS web Server ....................................................... 918.0.8. Database or IIS web site fails immediately after rebooting computer ...................... 91

9. Glossary............................................................................................................................................................ 93

vSAP BCM INFRASTRUCTURE


23.4.2009

SAP BCM INFRASTRUCTUREvi

ADMINISTRATION GUIDE1. INTRODUCTION

23.4.2009

1. INTRODUCTIONThe following applications are used for managing the SAP BCM system infrastructure:

High Availability Controller (HAC) => HAC is the application running on the background of each server. It performs constant monitoring and controlling tasks on the server, and networks with other HAC instances running in other servers to perform system management tasks outside a single computer’s environment. HAC monitors and manages the system components (such as software applications and web sites) to keep the end-user services available at all times. For example, if a managed server fails, HAC automatically restarts the services on another server which allows continuing the end-user servicing. See the section 2. High Availability Controller (HAC) (page 5).Virtual Unit Administrator (VUA) => The application for installing and managing the server software on each particular server. It uses a set of the software packages that contain the actual SAP BCM server software to be installed. See the section 3. Virtual Unit Administrator (VUA) (page 17).Infrastructure Administrator (IA) => The application running on one or more administration workstations. The system administrators use it for viewing and managing the system status as seen by each of the connected HAC instances. See the section 4. Infrastructue Administrator (IA) (page 31).Alarm Server => The application for converting and transferring alarms to some third-party network management systems. Some components of the software can generate these alarms when problems occur. See the section 5. Alarm Server (page 45).System model => Logical model of the server system hosting customer services. System model describes the particular managed system and it includes managed computer systems, software, access points and redundancy settings. See the section 6. HAC system model (page 57).

The infrastructure management applications are included in the Infrastructure installation package. The installation package asks the name of the installed HAC node and performs the required initialization automatically. By default the installation directory is C:\Program Files\SAP\BCM\HAC (the main HAC directory), and it contains the listed management applications.

You must be systematic and logical when creating and maintaining data in order to make the entire system work as intended. Use consistent syntax and keep in mind that information may be displayed in other applications as well. You must also be familiar with the whole concept and the related terminology before you start the setup and configuration work.

Some of the functions described in this guide may not be implemented in your system, or you may not have permission to use some of the functions. Furthermore, your system may include separately implemented customer-specific features that this guide does not cover. Contact the supplier or administrator for more information.

It is important to understand the following concepts related to this guide:

Server => In this document a physical computer system which is capable of running software applications. Some servers may have a variety of attached special hardware, such as a disk array or PSTN gateway cards. Servers can be categorized according to their primary role in the system. For example, a computer system with a large RAID disk array and a large amount

1SAP BCM INFRASTRUCTURE


23.4.2009

of RAM may primarily be used as a database server, whereas another computer system with PSTN gateway cards may primarily be used as a gateway server. In this context an application server usually means a computer system that is used for running general software applications (other than database or gateway software). A single physical computer system may have multiple roles and these categorizations or primary roles do not necessarily imply that these servers could not or would not be used for any other purposes.Customer => In this document an independent subsystem within a server system hosting several of this type of subsystems simultaneously. For example, a customer may be a customer of an Application Service Provider (ASP) center which hosts services, or an internal subdivision of such customer. Each customer has its own independent set of data, services and access points (in terms of end-user terminals).Physical and virtual IP address => It is important to understand the difference between a physical and virtual IP address. A physical (real) IP address is statically assigned to a physical computer system. A virtual IP address is managed by HAC, which may reassign the address dynamically to another server. Each physical address is related to a specific physical computer system, whereas each virtual address is related to a specific virtual unit.Virtual unit =>A group of technical services that are managed as a single unit. A virtual unit is usually associated with an access point (IP address) which is used to access the virtual unit’s services over network. To achieve redundancy for the virtual unit’s services, an instance of the virtual unit is set up on two or more servers while only one of these instances is activate at a time. If the server with an active virtual unit instance fails, another of the virtual unit’s instances is activated, thus allowing the virtual unit’s services to continue on another server with minimal downtime.

The following terminology and abbreviations are specific to this document and the Installation Guide document:

Alarm log => A log file which contains only alarms.ASP => See the section 9. Glossary (page 93).Base installation => A directory containing a set of the software packages for VUA.CIM => Common Information Model => Related to DMTF.DMTF => Distributed Management Task ForceEvent log => A log file which is generated by an application and used for troubleshooting purposes.HA => See the section 9. Glossary (page 93).HAC node => A computer system which runs a HAC instance.MSE => Managed System Element => Represents a physical or logical part of the system managed by HAC.Production system => A system producing services for a real customer. Compare to the term test system which is used for testing purposes only.System component => A component in the system that HAC manages.Trace log => A log file which is generated by an application and used for troubleshooting purposesUML => Unified Modeling LanguageXML => Extensible Markup Language

SAP BCM INFRASTRUCTURE2


23.4.2009

ITEM MARKING EXAMPLEProper nouns Italic Microsoft Windows Various user interface items (such as buttons, menus, submenus, dialog windows, tabs, and sheets)

Italic Click the Update button.

Select Start > Programs > Internet Explorer.Paths and directories Italic By default the file is located in the following

directory: C:\Documents.Values and variables Italic Replace the xyz value with the 123 value.Code examples Courier fontSome functions Bold You can use the Find and replace function for

searching items.Terminology Bold italic By default clicking refers to the left mouse

button.

CAUTION: The SAP Business Communication Management software users (service providers and end-users) are fully responsible for ensuring that the services provided using this software do not violate or are not used in contravention of local legislation. The software users must acknowledge that the software collects identification data for enabling the services and their invoicing, security and troubleshooting, protecting the services against misuse and misappropriation, and further improvement of the software and services, and they must assume the full responsibility for the use of the collected data.

Conventions in this document

CAUTION: This is an important caution.

NOTE: This is a necessary note.

HINT: This is a helpful hint.

run if xyz = 123



23.4.2009


ADMINISTRATION GUIDE2. HIGH AVAILABILITY CONTROLLER (HAC)

23.4.2009

2. HIGH AVAILABILITY CONTROLLER (HAC)High Availability Controller (HAC) is the application running in the background of each server. It performs constant monitoring and controlling tasks on the server, and networks with other HAC instances running in other servers to perform system management tasks outside a single computer’s environment. HAC monitors and manages the system components (such as software applications and web sites) to keep the end-user services available at all times. For example, if a managed server fails, HAC automatically restarts the services on another server which allows continuing the end-user servicing. For redundancy and timeout settings, see also the chapter 6. HAC system model (page 57).

Typically a single HAC instance (may also be called a HAC node or just HAC) is installed on each computer. All HAC instances have a unique name which identifies them in the system model and differentiates them from other HAC instances. The HAC instance name and the name of the local computer have no enforced relation.

HAC users are defined during HAC installation. There two types of users:

Administrator users, who are allowed to create and modify system model in the IA tool and start and stop components in it. We recommend that these users connect the system from the workstation located in the servere network.View-only users who can monitor the system status. Monitoring can take place also in the office-network.

This section describes the following functions and issues:

2.1. Installing and removing HAC instances (page 5)2.2. Starting and stopping instances (page 6)2.3. Architecture (page 6)2.4. Service parameters (page 8)2.5. Service application interfaces (page 9)2.6. External alarm interface (page 11)

2.1. INSTALLING AND REMOVING HAC INSTANCES

Install the HAC software package with the VUA tool from it own software package. We recommend that HAC is installed in a specific virtual unit, possibly sharing it with the Alarm Server package.

Define in the VUA tool the HAC node name, HAC node server address and administration addresses, the administration and view-only users, and optionally, if the connection is to be secured with the TLS, the server certificate names for both the HAC-HAC and HAC administration connections. See the Installation Guide for more specific instructions.

NOTE: Only the users defined as HAC administrators can start and stop the system model, that is, start and stop the system and its components.


ADMINISTRATION GUIDE2.2. STARTING AND STOPPING INSTANCES

23.4.2009

Remove the HAC node accordingly with the VUA tool.

Advanced

If you need to reinstall or reinitialise a HAC instance manually, perform the following procedure in the directory which contains the hac.exe file:

1. Initialize the Microsoft Windows registry for the HAC instance by using the command line hac -init name=<HAC INSTANCE_NAME>.

2. Install HAC as a Microsoft Windows service by using the command line hac -install name=<HAC INSTANCE_NAME>.

NOTE: You can install HAC into any directory, but if you want to change the directory afterwards, you need to reinstall the HAC service.

If you need to remove an instance manually, perform the following procedure:

1. Remove the HAC service by using the command line hac -remove name=<HAC INSTANCE_NAME>.

2. Clean up the Microsoft Windows registry by using the command line hac -cleanup name=<HAC INSTANCE_NAME>.

3. Delete the HAC directory and its entire contents.

2.2. STARTING AND STOPPING INSTANCES

A HAC instance is a Microsoft Windows service. You can use the Microsoft Windows Services control panel to start and stop it. Note the following:

The name of the service is SAP BCM HAC <NodeName>.The installation package makes the HAC service to start up automatically.The recovery method is defined to restart the application.If you change the recovery or start-up options of the HAC service, it may cause HAC to malfunction.

2.3. ARCHITECTURE

Each HAC instance communicates with other HAC instances via the HAC-to-HAC interface. The communications are built on TCP/IP protocol and use the IP addresses and ports defined for each HAC node in the system model.

HAC includes interfaces to monitor and control the external entities (such as service applications, IP addresses and IPMI devices). These interfaces are called service application interfaces.

The alarm interface is used for generating alarms to a network management system. HAC generates and transports alarms in the XML format over the HTTP protocol. The optional conversions to


ADMINISTRATION GUIDE2.3.1. MANAGEMENT PROCESS

23.4.2009

SNMP and other network management protocols are done outside of HAC, for example, in the Alarm Server application, see the section 5. Alarm Server (page 45).

2.3.1. MANAGEMENT PROCESS

A HAC instance manages the elements in the local node. It communicates with HAC instances in other nodes to maintain the desired overall status of the system. After a HAC instance has gained the system model and other configuration data, it starts its node management process.

HAC monitors and manages the state (role, status, health and so on) of each managed element in the local node. It also goes through the elements spanning across nodes by checking the local representatives of the elements. If HAC notices that state of an element does not match its desired value, it triggers actions to control the element and to bring it to the desired state. For example, if an element seems to fail permanently, HAC raises a minor alarm and tries to take the corrective action to replace the failed unit with a spare unit. If the corrective actions are not successful, a critical alarm is raised to notify the administrator.

While the system is up and running smoothly, HAC instances only execute monitoring actions. Although a HAC instance is not required to successfully run the end-user services in the system, all HAC instances on servers should be kept running at all times. In the normal operational mode only very short down time and controlled resets are allowed on any HAC instance without causing automatic recovery actions by other HAC instances.

Each HAC determines the status and health of each node by communicating with its HAC instance and the operating system of that node. If all communication fails, the node is considered inactive and failed. There are no built-in mechanisms in HAC to shut down or control other nodes or their operating systems remotely. If a missing node reappears, it is automatically considered as active and working, and the system state information is synchronized with the reappeared instance.

See also 6. HAC system model (page 57) for more information on the management process and its settings.

2.3.2. INTER-HAC COMMUNICATIONS

To communicate with each other, HAC instances form persistent connections using the IP addresses defined in the system model for each node. Each node may be defined more than one optional addresses.

If a connection to HAC instance is lost, HAC instances automatically attempt to re-establish the connection. Once the connection is re-established, the HAC instances synchronize their views to account for any lost information while the connection was down. If a connection to a HAC instance is lost for longer than time specified in the system model, the HAC instance is considered as lost and thus failed.

HAC instances contain some instance-specific configuration parameters. The instance parameters include the logging level, the diagnostics generation option, and some tuning parameters.

The data in the system model may be divided into two rough categories:


ADMINISTRATION GUIDE2.4. SERVICE PARAMETERS

23.4.2009

The part that only the administrator can modify is static data. It includes information about the computer system and installed software. Typically only the static data is stored persistently by HAC to a local file.The part the HAC may modify by itself is dynamic data. It includes observational information about the status and health of each element in the system.

2.4. SERVICE PARAMETERS

The parameters are in the following location in the Microsoft Windows registry: HKEY_LOCAL_MACHINE\SOFTWARE\WICOM\HAC_<INSTANCE_NAME>.

Note the following about the registry parameters:

The registry key above is used by a HAC instance with the Microsoft Windows service name HAC_<HAC INSTANCE NAME>.The WICOM and HAC_<HAC INSTANCE NAME> keys are generated when the HAC instance is initialized. The registry entries are created and initialized with default values when the HAC instance is initialized.If a registry entry is missing, HAC creates it with the default value when it starts up. Thus, you may reset any entry value back to the default value by deleting the corresponding entry and restarting the HAC instance.The default values should be appropriate, so change them only if necessary.

AlarmServers => Defines the alarm server addresses in the format HOST:PORT (for example 10.0.0.5:21013). Entering multiple alternative alarm server addresses can be done by separating the addresses with semicolon (“;”) character (for example 10.0.0.5:21013;10.0.0.6:21013).

ConfigDataPollInterval => Defines the polling interval in milliseconds how often HAC checks for the system model if the system model data is initially missing.

EnableHTTPAlarms => Defines whether XML alarms are sent over the HTTP protocol to the configured alarm servers. 0 = no, 1 = yes. If no, the XML alarms are written only to local alarm log files.

LogLevel => Defines the level of trace event logging. Selecting a higher level causes extra load. High logging levels rapidly generate large amounts of log data. It is recommended to run HAC in the log level 1. 0 = errors only, 1 = warnings, 2 = informational, 3 = trace, 4 = full trace for debugging.

MakeDiagnostics => Defines whether runtime diagnostics is generated and included in the element information. 0 = no, 1 = yes.

StabilizationPeriod => Specifies the time period in seconds which after an unmodified system is considered to be stable. See also parameters UnstableManagementCycleInterval and StableManagementCycleInterval below.

SystemConfigurationPath => Path to the system model file. Relative paths start from the working directory of the instance process (which is normally HAC/bin).


ADMINISTRATION GUIDE2.5. SERVICE APPLICATION INTERFACES

23.4.2009

UnstableManagementCycleInterval => Defines the polling interval of the system model in seconds between management rounds if the system is unstable.

StableManagementCycleInterval => Defines the polling interval time of the system model if the system is stable.

SystemInfo => A copy of the last valid static system model. HAC uses this as a backup for the system model data in case the system model file is lost or corrupted.

QuitInterval => Defines how often HAC restarts itself. This parameter is useful if HAC itself needs to be restarted periodically for internal clean-up purposes. Note that the HAC service's restart option in Windows' Services control panel should be set to automatically restart (default) HAC. The value is in hours. 0 = no scheduled restarts (default).

2.5. SERVICE APPLICATION INTERFACES

HAC monitors and controls system components (like application processes and web sites) via its service application interfaces. The interface consists of various monitors and controllers useful for each target system component type.

2.5.1. WINDOWS PROCESS

Windows processes are service applications that correspond to an executable file and a Windows process launched from it.

When starting a process, HAC also issues the configured command line parameters for the executable. Processes are stopped by simply terminating them, except for application processes, where HAC first attempts a graceful shutdown using a proprietary mechanism. For these applications, process termination is used only as the last resort.

By default, HAC starts processes as the user it itself is running unless otherwise configured in the process controller in the system model.

2.5.2. WINDOWS SERVICE

Windows Services are service applications that correspond to a Windows Service. HAC monitors and controls these services through Microsoft Windows Service Control Manager.

If a graceful shut down of a Windows Service fails (that is, it does not respond to Stop command before a timeout), HAC terminates the associated process as the last resort.

2.5.3. WEB SERVER MONITORING

Web servers correspond to a HTTP-server web site. Web server status and health is monitored primarily by using the HTTP GET method on a URL provided in the system model. In addition to the HTTP monitoring, the Microsoft IIS sites are controlled and monitored via the Microsoft IIS metabase.


ADMINISTRATION GUIDE2.5.4. SHELL MONITOR AND CONTROLLER

23.4.2009

2.5.4. SHELL MONITOR AND CONTROLLER

Shell monitor and controller are used to integrate services that are monitored and/or controlled via command line interface. These are the primary means for adding the custom monitoring and controlling mechanisms to HAC:

Shell Monitor => Uses the target string to generate the Microsoft Windows command line commands which monitor the associated system component.Shell Controller => Uses the appropriate command string to control the system component.

When monitoring a system component, HAC executes the command lines generated by Shell Monitor using the command parameter status first, and then (depending on the status return value) either health_active (for the system components that should be active) or health_inactive (for the system components that should be inactive).

The target string in Shell Monitor is used in the following way: <TargetString> <Command>. The command parameter and the expected return values from the command line call are the following:

Expected return values from command line with the command parameter status:

0 unknown1 inactive2 active3 standby4 activating5 inactivating6 resetting7 standing by8 partially active

Expected return values from command line with command parameters health_active and health_inactive:

0 unknown1 normal2 failed3 near failure

Since no third-party process is likely to be compatible with the calls listed above, it is recommended to create an adapter (such as a Visual Basic script or a batch file) that handles the actual command execution and transforms the actions and results to the defined form. It is convenient to place these scripts into the HAC subdirectory HAC/bin/script.

For example, MS SQL Server can be managed by using Shell Monitor and Shell Controller. Do this by creating a Visual Basic script called HAC/bin/sqlserver.vbs which accepts the parameters listed above and returns the listed result codes. It would issue calls to the SQL Server command line utility (SCM) to actually carry out the monitoring tasks. For health monitoring the Visual Basic script could call an SQL script doing some basic database manipulation tests (for example, create a test


ADMINISTRATION GUIDE2.6. EXTERNAL ALARM INTERFACE

23.4.2009

table, insert a row, select the row and then drop the table). The success of the test script shows the health of the database. Also more elaborate testing might be included.

Shell Monitor of the element would then be configured with the target string cscript script/sqlserver.vbs. When the SQL Server element is monitored, HAC issues a command line call cscript script/sqlserver.vbs status. That would start SQL Server and return the status of the database as the return value. If the status is for example active, HAC issues a command line call cscript script/sqlserver.vbs health_active. That would return the health of the running database.

The command lines are executed in the HAC instances process environment and thus, they inherit environment variables from the HAC process. Absolute and relative paths are allowed. Default working directory is the directory containing the HAC executable (HAC/bin).

2.6. EXTERNAL ALARM INTERFACE

This section describes the interface which HAC uses for describing and sending alarms to a network management system.

2.6.1. Alarm format (page 11)2.6.2. Transportation methods (page 13)2.6.3. HAC alarms (page 13)

See also the section 5. Alarm Server (page 45).

2.6.1. ALARM FORMAT

The alarms are in the following XML-like format:

<ALARM NAME=“alarm name“ SEVERITY=“alarm severity“ TIME=“alarm timestamp“>

<HOST>name of the host running the program generating the alarm</HOST> <PROCESS>name of the program generating the alarm</PROCESS> <INSTANCE>name or ID of the generating program instance</INSTANCE> <REASON>alarm reason string</REASON> <DESC>alarm description for humans</DESC> <RELATES>an entity which is related to the alarm</RELATES> <DATA>additional alarm data</DATA>

</ALARM>

All alarms have at least a name, severity and timestamp. The severity levels are exclusive: critical takes precedence over major, major takes precedence over minor, and minor takes precedence over notification. Exception to this precedence order is an alarm cancellation with a notification alarm. Sending duplicate alarms is allowed, but sending frequent duplicates should be avoided for performance reasons.


ADMINISTRATION GUIDE2.6.1. ALARM FORMAT

23.4.2009

An alarm may have the following fields:

TIMESTAMP Mandatory date and time of the log entry or event in the format YYYY-MM-DD hh:mm:ss zone (24 h time format). The time zone code is optional. The missing zone implies the local zone. The time zone code follows the ISO 8601 standard or +/-N hours from GMT.

SEVERITY Mandatory alarm level. The following values are in use:CRITICAL Indicates a severe service-affecting condition which requires immediate

corrective action.MAJOR Indicates such a failure in a major redundant service that a further failure

would create a critical condition. These problems may require immediate attention to restore or maintain the system capability.

MINOR Indicates problems which do not have a serious effect on the service to customers. They may also be service problems that are not essential to the primary operation.

NOTIFY Used for cancelling alarms implicitly by notifying that a certain feature is functioning properly. For example, if the description is the name of the alarm with the suffix OK (for example CONFIG OK), the corresponding raised alarm should be cancelled.

PROCESS Optional name and version of the process generating the entry. This field can be used to differentiate alarms from various sources.

NAME Mandatory alarm name. A short code for the process feature causing the alarm. Common features could be INIT for the process initialisation and CONFIG for the process configuration. The alarm name is a string which should contain only alphanumeric characters ([A..Z, 0..9]), and should be interpreted case-insensitively.

REASON A short descriptive alarm reason (for example disk full) that can be easily parsed programmatically. This field should be interpreted case-insensitively.

HOST Optional name of the host generating the entry. A DNS or Netbios name is preferred. An IP address can also be used if it uniquely identifies the specific host.

INSTANCE Optional name or ID of the process instance. This should be used if a host runs more that one instance of the same process for example for different customers. The instance could be the customer name.

DESC Optional textual description of the event.RELATES Optional name of an alarm-related entity. For example, the name of the

disk which is full.DATA Optional additional runtime data related to the alarm. For example,

problematic data structure contents encoded into a string.


ADMINISTRATION GUIDE2.6.2. TRANSPORTATION METHODS

23.4.2009

2.6.2. TRANSPORTATION METHODS

HAC supports two methods for transporting the alarms to a network management system: a local alarm log file and HTTP. The used method can be configured for each HAC instance separately. Both methods use the same alarm format.

To avoid resending the alarm continuously, HAC maintains an internal alarm repository (a list of current alarms), and an alarm is sent only if it is new or its severity is changed. Furthermore, if HAC is unable to send an alarm to any of the destinations, it resends the status of all its alarms (including the cancelled alarms) once the alarm destination is available again. In addition, a HAC instance may be requested to resend all its alarms from the HAC user interface (IA).

2.6.2.1. ALARM LOG FILE

If no alarm servers are defined and enabled, the alarms are written into a local alarm log file. An alarm log file is separate from the trace log files.

The alarm log contains the generated alarms in a sequential order. New alarms are appended to the file. The file is closed by HAC after writing each alarm. If a file is deleted or moved away, a new one is automatically created when the next alarm is written. This allows the user of the file to collect the file intact almost at any time.

The alarm log file name is SAP BCM HAC_<instance name>_<date>_alarms.log. The instance name is the HAC instance name and the date is in the format YYYYMMDD. A new alarm log file is generated each day if there are new alarms.

2.6.2.2. HTTP ALARM DESTINATIONS

If the HAC instance has alarm servers defined and enabled, it sends the alarms to one of the servers defined in the list. If an alarm server fails, HAC tries the next one in the list in a round-robin fashion.

The alarm is sent in an HTTP POST message to the URL http://AlarmServer/alarm.

2.6.3. HAC ALARMS

HAC may generate several different alarms. It also handles cancelling alarms when needed. Some alarms relate to the HAC instance process itself and some to the system model managed by HAC.

Each alarm includes the following data regardless of its type:

TIME => The data and time. Does not contain the time zone.HOST => The local host’s Netbios name.PROCESS => SAP BCM HAC 2.0. The version number may vary.INSTANCE => The name of the HAC instance (node).

HAC sends the following alarms:


ADMINISTRATION GUIDE2.6.3.1. INITIALISATION

23.4.2009

2.6.3.1. Initialisation (page 14)2.6.3.2. Configuration (page 14)2.6.3.3. Process (page 14)2.6.3.4. Watchdog (page 15)2.6.3.5. Interhac (page 15)2.6.3.6. Elements (page 15)2.6.3.7. Redundancy (page 16)

2.6.3.1. INITIALISATION

The following alarms are related to HAC instance initialisation:

INIT OK NOTIFY The HAC process was successfully initialised.INIT failed MAJOR The HAC process has failed to initialise itself and is unable

to operate. An automatic restart is likely to be successful.INIT failed CRITICAL The HAC process has failed to initialise itself and is unable

to operate. The problem is likely to be persistent.

2.6.3.2. CONFIGURATION

The following alarms are related to HAC instance configuration:

CONFIG OK NOTIFY The HAC process was successfully configured.Minor parameter error

MINOR The related entity is the parameter name. An error in the contents of a HAC instance parameter (or the HAC process is unable to attain the parameters). The default value is used instead.

Fatal parameter error MAJOR The related entity is the parameter name. A fatal error in the HAC instance parameters.

Missing system info MAJOR The HAC process is unable to attain the system model data. The searched locations are given in the relates-field.

Invalid system info MAJOR The attained system model data is invalid. The system info source is given in the relates-field.

Fatal configuration error

MAJOR An unexpected error during configuration.

No configuration data MAJOR Failed to find system model data.

2.6.3.3. PROCESS

The following alarms are related to HAC instance processes (runtime):

PROCESS OK NOTIFY No process errors within the defined time period.


ADMINISTRATION GUIDE2.6.3.4. WATCHDOG

23.4.2009

2.6.3.4. WATCHDOG

The following alarms are related to IPMI reset watchdog:

WATCHDOG OK NOTIFY No errors related to the watchdog feature.Watchdog management failed

MINOR An error occurred during general watchdog management.

Failed to set IPMI watchdog

MINOR An error occurred when setting the watchdog mode.

Failed to set IPMI watchdog

MAJOR Failed to set the watchdog into one of the active modes. The watchdog may not be able to reboot the device if HAC fails.

2.6.3.5. INTERHAC

The following alarms are related to inter-HAC communications:

INTERHAC OK NOTIFY All HAC nodes connected successfully.IP address binding failed MINOR HAC is unable to listen to the failed address for inter-

HAC messages. The failed address is in relates-field.Unable to bind any IP address

MAJOR The related entity is the attempted addresses. HAC is unable to listen to any configured address for inter-HAC messages.

2.6.3.6. ELEMENTS

The following alarms are related to system model elements (for example, the element health may have failed or be near failure), nn is the element ID and the related entity is the element name and ID):

Minor reconfiguration error

MINOR An error occurred when reconfiguring HAC with the new system model data.

Minor internal error MINOR A non-fatal error occurred. The error message is displayed in the optional DATA field.

Fatal internal error MINOR A fatal error occurred. HAC was hard-reset. The error message is displayed in the optional DATA field.

Persistent internal error

MAJOR Errors have occurred very frequently recently. The last error message is displayed in the optional DATA field.

ELEMENTnn OK NOTIFY The element has no alarms set.Element failed MINOR/

MAJOR/CRITICAL

The element health in the system model has changed to failed. The actual severity depends on the element. The reason is displayed in the optional DATA field.


ADMINISTRATION GUIDE2.6.3.7. REDUNDANCY

23.4.2009

2.6.3.7. REDUNDANCY

The following alarms are related to problems with redundant system model elements, nn is the element ID and the related entity is the name and ID of the redundant system:

REDUNDANCYnn OK NOTIFY The redundant instance has no alarms set.Currently out of eligible instances

MINOR Not enough active and eligible instances. An automatic recovery is expected to occur soon.

Too many failed instances

MAJOR Too many failed instances. An automatic recovery may take some time.

Persistently out of eligible instances

CRITICAL All instances of a redundant system have failed and an automatic recovery has already failed several times.

Element nearly failed MINOR/MAJOR

The element health in the system model has changed to near failure. The actual severity depends on the element. The reason is displayed in the optional DATA field.

Failed to inactivate failed element

MAJOR Failed persistently to inactivate the related failed system component.

Failed to inactivate failed redundant element

MAJOR Failed persistently to inactivate the failed system component which is part of a redundant system. This may result in problems during the automatic fail-over to another redundant element.


ADMINISTRATION GUIDE3. VIRTUAL UNIT ADMINISTRATOR (VUA)

23.4.2009

3. VIRTUAL UNIT ADMINISTRATOR (VUA)

NOTE: See the notes and limitations in the section 1. Introduction (page 1) before you start using the application.

Virtual Unit Administrator (VUA) is the application for installing and managing the server software on each particular server. It is used for deploying virtual units (VU) and installing and upgrading the software in the virtual units. VUA needs to be run locally on each server where it manages the virtual units and software packages.


3.1. Installing and starting VUA (page 17)3.2. Using graphical user interface (GUI) (page 18)3.3. Adding virtual units (page 21)3.4. Adding software components (page 22)3.5. Adding hotfixes (page 23)3.6. Removing hotfixes (page 24)3.7. Changing base installation (page 26)3.8. Upgrading software components (page 27)3.9. Updating configuration variables (page 28)3.10. Removing virtual units (page 28)3.11. Removing software components (page 28)3.12. Committing all changes (page 29)3.13. Refreshing system view and clearing changes (page 29)3.14. Clearing log view and changing logging level (page 29)3.15. Using command line options (page 29)

3.1. INSTALLING AND STARTING VUA

The VUA application is installed from the Virtual Unit Administrator package. By default, the VUA application is installed into directory C:\Program Files\SAP\BCM\vua and shortcuts to the executable are created to Start-menu and on desktop.

During the start-up, the VUA application scans two directories for deployed virtual units and available software packages. Virtual units are expected to be deployed under a root directory for virtual units (defaults to C:\Program Files\SAP\BCM\VU ) and the software packages under installation media directory (defaults to C:\Program Files\SAP\BCM\Install).

To change the above directories use the commands:

Tools > Set Install Media Directory for installation media directory Tools > Set Home Directory for the root directory for virtual units.


ADMINISTRATION GUIDE3.2. USING GRAPHICAL USER INTERFACE (GUI)

23.4.2009

By default, these changes are temporary and you loose them when you close the application. Save the changed values as new defaults to the user’s registry with the function Tools > Save Settings As Default.

NOTE: Instead of having a copy of all software packages on each server, you may set the install media directory to point to a network share containing the software packages. Using a shared directory for install media saves the trouble of maintaining a consistent copy of all software packages and their upgrades on all servers separately.

3.2. USING GRAPHICAL USER INTERFACE (GUI)

The user interface has the following parts:

1. Menu bar => Menus for managing virtual units (see the list below). Usually the functions in the menu bar are also available in the context sensitive pop-up menu which appears by right-clicking an item in the system view. Most functions also have a keyboard shortcut.

2. System view => Displays a tree structure containing the virtual units and software components in the host system.

3. Properties view => Displays detailed information about the item you have selected in the system view.

4. Log view => Displays the trace log entries. The application saves the same information into the VUA.log file which is created into the working directory. Clearing log view and changing logging level

5. Status bar => Displays various messages related to the software status and usage. It may also display context sensitive help text.



23.4.2009

The menu bar has the following menus:

File New Empty Host System => Clears any existing virtual units from the system view. For example, use the function to create virtual unit definitions off-line. These definitions can be exported into a file which is used later in the target host system.Import Host System... => Used for importing a host definition file which has been previously exported from the application. The virtual units and software components defined in the file are displayed in the system view and can be applied to the local server.Export Host System... => Used for exporting the current host system to a host definition file.Import Virtual Unit... => Used for importing a definition file of an individual virtual unit. The virtual unit is displayed in the system view with the existing virtual units.Export Virtual Unit... => Used for exporting the selected individual virtual unit to a definition file.



23.4.2009

Exit => Closes the application.Edit

Delete => Deletes the selected item or marks the item to be deleted later if it cannot be deleted immediately.

View Refresh All => Scans the entire local host system for deployed virtual units and available installation packages. You can also use the function for clearing all changes that you have not saved or applied yet.Clear Log View => Clears the log view. The function does not affect the VUA.log file.

Software Add Virtual Unit... => Adds a new virtual unit into the host system.Add Software... => Adds new software to the selected virtual unit. Opens the dialog window for adding software components to the selected virtual unit. The dialog window lists the available software packages in the base installation of the virtual unit.Edit Virtual Unit => Displays the variables of the selected virtual unit in the editing mode.Mark for Upgrade => Marks the selected item to be upgraded. The application uses the current base installation in the upgrade. Use this to apply changes you have made to the software package in the current base installation of the selected software.Apply Changes To Host => Applies the changes in the selected virtual unit to the host system. If the virtual unit is new or it has new software, installation procedures are run. Also deferred upgrades and removals are applied accordingly.Apply All Changes To Host => Updates the changes in all virtual units in the system view to the host system.

Tools Change Log Detail Level => Changes the logging level. The function affects the VUA.log file and the log view. The default value is Include basics, which means that errors and basic information are collected. Use the Include debug messages value only if you need fully detailed trace information.Set Install Media Directory => Change the directory which contains all software packages. Opens the dialog window for specifying the new installation media directory.Set Home Directory => Change the root directory containing all virtual units. Opens the dialog window for specifying the new directory. If you change the directory, it affects the views in the application (not the existing virtual units in either of the directories).Save Settings As Default => Saves the directory settings and the current main window size to the registry. The new settings are used as defaults when you restart VUA next time.Add Hotfixes To Base Installation… => Adds hotfix packages to the selected base installation.Remove Hotfixes From Base Installation… => Removes hotfix packages from the selected base installation.


ADMINISTRATION GUIDE3.3. ADDING VIRTUAL UNITS

23.4.2009

3.3. ADDING VIRTUAL UNITS

Perform the procedure as follows:

1. Select the target system (for example Default System).2. Select Add Virtual Unit....3. Enter the virtual unit name and select the base installation from the given list to be used for

the new virtual unit. A base installation contains the entire software related to a specific version.

4. Click the OK button.5. To commit the installation of the virtual unit and the selected software, select the virtual unit

and Apply Changes To Host. Note that it may take several minutes to complete the operation.


ADMINISTRATION GUIDE3.4. ADDING SOFTWARE COMPONENTS

23.4.2009

3.4. ADDING SOFTWARE COMPONENTS

Perform the procedure in the following way:

1. Select the virtual unit and the options Software -Add Software…. The Choose software dialog window appears.

2. Select the software components to be added to the virtual unit and click the OK button. A list of configuration variables appears. The contents of the variable list depend on the selected software components.

3. Select the virtual unit and enter configuration variable values.4. Click the Save Variables button. The Revert button returns the saved values if you make an

error when you enter the values.5. To commit the installation of the new software, select the virtual unit and Apply Changes To

Host. Note that it may take several minutes to complete the operation.


ADMINISTRATION GUIDE3.5. ADDING HOTFIXES

23.4.2009

3.5. ADDING HOTFIXES

A hotfix package is installed in two steps.

1. 3.5.1. Adding hotfixes to base installation (page 23).2. 3.5.2. Adding hotfixes to software component (page 23).

3.5.1. ADDING HOTFIXES TO BASE INSTALLATION

Add the hotfix package to the base installation in the following way:

1. Select Tools > Add Hotfixes To Base Installation… A dialog window appears for selecting the base installation.

2. Select the base installation and click the OK button. A dialog window appears for selecting the hotfix packages.

3. The dialog shows a list of hotfix packages that are found from the hotfixes subdirectory of installation media directory. Click the … button to change the directory used for searching the hotfix packages.

4. Click the Apply button to add the selected hotfix packages to the base installation.

3.5.2. ADDING HOTFIXES TO SOFTWARE COMPONENT


1. Select the software component and Add Hotfixes…. The Add hotfixes to software dialog window appears.


ADMINISTRATION GUIDE3.6. REMOVING HOTFIXES

23.4.2009

2. Select the hotfix and click the OK button.3. To commit the changes, select the virtual unit and Apply Changes To Host.

3.6. REMOVING HOTFIXES

NOTE: When a hotfix package is removed from a base installation, it is not removed from the software components it has been added to. See the section 3.6.2. Removing hotfix from software component (page 25) if you need to remove the hotfix from the software components as well.


ADMINISTRATION GUIDE3.6.1. REMOVING HOTFIXES FROM BASE INSTALLATION

23.4.2009

3.6.1. REMOVING HOTFIXES FROM BASE INSTALLATION


1. Select Tools > Remove Hotfixes From Base Installation… A dialog window appears for selecting the base installation.

2. Select the base installation and click the OK button. A dialog window appears for selecting the hotfix packages.

3. Click the Apply button to remove the selected hotfix packages from the base installation.

3.6.2. REMOVING HOTFIX FROM SOFTWARE COMPONENT


1. Select the hotfix and Remove Hotfix. This can be done also by selecting the hotfix and pressing Ctrl+Delete.


ADMINISTRATION GUIDE3.7. CHANGING BASE INSTALLATION

23.4.2009

2. To commit the changes, select the virtual unit and Apply Changes To Host.

3.7. CHANGING BASE INSTALLATION

All software packages that belong to a certain release version are delivered in the same base installation package. You can upgrade a virtual unit to a new release version by changing its base installation and confirming the changes.


1. Select the virtual unit and Change Base Installation.... A dialog window appears for selecting the new base installation.

2. Select the base installation and click the OK button. All software components in the virtual unit are marked to be upgraded.


ADMINISTRATION GUIDE3.8. UPGRADING SOFTWARE COMPONENTS

23.4.2009

3. To commit the changes Apply Changes To Host. Note that it may take several minutes to complete the operation.

3.8. UPGRADING SOFTWARE COMPONENTS

NOTE: The software component marked to be upgraded use the same base installation package while updating the files and registry entries. This is useful when you want to apply new customisations made to the base installation package.


1. Start with either of the following steps:Select an individual software component and select Upgrade Software. The software component is marked to be upgraded.Select a virtual unit and select Upgrade All Software. All software components in the virtual unit are marked to be upgraded.


ADMINISTRATION GUIDE3.9. UPDATING CONFIGURATION VARIABLES

23.4.2009

2. Select Apply Changes To Host for the virtual unit to confirm the changes and update the files and registry entries related to the software components.

3.9. UPDATING CONFIGURATION VARIABLES

By default the list of configuration variables for the virtual unit is read-only, but you can also edit the variables.

Select the virtual unit and select Edit Variables. Click the Save Variables button to save the changes and select Apply Changes To Host to confirm the changes.

3.10. REMOVING VIRTUAL UNITS

Select the virtual unit and Remove Virtual Unit to mark it to be removed.

Select Apply Changes To Host for the virtual unit to confirm the changes and remove the files and registry entries related to the software components in the virtual unit. The application removes also the home directory of the virtual unit.

3.11. REMOVING SOFTWARE COMPONENTS

Select the software component and Remove Software to mark it to be removed.

Select Apply Changes To Host for the software component to confirm the changes and remove the files and registry entries related to the software component. The application removes only files and registry entries which are not shared with other software components.


ADMINISTRATION GUIDE3.12. COMMITTING ALL CHANGES

23.4.2009

3.12. COMMITTING ALL CHANGES

If you have modified multiple virtual units (that is, they are upgraded to a new version), you can confirm all changes with a single function (Software > Apply All Changes To Host or select host and Apply All Changes To Host).

3.13. REFRESHING SYSTEM VIEW AND CLEARING CHANGES

Select View > Refresh All to scan the entire local host system for deployed virtual units and available software packages. You can also use the function for clearing all changes that you have not yet committed.

3.14. CLEARING LOG VIEW AND CHANGING LOGGING LEVEL

Select View > Clear Log View or Tools > Change Log Detail Level. Both affect the log view, and the latter affect also the VUA.log.

The default value for the logging level is Include basics, which means that errors and basic information are collected. Use the Include debug messages value only if you need fully detailed trace information.

3.15. USING COMMAND LINE OPTIONS

You can also run VUA from the command line which allows scripting its tasks. Since VUA is ran on each server, it may be useful to script mass updates on the system.

VUA command line syntax is:

VUA [-ah < CONFIG FILE >] [-av <CONFIG FILE>] [-ev <VIRTUAL UNIT>] [-o <FILE NAME>] [-u < CONFIG FILE >] –b –d –eh –h


ADMINISTRATION GUIDE3.15. USING COMMAND LINE OPTIONS

23.4.2009

Description of command line options (you can use short or long style):

SHORT LONG DESCRIPTION-ah --addHost <CONFIG FILE> Delete all existing virtual units and add virtual

units according to the information in given CONFIG FILE.

-av --addVU <CONFIG FILE> Add virtual units according to the information in given CONFIG FILE.

-ev --exportVU <VIRTUAL UNIT>

Export information about the given VIRTUAL UNIT to the specified output file (-o <FILE NAME>).

-o --outputFile <FILE NAME> Specify output file path.-u --upgrade <CONFIG FILE> Upgrade the system according to the information

in given CONFIG FILE.-b --batchMode Suppress dialog boxes while processing command

line options.-d --deleteAll Delete all existing virtual units.-eh --exportHost Detect all virtual units and export host system

information to the specified file (-o <FILE NAME>).

-h --help Display help text dialog box and exit.

You can also use slash to specify an option. Option names are case insensitive.

For example, you can use any of the following commands to detect all virtual units and export host system information into a file mysystem.xml:

VUA -eh mysystem.xml

VUA /EH mysystem.xml

VUA –exportHost mysystem.xml


ADMINISTRATION GUIDE4. INFRASTRUCTUE ADMINISTRATOR (IA)

23.4.2009

4. INFRASTRUCTUE ADMINISTRATOR (IA)Infrastructue Administrator (IA) is the application running on one or more administration workstations. The system administrators use it for viewing and managing the system status as seen by each of the connected HAC instances. It also is the user interface for creating and managing the system model, see the chapter 6. HAC system model (page 57).


4.1. Installing and starting IA (page 31)4.2. Using graphical user interface (GUI) (page 31)4.3. Using system model (page 34)4.4. Using IA products (page 37)

4.1. INSTALLING AND STARTING IA

The Infrastructue Administrator application is included in the Infrastructure Administrator installation package. By default the application is installed into the directory C:\Program Files\SAP\BCM\ia. Start the application by running the executable IA.exe file from the directory or from short-cuts created by the installation package to Start-menu or desktop.

When the application starts up, it is in the off-line mode, which means that it is not actively communicating with the other HAC nodes in the system. You can make any structural changes into the system model only in the off-line mode. In this mode you can also add, remove, rearrange and reconfigure the elements in the system model.

In the online mode the application actively tries to communicate with all HAC nodes in the system model. You cannot make structural changes or re-configurations to the system model while in online mode. In this mode you can perform only various online actions related to elements, such as change role, request diagnostics or initiate switch-over of an element in the system model. Changes made to system model in online mode are not automatically stored persistently. Thus, if IA or a HAC instance is restarted and read the system model from disk, some changes may be reverted. To make online changes persistent, you must select File > Save in IA. Saving the system model in IA automatically updates the version number in the system model, distributes the new model to all HAC instances. HACs will then store the new system model to disk on each server.

You can change the mode by using the functions Monitoring > Connect and Monitoring > Go Offline. The status bar indicates the current mode.

4.2. USING GRAPHICAL USER INTERFACE (GUI)

The user interface has the following parts:

1. Menu bar => The functions for managing the system status (see the list below). Usually the same functions are also available in the pop-up menu which appears by right-clicking in the system model view.



23.4.2009

2. System model view => Displays the system model as a tree structure. Structural changes to the system model in the off-line mode are made in this view. Also various online actions related to elements can be performed in this view. See the section 4.3. Using system model (page 34). The upper combo box enables selecting the tree structure displayed.

3. Properties view => Displays detailed information about the item you have selected in the system model view. It is also used for making most of the changes to the element properties in the off-line mode. The view may also contain any number of monitoring views as separate tabs.

4. Events view => Displays notes about events that have occurred during the current session. You can clear the view manually. The view may also be hidden.

5. Status bar => Displays the IA status and usage information.

The menu bar has the following menu functions:

File New => Creates a new empty system model.Open... => Opens a selected IA system model file.



23.4.2009

Save => Saves changes in the system model and monitoring views into the current IA file.Save As... => Saves changes into a different file.Import System Model... => Imports the system model from a HAC system model file (typically structure.xml).Export System Model... => Exports the IA system model into a HAC system model file (typically structure.xml).Exit => Closes IA.

Edit => The effect of these functions depend on the selected items or the clipboard contents.Copy => Copies the selected text or the XML description of the selected element to the clipboard.Paste => Pastes the text to selected editing field or adds a new element as a component to the selected element (if the copied item is a valid XML element description).

Monitoring Connect => Enters the online mode by connecting to all HACs in the system.Go Offline => Enters the off-line mode.Add New Monitoring View... => Adds a new monitoring view.Remove Monitoring View => Removes the selected monitoring view.Rename Monitoring View => Renames the selected monitoring view.Set Monitoring View Background... => Opens the dialog window for selecting a background picture for the selected monitoring view. For example, this picture can be a site map or a layout drawing of the computer room.Tear Off Monitoring View => Opens the selected monitoring view in a new window. By default the monitoring views are displayed as separate tabs in the properties view. When you close the monitoring window, the monitoring view is displayed as a tab again.

Views Show Model View => Displays the system model view.Show Events View => Displays the events view.Toggle Properties View => Opens the element properties view into a separate window or closes the separate properties window if it is already open.Lock Views => Locks IA so that you can only monitor the system. You cannot make any changes before you unlock the application. Use this to prevent accidental changes to the system while monitoring the system.Unlock Views => Unlocks the application.Clear Events View => Clears the events view.Set Events Mask => Allows you to select the types of events displayed in the events view.Save Settings => Saves the current window position and other settings to be used as your default values. It also saves the current system model file as the default file to be opened when you start a new session.


ADMINISTRATION GUIDE4.3. USING SYSTEM MODEL

23.4.2009

4.3. USING SYSTEM MODEL

This section describes the IA application’s system mode in the following sections:

4.3.1. System element (page 34)4.3.2. HAC Nodes (page 34)4.3.3. Virtual units (page 35)4.3.4. Other software (page 36)4.3.5. Monitoring views (page 36)

4.3.1. SYSTEM ELEMENT

The top-level element in the system model view tree structure is the HA system element which represents the entire system. All other elements in the system are components of the HA system element:

HA system element (by default The System)HAC nodes => All HAC nodes. Typically each server running HAC has an entry here. The element name must match the node name which was given as its HAC node name when the infrastructure software was installed onto the respective server.Virtual units => All standard virtual units which HAC manages. Standard virtual units have identical or similar instances on all nodes.Other redundant systems => These systems are similar to virtual units, but they can be special arrangements of heterogeneous instances.

4.3.2. HAC NODES

Add all nodes with their correct IP addresses to the system model, and save the model into an IA file.

After all nodes have been added to the system model, export the model for HACs by selecting the function File > Export System Model... and save it into a .xml file. Restart each HAC service (in the Microsoft Windows Services control panel) to make sure that they start to use this new system model file.


ADMINISTRATION GUIDE4.3.3. VIRTUAL UNITS

23.4.2009

If no problems occur, you should see all nodes in normal health when you enter the online mode (Monitoring > Connect).

If problems occur, correct the errors, save and export the system model again. Make sure that HAC services are running on all nodes.

Once you have successfully connected to all HAC nodes, you can make and distribute changes to the system model to other HACs. After changes, just select File > Save in IA. Saving the system model in IA automatically updates the version number in the system model, distributes the new model to all HAC instances. HACs will then store the new system model to disk on each server and take it into use.

4.3.3. VIRTUAL UNITS

Right-click a virtual unit in the system model view and a pop-up menu with a list of predefined virtual unit products appears.

For the description of virtual unit products, see the table in the section 4.4.2. Virtual Unit Products (page 38).


ADMINISTRATION GUIDE4.3.4. OTHER SOFTWARE

23.4.2009

Virtual unit elements have Components subsection which is the template for creating virtual unit’s instances. The top-level element in this template is a service element, which may contain any number of other component elements arranged in the relevant order. When you add or update a virtual unit instance on a host, the Components template is used for creating the instance elements onto the selected host.

A virtual unit has instances on the hosts listed in the Hosts subsection. You can add new hosts to the list and remove existing hosts from it.

If the Components template is changed, you can reapply the changes to all instances by selecting Synchronize Instances from the pop-up menu which appears when you right-click the virtual unit.

You can use variables in any fields in the Components template. Each variable is denoted by the variable name between two dollar signs. The IA application replaces these variables with actual string values when creating new or updating existing instances. The following variables are available:

$HOST_NAME$ => Replaced with the node name hosting the elements in the instance.$VU_NAME$ => Replaced with the virtual unit name.$BCM_HOME$ => Replaced with node’s home path settings (see Variables tab in node’s Element Properties view). Defaults to C:\Program Files\SAP\BCM.$HOST_LOGS_PATH$ => Replaced with node’s Directory for Logs path settings (see Variables tab in node’s Element Properties view). Defaults to refer $BCM_HOME$.$VU_HOME$ => Replaced with virtual unit instance’s home directory on the node. This is actually a short-cut for and equals to $BCM_HOME$\VU\$VU_NAME$.$VU_LOG_PATH$ => Replaced with virtual unit instance’s logs directory on the node. By default, this equals to $HOST_LOGS_PATH$\VU\$VU_NAME$\logs.

4.3.4. OTHER SOFTWARE

If you want HAC to control software that is not part of any virtual unit or redundant system, you should add appropriate software elements directly to the HAC node hosting the software.

For example, you may want to control VNC server software (which runs as Microsoft Windows service called VNC Server) via the IA application. In that case add a Windows Service Application product to the HAC nodes that host the VNC servers. When the IA asks the service name, enter VNC Server. After that the VNC server software is kept active by HAC if its role is defined to be active. You can shut it down by changing the role to inactive.

4.3.5. MONITORING VIEWS

In the Overview tab, the system can be monitored in a graphical view. You can additionally create one or several monitoring views that display the selected elements status:

HINT: Make each customer system a specific monitoring view and name it accordingly.

1. Select the Monitoring > Add New Monitoring View.... option


ADMINISTRATION GUIDE4.4. USING IA PRODUCTS

23.4.2009

2. Drag-and-drop the administration nodes, servers and redundancy groups in their places. The virtual units should be underneath the corresponding servers.

4.4. USING IA PRODUCTS

Products in IA are predefined templates for adding new elements into the system model. Some products describe a single element (such as a HAC node), whereas some products may describe more complex arrangements of elements (such as an entire virtual unit with related access point and software elements).

The adding procedure is context sensitive, and some products may be added to certain locations only. When building system model, IA will display only the suitable products for the given location.

When you instantiate a product, you are asked to fill in values for variables (such as the name for the new virtual unit and the related IP address). When you have added a product into the system model, the created elements do not retain the product relation.

Each product is described in a text file in the products subdirectory inside IA application directory. IA comes with a set of predefined products, but you can also create your own customised products.

The predefined products as well as instructions on building custom products are described below.

4.4.1. GENERIC PRODUCTS

These products specify commonly used elements.

PRODUCT NAME DESCRIPTION AND INCLUDED COMPONENTSHAC Node A computer system running HAC.Server without HAC A computer system or node that does not have HAC.Redundant System Element An element representing a group of equivalent redundant

instances.IP Service Access Point A reassignable IP address. Commonly used for virtual IP

addresses.Service Element An element representing a group of other elements managed as a

single unit.Windows Application with Shell Interface

A Microsoft Windows application with a command line interface.

Windows Application Process A Microsoft Windows application run and monitored as a regular process.

Windows Service Application A regular application run and monitored as a Microsoft Windows service.

Virtual Unit with Access Point

Includes component: Virtual IP address

Empty Virtual Unit Element An empty virtual unit.


ADMINISTRATION GUIDE4.4.2. VIRTUAL UNIT PRODUCTS

23.4.2009

4.4.2. VIRTUAL UNIT PRODUCTS

These products create full virtual units with predefined set of components. Components referred to with the name Wicom are intended for support of the software versions earlier than 6.0.

PRODUCT NAME DESCRIPTION AND INCLUDED COMPONENTSEmpty Virtual Unit Element Does not include componentsMicrosoft IIS site in Virtual Unit

Used with the Microsoft IIS Includes components: Virtual IP address, Microsoft web site

SAP BCM Communications Server Virtual Unit

Includes components virtual IP address, Message Cleaner, Message to Mail, Voice Mail Compress and UIMS.

SAP BCM Core Server Virtual Unit

Includes components Virtual IP address, CEM server and Call Dispatcher.

SAP BCM Data Collector Virtual Unit

Includes components virtual IP address and Data Collector module.

SAP BCM ETC Virtual Unit Includes components virtual IP address and External Terminal Controllor module.

SAP BCM H.323 Bridge Server Virtual Unit

Includes components virtual IP address, H.323 Bridge and H.323 Gatekeeper.

SAP BCM SIP Bridge Server Virtual Unit

Includes components virtual IP address and SIP Bridge.

SAP BCM SMS Server Virtual Unit

Includes components virtual IP address, SMS Engine and SMS to Message.

SAP BCM Web Server Virtual Unit

Includes components: Virtual IP address, SAP BCM Web Server

4.4.3. VIRTUAL UNIT COMPONENT PRODUCTS

These products create specify elements, which are intended to be added to Components section of an existing virtual units. They typically represent individual server processes.

PRODUCT NAME DESCRIPTIONSAP BCM Alarm Server Alarm server for detecting and communicationg of the system

malfunctions.SAP BCM Call Dispatcher Call Dispatcher server. Not to be used with versions earlier than

4.0 because their CEM server contains call dispatcher already.SAP BCM CEM Server CEM serverSAP BCM Chat Server For systems with chat channel configuration.SAP BCM Connection Server Connection server.SAP BCM Data Collector H.323 Bridge serverSAP BCM External Terminal Controller

H.323 Bridge server


ADMINISTRATION GUIDE4.4.4. OLD WICOM PRODUCTS

23.4.2009

4.4.4. OLD WICOM PRODUCTS

These products are intended for supporting of the software versions earlier than 6.0. They are intended to be added directly into a specific node. They typically represent individual server processes.

PRODUCT NAME DESCRIPTIONWicom BT TR2001 Gateway Includes Wicom BT TR2001 Gateway software as a Windows

serviceWicom BT TR2020 Gateway Includes Wicom BT TR2020 Gateway software as a Windows

serviceWicom NAT Server Wicom NAT ServerWicom NAT as Windows service

Wicom NAT as a Windows service

Wicom Instant Messaging Wicom the Instant Messaging service (UIMS)Wicom 4 CEM Server Application Server i.e. CEM server component from 4.

SAP BCM Federation Bridge Server

Federation Bridge Server

SAP BCM File Replication Server

File Replication Server

SAP BCM H.323 Gatekeeper H.323 Gatekeeper serverSAP BCM Media Routing Server

Media Routing Server (MRS) component

SAP BCM Message Cleaner Message CleanerSAP BCM Message to MailSAP BCM SIP Bridge SIP BridgeSAP BCM SMS Engine SMS EnginerSAP BCM SMS to Message Server

SMS to Message

SAP BCM Web Server Web ServerSAP BCM Voice Mail Compressor

The voicemail compressor server

PRODUCT NAME DESCRIPTION


ADMINISTRATION GUIDE4.4.5. SUPPORTED THIRD-PARTY PRODUCTS

23.4.2009

4.4.5. SUPPORTED THIRD-PARTY PRODUCTS

These products create specify elements, which are intended to be added directly into a specific node. They typically represent individual server processes.

PRODUCT NAME DESCRIPTIONMicrosoft IIS Microsoft Internet Information Server. Controls and monitors all Microsoft

IIS server services.Microsoft SQL Server

Microsoft SQL Server Windows services. The script\sqlserver.vbs file contains a Visual Basic (VB) script which controls and monitors an SQL server by using the Microsoft command line utility. There is also an SQL script for checking the health of an active database (script\health_check.sql). The VB script uses the health check automatically. Currently there is no product using this script, but you can use the generic shell product.

Microsoft IIS site in Virtual Unit

Virtual unit that includes component’s IP address and a single IIS site.

4.4.6. CUSTOMISED PRODUCTS

You can also create customised products that can be used along the standard products. You may create new products from scratch or using an existing product as a starting point.

The product files are located in the products directory. When starting IA application, it scans the directory for product files. Each product displayed in the pop-up menu is defined in a separate XML file in the directory.

An instance of a product is always a system model element or a number of elements arranged in a hierarchy. Single product has always only one element that is the top-level element for the product.

The main information categories in the product file are:

Product information List of product groups the product belongs toVariables asked from user when instantiating the productHAC system model element template


ADMINISTRATION GUIDE4.4.6. CUSTOMISED PRODUCTS

23.4.2009

To explain the format and syntax in more detail, below is an example of a product file:

Product information consists of the following fields

NAME: Name of the product as displayed in IA when selecting the product (see the picture below)DESCRIPTION: Free form description of the productVERSION: Free form version information about product fileGROUPS node contains a list of group names that the product is organized into when selecting a product in IA. The product is shown with all the listed groups. The above example



23.4.2009

product belongs to the groups All Products and Generic. See the picture below how the example product is displayed in IA.

The ELEMENT node is a template for the created system model element. The top-level element may contain any number of component elements. See the section 6. HAC system model (page 57) for more detailed information about the elements.

When you create a product instance in the IA application, it asks a value for each variable from user. Product may contain any number of variables to make it more generic and useful. IA replaces the variables with the given values in the ELEMENT template section when creating the element.

Variable definition consists of the following fields and subfields:

TAG: Variable nameTEXT: Text to be displayed when asking the user for value for the variable DEFAULT: Optional default value for the variableCHECKER: Optional automatic content check on the entered variable value. The following checker values are valid:

EXISTS => Check that the value is not empty.ISNUMERIC => Check that the value is numeric.ISIPADDRESS => Check that the value is a valid IP address in the format a.b.c.d.ISPORT => Check that the value is a valid IP port number.ISSUBNETMASK => Check that the value is a valid IP subnet mask in the format a.b.c.d.ISIPADDRESSANDPORT => Check that the value is a valid IP address and port in the format a.b.c.d:port.

You can use variables in the element template with the $variablename$ notation and the product instantiation replaces the variable values directly in the template. Previously asked variable values (in the current product instantiation) may be used for building default values for the subsequent variables.



23.4.2009

As element IDs you can use literal element IDs that IA offsets accordingly when the product is instantiated. Element IDs in the template are considered as relative IDs within the product and you may make references to the element IDs in the product.

If the product is instantiated into a node (a child or child of a child of a ComputerSystem element), a $HOSTING_NODE_NAME$ variable is set to the name of the ComputerSystem element. This allows making more sensible default values and templates.



23.4.2009


ADMINISTRATION GUIDE5. ALARM SERVER

23.4.2009

5. ALARM SERVERAlarm Server is the background application for converting and transferring alarms to third-party network management systems. It receives XML alarms from HAC nodes (or other applications), filters and converts them into SMS, e-mail and/or SNMP alarms towards predefined recipients.

See also the section 2.7. External alarm interface (page 10).


5.1. Installing and removing Alarm Server instances (page 45)5.2. Starting and stopping instances (page 46)5.3. Configuring Alarm Server (page 46)

5.1. INSTALLING AND REMOVING ALARM SERVER INSTANCES

Alarm Server service is installed from the Alarm Server package with VUA tool.

The directory contains the following files and subdirectories:

bin\alarmserver.exe => The executable file for the alarm server instance.etc\ => The directory for various alarm server configuration files.mib\wicom.mib => The Management Information Base (MIB) file for third-party SNMP management systems.

If you need to reinstall or reinitialise an alarm server instance manually, perform the following procedure in the directory containing the alarmserver.exe file:

1. Initialize the Microsoft Windows registry entries for the alarm server instance by using the command line alarmserver -init name=<INSTANCE_NAME>.

2. Install the alarm server as a Microsoft Windows service by using the command line alarmserver -install name=<INSTANCE_NAME>.

NOTE: You can install Alarm Server service into any directory, but you need to reinstall it if you want to change the directory.

Normally an alarm server instance is removed by removing the Infrastructure in Microsoft Windows control panels. If you need to remove an instance manually, perform the following procedure:

1. Remove the alarm server service by using the command line alarmserver -remove name=<INSTANCE_NAME>.

2. Clean up the Microsoft Windows registry by using the command line alarmserver -cleanup name=<INSTANCE_NAME>.

3. Delete the alarmserver.exe file from the bin directory, and delete the etc and mib directories.


ADMINISTRATION GUIDE5.2. STARTING AND STOPPING INSTANCES

23.4.2009

5.2. STARTING AND STOPPING INSTANCES

An alarm server instance is a Microsoft Windows service. You can use the Microsoft Windows Services control panel to start and stop it. Note the following:

The name of the service is SAP BCM Alarm Server <INSTANCE_NAME>.The installation package sets the default start-up type of the alarm server service to Manual.

5.3. CONFIGURING ALARM SERVER

The configuration is a combination of service parameters in the Microsoft Windows registry and data in the adapter configuration files.

5.3.1. Service parameters (page 46)5.3.2. Alarm adapters (page 48)

Additionally, set the HAC service parameter EnableHTTPAlarms to the value 1, see the section 2.4. Service parameters (page 8).

5.3.1. SERVICE PARAMETERS

The parameters are in the following location in the Microsoft Windows registry: HKEY_LOCAL_MACHINE\SOFTWARE\WICOM\AlarmServer_<INSTANCE_NAME>.

Note the following about the registry parameters:

The registry key above is used by an alarm server instance with the Microsoft Windows service name Alarm Server <INSTANCE_NAME>.The WICOM and AlarmServer_<INSTANCE_NAME> keys are generated when the Alarm Server instance is initialised and the registry entries are initialised with default values.If a registry entry is missing, the Alarm Server service creates it with default value when it starts up. Thus, you may reset any entry value back to the default value by deleting the corresponding entry and restarting the Alarm Server instance.

AlarmConversionEnabled => Enables alarm conversion to e-mail, SMS, and/or SNMP. 0 = no, 1 = yes.

AlarmForwardAddresses => Alarm server addresses to which the received alarms are forwarded. The format is HOST:PORT (for example 127.0.0.1:21013). The value is a semicolon-separated list.

AlarmForwardingEnabled => Enables forwarding of received alarms in the XML format to other alarm server instances. 0 = no, 1 = yes.

AlarmLoggingEnabled => Enables alarm logging into the alarm log file. 0 = no, 1 = yes.

AlarmLogPath => The directory path for alarm log files.


ADMINISTRATION GUIDE5.3.1. SERVICE PARAMETERS

23.4.2009

AlarmSendDelay => Defines how frequently the alarm server processes the received alarms. The value is in milliseconds.

EmailAdapterConfigFile => The path to the e-mail adapter configuration file. See the section 5.3.2. Alarm adapters (page 48). The default value is ../etc/email_config.xml.

EmailAdapterDSN => The ODBC data source definition the e-mail adapter uses for connecting to a CEM database. The default value is DRIVER=SQL Server;SERVER=LOCAL;DATABASE=CEM;UID=wicomcem;PWD=xxxxxxxx.

EmailAdapterEnabled => Enables the alarm-to-e-mail converter. 0 = no, 1 = yes. The default value is 0.

LogLevel => Defines the level of trace event logging. Do not select an unnecessarily high level just as a precaution, for high levels generate massive amount of log data very quickly. Under normal conditions it is recommended to run the alarm server in the log level 1 or 0. 0 = only errors, 1 = informative messages only, 2 = tracing, 3 = debugging.

LogPath => The location of the trace log files.

SMSAdapterConfigFile => The path to the SMS adapter configuration file. See the section 5.3.2. Alarm adapters (page 48). The default value is ../etc/sms_config.xml.

SMSAdapterDSN => Defines the ODBC data source definition the SMS adapter uses for connecting to a CEM database. The default value is DRIVER=SQL Server;SERVER=LOCAL;DATABASE=CEM;UID=wicomcem;PWD=xxxxxxxx.

SMSAdapterEnabled => Defines whether the alarm-to-SMS conversion is enabled. 0 = no, 1 = yes. The default value is 0.

SNMPAdapterConfigFile => Defines the location and name of the SNMP adapter configuration file. See the section 5.3.2. Alarm adapters (page 48). The default value is ../etc/snmp_config.xml.

SNMPAdapterEnabled => Enables the alarm-to-SNMP trap conversion. 0 = no, 1 = yes. The default value is 0.

SNMPAdapterManagerAddresses => The SNMP trap destinations in format HOST[:PORT]. The value is a semicolon-separated list (for example 127.0.0.1:161;MANAGER_HOST:5150). The port value is optional and the default value is 161.

TCPServerAddresses => The sockets the Alarm Server service listens to for incoming alarms. The addresses are in the format HOST[:PORT] (for example 0:0:0:0:9666 for all assigned IP addresses, or 127.0.0.1:9666 for a single address). If port number is given, it overrides the default port in TCPServerDefaultPort parameter. The value is a semicolon-separated list.

TCPServerDefaultPort => The default port number used with the IP addresses in TCPServerAddresses parameter if the entries do not include a port number.

TCPServerReceiveTimeout => The time interval when the Alarm Server service checks, whether it has been requested to shut down. The value is in milliseconds.


ADMINISTRATION GUIDE5.3.2. ALARM ADAPTERS

23.4.2009

5.3.2. ALARM ADAPTERS

Adapter-specific configuration files are related to the e-mail, SMS and SNMP alarm adapters. They are in XML format and located in the etc directory.


5.3.2.1. E-mail adapter (page 48)5.3.2.2. SMS adapter (page 51)5.3.2.3. SNMP adapter (page 52)5.3.2.4. Alarm Filtering (all adapters) (page 53)

5.3.2.1. E-MAIL ADAPTER

The following registry parameters are used by this adapter. See section 5.3.1. Service parameters (page 46) for more details.

EmailAdapterConfigFile EmailAdapterDSN EmailAdapterEnabled

The adapter must establish an ODBC connection to a CEM database to be able to send e-mail messages.The message conversion service has to be configured to process e-mail message data in that database.

The configuration file contains the majority of the e-mail adapter configuration information. Use the service parameter for defining the location and name of the file (by default ../etc/email_config.xml). The alarm filtering rule set is described in the section 5.3.2.4. Alarm Filtering (all adapters) (page 53).

The file contains the following general settings (advanced adapter configuration parameters):

REGISTER_TO_WATCHDOG => Enables monitoring of the adapter. If there is a failure in the adapter, the Alarm Server service is automatically restarted. FALSE or TRUE. The default value is FALSE.FLUSH_DELAY => Defines time interval for the adapter to process new alarms. The value is in seconds (between 5 and 60). The default value is 30.

The file may contain the following e-mail settings:

SENDER => Defines the alarm sender’s address. The default value is alarmserver@$HOSTNAME$.


ADMINISTRATION GUIDE5.3.2.1. E-MAIL ADAPTER

23.4.2009

RECIPIENTS => TO, CC and BCC => Defines the recipients. At least one TO recipient is compulsory. Each field may contain multiple addresses separated with semicolons. For example, <RECIPIENTS> <TO>[email protected];[email protected]</TO> <CC>[email protected] </CC> </RECIPIENTS>

SUBJECTS => RAISE, CANCEL and DEFAULT => Defines the subjects of the alarm messages. RAISE = the subject of messages informing that an alarm has been raised, CANCEL = the subject for messages informing that an alarm is cancelled, DEFAULT => used in unspecified cases.BODIES => The following formats are supported in the body template files: ANSI, UTF-8, UTF-8 little-endian, UTF-8 big-endian.

FORMAT => Defines the body text format for all messages. TEXT for plain text and HTML for HTML content. The default value is TEXT.RAISE, CANCEL and DEFAULT => FILE and ALT => Defines the body text for the messages of different types of alarms (an alarm has been raised or cancelled). The FILE value defines the path to a file which contains the text to be used as template for the body text (for example <FILE>c:\\temp\\body_file.txt</FILE>). The ALT value defines the body text to be used if the body template file is not in use (the FILE value is missing), cannot be opened (the file is corrupted or does not exist), or has no contents (the file is empty). The DEFAULT body text is used for cases (RAISE or CANCEL) for which a body text is not specified.

IMPORTANCES => NOTIFY, MINOR, MAJOR, CRITICAL and DEFAULT => Defines the message importance by the alarm severity. LOW, NORMAL or HIGH. The following default values are in use:

NOTIFY => NORMALMINOR => LOWMAJOR => NORMALCRITICAL => HIGHDEFAULT => NORMAL


ADMINISTRATION GUIDE5.3.2.1. E-MAIL ADAPTER

23.4.2009

Certain variables can be used in the following fields to produce the final values:

SENDER (for example <SENDER>alarmserver@$HOSTNAME$</SENDER>)RECIPIENTS SUBJECTS BODIES

Most variable values are transferred from the alarm data which is described in the section 2.7.1. Alarm format (page 11). The following variables can be used:

$HOSTNAME$ => The host name of the alarm server is using. This is the only variable which does not get its value from alarm data.$TIME$ => The original time stamp of the alarm in the format YYYY-MM-DD HH:MM:SS.$SEVERITY$ => The alarm level (NOTIFY, MINOR, MAJOR or CRITICAL).$PROCESS$ => The name of the process causing the alarm.$NAME$ => The (internal HAC) name of the element causing the alarm.$REASON$ => The alarm reason in compact form (for example INIT OK or element failed).$HOST$ => The host name of the device the alarm was generated on.$INSTANCE$ => The name of the HAC instance which generated the alarm (for example SERVER1).


ADMINISTRATION GUIDE5.3.2.2. SMS ADAPTER

23.4.2009

$DESC$ => Optional verbal alarm description (for example A system model element has failed due to reason in additional data).$RELATES$ => The (internal HAC) element the alarm is related to (for example Element [SERVER2] ID 2).$DATA$ => The optional extra alarm data (for example The HAC instance not being contacted within silent loss timeout).

5.3.2.2. SMS ADAPTER

The following registry parameters are used by this adapter. See the section 5.3.1. Service parameters (page 46) for more details.

SMSAdapterConfigFile SMSAdapterDSN SMSAdapterEnabled

The adapter must establish an ODBC connection to a CEM database to send SMS messages. The message conversion service must be configured to process SMS message data in that database.

The configuration file contains the majority of SMS adapter configuration information. Use the service parameter for defining the location and name of the file (by default ../etc/sms_config.xml). The alarm filtering rule set is described in the section 5.3.2.4. Alarm Filtering (all adapters) (page 53).

The file has the following general settings (advanced adapter configuration parameters):


The file has the following SMS-related settings:

RECIPIENTS => Defines the mobile phone numbers of the recipients. At least one number is compulsory. Each field may contain multiple addresses separated with semicolons. For example, <RECIPIENTS>0501234567;0402345678</RECIPIENTS>

BODIES => RAISE, CANCEL and DEFAULT => Defines the body text for the messages of different types of alarms (an alarm has been raised or cancelled). The DEFAULT body text is used for cases (RAISE or CANCEL) for which a body text is not specified. Note the following:

The recommended maximum number of characters is 160, as otherwise the message may be split.


ADMINISTRATION GUIDE5.3.2.3. SNMP ADAPTER

23.4.2009

You can also use the variables which are listed in the section E-mail adapter (page 48).

5.3.2.3. SNMP ADAPTER

The following registry parameters are used by this adapter. See the section 5.3.1. Service parameters (page 46) for more details.

SNMPAdapterConfigFile SNMPAdapterEnabled SNMPAdapterManagerAddresses

The adapter uses the Microsoft IIS SNMP service for sending the SNMP traps it generates. Therefore that service must be running properly.

The configuration file contains the majority of SNMP adapter configuration information. Use the service parameter for defining the location and name of the file (by default ../etc/snmp_config.xml). The alarm filtering rule set is described in the section 5.3.2.4. Alarm Filtering (all adapters) (page 53).

The file has the following general settings (advanced adapter configuration parameters):


The file has the following SNMP settings:

TRAP_TYPE => Defines the trap type. GENERIC = a single trap for all alarms (alarm severity code is included in the trap data as a varbind value), SEVERITY = a different trap for each


ADMINISTRATION GUIDE5.3.2.4. ALARM FILTERING (ALL ADAPTERS)

23.4.2009

alarm severity code (NOTIFY, MINOR, MAJOR and CRITICAL). The default value is GENERIC.

5.3.2.4. ALARM FILTERING (ALL ADAPTERS)

All alarm adapters support alarm filtering and all adapter configuration files have a section for filtering settings. Various filtering rules can be specified to exclude or include certain alarms or alarms with certain content. This section describes the alarm filtering rule set.

Filtering rules can be either simple or complex. The chosen filtering mode is defined in the FILTERMODE attribute of the CONFIG (top-level) settings.

<CONFIG FILTERING="SIMPLE"> <CONFIG FILTERING="COMPLEX">

The actual rules for each mode must be specified in a separate section.

The filtering section has the following settings related to the simple filtering mode:

HOSTS => The allowed host names. You can use an asterisk (*) to allow partial matches. For example, the SERV* value allows to process alarms from the SERVER1 and SERVER2 hosts. Enter a single asterisk to allow to process alarms from any host. The value is a semicolon-separated list.INSTANCES => The allowed alarm instance names. You can use an asterisk (*) to allow partial matches. For example, the INST* value allows to process alarms related to the INSTANCE1 and INSTANCE2 instances. Enter a single asterisk to allow to process alarms related to any instances. The value is a semicolon-separated list.PROCESSES => The allowed process names. You can use an asterisk (*) to allow partial matches. For example, BCM* allows to process alarms related to the BCM HAC and Alarm Server processes. Enter a single asterisk to allow to process alarms related to any processes. The value is a semicolon-separated list.SEVERITIES => The allowed alarm severity code values which indicate alarm-raising events (MINOR, MAJOR, and CRITICAL). Enter a single asterisk to allow to process alarms with any of these severity code values. The NOTIFY code value (cancelling a raised alarm) is automatically allowed.



23.4.2009

Alarm data is always matched against the simple-mode filtering rules in the following order: HOSTS, INSTANCES, PROCESSES and SEVERITIES. Note, that a filter never blocks alarms of severity level NOTIFY. The entire alarm passes filtering when each one of the steps returns a positive match.

An example simple mode filter: This filter allows only alarms from hosts that have a name beginning with the string SERVER and from process named BCM HAC 2.0.

The filtering section has the following settings related to the complex filtering mode:

HOST => Host name (or multiple hosts if you use wildcard characters in the attribute values) sending alarms to the alarm server. The HOST value of an alarm must match NAME, ALIAS or IP attribute value. The attribute values are used for matching and you can use an asterisk (*) as a wildcard character in them. NAME attribute specifies name of the host, ALIAS the secondary name of the host and IP the IP address of the host. DISABLED attribute disables the matching alarms (TRUE or 1 if disabled, and FALSE or 0 for enabled). If disabled, the alarms from the matched host(s) are blocked.

INSTANCE subnode(s) => A HAC instance running under the host. The INSTANCE value of an alarm must match the NAME attribute value. The attribute values are used for matching and you can use an asterisk (*) as a wildcard character in them.

PROCESS subnode(s) => Process monitored by a HAC instance. PROCESS field’s value of an alarm must match the NAME attribute value. The attribute values are used for matching and you can use an asterisk (*) as a wildcard character in them.

SEVERITY subnode(s) => alarm severity levelGENERIC_HOST => Represents hosts that do not match any of the HOST nodes. DISABLED attribute disables the matching alarms (TRUE or 1 if disabled, and FALSE or 0 for enabled). If disabled, the alarms from the matched host(s) are blocked.

INSTANCE subnode(s) defined as in above



23.4.2009

An example complex mode filter: This filter allows only alarms from the two specific hosts called SERVER1 and SERVER2. There is no filtering related to the instance, process, or severity values.



23.4.2009

Another example of the complex mode filter: This filter allows alarms from any hosts with the severity codes NOTIFY and CRITICAL, and also defines a specific filter for the SERVER3 host:

Allows alarms from any serverAllows alarms from the following processes with alarm severities:PROCESS1 with severity level NOTIFY, MAJOR, and CRITICALPROCESS2 with severity level NOTIFY, MINOR, and MAJOR


ADMINISTRATION GUIDE6. HAC SYSTEM MODEL

23.4.2009

6. HAC SYSTEM MODELHAC system model describes the system to be managed for HAC. The system model contains physical and logical components of the system as well as their relations to each other and intended behaviour.

NOTE: The system model is created and maintained in the Infrastructure Administrator application, but the following descrptions describe the entire function of the system model, not only the ones that are available in the IA user interface.


6.1. Managed system elements (MSE) (page 57)6.2. Basic element properties (page 59)6.3. All element properties (page 63)6.4. Attachment element properties (page 72)6.5. Behaviour scenarios (page 75)

6.1. MANAGED SYSTEM ELEMENTS (MSE)

Managed system elements (MSE) represent a physical or logical component of the system to be managed by HAC. It can represent server hardware, installed software, IP address or a logical group of other managed system elements.

The managed system elements of different kinds or class form a conceptual hierarchy as shown in UML class diagram below:

MSE may be composed of other managed system elements. A composite MSE is parent and contained elements are called components. The nature of the composition is defined by the class of the particular MSE. MSE also implements the basic activity dependencies, that is, a process may not run if another process it depends on is not active first.


ADMINISTRATION GUIDE6.1.1. HA SYSTEM ELEMENT

23.4.2009

Some elements can be hosted by a computer system. For example, an application is installed on a host which runs the application as a local process. The installed application and the related process are modelled with a software element hosted by a computer system.

In addition, MSEs may have a number of attachments depending on the MSE class. For example, a software element has attached monitor and controller elements which describe the monitoring and controlling of the associated software system component.

6.1.1. HA SYSTEM ELEMENT

HASystem element represents the entire managed system and is the top-level object in each system model. All other elements are direct or indirect components or subcomponents of this element.

6.1.2. SERVICE ELEMENT

Service elements represent a group of elements that are managed as a group. If any of the component elements fail, the service elements fails also thus resulting in inactivating the entire service and all its components.

A service is often a software element or collection of software elements. A service element provides a single point of management for its components. Typically, virtual unit instance elements are services.

If a component element's role is set to unassigned, it is not considered as part of the service. Thus, its failure does not cause the service to fail.

Service elements are always hosted by (components or subcomponents of) a computer system.

6.1.3. SOFTWARE ELEMENT

Software element represents a software system component for example an installed application process or web server. All software elements are always hosted by (components or subcomponents of) a computer system.

Software elements have an attached monitoring and controlling methods. Several alternative methods exist for different types of software (such as Microsoft Windows services, processes, and so on).

Software elements may have optional attached monitor and controller objects. They allow the software element to monitor and control the system component (for example the process and its executable file). Currently the following types of controllers and monitors are available:

Windows Service Monitor and Controller => Monitors and controls Microsoft Windows services.Windows Process Monitor and Controller => Monitors and controls Microsoft Windows processes that are started from an executable file. The process controller also supports the SAP BCM Stop Event signalling for stopping a SAP BCM process.


ADMINISTRATION GUIDE6.1.4. COMPUTER SYSTEM ELEMENT

23.4.2009

Shell Monitor and Controller => Uses given command lines to execute the required action. The return values from the command lines are interpreted as the results of the action.HTTP Monitor => Monitors a web server. It uses HTTP GET to a given web page on a given web server. This monitor also supports the Microsoft IIS web site (and application pool) monitoring.IIS web site controller => Controlling individual Microsoft IIS web sites.

The target for the controllers and monitors (the command line, executable file or service name) is defined in the TARGET property. You can use the PARAMETERS property to enter any parameters for the Microsoft Windows services or processes.

6.1.4. COMPUTER SYSTEM ELEMENT

Computer System represents a computer including the hardware and operating system.

When a computer system has a HAC instance, it is considered as a HAC node with the same name as the computer system element. HAC instances use the configured addresses to communicate with each other as well as for ICMP pinging for determining whether the computer system is online or not.

6.1.5. REDUNDANT SYSTEM ELEMENT

Redundant system represents a group of equivalent and redundant elements. The redundant elements are the instances of the redundant system.

Redundant system automatically manages the roles of the instance elements in order to maintain the appropriate number of its instances active and/or in the standby mode at all times. Instances are prioritized primarily by the instance element's name and secondarily by the instance element's element ID.

Typical virtual unit is modelled in HAC with a redundant system element having one instance on each node the virtual unit's software has been installed.

6.2. BASIC ELEMENT PROPERTIES

A unique element ID number identifies each element. Internally HAC uses the element ID as the reference to the elements. You can also give elements descriptive names and free-form descriptions. The element type specifies the element's type for example ComputerSystem.

6.2.1. COMPOSITION

Composition is a relation between elements. An element may contain other elements. The contained elements are called components of the containing element.

For example, HA System element represents the entire managed system and is the top-level object in each system model. A server contains the software installed into it, so in system model the computer


ADMINISTRATION GUIDE6.2.2. DEPENDENCY

23.4.2009

system element representing the server contains the software elements representing the installed software.

Components implicitly depend on their parent when it comes to activation and existence. If the parent is deleted, the components are deleted also. If a parent is set to be inactive, components are implicitly set to be inactive also regardless of other conditions. For example, setting a server to an inactive role causes inactivation of the installed software also.

6.2.2. DEPENDENCY

Elements may be given explicit dependencies on other elements. An element that depends on other elements, cannot be activated or be active before the antecedent elements are all active first. There cannot be loops in dependency chain to prevent deadlocks.

Dependencies can effectively be used for example to force a predefined activation sequence on a series of elements.

6.2.3. ELEMENT STATUS

Status indicates the runtime status of the system component represented by the element. For example, a software element representing a process is active if the process is running and inactive if the process is not running.

The following values are in use:

Unknown => The status has not been successfully determined yet.Active => Participates actively in the production.Inactive => The element has been shut down and does not participate in the production.Standby => The element is active, but does not participate in the production. This is considered to be the hot standby mode, and the element may be quickly activated into production from it.Activating => Proceeding to the active state.Inactivating => Proceeding to the inactive state.Standingby => Proceeding to the standby state.Partially active => The element is partially active.

6.2.4. ELEMENT HEALTH

Health indicates the runtime health of the system component represented by the element. Healthy system components are running and functioning as expected and they can be controlled when necessary.

For example, if an active web server successfully responds to HAC's monitoring, the element representing the web site can be considered to have normal health. If the web server suddenly starts producing errors in its responses, the element representing the web server is set to the failed health.

The following values are in use:


ADMINISTRATION GUIDE6.2.5. ELEMENT ROLE

23.4.2009

Unknown => The health has not been successfully determined yet.Normal => The element is acting normally according to its state. If an element is in a transitional state or is inactive, it has normal health if the controlling and monitoring mechanisms are generally available.Failed => The element has failed permanently and needs manual repair. A major alarm is raised and the HAC attempts to inactivate the element (forcibly if necessary).Near failure => The element is about to or may fail soon if no actions are taken. A minor alarm is raised to suggest preventive actions.

6.2.5. ELEMENT ROLE

Role of an element controls the desired status of the element. If other conditions (such as dependencies and so on) are met, the element's desired status matches its role.

The following values are used:

Active => The element should be active.Inactive => The element should be inactive.Standby => The element should be in hot standby.Spare => The element should be in cold standby.Unassigned => The element is intentionally left unassigned. HAC takes no actions to control the element. If a component of a Service element is set to unassigned role, the component is not considered as part of the service and thus, its failure does not cause the service to fail.Unknown => Reserved.

6.2.6. DESIRED STATUS OF ELEMENT

Desired status is a derived runtime property which indicates the runtime status the element should be in all things considered.

If an element status differs from the desired status, HAC issues actions to correct the situation. Typically, the following considerations apply:

Element roleElement healthDesired status of the parent of the element (if one exists)Status and desired status of the antecedents of the element (if any exist)Role of the redundant system the element belongs to (if applicable)

The status of an antecedent forms a constraint to the state of the dependent. HAC dependency relation is activation dependant, a depending element may not be active if its antecedent is not active as well.

A system component has failed temporarily if its status does not match the desired value. HAC tries to change the status of the temporarily failed element to the desired value several times by issuing


ADMINISTRATION GUIDE6.2.7. OPERATIONAL MODE

23.4.2009

controlling actions upon it. If the element remains in an undesired state after all retries, the element is marked as permanently failed and it is inactivated.

The general concept of element statuses is shown in the following state diagram:

The last inactivation attempt for an element is always a forced action. The actual forcing mechanism depends on the element type (and for a software element on the controllers attached to it).

Disaster handling depends on the situation and configuration. If a software element cannot be inactivated, appropriate alarms are generated to signal the condition and the local node can optionally be rebooted.

After an element has failed permanently, HAC continues to monitor the element, but leaves its failed health even if the monitoring would later start producing successful results. The Administrator has to manually tell HAC (using IA) that the problem behind the failure has been fixed. Exceptions to this rule are redundant system and computer system elements, which do revert to normal health automatically when the situation is corrected (for example, the server comes back on line or sufficient number of healthy redundant instances have been detected).

6.2.7. OPERATIONAL MODE

Operational mode is used to modify the behaviour of the element in the system.

The following values are used:

Normal => The element is participating in the production normally. All monitoring, controlling and recovery actions are performed in the usual way.Maintenance => The elements are monitored and managed in a normal way, but with the following exceptions:


ADMINISTRATION GUIDE6.2.8. LOCATION

23.4.2009

Software elements are not marked as permanently failed even if monitoring would produce the result. Also, instability of status does not cause the element to fail.Service elements do not fail even if its components fail.

Freeze => No automatic recovery actions are performed.Unknown => Reserved.

6.2.8. LOCATION

Location refers to relative physical location of the elements. For example, software elements hosted by a computer system are local within that computer system. From the point of view of another computer system these elements would appear as remote elements.

6.2.9. ELEMENT TAG

Tag property is a free-form string that administrators can use for their own purposes.

6.3. ALL ELEMENT PROPERTIES

All managed elements have some common properties. Each subclass or element type has its own additional properties. The properties are displayed and can be modified in the IA application in the Element Properties tab:

The following property value types are used:

String => A free-form string.Number => An integer number.Seconds => An integer number indicating a time period or interval in seconds.Boolean => The boolean values (TRUE/1 = true, FALSE/0 = false).IP Address => An IP address in the format n.n.n.n:port. The port number is optional.TypeName => Denotes a value from the list of possible values for the type name. For example, the health value may be one of the following: UNKNOWN, NORMAL, NEARFAILURE or FAILED.Substructure => A substructure with any number of other fields.Array => An array of substructures or fields.

6.3.1. COMMON MANAGED SYSTEM ELEMENT PROPERTIES

These properties are common to all managed system element types. The following properties can be seen and defined in the IA user interface in tabs Basics and Advanced for any element type.

PROPERTY NAME TYPE DESCRIPTIONID Number Unique element identifierType String Type or subclass name of the elementName String Name of the element displayed in IA and logs


ADMINISTRATION GUIDE6.3.1. COMMON MANAGED SYSTEM ELEMENT PROPERTIES

23.4.2009

Description String Free-form information displayed in IATag String Free-form information displayed in IAMode String Operational modeRole String Element roleStatus String Element runtime statusHealth String Element runtime healthGet Local/Remote Diagnostics

Array Context menu: Runtime diagnostics information. Remote Diagnostics contains information received from other nodes.

Element Dependencies Array The list of elements this element depends on. The antecedent elements are referred by their IDs, which are each given in an ANTECEDENTID item.

Force restart if antecedent is suddenly inactivated

Boolean If this is true, an active element is restarted if an antecedent element has even briefly not been active.For example, this is useful when an application depends on an IP address and is not able to rebind to the address if the address is temporarily lost. The flag would be set to true on the application's element to make the application restart when the IP address is even temporarily lost.

Alarm on Failure String The severity of the alarm generated when the element is failed.

Alarm on near failure String The severity of the alarm generated when the element is near failure.

PROPERTY NAME TYPE DESCRIPTION


ADMINISTRATION GUIDE6.3.2. SOFTWARE ELEMENT PROPERTIES

23.4.2009

6.3.2. SOFTWARE ELEMENT PROPERTIES

These properties are specific to elements with the type SoftwareElement. The following properties can be seen and defined in the IA user interface.

TAB PROPERTY NAME

TYPE DESCRIPTION

Advanced Log file settings String The log file definition for the remote log file import. You can use wildcard characters. The value may also contain one % variable which is automatically replaced with the node name when the string is used. If the string should contain an explicit % character, you must enter it twice (%%).


ADMINISTRATION GUIDE6.3.2. SOFTWARE ELEMENT PROPERTIES

23.4.2009

Depending on the software element, there may be additionally attachment elements like monitors and controllers, see also the 6.4. Attachment element properties (page 72).

System Component Interface

Monitor Substructure Attached system component monitorController Substructure Attached system component controllerReset host if inactivation persistently fails

If true, the hosting node is rebooted if the element fails to be inactivated.

Tolerate undesired status time

Seconds Defines how long the element tolerates instability of element status before failing. The default value is 60.

Required stabile time for status

Seconds Defines how long the element status must match the desired status before the element is considered as stabilised. The default value is 3 (for web packages) and 10 (for Windows process packages).

Maximum number of control actions retries

Number Defines how many times corrective control actions can be done before transition to desired status fails. The default value is 3

Monitor never fails the element

SubstructureBoolean

If true, the element's health is not set to failed even if its monitor would detect a failure in the system component.

TAB PROPERTY NAME

TYPE DESCRIPTION


ADMINISTRATION GUIDE6.3.3. SERVICE ACCESS POINT (IP ADDRESS) PROPERTIES

23.4.2009

6.3.3. SERVICE ACCESS POINT (IP ADDRESS) PROPERTIES

These properties are specific to elements with the type ServiceAccessPoint, such as IP address. The following properties can be seen and defined in the IA user interface in the Address tab.

PROPERTY NAME TYPE DESCRIPTIONAddressType String The value should always be IPV4.Address IP Address The access point IP address in the format n.n.n.nNetmask Netmask The access point netmask in the format n.n.n.n


ADMINISTRATION GUIDE6.3.4. SERVICE PROPERTIES

23.4.2009

6.3.4. SERVICE PROPERTIES

These properties are specific to elements with the type SERVICE.

PROPERTY NAME TYPE DESCRIPTIONManage Component Roles Boolean If true, the roles of the components are modified to

match the role of the service element. Use this value to enable the use of a genuine standby role in the service components.

Components depend on Service Access Points

Boolean If true, HAC automatically maintains dependency between a Service Access Point element and other elements in the service. The use of the flag eliminates the need to make explicit manual dependency declaration from other component elements to the Service Access Point component.

Interface IP Address The network interface card (NIC) to add the IP address to. If the value is missing, the first suitable NIC is used. An IP address already assigned to the card identifies the NIC. Enter the address in the format n.n.n.n.



ADMINISTRATION GUIDE6.3.5. COMPUTER SYSTEM PROPERTIES

23.4.2009

6.3.5. COMPUTER SYSTEM PROPERTIES

These properties are specific to elements with the type ComputerSystem. The components of a computer system are the local service and software elements (the installed software). The following properties can be seen and defined in the IA user interface in the Network, Logs and Variables tabs..

PROPERTY NAME TYPE DESCRIPTIONIP Addresses Array The list of IP addresses used by the HAC instance in

the computer system. The address is in the format n.n.n.n:port.

Allow Only TLS Connections

Boolean If selected, this node only accepts TLS connections from other HACs or IA.

Polling Interval Seconds Defines how often the node is polled. The default value is 5.

Silent Loss Timeout Seconds Defines how long the node can remain non-contacted before it is assumed to be lost. The default value is 20.

Forced Resynch Interval Seconds Defines how often the resynchronisation is executed with the node.The default value is 60.

Monitoring Timeout Seconds Defines the timeout for a node monitoring task. The default value is 60.

Reboot Timeout Seconds Defines the timeout for resetting the node. If the node has been reset for longer than this value indicates, it is assumed to be failed. The default value is 300.

IP Addresses for Administration

Array The list of IP addresses used for HAC-IA connection. The address is in the format n.n.n.n:port.

Logs String The log file definition for the remote log file import. You can use wildcard characters. The value may also contain one % variable which is automatically replaced with the node name when the string is used. If the string should contain an explicit % character, you must enter it twice (%%).

BCM Home Directory (i.e.WICOM_HOME)

String Home path where the virtual units are installed. The default value is C:\Program Files\SAP\BCM.

Directory for logs in the host (i.e. HOST_LOGS_PATH)

String Path to directory containing log files from for example, virtual units. Defaults to the variable HOST_LOGS_PATH.


ADMINISTRATION GUIDE6.3.6. REDUNDANT SYSTEM PROPERTIES

23.4.2009

6.3.6. REDUNDANT SYSTEM PROPERTIES

These properties are specific to elements with the type RedundantSystem, such as virtual units. The following properties can be seen and defined in the IA user interface in Redundancy and Variables tabs.

PROPERTY NAME TYPE DESCRIPTIONAutomatic Repair Instances when all instances have failed after

Seconds Defines how long to wait until an automatic repair of all instances is executed if all instances fail. If the value is zero, the feature is disabled. The default value is 120.


ADMINISTRATION GUIDE6.3.6. REDUNDANT SYSTEM PROPERTIES

23.4.2009

Wait timeout for instances in unknown status

Seconds Defines how long to wait for elements with an unknown state before altering instance roles. Useful for preventing unnecessary instance switch-overs during the HAC instance resets and reconstruction. If the value is zero, the feature is disabled. The default value is 20.

Minimum active instances Number Minimum number of instances attempted to maintain active. The default value is 1.

Maximum active instances Number Maximum number of instances allowed active. The default value is 1.

Maximum standby instances Number Number of additional instances to be kept in the standby mode if it is possible. The default value is 0.

Directory for virtual unit logs (i.e. VU_LOG_PATH)

String Path to directory containing virtual unit log files. Defaults to the variable HOST_LOGS_PATH$\VU\VU_NAME$\logs.



ADMINISTRATION GUIDE6.3.7. HA SYSTEM PROPERTIES

23.4.2009

6.3.7. HA SYSTEM PROPERTIES

These properties are specific to elements with the type HASYSTEM. An HA system element represents the entire managed system and is the top-level object in each system model. All other elements are components or subcomponents of this element. These properties have no settings in IA user inteface in addition to common ones..

6.4. ATTACHMENT ELEMENT PROPERTIES

Some managed system elements have attachments like system component controllers and monitors. All attachments have a common type property which describes the attachment type.

6.4.1. COMMON ATTACHMENT PROPERTIES

All attachments have some common properties. Attachments usually refer to a target for which an action or a number actions can be performed.

PROPERTY NAME TYPE DESCRIPTIONTarget String The target of the attachment actions.Parameters String Parameters related to the target.Execution timeout Seconds Timeout for performing actions on the target. The

default value is 30.Soft cancel timeout Seconds Timeout for gracefully cancelling an action. The

default value is 5.Resting time after completion Seconds Minimum time to pause before the action can be

restarted. The default value is 3.Minimum time between restarts Seconds Maximum frequency of restarting the action. The

default value is 2.

6.4.2. ELEMENT MONITORS

The target property is the target descriptor used for determining the status and health of the system component. Each subclass interprets the target in different ways and may define additional properties to specify the actual monitored target.

6.4.2.1. WINDOWS PROCESS MONITOR

These properties or their interpretations are specific to monitors with the type WINPROCESS.

PROPERTY NAME TYPE INTERPRETATIONFull path to the executable String The full path for the executable file searched from

the process list.Parameters String The command line parameters in the space-

delimited format.


ADMINISTRATION GUIDE6.4.2.2. WINDOWS SERVICE MONITOR

23.4.2009

6.4.2.2. WINDOWS SERVICE MONITOR

These properties or their interpretations are specific to monitors with the type WINSERVICE.

PROPERTY NAME TYPE INTERPRETATIONTarget String The name of the Microsoft Windows service to be

monitored.Parameters String The command line start-up parameters for the

service in the space-delimited format.

6.4.2.3. COMMAND LINE MONITOR

These properties or their interpretations are specific to monitors with the type SHELL. See the section 2.5.4. Shell monitor and controller (page 10).

PROPERTY NAME TYPE INTERPRETATIONTarget String The prefix used for constructing the command line

which returns the status and health of the monitored system component.

6.4.2.4. WEB SERVER MONITOR

These properties or their interpretations are specific to monitors with the type HTTP.

PROPERTY NAME TYPE INTERPRETATIONHTTP page path to test String The path to the web page within the server (for example

/test/index.htm). The web page is used for checking the availability of the web service.

Server IP Addresses to test Array The optional server addresses in the address subproperty in the format n.n.n.n:port.

Server response time and health: Maximum for normal health

Seconds Defines the maximum response time for a healthy web server. If a response time is longer, the health is considered to be near failure or failed. The default value is 5.

Server response time and health: Minimum before failing

Seconds Defines how long to wait for the web server response before the site is considered as failed. The default value is 20.

Enable IIS web site check Boolean If this is true, the web server is IIS and the monitored site is an IIS web site.

Name of the IIS site String The identifier for the monitored IIS web site. The identifier may be the IIS metabase path (for example /LM/W3SVC/1 or just /W3SVC/1) or the name of the site the server comment such as Default Web Site).


ADMINISTRATION GUIDE6.4.3. ELEMENT CONTROLLERS

23.4.2009

6.4.3. ELEMENT CONTROLLERS

The target property is the target descriptor used for controlling the system component. Each controller type interprets the target in different ways and may define additional properties to specify the actual controlled target.

Element controllers have a number of additional timeouts to be defined and they override the common attachment timeout property. The timeout values are in seconds and the name indicates the command the timeout refers to. The following additional timeouts are in use:

ActivateTimeout InactivateTimeout StandbyTimeout HardResetTimeout SoftResetTimeout

6.4.3.1. WINDOWS PROCESS CONTROLLER

These properties or their interpretations are specific to controller with type WINPROCESS.

PROPERTY NAME TYPE INTERPRETATIONTarget String The full path for the executable file.Priority String The priority of the created process. One of IDLE,

NORMAL, HIGH or REALTIME.UserID String The user ID the process is run as. With an empty value

HAC runs the process with the same user ID as the HAC itself is run with.

Password String The clear text password for the user. WARNING: This password is stored in the xml as plain text.

6.4.3.2. WINDOWS SERVICE CONTROLLER

These properties or their interpretations are specific to controller with the type WINSERVICE.

PROPERTY NAME TYPE INTERPRETATIONTarget String The name of the Microsoft Windows service. The actual

name of the service instead of the displayed name.Priority String The priority for the created service process IDLE,

NORMAL, HIGH or REALTIME.UserID String The user ID the service process is run as. With an empty

value HAC runs the process with the same user ID as the HAC itself is run with.

Password String The clear text password for the user.


ADMINISTRATION GUIDE6.4.3.3. COMMAND LINE CONTROLLER

23.4.2009

6.4.3.3. COMMAND LINE CONTROLLER

These properties or their interpretations are specific to controller with the type SHELL. In this context component means the system component. The shell controller considers the action to be successful if the command line exits with the zero exit code. A non-zero exit code results in considering the action failed.

PROPERTY NAME TYPE INTERPRETATIONActivateCmd String The complete command line to activate the component.InactivateCmd String The complete command line to inactivate the

component.ForceInactivateCmd String The complete command line to inactivate the

component forcefully.StandbyCmd String The complete command line to set the component to

standby.SoftResetCmd String The complete command line to soft-reset the

component.HardResetCmd String The complete command line to hard-reset the

component.

6.4.3.4. IIS SITE CONTROLLER

These properties or their interpretations are specific to controller with the type IISSITE.

PROPERTY NAME TYPE INTERPRETATIONTarget String The identifier of the IIS web site to be controlled. The

identifier may be the IIS metabase path (for example /LM/W3SVC/1 or just /W3SVC/1) or the name of the site (the server comment such as Default Web Site).

6.5. BEHAVIOUR SCENARIOS

This subsection describes some typical situations that occur in a system when it is controlled by HAC. Some troubleshooting scenarios are described in the section 8.3. Problem Scenarios (page 89).

6.5.1. ACTIVATION SCENARIOS

The following scenarios describe starting up the system or parts of it:

6.5.1.1. Starting up system (page 76)6.5.1.2. Activating service elements (page 76)6.5.1.3. Activating redundant system elements (page 76)


ADMINISTRATION GUIDE6.5.1.1. STARTING UP SYSTEM

23.4.2009

6.5.1.1. STARTING UP SYSTEM

This scenario describes the initial start-up of the entire system.

When HAC instance starts up, it monitors all elements and tries to contact the other HAC instances. Once a successful contact to a node is made, the HAC instances immediately synchronise themselves with each other. One by one the mesh of active HAC instances is formed and all instances gain visibility of the entire managed system.

Depending on the start-up sequence and timing, some fluctuation may appear in the state of the elements which have inter-node dependencies. This is normal for distributed systems, and the fluctuation will cease once enough instances have been interconnected.

6.5.1.2. ACTIVATING SERVICE ELEMENTS

This scenario describes activation of a Service element having some components.

Initially, the service element and its components are all healthy but inactive.

1. The service element's desired status results to active, which allows the component elements to activate.

2. The service element status is set to activating.3. Each component element is activated.4. Once all components are active, the status of service elements is set to active.

The final situation is that the service element and all its component elements are healthy and active.

6.5.1.3. ACTIVATING REDUNDANT SYSTEM ELEMENTS

This scenario describes the activation of a redundant system which has some spare instances included.

The initial situation is that the redundant system element is healthy but inactive. Its instances are all healthy, inactive and have the role spare. The system is set to have one and only one active instance at a time.

1. The redundant system element's desired status results to active.2. The redundant system element status is set to activating.3. The redundant system element determines the first eligible instance and sets its role to active.4. The selected instance element is activated.5. Once the instance is active, the status of the redundant system element is set to active.

The final situation is that the redundant system element and the first instance element are healthy and active. All other instance elements are healthy and inactive.


ADMINISTRATION GUIDE6.5.2. INACTIVATION SCENARIOS

23.4.2009

6.5.2. INACTIVATION SCENARIOS

The following scenarios describe the effects of shutting down the system or parts of it:

Inactivating system elementsInactivating local computer system elementInactivating service elements

6.5.2.1. INACTIVATING SYSTEM ELEMENTS

This scenario describes what happens when an active element is set to the role inactive.

The system element components notice that the desired status of their parent element is inactive. This sets the desired status of each component to inactive as well. The inactivation progresses downwards within the components and their subcomponents until all elements have the status inactive.

6.5.2.2. INACTIVATING LOCAL COMPUTER SYSTEM ELEMENT

This scenario describes what happens when role of an active computer system is set to inactive.

All service, software and service access point elements hosted by the computer system are inactivated due to their direct or indirect parent element having the desired status inactive.

The status of the computer system element itself stays active because the computer device itself is still running.

6.5.2.3. INACTIVATING SERVICE ELEMENTS

This scenario describes what happens when an active service with active components is set to the role inactive.

1. The service element's desired status results to inactive, which causes the component elements to inactivate.

2. The status of the service element is set to inactivating.3. Components are inactivated.4. After all components are inactive, the service status is set to inactive.

6.5.3. RECOVERY SCENARIOS

The following scenarios describe how HAC makes the automatic recovery actions when a part of the system has failed:

6.5.3.1. Failure of software element (page 78)6.5.3.2. Failure of computer system element (page 78)6.5.3.3. Silent failure of computer system (page 78)


ADMINISTRATION GUIDE6.5.3.1. FAILURE OF SOFTWARE ELEMENT

23.4.2009

6.5.3.4. Software element recovery from transient failure (page 78)6.5.3.5. Redundant system recovery (page 79)6.5.3.5. Redundant system recovery (page 79)6.5.3.6. Recovery from network failure (page 79)

6.5.3.1. FAILURE OF SOFTWARE ELEMENT

Inactivating service elements

6.5.3.2. FAILURE OF COMPUTER SYSTEM ELEMENT

This scenario describes what happens when an active computer system is considered as failed and inactive. This usually occurs if the computer device does not respond within a timeout due to being for example, suddenly turned off or unplugged from IP network.

If communication with a node fails, the node is considered as lost after a timeout. The health of the corresponding computer system element is set to failed.

In each HAC node all service, software and service access point elements which are local for the inactive computer system are set to inactive due to their host being inactive.

6.5.3.3. SILENT FAILURE OF COMPUTER SYSTEM

This scenario describes what happens when an active computer system fails without a notification.

If HAC detects that another HAC node has been silent for a while, it polls the node. If polling fails, the node is considered as temporarily lost and the computer system element health is first set to near failure.

If contact attempts continue to fail longer than the silent loss timeout period defined for the node can last, the node is considered as failed and its health is set accordingly.

6.5.3.4. SOFTWARE ELEMENT RECOVERY FROM TRANSIENT FAILURE

This scenario describes how a software element recovers from a transient failure of the system component (process or web server).

After the system component is monitored and found not to be in a desired status (for example, this may be due to a sudden termination of the process), the status of the corresponding software element is set to inactive.

Then the activate control action is issued upon the system component and the software element status is set to activating.

When normal operation is restored, the status of the software element is set to active.


ADMINISTRATION GUIDE6.5.3.5. REDUNDANT SYSTEM RECOVERY

23.4.2009

6.5.3.5. REDUNDANT SYSTEM RECOVERY

This scenario describes how redundant system element makes a switch-over from failing to a functioning instance. Initially, the failing instance is active while its health is set to failed.

1. The status of the redundant system element is set to activating and the health to near failure.2. The role of the failed instance element is set to spare.3. The next eligible instance element is determined and its role is set to active.4. The selected instance element activates.5. Once the instance has been successfully activated, the status of the redundant system element

is set to active and the health to normal.

6.5.3.6. RECOVERY FROM NETWORK FAILURE

This scenario describes how HAC recovers from the Ethernet link-down and route-broken situations. The presumption is that more than one network interface cards (NIC) have been installed and configured in the device.

Each HAC listens to all their configured IP addresses. All HACs continue trying to connect to each configured address in a round-robin fashion until a successful route is found.

When there is a link-down situation, the operating system disables the NIC and all addresses assigned to it. The IP service access point elements (used in the virtual units and so on) notice that the IP address has been removed and try to assign it to the first valid and enabled NIC. Providing that a valid NIC can be found, the IP address is assigned to it.


ADMINISTRATION GUIDE6.5.3.6. RECOVERY FROM NETWORK FAILURE

23.4.2009


ADMINISTRATION GUIDE7. ADMINISTRATIVE TASKS

23.4.2009

7. ADMINISTRATIVE TASKSThis section describes the following topics:

7.1. Backing up Server (page 81)7.2. Backing up virtual unit instance (page 82)7.3. Restoring virtual unit instance From Backup (page 82)7.4. Upgrading infrastructure software (page 82)7.5. Upgrading other software (page 83)7.6. Changing IP addresses (page 84)7.7. Changing passwords (page 85)

7.1. BACKING UP SERVER

Export the following registry keys under key HKEY_LOCAL_MACHINE\SOFTWARE:

Wicom ODBC

Back up the following directories containing system related software and files:

The infrastructure software (by default in C:\Program files\SAP\BCM)Files of all virtual unit instances (by default in C:\Program files\SAP\BCM\VU)SAP BCM software installation packages (by default in C:\Program files\SAP\BCM\Install)System databases. Take a complete SQL back-up copy with SQL Enterprise Manager.All special directories that may have been configured to another location than defaults (check on each virtual unit)

Standard and customized promptsVoicemail recordings foldersCall recording foldersSent and received faxes foldersCPM attachments foldersOutbound folders Logs

In addition to the above files, directories and registry entries, a server may also contain other items . When the server contains web sites hosted by Microsoft IIS, these web sites and associated application pools should also be taken into account. If Microsoft IIS is reinstalled, the sites and application pools are also removed. The web sites can be recreated using VUA, but any custom settings on them should be reapplied manually.

For backing up third party components (PSTN gateways, hardphones and so on), refer to their vendors’ manuals.


ADMINISTRATION GUIDE7.2. BACKING UP VIRTUAL UNIT INSTANCE

23.4.2009

7.2. BACKING UP VIRTUAL UNIT INSTANCE

The following actions are needed to back up a virtual unit instance on a server:

Copy the home directory of the virtual unit. By default the directory is C:\Program Files\SAP\BCM\VU\<virtual unit name>. Do not save the copy to the same directory with other virtual units since it causes the VUA application to malfunction.Copy the virtual unit’s registry key recursively from HKLM/Software/Wicom/<virtual unit name>.If the virtual unit contains a Microsoft SQL Server database, backup the database.

7.3. RESTORING VIRTUAL UNIT INSTANCE FROM BACKUP

The following actions are needed to restore a backed up a virtual unit instance on a server:

Make sure the virtual unit instance is inactive on the server.Restore the home directory of the virtual unit from backup. By default the directory is C:\Program Files\SAP\BCM\VU\<virtual unit name>.Restore the virtual unit’s registry key in HKLM/Software/Wicom/<virtual unit name> from backup.If the virtual unit contains a Microsoft SQL Server database, restore the database from backup.If the virtual unit contains Microsoft IIS web sites or ODBC data source names, recreate these using VUA. Upgrading the virtual unit to its current base installation causes the files, registry entries and web sites to be set or recreated properly.

7.4. UPGRADING INFRASTRUCTURE SOFTWARE

You can upgrade all infrastructure management software (including HAC, IA, and utilities like VUA) without affecting the running production system.

Upgrading utilities has no impact on the running system. They are upgraded by replacing old utilities with new ones.

Upgrading HAC and IA applications requires more careful approach, since they actively participate in the running system. It is strongly recommended to upgrade all HAC and IA applications to the same version simultaneously.

Perform the procedure for live systems in the following way:

1. Back up the HAC system model and IA files.2. Make sure IA is online and all HACs are running.


ADMINISTRATION GUIDE7.5. UPGRADING OTHER SOFTWARE

23.4.2009

3. Freeze the entire system model by setting the top-level element (by default named The System) to the Freeze mode. The mode change propagates to all elements in the system.

4. Set the frozen system model as the start-up configuration for HACs by saving the system model in the IA tool. Then, wait until all looks normal again in IA. Depending on the size of the system, it may take some seconds for all HACs to receive and store the new start-up configuration.

5. Shut down all HACs and IAs. This should not affect the running services.6. Remove the previous version of the Infrastructure Administrator program in the Control

Panel - Add or Remove Programs.7. Upgrade the Infrastructure Administrator package, and HACs on all servers. See the

Installation Guide document.8. Start all HACs.9. Start IA and put it online.10. Unfreeze the entire system model by setting the top-level element to the Normal mode. The

mode change propagates to all elements in the system.11. Set the unfrozen system model as the start-up configuration for all HACs by saving the

system model in IA.

7.5. UPGRADING OTHER SOFTWARE

You can upgrade other software by using the VUA application. The new installation packages can either replace the older packages or you can install them to a new base installation directory. See the section 3. Virtual Unit Management (VUA) (page 17) and the Installation Guide document.

Normally an instance of actively running software cannot be upgraded, because the system prohibits replacing open files (such as executable and DLL files related to the running applications). You must shut down an active instance before commencing with the upgrade.

In live environments the downtime can be limited by using the rolling update strategy. First the software is upgraded in all inactive virtual unit instances. When it is time to upgrade the last instance (the active one), the production is switched to another instance which you have already upgraded. After the switch-over you can upgrade the last instance.


ADMINISTRATION GUIDE7.6. CHANGING IP ADDRESSES

23.4.2009

7.6. CHANGING IP ADDRESSES

In some cases you must make IP address changes in an entire platform. For example, when you move all servers into a new subnetwork. The checklists in this section cover the situation when all IP addresses and subnet masks need to be changed.

You need to modify several parts of a system to change the IP address range to the HAC platform. Make sure that you understand the difference between a physical and virtual IP address before proceeding. The concepts are described in the section 1. Introduction (page 1).

It is strongly recommended to take an overall back-up copy before implementing any IP changes.

IP addresses must be reconfigured in the following parts of the system:

Reconfiguring Databases (use the System Administrator application)Reconfiguring HAC system model (use IA )Reconfiguring Virtual Unit Instances on each host (use VUA )Reconfiguring PSTN gateways Reconfiguring End-User Clients on workstations, hardphones and so on

7.6.1. RECONFIGURING DATABASES

Configure the following settings by using the System Administrator application:

Applications => Application serverServer => Update the virtual IP address.Server => Update the WAV file path (if an IP address is used instead of a name).Calldispatcher => Update the virtual IP address.

Applications => ApplicationApplication => Select the conceptual VOICEMAIL application and update the recording and conversion paths (if an IP address is used instead of a name).

Services => Service controllerController => Update the virtual IP address (if an IP address is used instead of a name).Service => Update the virtual IP address for all appropriate services.

Platforms => GatewaysGateway => Update the virtual IP address for the H.323 bridge, H.323 gatekeeper and other possible selected components.

Platforms => H.323 GatewayH.323 Gateway => Update the virtual IP addresses.

7.6.2. RECONFIGURING HAC SYSTEM MODEL

Update the IP addresses and/or subnet masks in the following locations by using the IA application:

Server or node address lists


ADMINISTRATION GUIDE7.6.3. RECONFIGURING VIRTUAL UNIT INSTANCES

23.4.2009

IP address and subnet mask for a virtual unitWeb site monitorsElement names containing the old address.

Although the addresses in the element names do not have any functional purpose, incorrect names are very inconvenient and confuse system administrators. Update the element names as well.

7.6.3. RECONFIGURING VIRTUAL UNIT INSTANCES

1. Inactivate the virtual unit in the IA tool.2. For other than web sites, edit the virtual unit in VUA, change the IP address, and apply

changes.3. For virtual units containing the Web Server: uninstall and recretae on with a new IP address,

for IIS does not allow changing the IP address of the web site.

7.6.4. RECONFIGURING PSTN GATEWAYS

Update the IP address and the gatekeeper address for the gateways. Use the gateway vendor’s utilities and recommendations for modifying the gateways.

7.6.5. RECONFIGURING END-USER CLIENTS

Update the IP addresses and masks in the following locations:

Workstations Add the new virtual IP address to the trusted sites.Add the new virtual IP address (range) to the proxy settings (if they are in use).

Terminals Update the firewall rules (if a firewall is used between servers and/or end user terminals) and the routing rules.Update the new virtual gatekeeper IP address and subnet mask for the required devices (such as Tiptel IP200 or 21, the wireless Netvision terminals, access points, possible SIP terminals, and so on).

7.7. CHANGING PASSWORDS

The system includes several different passwords. When you change a password somewhere, usually you must change it in several other places as well. Take into account at least the following passwords:

System administration passwordYou can change it in the System Administrator application.Controls the server component access to the CEM and CPM databases in the SQL server.


ADMINISTRATION GUIDE7.7. CHANGING PASSWORDS

23.4.2009

Controls the access to the System Administrator application which is used for managing system data.

Database passwordsIf you change the database username and/or password for CEM, make also the necessary changes to the appropriate virtual units (by using VUA).Make these changes in each server hosting the software.


ADMINISTRATION GUIDE8. TROUBLESHOOTING

23.4.2009

8. TROUBLESHOOTINGIn most cases the HAC log files and alarms together with the element diagnostics data provide enough information to find out the cause of the problem. The information is mainly in plain English. If a problem occurs repeatedly, you can temporarily switch the HAC logging level to the tracing or debugging value to get more detailed information.


8.1. HAC log files (page 87)8.2. HAC element diagnostics (page 88)8.3. Problem Scenarios (page 89)

8.1. HAC LOG FILES

Each HAC node produces event logs to its local disk, and by default they are stored to system’s log file directory of the system (such as C:\WINNT\system32\LogFiles\...). HAC creates a new log file each day with the date in the name of the file.

Most of the entries have the following syntax (from left to right):

1. A time stamp2. An optional priority

INF => InformationERR => ErrorDBG => Debugging informationTRC => Tracing information

3. The element4. The change5. The reason for change

The following example displays a typical entry sequence in a start-up situation. Some less important lines are left out.


ADMINISTRATION GUIDE8.2. HAC ELEMENT DIAGNOSTICS

23.4.2009

Another example of log entries are from HAC’s startup when there are problems with IP address settings or network interfaces:

8.2. HAC ELEMENT DIAGNOSTICS

Each HAC node produces diagnostics information about its local elements. The diagnostics are available remotely using the IA tool’s Get Remote Diagnostics command on the node element in the IA tool’s system model view.


ADMINISTRATION GUIDE8.3. PROBLEM SCENARIOS

23.4.2009

The requested diagnostics data is opened into a separate window as well as copied into clipboard. Diagnostics could look something like below:

8.3. PROBLEM SCENARIOS

Some typical situations that may occur are described in the section 6.5. Behaviour scenarios (page 70).


8.0.1. Communication with node fails (page 90)8.0.2. All elements in node stay in unknown health (page 90)8.0.3. All nodes are failed (page 90)8.0.4. Some virtual unit components fail immediately (page 90)8.0.5. Some software elements fail after a while (page 91)8.0.6. HAC log file displays system error code 12 (page 91)8.0.7. HAC fails to control or monitor IIS web Server (page 91)8.0.8. Database or IIS web site fails immediately after rebooting computer (page 91)


ADMINISTRATION GUIDE8.0.1. COMMUNICATION WITH NODE FAILS

23.4.2009

8.0.1. COMMUNICATION WITH NODE FAILS

When IA cannot properly communicate with a HAC node, it marks its health status as failed and the health of the hosted elements as unknown. If the node cannot be contacted by any means (not even with the ICMP ping), the node status is set to inactive. The statuses of elements hosted by the node are also set to inactive.

Check the following issues:

The IP addresses for the node in the system model is correct.HAC must be running properly with a correct name. Check the spelling of the HAC node names in the system model and in the HAC instance of the problem node (the Microsoft Windows service).All nodes must share the same version of the system model.IA and HAC must be able to send IP packets between the HAC administration node and the problem node.

8.0.2. ALL ELEMENTS IN NODE STAY IN UNKNOWN HEALTH

In this case the nodeoften has the status failed. This problem is usually related to communication problems with the node. It usually occurs when you create a new system or add a new node to the system.

8.0.3. ALL NODES ARE FAILED

All nodes are running, but IA shows their health as failed. The probable reason is that the IA cannot communicate properly with other HAC nodes.

Check the following issues:

The administration node must have correct IP addresses and ports in the system model.There can be only a single IA process running on the computer at the same time with the same node name. Otherwise, the concurrent processes would attempt to use the same IP address for communicating with other HAC nodes. Only one of them is able to receive messages from other HAC nodes.

8.0.4. SOME VIRTUAL UNIT COMPONENTS FAIL IMMEDIATELY

When the system is running otherwise normally, some virtual unit (VU) components fail almost immediately even when you have marked them as repaired.

Investigate the diagnostics information for the element, and check the LAST_FAILURE_REASON value. If the reason is for example, a missing executable, HAC cannot find the executable file associated with the software element.

Check that the virtual unit instance has been correctly created. The virtual unit name must also match in the system model and in the file system related to the problem node.


ADMINISTRATION GUIDE8.0.5. SOME SOFTWARE ELEMENTS FAIL AFTER A WHILE

23.4.2009

8.0.5. SOME SOFTWARE ELEMENTS FAIL AFTER A WHILE

When the HA system is running otherwise normally, some virtual unit (VU) components fail after a while when you have repaired them. The associated executable application files exist and the possible virtual unit names match.

The problem may be that the associated application process or the Microsoft Windows service starts up normally, but exits soon after its start-up. HAC notes this as a failed activation and tries to restart the application. Software elements fail after suffering a number of unsuccessful attempts to activate the associated system component (process).

Some applications (such as the services MsgCleaner and MsgToMail) exit if their configuration or running environment is not correct. Check the configuration for the applications from their possible Microsoft Windows registry, configuration file, and/or database entries. When you find the reason why the application exits soon after its start-up, you are usually able to fix the problem.

8.0.6. HAC LOG FILE DISPLAYS SYSTEM ERROR CODE 12

If the HAC log file displays the following error message, you should restart the HAC service as soon as possible:

07:12:34 ERR> Unable to start thread [Computer system monitor thread] due to system error code 12.

HAC has ran out of system resources and cannot operate normally. Restarting HAC does not affect the services managed by HAC.

8.0.7. HAC FAILS TO CONTROL OR MONITOR IIS WEB SERVER

If HAC fails to control or monitor an IIS web site or an associated application pool, you should restart the local HAC service. Restarting HAC does not affect the services managed by HAC.

8.0.8. DATABASE OR IIS WEB SITE FAILS IMMEDIATELY AFTER REBOOTING COMPUTER

If HAC is used for monitoring SQL databases or IIS web sites, it is possible that a HAC service starts during a Windows reboot before the Windows operating system is able to start the required services to run the databases or web sites. Therefore HAC may mark the databases or web sites as failed even before they have been able to start.

In these cases, the HAC-related Windows service should be configured to depend on the SQL Server or IIS Web publishing services. This forces Windows to start the SQL Server and web server services before it starts HAC.


ADMINISTRATION GUIDE8.0.8. DATABASE OR IIS WEB SITE FAILS IMMEDIATELY AFTER REBOOTING

23.4.2009


ADMINISTRATION GUIDE9. GLOSSARY

23.4.2009

9. GLOSSARYABBREVIATION (TERM) DESCRIPTION OR SYNONYM3G (third generation) A level of development related to wireless technologies. The

preceding levels were 1G (included analog standards such as FDMA and NMT), 2G (included digital standards such as CDMA and GSM), and 2.5G (included the packet-based GPRS standard). The 3G standards include UMTS (based on GSM) and WCDMA (based on CDMA).

A number The number where the call or message comes from (the caller’s number or the source number).

Absence A status in the PRS system when a user is away or not available and cannot be reached.

ADS (Active Director Synchronizer) A service that transfers user accounts from Active Directory to the CEM database.

Agent A user who handles queue calls and interacts with customers. Usually related to contact centers.

APO (Access Point) One of the databases in the Reporting system, works as an access point for operative SQL databases and controls the DTE job.

ASP (application service provider) An enterprise that provides other enterprises or individuals remote access to application programs and services over the Internet.

Attended transfer A call is transferred to another number only after the person it is transferred to answers the phone. The call is put on hold automatically, and you can release it and continue if the other party does not answer. Compare to the blind transfer method.

Auto-allocation mode The call queue mode where you automatically get the next inbound call from the queues in which you are currently serving as an agent. The call is offered to one agent at a time. Compare to the hunt group mode.

Availability information Indicates whether a user is absent or present. Related to PRS profiles.

B number The target of the call or message (the destination number).Blind transfer A call is transferred to another number without you knowing

whether the other party answers or not. Compare to the attended transfer method.

Bridge (H.323 or SIP) A core module for connecting the registered terminal devices and the gateways to the CD core module.

C number The target of the call which is forwarded from the B number.Campaign Defines the contents of the outbound call set (such as the

customers, scripts and special rules) in the Outbound Desktop application.

CD (Call Dispatcher) The core module for low-level call handling.CDT (Communication Desktop) An end user application for enterprise telephony systems and

contact center operations.



23.4.2009

CEM (Contact Event Manager) The core module for top-level call handling.CEM database The system database for call handling.Chat, chatting Real-time communication between users using computing devices.ClientCom The communication interface between the client-level

applications.CMC (Communication Mobile Client) An end user application for mobile phone users.Codec (coder/decoder) A module which combines analog-to-digital and digital-to-analog

conversion.Company An external customer or an internal employer in the CPM

database. Contacts are always linked to one or more companies.Contact An external customer or an internal employee in the CPM

database. When internal user accounts are transferred from the CEM database to the CPM database, they are interpreted as contacts. Contacts are always linked to one or more companies.

CPM (Contact Process Manager) database

The system database for managing customer information and activities (such as tasks).

CPM Administrator An administration application related to the CPM database and predefined outbound call campaigns.

CT Outlook (Communication Toolbar for MS Outlook)

An extension application which makes it possible to use some telephony and availability functions in the MS Office Outlook application.

CTM (Communication Task Management) An end user application related to task management. It is also used for creating and maintaining customer data and personal segments.

Customer In the CPM database: an external company or contact. In the ASP system model: a separate subsystem.

Customizer, customizing file A text file in the CEM server which contains dedicated customer-specific values.

DB, db (database) A collection of information which is organized by using predefined rules.

Dialer A module that controls the outbound call sequence, timing and agent assignment in the Outbound Desktop application.

Directory Either a CEM directory defined in the System Administrator application, or a segment which is displayed as a contact directory in the Communication Desktop (CDT) application.

DSArea (Data Staging Area) One of the databases in the DTE. Related to the Reporting application.

DTE (Data transformation engineer) A tool that runs the transformation process in the Reporting application.

DTMF (dual tone multi-frequency) The signals you generate by pressing the keypad of a traditional phone.

DW (Data warehouse) Information organised in datanarts for effective on-line search. Related to the Reporting application.

ABBREVIATION (TERM) DESCRIPTION OR SYNONYM



23.4.2009

E-mail channel The queue type which is used for receiving and handling e-mail messages.

External agent A user who is logged into the software from an external number (mobile or fixed). External agents serve in queues remotely.

FBR (Federation Bridge) The core module for interconnecting several BCM systems. Used in ASP systems.

GK (gatekeeper) (H.323 or SIP) A core module for registering the terminal devices to the CD core module.

GUI (graphical user interface) The graphical interface for human-computer interaction (HCI). GUIs make it easier to use the software applications compared to command-based interfaces.

GW (gateway) (H.323 or SIP) An external module for connecting the system to an external network (usually to the PSTN network).

H.323, H323 A standard protocol for audio, video, data, internet phone, and VoIP transmissions.

HA (high availability) A system or module which is operational without uncontrolled interruptions.

HAC (High-Availability Controller) An infrastructure application that ensures one of the redundant virtual unit instances is running all the time.

Hunt group mode The call queue mode where you can pick an inbound call from the queues in which you are currently serving at as an agent. The call is offered simultaneously to all agents who are logged into the queue. Compare to auto-allocation mode.

IA (Infrastructure Administrator) An administration application for creating the system model, and starting and stopping all components of the system.

IA Viewer An administration application for monitoring the system functions. IAP (Internet Access Point) The connection server through which the CMC application

connects to the internet. IIS (Internet Information Server) A Microsoft server product which is used for various web-related

tasks, such as managing services and sharing information.IM (instant message) A short messages sent and delivered using the Communication

Desktop (CDT) application internally in a BCM system.Inbound Incoming (contact events).IP (Internet Protocol) The method and technology for sending data between computers

on the Internet.IP phone A telephone based on IP technology.IVR (Interactive Voice Response) A system which supports interaction between the caller and the

system. For example, the caller may hear a prerecorded prompt which instructs them to enter data with the phone keypad.

LAN (local area network) A group of computing devices which are used over a shared data line within a limited geographical area.




23.4.2009

MAGENT The core module required for the messaging functions in the Communication Desktop (CDT) application. This ActiveX component is installed on a client workstation.

MCTABUFF The core module required for ClientCom integrations and the task management integration. This ActiveX component is installed on a client workstation.

Mobile phone A cellular telephone.MRS (Media Routing Server) The core module for playing prompt files. It also converts the RTP

stream into a WAV file when a caller leaves a voicemail message.MSI The file format for Microsoft Windows Installer packages.MTD (Multiterminal Desktop) Functions for defining multiple terminal devices for receiving

inbound calls, and for selecting which one of the devices is used when making outbound calls. Used in the Communication Desktop (CDT) application.

NAT (Network Address Translation) An IP address used in one network (the inside network) is translated to a different IP address known in another network (the outside network). Often involves address mapping and firewall configuration to improve security.

OB Desktop (Outbound Desktop) An end user application related to predefined outbound call campaigns.

OLAP On-line analytical processing. Related to the Reporting application.

OPER_DIR The default queue for passing personal inbound calls within the BCM system

Outbound Outgoing (contact events).PBX (private branch exchange) A traditional corporate telephone system which usually includes

switchboard hardware.PDC (Predictive Dialing Controller) A CEM module which runs the outbound campaigns. Used in the

Outbound Desktop application.Person An external individual in the CPM database. Persons are not

connected to companies and are usually private persons.POP (point-of-presence) An internet access point which has a unique IP address and

provides access to the rest of the Internet.Presence A status in the PRS system when a user is free and can be reached.Prompt An audio message file in the WAV format.PRS (Personal Reachability Services) Functions related to the availability information. The selected PRS

profile tells other users if you are available or not. Used in the Communication Desktop (CDT) application and Communication Mobile Client (CMC) application.

PRS profile An absence, presence or conference profile which defines how inbound calls are handled when an appropriate profile is selected.




23.4.2009

PSTN (public switched telephone network)

The collection of interconnected public telephone networks and systems.

Queue routing The rules for offering calls to the agents who are serving in the queues in the auto-allocation mode.

R number The term used for the original external source number (the A number) in the following special case: the system is configured to display the original number even if the call has been forwarded within the system before it is finally forwarded to another external number. Normally the system displays the personal extension number or the queue number as the source number.

Reporting An application using data warehouse technology for effective reporting.

RTP (Real-time Transport Protocol) A standard protocol for audio, video, data, internet phone, and VoIP transmissions.

SBR (skill-based routing) A queue routing method in the software. The software offers calls to the agents who are most suited to take the call.

Segment A target group which is created in the CPM database and displayed as a directory in the CDT or CMC application. It contains persons, contacts, and companies. Segments may be company-wide (created in the CPM Administrator application) or personal (created in the CDT or CTM application).

SIP (Session Initiation Protocol) A standard protocol for audio, video, data, internet phone, and VoIP transmissions.

SMS (short message service) The method for delivering short messages to mobile phones.SOAP (Simple Object Access Protocol) The method which allows an exchange of data between

applications running on different platforms.SQL (Structured Query Language) A programming language used for database queries and updates.

May also refer to a database server or program.Superior-assistant A role related to special queue functions.Switchboard Traditionally hardware (a telephone routing table) for routing and

connecting calls to other users.System Administrator An administration application related to the system data and

configuration.TAPI (Telephony Application Programming Interface)

A programming interface which allows you to make telephone and video calls using computers.

TCP/IP (Transmission Control Protocol/Internet Protocol)

A method and language for sending data between computers on the Internet.

Terminal The core module required for the phone functions in the Communication Desktop (CDT) application. This ActiveX component is installed on a client workstation.

User Administrator An administration application where user accounts and their rights are created and maintained.




23.4.2009

UTC (Coordinated Universal Time) The standard time system used in the software. Times in different time zones are calculated in relation to the UTC time.

WLAN (wireless local area network) A group of computing devices which are used over a wireless link within a limited geographical area.

Voicemail Traditionally a telephone answering service where callers can leave messages into a voicemail box. Also an application in the BCM system.

VoIP (Voice over internet protocol) A method for transferring voice signal over the Internet.VPN (virtual private network) A method for offering remote users secure access to a network.VU (virtual unit) A group of technical services that are managed as a single unit.

Related to the system infrastructure. BCM software is installed in the virtual units that have redundant instances on two or more physical computers. HAC controls that one of the instances is active at a time.

VUA (Virtual Unit Administrator) An infrastructure application where virtual units are created and maintained. .

VWU Virtual Warehouse Unit. Related to the Reporting application.



Infrastructure Guide

Documents

Transcript of Infrastructure Guide