Alpaca 11.0

Alpaca Installation

This is a guide for installing Alpaca on a clean server.

Officially Supported Operating Systems

Red Hat Enterprise Linux, Oracle Linux, CentOS Stream 8
Red Hat Enterprise Linux, Oracle Linux, CentOS Stream 9

Assumptions

A clean installation of a supported operating system.
This is not an upgrade.
A valid SSL certificate for the Alpaca Gateway's hostname.
Credentials to access the Alpaca server as root.
Credentials to access the connected BroadWorks Application and Profile Servers.
BroadWorks Credentials to make changes via bwcli.
Working knowledge of ssh and a file transfer tool such as scp.
RPM version 4.13 or higher is installed on the Alpaca server.
Minimum system requirements are met.

Guide

The guide is split into sections based on the server or machine that the operations should be performed. It is also in chronological order. Performing the steps from top to bottom is the desired procedure.

Local Workstation

Step: O-1
1. Download TimesTen 11.2.2.8.0 from Oracle's edelivery website. This requires accepting the license agreement and having an Oracle account.
  - Once logged in, search "Timesten" in the search bar.
  - Click "REL:Oracle TimesTen Application-Tier Database Cache 11.2.2.8.0". The package will be added to your download queue.
  - Click "continue" at the top right to be taken to your download queue.
  - Under "Platform/Languages", select "Linux x86-64".
  - Click "Continue".
  - Accept the license agreement(s).
  - Click "Continue".
  - Click the package name to download directly to your current machine.
2. Transfer the downloaded archive to the Alpaca Server's "/opt" directory.
Step: O-2
1. Download the Alpaca installation RPM. This requires an ECG Portal Account.
2. Transfer the downloaded installation package to the Alpaca server's "/tmp" directory.
Step: O-3
1. If using a subscription based license, this step can be skipped.
2. Download the Alpaca license file. This requires an ECG Portal Account.
3. This file should be downloaded to your local machine.
Step: O-4
1. Transfer the SSL certificate chain "fullchain.pem" and private key "privkey.pem" file to the Alpaca server's " /tmp" directory.

Alpaca Server

Step: A-1

Additional Requirement:
1. # dnf install -y libnsl
Installed: libnsl-2.28-151.el8.x86_64

Complete!

Commands:

# cd /opt
# mkdir ttTemp
# mv TimesTenPackage ttTemp
# cd ttTemp
# unzip -q TimesTenPackage
# cd linux8664/
# ./setup.sh

WARNING: You are about to install TimesTen as root. TimesTen daemon processes will run with root privileges. See the TimesTen Installation Guide for additional information.
Are you sure that you want to install as root? [ no ] y

NOTE: Each TimesTen installation is identified by a unique instance name. The instance name must be a non-null alphanumeric string, not longer than 255 characters.
Please choose an instance name for this installation? [ tt1122 ] tt1122

Instance name will be 'tt1122'.

Is this correct? [ yes ] y

Of the three components:

  [1] Client/Server and Data Manager
  [2] Data Manager Only
  [3] Client Only

Which would you like to install? [ 1 ] 3

Of the following options :

  [1] /opt
  [2] /tmp
  [3] Specify a location
  [q] Quit the installation

Where would you like to install the tt1122 instance of TimesTen? [ 1 ] 1

Installing into /opt/TimesTen/tt1122 ...
Creating /opt/TimesTen/tt1122 ...
Uncompressing ...

NOTE: For security, we recommend that you restrict access to the
      TimesTen installation to members of a single OS group. Only members of
      that OS group will be allowed to perform direct mode connections to
      TimesTen, and only members of that OS group will be allowed to perform
      operations that access TimesTen data stores, TimesTen files and shared
      memory. The OS group defaults to the primary group of the instance
      administrator. You can default to this group, choose another OS group
      or you can make this instance world-accessible. If you choose to make
      this instance world-accessible, all database files and shared memory
      are readable and writable by all users.

Restrict access to the TimesTen installation to the group 'root'? [ yes ] n
Do you want to restrict access to the TimesTen installation to a different group? [ yes ] n

Are you sure you want to make this instance world-accessible? [ yes ] y

