Alpaca 6.5

Configuration

The following properties can be defined inside the /opt/alpaca/config/application-prod.yml file.

Migration

  • announcementRepositoryUsername: The username to retrieve voice portal audio and video files from for migration procedures.
  • announcementRepositoryPassword: The password to retrieve voice portal audio and video files from for migration procedures.
  • authenticationPasswordChangeable: When randomizing a user's authentication password, the user's access device type must match the provided regular expression.
  • authenticationUsernameChangeable: When randomizing a user's authentication username, the user's access device type must match the provided regular expression.
  • deviceRebootDelayMillis: The delay in milliseconds between rebooting the device and performing the migration procedure.
  • htmlEncodeExports: When performing an export, special characters will be escaped if this option is turned on. Characters include <, >, &, =, and '.
  • blf-caching-enabled: When BLF caching is enabled, Alpaca will parse through all BLF entries and keep an updated database of monitoring users. This can cause startup to take a little longer but it will improve the speed of migrations.
  • ignore-line-port-transforming: Only applies to line ports with the source default domain. If set to true, line ports with the source default domain, will not have their domain transformed to the destination default domain.
  • deviceFileMigrationRuleList: Migration file rules consist of device types matched to the files that should be migrated with the device. There can be any number of file rules that specify the desired files to be migrated. If no rules are provided, no device files will be migrated during any type of migration.
  • deviceFileMigrationRuleList/deviceTypeRegex: This defines the file rule device type, as specified by regular expression.
  • deviceFileMigrationRuleList/fileRegexes: Any number of files can be specified by exact name.

Example configuration:

alpaca:
    migration:
      announcement-repository-username: "BoNjOuRlEsAmIs049"
      announcement-repository-password: "viveLEROILouis14"
      html-encode-exports: true
      device-reboot-delay-millis: 5000
      authentication-username-changeable-regex: ".*(Polycom|Linksys|Cisco).*"
      authentication-password-changeable-regex: ".*(Polycom|Linksys|Cisco).*"
      blf-caching-enabled: true
      ignore-line-port-transforming: false
      device-file-migration-rule-list:
        -
          device-type-regex: ".*(Polycom|Linksys|Cisco).*"
          file-regexes: [
            "%BWMACADDRESS%-directory.xml",
            "%BWMACADDRESS%-calls.xml",
          ]

File Store

  • location: The absolute or relative location on the filesystem where exported files will be stored.
  • cleanup-interval: The number of days between file store cleanups.
alpaca:
    file-store:
      location: filestore
      cleanup-interval: 90

File Upload

  • max-file-size: Max file size. Values can use the suffixes "MB" or "KB" to indicate megabytes or kilobytes, respectively. Defaulted to 1000MB. Setting to -1, makes the file size unlimited.
  • max-request-size: Max request size. Values can use the suffixes "MB" or "KB" to indicate megabytes or kilobytes, respectively. Defaulted to 1000MB. Setting to -1, makes the request size unlimited.
  • location: Intermediate location of uploaded files.
spring:
    servlet:
      multipart: 
        max-file-size: 1000MB
        max-request-size: 1000MB
        location: tmp

Audit Logs

  • fire-alerts-for-tasks: If disabled, Alpaca will not fire alerts for audit logs that are the result of a task that Alpaca started, i.e. Enterprise Migration.
alpaca:
    audit-logs:
      fire-alerts-for-tasks: false

