Cisco BroadWorks

Application Delivery Platform

Configuration Guide

Document Version 1
 Copyright Notice
Copyright© 2020 Cisco Systems, Inc. All rights reserved.

Trademarks
Any product names mentioned in this document may be trademarks or registered
trademarks of Cisco or their respective companies and are hereby acknowledged.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 2
 Document Revision History

Release Version Reason for Change Date Author

2020.07 1 Created document. June 13, 2020 Yves Racine

2020.07 1 Added keywords to document July 3, 2020 Joan Renaud

Properties. Edited and published
document.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 3
 Table of Contents

1 Summary of Changes ...................................................................................................................1

1.1 Changes for Release 2020.07, Document Version 1 .................................................................1
2 Introduction ....................................................................................................................................2
2.1 Deployment Models......................................................................................................................2
2.2 Optional Front End .......................................................................................................................5
3 Get Started ......................................................................................................................................6
4 Software Distribution ....................................................................................................................7
5 Licensing .........................................................................................................................................8
6 Installation and Upgrade ..............................................................................................................9
6.1 Server Upgrade ............................................................................................................................9
6.1.1 Upgrade from Xtended Services Platform/Profile Server ............................................... 10
6.1.2 Revert to Xtended Services Platform/Profile Server....................................................... 10
6.2 Applications Installation and Upgrade ...................................................................................... 11
6.2.1 Release-Independent Applications .................................................................................. 11
6.2.2 Release-Anchored Applications ...................................................................................... 12
6.2.3 Upgrade Mode .................................................................................................................. 13
6.2.4 Application Compatibility with Application Delivery Platform.......................................... 13
6.3 Additional Installation Tips......................................................................................................... 13
7 Application Delivery Platform Components .......................................................................... 14
7.1 Core Daemons .......................................................................................................................... 14
7.1.1 Software Manager ............................................................................................................ 14
7.1.2 SNMP Agent ..................................................................................................................... 14
7.1.3 License Manager .............................................................................................................. 15
7.1.4 Configuration Agent .......................................................................................................... 16
7.1.5 Platform Processes .......................................................................................................... 17
7.2 Controllable Applications ........................................................................................................... 18
7.2.1 WebContainer ................................................................................................................... 18
8 Configuration and Management .............................................................................................. 20
8.1 Configuration Modes ................................................................................................................. 20
8.2 Profile Tuning ............................................................................................................................. 20
8.2.1 Profile Characterization .................................................................................................... 20
8.2.2 CLI Level ........................................................................................................................... 21
8.3 WebApplication Threading ........................................................................................................ 22
8.3.1 General Concept .............................................................................................................. 22
8.3.2 Typical Configurations ...................................................................................................... 23
8.4 Configuration of BWCommunicationUtility ............................................................................... 25
8.4.1 Integration Mode ............................................................................................................... 25
8.4.2 Provision to Secondary .................................................................................................... 25

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 4
 8.4.3 Communication Settings .................................................................................................. 25
8.4.4 Overflow Protection Settings ............................................................................................ 25
8.4.5 Executors .......................................................................................................................... 26
8.4.6 External Authentication Support ...................................................................................... 26
8.4.7 Name Service ................................................................................................................... 26
8.5 Configuration of WebContainer ................................................................................................ 27
8.5.1 General Settings ............................................................................................................... 27
8.5.2 Logging.............................................................................................................................. 28
8.5.3 Executors .......................................................................................................................... 29
8.5.4 Process Metrics ................................................................................................................ 29
8.5.5 Overload Protection .......................................................................................................... 30
8.5.6 Session Management ...................................................................................................... 32
8.5.7 Thresholds ........................................................................................................................ 33
8.6 Management of WebContainer ................................................................................................ 35
8.6.1 Metric Groups ................................................................................................................... 35
8.6.2 Sequence Diagrams......................................................................................................... 36
8.6.3 Process Metrics ................................................................................................................ 40
8.6.4 Thresholds ........................................................................................................................ 41
8.7 Application Management .......................................................................................................... 42
8.7.1 Installation ......................................................................................................................... 43
8.7.2 Activation ........................................................................................................................... 44
8.7.3 Deployment ....................................................................................................................... 45
8.7.4 Undeployment................................................................................................................... 51
8.7.5 Deactivation ...................................................................................................................... 52
8.7.6 Uninstallation..................................................................................................................... 52
8.7.7 Upgrade ............................................................................................................................ 53
8.7.8 Revert ................................................................................................................................ 54
8.8 HTTP Server Configuration....................................................................................................... 54
8.8.1 Public Host Name ............................................................................................................. 55
8.8.2 Secure HTTP Server ........................................................................................................ 56
8.8.3 Create HTTP Server......................................................................................................... 56
8.8.4 Delete HTTP Server ......................................................................................................... 56
8.8.5 Manage SSL Certificates ................................................................................................. 57
8.8.6 HTTP Aliases .................................................................................................................... 61
8.8.7 HTTP Bindings.................................................................................................................. 61
8.9 Peering ....................................................................................................................................... 61
8.9.1 File Replication ................................................................................................................. 61
8.9.2 Configuration Replication ................................................................................................. 61
8.9.3 Redundancy Configuration .............................................................................................. 62
8.10 Network Server Configuration................................................................................................... 65
9 Network Configuration Changes ............................................................................................. 66
9.1 Change IP or Host Name of Application Delivery Platform ..................................................... 66

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 5
 9.1.1 Update HTTP Server Configuration ................................................................................ 66
9.2 Change IP, Host Name, or FQDN of Network Server ............................................................. 66
9.3 Change IP or Host Name of Application Server ...................................................................... 67
10 Troubleshooting ......................................................................................................................... 68
10.1 Logs ............................................................................................................................................ 68
10.1.1 HTTP Access Logs........................................................................................................... 68
10.1.2 Tomcat Logs ..................................................................................................................... 68
10.1.3 Web Application Logs....................................................................................................... 68
10.1.4 Cisco BroadWorks Application Logs ............................................................................... 68
10.1.5 Configuration Agent Logs................................................................................................. 68
10.1.6 Other Cisco BroadWorks Logs ........................................................................................ 68
10.2 Common Problems ................................................................................................................... 69
10.2.1 Authentication Failure for Valid User ............................................................................... 69
10.2.2 OCI-C Connectivity Problems .......................................................................................... 69
11 Application Delivery Platform Web Applications Requirements ....................................... 71
11.1 Application Packaging Requirements ...................................................................................... 71
11.1.1 War File Name .................................................................................................................. 71
11.1.2 War File Structure and Contents ..................................................................................... 71
11.2 Web Application Descriptor File (web.xml) .............................................................................. 72
11.3 Web Application Naming........................................................................................................... 73
11.4 Web Application Versioning ...................................................................................................... 73
11.5 Web Application External Configuration................................................................................... 73
11.5.1 BwCommunicationUtility Overrides ................................................................................. 74
11.6 Web Application Context Path .................................................................................................. 74
References .......................................................................................................................................... 75

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 6
 Table of Figures

Figure 1 Application Delivery Platform Deployment Models .................................................................... 3

Figure 2 Components Overview ................................................................................................................ 4
Figure 3 Load Balancer Deployment Example ......................................................................................... 5
Figure 4 Web Container Assembly.......................................................................................................... 18
Figure 5 HTTP Blocking Sequence Diagram (HttpNiO) ......................................................................... 36
Figure 6 HTTP Streaming Sequence Diagram (HttpNio) ....................................................................... 37
Figure 7 CTI Sequence Diagram ............................................................................................................. 37

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 7
 1 Summary of Changes

This section describes the changes to this document for each release and document
version.

1.1 Changes for Release 2020.07, Document Version 1

The document was created for this release.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 1
 2 Introduction

The Application Delivery Platform is a general-purpose application-hosting server. It is

meant as a controlled platform on which applications that integrate with other Cisco
BroadWorks services/servers can run. The Application Delivery Platform is based on two
container frameworks, the BroadWorks Container and the Web Container. The
BroadWorks Container provides flexibility for the applications, scalability for the servers,
and ease to manage the development and deployment of current and future applications.
Applications running inside the BroadWorks Container can have their own threading
model, garbage collection algorithm, and memory configuration.
The Web Container relies on the industry reference Apache Hypertext Transfer Protocol
(HTTP) Server and Apache Tomcat Servlet Container.
The Application Delivery Platform supplies an enhanced Cisco BroadWorks platform that
allows installation, activation, deployment, upgrade, and revert of Cisco BroadWorks and
web applications. It also comes with the usual Cisco BroadWorks platform services such
as a command line interface (CLI), Simple Network Management Protocol (SNMP) agent,
and process monitoring.
The Application Delivery Platform also includes the BWCommunicationUtility, which
provides base functionality for all web applications. It provides integrated services, which
allow simple communication to other Cisco BroadWorks servers. It also provides web
application building blocks such as security and authentication services and web
application overload protection to Cisco BroadWorks users.
The Application Delivery Platform provides a comprehensive CLI that allows operators to
install new Cisco BroadWorks (and web) applications and use them as required.

2.1 Deployment Models

The Application Delivery Platform can be deployed in different models depending on the
services offered. It can be deployed as a stand-alone server or as pools of servers. Each
Application Delivery Platform in a pool is independently managed.
The Application Delivery Platform can be located at the front end of multiple Application
Server clusters and a Network Server is always required. The Application Delivery
Platform can also be located at the back end of multiple Application Server clusters and
serve to host back end applications.
When using pools of servers, the recommended approach is to identify multiple pools of
segregated applications. In other words, there should be multiple pools of like-servers
such as a pool for Device Management (DM) applications, another pool for Xtended
Services Interface (Xsi) applications, and so on.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 2
 Figure 1 shows the deployment models.

ADP Farm

NS

AS Cluster
ADP

Figure 1 Application Delivery Platform Deployment Models

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 3
 Figure 2 shows the major software components of the Application Delivery Platform and
how they relate to each other.

Application Application
...

BroadWorks BroadWorks
Container Container

BroadWorks Platform

Configuration Software SNMP Agent

Agent Manager

BroadWorks Web Container Application Alarms & PMs

Tomcat (v8.0)

BW
Communication OCI-P
Web Utility
Application AS- PS
OCI-C

...
httpnio

http (blocking

http (async)

Web
Application
LocationAPI NS
XML
CTI

Figure 2 Components Overview

This guide provides general Application Delivery Platform product description and
deployment information. It explains the Cisco BroadWorks and web applications
management features of the Application Delivery Platform and provides some guidelines
on web application development.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 4
 2.2 Optional Front End
The Load Balancer is an HTTP reverse proxy that can be deployed on an Application
Delivery Platform in lieu of the Web Container application. As a gateway in front of other
Application Delivery Platforms, it allows for the quick reconfiguration of proxied server
farms hosting HTTP services.

Backend A
[WebContainer]
App-A
Bindings App-C

Backend C
ADP [WebContainer]
[LoadBalancer] App-B
App-C

Backend B
ProxyServer X
[WebContainer]
App-B
App-C

ProxyServer Y

Backend D
[WebContainer]
App-D

Figure 3 Load Balancer Deployment Example

For more information about the Load Balancer application, see the Load Balancing
Feature Description [4].

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 5
 3 Get Started

The following steps should be executed to start an Application Delivery Platform Server.
1) Obtain a license from Cisco. For more information, see section 5 Licensing.
2) Install the Application Delivery Platform from the binary image. For more information,
see the Cisco BroadWorks Software Management Guide [1].
3) Configure the BWCommunicationUtility on the Application Delivery Platform. For
more information, see section 8.4 Configuration of BWCommunicationUtility.
4) Configure the Application Server cluster to allow Application Delivery Platform
connectivity.
5) Start the Application Delivery Platform.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 6
 4 Software Distribution

The Application Delivery Platform is distributed using binary images for Linux. The image
files are named using the usual format:
 ADP_Rel_2020.07_1.yyy.Linux-x86_64.bin
Where yyy is a unique identifier for the Application Delivery Platform Release 2020.07.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 7
 5 Licensing

The Application Delivery Platform has its own license. This license is such that it can
contain multiple licenses to allow the running of Cisco BroadWorks applications.
The Application Delivery Platform does not start if it is not properly licensed.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 8
 6 Installation and Upgrade

The installation procedure for the Application Delivery Platform is similar to the one used
for existing Cisco BroadWorks servers. For detailed information and procedures on
installing the Application Delivery Platform, see the Cisco BroadWorks Software
Management Guide [1].
The upgrade process for the Application Delivery Platform works the same way as for
other Cisco BroadWorks servers. However, the Cisco BroadWorks and web applications
hosted by the Application Delivery Platform are handled differently from the Application
Delivery Platform itself. The following subsection provides more information.

6.1 Server Upgrade

The upgrade of the Application Delivery Platform is similar to the other Cisco BroadWorks
servers except for the activation. Compared to the other servers where the activation is
done in two steps (setting the target version and resetting), activating an Application
Delivery Platform is done in a single step, that is, setting the active software version. As
soon as the set command is executed and accepted, the server is stopped and its version
is switched to the specified version. Finally, the server is started with the specified version.
The following example shows the set command.
ADP_CLI/Maintenance/ManagedObjects> help set
This command is used to modify the Managed Object (MO)-related attributes.

Parameters description:
forceOption : This parameter determines the force option. Use the
"force" option to apply the change immediately.
Otherwise, a restart of the application is required for
the changes to apply.
option : This parameter determines the options.
activeSoftwareVersion: This parameter specifies the active software version.
type : This parameter determines whether the activation type is
the server or a specific application. The software
automatically determines whether it needs to upgrade or
rollback.
server : This parameter controls the activation of the server.
identity : This nested parameter specifies the name of the server
identity to set to "active". It is usually the short
name of a BroadWorks server (for example, Profile
Server, Network Server, and so on).
version : This nested parameter specifies the version of the
software to activate.
revert : This parameter provides the ability to revert to a
previous release. Use the "revert" option to perform a
revert to the specified previous release. Otherwise, a
rollback to the specified previous release is performed.
backupLocation : This nested parameter specifies the full path of the
database backup file to use when performing a revert.
application : This parameter controls the activation of an application.
name : This parameter specifies the name of the application to
set to "active".

======================================================================
set
[<forceOption>, Choice = {force}]
<option>, Choice = {activeSoftwareVersion}
activeSoftwareVersion:
<type>, Choice = {server, application}
server:
<identity>, String {1 to 80 characters}
<version>, String {1 to 80 characters}
[<revert>, Choice = {revert}]
revert:

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 9
 [<backupLocation>, String {0 to 80 characters}]
application:
<name>, String {1 to 80 characters}
<version>, String {1 to 80 characters}
[<revert>, Choice = {revert}]
revert:
[<backupLocation>, String {0 to 80 characters}]

ADP_CLI/Maintenance/ManagedObjects> set activeSoftwareVersion server ADP

2020.07_1.030

+++ WARNING +++ WARNING +++ WARNING +++

This command will change the active software version of ADP to 23.0_1.1015. NOTE
that this action will cause downtime.
Continue?

Please confirm (Yes, Y, No, N): y

BroadWorks SW Manager checking ADP server version 23.0_1.1015...

Reverting to a previous version is executed the same way, that is, through the CLI. Note
that since the Application Delivery Platform is release independent, rollback is not
supported. However, for the revert operation to be allowed, the list of applications installed
on the Application Delivery Platform, including their versions, must be the same as it was
before the upgrade.

NOTE: Server upgrade/revert shall be performed during a maintenance window.

6.1.1 Upgrade from Xtended Services Platform/Profile Server

The Application Delivery Platform also supports upgrades from the Xtended Services
Platform and Profile Server from both Release 22.0 and Release 23.0. However, to
preserve the functionalities, all the corresponding applications that are deployed on the
current Xtended Services Platform and Profile Server release must be pre-downloaded to
/usr/local/broadworks/apps before the actual upgrade. If one of the deployed applications
is not pre-downloaded, the pre-upgrade check reports an error, and the upgrade process
is aborted.
To make sure the required applications are pre-downloaded, the pre-upgrade check uses
the following rules:
 For release independent, one and only one release-independent version of the
application is present.
 For release anchored, one and only one application with a release higher or equal to
24.0 is present.
Failure to respect one of these rules will make the upgrade check fail.
At the end of the upgrade process, the server is converted to an Application Delivery
Platform and all applications that were in the deployed state on the former Xtended
Services Platform/Profile Server are deployed and ready to use on the Application
Delivery Platform.

6.1.2 Revert to Xtended Services Platform/Profile Server

Reverting to former Release 22.0 and Release 23.0 Xtended Services Platform and
Profile Server is also supported. Once the revert operation is completed, the server state
is the same state as it was before the upgrade. Any actions and/or configuration
performed after the upgrade is lost.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 10
 All the applications that were deployed before the server upgrade are redeployed with the
same configuration they had.

6.2 Applications Installation and Upgrade

The WebContainer application is automatically installed, activated, and deployed on the
Application Delivery Platform. This application provides the HTTP functionality. Other
applications can be installed by the operator via the CLI. For more information, see
section 8.7 Application Management.
Depending on the individual application’s reliance on the Open Client Interface-
Provisioning (OCI-P) and Open Client Interface-Call Control (OCI-C) Application Server
schema, applications evolve in one of two ways:
 If an application has no direct dependency, the application is delivered in a release-
independent version train.
 If the application has a direct dependency, the application evolves as a release-