In order to use the 'Oracle TimesTen Application-Tier Database Cache' feature in any databases
created within this installation, you must set a value for the TNS_ADMIN
environment variable. It can be left blank, and a value can be supplied later
using <install_dir>/bin/ttModInstall.

Please enter a value for TNS_ADMIN (s=skip)? [ ] s
Do you want to install the Quick Start Sample Programs and the TimesTen Documentation? [ no ] n
Would you like to install the documentation (without the Quick Start Sample Programs)? [ yes ] n
```
Installing client components ...
```
What is the name of the host running the TimesTen server? [ alpaca.ecg.co ] ⏎

What is the TCP/IP port number that the TimesTen server is listening on? [ 53397 ] ⏎

The documentation was not installed.
To manually install the documentation, run the command 'setup.sh -installDoc'

The 11.2.2.8 Release Notes are located here :
  '/opt/TimesTen/tt1122/README.html'

End of TimesTen installation.

# rm -f /opt/TimesTen/tt1122/lib/ttjdbc{5,6,7}.jar
# echo "/opt/TimesTen/tt1122/lib" > /etc/ld.so.conf.d/timesten.conf

# ldconfig -v | grep TimesTen -A 7

/opt/TimesTen/tt1122/lib:
    libttcoD.so -> libttcoD.so
    libttco.so -> libttco.so
    libttclassesCS.so.gcc346 -> libttclassesCS.so.gcc346
    libttclient.so.gcc346 -> libttclient.so.gcc346
    libttclassesCS.so.gcc410 -> libttclassesCS.so.gcc410
    libttJdbcCS.so -> libttJdbcCS.so
    libttclient.so.gcc410 -> libttclient.so.gcc410

Step: A-2
1. If using Red Hat Enterprise Linux, Oracle Linux, CentOS Stream 8 a. # echo -e "[mongodb-org-4.4]\nname=MongoDB Repository\nbaseurl=https://repo.mongodb.org/yum/redhat/\$releasever/mongodb-org/4.4/x86_64/\ngpgcheck=1\nenabled=1\ngpgkey=https://www.mongodb.org/static/pgp/server-4.4.asc" > /etc/yum.repos.d/mongodb-org-4.4.repo
2. If using Red Hat Enterprise Linux, Oracle Linux, CentOS Stream 9 a. # echo -e "[mongodb-org-6.0] name=MongoDB Repository baseurl=https://repo.mongodb.org/yum/redhat/9/mongodb-org/6.0/x86_64/ gpgcheck=1 enabled=1 gpgkey=https://pgp.mongodb.com/server-6.0.asc" > /etc/yum.repos.d/mongodb-org-4.4.repo
Step: A-3
1. Follow the installation guide for RabbitMQ.
  - Follow the Red Hat 8, CentOS Stream, CentOS 8, Modern Fedora sections.
2. Ensure that RabbitMQ is enabled as a service, set to run on boot, and is currently running.
3. Additional Commands:
  1. # rabbitmqctl add_user "alpaca"
    - This user and password will be used to access RabbitMQ from the Alpaca Server application.
  2. # rabbitmqctl set_user_tags alpaca administrator
  3. # rabbitmqctl set_permissions -p / alpaca "." "." ".*"
  4. # rabbitmq-plugins enable rabbitmq_management
    - This will allow access to the RabbitMQ web interface on port 15672.
Step: A-4
- Commands:
  1. # cd /tmp
  2. # dnf install -y alpaca-ALPACA_VERSION.x86_64.rpm

Step: A-5 (Optional Mongo Steps)

Set up logrotate to manage Mongo logs. (Optional)

- Update the Mongo configuration located at `/etc/mongod.conf`. Make sure `logAppend` is set `true`
  and `logRotate` is set to `reopen`.

  ```
      systemLog:
       destination: file
       logAppend: true
       logRotate: reopen
       path: /var/log/mongodb/mongod.log
  ```