Broadworks

  • encoding: The encoding to use for the outgoing and incoming parsing of BroadWorks messages.
  • max-requests-per-second: The maximum number of requests to send per second through a single BroadWorksServer object. This is a blocking operation that will limit the overall speed of the code if attempting to perform too many operations per second.
  • validate-requests-on-fire: Sets if JSR 303 Bean Validation will be used to verify that a request is valid per the XML spec before sending it to BroadWorks. The Request will not be sent if invalid.
  • auto-fire-millis: When using a RequestBundler this timeout controls how long to wait before firing a request with less than 15 entries.
  • ssl-permissive: Whether to disable SNIExtension and use a universal trust strategy for SSL.
  • number-of-sockets-per-server: How many sockets will be opened per BroadWorksServer connection.
  • connection-reconnect-attempts: How many times to attempt a reconnect to BroadWorks once a connection is lost.
  • connection-reconnect-delay-millis: How long after a connection lost to attempt to reconnect.
  • asynchronous-timeout-millis: Timeout for asynchronous calls.
  • synchronous-timeout-millis: Timeout for synchronous calls.
  • max-retries-for-system-error: The number of times to retry a request if it comes back as a System Error. 
broadworks:
  ssl-permissive: true
  connection-reconnect-attempts: 4
  connection-reconnect-delay-millis: 500
  max-requests-per-second: 40
  connection-timeout-millis: 5000
  validate-requests-on-fire: false
  encoding: "ISO-8859-1"
  number-of-sockets-per-server: 1
  asynchronous-timeout-millis: 12000
  synchronous-timeout-millis: 60000
  auto-fire-millis: 1000
  max-retries-for-system-error: 3

File Repository Configuration

  • cluster: The nickname of the cluster configured in Alpaca.
  • file-repo: The file repository name in BroadWorks.
  • username: The username of the file repository admin.
  • password: The password of the file repository admin.
broadworks:
  profile-server:
  - cluster: Production
    file-repo: ProfileServer
    username: fileadmin
    password: P@ssw0rd
  -cluster: Lab
    file-repo: ProfileServer
    username: fileadmin
    password: P@ssw0rd

Spring Email Configuration

  • host - The server to connect to.
  • port - The port to connect to. Defaults to 25.
  • username - The email account to use to send emails from.
  • password - The password for the email account that is being used.
  • protocol - The protocol to use to send the email, i.e. SMTP, POP3, IMAP.
  • properties.mail.smtp - Mail properties if using SMTP.
    • auth - If true, attempt to authenticate the user using the AUTH command. Defaults to false.
    • starttls.enable - If true, enables the use of the STARTTLS command (if supported by the server) to switch the connection to a TLS-protected connection before issuing any login commands. Note that an appropriate trust store must be configured so that the client will trust the server's certificate. Defaults to false.
    • ssl.trust - If set to "*", all hosts are trusted. If set to a whitespace separated list of hosts, those hosts are trusted. Otherwise, trust depends on the certificate the server presents.

Sample Spring Email configuration

 mail:
    host: smtp.gmail.com
    port: 587
    username: alpaca.alerts@email.com
    password: "emailPassword!"
    protocol: smtp
    properties.mail.smtp:
        auth: true
        starttls.enable: true
        ssl.trust: smtp.gmail.com

Alpaca Email Configuration

  • from - The email address to send emails from.
  • base-url - The URL of the Alpaca server that the emails will be sent from.

Sample Alpaca Email configuration

mail:
    from: alpaca.alerts@email.com
    base-url: http://127.0.0.1:8080

MongoDB

The MongoDB configuration can be put in the data portion of your application-prod.yaml configuration file.

  • uri - The address of the local Mongo installation. This is typically mongodb://localhost:27017.
  • database - The name of the database to use for Alpaca. This should always be alpaca.

Sample MongoDB configuration

data:
    mongodb:
        uri: mongodb://localhost:27017
        database: alpaca

SSL Configuration

To configure Alpaca to run via SSL, start by enabling the https profile. See Profile Configuration. Once enabled, the application-https.yaml needs to be configured.

Generating a Key Store

To enable SSL you need a valid Java keystore configured. This first requires a valid certificate.

A valid certificate can be generated using the free Let's Encrypt service using Certbot. This requires a web service such as apache to perform domain verification. Example:

wget https://dl.eff.org/certbot-auto
chmod a+x certbot-auto
./certbot-auto certonly

After the certificate has been created use openssl to create a keystore file.

cd /etc/letsencrypt/live/<domain>
openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem -out keystore.pkcs12