anchored version train.
In both cases, applications are built as signed BroadWorks Application aRchive (BWAR)
files.
Both types of applications are available for download from the software distribution center.

6.2.1 Release-Independent Applications

The following applications are delivered as release independent:
 AuthenticationService
 BroadWorksDMS
 BwCMProxy
 CustomMediaFilesRetrieval
 DeviceManagementTFTP
 LoadBalancer
 LogServer
 NotificationPushServer
 OCIFiles
 OCIOverSoap
 OpenClientServer
 PublicReporting
 RatingFunction
 BroadworksFileRepos
 BroadworksFileReposExtdCapture
 CCReporting
 CCReportingDBManagement
 CCReportingRepository
 DBSObserver
 DeviceManagementFiles

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 11
  ECLReportingRepository
 LogRepository
 MediaFiles
 MeetMeConferencingRepository
 MessageArchive
 EnhancedCallLogsDBManagementNDS

Since these applications are delivered as release independent, the build format is date
based, as follows:
APP_YYYY.MM_1.XXX
Where:
 APP represents the application name (for example, LoadBalancer).
 YYYY represents the year (for example, 2020).
 MM represents the month (for example, 07).
 XXX represents the incremented build number.

The resulting application binary file is APP_YYYY.MM_1.XXX.bwar. For example, the

binary file for the LoadBalancer application is similar to the following:
 LoadBalancer_2020.07_1.030.bwar

6.2.2 Release-Anchored Applications

The following applications are delivered as release anchored:
 CommPilot
 Xsi-Actions
 Xsi-Events
 Xsi-MMTel
 Xsi-VTR
 UCAPI
 PublicECLQuery
 ECLQuery

Since these applications are delivered as release anchored, the build format is release
based, as follows:
APP_MAJOR.MINOR_1.XXXX
Where:
 APP represents the application name (for example, CommPilot).
 MAJOR represents the major version (for example 24, corresponding to the
Application Server version).
 MINOR represents the minor version (for example, 0).
 XXXX represents the incremented build number.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 12
 The resulting application binary file is APP_MAJOR.MINOR_1.XXXX.bwar. For
example, the binary file for the CommPilot applications is similar to the following:
 CommPilot_24.0_1.1030.bwar

6.2.3 Upgrade Mode

The Application Delivery Platform supports two upgrade modes for applications, automatic
and manual.
 Automatic upgrade is used for applications that are completely controlled by Cisco
BroadWorks. These applications are only embedded in Cisco BroadWorks
installation packages. They cannot be manually installed or uninstalled via bwar/war
files. They are automatically upgraded by the Cisco BroadWorks upgrade server
process. The only non-automated task is the decision to activate/deactivate or
deploy/undeploy the application, which is still made by the operator. On the
Application Delivery Platform, only the WebContainer application is automatically
upgraded.
 Manual upgrade is used for all other applications that are individually distributed as
bwar/war files by Cisco or through the Xtended Developer’s program. These
applications can be freely installed, activated, deployed, undeployed, deactivated,
uninstalled, upgraded, or reverted by the operator. These applications are not
automatically managed by the upgrade process, that is, upgrading the Cisco
BroadWorks server does not affect the installed/deployed application.
The application modes cannot be modified through the CLI. Only Cisco can provide
applications in automatic mode.
Two application types are also supported: Cisco BroadWorks (BW) application and web
application:
 Cisco BroadWorks applications are packaged as a BroadWorks ARchive (.bwar) file.
 Web applications are packaged as Web ARchive (.war) file.

6.2.4 Application Compatibility with Application Delivery Platform

When installing the application, a validation is performed to make sure the application is
compatible with the active Application Delivery Platform. If the application is not
compatible, an upgrade of the Application Delivery Platform is necessary to install the
application.

6.3 Additional Installation Tips

Best practices dictate that an operator should provision a firewall between the public
Internet and the Application Delivery Platforms to facilitate tracking of resources, such as
the number of connections per IP, long connections to Tomcat, and so on.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 13
 7 Application Delivery Platform Components

The Application Delivery Platform hosts several active components that provide internal
and external services.

7.1 Core Daemons

The components described in this section are Cisco BroadWorks server daemons that are
started by the operating system service initialization script when the server boots. They
are only stopped when the operating system stops. As such, these daemons are started
when the operating system enters run level 3, 4, or 5 (that is, normal operation). They are
terminated when the operating system leaves these levels (for example, shutdown).
Manual control of the daemon’s lifecycle is neither required nor expected but can be
accomplished using the commands specified in the following sections.

7.1.1 Software Manager

The Software Manager is part of the core components of the Application Delivery Platform.
It is responsible for the installation, activation, and deployment of Cisco BroadWorks
applications and web applications. The Software Manager is a critical component that
must run for an operator to perform management and maintenance of the Cisco
BroadWorks server.

7.1.1.1 Lifecycle Control

While it is not recommended during normal operation, it is possible to restart the Software
Manager during the maintenance window. To stop and start it, the following commands
can be used.
bwadmin@mtl64lin12 $ stopswman.pl

Stopping SW Manager version: 751259

bwadmin@mtl64lin12 $ startswman.pl

Starting SW Manager version: 751259

bwadmin@mtl64lin12 $

7.1.1.2 Logs
The Software Manager logs are located in directory /var/broadworks/logs/swmanager.

7.1.2 SNMP Agent

The SNMP Agent is a core component of the Application Delivery Platform. It is not
started and stopped with Cisco BroadWorks. It is running all the time. The SNMP Agent
exposes the application counters and gauges to the management system. When a new
application (Cisco BroadWorks or web) is installed on the Application Delivery Platform, its
counters and gauges are automatically added to those exposed by the SNMP Agent. On
the other end, when an application is uninstalled, its counters and gauges are removed.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 14
 7.1.2.1 Lifecycle Control
While it is not recommended during normal operation, it is possible to restart the SNMP
Agent during the maintenance window. The lifecycle of the SNMP Agent is controlled with
the snmpdctl script located in /usr/local/broadworks/bw_base/bin. The script supports the
following options:
 start: Starts the SNMP Agent.
 stop: Stops the SNMP Agent.
 status: Shows the current SNMP Agent’s state (inService or dead).
 restart: Stops and restarts the SNMP Agent.
Following is an example of the usage.
bwadmin@mtl64lin12 $ snmpdctl
Usage: snmpdctl {start|stop|restart|status}
bwadmin@mtl64lin12 $ snmpdctl stop
Shutting down bwsnmpd... [ok]
Shutting down netsnmp... [ok]
bwadmin@mtl64lin12 $ snmpdctl start
Executing transform... [ok]

Executing transform... [ok]

Executing transform... [ok]

Starting netsnmp... [ok]

Starting bwsnmpd... [ok]
bwadmin@mtl64lin12 $
bwadmin@mtl64lin12 $ snmpdctl status
netsnmp: inService
bwsnmpd: inService

NOTE: The statistics collected by the SNMP Agent are lost when the SNMP Agent is stopped.

7.1.2.2 Logs
The SNMP Agent logs are located in the /var/broadworks/logs/snmp directory.

7.1.3 License Manager

The License Manager (LicenseManager) is a core component of the Application Delivery
Platform. It runs all the time, regardless of whether Cisco BroadWorks is started or
stopped. The License Manager is started initially during the installation process but more
generally, the UNIX initd starts and stops it at boot-time and shutdown.
The License Manager is responsible for managing the license files locally, getting the
license files from the Network Function Manager (NFM) Server, and requesting license
permission usage to the Network Function Manager.
The License Manager must be running for the applications to start. If the License
Manager is down or stopped and you attempt to start Cisco BroadWorks (startbw), the
application does not start.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 15
 7.1.3.1 Lifecycle Control
While it is not recommended during normal operation, it is possible to restart the License
Manager during the maintenance window. The lifecycle of the License Manager is
controlled with the lmdctl script located in /usr/local/broadworks/bw_base/bin. The script
supports the following options:
 start: Starts the License Manager.
 stop: Stops the License Manager.
 status: Shows the current License Manager’s state (inService or dead).
 restart: Stops and restarts the License Manager.
Following is an example of the usage.
bwadmin@mtl64lin12 $ lmdctl
Usage: lmdctl {start|stop|restart|status}
bwadmin@mtl64lin12 $ lmdctl stop
Shutting down lmd... [ok]
bwadmin@mtl64lin12 $ lmdctl start
Executing transform... [ok]

Starting lmd... [ok]

bwadmin@mtl64lin12 $
bwadmin@mtl64lin12 $ lmdctl status
lmd: inService

7.1.3.2 Logs
The License Manager logs are located in the /var/broadworks/logs/lmd directory.

7.1.4 Configuration Agent

The Configuration Agent is responsible for managing the server’s configuration. It hosts
the configuration data and is interfaced by other Cisco BroadWorks components that need
to read and/or write configuration data. The Configuration Agent is a critical component
that must run for other components to operate properly. It provides local services to other
components of the server.
The Configuration Agent communicates using the Network Configuration (NETCONF)
protocol. This interface complies with RFC 6241 Network Configuration Protocol
(NETCONF). For more information, see the Cisco BroadWorks Configuration System
Interface Specification [5].

7.1.4.1 Lifecycle Control

It is not recommended to stop the Configuration Agent during normal operation. The
Configuration Agent is used by many platform components and applications and when
stopped, these components and applications may misbehave. When required, it can be
stopped during the maintenance window using the configdctl script provided in
/usr/local/broadworks/bw_base/bin. The script supports the following options:
 start: Starts the Configuration Agent.
 stop: Stops the Configuration Agent if Cisco BroadWorks applications are not
running.
 stopnow: Stops the Configuration agent even if Cisco BroadWorks applications are
running.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 16
  status: Shows the current Configuration Agent’s state (inService or dead).
 restart: Stops and restarts the Configuration Agent.
 validate: Checks if the config.xml file is valid.
Following is an example of the usage.
bwadmin@mtl64lin12 $ configdctl
Usage: configdctl {start | stop | stopnow | restart | status | validate}
bwadmin@mtl64lin12 $ configdctl stop
Shutting down configd... [ok]
bwadmin@mtl64lin12 $ configdctl stopnow
Shutting down configd... [ok]
bwadmin@mtl64lin12 $ configdctl start
Setting system info values
Patching configuration... [ok]

Executing transform... [ok]

Starting configd... [ok]

bwadmin@mtl64lin12 $ configdctl status
configd: inService
bwadmin@mtl64lin12 $ configdctl validate
Validating ... [ok]

7.1.4.2 Logs
The Configuration Agent issues logs to the /var/broadworks/logs/config directory.

7.1.5 Platform Processes

On the Application Delivery Platform, the showrun command always displays two
categories of processes: the application and the platform processes. Following is an
example of the showrun command output.
[email protected]$ showrun

Currently running BroadWorks Application processes:

tomcat process monitor (pid=3333)

tomcat (pid=3498)

Currently running BroadWorks Platform processes:

BroadWorks Configuration Agent process monitor (pid=4345)

BroadWorks Configuration Agent (pid=4364)
BroadWorks License Manager process monitor (pid=4716)
BroadWorks License Manager (pid=4735)
BroadWorks SNMP Agent process monitor (pid=19271)
BroadWorks SNMP Agent (pid=19290)
BroadWorks Software Manager (pid=32459)
Net-SNMP Daemon process monitor (pid=19193)
Net-SNMP Daemon (pid=19214)

The platform processes must always be running for the Cisco BroadWorks applications to
run properly. The healthmon command monitors these processes and reports any
missing platform processes.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 17
 7.2 Controllable Applications
The components described in this section are Cisco BroadWorks services that can be
started and stopped by the operator. Deployed applications typically start when Cisco
BroadWorks starts and stop when Cisco BroadWorks stops.

7.2.1 WebContainer
The Application Delivery Platform deploys a WebContainer application to host the web
applications. The WebContainer is built around the Tomcat application server.
The WebContainer application is like any other automatic Cisco BroadWorks applications,
that is, it can be activated, deployed, undeployed, and deactivated.

7.2.1.1 WebContainer Software Components

The following figure fragments the Web Container into software components pertinent for
the metrics it provides. This section provides only a summary in the form of metric groups.
This representation is reused in sequence diagrams that explain the key metrics in detail.
For a complete description, see section 8.6.1 Metric Groups.

WebContainer Components

Tomcat Application Container Platform services:

Bindings
Stats Collection
Overload STATS #E
server.xml
STATS #D
(generated)

Platform App WebApplication