- Create/Update the Mongo logrotate configuration located at `/etc/logrotate.d/mongodb`.

  ```
    /var/log/mongodb/mongod.log
     {
         rotate 7
         daily
         size 1M
         missingok
         create 0600 mongod mongod
         delaycompress
         compress
         sharedscripts
         postrotate
              /bin/kill -SIGUSR1 $(cat /var/run/mongodb/mongod.pid)
         endscript
     }
  ``` 

    - `rotate` - The number of files to keep. Currently set to 7.
    - `daily` - Rotate files at least once a day.
    - `size` - Rotate file when it reaches provided size. Currently set to 1MB.
    - Note that depending on the version of Mongo, the user used in `create 0600 mongod mongod` may be `mongod` or `mongodb`.
    - The log rotate script can be tested using `logrotate -v -f /etc/logrotate.d/mongodb`. 
- Restart mongo - `service mongod restart`

Setup authentication (optional but recommended)

Create "Super Admin"

      > mongo
      > use admin
      > db.createUser({ user: "MySuperAdmin", pwd: "MySecretPassword", roles: [{ role: "userAdminAnyDatabase", db: "admin"}]});
      > exit

Enable Authentication
- Update mongod config located at /etc/mongod.conf.
- Make sure the file includes:
```
      security:
          authorization: "enabled"
```
Restart Mongo - service mongod restart
Add DB User

      > mongo
      > use admin
      > db.auth("MySuperAdmin", "MySecretPassword");
      > use alpaca
      > db.createUser({ user: "AlpacaDBUser", pwd: "MySecretUserPassword", roles: [{ role: "readWrite", db: "alpaca"}, { role: "readWrite", db: "jobrunr"}]});
      > exit

Follow the config guide in step A-8 to provide credentials for Mongo.

Step: A-6
- Note: If using an external load balancer with SSL termination such as an F5, this step can be ignored. The Gateway will still need to be configured; however, that will occur during HA clustering configuration.
- Commands:
  1. # openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem -out keystore.pkcs12
  2. Enter Export Password: KEYCHAIN_PASSWORD
  3. Verifying - Enter Export Password: KEYCHAIN_PASSWORD
  4. # mv keystore.pkcs12 /etc/alpaca/gateway/config
  5. # vi /etc/alpaca/gateway/config/application-https.yml
    - Set the "key-store-password" field to the value set during export.
  6. # vi /etc/alpaca/gateway/config/application-prod.yml
    - Follow the configuration guide to configure the Eureka hostname.
Step: A-7
- Commands:
  1. # vi /etc/alpaca/eureka/config/application-prod.yml
    - Follow the configuration guide to configure the Eureka hostname.
Step: A-8
- Commands:
  1. Follow the configuration guide to configure required settings. This includes RabbitMQ, Eureka, and MongoDB.
- Two configuration modes are supported:
  - native: The server configuration file is located on the Alpaca server.
    - Configuration file will be located in /etc/alpaca/eureka/cloud-config/alpaca-server-prod.yml
    - A template can be found in /etc/alpaca/eureka/cloud-config/alpaca-server-template.yml.
      - Note that this file is not read in by Alpaca. This is a starting place for your configuration.
    - Once filled out, rename the file from alpaca-server-template.yml to alpaca-server-prod.yml
  - awss3: The server configuration file is hosted in an S3 instance such as AWS or MinIo.
    - A template can be found in /etc/alpaca/eureka/cloud-config/alpaca-server-template.yml.
    - Once filled out, rename the file from alpaca-server-template.yml to alpaca-server-prod.yml.
    - Upload alpaca-server-prod.yml to your S3 repository.
Step: A-9
- Commands:
  1. # vi /etc/sysconfig/alpaca_config
    - This is the startup configuration.
    - You can also control what profiles are used for each service. Follow the configuration guide to determine what profiles you need.
Step: A-10
- By default, all version of Alpaca are enabled (R22, R23, and R24).
  - If you wish for a version to not run, you can simply use chkconfig to turn it off.
    - chkconfig alpaca-server-<BW_VERSION> off
    - To re-enable a version, use the following command:
    - chkconfig alpaca-server-<BW_VERSION> on
- The Alpaca start script is located in /usr/local/bin. Make sure that this directory is included in your PATH.
- Commands:
  1. # service mongod start
  2. # chkconfig mongod on
  3. # alpacactl start
