Installation

Installation CentOS and RedHat

Installation tested on CentOS 7.

Prerequisites

• System Requirements
• Java JDK 1.8
• Mongo Database
• Oracle TimesTen Java Libraries
• BroadWorks Profile Server Access
• Audit Log Network File Sharing
• Alpaca Service

System Requirements

The minimum system requirements to run Alpaca are as follows: - Storage: 100 GB - CPU: 2 - RAM: 4 GB + 2x PERM_ALLOCATED_SIZE

Determining PERM_ALLOCATED_SIZE

You can determine the current PERM_ALLOCATED_SIZE on a Broadworks Application server using the ttIsql command:

bwadmin@as1.voip.net$ ttIsql

...
Command> dssize;
The following values are in KB:

  PERM_ALLOCATED_SIZE:      1048576
  PERM_IN_USE_SIZE:         71861
  PERM_IN_USE_HIGH_WATER:   71944
  TEMP_ALLOCATED_SIZE:      348160
  TEMP_IN_USE_SIZE:         28888
  TEMP_IN_USE_HIGH_WATER:   32368
Command> exit;

In this example, our PERM_ALLOCATED_SIZE is 1048576 kB (1.05 GB), so this system requires 6 GB (4 + 2(1)) of RAM.

Mongo Setup

Alpaca uses Mongo as it's backing database. A minimum of version 3.4 is required. The newest release can be found on Mongo's webpage.

Follow the official install instructions

TimesTen Setup

1. Download the TimesTen installation archive.
2. Extract and run setup.sh.
   • Installation as root is acceptable.
   • The instance name can be anything and will determine directory name.
   • Install in client only mode.
   • Installation location can be anywhere. Our example commands use /opt/TimesTen/tt1122.
   • Do not restrict access to root or another group if other tools will be installed on the server.
   • The TNS_ADMIN, quick start programs, documentation, HOST, and PORT can all be skipped.
3. After installed, the TimesTen lib directory must be set within the configuration file in /opt/alpaca/configuration.
4. Remove obsolete JDBC drivers.
   • In your TimesTen lib directory, you will find multiple ttjdbc*.jar files. Alpaca only needs ttjdcb8.jar.
   • Create a backup directory and move all of the ttjdcb*.jar files except for the ttjdcb8.jar into this directory.
5. Add TimesTen lib directory to the Linux library linking path.
   • echo "/opt/TimesTen/tt1122/lib" > /etc/ld.so.conf.d/timesten.conf
   • Verify that the TimesTen library is loaded by ldconfig -v | grep TimesTen -A 20.
   • The output should display the library links being created.

Profile Server Setup

The IP address of the Alpaca system must be in an access control list on the BroadWorks profile server to allow access to device configuration files.

1. Login to the Profile Server.
2. In the BWCLI navigate to /Applications/BroadworksFileRepos/NetworkAccessLists/WebDav.
3. Add the IP address of the Alpaca server.
   • add <IP_ADDRESS> description <DESCRIPTION>
   • e.g., if there's no NAT and you're running Alpaca on 192.168.25.200, you could do:
   • add 192.168.25.200 "Alpaca workstation"

Application Server Open Client Server External Authentication ACL

Alpaca uses the XSPs to communicate via OCI to the Application Server. If the Application Server has an ACL configured for the OCS External Authentication, the XSPs must be listed.

1. Log in to the Application Server.
2. In the BWCLI, login as an administrator and navigate to /Applications/OpenClientServer/ExternalAuthentication/AccessControlList
3. Use the get command to confirm if an ACL is configured.
   • If an ACL is configured, ensure the XSP which Alpaca will send OCI requests to is listed.
     • Otherwise, if the XSP is not listed in the output, add the XSP using the following format.
       • add <XSP_IP_ADDRESS> description xsp
   • If no IPs are listed, then BroadWorks allows external authentication by default and no adjustments are necessary.

Audit Log NFS Setup

Alpaca indexes BroadWorks audit logs for each configured Application Cluster. This requires access to a directory or directories housing BroadWorks Audit logs. This is typically done via NFS.

Source Application Servers

Each source Application Server will need to perform the following installation. For Application Server pairs this should be performed on both servers.

1. Make sure the following packages are installed:
   • nfs-utils-*
   • nfs-utils-lib-*
   • rpcbind-*
2. Add the following line to the /etc/exports file.
   • /var/broadworks/logs/appserver <ALPACA_SERVER_IP>(ro,fsid=0,sync)
     
3. Run the following commands:
   1. chkconfig nfs on
   2. chkconfig rpcbind on
   3. service rpcbind start
   4. service nfs start

Alpaca Server

1. Make sure the following packages are installed:
   • nfs-utils-*
   • nfs-utils-lib-*

2. Add the following line to the /etc/fstab file for each Application Server for which audit logs will be read. The destination directory should not be inside the Alpaca service directory as this is not guaranteed to be maintained during future upgrades.

   • <BW_AS_IP>:/var/broadworks/logs/appserver <DESTINATION_DIRECTORY> nfs defaults 1 1

   • Example:

     as1.lab.e-c-group.com:/bw/broadworks/logs/appserver /opt/nfs/auditlogs/as1 nfs defaults 1 1
     as2.lab.e-c-group.com:/bw/broadworks/logs/appserver /opt/nfs/auditlogs/as2 nfs defaults 1 1
     

3. Mount all the file systems listed in /etc/fstab:

   • mount -a
   • This will ignore those marked as “noauto”, excluded by the -t flag, or those that are already mounted.

BroadWorks Logging Configuration

Alpaca reads the Audit Logs created by the Application Servers to provide the historic details within specific log entries.