Services Filters (ex: XsiActions)
War
(classes,
STATS #C web.xml)

Mgr
HTTPNIO
Executor

STATS #B
STATS #B
HTTP
HTTP-Nio
Connector

STATS #C

CTI OCIC
Executor Executor BCCT
(OCIP,
Proprietary, XML-based BwCommunicationUtility
OCIC,
OCIP SMAP)
CTI Connector Executor

Config

STATS #E
STATS #E

Figure 4 Web Container Assembly

The BwCommunicationUtility provides common platform-level services that webapps can

use to interact with Cisco BroadWorks services. It provides a simplified API that abstracts
details of the underlying communication infrastructure. Each webapp uses a dedicated
instance of the BwCommunicationMgr. The webapp can also instantiate and configure
request processing filters that are provided with the BwCommunicationUtility.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 18
 All incoming HTTP traffic is processed by Tomcat’s specialized HttpNio connector. The
connector uses the associated executor (queue/threadPool) to process all requests.
Applications can use blocking or non-blocking processing, whichever is better suited to
their needs. The blocking processing consumes a thread for the duration of the request
processing, up until the response is transmitted. The non-blocking processing uses
threads sporadically as needed up until the response is transmitted.
The CTIConnector is a proprietary connector that allows use of the webapps via an XML-
based protocol used for Computer Telephony Integration (CTI) integration with third-party
systems.

7.2.1.2 WebContainer Metric Groups

As indicated in the previous figure, performance metrics are collected at various points
within the WebContainer:
1) Connector processing metrics (Stats #B): These metrics are reported per connector
type and provide total processing time (cumulative) and max processing time (single
request).
2) Executor processing metrics (Stats #C and #E): These metrics are reported per
executor type and provide measurements about queue delay and task processing
time.
3) Platform Services metrics (Stats #D): These filters provide global and webapp-level
metrics about overload protection, overhead processing time, and bindings.

7.2.1.3 Logs
The Tomcat application container used by the Application Delivery Platform issues logs to
the /var/broadworks/logs/tomcat directory. This log contains the container internal logs
and possibly the exceptions it encounters while executing the various web applications.
The general settings for Tomcat allow configuring the log level.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 19
 8 Configuration and Management

8.1 Configuration Modes

The Application Delivery Platform supports configuration locally through the CLI.
It is not all the configurations of a node that have been integrated in the Configuration
Agent. Some platform components still rely on configuration files. The following are
always managed locally:
 Maintenance task configuration
 Software Manager configuration

8.2 Profile Tuning

The profile tuning provides a list of predefined profile definitions based on a set of
identified deployment models. This flexibility eases the tailoring of a server to meet its
expected usage.
The Application Delivery Platform renders a CLI level for the profile tuning under the
ADP_CLI/System/ProfileTuning/GeneralSettings level.
The profile tuning has the following characteristics:
 This functionality is optional. That is, a server functions normally without an assigned
profile.
 The configuration action for a selected profile is immediate: when an administrator
selects a profile, the system immediately sets the parameters with the values fetched
from the profile.
 Only one profile is active at any given time. That is, the profiles are not stackable.
 The selected profile can be changed at any time. This action is immediate and
supersedes all previously tailored values.
 The selected profile is reloadable at any time. Such action may be used to restore a
server to the initial profile values (thus eliminating manual customization for the
specific parameters included in the reloaded profile).
 When a profile includes webapp centric data, the profile values apply upon deploying
a webapp even if the webapp was not present at the time of selecting a profile.
 This is the only mechanism available for tuning the Java Garbage Collection (GC)
parameters.
 It is not possible to revert or undo a profile. The CLI only indicates the profile that is
currently applied. To go back to a known profile, clear the existing profile and re-apply
the desired profile.

8.2.1 Profile Characterization

The Tomcat HttpNio executors are the primary terminations for all incoming HTTP
connections that include both blocking and streaming requests. The number of
processing threads allocated to Tomcat encompasses both traffic types and reflects the
expected usage for each.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 20
 The following table captures the targeted characteristics when identifying the needs for a
profile. In an effort to ease the documentation, the table includes only groups of
parameters and targeted characteristics rather than a list of specific parameters and
values.
Profile Type Non Real-Time Real-Time XSI

Server Parameter Input Targeted Content

Type Group parameters

ADP Garbage  Memory  Disable concurrent  Enables  Enables

Collection  CPU GC. concurrent GC concurrent GC
(tomcat) Counts  Use values similar to (parallel GC (parallel GC
existing defaults. threads @ 100% threads @
of CPU Counts). 100% of CPU
 Same value for Counts).
heap min and  Same value for
heap max. heap min and
 Fixed new size heap max.
generation @  Fixed new size
100% overall generation @
heap size. 100% overall
heap size.

Tomcat None Use values similar to Targeted Targeted

existing defaults. parameters: parameters:
 Global session  Max
timeout. connections.
 Per webapp  Max queued
session timeout. connections.
 Max threads per  HTTP NIO
connector type. threads
min/max.

Based on these characteristics, the following profiles are available:

 ADP non real-time.
 ADP real-time.
 The XSI profile is targeted for ADPs where the XSI applications are deployed.
 A default profile that corresponds to the factory config settings is also available.

8.2.2 CLI Level

The Profile Tuning CLI level provides the typical get and apply commands. In addition, it
provides a command named describe that prints the list of changes expected from
applying a specific profile. When the describe command is used, there is no configuration
change applied to the system. This is the key difference between the describe and apply
commands.
Following is an example of describing the real-time profile tuning.
ADP_CLI/System/ProfileTuning/GeneralSettings> help describe
This command is used to print the configuration changes performed by a
profile. The printed output lists the difference between the current
values stored within the configuration and the new values that would be
set by applying the profile. No configuration changes are applied.

Parameters description:
profileTuningName: This parameter specifies the name of the selected
profile tuning.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 21
 ======================================================================
describe
<profileTuningName>, Choice = {default, realTime, nonrealtime, xsi}

ADP_CLI/System/ProfileTuning/GeneralSettings> describe realTime

This is a description of the realTime profile. The configuration is not
changed by this command.
/Applications/WebContainer/Tomcat/Executors/CTI/ThreadPool
Modifies, min: 200 to 400
Modifies, max: 200 to 400
/Applications/WebContainer/Tomcat/Executors/HTTPNio/ThreadPool
Preserves, min: 166
Preserves, max: 1666
/Applications/WebContainer/Tomcat/SessionManagement/Server
Modifies, sessionTimeout: 1800 to 600
/Applications/WebContainer/Tomcat/SessionManagement/Webapps
Modifies, sessionTimeout[Xsi-Actions]: <nil> to 600
/Interface/Http/GeneralSettings
Modifies, keepAliveTimeout: 5 to 4
Preserves, maxConnections: 1666
Preserves, maxQueuedConnections: 833
Preserves, pollerThreadCount: 2

The following values are not exposed through the CLI

Modifies, /Applications/WebContainer/Tomcat GC: Parallel to Concurrent
Modifies, /Applications/WebContainer/Tomcat heap size: Variable to
Fixed

No configuration changes have actually been performed.

ADP_CLI/System/ProfileTuning/GeneralSettings>

8.3 WebApplication Threading

Processing of HTTP requests within web applications is performed on threads provided by
the underlying platform components (WebContainer and BWCommunicationUtility). Web
Applications can have internal threads as needed but the main processing threads are
those provided by the platform. The threading service is provided by the various
“Executors” provided at the platform level and illustrated in the preceding Web Container
Assembly figure.
A distinct executor is available at each input/output location. Each executor can be
individually configured for the needs of the interface it serves. The WebContainer
manages the following external interfaces: HTTPNIO, and CTI whereas the
BWCommunicationUtility manages the Open Client Interface-Provisioning (OCI-P) and
Open Client Interface-Call Control (OCI-C) interfaces. Refer to the following subsections
for specific details about these executors.

8.3.1 General Concept

An executor is a means of binding and managing resources consumed when executing a
collection of tasks. It is composed of a thread pool used to execute required tasks and a
queue where tasks wait to be executed. To address the level of flexibility expected from
the Application Delivery Platform, the following configuration parameters are supported for
each executor:
 minPoolSize: defined as the minimum number of live threads (busy or idle) kept in the
pool at any time (excluding startup transients).

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 22
  maxPoolSize: defined as the maximum number of live threads (busy and idle)
allowed in the pool.
 keepAliveTime: defined as the amount of idle time before an excess thread is
terminated.
 queueCapacity: defined as the maximum number of tasks that can be queued while
waiting for other tasks to complete their execution. The capacity can be unlimited (left
unspecified), disabled (0 capacity,) or fixed.
Based on the previous parameters, the following approach is used when processing tasks
(for example, processing an incoming http request):
 The actual pool size is automatically adjusted based on the minPoolSize and the
maxPoolSize. When a new task is submitted and fewer than minPoolSize threads are
running, the system allocates a new thread to handle the request, even if other worker
threads are idle. If there are more than minPoolSize but less than maxPoolSize
threads running, the system allocates a new thread only if the queue is full or disabled
(as expressed by the actual queue size).
 Furthermore, if the pool currently has more than minPoolSize threads, excess threads
will be terminated if they have been idle for more than the keepAliveTime. This
provides a means of reducing resource consumption when the pool is not being
actively used. If the pool becomes more active later, new threads will be allocated.
Note that the keep-alive policy applies only when there are more than minPoolSize
threads.
As a result of this behavior, the system rejects a request when the queue is full and the
actual pool size equals maxPoolSize.
The queue capacity can be left unspecified, meaning unlimited queuing. In that case, the
queuing capacity is implicitly limited by the total memory capacity available to the
WebContainer. The queue capacity can be set to 0, effectively disabling the queuing
function (the queue can be thought of as being always full). In that case, new tasks are
immediately rejected if no thread is available in the pool and the pool size has already
reached its maxPoolSize.

8.3.2 Typical Configurations

Although providing a great deal of configuration flexibility, executors are typically
configured following three operational models:
 Fixed threading: The thread pool is fixed for optimum processing throughput; waiting
is acceptable for momentary excess demand. [minPoolSize=maxPoolSize,
queueCapacity > 1].
 On-demand threading: The number of threads is adjusted with demand; waiting is
acceptable for momentary excess demand. [minPoolSize<maxPoolSize,
queueCapacity > 1]. This thread pool model limits the thread creation and ties heap
usage more closely to actual instantaneous traffic.
 Adjustable threading: The number of threads is adjusted with demand, waiting is
not acceptable. [minPoolSize < maxPoolSize, queueCapacity=0].

8.3.2.1 Configuration Through CLI

Following is an example of configuring an OCI-C executor (for both the queue and thread
pool).
ADP_CLI/System/CommunicationUtility/DefaultSettings/Executors/OCIC/Queue>
help set
The command is used to modify Queue settings.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 23
 Parameters description:
attribute: The name of an attribute to modify.
capacity : This parameter specifies the maximum queue capacity. Tasks are
queued while waiting for an available thread. When the value is
not set, queuing is unlimited and tasks are queued as long as
there is enough memory available.

======================================================================
set
<attribute>, Multiple Choice = {capacity}
<capacity>, Integer {1 to 2147483647}

ADP_CLI/System/CommunicationUtility/DefaultSettings/Executors/OCIC/Queue> set
capacity 25000
*** Warning: Broadworks needs to be restarted for the changes to take effect
***

ADP_CLI/System/CommunicationUtility/DefaultSettings/Executors/OCIC/Queue> get
capacity = 25000

ADP_CLI/System/CommunicationUtility/DefaultSettings/Executors/OCIC/Queue>

ADP_CLI/System/CommunicationUtility/DefaultSettings/Executors/OCIC/ThreadPool>
help set
This command is used to modify the thread pool settings.

Parameters description:
attribute : The name of an attribute to modify.
min : This parameter specifies the minimum number of threads to keep
in steady state. Lower thread counts are possible during
initialization.
max : This parameter specifies the maximum number of threads this
pool
can contain.
keepALiveTime: This parameter specifies the amount of idle time before an
excess thread is terminated.

======================================================================
set
<attribute>, Multiple Choice = {min, max, keepALiveTime}
<min>, Integer {1 to 10000}
<max>, Integer {1 to 10000}
<keepALiveTime>, Integer {1 to 3600}

ADP_CLI/System/CommunicationUtility/DefaultSettings/Executors/OCIC/ThreadPool> set
min 5 max 5 keepALiveTime 30
*** Warning: Broadworks needs to be restarted for the changes to take effect
***

ADP_CLI/System/CommunicationUtility/DefaultSettings/Executors/OCIC/ThreadPool> get
min = 5
max = 5
keepALiveTime = 30

ADP_CLI/System/CommunicationUtility/DefaultSettings/Executors/OCIC/ThreadPool>

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 24
 8.4 Configuration of BWCommunicationUtility
The BWCommunicationUtility provides the framework on which web applications can be
built. It can be configured with default settings that are inherited by all web applications.
However, web applications are not forced to use the default settings. Instead, they can
override them with values that are more appropriate to their needs. The
BWCommunicationUtility default settings are configurable through the CLI, under the
ADP_CLI/System/CommunicationUtility/DefaultSettings level.

8.4.1 Integration Mode

The integration mode used to communicate with other Cisco BroadWorks servers is
controlled by the mode attribute. The mode can be set to either “NS” or “AS”, where NS
should be used when a Network Server is used to front end one or multiple Application
Server clusters, and AS should be used when connecting to a single Application Server
cluster without a Network Server.
In NS mode, the Network Server cluster address must be provided as well as the
OCI-P/OCI-C ports to use. Note that in NS mode, all Application Server clusters must be
using the same OCI-P port.
In AS mode, the primary and secondary Application Server addresses are configurable, as
well as the Open Client Interface ports to use for OCI-P.

NOTE: OCI-C is not supported in this mode.

8.4.2 Provision to Secondary

The Application Delivery Platform can be configured to give preference to the secondary
Application Server when sending OCI-P messages to an Application Server cluster. The
provisionToSecondary attribute controls this behavior.

8.4.3 Communication Settings

The following settings affect the communication channels to other Cisco BroadWorks
servers:
 reconnectionTimerSecs – The number of seconds to wait between reconnection
attempts to a Cisco BroadWorks server.
 responseTimeoutSecs – The number of seconds to wait for a response from a Cisco
BroadWorks Server after issuing a message.
 useSecureBCCT – Only secure BCCT connections are used for OCI-P and OCI-C.

8.4.4 Overflow Protection Settings

The BWCommunicationUtility allows rate protection per web application for user
HTTP/HTTPS requests.
The rate is controlled by first setting the calculation period in seconds using the
transactionLimitPeriodSecs attribute. Then, the number of requests allowed per user
during the same period is determined by the userTransactionLimit.
For example:
 transactionLimitPeriodSecs = 10 seconds
 userTransactionLimit = 5

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 25
  user rate = 5 requests every 10 seconds
The rates are computed per web application.
Note that section 8.5.4 Overload Protection describes another mechanism that provides
overload controls before authentication takes place.

8.4.5 Executors
Individual executors are available for OCI-C and OCI-P processing. Each Web App that
requires an executor gets a distinct instance. However, all instances are configured using
the same settings.
The recommended operating model for these executors is the fixed threading
configuration: minPoolSize=maxPoolSize, with queueCapacity > 1.
These executors are configurable from the
ADP_CLI/System/CommunicationUtility/DefaultSettings/Executors level.

8.4.6 External Authentication Support

Cisco BroadWorks user authentication can be delegated to an external entity, and the
administrator has the choice of either Web-based Authentication Server (WAS), Kerberos,
LDAP, or RADIUS as the selected external authentication mechanism. The administrator
also has the alternative of using an embedded agent.
For more information, see the Cisco BroadWorks External Portal Integration Guide.

8.4.7 Name Service

The Application Delivery Platform integrates the Cisco BroadWorks Name Service into the
BWCommunicationUtility. Webapps and the Open Client Server (OCS) application also
benefit from this mechanism since they go through the Cisco BroadWorks Name Service
for name resolution.

8.4.7.1 NS Location URL

The NS location URL uses the following syntax.
scheme://hostname:[port]

When the NS location URL specifies HTTPS as the scheme, the Application Delivery
Platform initiates a secured HTTP connection (using Transport Layer Security
[TLS]/Secure Sockets Layer [SSL]) to the server. Otherwise, the Application Delivery
Platform initiates an unsecured HTTP connection.
SRV lookup for the nslocation service is performed when the port is omitted from the
configured locationServiceURL. When using this option, the locationServiceURL’s
hostname is taken as the domain name for an SRV lookup on the following service. The
result from the lookup considers the weight and cost associated with the service.
_nslocation._tcp.<domain>

If the port is omitted from the configured locationServiceURL but no SRV records are
found, the URL is used as-is with the default HTTP port (80) or HTTPS port (443), as
determined by the URL scheme to perform an A/AAAA lookup.
Alternatively, to immediately perform an A/AAAA lookup and, consequently, prevent a
Service Locator (SRV) lookup, the port needs to be specified explicitly in the URL.
The following example shows a URL that is resolved using SRV lookups.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 26
 https://nsdomain.com

When using this syntax, a lookup on the following SRV record occurs.
_nslocation._tcp.nsdomain.com SRV 1 10 1234 nsdomain1.broadsoft.com
_nslocation._tcp. nsdomain.com SRV 2 10 567 nsdomain2.broadsoft.com

These records result in the following URLs that reflect the weight and cost associated with
the service.
https://nsdomain1.broadsoft.com:1234
https://nsdomain2.broadsoft.com:567

If no SRV records are found, the following URL is used instead to perform an A/AAAA
lookup.
https://nsdomain.com:443

8.5 Configuration of WebContainer

The WebContainer CLI level allows for configuration of Tomcat. The configuration spans
several distinct levels, which are documented in the following subsections.

8.5.1 General Settings

The WebContainer general setting is configurable through the CLI, under the level
ADP_CLI/Applications/WebContainer/Tomcat/GeneralSettings. In particular, it allows
configuring the following parameters:
 uriEncoding: This parameter specifies the character encoding for URI definition.
 authenticationEncoding: This parameter specifies the character encoding used to
decode the username and password coming from the authenticate header when
using basic authentication.
 statisticsRefreshPeriod: This parameter specifies the frequency (in seconds) at which
Cisco BroadWorks fetches Performance Measurements (PMs) within Tomcat.
 maxHttpHeaderSize: This parameter specifies the limit (in bytes) on the allowed size
of an HTTP request header field.
 xFrameOptionsSameOrigin: This parameter enables the addition of the X-Frame-
Options HTTP Header (defined by RFC 7034) to all HTTP responses, with a value of
“SAMEORIGIN”. This is used to improve the protection of web applications against
clickjacking.
 blockContentTypeSniffingEnabled: This parameter enables the addition of the
X-Content-Type-Options HTTP header to all HTTP responses. This header blocks
content-type sniffing.
 sendReasonPhrase: This parameter controls whether the reason phrase is present in
the response.
 jvmRoute: This parameter specifies the name of this server instance that will be
appended to the JSESSIONID in HTTP responses.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 27
 8.5.1.1 HTTP Strict Transport Security Headers
The WebContainer can be configured to add the HTTP Strict Transport Security (HSTS)
header to its responses. This allows compatible user agents to enforce the use of secure
connections, as specified in RFC 6797. The HSTS settings can be configured in the CLI
under the ADP_CLI/Applications/WebContainer/Tomcat/GeneralSettings/HSTS level. For
earlier releases, the same settings are available as container options. The following
parameters are available:
 enabled: This parameter controls whether the HTTP Strict-Transport-Security header
will be included in all HTTP responses.
 maxAgeInSeconds: This parameter specifies the amount of time in seconds the
HTTP Strict-Transport-Security directive will be heeded by the connecting clients.
 includeSubdomains: This parameter controls whether the HTTP Strict-Transport-
Security directive should be applied to all subdomains of the current domain by the
connecting clients.

8.5.2 Logging
The log settings for the Tomcat Application container are configurable through the CLI
under the ADP_CLI/Applications/WebContainer/Tomcat/Logging level. It uses the
common Cisco BroadWorks logging mechanism for input and output channels.
The Tomcat input channel includes the following names:
 Generic
 NameService
 TomcatCore
 CtiConnector
 GcLog
 SMAP
 ExternalAuthenticator
By default, the Tomcat application container used by the Application Delivery Platform
issues logs in the /var/broadworks/logs/tomcat directory. This log contains the container
internal logs and possibly the exceptions it encounters while executing the various web
applications.
The Tomcat output channel follows the typical Cisco BroadWorks output channel pattern.
Following is an example of setting the TomcatCore log level to “FieldDebug”.
ADP_CLI/Applications/WebContainer/Tomcat/Logging/InputChannels> h set
This command is used to modify input channels-related attributes.

Parameters description:
name : This parameter specifies the name of the logging input channel.
attribute: The name of an attribute to modify.
enabled : This parameter turns the logging to the logging input channel on
and
off.
severity : This parameter specifies the severity level of the logging input
channel.

======================================================================
set
<name>, Choice = {Generic, NameService, TomcatCore,
ExternalAuthenticator, CtiConnector, GcLog, SMAP}

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 28
 <attribute>, Multiple Choice = {enabled, severity}
<enabled>, Choice = {false, true}
<severity>, Choice = {Debug, FieldDebug, Info, Notice, Warn}

ADP_CLI/Applications/WebContainer/Tomcat/Logging/InputChannels> set
TomcatCore enabled true severity FieldDebug
*** Warning: BroadWorks needs to be restarted for the changes to take
effect ***

ADP_CLI/Applications/WebContainer/Tomcat/Logging/InputChannels> get
Name Enabled Severity
============================================
Generic true
NameService true Info
TomcatCore true FieldDebug
ExternalAuthenticator true Info
CtiConnector true Info
GcLog true Info
SMAP false

7 entries found.

ADP_CLI/Applications/WebContainer/Tomcat/Logging/InputChannels>

8.5.2.1 HTTP Access Logs

The configuration related to access logs can be changed from the CLI level
ADP_CLI/Applications/WebContainer/Tomcat/AccessLogs.

8.5.3 Executors
Individual executors are available for each access point:
 HTTPNIO: Blocking HTTP requests and NonBlocking HTTP requests used for
streaming.
 CTI: CTI interface.
The recommended operating model for the CTI executors is the fixed threading
configuration described in section 8.3.2 Typical Configurations.
(minPoolSize=maxPoolSize, with queueCapacity > 1).
The recommended operating model for the HTTPNIO executors is the on-demand
threading configuration described in section 8.3.2 Typical Configurations.
(minPoolSize<maxPoolSize, with queueCapacity > 1).
These executors are configurable from the
ADP_CLI/Applications/WebContainer/Tomcat/Executors level.

8.5.4 Process Metrics

The process metrics targets the Java Virtual Machine (JVM) metrics that is used by many
Cisco BroadWorks servers.
The JVM metrics provide several built-in statistics (using JVM MBeans) to report on key
performance factors.
The Application Delivery Platform renders a CLI level for process metrics under the
ADP_CLI/Applications/WebContainer/Tomcat/JVMStatsCollector/GeneralSettings level.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 29
 Data collection is controlled by setting the enabled attribute and the data frequency is
controlled by setting the period in seconds using the statisticsRefreshPeriod attribute.
 enabled: This parameter enables or disables data collection for JVM statistics.
 statisticsRefreshPeriod: The frequency (expressed in seconds) at which Cisco
BroadWorks fetches PMs from the JVM MBeans. The default value is 5 seconds. In
addition to the regular polling, the system refreshes the PMs after every full garbage
collection 1.

8.5.4.1 CLI Level

Following is an example of setting the refresh period for the JVM Stats Collector.
ADP_CLI/Applications/WebContainer/Tomcat/JVMStatsCollector/GeneralSettings>
help set
The command is used to modify JVM statistics collector general settings.

Parameters description:
attribute : The name of an attribute to modify.
enabled : This parameter enables or disables data collection
for
JVM statistics
statisticsRefreshPeriod: This parameter specifies the frequency at which
BroadWorks fetches PMs from JVM Mbeans

======================================================================
set
<attribute>, Multiple Choice = {enabled, statisticsRefreshPeriod}
<enabled>, Choice = {false, true}
<statisticsRefreshPeriod>, Integer {1 to 86400}

ADP_CLI/Applications/WebContainer/Tomcat/JVMStatsCollector/GeneralSettings>
ADP_CLI/Applications/WebContainer/Tomcat/JVMStatsCollector/GeneralSettings>
set enabled true statisticsRefreshPeriod 10
*** Warning: Broadworks needs to be restarted for the changes to take effect
***

ADP_CLI/Applications/WebContainer/Tomcat/JVMStatsCollector/GeneralSettings>
get
enabled = true
statisticsRefreshPeriod = 10

ADP_CLI/Applications/WebContainer/Tomcat/JVMStatsCollector/GeneralSettings>

8.5.5 Overload Protection

The BWCommunicationUtility allows rate protection at the Web Container level. It is
registered globally and allows overload controls before authentication takes place. This
mechanism provides both global and webapp-level protection.
The Application Delivery Platform renders a CLI level for the overload protection under the
ADP_CLI/Applications/WebContainer/Tomcat/OverloadProtection/Server and ADP_CLI/
Applications/WebContainer/Tomcat/OverloadProtection/Webapps levels.
The Server level controls the number of requests allowed globally and the Webapps level
controls the number of requests allowed per webapp.
Each rate is controlled by first setting the calculation period in seconds using the period
attribute. Then the total number of requests allowed during this period is determined by
the limit attribute.

1 There is a notification sent upon completion of a full garbage collection.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 30
 For example:
 server.period = 10 seconds
 server.limit = 1000
 webapp.name = PublicReporting
 webapp.period = 10 seconds
 webapp.limit = 200
 global rate = 1000 requests every 10 seconds
 PublicReporting webapp rate = 200 requests every 10 seconds

8.5.5.1 CLI Level

Following is an example of limiting the number of request for the Xsi-Actions webapp.

1) If the web application does not exist, add by:

