Alpaca Installation

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

Officially Supported Operating Systems

  • Red Hat Enterprise Linux 8
  • Oracle Linux 8
  • CentOS Stream 8

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. Transfer the downloaded license file "ecg.license.txt" to the Alpaca server's "/tmp" directory.
  • 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:

      1. # cd /opt
      2. # mkdir ttTemp
      3. # mv TimesTenPackage ttTemp
      4. # cd ttTemp
      5. # unzip -q TimesTenPackage
      6. # cd linux8664/
      7. # ./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.

      8. 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.

      9. Please choose an instance name for this installation? [ tt1122 ] tt1122

        Instance name will be 'tt1122'.

      10. Is this correct? [ yes ] y

        Of the three components:
        
          [1] Client/Server and Data Manager
          [2] Data Manager Only
          [3] Client Only
        
      11. Which would you like to install? [ 1 ] 3

        Of the following options :
        
          [1] /opt
          [2] /tmp
          [3] Specify a location
          [q] Quit the installation
        
      12. 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.
        
      13. Restrict access to the the TimesTen installation to the group 'root'? [ yes ] n

      14. Do you want to restrict access to the TimesTen installation to a different group? [ yes ] n

      15. 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.
        
      16. Please enter a value for TNS_ADMIN (s=skip)? [ ] s

      17. Do you want to install the Quick Start Sample Programs and the TimesTen Documentation? [ no ] n

      18. Would you like to install the documentation (without the Quick Start Sample Programs)? [ yes ] n

        Installing client components ...
        
      19. What is the name of the host running the TimesTen server? [ alpaca.ecg.co ] ⏎

      20. 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.
        
      21. # rm -f /opt/TimesTen/tt1122/lib/ttjdbc{5,6,7}.jar

      22. # echo "/opt/TimesTen/tt1122/lib" > /etc/ld.so.conf.d/timesten.conf

      23. # 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. # 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
  • 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)

    1. 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 mongodb mongodb
             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.
    - Restart mongo - `service mongod restart`
    
    1. 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
  • Step: A-7

    • Commands:
      1. # vi /etc/alpaca/eureka/config/application-prod.yml
  • Step: A-8

    • Commands:
      1. If not using a subscription based license, perform the following command:
        • # mv ecg.license.txt /etc/alpaca/server
      2. 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