The following steps detail how to configure a BroadWorks Application Server to log the necessary details to the Audit Log file for Alpaca.

• Log in to the Application Server's bwcli.
  • AS1# bwcli
• Navigate to the Audit Log's configuration enable verbose logging and accountInfo.
  • AS_CLI> cd /Applications/ExecutionAndProvisioning/PS/Logging/InputChannels/AuditLog
  • AS_CLI/Applications/ExecutionAndProvisioning/PS/Logging/InputChannels/AuditLog> set accountInfo true
  • AS_CLI/Applications/ExecutionAndProvisioning/PS/Logging/InputChannels/AuditLog> set verbose true
  • The getRequest option is not required by Alpaca.
• Next ensure AuditLogs are being output to a file.
  • AS_CLI/Applications/ExecutionAndProvisioning/PS/Logging/InputChannels/AuditLog> q;q;Output
  • AS_CLI/Applications/ExecutionAndProvisioning/PS/Logging/OutputChannels> get
  • If the Audit logs are not enabled to be output to a file, enable the Audit Logs.
    • AS_CLI/Applications/ExecutionAndProvisioning/PS/Logging/OutputChannels> set AuditLog enabled true

Alpaca Setup

1. Download the Alpaca tarball(.tar.gz) to the /opt directory on the server.
2. Extract the archive.
   • cd /opt
   • tar xzvf /opt/alpaca-server-21sp1-6.0.0-RELEASE-bin.tar.gz
3. Create a symlink to the new alpaca directory.
   • ln -s /opt/alpaca-server-21sp1-6.0.0 /opt/alpaca
4. Create an alpaca user.
   • useradd -m alpaca
5. Change the ownership of the /opt/alpaca directory and all of its children.
   • chown -R alpaca:alpaca /opt/alpaca/
6. Copy the license file from the ECG portal ecg.license.txt into the config directory.
7. Perform configuration according to Alpaca configuration guides.
8. Copy the alpaca file into /etc/init.d.
9. Run the following commands:
   1. chkconfig --add alpaca
   2. chkconfig alpaca on
10. Launch service with service alpaca start.
11. Alpaca can then be accessed by visiting http://<SERVER_IP>:8080 or other location as configured.

BroadWork's Host IDs

A perpetual ECG License requires the Host Ids of all of the BroadWorks Application Servers that Alpaca will be communicating with. There are two ways to retrieve the Host IDs: From the XSP_CLI and directly off of the Application Server.

XSP_CLI

All host ids used by an XSP are located at: XSP_CLI/System/Licensing. Sample output from the XSP CLI --

XSP_CLI/System/Licensing> get
customerName         = Engineers Consulting Group
licenseType          = HARD
expirationDate       = 09/16/2017
     Host Id
============
AAAAAAAA-BBBB-1111-CCCC-123456ABCDEFG

1 entries found.

AS

Specific AS host ids can be seen from the AS via /usr/local/broadworks/bw_base/sbin/bwdd | grep UUID or dmidecode | grep UUID.

Alpaca Licenses

Open Source Licenses

• Apache License - Version 2.0
• Eclipse Public License - Version 1.0
• jLine License - Version 1.0
• MIT License - Version 1.0
• Mozilla Public License - Version 2.0

Semantic Version Matching

Semantic version matching allows for easy comparison and analysis of versions. Some common examples--

• Simple Ranges - >=1.0.0 & <2.0.0
• Wildcard Ranges (|X|x) - 1. which is equivalent to >=1.0.0 & <2.0.0
• Tilde Ranges (~) - ~1.5 which is equivalent to >=1.5.0 & <1.6.0
• Hyphen Ranges (-) - 1.0-2.0 which is equivalent to >=1.0.0 & <=2.0.0
• Caret Ranges (^) - ^0.2.3 which is equivalent to >=0.2.3 & <0.3.0
• Partial Version Ranges - 1 which is equivalent to 1.X or >=1.0.0 & <2.0.0
• Negation operator - !(1.x) which is equivalent to <1.0.0 & >=2.0.0
• Parenthesized expressions - ~1.3 | (1.4.* & !=1.4.5) | ~2

Complete Grammar

The complete expression grammar is parsed as follows.

          <semver-expr> ::= "(" <semver-expr> ")"
                          | "!" "(" <semver-expr> ")"
                          | <semver-expr> <more-expr>
                          | <range>

            <more-expr> ::= <boolean-op> <semver-expr>
                          | epsilon

           <boolean-op> ::= "&" | "|"

                <range> ::= <comparison-range>
                          | <wildcard-range>
                          | <tilde-range>
                          | <caret-range>
                          | <hyphen-range>
                          | <partial-version-range>

     <comparison-range> ::= <comparison-op> <version> 
                          | <version>

       <wildcard-range> ::= <wildcard>
                          | <major> "." <wildcard>
                          | <major> "." <minor> "." <wildcard>

          <tilde-range> ::= "~" <version>

          <caret-range> ::= "^" <version>

         <hyphen-range> ::= <version> "-" <version>

<partial-version-range> ::= <major>
                          | <major> "." <minor>

              <version> ::= <major>
                          | <major> "." <minor>
                          | <major> "." <minor> "." <patch>

        <comparison-op> ::= "=" | "!=" | ">" | ">=" | "<" | "<="

                <major> ::= <numeric-identifier>

                <minor> ::= <numeric-identifier>

                <patch> ::= <numeric-identifier>

   <numeric-identifier> ::= "0"
                          | <positive-digit>
                          | <positive-digit> <numeric-identifier>

       <positive-digit> ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"

             <wildcard> ::= "*" | "x" | "X"