ADP_CLI/Applications/WebContainer/Tomcat/OverloadProtection/Webapps> help
add
This command is used to add the web application overload protection
entry.

Parameters description:
name : This parameter specifies the name of the web application.
period: This parameter specifies the duration expressed in seconds during
which
the total number of transactions is limited for the overall
server.
limit : This parameter specifies the maximum number of requests to be
allowed
during the specified period duration.

======================================================================
add
<name>, Choice = {<list of installed applications>}
<period>, Integer {1 to 300}
<limit>, Integer {1 to 65535}

ADP_CLI/Applications/WebContainer/Tomcat/OverloadProtection/Webapps> add
Xsi-Events 1 50

2) If the web application exists, modify it by:

ADP_CLI/Applications/WebContainer/Tomcat/OverloadProtection/Webapps> help set

The command is used to modify per web application overload protection
settings.

Parameters description:
name : This parameter specifies the name of the web application.
attribute: The name of an attribute to modify.
period : This parameter specifies the duration expressed in seconds during
which the total number of transactions is limited for the overall
server.
limit : This parameter specifies the maximum number of requests to be
allowed during the specified period duration.

======================================================================
set
<name>, Choice = {{<list of installed applications>}

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 31
 <attribute>, Multiple Choice = {period, limit}
<period>, Integer {1 to 300}
<limit>, Integer {1 to 65535}

ADP_CLI/Applications/WebContainer/Tomcat/OverloadProtection/Webapps>
ADP_CLI/Applications/WebContainer/Tomcat/OverloadProtection/Webapps> set Xsi-
Events period 1 limit 50
*** Warning: Broadworks needs to be restarted for the changes to take effect
***

ADP_CLI/Applications/WebContainer/Tomcat/OverloadProtection/Webapps> get
Name Period Limit
========================================
Xsi-Actions 1 100
Xsi-Events 1 50
Xsi-MMTel 1 100

3 entries found.

8.5.6 Session Management

Session management allows specifying session timeouts globally and per web app
(optionally).
The Application Delivery Platform renders a CLI level for the session management under
the ADP_CLI/Applications/WebContainer/Tomcat/ SessionManagement/Server and
ADP_CLI/ Applications/WebContainer/Tomcat/ SessionManagement/Webapps levels.
Data collection is controlled by setting the sessionTimeout attribute.
 sessionTimeout: a duration expressed in seconds after which an inactive session
times out. The default is 30.
The parameter is configurable per individual webapp (identified by the display name).
When set, the value supersedes the value specified globally for the webapp. When there
are multiple instances of a given webapp, they all share the same settings. That is, the
same session timeout setting applies to all instances.
 sessionTimeout (webapp): a webapp-specific duration expressed in seconds after
which an inactive session times out. By default, this parameter is empty for all
configured webapps.

8.5.6.1 CLI Level

Following is an example of setting the Xsi-Actions timeout to “1800”.

1) If the web application does not exist, add by:

ADP_CLI/Applications/WebContainer/Tomcat/SessionManagement/Webapps> help add

This command is used to add the web application session management entry.

Parameters description:
name : This parameter specifies the name of the web application.
attribute : Name of the webapp.
sessionTimeout: This parameter specifies a web application specific duration
expressed in seconds after which an inactive session times
out.

======================================================================
add
<name>, Choice = {{<list of installed applications>}

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 32
 [<attribute>, Multiple Choice = {sessionTimeout}]
<sessionTimeout>, Integer {1 to 86400}

ADP_CLI/Applications/WebContainer/Tomcat/SessionManagement/Webapps> add Xsi-

Actions sessionTimeout 1200
*** Warning: BroadWorks needs to be restarted for the changes to take effect
***

2) If the web application exists, modify it by:

ADP_CLI/Applications/WebContainer/Tomcat/SessionManagement/Webapps> help set

The command is used to modify per web application session management
settings.

Parameters description:
name : This parameter specifies the name of the web application.
attribute : The name of an attribute to modify.
sessionTimeout: This parameter specifies a web application specific duration
expressed in seconds after which an inactive session times
out.

======================================================================
set
<name>, Choice = {<list of installed applications>}
<attribute>, Multiple Choice = {sessionTimeout}
<sessionTimeout>, Integer {1 to 86400}

ADP_CLI/Applications/WebContainer/Tomcat/SessionManagement/Webapps> set Xsi-

Actions sessionTimeout 1200
*** Warning: Broadworks needs to be restarted for the changes to take effect
***

ADP_CLI/Applications/WebContainer/Tomcat/SessionManagement/Webapps> get
Name Session Timeout
==============================
Xsi-Actions 1200

1 entry found.

8.5.7 Thresholds
This section describes the list of configurable thresholds. For the list of SNMP traps
generated upon a threshold crossing, see section 8.6.4 Thresholds.

8.5.7.1 Executors
For each of the executor name (CTI and HTTPNIO), the Application Delivery Platform
provides the ability to set the following thresholds.
Executor Queue Usage Ratio
The executor queue usage ratio is defined as a percentage using the following formula:
EventQueueCount / queueCapacity * 100. By default, this threshold defines the arm level
to be 90 and the clear level to be 81. This threshold is enabled.
The Application Delivery Platform renders a CLI level for this threshold under the
ADP_CLI/Applications/WebContainer/Tomcat/Executors/<executorName>/Queue/SizeTh
reshold level.
The following is an example of setting the arm value to “88” and the reset value to “78” for
the HTTPNio executor.
ADP_CLI/Applications/WebContainer/Tomcat/Executors/HTTPNio/Queue/SizeThreshold>
help set

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 33
 This command is used to modify the size threshold settings.

Parameters description:
attribute : The name of an attribute to modify.
enabled : This parameter determines whether a threshold is active.
armValue : This parameter specifies a value for enabling a threshold crossing.
resetValue: This parameter specifies a value for clearing a threshold crossing.

======================================================================
set
<attribute>, Multiple Choice = {enabled, armValue, resetValue}
<enabled>, Choice = {false, true}
<armValue>, Integer {0 to 100}
<resetValue>, Integer {0 to 100}

ADP_CLI/Applications/WebContainer/Tomcat/Executors/HTTPNio/Queue/SizeThreshold> set
armValue 88 resetValue 78
*** Warning: BroadWorks needs to be restarted for the changes to take effect ***

ADP_CLI/Applications/WebContainer/Tomcat/Executors/HTTPNio/Queue/SizeThreshold> get
enabled = true
armValue = 88
resetValue = 78

ADP_CLI/Applications/WebContainer/Tomcat/Executors/HTTPNio/Queue/SizeThreshold>

Executor Queue Latency

The executor queue latency is defined as an absolute value and represents the number of
requests that are currently queued while waiting for other tasks to complete during
execution. By default, this threshold defines the arm level to be 2500 and the clear level to
be 2000. This threshold is enabled.
The Application Delivery Platform renders a CLI level for this threshold under the
ADP_CLI/Applications/WebContainer/Tomcat/Executors/<executorName>/Queue/Latenc
yThreshold level.
Executor Thread Pool Processing Time
The executor thread pool processing time is defined as an absolute value and represents
the execution time taken by a task to complete. By default, this threshold defines the arm
level to be 2500 and the clear level to be 2000. This threshold is enabled.
The Application Delivery Platform renders a CLI level for this threshold under the
ADP_CLI/Applications/WebContainer/Tomcat/Executors/<executorName>/ThreadPool/Pr
ocessingTimeThreshold/ level.
Executor Thread Pool Busy Ratio
The executor thread pool busy ratio is defined as a percentage using the following
formula: threadsBusy / maxPoolSize * 100. By default, this threshold defines the arm level
to be 95 and the clear level to be 85. This threshold is enabled.
The Application Delivery Platform renders a CLI level for this threshold under the
ADP_CLI/Applications/WebContainer/Tomcat/Executors/<executorName>/ThreadPool/
UsageThreshold/ level.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 34
 8.5.7.2 Process Metrics
Heap and Nonheap Memory Usage Ratios
The Application Delivery Platform provides the ability to set a threshold for the heap and
nonheap memory usage ratios. By default, these thresholds define the arm level to be 90
and the clear level to be 81. These thresholds are enabled.
The heap memory usage ratio is defined as a percentage and represents the heap
memory usage after a full garbage collection.
The nonheap memory usage ratio is defined as a percentage and represents the nonheap
memory usage after a full garbage collection.
The Application Delivery Platform renders a CLI level for this threshold under the
ADP_CLI/Applications/WebContainer/Tomcat/JVMStatsCollector/HeapUsageThreshold
level.
The following is an example of setting the arm value to “88” and the reset value to “78” for
the heap memory usage threshold.
ADP_CLI/Applications/WebContainer/Tomcat/JVMStatsCollector/HeapUsageThreshold> help
set
This command is used to modify the heap usage threshold settings.

Parameters description:
attribute : The name of an attribute to modify.
enabled : This parameter determines whether a threshold is active.
armValue : This parameter specifies a value for enabling a threshold crossing.
resetValue: This parameter specifies a value for clearing a threshold crossing.

======================================================================
set
<attribute>, Multiple Choice = {enabled, armValue, resetValue}
<enabled>, Choice = {false, true}
<armValue>, Integer {0 to 100}
<resetValue>, Integer {0 to 100}

ADP_CLI/Applications/WebContainer/Tomcat/JVMStatsCollector/HeapUsageThreshold> set
armValue 88 resetValue 78
*** Warning: Broadworks needs to be restarted for the changes to take effect ***

ADP_CLI/Applications/WebContainer/Tomcat/JVMStatsCollector/HeapUsageThreshold> get
enabled = true
armValue = 88
resetValue = 78

ADP_CLI/Applications/WebContainer/Tomcat/JVMStatsCollector/HeapUsageThreshold>

8.6 Management of WebContainer

The combination of flexible configurations and strong reporting capabilities allows for
configuring specific thresholds with predefined values. Upon threshold crossing, the
system generates SNMP traps to report this state to the network management layers.
The Application Delivery Platform allows enabling (or disabling) data collection and the
frequency of these metrics as well as customizing thresholds.
From a network management layer, it is possible to collect the Performance
Measurements (PMs) and receive threshold crossing notifications.

8.6.1 Metric Groups

For a review of the metric groups, see section 7.2.1.2 WebContainer Metric Groups.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 35
 8.6.2 Sequence Diagrams
Using sequence diagrams, this section highlights key processing time metrics. They are
organized by connector and executor types.
The HttpNio connector may expose processing time that varies widely. The key difference
is the types of processing that the HttpNio connector handles since it supports both non-
streaming web application and persistent HTTP connection with two-way HTTP
streaming. For blocking request, the processing blocks until it transmits a response
whereas for streaming request, the processing uses threads sporadically as needed up
until the response is transmitted. For the CTI connector, the processing returns
immediately after an event was sent since all the requests are non-blocking. The
sequence diagrams also capture the implications of the OCI executor that is involved
when receiving responses from other Cisco BroadWorks servers.

Tomcat Core
occurs here

NIO NIO OCI OCI BW

HTTPNIO Platform Web
Executor Executor Executor Executor Comm
Connector Services app
Queue Thread Thread Queue Utility

Comet
Events

request

queue
Waiting
Time
HTTP

OCIP
Request

Other BW
Servers
Connector
processing
Time
Task
Processing OCIP
Time application
processing Responses Response
time i/o
queue
Waiting
Responses Time
i/o Task
Processing
Time

response

Figure 5 HTTP Blocking Sequence Diagram (HttpNiO)

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 36
 Tomcat Core
occurs here

NIO NIO OCI OCI BW

HTTPNIO Platform Web
Executor Executor Executor Executor Comm
Connector Services app
Queue Thread Thread Queue Utility

Comet
Events

request

queue
Waiting
Time
HTTP

Task
Processing OCIC
Time Request

Other BW
queue

Servers
Task Waiting OCIC
Connector Processing Time Responses
processing Time
Time Responses
i/o
application
processing
time

end
response

Figure 6 HTTP Streaming Sequence Diagram (HttpNio)

Tomcat Core
occurs here

CTI CTI OCI OCI BW

CTI Platform Web
Executor Executor Executor Executor Comm
Connector Services app
Queue Thread Thread Queue Utility

Comet
Events

Proprierary,
XML-based request

queue
Waiting
Time

Task
Processing OCIC
Time Request
Other BW

queue
Servers

Task Waiting OCIC

Connector Processing Time Responses
processing Time
Time Responses
i/o
application
processing
time

response end

Figure 7 CTI Sequence Diagram

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 37
 These diagrams highlight the following metrics. Note that only the object identifiers (OIDs)
pertinent to the key metrics are presented here. For complete details, see the
Performance Measurements Interface Specification document for the applicable Cisco
BroadWorks server.

8.6.2.1 Connector Processing Time

This statistic measures the processing time spent in the connector. The system does not
report an instant value. Instead, it reports the cumulative time and the maximum value for
an individual request. The BW-WebContainer MIB reports this statistic with the following
OIDs:
 bwWebContainer.connectors.bwConnectorTotalProcessingTime
 bwWebContainer.connectors.bwConnectorMaxProcessingTime
These OIDs are available from the following CLI level.
ADP_CLI/Monitoring/PM/WebContainer> cd connectors;get
bwWebContainer/connectors/
------------------------------------------------------------------------------
bwWebContainer/connectors/
------------------------------------------------------------------------------
bwConnectorTable:

(1) bwConnectorIndex
(2) bwConnectorName
(3) bwConnectorExecutorName
(4) bwConnectorRequestCount
(5) bwConnectorBytesRx
(6) bwConnectorBytesTx
(7) bwConnectorTotalProcessingTime
(8) bwConnectorMaxProcessingTime