To verify that the certificate was correctly imported: 

keytool -list -keystore config/keystore.pkcs12 -storetype pkcs12 -alias 1

Now the keystore can be copied to the Alpaca configuration directory for usage.

cp keystore.pkcs12 /opt/alpaca/config/
chown alpaca:alpaca /opt/alpaca/config/config/keystore.pkcs12

Configurations

These configurations assume that necessary keys, key stores, and certificates have already been generated.

  • key-store - Path to the key store that holds the SSL certificate (typically a jks or pem file).
  • key-store-password - Password used to access the key store.
  • key-store-type - Type of the key store.
  • key-alias - Alias that identifies the key in the key store.
  • key-password - Password used to access the key in the key store.
  • protocol - SSL protocol to use.
  • ciphers - Supported SSL ciphers.

Sample SSL configuration

server:
    port: 8443
    ssl:
      key-store: config/keystore.pkcs12
      key-store-password: myStorePassword!
      key-store-type: PKCS12
      key-alias: 1
      key-password: myKeyPassword!
      protocol: TLSv1.2
      ciphers: ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256,TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256

Profiles

  • prod - This is the primary configuration for production.
  • https - Enables ssl. See the SSL Configuration.

Profile selection can be done in the alpaca-server script using the --profiles option followed by a comma-separated list of profiles. They can be configured on service startup in the alpaca service script using the PROFILES field.

Configure AlpacaStore Cleanup Process

Alpaca is configured to remove older JSON files from migrations and exports after 90 days by default. If the default needs to be changed, review the following steps.

  1. In the application-prod.yml configuration file, locate the file-store configuration under alpaca.

    alpaca:
    file-store:
      location: /opt/alpaca/store
      cleanup-interval: 90

  2. Change the cleanup-interval value to the desired number of days to retain files within the configured location.

BroadWorks Clusters Configuration

Initial Setup / Adding Clusters

After the installation process has been completed, you will need to configure Alpaca to be able to communicate with your BroadWorks Cluster(s). Find the steps to do this below.

  1. Navigate to your Alpaca server via a web browser.
  2. Log in using the default credentials:
    • username: admin
    • password: admin
    • It is recommended to immediately change the password upon login.
  3. From the navigation bar, expand the "Admin" drop-down and navigate to the "BroadWorks Clusters" page.
  4. To add a cluster, click the "Add Cluster" button and complete the form.
    • Cluster Nickname - This is the nickname that will be used to describe the cluster. All clusters must have a unique nickname. Examples: "ECG Production" or "ECG Lab1".
    • OCI Hostname - The address to send OCI calls to. This is the address of the XSP or EWS.
    • BroadWorks Admin Username - This account is used by Alpaca to perform background information retrieval for items such as the searchable database and licensing information.
    • BroadWorks Admin Password - The password for the account above.
    • Audit Log Directories - The location of the audit logs for the particular cluster. i.e. /opt/alpaca/auditlogs/ECG_Production/. More than one directory can be provided.
  5. Once the form has been completed, click the "Create" button and a success or error message will appear. If an error has occurred, please check and verify that the credentials and addresses provided are correct.
  6. Repeat for each cluster.

Editing Clusters

Cluster information can be edited at any time by following the instructions below.

  1. Navigate the BroadWorks Cluster page. All BroadWorks Clusters that Alpaca has a connection with will appear here.
  2. Click on the cluster that needs to be edited.
  3. Modify that fields that need editing and click the "Update" button on the button right of the page. Note that the password field must be re-entered each time an edit is made.

Delete Clusters

Clusters can be removed from Alpaca at any time but please note that once a cluster has been removed its data will no longer be accessible via Alpaca.

  1. Navigate the BroadWorks Cluster page.
  2. Click on the cluster that needs to be deleted.
  3. Click the "Delete" button.

Spring Boot

Spring Boot offers a wide variety of pre-defined configurations. The complete list of configurations can be found here.