Step: A-11
- See Guide for initial login instructions.
- See Guide for setting up Clusters.
- See Guide for setting up Alpaca User BroadWorks credentials.

alpacactl

alpacactl is used to control the states of the various Alpaca components. alpacactl is used in place of the Linux service/systemctl commands.

For alpacactl to work, the directory /usr/local/bin needs to be included in the PATH of the user running Alpaca ( usually root).

To accomplish this, run echo "export PATH=$PATH:/usr/local/bin" > /etc/profile.d/alpaca_ctl.sh, which will add /usr/local/bin to the PATH globally.
If you do not wish to edit your path, you can reference alpacactl using the full path - /usr/local/bin/alpacactl {start|stop|restart|status}
Starting services
1. All services
  - alpacactl start
2. Single service
  - alpacactl start {eureka|gateway|server-22|server-23|server-24}
Stopping services
1. All services
  - alpacactl stop
2. Single service
  - alpacactl stop {eureka|gateway|server-22|server-23|server-24}
Restarting services
1. All services
  - alpacactl restart
2. Single service
  - alpacactl restart {eureka|gateway|server-22|server-23|server-24}
Checking service status
- alpacactl status {eureka|gateway|server-22|server-23|server-24}
Checking health status
- alpacactl health

BroadWorks Application Server

These steps are performed for each BroadWorks Application Server that will be monitored by Alpaca. Log in to the server as bwadmin. A BroadWorks admin login will be required to make the required AS_CLI changes.

Step: AS-1
Commands:
1. AS_CLI> cd /Applications/ExecutionAndProvisioning/PS/Logging/InputChannels/AuditLog
2. AS_CLI/Applications/ExecutionAndProvisioning/PS/Logging/InputChannels/AuditLog> set accountInfo true
  
  ...Done
3. AS_CLI/Applications/ExecutionAndProvisioning/PS/Logging/InputChannels/AuditLog> set verbose true
  
  ...Done
4. AS_CLI/Applications/ExecutionAndProvisioning/PS/Logging/InputChannels/AuditLog> q;q;Output
5. AS_CLI/Applications/ExecutionAndProvisioning/PS/Logging/OutputChannels> set AuditLog enabled true
  
  ...Done
6. AS_CLI/Applications/ExecutionAndProvisioning/PS/Logging/OutputChannels> cd /Applications/OpenClientServer/ExternalAuthentication/AccessControlList
7. AS_CLI/Applications/OpenClientServer/ExternalAuthentication/AccessControlList> get
  
  IP Address Description
  
  0 entry found.
  - If no entries are found skip step 8.
  - If the BroadWorks XSP IP address is already listed skip step 8.
8. AS_CLI/Applications/OpenClientServer/ExternalAuthentication/AccessControlList> add *<kbd>XSP-IP* description xsp
  
  ...Done

BroadWorks Profile Server

These steps are performed for each BroadWorks Profile Server that will be accessed by Alpaca to perform migrations and data retrieval. Log in to the server as bwadmin. A BroadWorks admin login will be required to make the required PS_CLI changes.

Step: PS-1
Commands:
1. PS_CLI> cd /Applications/BroadworksFileRepos/NetworkAccessLists/WebDav
2. PS_CLI/Applications/BroadworksFileRepos/NetworkAccessLists/WebDav> add ALPACA-IP description alpaca-server
  
  ...Done
Step: PS-2
Commands:
1. PS_CLI> cd /Applications/BroadworksFileRepos/Users
2. PS_CLI/Applications/BroadworksFileRepos/Users> add alpaca-server get put delete
3. New Password: CREATE_A_FILE_REPO_USER_PASSWORD
4. Retype New Password: CREATE_A_FILE_REPO_USER_PASSWORD
  
  ...Done
Step: PS-3
- This is an optional step that only applies if you have BroadworksFileReposExtdCapture enabled.
Commands:
1. PS_CLI> cd /Applications/BroadworksFileReposExtdCapture/Users
2. PS_CLI/Applications/BroadworksFileReposExtdCapture/Users> add alpaca-server get put delete
3. New Password: CREATE_A_FILE_REPO_USER_PASSWORD
4. Retype New Password: CREATE_A_FILE_REPO_USER_PASSWORD