(1) (2) (3) (4) (5) (6) (7) (8)

1 [localhost/127.0.0.1]:8010 httpnio 0 0 0 0 0

ADP_CLI/Monitoring/PM/WebContainer>

8.6.2.2 Executors
The Queue Waiting Time and Task Processing Time are part of the executor metrics.
The Queue Waiting Time statistic reports the time spent waiting in the executor queue. A
delay occurs when the executor threads are all busy processing other events. This metric
is reported in a MIB table identified by the executor type. The BW-WebContainer MIB
reports this statistic with the following OID:
 bwWebContainer.executors.executorTable.bwExecutorQueueWaitingTime
The Task Processing time statistic reports the processing time spent in the executor
thread. This metric is reported in a MIB table identified by the executor type. The system
does not report an instant value. Instead, it tracks the minimum, average, and maximum
values. The BW-WebContainer MIB reports this statistic with the following OIDs:
 bwWebContainer.executors.executorTable.bwExecutorTaskProcessingTimeMin
 bwWebContainer.executors.executorTable.bwExecutorTaskProcessingTimeAvg
 bwWebContainer.executors.executorTable.bwExecutorTaskProcessingTimeMax

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 38
 These OIDs are available from the following CLI level.
ADP_CLI/Monitoring/PM/WebContainer> cd executors;get
------------------------------------------------------------------------------
bwWebContainer/executors/
------------------------------------------------------------------------------
*bwExecutorReset
bwExecutorTable:

(1) bwExecutorIndex
(2) bwExecutorName
(3) bwExecutorQueueCapacity
(4) bwExecutorQueueSize
(5) bwExecutorQueueWaitingTimeAvg
(6) bwExecutorQueueWaitingTimeMin
(7) bwExecutorQueueWaitingTimeMax
(8) bwExecutorQueueWaitingTimeMaxTimestampMSB
(9) bwExecutorQueueWaitingTimeMaxTimestampLSB
(10) bwExecutorMinPoolSize
(11) bwExecutorMaxPoolSize
(12) bwExecutorThreadsBusy
(13) bwExecutorCompletedTaskCount
(14) bwExecutorThreadsAlive
(15) bwExecutorThreadsAliveMax
(16) bwExecutorTaskProcessingTimeAvg
(17) bwExecutorTaskProcessingTimeMin
(18) bwExecutorTaskProcessingTimeMax
(19) bwExecutorTaskProcessingTimeMaxTimestampMSB
(20) bwExecutorTaskProcessingTimeMaxTimestampLSB
(21) bwExecutorQueueWaitingTimeMaxTimestamp
(22) bwExecutorTaskProcessingTimeMaxTimestamp
(23) bwExecutorQueueWaitingTimeResetTS
(24) bwExecutorQueueWaitingTimeAvgCurrInt
(25) bwExecutorQueueWaitingTimeAvgLastInt
(26) bwExecutorQueueWaitingTimeMinCurrInt
(27) bwExecutorQueueWaitingTimeMinLastInt
(28) bwExecutorQueueWaitingTimeMinCurrIntTS
(29) bwExecutorQueueWaitingTimeMinLastIntTS
(30) bwExecutorQueueWaitingTimeMaxCurrInt
(31) bwExecutorQueueWaitingTimeMaxLastInt
(32) bwExecutorQueueWaitingTimeMaxCurrIntTS
(33) bwExecutorQueueWaitingTimeMaxLastIntTS
(34) bwExecutorTaskProcessingTimeResetTS
(35) bwExecutorTaskProcessingTimeAvgCurrInt
(36) bwExecutorTaskProcessingTimeAvgLastInt
(37) bwExecutorTaskProcessingTimeMinCurrInt
(38) bwExecutorTaskProcessingTimeMinLastInt
(39) bwExecutorTaskProcessingTimeMinCurrIntTS
(40) bwExecutorTaskProcessingTimeMinLastIntTS
(41) bwExecutorTaskProcessingTimeMaxCurrInt
(42) bwExecutorTaskProcessingTimeMaxLastInt
(43) bwExecutorTaskProcessingTimeMaxCurrIntTS
(44) bwExecutorTaskProcessingTimeMaxLastIntTS

(1) (2) (3) (4) (5) (6) (7) (8) (9) (10)
(11) (12) (13) (14) (15) (16) (17) (18) (19) (20)
(21) (22) (23) (24) (25)
(26) (27) (28) (29) (30)
(31) (32) (33)
(34) (35) (36) (37) (38) (39)
(40) (41) (42) (43) (44)
1 httpnio 20000 0 0 0 0 370 2681315361 166
1666 0 0 0 0 0 0 0 370 2681315361 Wed Jun
10 16:00:14 EDT 2020 Wed Jun 10 16:00:14 EDT 2020 Thu Jun 11 08:00:00 EDT 2020
0 0 0 0 Thu Jun 11 08:00:00 EDT 2020 Thu Jun 11 07:55:00 EDT 2020
0 0 Thu Jun 11 08:00:00 EDT 2020 Thu Jun 11 07:55:00 EDT 2020 Thu Jun 11
08:00:00 EDT 2020 0 0 0 0 Thu Jun 11 08:00:00 EDT 2020 Thu
Jun 11 07:55:00 EDT 2020 0 0 Thu Jun 11 08:00:00 EDT 2020 Thu Jun 11
07:55:00 EDT 2020

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 39
 ADP_CLI/Monitoring/PM/WebContainer>

8.6.2.3 Application Processing Time

This statistic reports the processing time spent in the web application. The system
does not report an instant value. Instead, it reports only the cumulative time. The
BW-WebContainer MIB reports this statistic with the following OID:
 bwWebContainer.applications.applicationResources.bwApplicationResourceTotalPro
cessingTime
This OID is available from the following CLI level.
ADP_CLI/Monitoring/PM/WebContainer> cd applications/applicationResources;get
bwWebContainer/applications/applicationResources/
------------------------------------------------------------------------------
bwWebContainer/applications/applicationResources/
------------------------------------------------------------------------------
bwApplicationResourcesTable:

(1) bwApplicationResourceIndex
(2) bwApplicationResourceWebAppName
(3) bwApplicationResourceRequestCount
(4) bwApplicationResourceTotalProcessingTime

(1) (2) (3) (4)

1 /dms 0 0

ADP_CLI/Monitoring/PM/WebContainer> >

8.6.3 Process Metrics

The process metrics targets the Java Virtual Machine (JVM) metrics that is used by many
Cisco BroadWorks servers.
The JVM metrics provide several built-in statistics (using JVM MBeans) to report
performance on key performance factors.
The BW-WebContainer MIB reports this statistic with the following OID:
 bwWebContainer.processMetrics

8.6.3.1 Memory
The OIDs for heap and nonheap memories are available from the following CLI levels.
ADP_CLI/Monitoring/PM/WebContainer> cd processMetrics/memory/heap;get
bwWebContainer/processMetrics/memory/heap/
------------------------------------------------------------------------------
bwWebContainer/processMetrics/memory/heap/
------------------------------------------------------------------------------
bwProcessMetricsHeapInitSize 226492416
bwProcessMetricsHeapMaxSize 226492416
bwProcessMetricsHeapUsed 60406032
bwProcessMetricsHeapUsedMax 92134800
bwProcessMetricsHeapCommitted 226492416
bwProcessMetricsHeapLastPostCollectionSize 60496664

ADP_CLI/Monitoring/PM/WebContainer>

ADP_CLI/Monitoring/PM/WebContainer> cd memory/nonheap;get
bwWebContainer/processMetrics/memory/nonheap/
------------------------------------------------------------------------------
bwWebContainer/processMetrics/memory/nonheap/
------------------------------------------------------------------------------

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 40
 bwProcessMetricsNonHeapInitSize 24313856
bwProcessMetricsNonHeapMaxSize 318767104
bwProcessMetricsNonHeapUsed 34920144
bwProcessMetricsNonHeapUsedMax 38417936
bwProcessMetricsNonHeapCommitted 35192832
bwProcessMetricsNonHeapLastPostCollectionSize 0

ADP_CLI/Monitoring/PM/WebContainer>

8.6.3.2 Thread
The OIDs for threads are available from the following CLI level.
ADP_CLI/Monitoring/PM/WebContainer> cd processMetrics/threads;get
bwWebContainer/processMetrics/threads/
------------------------------------------------------------------------------
bwWebContainer/processMetrics/threads/
------------------------------------------------------------------------------
bwProcessMetricsThreadsAlive 33
bwProcessMetricsThreadsAliveMax 34
bwProcessMetricsThreadsStarted 37911

ADP_CLI/Monitoring/PM/WebContainer>

8.6.4 Thresholds
This section describes the list of SNMP traps generated upon a threshold crossing. For
the list of thresholds whose default values are configurable, see section 8.5.7 Thresholds.

8.6.4.1 Executors
For each of the executor name (CTI, and HTTPNIO), the Application Delivery Platform
provides the ability to generate the following traps:
Executor Queue Usage Ratio
The executor queue usage ratio is defined as a percentage using the following formula:
EventQueueCount / queueCapacity * 100. Upon threshold crossing, the system
generates the following trap:
 Trap bwExecutorQueueUsageExceeded (of severity high): The usage ratio of the
executor queue exceeded the threshold level.
Executor Queue Latency
The executor queue latency is defined as an absolute value and represents the number of
requests that are currently queued while waiting for other tasks to complete during
execution. Upon threshold crossing, the system generates the following trap:
 Trap bwExecutorQueueLatencyExceeded (of severity high): The executor queue
latency exceeded the threshold level.
Executor Thread Pool Processing Time
The executor thread pool processing time is defined as an absolute value and represents
the execution time taken by a task to complete. Upon threshold crossing, the system
generates the following trap:
 Trap bwExecutorThreadPoolProcessingTimeExceeded (of severity high): The
executor thread pool processing time exceeded the threshold level.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 41
 Executor Thread Pool Busy Ratio
The executor thread pool busy ratio is defined as a percentage using the following
formula: threadsBusy / maxPoolSize * 100. Upon threshold crossing, the system
generates the following trap:
 Trap bwExecutorThreadPoolBusyExceeded (of severity high): The executor
thread pool busy ratio exceeded the threshold level.

8.6.4.2 Process Metrics

Heap and Nonheap Memory Usage Ratios
The Application Delivery Platform provides the ability to set a threshold for the heap and
nonheap memory usage ratios.
The heap memory usage ratio is defined as a percentage and represents the heap
memory usage after a full garbage collection.
The nonheap memory usage ratio is defined as a percentage and represents the nonheap
memory usage after a full garbage collection.
Upon a threshold crossing, the system generates the following traps:
 Trap bwHeapMemoryUsageExceeded (of severity high): The memory usage ratio
after a full garbage collection (in %) exceeded the threshold level.
 Trap bwNonheapMemoryUsageExceeded (of severity high): The nonheap memory
usage ratio after a full garbage collection (in %) exceeded the threshold level.

8.6.4.3 Overload Protection

The Application Delivery Platform raises an SNMP trap when the system starts rejecting
requests. For these traps, the threshold setting is embedded in the definition of the
protection mechanism. Hence, there is no additional threshold parameter required.
These traps are notifications and do not clear automatically.
 Trap bwServerTransactionLimitExceeded: During the last overload protection
period, the number of incoming requests exceeded the prescribed limit for the whole
server.
 Trap bwWebAppTransactionLimitExceeded: During the last overload protection
period, the number of incoming requests exceeded the prescribed limit for a specific
web app (as identified by its name).
 Trap bwUserTransactionLimitExceeded: During the last overload protection
period, the number of incoming requests exceeded the prescribed limit for a specific
user.

8.7 Application Management

Operators can install, activate, deploy and upgrade new applications on the Application
Delivery Platform. The Application Delivery Platform provides application management
functionality through the CLI, under the Maintenance/ManagedObjects level. Applications
can be installed, uninstalled, activated, deactivated, deployed, undeployed, upgraded, and
reverted. All operations are CLI-driven. No manual operations are required.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 42
 Applications must be packaged using two possible formats, the standard web application
archive (.war) format and the Cisco BroadWorks Application format (.bwar). The web
application must follow specific guidelines documented in section 11 Application Delivery
Platform Web Applications Requirements so that they can be installed on the Application
Delivery Platform. The Cisco BroadWorks applications are created and released by Cisco
(formerly BroadSoft).
The full life cycle of an application is:
Installation  activation  Deployment  Undeployment  deactivation 
Uninstallation
Individual CLI operations are described in the following subsections.
Unless otherwise mentioned, no restart is necessary for any operation. All changes are
effective immediately.

8.7.1 Installation
The first step in the application life cycle is the installation. For the installation of
applications that are not pre-packaged with the Application Delivery Platform, the
application file (.war or .bwar) must be copied to a local temporary directory on the server,
for example, /tmp. Using the CLI, in the Maintenance/ManagedObjects level, invoke the
install command, providing the full path name of the application file. Note that the name of
the file is irrelevant to the Application Delivery Platform. All the descriptive and operational
data used by the Application Delivery Platform are inside the file. By default,
pre-packaged applications are located in the /usr/local/broadworks/apps directory.
An application is made unique by its name and its version, both of which are defined in the
internal deployment descriptor (in the .war/.bwar). For web application, the deployment
descriptor is the web.xml file. On the other hand, the Cisco BroadWorks application
deployment descriptor is in the broadworks.xml file. The Application Delivery Platform
enforces uniqueness of applications and does not allow installation of two applications with
the same name/version.
Following is an example of an installation of an application.
ADP_CLI/Maintenance/ManagedObjects> install application /tmp/Example-
_1.0.war
Broadworks SW Manager installing Example_1.0.war...
- Performing basic validation
. Valid application structure
. Name : Example
. Description: This is an example Web Application
. Version : 1.0
...Done

ADP_CLI/Maintenance/ManagedObjects>

During the installation process, the application file is validated and, if valid, it is internally
copied and installed. Once the application is installed, the file used to install the
application is no longer required and can be deleted.
After being installed, the application can either be activated to make it configurable or it
can be uninstalled.

NOTE: Applications with an automatic upgrade mode are installed by default when the
Application Delivery Platform is installed. Such applications cannot be uninstalled.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 43
 8.7.2 Activation
To be able to configure the application, it must be activated. Activation is performed
through the CLI with the activate command. The following examples illustrate the
activation of applications.
ADP_CLI/Maintenance/ManagedObjects> activate ?
<type>, Choice = {application}
application:
<name>, String {1 to 80 characters}
<version>, String {1 to 80 characters}
[<contextPath>, String {1 to 80 characters}]

ADP_CLI/Maintenance/ManagedObjects> activate application Example 1.0

/example
Broadworks SW Manager activating...Example version 1.0
...Done

ADP_CLI/Maintenance/ManagedObjects> activate application OpenClientServer

2020.07_1.030
BroadWorks SW Manager activating... OpenClientServer version
2020.07_1.030
...Done

ADP_CLI/Maintenance/ManagedObjects>

When activating an application, the name and version are mandatory. The contextPath
parameter is only required when activating a web application. It must not be specified
when activating a Cisco BroadWorks application.
Multiple instances of the same web application can be activated using different context
paths. However, a single activation of a Cisco BroadWorks application is allowed.
Once activated, applications can be configured. Configuration is done through the CLI
from the application specific context. This context can be found under the application level
as illustrated in the following example.
ADP_CLI/Applications> ?
0) OpenClientServer: go to level OpenClientServer
1) Example : go to level Example_1.0

h (help), e (exit), q (quit), r (read), w (write), t (tree),

c (config), cd (cd), a (alias), hi (history), p (pause), re
(repeat)

ADP_CLI/Applications> 1

ADP_CLI/Applications/Example> ?
Configure the Example_1.0 web application.

Commands:
0) get : show webapp-related attributes
1) set : modify webapp-related attributes
2) clear : clear webapp-related attributes

h (help), e (exit), q (quit), r (read), w (write), t (tree),

c (config), cd (cd), a (alias), hi (history), p (pause), re
(repeat)

ADP_CLI/Applications/Example>

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 44
 As shown in the example, the two activated applications are listed as sub context. Note
however, that not all applications support configuration.

8.7.3 Deployment
Applications activated on the Application Delivery Platform can be selectively deployed
using the CLI deploy command. Following are examples of application deployments.
ADP_CLI/Maintenance/ManagedObjects> deploy ?
<type>, Choice = {application}
application:
<nameOrContextPath>, String {1 to 255 characters}

ADP_CLI/Maintenance/ManagedObjects> deploy application /example

Broadworks SW Manager deploying /example...
...Done

ADP_CLI/Maintenance/ManagedObjects> deploy application OpenClientServer

Broadworks SW Manager deploying OpenClientServer...
WARNING -> You need to restart the server prior to start this application
due to memory settings change.
...Done

ADP_CLI/Maintenance/ManagedObjects>

As shown in the previous example, deploying a web application and a Cisco BroadWorks
application require different parameters. A web application is deployed using the context
path specified during the activation command. On the other hand, deploying a Cisco
BroadWorks application is done using the application name.
The following subsections present the deployment differences between web and Cisco
BroadWorks application.

8.7.3.1 Web Application

When activating and deploying a web application, the HTTP uniform resource locator
(URL) path that leads to it must be specified; this is the “context path”. The Application
Delivery Platform can host many web applications and each one must have a unique
context path.
Web applications are deployed to the application container (Cisco BroadWorks
WebContainer application), creating a running instance of the application. A given web
application (name, version) can be deployed many times using different context paths,
creating as many independently running instances.
Deployed web applications remain deployed until they are undeployed. However, it is not
because a web application is deployed that it automatically has a running instance. There
is a relationship between web applications and Cisco BroadWorks WebContainer
application such that the WebContainer application must be deployed and running for the
web application instances to be running. When the Cisco BroadWorks WebContainer
application is stopped, the running instances of the web applications are automatically
stopped.
The state of the web applications is preserved through Application Delivery Platform
restarts and Application Delivery Platform upgrades.
Note that the context path must always start with a leading “/” and cannot contain any
other “/” characters. For example “/xsi-actions_1.0” is a valid context path.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 45
 8.7.3.2 Cisco BroadWorks Application
Compared to web applications, Cisco BroadWorks applications are made of one or more
components called containers. Each container is implemented as a process on the
server. Deploying the Cisco BroadWorks application is not enough to get the application’s
functionality; it must be started. Cisco BroadWorks applications are started and stopped
individually or all at the same time using either the CLI start or stop command or the
startbw or stopbw script. The syntax is similar in both cases. When the optional
application name is specified, only the specified application is started/stopped. Following
are some examples of application start and stop.
ADP_CLI/Maintenance/ManagedObjects> start application OpenClientServer
--> Starting application OpenClientServer<--

Broadcast message from bworks@mtl64lin12 (Tue Sep 18 15:04:42 2018):

===== BROADWORKS CONTROL --- START INITIATED ON MTL64LIN12

(OpenClientServer) =====
Starting [done]

ADP_CLI/Maintenance/ManagedObjects>

bwadmin@mtl64lin12 $ showrun

Currently running BroadWorks Application processes:

OCS process monitor (pid=24070)

OCS (pid=24107)
tomcat process monitor (pid=3333)
tomcat (pid=3498)

Currently running BroadWorks Platform processes:

BroadWorks Configuration Agent process monitor (pid=4345)

BroadWorks Configuration Agent (pid=4364)
BroadWorks License Manager process monitor (pid=4716)
BroadWorks License Manager (pid=4735)
BroadWorks SNMP Agent process monitor (pid=19271)
BroadWorks SNMP Agent (pid=19290)
BroadWorks Software Manager (pid=32459)
Net-SNMP Daemon process monitor (pid=19193)
Net-SNMP Daemon (pid=19214)
bwadmin@mtl64lin12 $ stopbw SIPLocation
BroadWorks control script version 2020.07
Stopping OpenClientServer...

Broadcast message from bworks@mtl64lin12 (Tue Sep 18 15:06:07 2018):

===== BROADWORKS CONTROL --- STOP INITIATED ON MTL64LIN12

(OpenClientServer) =====
Stopping sipLocation...
Waiting for core processes to terminate.....
... Done.

Currently running BroadWorks Application processes:

tomcat process monitor (pid=3333)

tomcat (pid=3498)

Currently running BroadWorks Platform processes:

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 46
 BroadWorks Configuration Agent process monitor (pid=4345)
BroadWorks Configuration Agent (pid=4364)
BroadWorks License Manager process monitor (pid=4716)
BroadWorks License Manager (pid=4735)
BroadWorks SNMP Agent process monitor (pid=19271)
BroadWorks SNMP Agent (pid=19290)
BroadWorks Software Manager (pid=32459)
Net-SNMP Daemon process monitor (pid=19193)
Net-SNMP Daemon (pid=19214)
bwadmin@mtl64lin12 $

As soon as an application is deployed, healthmon starts monitoring it and reports any

abnormal condition. Following is an example of healthmon output where both
OpenClientServer and WebContainer applications are deployed but not running.
bwadmin@mtl64lin12 $ healthmon -l
Partition monitoring [....................]
BroadWorks monitoring [....................]
Resources monitoring [....................]
--------------------------------------
System Health Report Page
Cisco BroadWorks Server Name : yracine-ADP-trunk
Date and time : Thu Jun 11 10:57:21 EDT 2020
Report severity : CRITICAL
Upgrade check severity : CRITICAL
Server type : XtendedServicesPlatform
Server state : Unlock
--------------------------------------

BroadWorks XtendedServicesPlatform processes in trouble:

tomcat not running

tomcat process monitor not running
OCS not running
OCS process monitor not running

Active alarms

2020-06-11 07:57:10 GMT Informational bwMemoryOverAllocation

--------------------------------

Recommendations
---------------

The WebContainer application needs to be restarted.

The OpenClientServer application needs to be restarted.
bwadmin@mtl64lin12 $

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 47
 8.7.3.2.1 Memory Management
Each Cisco BroadWorks application has its own memory requirement (minimum and
maximum values) defined by Cisco based on the application deployment requirements.
When deploying a Cisco BroadWorks application, the Software Manager calculates the
current system memory usage to determine whether the system has enough memory
available for the application being deployed. In cases where there is not enough memory
available, the Software Manager recalculates the allocated memory and may decide to
reduce the memory allocated to already deployed applications to give some memory to
the application being deployed. In such a case, a warning is displayed to indicate a restart
of the applications is required for the applications to start with their readjusted memory
configuration. Following is an example of such a warning.
ADP_CLI/Maintenance/ManagedObjects> deploy application
DeviceManagementTFTP
Broadworks SW Manager deploying DeviceManagementTFTP...
WARNING -> You need to restart the server prior to start this application
due to memory settings change.
...Done

ADP_CLI/Maintenance/ManagedObjects>

In cases where the amount of physical memory is changed on the server, the application’s
memory configuration is automatically recalculated by the Software Manager at boot time.
8.7.3.2.2 State Management
Each Cisco BroadWorks application implements its own state. The application state is
presented as an administrative state and an effective state. Both states can be viewed
from the CLI Maintenance/ManagedObjects level using the command get broadworks full.
Only the administrative state can be controlled by an operator; the effective state simply
reflects the actual state of the application. The administrative state is controlled through
the CLI Maintenance/ManagedObjects level using the lock and unlock commands. As the
commands suggests, the possible administrative states are:
 Locked
 Unlocked
When an application administrative state is set to one of these states, it means that the
application tries to transition to that state (assuming the application is running).
On the other hand, the effective state reflects the actual state of the application and can
have the following values.
 Locked: The application is locked. Depending on the application’s implementation, it
may mean that it provides limited to no functionality at all.
 Locking: The application is in the process of being locked. This is a transitional state.
 Unlocked: The application is unlocked; all its functionality is available.
 Unlocking: The application is in the process of being unlocked. This is a transitional
state.
 Stopping: The application is in the process of being stopped. This is a transitional
state.
 Stopped: The application is stopped; none of its functionality is available.
 InTrouble: The application is not functional; one or more (but not all) of its containers
are dead. The application must be restarted. The application also enters this state
when one or more (but not all) of its containers is restarted by the process monitor.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 48
  Dead: The application is not functional; all of its containers are dead. The application
must be restarted.
Following is an example of the get broadworks full command, where three Cisco
BroadWorks applications are deployed but only two are running.
ADP_CLI/Maintenance/ManagedObjects> get broadworks full
BroadWorks Managed Objects
==========================

* Server:
Identity..............: ADP
Version...............: Rel_2020.07_1.030
Administrative State..: Unlocked

* Applications:
Name Version Deployed Administrative State
Effective State
=========================================================================
=========
OpenClientServer 2020.07_1.030 true Unlocked
Unlocking
WebContainer 2020.07_1.030 true Unlocked
Unlocked

2 entries found.

* Hosted Applications:
Name Version Context Path Deployed Administrative State Effective
State
=========================================================================
=====

0 entry found.

Currently running BroadWorks Application processes:

OCS process monitor (pid=13812)

OCS (pid=13896)
tomcat process monitor (pid=13766)
tomcat (pid=14088)

Currently running BroadWorks Platform processes:

BroadWorks Configuration Agent process monitor (pid=4345)

BroadWorks Configuration Agent (pid=4364)
BroadWorks License Manager process monitor (pid=4716)
BroadWorks License Manager (pid=4735)
BroadWorks SNMP Agent process monitor (pid=19271)
BroadWorks SNMP Agent (pid=19290)
BroadWorks Software Manager (pid=32459)
Net-SNMP Daemon process monitor (pid=19193)
Net-SNMP Daemon (pid=19214)

ADP_CLI/Maintenance/ManagedObjects>

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 49
 The server administrative state, as shown in the top of the above output as Unlocked, also
has an impact on the application’s effective state. For instance, if an operator locks the
server, all application effective states transition to Locked regardless of the application’s
administrative state. This is because the Locked server’s administrative state supersedes
the application’s administrative state. However, when the server is in Unlocked state, an
operator can freely change an application administrative state, and the application
effective state transitions to the requested state. Following is an example where the
server administrative state is set to “Locked” and the application’s administrative state is
Unlocked but the effective state of the running application is Locked.
ADP_CLI/Maintenance/ManagedObjects> qbw
BroadWorks Managed Objects
==========================

* Server:
Identity..............: ADP
Version...............: Rel_2020.07_1.030
Administrative State..: Unlocked

* Applications:
Name Version Deployed Administrative State
Effective State
=========================================================================
=========
OpenClientServer 2020.07_1.030 true Unlocked
Unlocking
WebContainer 2020.07_1.030 true Unlocked
Unlocked

2 entries found.

* Hosted Applications:
Name Version Context Path Deployed Administrative State Effective
State
=========================================================================
=====

0 entry found.

Currently running BroadWorks Application processes:

OCS process monitor (pid=13812)

OCS (pid=13896)
tomcat process monitor (pid=13766)
tomcat (pid=14088)

Currently running BroadWorks Platform processes:

BroadWorks Configuration Agent process monitor (pid=4345)

BroadWorks Configuration Agent (pid=4364)
BroadWorks License Manager process monitor (pid=4716)
BroadWorks License Manager (pid=4735)
BroadWorks SNMP Agent process monitor (pid=19271)
BroadWorks SNMP Agent (pid=19290)
BroadWorks Software Manager (pid=32459)
Net-SNMP Daemon process monitor (pid=19193)
Net-SNMP Daemon (pid=19214)

ADP_CLI/Maintenance/ManagedObjects>

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 50
 8.7.4 Undeployment
Applications can be undeployed when they are no longer required. Web applications can
be undeployed without restriction; however, before being undeployed, Cisco BroadWorks
applications must be stopped. Undeploying an application is done with the command
undeploy invoked from the CLI Maintenance/ManagedObjects level. For web
applications, the path must be specified and for Cisco BroadWorks applications, the
application name must be used. Following are some examples.
ADP_CLI/Maintenance/ManagedObjects> undeploy application OpenClientServer
BroadWorks SW Manager un-deploying OpenClientServer...
WARNING -> Memory settings have changed. Please consider restarting
server for the changes to take effect.
...Done

ADP_CLI/Maintenance/ManagedObjects> undeploy application /CommPilot-XS-

TAS
BroadWorks SW Manager un-deploying /CommPilot-XS-TAS...
...Done

ADP_CLI/Maintenance/ManagedObjects> get broadworks full

BroadWorks Managed Objects
==========================

* Server:
Identity..............: ADP
Version...............: Rel_2020.07_1.030
Administrative State..: Unlocked

* Applications:
Name Version Deployed Administrative State
Effective State
=========================================================================
=========
OpenClientServer 2020.07_1.030 false Unlocked
Stopped
WebContainer 2020.07_1.030 true Unlocked
Unlocked

2 entries found.

* Hosted Applications:
Name Version Context Path Deployed Administrative State Effective
State
=========================================================================
=====

0 entry found.

Currently running BroadWorks Application processes:

tomcat process monitor (pid=13766)

tomcat (pid=14088)

Currently running BroadWorks Platform processes:

BroadWorks Configuration Agent process monitor (pid=4345)

BroadWorks Configuration Agent (pid=4364)
BroadWorks License Manager process monitor (pid=4716)
BroadWorks License Manager (pid=4735)
BroadWorks SNMP Agent process monitor (pid=19271)

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 51
 BroadWorks SNMP Agent (pid=19290)
BroadWorks Software Manager (pid=32459)
Net-SNMP Daemon process monitor (pid=19193)
Net-SNMP Daemon (pid=19214)

ADP_CLI/Maintenance/ManagedObjects>

Once a web application is undeployed, no instance of this application’s context path is

running within the WebContainer. To reuse the context path, the web application must be
deactivated.
When a Cisco BroadWorks application is undeployed, it can no longer be started.
Applications can still be configured once undeployed.

NOTE: Undeploying the Cisco BroadWorks WebContainer application affects all web
applications. The web applications are no longer running.

8.7.5 Deactivation
Undeploy applications can be deactivated using the deactivate CLI command.
Deactivated applications can no longer be configured. As such, their associated CLI level
under the application context is removed. For web applications, the context path is
released and can be reused. Following are some examples of application deactivation.
Note that deactivating a Cisco BroadWorks application is done using the application
name, whereas deactivating a web application is done using the context path.
ADP_CLI/Maintenance/ManagedObjects> deactivate application
OpenClientServer
BroadWorks SW Manager deactivating...OpenClientServer version
2020.07_1.030
...Done

ADP_CLI/Maintenance/ManagedObjects> deactivate application /CommPilot-XS-

TAS
BroadWorks SW Manager deactivating...CommPilot-XS-TAS version
2020.07_1.030
...Done

ADP_CLI/Maintenance/ManagedObjects>

8.7.6 Uninstallation
Installed applications that are no longer required can be uninstalled. This removes all files
related to this application from the Application Delivery Platform. Only applications in
Active state can be uninstalled. Furthermore, only applications having their upgrade mode
set to “Manual” can be uninstalled. Those with an Automatic upgrade mode cannot be
uninstalled as they are part of the Application Delivery Platform and they are upgraded
with the platform. An application is uninstalled using the uninstall command from the CLI,
Maintenance/ManagedObjects level. The uninstall command required an application and
a version. Following is an example of an uninstallation of a web application.
ADP_CLI/Maintenance/ManagedObjects> uninstall application Example 1.0
BroadWorks SW Manager un-installing Example version 1.0...
...Done

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 52
 ADP_CLI/Maintenance/ManagedObjects>

8.7.7 Upgrade
Applications that are using the Manual upgrade mode must be manually upgraded
through the CLI. Applications with an Automatic upgrade mode are automatically
upgraded when the Application Delivery Platform is upgraded. The upgrade procedure is
different whether the application is a Cisco BroadWorks application or a web application.

8.7.7.1 Cisco BroadWorks Applications

The following procedure describes the steps required to upgrade a running Cisco
BroadWorks application.
After downloading the new version from the software distribution center, the application
must first be installed on the Application Delivery Platform.
ADP_CLI/Maintenance/ManagedObjects> install application
/bw/install/LoadBalancer_2020.09_1.090.bwar
BroadWorks SW Manager installing LoadBalancer_2020.09_1.090.bwar...
- Performing basic validation
. Valid application structure
. Name : LoadBalancer
. Description: Load Balancer
. Version : 2020.09_1.090
...Done

Once the application is installed, the upgrade process can be performed. First, the
application must be locked for the upgrade to proceed.
ADP_CLI/Maintenance/ManagedObjects> set activeSoftwareVersion application
LoadBalancer 2020.09_1.090

+++ WARNING +++ WARNING +++ WARNING +++

Upgrading an application will cause downtime for the targeted component.
Continue?

Please confirm (Yes, Y, No, N): y

--> Stopping application LoadBalancer <--

Stopping [done]

BroadWorks SW Manager upgrading LoadBalancer to version 2020.09_1.090

...Done

As part of this process, the application is both locked and stopped. To make sure the
operator is aware that this will cause a downtime, a question is prompted before
performing the upgrade.
In some cases, the new application version requires a newer version of the Application
Delivery Platform. In this case, the Application Delivery Platform must be upgraded before
the application can be installed.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 53
 8.7.7.2 Web Applications
The following procedure describes the steps required to upgrade a running web
application:
1) Copy the new application .war file to a local directory (/tmp/first.war).
2) Install the new web application using the CLI.
3) [Optional] Test the new web application:
− Deploy a test instance using the CLI.
− Test the application.
− Undeploy the test instance using the CLI.
4) Undeploy the old version of the web application using the CLI.
5) Deploy the new version using the CLI.

8.7.8 Revert
If, for some reason, the Cisco BroadWorks application must be reverted to a previous
version, the process is similar to an upgrade.
ADP_CLI/Maintenance/ManagedObjects> set activeSoftwareVersion application
LoadBalancer 2020.04_1.030 revert
+++ WARNING +++ WARNING +++ WARNING +++
Upgrading an application will cause downtime for the targeted component.
Continue?

Please confirm (Yes, Y, No, N): y

--> Stopping application LoadBalancer <--

Stopping [done]

BroadWorks SW Manager reverting LoadBalancer to version 2020.07_1.030

...Done

Again, the application is locked and stopped before the revert operation is executed.
One important thing to note is that some changes may be lost after the revert operation is
executed (for example, configuration changes) because the resulting active application is
in the state it was before the upgrade.
Installation of an application older than the one that is active is supported. However,
reverting to such an application will result in losing all the configuration made to the active
version.
Note that the revert operation is not supported for web applications.

8.8 HTTP Server Configuration

Typically, a Web Server processes HTTP requests on port 80 and HTTPS requests on
port 443 of its public Internet Protocol (IP) interface. The Application Delivery Platform
requires the additional capacity to serve HTTP/HTTPS on different ports and to support
multiple IP interfaces. For this reason, the Application Delivery Platform allows complete
operator control over which IP interfaces and ports are used to accept server requests.
The CLI provides comprehensive management functions to configure and set up HTTP
servers. All commands are located under the ADP_CLI/Interfaces/Http/HttpServer level.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 54
 The Application Delivery Platform defines an HTTP server as a point of service for HTTP
or HTTPS requests. An HTTP server is uniquely defined by an IP address of a local
interface and a port (for example, 192.168.12.12:80). Each HTTP server is defined with a
public host name and can be secured with a secure sockets layer (SSL).
During the Application Delivery Platform installation, a default secured HTTP server is
created using the first IP address corresponding to the local host name and port 443. If no
interface matches the local host name configuration, the first IP address is used.
Requests received by all Web Servers are dispatched to the proper web application
according to the web application’s context path. There are no restrictions applied to the
dispatching of requests based on the HTTP server that received them.
Following is an example of how the HTTP server can be properly defined.
ADP_CLI/Interface/Http/HttpServer> get
Interface Port Name Secure Client Auth Req Cluster FQDN
=========================================================================
192.168.13.186 80 192.168.13.186 false false

192.168.13.186 443 192.168.13.186 true false

In the example, web.broadsoft.com represents the FQDN used by all HTTP servers
(namely, ADP1 and ADP2), and ADP1.broadsoft.com represents the local name of the
server. Naming can be important for single SSL certificate generation.
The HTTP servers generate self-signed certificates by default and use the default
SSL/TLS protocol and cipher provided by Java. These defaults may be configured on a
per end-point basis using the following CLI levels.
ADP_CLI/Interface/Http/HttpServer/SSLSettings> h
This level is used to configure the Secure Sockets Layer (SSL)/Transport
Layer Security (TLS) parameters.

Commands:
0) Certificates : go to level Certificates
1) Ciphers : go to level Ciphers
2) Protocols : go to level Protocols

h (help), e (exit), q (quit), r (read), w (write), t (tree),

c (config), cd (cd), a (alias), hi (history), p (pause), re
(repeat),
k (keyboardHelp)

ADP_CLI/Interface/Http/HttpServer/SSLSettings>

The protocols and ciphers may also be configured at less specific contexts at the interface
and server level. These less specific contexts are referred to as SSLCommonSettings.
For more information, see the Cisco BroadWorks SSL Support Options Guide [3].

8.8.1 Public Host Name

Each HTTP server is configured with a public host name. The HTTP servers issue a
redirect to http://<hostname>:port/... for each request it receives in which the host name
part of the URL does not match its configured host name.
For example, a server configured with a host name of “myhost1.com” would redirect a
request from http://<ip>/some to http://myhost1.com/some.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 55
 Clients must be able to resolve the host name to an IP address. The Application Delivery
Platform verifies that the host name is locally defined in /etc/host.
Requests to the following applications will not be redirected:
 BroadworksDMS
 OCIFiles
For all other web applications, exceptions to this behavior can be established using
aliases. For more information, see section 8.8.6 HTTP Aliases.

8.8.2 Secure HTTP Server

The HTTP servers can be configured as secured or not secured. A secured HTTP server
only serves HTTPS requests.
Mutual TLS/SSL authentication or certificate-based mutual authentication refers to two
parties authenticating each other through verifying the provided digital certificate so that
both parties are assured of the other’s identity. In Cisco BroadWorks terms, it refers to a
client authenticating themselves to an Application Delivery Platform and the Application
Delivery Platform also authenticating itself to the client through verifying each other’s
certificate. The Application Delivery Platform supports one-way authentication,
authenticating itself to the client similar to any other web server and, optionally, supports
mutual TLS/SSL authentication.
One-way or two-way authentication requires secure sockets layer (SSL) certificates signed
by a recognized authority. On the server side, the Application Delivery Platform initially
generates self-signed certificates and provides CLI commands to manage replacement of
these self-signed certificates with properly signed ones.
The use of self-signed certificates allows for immediate use of the HTTP server for
HTTPS; however, they should be replaced with signed certificates for production systems.
On the client side, there are commands to generate trust anchors.

8.8.3 Create HTTP Server

Additional HTTP servers can be added to the Application Delivery Platform by using the
add command. The IP must be an IP that is locally valid. The host name is the name that
clients are redirected to and shows up in URLs.
For example:
ADP_CLI/Interface/Http/HttpServer> add 192.168.12.12 8080 myhost false
false

8.8.4 Delete HTTP Server

HTTP servers that are no longer required can be deleted using the delete command. The
IP and port of the server to delete must be provided.
For example:
ADP_CLI/Interface/Http/HttpServer> delete 192.168.12.12 8080

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 56
 8.8.5 Manage SSL Certificates

8.8.5.1 Server Certificates

When using a secured HTTP server, the Application Delivery Platform automatically
generates self-signed certificates using the host specified for that server. To sign the
certificate, the certificate signing request must be extracted from the Application Delivery
Platform. Using the sslGenKey, the certificate signing request file is generated to the
/var/broadworks/tmp directory under the name <host>.csr. This file is required for the
official signed procedures.
Once signed, the certificate file must be locally copied to the Application Delivery Platform,
for example, in /tmp. The sslUpdate command can be used to reload the signed
certificate (and optionally, the certificate chain file), replacing the old self-signed
certificates. If a certificate chain file is no longer required, it can be removed using the
sslRemove command.
The sslExport command can also be used to export the certificate file, the SSL key, and
the certificate chain file.
The Application Delivery Platform supports single-host, multi-domain (SAN) and wildcard
certificates. Single-host certificates are required for device management when devices do
not support wildcard certificates. SAN certificates are required when multiple domains are
required for a single certificate. The following subsection shows examples of using each.

8.8.5.2 Single Wildcard SSL Certificate

The certificate must be named properly in accordance with the network naming
convention. The following example shows the best-practice approach to single certificate
naming.
Assume two (or more) Application Delivery Platform HTTP servers are defined as follows.
On ADP1:
ADP_CLI/Interface/Http/HttpServer> get
Interface Port Name Secure Client Auth Req Cluster FQDN
===============================================================================
192.168.8.8 443 ADP1.broadsoft.com true false ADP.broadsoft.com
192.168.8.8 80 ADP1.broadsoft.com false false ADP.broadsoft.com

On ADP2:
ADP_CLI/Interface/Http/HttpServer> get
Interface Port Name Secure Client Auth Req Cluster FQDN
===============================================================================
192.168.8.9 443 ADP2.broadsoft.com true false ADP.broadsoft.com
192.168.8.9 80 ADP2.broadsoft.com false false ADP.broadsoft.com

Because the names of the HTTP servers follow a proper pattern for the server name, a
single certificate with a common name using wildcard characters, such as
ADP*.broadsoft.com or *.broadsoft.com, can be issued. One could decide to have two
distinct certificates here, for example, ADP1.broadsoft.com and ADP2.broadsoft.com,
although this would not be practical in an environment where both Application Delivery
Platforms serve the same software clients in a farm.
Note that software clients accessing the HTTP server using a different alias name, allowed
as defined under the ADP_CLI/Interface/Http/HttpAlias level, are still handled properly by
the same single certificate name. For more information, see section 8.8.6 HTTP Aliases.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 57
 If the names of the HTTP servers do not follow a common pattern (for instance, if the
servers are named ADP1.broadsoft.com and web2.bsoft.com), a single wildcard certificate
cannot be used for the Application Delivery Platform farm. However, a single multi-
domain (SAN) certificate may address that requirement. For more information, see
section 8.8.5.3 Single Multi-Domain (SAN) Certificate.
One or more aliases defined for this server do not affect or influence in any way how the
certificate is managed. The certificate is always derived from the HTTP server name
defined under the CLI and is uniquely bound to an interface and port, whether or not
aliases are defined.
This type of certificate will address the need for additional servers without the need for
signing again. For example, the existing certificate whose common name is
*.broadsoft.com supports ADP3.broadsoft.com.

8.8.5.3 Single Multi-Domain (SAN) Certificate

The certificate must be named properly in accordance with the network naming
convention. The following example shows the best-practice approach to SAN certificate
naming.
Assume two Application Delivery Platform HTTP servers are defined as follows.
On ADP1:
ADP_CLI/Interface/Http/HttpServer> get
Interface Port Name Secure Client Auth Req Cluster FQDN
==============================================================================
192.168.8.8 443 ADP1.broadsoft.com true false ADP.broadsoft.com
192.168.8.8 80 ADP1.broadsoft.com false false ADP.broadsoft.com

On ADP2:
ADP_CLI/Interface/Http/HttpServer> get
Interface Port Name Secure Client Auth Req Cluster FQDN
==============================================================================
192.168.8.9 443 web2.bsft.com true false web.bsft.com
192.168.8.9 80 web2.bsft.com false false web.bsft.com

By creating a single certificate that includes the subjectAlternativeName extension with the
value “ADP1.broadsoft.com web2.bsft.com”, a single certificate may be shared between
the 2 servers.
It is important to understand that the presence of the subjectAlternativeName in a
certificate is mutually exclusive with the certificate common name. That is, when the
subjectAlternativeName is present, the SSL handshake does not use the common name.
As a result, the common name should be added to the subjectAlternativeName extension
when required.
Note that software clients accessing the HTTP server using a different alias name, allowed
as defined under the ADP_CLI/Interface/Http/HttpAlias level, are still handled properly by
the same single multi-domain (SAN) certificate name.
If the need for an additional server arises (for example, web3.bsft.com), a SAN certificate
must be signed again with the updated field subjectAlternativeName
(“ADP1.broadsoft.com web2.bsft.com web3.bsft.com”).

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 58
 8.8.5.4 Multiple Single-host SSL Certificates
There are cases where more than one SSL certificate is needed.
For example, when a single Application Delivery Platform is configured to serve two or
more customers on the same interface, it is important to remember that only one certificate
can be issued for a single HTTP server interface per port for this Application Delivery
Platform.
Assume that the server is defined as follows.
ADP_CLI/Interface/Http/HttpServer> get
Interface Port Name Secure Client Auth Req Cluster FQDN
=========================================================================
192.168.8.8 443 companyA.com true false
192.168.8.8 80 companyA.com false false

ADP_CLI/Interface/Http/HttpAlias> get

Interface Alias Cluster FQDN

===================================================================
192.168.8.8 companyB.com

The URL companyB.com would appear in the HTTP header of a browser because it is
defined here as an alias. However, the certificate can only be issued against
companyA.com with the interface address 192.168.8.8 and port 443. A user accessing
the server with companyB.com and fetching information about the SSL certificate would
realize it was issued against companyA.com, which is undesirable. An alternative is to
define additional HTTP servers with the internet address 192.168.8.8 but with different
ports (for example, 442 and 444), and with some kind of a dummy and generic name
applicable to both companies. Although this is not necessarily desirable either.
If additional network cards are added to the platform, additional HTTP servers can be
defined, which can then have their own certificates, as illustrated by the following example.
ADP_CLI/Interface/Http/HttpServer> get
Interface Port Name Secure Client Auth Req Cluster FQDN
=========================================================================
192.168.8.8 443 companyA.com true false
192.168.8.8 80 companyA.com false false
192.168.8.9 443 companyB.com true false
192.168.8.9 80 companyB.com false false

When the need for an increasing number of distinct SSL certificates arises, it might not be
feasible to add as many network cards as required. Virtual IPs can be defined for such a
purpose.
 On Linux, each physical interface is represented by a file corresponding to
/etc/sysconfig/network-scripts/ifcfg-eth<x> where <x> represents the unique interface
number for that card (for example, the first interface card is represented by ifcfg-eth0).
To create a virtual interface for that physical interface, a file, in the format of ifcfg-
eth0:<y> where <y>represents the alias number, must be created.
For example:
ifcfg-eth0
# Intel Corporation 82540EM Gigabit Ethernet Controller
DEVICE=eth0
IPADDR=192.168.8.8
NETMASK=255.255.255.0

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 59
 NETWORK=192.168.8.0
BROADCAST=192.168.8.255
BOOTPROTO=none
ONBOOT=yes
HWADDR=00:11:25:22:28:c8

ifcfg-eth0:0
# Intel Corporation 82540EM Gigabit Ethernet Controller
DEVICE=eth0:0
IPADDR=192.168.8.10
NETMASK=255.255.255.0
BOOTPROTO=none
ONPARENT=yes
BROADCAST=192.168.8.255

Note that the addition of Application Delivery Platform interface addresses must be
properly propagated through the entire network (DNS or /etc/hosts, Network Servers
configuration, and so on). All settings required on the network and in the Cisco
BroadWorks configuration for the primary IP address of the Application Delivery Platform
are also required for the added IP addresses.
The virtual interfaces act just as physical interfaces as far as certificates are concerned.

8.8.5.5 Trust Anchors

Configuration of client authentication is centralized under a dedicated CLI context named
ClientAuthentication. The list of trust anchors applies to all interfaces listed in the
HttpServer level where the field clientAuthReq is set to “true”. The following shows where
this HttpServer level is located.
PS_CLI/Interface/Http/SSLCommonSettings/ClientAuthentication>

Requiring client authentication means that the server must validate the certificate received
from the client during the SSL handshake. The server uses a trust store that contains trust
anchors to validate these certificates. Therefore, this CLI level provides a sublevel named
trusts that defines a set of dedicated commands for handling trust anchors. This sublevel
is located as follows for the HttpServer level.
PS_CLI/Interface/Http/SSLCommonSettings/ClientAuthentication/Trusts>

These interactions allow the generation of a trust anchor that can be directly distributed to
the client software 2 or can be used as an issuer for generating client certificates.
Depending on the network requirement, a Cisco BroadWorks customer can require
multiple trust anchors. For example, certain device vendors demand the use of their own
certificates. The CLI commands require an administrator to specify an alias name to allow
for identifying the trust anchors individually.

2 A trust anchor is itself a certificate.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 60
 8.8.6 HTTP Aliases
The Application Delivery Platform allows the use of HTTP aliases for each local interface.
Aliases are managed through the ADP_CLI/Interface/Http/HttpAliases level in the CLI.
Normally, the HTTP servers receiving requests with a host name different from their public
host name redirect the client to use the public host name. For more information, see
section 8.8.1 Public Host Name.
Aliases define additional host names values that the HTTP servers accept without
redirections. Aliases can be added and deleted through the CLI.

8.8.6.1 Fully Qualified Domain Name Mapping

The HTTP servers support mapping of known fully qualified domain names (FQDNs) to
aliases through redirections. An FQDN value can be provisioned on each HTTP alias.
HTTP servers receiving a request with the FQDN as a host name redirect the client to use
the corresponding alias.

8.8.7 HTTP Bindings

The HTTP bindings define which interfaces (IP address and port) a given web application
is available and allow the binding of all applications to specific interfaces. The name of the
web application corresponds to the display name defined in its web.xml file. An HTTP
server web application binding can be created even if the application is not activated or
deployed. By default, if no entry is defined under the HTTP server binding, the web
application is available on all interfaces. As soon as one entry is added, it is only allowed
on that interface.

8.9 Peering
The Application Delivery Platform supports being deployed in a cluster. Redundancy in
this case is used for file and configuration replication across the cluster members.

8.9.1 File Replication

The list of replicated files depends on the applications deployed on the Application
Delivery Platform. The following applications support file replication:
 CommPilot
 BroadworksFileRepos
 BroadworksFileReposExtdCapture
 ECLReportingRepository
 MessageArchive

8.9.2 Configuration Replication

In addition to file replication, the Application Delivery Platform also supports configuration
replication. Configuration replication must be set up from the CLI on replicated and replica
nodes, as follows:
Replicated node configuration
ADP_CLI/System/ConfigAgent/GeneralSettings> set mode replicated
...Done

ADP_CLI/System/ConfigAgent/GeneralSettings> cd ../Replication/

ADP_CLI/System/ConfigAgent/Replication> start

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 61
 ...Replication started

Replica node configuration

ADP_CLI/System/ConfigAgent/GeneralSettings> set mode replica
...Done

ADP_CLI/System/ConfigAgent/GeneralSettings> cd ../Replication/

ADP_CLI/System/ConfigAgent/Replication> start
...Replication started

The list of replicated CLI levels depends on the applications deployed on the Application
Delivery Platform. The following applications support configuration replication:
 BroadworksFileRepos
 BroadworksFileReposExtdCapture
 ECLReportingRepository
 MessageArchive

8.9.3 Redundancy Configuration

To set up the redundancy, the config-redundancy script must be invoked from every peer
as follows.
/usr/local/broadworks/bw_base/bin> ./config-redundancy

-> Data gathering <-

--------------------------
Redundant server settings:
Non-Redundant system.
--------------------------

Enter an additional peer hostname (q to quit, c to clear the list):

adp1.mtl.broadsoft.com
Enter peer address: 10.9.27.40

Enter an additional peer hostname (q to quit, c to clear the list):

adp2.mtl.broadsoft.com
Enter peer address: 10.9.27.41

Enter an additional peer hostname (q to quit, c to clear the list): q

-> Confirmation <-

This is the New redundancy configuration:

--------------------------
Redundant server settings:
Currently configured peer(s) (list of hostname/address):
adp1.mtl.broadsoft.com /10.9.27.40
adp2.mtl.broadsoft.com /10.9.27.41
--------------------------

Do you want to keep the following configuration? (y/n) [y]?y

-> Adding new peer <-

Adding adp1.mtl.broadsoft.com /10.9.27.40...
Adding adp2.mtl.broadsoft.com /10.9.27.41...

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 62
 -> Configure Secure Shell <-

==============================================
==== SSH CONFIGURATION TOOL version 2.2.22 ====
=> Setting default settings <=
Setting 'StrictHostKeyChecking no'
Setting 'ServerAliveInterval 250'
=> DNS Sanity test <=
[###############]
[...............]
Configured: y, Reachable: y, Resolved: n, Required: n.
Using [email protected] as local peer name for
adp1.mtl.broadsoft.com.
=> DNS not OK, continuing... <=
=> Peer reachability test <=
[######]
[......]
=> Creating SSH keys <=
Creating keys for [email protected]...

Creating keys for [email protected]...

[email protected]'s password:

Creating keys for [email protected]...

=> Keying SSH <=

Preparing [email protected] for keying...

Cleaning public keys for [email protected]...

Cleaning public keys for [email protected]...
Sharing keys with [email protected]...
Pushing local public keys...
Pulling remote public keys...
Sharing keys with [email protected]... [done]

Sharing keys with [email protected]...

Pushing local public keys...
[email protected]'s password:
Pulling remote public keys...
[email protected]'s password:
Sharing keys with [email protected]... [done]

=> Fully meshing SSH peers <=

=> Recursing with [email protected] <=

Pushing config-ssh script to [email protected]...
Launching config-ssh on [email protected]...

=> Setting default settings <=

Setting 'StrictHostKeyChecking no'
Setting 'ServerAliveInterval 250'
=> DNS Sanity test <=
[###############]
[...............]
Configured: y, Reachable: y, Resolved: n, Required: n.
Using [email protected] as local peer name for
adp1.mtl.broadsoft.com.
=> DNS not OK, continuing... <=
=> Peer reachability test <=
[######]
[......]

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 63
 => Keying SSH <=
Preparing [email protected] for keying...

Cleaning public keys for [email protected]...

Cleaning public keys for [email protected]...
Sharing keys with [email protected]...
Pushing local public keys...
Pulling remote public keys...
Sharing keys with [email protected]... [done]

Sharing keys with [email protected]...

Pushing local public keys...
Pulling remote public keys...
Sharing keys with [email protected]... [done]

=> Recursing with [email protected] <=

Pushing config-ssh script to [email protected]...
Launching config-ssh on [email protected]...

=> Setting default settings <=

Setting 'StrictHostKeyChecking no'
Setting 'ServerAliveInterval 250'
=> DNS Sanity test <=
[###############]
[...............]
Configured: y, Reachable: y, Resolved: n, Required: n.
Using [email protected] as local peer name for
adp2.mtl.broadsoft.com.
=> DNS not OK, continuing... <=
=> Peer reachability test <=
[######]
[......]
=> Keying SSH <=
Preparing [email protected] for keying...

Cleaning public keys for [email protected]...

Cleaning public keys for [email protected]...
Sharing keys with [email protected]...
Pushing local public keys...
Pulling remote public keys...
Sharing keys with [email protected]... [done]

Sharing keys with [email protected]...

Pushing local public keys...
Pulling remote public keys...
Sharing keys with [email protected]... [done]

=> Testing ssh configuration <=

Testing [email protected]... [done]
Testing [email protected]... [done]

==== SSH CONFIGURATION TOOL completed ====

-> Importing data from peers <-

---- config-redundancy [done] ----

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 64
 8.10 Network Server Configuration
There are no changes required to the Network Server configuration to use the Application
Delivery Platform.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 65
 9 Network Configuration Changes

This section provides information on Application Delivery Platform configuration operations

required when the IP or host name of the Application Delivery Platform, Application
Server, or Network Server is changed.

9.1 Change IP or Host Name of Application Delivery Platform

When changing the IP address or host name of the Application Delivery Platform, the
HTTP server and in some cases the HTTP Alias configuration must be updated.
The overall procedure for updating the IP address or host name of a Cisco BroadWorks
server is described in the Cisco BroadWorks Maintenance Guide. This section details the
operations specific to the Application Delivery Platform.
After the IP address or host name has been updated at the operating system (OS) level,
the following must be performed:
1) Update the HTTP server configuration.
2) Update the Application Server network access lists for the open client interface (OCI)
and ExtAuth.

9.1.1 Update HTTP Server Configuration

Updating the HTTP server configuration is done using the CLI, under the
ADP_CLI/Interface/Http/HttpServer level.

For IP address changes:

1) First, for each HTTP server using the old IP, create a new HTTP server on the new IP
with the same attributes. Use the add command (for example, add 192.168.12.1 80
host false).
2) When all new HTTP servers are created, simply delete those using the old IP. Use
the delete command (for example, delete 192.168.13.1 80).

For host name changes:

1) If the host name was being used by an HTTP server, update the HTTP server name
with the new host name. Use the set command (for example, set 192.168.12.1 80
name=newhost).
2) If using the host name for a secured HTTP server, the Application Delivery Platform
generates self-signed certificates. These certificates must be signed. For more
information, see section 8.8.5 Manage SSL Certificates.

9.2 Change IP, Host Name, or FQDN of Network Server

The BwCommunicationUtility must be reconfigured with the new IP or host name if the
integration mode is set to “NS”. If it is set to “NS”, the IP address or host name of the
Network Server must be entered in the locationServiceURL using the CLI, under the
ADP_CLI/System/CommunicationUtility/DefaultSettings level. For more information, see
section 8.4.1 Integration Mode.
If using a clusterFQDN to reach the Network Server(s), then this step is only required
when the FQDN changes.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 66
 9.3 Change IP or Host Name of Application Server
The BwCommunicationUtility must be reconfigured with the new IP or host name if the
integration mode is set to “AS”. If it is set to “AS”, the IP address or host name of the
Application Server must be entered using the CLI, under the
ADP_CLI/System/CommunicationUtility/DefaultSettings level. For more information, see
section 8.4.1 Integration Mode.
Change the asPrimaryAddress or the asSecondaryAddress as required.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 67
 10 Troubleshooting

This section provides general information about Application Delivery Platform

troubleshooting.

10.1 Logs
Most Application Delivery Platform components issue logs. The following subsections
provide information on where logging information can be found on the Application Delivery
Platform.

10.1.1 HTTP Access Logs

The access logs associated with HTTP requests are stored in the
/var/broadworks/logs/tomcat directory.
The following shows an example of access logs.
bwadmin@ADP:/var/broadworks/logs/tomcat> more access_log.2020.06.11-
11.25.35.txt
10.82.133.248 - - [11/Jun/2020:11:25:35 -0400] "GET / HTTP/1.1" 404 - 433
0.159 159 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS
X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.61
Safari/537.36" "-"
10.82.133.248 - - [11/Jun/2020:11:25:35 -0400] "GET /favicon.ico
HTTP/1.1" 404 - 433 0.024 24 "http://10.9.32.211/" "Mozilla/
5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like
Gecko) Chrome/83.0.4103.61 Safari/537.36" "-"

10.1.2 Tomcat Logs

The Tomcat servlet container used by the Application Delivery Platform issues logs in the
/var/broadworks/logs/tomcat directory. This log contains the container internal logs and
possibly the exceptions it encounters while executing the various web applications.

10.1.3 Web Application Logs

Web application logging is under the control of the individual web applications. For
information on logging, refer to the related documentation for each web application.
For example, the XtendedServicesInterface, version 1.0, issues logs in the
/var/broadworks/logs/ADP directory, using the XsiLog*.txt file name.

10.1.4 Cisco BroadWorks Application Logs

Cisco BroadWorks application logging is under the control of the individual applications.
For information on logging, refer to the related documentation for each application.

10.1.5 Configuration Agent Logs

The Configuration Agent responsible for hosting the server’s configuration issues logs to
the /var/broadworks/logs/config directory.

10.1.6 Other Cisco BroadWorks Logs

In general, all logs issued by Cisco BroadWorks components are located in the
/var/broadworks/logs directory.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 68
 10.2 Common Problems
This section describes common problems and potential causes.

10.2.1 Authentication Failure for Valid User

The following subsections describe some of the causes for an authentication failure for a
valid user.

10.2.1.1 User Login without Domain Name when Network Server Mode is Used
In “NS” mode, the BWCommunicationUtility performs LocationAPI lookups on the Network
Server to resolve the Application Server cluster that owns it. The full user name must be
user: user@domain because the Application Delivery Platform is not aware of the default
domain of the Application Server cluster.
The following log can usually be observed.
BwCommunicationMgr: Executing NS user lookup
BwCommunicationMgr: Servers={null,null}
BwCommunicationMgr: No usable OCI-P authenticator for <user>

10.2.1.2 Application Server ExtAuth or OCI AccessControlList Not Provisioned

The following log can usually be observed.
OCI-P authentication for <user>@<domain>
…
Authentication rejected for <user>@<domain>

10.2.2 OCI-C Connectivity Problems

The following subsections describe common errors that occur when using OCI-C.

10.2.2.1 Application Server Does Not Support OCI-C (For Release 14.sp5 or Later)
The following log can usually be observed.
Failed to register OCI-C protocol

10.2.2.2 Application Delivery Platform is Configured for AS Mode Integration

The following log can usually be observed.
Operation aborted, OCI-C is not supported in AS integration mode

10.2.2.3 Web Application Does Not Provide an OCI-C Application ID

The following log can usually be observed.
Operation aborted, OCI-C application is not configured

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 69
 10.2.2.4 OCI-C Application ID used by Web Application is Not Properly Provisioned on
Application Server
The following log can usually be observed.
OCI-C Connection Registration rejected app <name>
AS responded with <reason>

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 70
 11 Application Delivery Platform Web Applications Requirements

The Application Delivery Platform allows installation and deployment of standard web
applications packaged as web application archive (war) files. This section defines the
expected structure of such web applications and provides guidelines for their
implementation.
These guidelines take into account the fact that some of the web applications produced by
Cisco BroadWorks can be deployed on third-party platforms.
This section is not a tutorial on how to build web applications. Rather, it focuses on the
compliancy with the Application Delivery Platform.

11.1 Application Packaging Requirements

The applications must be packaged as standard war files. The applications must be
designed with the mindset that the war is never to be exploded or tampered with to be
installed, deployed, and used.

11.1.1 War File Name

The following war file naming convention is used by Cisco (formerly BroadSoft) for all
applications it releases:
<appname>_<version>.war
… where:
<version> = <major>.<minor>
For example: bwXsi_1.0.war

NOTE: This naming convention has no functional bearing on the web application and is
intended only as a convenience for users.

The Application Delivery Platform does not rely on any elements from the naming pattern
for management of the web application. It extracts name and version information from the
embedded web.xml, as described in the following subsections. The Application Delivery
Platform, therefore, does not expect or enforce this naming convention.
Note that manually changing the .war file name can be required on third-party platforms to
accommodate deployment and establishment of the context path for the application
(notably for Tomcat in some configurations). This is to be expected.

11.1.2 War File Structure and Contents

The .war file must have the following directory structure 3:
 *.html, *.jsp, and so on – The HTML and JSP pages, along with other files that must
be visible to the client browser (such as JavaScript, style sheet files, and images).

3 The standard for building the web application can be obtained from

http://tomcat.apache.org/tomcat-6.0-doc/appdev/deployment.html.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 71
  /WEB-INF/web.xml – The web application deployment descriptor for the application.
Details about this file can be obtained from http://tomcat.apache.org/. All servlet
mappings and listener configuration (as defined earlier in this document) must be
done by the web application developer. This file only contains static configuration for
the application.
 /WEB-INF/classes/ – This directory contains any Java class files (and associated
resources) required by the interface, including both servlet and non-servlet classes,
which are not combined into JAR files. If some classes are to be organized into Java
packages, one must reflect this in the directory hierarchy under /WEB-INF/classes/.
For example, a Java class named com.mycompany.mypackage.MyServlet would
need to be stored in a file named /WEB-
INF/classes/com/mycompany/mypackage/MyServlet.class.
 /WEB-INF/lib/ – This directory contains JAR files that contain Java class files (and
associated resources) required by the application, such as third-party class libraries.
The BwCommunicationUtility should not be included in the .war file.
Note that the .war file can be built using zip or jar utilities. One simply needs to use the
.war file extension rather than .zip or .jar.

11.2 Web Application Descriptor File (web.xml)

To deploy web applications on the Application Delivery Platform, the following web.xml
items are used by the Application Delivery Platform for web application management
processes. The Application Delivery Platform validates the web.xml of all web applications
and enforces the presence of mandatory fields.
Item Status XML Tags

Display name required <display-name>bwXsi</display-name>

Description optional <description>

BroadWorks Xtended Services Interface
</description>

Webapp version required <env-entry>

<description>webapp version</description>
<env-entry-name>webAppVersion</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>1.0</env-entry-value>
</env-entry>

Webapp configuration optional <env-entry>

file <description>
Name of the configuration file for this webapp.
</description>
<env-entry-name>webAppConfigFile</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>bwXsiActionsConfig.properties
</env-entry-value>
</env-entry>

The following provides a sample web.xml with the expected items.

<web-app>
<display-name>bwXsi</display-name>
<description>BroadWorks Xtended Services Interface</description>

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 72
 <env-entry>
<env-entry-name>webAppVersion</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>1.0</env-entry-value>
</env-entry>

<env-entry>
<env-entry-name>webAppConigFile</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>bwXsiActionsConfig.properties</env-entry-value>
</env-entry>
…

</web-app>

11.3 Web Application Naming

To manage the web application, the display-name must be defined in the web.xml. This
should be a short token and must not contain spaces.
The name is used together with the version to uniquely identify a web application on the
Application Delivery Platform. It is presented to the operator by the Application Delivery
Platform’s CLI to provide web application management functions.
Note that this name has no bearing on the web application’s context path on the
Application Delivery Platform.

11.4 Web Application Versioning

To help manage the web application, the web application developer is required to include
the web application version information in the web application descriptor file (web.xml).
The version is specified as an environment entry <env-entry>. For tag details, see section
11.2 Web Application Descriptor File (web.xml).
The version information together with the display-name uniquely identifies a web
application on the Application Delivery Platform. It is presented to the operator by the
Application Delivery Platform CLI to provide web application management functions. This
is the version used by the CLI and not the version embedded in the war file name.
The version should not contain spaces.

11.5 Web Application External Configuration

The web.xml and context.xml presented in the .war file should be used to provide
configuration data to the web application implementation instead of the hard-coding values
in the Java code. This allows easier customization of web applications by application
developers. If the web.xml and context.xml are too limited for some configuration data,
data files can be included under WEB-INF/lib and loaded by the web application.
However, this is to be considered as static “build time” configuration rather than end-user
web application configuration because it relies on files packaged inside the war file. Once
packaged, war files should not be required to be exploded and rebuilt to be configured.
Web applications that require external deployment time configuration input must rely on an
external properties file to do this. The external properties file is to be made accessible to
one of the application container’s classloaders. For Tomcat, the file should be made
available to the shared classloader by placing it under /usr/local/tomcat/tomcat_base/lib.
The web application must publish the name for this file (no path is required since it is
loaded through the classpath). In addition, it must define the file name as an environment
entry in the web.xml, under the webAppConfigFile name.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 73
 On the Application Delivery Platform, this file can be managed through the CLI provided
the web application includes a Cisco BroadWorks configuration descriptor “bwCongif.xml”
in the META-INF directory included in its war file. If no configuration descriptor is provided
or if you are running the web application on a third-party container, this file must be
managed manually. The Application Delivery Platform renders a CLI level for the web
application under the ADP_CLI/Maintenance/WebApp/Config level.

11.5.1 BwCommunicationUtility Overrides

The BwCommunicationUtility allows “per-webapp” configuration of all its settings. The
default values for all web applications can be configured through the
BwCommunicationUtility’s own configuration file. If a web application wants to use its own
values for some of the settings (for example, overload controls), it can either rely on
internal static values that it uses to configure the library through its application
programming interface (API) or it must read its values from its external configuration file
and use these to configure the library through its API.

11.6 Web Application Context Path

The context.xml embedded in the war file contains a path attribute that can theoretically
define the URL path to the web application; however, it is not recognized on most
containers.
On the Application Delivery Platform, the web application context paths are specified
through the CLI at deployment time.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 74
References

[1] Cisco Systems, Inc. 2020. Cisco BroadWorks Software Management Guide.
Available from Cisco at cisco.com.
[2] Cisco Systems, Inc. 2020. Cisco BroadWorks Application Delivery Platform Fault
and Alarm Interface Specification. Available from Cisco at cisco.com.
[3] Cisco Systems, Inc. 2020. Cisco BroadWorks SSL Support Options Guide.
Available from Cisco at cisco.com.
[4] Cisco Systems, Inc. 2016. Load Balancing Feature Description, Release 22.0.
Available from Cisco at cisco.com.
[5] Cisco Systems, Inc. 2020. Cisco BroadWorks Configuration System Interface
Specification. Available from Cisco at cisco.com.

CISCO BROADWORKS APPLICATION DELIVERY PLATFORM CONFIGURATION GUIDE 03-BD6100-00

©
2020 CISCO SYSTEMS, INC. CISCO CONFIDENTIAL PAGE 75