Alpaca 11.0

Alpaca Server Configuration

This guide details all configurations that are available within the Alpaca Server. Starting in version 9.1 the Server configuration is centralized and accessible through the Eureka server. On Server startup it connects to the Eureka server and downloads the shared configuration file for all Alpaca Servers. See the Centralized Configuration section for more details.

Any changes to the configuration made while Alpaca is running will not take effect until after a restart. Use the following command to restart Alpaca - alpacactl restart server-[22|23|24].

YAML (YAML Ain't Markup Language)

All Alpaca configurations are in the YAML (.yml) format.

Basic Rules

  • YAML is case sensitive.
  • YAML does not allow the use of tabs. Spaces are used instead as tabs are not universally supported.

  • A dictionary is represented in a simple key: value form (the colon must be followed by a space):

        alpaca:
        migration:
          announcement-repository-username: "BoNjOuRlEsAmIs049"
          announcement-repository-password: "viveLEROILouis14"
          html-encode-exports: true

  • All members of a list are lines beginning at the same indentation level starting with a - (a dash and a space):

      broadworks:
    profile-server:
    - cluster: Production
      file-repo: ProfileServer
      username: fileadmin
      password: P@ssw0rd
    - cluster: Lab
      file-repo: ProfileServer
      username: fileadmin
      password: P@ssw0rd

  • Comments are denoted by #.

      # Alpaca Configuration
  alpaca:
      # Migration Configuration
      migration:
        announcement-repository-username: "BoNjOuRlEsAmIs049"
        announcement-repository-password: "viveLEROILouis14"
        html-encode-exports: true

Full Documentation

Complete YAML documentation can be found here.

Spring Boot

Alpaca configurations are built upon Spring Boot. Within Spring there are a wide variety of predefined configurations. The complete list of configuration options can be found here.

Centralized Configuration

Centralized configuration allows management of all Alpaca Servers using a single configuration file. To enable this, configuration of the /etc/alpaca/server/config/bootstrap.yml must be completed so that the Alpaca Server can retrieve its initial configuration file. This is a sample bootstrap.yml configuration file:

spring:
  cloud:
    config:
      name: alpaca-server
      uri:
        - http://alpaca:alpaca@alpaca-1.lab.ecg.co:8761/config
        - http://alpaca:alpaca@alpaca-2.lab.ecg.co:8761/config
        - http://alpaca:alpaca@alpaca-3.lab.ecg.co:8761/config
eureka:
  client:
    service-url:
      default-zone: http://alpaca:alpaca@alpaca-1.lab.ecg.co:8761/eureka,http://alpaca:alpaca@alpaca-2.lab.ecg.co:8761/eureka,http://alpaca:alpaca@alpaca-3.lab.ecg.co:8761/eureka

Spring Cloud Config (spring.cloud.config)

  • name: This is the name of the Alpaca Server used to determine the configuration file to retrieve. This is the exact name of the file on the config server without the profile. So in this example, if the server is running in production mode, the configuration file would be named alpaca-server-prod.yml.
  • uri: This is an array of Eureka servers with which to retrieve the configuration. The centralized configuration server is located on the Eureka server, so this should be the same domain, port, and credentials as the Eureka server. It contains the path segment for the configuration context as configured on the Eureka server. This defaults to /config.

Eureka Client Service URL (eureka.client.service-url)

  • default-zone: These are the Eureka servers to register against. This will be a comma separated list of Eureka servers to register against. This will include the username and password as configured in the Eureka configuration. The path will be /eureka by default.

Example Configuration

This sample configuration is meant to serve as a guide only. Do not copy and paste the entire content into your configuration.

org:
  jobrunr:
    dashboard:
      username: jobrunr
      password: jobrunr
alpaca:
  audit-logs:
    fire-alerts-for-tasks: false
    retention-days: -1
    skip-reads: true
    ignored-types:
      - "UserSingleSignOnCreateDeviceTokenRequest"
      - "SystemJWSPutFileCustomizationCompletedRequest"
      - "UserClientApplicationPutFileCustomizationRequest"
  access-logs:
    access-log-format: "%h %l %u %t "%r" %s %k %b %T %D "%{Referer}i" "%{User-Agent}i""
  broadworks:
    connection-timeout-millis: 60000
    ssl-permissive: true
    require-domain-on-credential-add: false
    update-alpaca-user-credentials-cn-change: false
  client:
    hide-enable-cisco-soft-client: true
    hide-authentication-reset: false
    header-text: 'BW Web Portal'
    header-image-u-r-l: 'images/logo.svg'
    always-remember-me: true
    custom-plugins-enabled: false
    style-sheets:
      - 'css/custom.css'
    am-charts:
      primary-colors:
        - "#653E4C"
        - "#7E4E60"
        - "#985D73"
        - "#AA7488"
        - "#B98D9D"
        - "#C9A6B3"
        - "#D8C0C9"
      complementary-colors:
        - "#412E1B"
        - "#715438"
        - "#916E4B"
        - "#B0875E"
        - "#C3A17F"
        - "#DBBA99"
        - "#EED3BA"
    logout-redirects-to-login: true
    enable-user-passcode-reset-without-previous-passcode: false
    breadcrumb-visibility:
      user:
        USER: 0
    hidden-navs:
      user.history:
        - USER
      user.registrations:
        - USER
        - GROUP
    device-name-config:
      device-name-template: "{device-name}"
      template-list:
        - name: "PolyTemplate"
          template: "PolyTemplate_{mac}"
          subtypes:
            - "Polycom VVX 600": "Polycom_VVX_600_{mac}"
            - "Polycom VVX 500": "Polycom_VVX_500_{mac}"
            - "Polycom VVX 300": "Polycom_VVX_300_{mac}"
            - "Polycom VVX 410": "Polycom_VVX_410_{mac}"
    user-replace:
      user-id-mask: "Mew User id"
      user-id-pattern: "^[A-Za-z0-9._%+-]"
  communigate:
    communigate-cluster-nickname: "Cluster1"
    communigate-service-provider-id: "Voice_Mail_Only"
    communigate-login-disabled-email: "voip.admin@acme.com"
    communigate-voicemail-dn-length: 10
  surge-mail:
    surge-mail-cluster-nickname: "Cluster1"
    surge-mail-service-provider-id: "Voice_Mail_Only"
    surge-mail-login-disabled-email: "voip.admin@acme.com"
    surge-mail-voicemail-d-n-length: 10
    mail-server-domains:
      - prod-domain.net
  file-store:
    location: /var/alpaca/store
    task-file-retention-period-months: 1
    report-file-retention-period-months: 6
    temp-file-retention-period-days: 90
    use-s3: false
    s3-endpoint: "https://s3.amazonaws.com"
    s3-region: "us-east-1"
    bucket-name: ""
    access-key-id: ""
    secret-access-key: ""
  mail:
    base-url: http://127.0.0.1:8080
    from: alpaca.alerts@email.com
  migration:
    announcement-repository-username: "BoNjOuRlEsAmIs049"
    announcement-repository-password: "viveLEROILouis14"
    authentication-username-changeable-regex: ".*(Polycom|Linksys|Cisco).*"
    authentication-password-changeable-regex: ".*(Polycom|Linksys|Cisco).*"
    blf-caching-enabled: true
    device-file-migration-rule-list:
      - device-type-regex: ".*(Polycom|Linksys|Cisco).*"
        file-regexes: [
          "%BWMACADDRESS%-directory.xml",
          "%BWMACADDRESS%-calls.xml",
        ]
    device-reboot-delay-millis: 5000
    html-encode-exports: true
    ignore-line-port-transforming: false
    update-expired-conference-schedules: true
    user-deletion-during-group-destroy-threshold: 450
    ignore-n-s-sync-error: false
  security:
    allow-registration: true
    max-failed-login-attempts: 5
    remember-me:
      key: XxXxXxXxXxXxXxXxXxXxXxXxX
    ip-fencing:
      SYSTEM:
        - "0.0.0.0/0"
      USER:
        - "192.168.0.1/24"
        - "192.168.0.2/24"
    password:
      enforce-nist-password-rules: true
      min-length: 12
      blacklist:
        - "password"
        - "secret"
        - "ecg"
  cisco-soft-client:
    copy-user-id-to-email: true
    service-pack-definitions:
      - service-pack-name: "UC Connect - AddOn"
        service-names:
          - Authentication
          - "Client License 17"
          - "BroadTouch Business Communicator Tablet - Video"
          - "Shared Call Appearance"
      - service-pack-name: "Communicator - AddOn"
        service-names:
          - Authentication
          - "Client License 17"
          - "BroadTouch Business Communicator Tablet - Video"
          - "Shared Call Appearance"
    mobile:
      enabled-by-default: true
      device-type-name: "Connect - Mobile"
      service-pack-name: "UC Connect - AddOn"
      line-port-template: |
        'connect-mobile-' + user.userId + "@domain.com"
      device-name-template: |
        'connect-mobile-' + user.userId.split('@')[0]
    tablet:
      enabled-by-default: false
      device-type-name: "Connect - Tablet"
      service-pack-name: "UC Connect - AddOn"
      line-port-template: |
        'connect-tablet-' + user.userId + "@domain.com"
      device-name-template: |
        'connect-tablet-' + user.userId.split('@')[0]
    desktop:
      enabled-by-default: true
      device-type-name: "Communicator - Desktop"
      service-pack-name: "Communicator - AddOn"
      line-port-template: |
        'connect-desktop-' + user.userId + "@domain.com"
      device-name-template: |
        'connect-desktop-' + user.userId.split('@')[0]
  bulk-provisioning:
    default-domain: acme.com
    sip-default-domain: sip.acme.com
    voicemail-email-domain: acme.com
    default-passcode: 1234
    default-password: "ChangeMe1!"
    max-rows: 1000
    activate-numbers: true
  license-entry:
    cleanup-interval: 365
    graphed-licenses:
      - "BusinessLine"
      - "Standard"
      - "PersonalMobility"
      - "Premium"
      - "CallCenterAgent"
      - "CallCenterSupervisor"
  number-inventory-management:
    enabled: true
    default-rate-center: "RateCenter1"
    country-codes:
      - "1"
    aging-period: 45
  tasks:
    task-difficulty-alert: 10000
    task-difficulty-refusal: 100000
  jobrunr:
    enable-cleanup: true
    succeeded-value: 1
    succeeded-unit: DAYS
    enqueued-value: 1
    enqueued-unit: DAYS
    deleted-value: 1
    deleted-unit: DAYS
    failed-value: 30
    failed-unit: DAYS
broadworks:
  asynchronous-timeout-millis: 12000
  auto-fire-millis: 1000
  connection-reconnect-attempts: 4
  connection-reconnect-delay-millis: 500
  encoding: "ISO-8859-1"
  max-requests-per-second: 40
  max-retries-for-system-error: 3
  number-of-sockets-per-server: 1
  trusted-host: true
  profile-server:
    - cluster: Production
      file-repo: ProfileServer
      username: fileadmin
      password: P@ssw0rd
    - cluster: Lab
      file-repo: ProfileServer
      username: fileadmin
      password: P@ssw0rd
  synchronous-timeout-millis: 60000
  validate-requests-on-fire: false
communigate:
  host: communigate.server
  port: 106
  login: postmaster
  password: password
surgemail:
  admin-username: admin
  admin-password: password
  login-timeout-minutes: 60
  path: /cgi/user.cgi
  protocol: http
  host: localhost:7026
  show: alpaca-surgemail.json
spring:
  rabbitmq:
    host: rabbitmq
    username: rabbitmq
    password: rabbitmq
  data:
    mongodb:
      database: alpaca
      uri: mongodb://localhost:27017
  session:
    timeout: 30m
  mail:
    host: smtp.gmail.com
    password: "emailPassword!"
    port: 587
    properties.mail.smtp:
      auth: true
      ssl.trust: smtp.gmail.com
      starttls.enable: true
    protocol: smtp
    username: alpaca.alerts@email.com
  servlet:
    multipart:
      location: tmp
      maxFileSize: 1000MB
      maxRequestSize: 1000MB
cdrprocessor:
  history:
    max: 180
  loaders:
    - clusters:
        - "Production"
      additional-details:
        redirectingReason: 40
      row-detail-map:
        header: 1
        failover:
          - 1
          - 45
          - 49
        call:
          - 314
          - 378
          - 403
          - 414
          - 435
          - 447
          - 465
  call-reporter-cluster-to-alpaca-cluster-map:
    production: Production
    lab1: Lab-Cluster-1

JobRunr (org.jobrunr)

  • dashboard.username: The access username to log into the JobRunr dashboard to view scheduled Alpaca tasks.
  • dashboard.password: The access password to log into the JobRunr dashboard.

Alpaca (alpaca)

alpaca is the root header for Alpaca Server related configurations.

Audit Logs (auditLogs)

Audit log configurations control what happens when Alpaca is parsing audit logs from BroadWorks.

  • 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.
  • retention-days: The number of days audit logs are retained for. -1 will cause the audit logs to be retained indefinitely.
  • skip-reads: If set to true, audit logs that are "reads" will be ignored by Alpaca.
  • skip-creates: If set to true, audit logs that are "UserSingleSignOnCreateDeviceTokenRequest" will be ignored by Alpaca. Defaults to false.
  • max-queue-size: The maximum number of audit logs allowed in the processing queue before Alpaca begins rejecting audit logs from the remote. Note that, the rejected audit logs will be accepted and processed once the queue size drops below the configured threshold. Defaults to 10000.
  • process-batch-size: The number of audit logs to pull out of the database into memory to process for each process cycle. Defaults to 250.
  • ignored-types: List of audit log types to ignore for audit log processing. Ignored entries will not be process, therefore they will not appear in the audit history within Alpaca.
  • resync-on-missing-file: On rare occasions, the Audit log file that Alpaca is currently processing can be removed from the Application Server before processing completes. Typically, when this happens, Alpaca performs a full re-sync of the affected cluster. If this value is set to false, Alpaca will move on to the next Audit log file instead of re-sync. This option could cause Alpaca to become out of sync with BroadWorks because the missing file never finished processing. Use at your own risk.
  • worker-threads: The number of workers to spawn for processing audit logs. If the number of threads is greater than the number of clusters, the number of threads will be reduced to the number of clusters. Defaults to 4.
  • lock-expiration-minutes: The number of minutes before the audit log queue lock will forcibly unlock. Defaults to 5.
  • completion-override: Percentage between 25 and 100. The percent of audit log queue workers that have completed their work and are waiting for other threads to complete. Once the percentage has been hit, the other workers will stop and work will be re-distributed on the next iteration. Defaults to 50.
  • max-iterations-per-thread: The number of iterations before a worker thread is stopped and work is re-distributed. Minimum value of 1. Default value 20.
  • verification-timeout-seconds: The number of seconds after an audit log verification poll is sent, before an initial alert is triggered. Defaults to 360 seconds.

Access Logs (access-logs)

Access log configurations control how to read in Apache Access logs from the BroadWorks XSP.

  • access-log-format: The log format that is used on your BroadWorks XSP. This can usually be found in the Tomcat server.xmlunder com.broadsoft.xsp.platform.AccessLogValve.pattern.

BroadWorks (broadworks)

Alpaca server configurations that relate to BroadWorks.

  • connection-timeout-millis: How long before an unanswered request is deemed timed out.
  • ssl-permissive: Whether to disable SNIExtension and use a universal trust strategy for SSL.
  • require-domain-on-credential-add: Whether a domain is required ot not when credentials are being added for a BroadWorks Cluster.
  • update-alpaca-user-credentials-cn-change: Defaults to false. If set to true, when a BroadWork User's password is updated within Alpaca and that User has an associated AlpacaUser, the AlpacaUser's credentials will also be updated.

Client (client)

Client configurations affect items that are seen on the Alpaca Server web interface.

  • hide-authentication-reset: If set to true, the SIP Authentication Reset action will be hidden from Users.
  • hide-enable-cisco-soft-client: If set to true, the Enable Cisco Soft Client action will be hidden from Users.
  • header-text: Text to be displayed in the header bar. Default is 'Alpaca'. If nothing is provided, text will be removed from the header.
  • header-image-u-r-l: Url to an image to be used in the header. If nothing is provided, no image will appear in the header. A height of 50px or smaller is recommended. Images stored locally should be put in <ALPACA_HOME>/static/images/.
  • logout-redirects-to-login: Defaults to true. When true, after logging out the user will be redirected to login. When false, the user will be redirected to a logout complete page.
  • enable-user-passcode-reset-without-previous-passcode: Defaults to false. Allows Alpaca Users with BroadWorks LoginType USER, to update their BroadWorks Voice Portal Passcode without providing the previous passcode.
  • style-sheets: An array of URLs (can be relative) that will be used by Alpaca as CSS. This will replace the existing style sheet and is intended to be used with the Alpaca styling project for branding.
  • am-charts.primary-colors: An array of quoted HEX HTML colors to be used as primary colors for the licensing chart. These default to the Alpaca slate palette.
  • am-charts.secondary-colors: An array of quoted HEX HTML colors to be used as secondary colors for the licensing chart. These default to the Alpaca brown palette.
  • always-remember-me: Defaults to true. If true, all login requests will automatically have remember-me set to true. If false, a Remember-Me checkbox will appear on the login page and the User will be able to choose whether or not to use it.
  • allow-archive-bypass: If set to true, an option to bypass archive will appear for some delete tasks within Alpaca. Defaults to false.
  • custom-plugins-enabled: If set to true, allows use of custom plugins. Defaults to false.

Configuration to change the visibility and depth of Alpaca breadcrumbs based on BroadWorks login types.

  • Model

client:
  breadcrumb-visibility:
    page-name:
      LoginType1: Depth
      LoginType2: Depth
  • Example

client:
  breadcrumb-visibility:
    user:
      USER: 0
      GROUP: 1
    group:
      GROUP: 0
  • Example explanation

In the above example, we are configuring the breadcrumb visibility for the User and Group pages. We have set USER login type to a depth of 0 and Group login type to a depth of 1 for the User page and we have set Group login type to a depth of 0 for the group page. A depth of 0 means that only the current level is visible and none of the higher breadcrumbs will be displayed. A depth of 1 means that the current level and one level above is visible in the bread crumb chain. In this example, if a Group admin was to navigate to the User's page, they would see the User's breadcrumb, as well as their own breadCrumb. If the depth was set to 2, the Group admin would also see the Service Provider/Enterprise breadcrumb. Depending on the page and login type, a depth of 0-4 can be used. If no configuration is provided, all breadcrumbs will be displayed.

  • Supported Login Types

    • USER
    • GROUP
    • DEPARTMENT
    • SYSTEM

  • Page Options

    • user
    • group
    • service-provider
    • cluster
    • group-access-device
    • sp-access-device
    • system-access-device

Hidden Navs (hidden-navs)

Configuration to hide individual nav tabs based on BroadWorks login type.

  • Model

client:
  hidden-navs:
    page-name.tab-name:
      - LoginType1
      - LoginType2
  • Example

client:
  brreadcrumb-visibility:
    user.registrations:
      - USER
      - GROUP
    user.history:
      - USER

In the above example, USER and GROUP login types would not be able to see the Registrations tab on the User's page. Also, USER login types would not be able to see the history tab on the User's page. If no configuration is provided, all tabs will be visible.

  • Page Options
    • user
    • group
    • service-provider
    • cluster
    • group-access-device
    • sp-access-device
    • system-access-device
    • admin

Device Name Config (deviceNameConfig)

Configuration to determine Device naming during a Device Migration.

  • device-name-template: Default template used for renaming the device. This is used if a template value is not supplied for a matched entry from the template list. Valid template replacement values are:
    • {deviceName}: The device's current name.
    • {deviceType}: The device's type.
    • {mac}: The device's MAC address.
  • template-list : Templates for Device's with potential subtypes.
    • name : Name of the templated DeviceType. This must match the name of a DeviceType in BroadWorks.
    • template : Default template for this type. This value will determine the Device's final name if a subtype is not selected.
    • subtypes : A map of Device Types to Device Type templates. The Device Type keys will appear in the Alpaca client under the selected template name. The template value will determine the Device's final name.

User Replace (userReplace)

Configurations used for the User Replace task.

  • user-id-mask: The title that will be used for the user id field in the User Replace wizard.
  • user-id-pattern: The regex pattern that the new user id for User Replace must match.

CommuniGate (communigate)

Client configurations used for the CommuniGate Voicemail tool.

  • communigate-cluster-nickname: The nickname of the BroadWorks cluster to associate Communigate with.
  • communigate-service-provider-id: This is the Service Provider ID that Users will be created within.
  • communigate-login-disabled-email: Where login disabled assistance requests will be sent.
  • communigate-voicemail-dn-length: The required number length for User creation. This is validated by the client.
  • mail-server-domains: List of mail server domain options to be used with the Communigate Voicemail Tool.

SurgeMail (surgemail)

Client configurations used for the SurgeMail Voicemail tool.

  • surge-mail-cluster-nickname: The nickname of the BroadWorks cluster to associate SurgeMail with.
  • surge-mail-service-provider-id: This is the Service Provider ID that Users will be created within.
  • surge-mail-login-disabled-email: Where login disabled assistance requests will be sent.
  • surge-mail-voicemail-d-n-length: The required number length for User creation. This is validated by the client.
  • mail-server-domains: List of mail server domain options to be used with the SurgeMail Voicemail Tool.
  • use-broad-works-password-rules: Passwords are generated using the BroadWorks password rules for the entity the user belongs to.
  • surge-mail-password-length: The length of the generated password. Ignored if use-broad-works-password-rules is set to true. Defaults to 12.
  • surge-mail-password-regex: The regex used to generate a password. This should match what is in SurgeMail. Ignored if use-broad-works-password-rules is set to true.

File Store (fileStore)

Configurations that deal with the Alpaca Filestore.

  • location: The absolute or relative location on the filesystem where exported files will be stored.
  • task-file-retention-period-months: The number of months tasks and the files (logs, attachments, etc.) associated with the task will be retained. Defaults to 1 month. If set to 0 or below, tasks will not be cleaned up.
  • report-file-retention-period-months : The number of months reports and the files (logs, attachments, etc.) associated with the report will be retained. Defaults to 6 months. If set to 0 or below, tasks will not be cleaned up.
  • temp-file-retention-period-days : The number of days to temporary files generated from tasks and reports will be retained. Defaults to 15 days. If set to 0 or below, tasks will not be cleaned up.
  • use-s3: Enables the use of S3 buckets to store Alpaca files. This is required when using HA clustering so that each server has access to associated logs and files for download.
  • s3-endpoint: The S3 endpoint, e.g. "https://s3.amazonaws.com"
  • s3-region: The region to which the S3 bucket belongs. e.g. "us-east-1"
  • bucket-name: The S3 bucket name to use.
  • access-key-id: The S3 access key id.
  • secret-access-key: The S3 secret access key.

Mail (mail)

Configurations for sending emails from Alpaca.

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

Migration (migration)

Configurations used for performing various migrations within Alpaca.

  • announcement-repository-username: The username to retrieve voice portal audio and video files from for migration procedures.
  • announcement-repository-password: The password to retrieve voice portal audio and video files from for migration procedures.
  • announcement-repository-use-https: Whether to use https when downloading announcement files from the repository. Defaults to true. Before Alpaca 11.0 (R25 support), this would have been false by default.
  • authentication-password-changeable: When randomizing a user's authentication password, the user's access device type must match the provided regular expression.
  • authentication-username-changeable: When randomizing a user's authentication username, the user's access device type must match the provided regular expression.
  • 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.
  • device-file-migration-rule-list: 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.
  • device-file-migration-rule-list/device-type-regex: This defines the file rule device type, as specified by regular expression.
  • device-file-migration-rule-list/file-regexes: Any number of files can be specified by exact name.
  • device-reboot-delay-millis: The delay in milliseconds between rebooting the device and performing the migration procedure.
  • html-encode-exports: When performing an export, special characters will be escaped if this option is turned on. Characters include <, >, &, =, and '.
  • 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.
  • update-expired-conference-schedules: If true, during a migration, expired Meet Me Conferences will be updated to the current time. Otherwise, the conference will not be migrated.
  • user-deletion-during-group-destroy-threshold: If a Group has more users than the threshold, each user will be individually deleted instead of being deleted as a part of the Group delete request.
  • ignore-n-s-sync-error: Configuration that will ignore an NS SYNC error returned from BroadWorks during a VoiceVPN Get Request call.
  • check-service-licensing-requirement: If false, the BroadWorks service license pre-check will not be performed. Defaults to true.

Security (security)

Configurations that can be used to make Alpaca more or less secure.

  • allow-registation: If true, Users will be able to register via the registration page, otherwise they will have to be manually added by an admin.
  • max-failed-login-attempts: The number of failed login attempts before an Alpaca User is locked out of their account. Defaults to 5 failed attempts.
  • remember-me.key: A unique key used for remember-me tokens. Should be a randomized string.
  • ip-fencing: Map of BroadWorks login type (SYSTEM, USER) to the allowed source subnets. If an Alpaca User of a provided type attempts to login from outside the provided ip space, login will be denied. If ip-fencing is not provided, logging in from anywhere is allowed.

Password (password)

Configurations for Alpaca User passwords.

  • enforce-nist-password-rules - If enabled, passwords must conform to NIST 5.1.1.2. Passwords cannot contain the Username, repeating digits, ascending or descending characters, and must have a minimum length of 8 characters. If disabled, only a minimum length of 8 will be enforced.
  • min-length - Password minimum length. Only used when enforceNistPasswordRules is set to true. Defaults to 8, minimum value is 8.
  • blacklist - List of phrases or character sequences that cannot be included in the password. Only used when enforceNistPasswordRules is set to true.

Cisco Soft Client (cisco-soft-client)

Configurations that can be used to control the way that Alpaca provisions services related to Cisco Soft clients.

  • enable-allow-call-retrieve: Controls whether the SCA Allow Call Retrieve option is enabled for the user. Defaults to no change.
  • enable-allow-bridging: Controls whether the SCA Allow Bridging option is enabled for the user. Defaults to no change.
  • enable-imp: Controls whether the Integrated IMP service is enabled for the user. Defaults to no change.
  • copy-user-id-to-email: When enabled, the user's email address (located in BroadWorks User Profile) will be set as their User ID.
  • service-pack-definitions: An array of service packs that will be created and authorized on the Service Provide and Group when provisioning Cisco Soft clients.
  • service-pack-definitions/service-pack-name: The name of the service pack.
  • service-pack-definitions/service-names: An array of the services to be added to the service pack. The names listed MUST match the name used in the BroadWorks Licenses. They are NOT necessarily the user-friendly name displayed in the BroadWorks web interface. (Ex: Integrated IMP is displayed as Integrated IM&P in the BroadWorks web interfaces, but BroadWorks OCI requires Integrated IMP instead.)
  • mobile: Sub-elements of mobile control the provisioning of mobile endpoints for Cisco Soft clients.
  • mobile/enabled-by-default: Controls whether mobile devices are provisioned by default as part of the Cisco Soft client provisioning task. Defaults to true.
  • mobile/device-type-name: The name of the Device Type to use for mobile devices. This device type must already exist in the system.
  • mobile/service-pack-name: The name of the Service Pack to assign to the user when provisioning a mobile device.
  • mobile/line-port-template: This template defines a Spring Expression Language (SpEL) statement used to calculate the line-port for the mobile device.
  • mobile/device-name-template: This template defines a Spring Expression Language (SpEL) statement used to calculate the device-name for the mobile device.
  • tablet: Sub-elements of tablet control the provisioning of tablet endpoints for Cisco Soft clients.
  • tablet/enabled-by-default: Controls whether tablet devices are provisioned by default as part of the Cisco Soft client provisioning task. Defaults to true.
  • tablet/device-type-name: The name of the Device Type to use for tablet devices. This device type must already exist in the system.
  • tablet/service-pack-name: The name of the Service Pack to assign to the user when provisioning a tablet device.
  • tablet/line-port-template: This template defines a Spring Expression Language (SpEL) statement used to calculate the line-port for the tablet device.
  • tablet/device-name-template: This template defines a Spring Expression Language (SpEL) statement used to calculate the device-name for the tablet device.
  • desktop: Sub-elements of desktop control the provisioning of desktop endpoints for Cisco Soft clients.
  • desktop/enabled-by-default: Controls whether desktop devices are provisioned by default as part of the Cisco Soft client provisioning task. Defaults to true.
  • desktop/device-type-name: The name of the Device Type to use for desktop devices. This device type must already exist in the system.
  • desktop/service-pack-name: The name of the Service Pack to assign to the user when provisioning a desktop device.
  • desktop/line-port-template: This template defines a Spring Expression Language (SpEL) statement used to calculate the line-port for the desktop device.
  • desktop/device-name-template: This template defines a Spring Expression Language (SpEL) statement used to calculate the device-name for the desktop device.

Service Packs specified in the mobile, tablet, and desktop sections are normally defined in service-pack-definitions.

Bulk Provisioning (bulk-provisioning)

Configurations that can be used to control the way that Alpaca treats certain fields during Bulk Provisioning.

  • default-domain: Domain used for User's if one is not explicitly provided. If not provided, defaults to the Group's default domain.
  • sip-default-domain: Domain used for the User's primary line/port if one is not explicitly provided. If not provided, defaults to the Group's default domain.
  • voicemail-email-domain: Domain used for User's Voice Messaging setting if one is not explicitly provided. If not provided, defaults to the Group's default domain.
  • default-passcode: Default passcode to use for Users if one is not explicitly provided. Defaults to random.
  • default-password: Default password to use for Users if one is not explicitly provided. Defaults to random.
  • default-voicemail-mode: The default Voicemail Mode to use when setting up voicemail. Options are 'FORWARD' or ' UNIFIEDGROUP'. Defaults to UNIFIEDGROUP.
  • default-blf-uri-domain: Domain used for User's BLF URI setting if one is not explicitly provided. If not provided, defaults to the Group's default domain.
  • max-rows: Maximum number of rows for spreadsheet. Defaults to 1000.
  • activate-numbers: If true, all numbers will be activated if the System Number Activation Mode is set to GROUPANDUSERACTIVATIONENABLED. Defaults to false.

License Entry (license-entry)

Configurations to control monitoring of BroadWorks licenses.

  • cleanup-interval: Defaults to 365. The number of days that a license entry will remain in the Alpaca database.
  • graphed-licenses: The BroadWorks licenses to display in the License Usage graph. Default licenses are: " BusinessLine", "Standard", "PersonalMobility", "Premium", "CallCenterAgent", "CallCenterSupervisor". License names can be found on the BroadWorks AS_CLI under System/Licensing. Limited to 7 licenses. If more than 7 are provided, only the first 7 will be used.

Tasks (tasks)

  • trunk-group-user-creation-monitor-minutes: How long to monitor for a BroadWorks TrunkGroupUserCreation task to complete. Defaults to 15 minutes.
  • task-difficulty-alert: The difficulty threshold that has to be crossed for a warning alert when about to run a task. Defaults to 10000. To disable, set to -1.
  • task-difficulty-refusal: The difficulty threshold that has to be crossed for Alpaca to refuse running a task. Defaults to 100000. To disable, set to -1.
  • executor.task-thread-count: The maximum number of threads to use for tasks. Defaults to 5.
  • executor.report-thread-count: The maximum number of threads to use for reports. Defaults to 5.
  • executor.broad-works-sync-threads: The maximum number of threads to use for the BroadWorks Sync task. Defaults to 5.
  • executor.bulk-delete-threads: The maximum number of threads to use for the Bulk User Delete task. Defaults to 5.
  • executor.anonymous-task-thread-count: The maximum number of threads to use for anonymous tasks. Defaults to 5.
  • executor.call-reporter-import-threads: The maximum number of threads to use for the Call Reporter Import Task. Defaults to 10.
  • executor.call-reporter-import-batch-size: The maximum number of database entities to query at one time during the Call Reporter Import Task. Defaults to 500.

Number Inventory Management (number-inventory-management)

Configurations for controlling the Number Inventory Management feature.

  • enabled: Whether the feature is enabled. Defaults to false.
  • default-rate-center: The rate center to assign to numbers within the system.
  • country-codes: List of country codes that your BroadWorks System uses. Defaults to ["1"].
  • aging-period: The number of days a number has to age before returning to the Available or Reserved state. Defaults to 45.

Endpoint Monitoring (endpoint-monitoring)

  • monitor-timeout-seconds - Timeout for monitoring endpoints. If an endpoint-monitor has not polled for the configured amount of seconds, then the endpoint will no longer be monitored. Defaults to 60 seconds.
  • monitor-loop-millis - How often to update data for monitored endpoints. Defaults to 30000 (30 seconds).
  • group-monitor-loop-millis - How often to update the backing group data for groups that are being monitored. Defaults to 60000 (60 seconds).

License Manager (license-manager)

  • enabled: Whether the license manager is enabled. Defaults to false. Must be enabled if using a subscription-based Alpaca license.
  • license-path: The file path for the Alpaca license. Defaults to /etc/alpaca/server/ecg.license.txt. No longer used as of Alpaca 10.6.0.
  • api-key: The generated API key to use to authenticate to the ECG License Manager. Can be generated from the ECG Portal.
  • expires-soon-days: The number of days for the license expires soon notification. The notification will be sent when the license expiration date is within this number of days. Minimum value is 7.
  • expires-very-soon-days: The number of days for the license expires very soon notification. The notification will be sent when the license expiration date is within this number of days. Minimum value is 1.

JobRunr (jobrunr)

JobRunr configurations specific to Alpaca.

  • enable-cleanup: If true, a nightly cleanup task will run and remove old jobs from the database. Defaults to true;
  • succeeded-value: The number of units old, before a succeeded job is removed by the cleanup task. Defaults to 1.
  • succeeded-unit: The unit for the succeeded value. Valid values: MINUTES, HOURS, DAYS, WEEKS, MONTHS. Defaults to DAYS.
  • enqueued-value: The number of units old, before an enqueued job is removed by the cleanup task. Defaults to 1.
  • enqueued-unit: The unit for the enqueued value. Valid values: MINUTES, HOURS, DAYS, WEEKS, MONTHS. Defaults to DAYS.
  • deleted-value: The number of units old, before a deleted job is removed (permanently) by the cleanup task. Defaults to 1.
  • deleted-unit: The unit for the deleted value. Valid values: MINUTES, HOURS, DAYS, WEEKS, MONTHS. Defaults to DAYS.
  • failed-value: The number of units old, before a failed job is removed by the cleanup task. Defaults to 30.
  • failed-unit: The unit for the succeeded value. Valid values: MINUTES, HOURS, DAYS, WEEKS, MONTHS. Defaults to DAYS.

Broadworks (broadworks)

broadworks is the root header for Alpaca Library related configurations.

  • asynchronous-timeout-millis: Timeout for asynchronous calls.
  • auto-fire-millis: When using a RequestBundler this timeout controls how long to wait before firing a request with less than 15 entries.
  • 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 is lost to attempt to reconnect.
  • 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.
  • max-retries-for-system-error: The number of times to retry a request if it comes back as a System Error.
  • number-of-sockets-per-server: How many sockets will be opened per BroadWorksServer connection.
  • synchronous-timeout-millis: Timeout for synchronous calls.
  • 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.
  • trusted-host: Whether or not the Alpaca server is in the External Authentication network access list on the XSP and Application Servers. Required for Single Sign-On.

File Repository (profileServer)

Configurations used for connecting Alpaca to a BroadWorks file repository (usually a profile server).

  • cluster: The nickname of the cluster configured in Alpaca.
  • file-repo: The file repository name in BroadWorks.
  • password: The password of the file repository admin.
  • username: The username of the file repository admin.

Communigate (communigate)

Configurations used for connecting Alpaca to a CommuniGate Voicemail server for use with the Alpaca CommuniGate Voicemail Tool.

  • host: The hostname or IP address of the CommuniGate server to connect to.
  • port: The CLI port for the Communigate server. This defaults to 106.
  • login: The admin login to use to perform changes. The account must have permissions to create, modify, and delete accounts for the desired domain.
  • password: The password for the associated login.

SurgeMail (surgemail)

Configurations used for connecting Alpaca to a SurgeMail Voicemail server for use with the Alpaca SurgeMail Voicemail Tool.

  • protocol: The protocol used to access the SurgeMail server.
  • host: The address of SurgeMail server.
  • path: The path element of the URI.
  • show: Controls the file template used by SurgeMail to return the REST responses.
  • admin-username: The SurgeMail admin Username.
  • admin-password: The SurgeMail admin Password.
  • login-timeout-minutes: The amount of time before timing out during a login attempt.

Show File

The location to place this file is dependent on the SurgeMail's configuration specified as the web_path. By default, this location is /usr/local/surgemail/web/. The name of the file (default is alpaca-surgemail.json) should match the show configuration and the contents should be as follows:

{
  "detailMessage": "||message2||",
  "requestSuccessful": false,
  "simpleMessage": "||message||",
  "utoken": "||utoken||"
}

Spring (spring)

Session

  • timeout - The session timeout for the web interface. Defaults to 30 minutes. Cannot be less than 1 minute. A value of 0 will disable the timeout. Example values: 1d (1 day), 30d (30 days), 1h (1 hour), 12h (12 hours), 30m (30 minutes), 5m (5 minutes)

MongoDB (data.mongo)

The MongoDB configuration can be put in the data portion of your alpaca-server-prod.yml configuration file.

  • database: The name of the database to use for Alpaca. This should always be alpaca.
  • uri: The address of the local Mongo installation. This is typically mongodb://localhost:27017. If using authentication, the URI should look like mongodb://<MY_ALPACA_DB_USER>:<MY_PASSWORD>@localhost:27017/alpaca.
    • Note that if your password contains : or @, it will need to be URL encoded.

Email (mail)

  • host: The server to connect to.
  • password: The password for the email account that is being used.
  • port: The port to connect to. Defaults to 25.
  • 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.
    • 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.
    • 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.
  • username: The email account to use to send emails from.

File Upload (servlet.multipart)

  • location: Intermediate location of uploaded files.
  • 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.

RabbitMQ (rabbitmq)

  • host: A comma separated list of RabbitMQ servers to connect to. This is used for events and messaging to clients.
  • username: The RabbitMQ username to use.
  • password: The RabbitMQ password to use.

SSO Configuration

Single Sign-On (SSO) is an Alpaca feature that allows registration and association with BroadWorks through a 3rd party authentication provider. The requirements and usages guide can be found in the concepts guide.

Configurations (spring.security)

OAuth/OAuth2 (oauth/oauth2) 
spring:
  security:
    oauth2:
      client:
        registration:
          google:
            client-id: id-provided-by-provider
            client-secret: secret-provided-by-provider
            client-name:
            scope: email
        provider:
          google:
            issuer-uri: https://accounts.google.com
  • registration.{service-name}: A name for the client. This can be any value the configurer would like. In this example, the name is google but it could be any OAuth provider or even the value SSO. This value is shown to the end user as a capitalized value to select during login.
  • registration.{service-name}.client-id: This is provided by the OAuth registration provider.
  • registration.{service-name}.client-secret: This is provided by the OAuth registration provider.
  • registration.{service-name}.client-name: This is provided by the OAuth registration provider.
  • registration.{service-name}.scop: This should be set to email.
  • provider.{service-name}: This value must match the value in the registration name. It is also dynamic but must match the previously configured value.
  • provider.{service-name}.issuer-uri: This is the URI as given by the specified authorization server. Examples:
    • Google: https://accounts.google.com
    • Okta: https://{{project}}.okta.com/oauth2/default
SAML2 (saml2) 
spring:
  security:
    saml2:
      relyingparty:
        registration:
          okta:
            signing.credentials:
              - private-key-location: "classpath:credentials/rp-private.key"
                certificate-location: "classpath:credentials/rp-certificate.cert"
            assertingparty:
              entity-id: http://www.okta.com/xxxxxxxxxxx
              verification.credentials:
                - certificate-location: "classpath:credentials/idp-certificate.cert"
              singlesignon.url: sso.url.account.xyz
              singlesignon.sign-request: true
  • registration.{service-name}: A name for the client that can be any value the configurer would like. In this example, the name is okta, but it could be any SAML provider or even the value SSO. This value is shown to the end user as a capitalized value to select during login.
  • private-key-location: The private key of the Relying Party. In this example location, the key is in the classpath of Alpaca. Valid directories for this are /opt/alpaca and /etc/alpaca/server. Example full path for certificates and keys: /etc/alpaca/server/credentials/*
  • certificate-location: The certificate of the Relying Party. See private-key-location for location assistance.
  • entity-id: The ID/URL provided by SAML provider.
  • verification.credentials.certificate-location: The certificate of the SAML identity provider. See private-key-location for location assistance.
  • singlesignon.url: The authentication URL as provided by the SAML provider.
  • singlesignon.sign-request: false: Whether or not the SSO request is signed. Defaults to true.

Access Logs

server:
  tomcat:
    accesslog:
      enabled: true
      directory: access-logs-#BW.Version#
      pattern: "%h %t %{username}r \"%r\" %s %b %D"
  • enabled - Whether or not access logging is enabled. Defaults to true.
  • directory - The directory where access logs are written. Defaults to access-logs-BW.Version.
  • pattern - The access logs pattern. Defaults to %h %t %{username}r \"%r\" %s %b %D. See Tomcat Access Log Guide for more information on access log patterns.

CDR Processing (cdrprocessor)

History

  • max: The maximum number of days of data retained.

Loaders

  • clusters: List of Cluster names that this loader is used for.
  • additional-details: This is a map of field names and CDR indexes to be added to the additionalDetails section of the Call collection.
  • row-details: A map of row types to a list of acceptable lengths.

Miscellaneous

  • call-reporter-cluster-to-alpaca-cluster-map - Used for importing a legacy Call Reporter database into Alpaca. Maps a Call Reporter Cluster to an Alpaca Cluster. The left side is the cluster name in Call Reporter, and the right side is the name of the corresponding Cluster in Alpaca.

Profiles

  • prod: This is the primary configuration for production.
  • sso: Enables Single Sign On. See the SSO Configuration

Profile selection can be done in the /ALPACA_HOME/configuration file. See below.

# The Alpaca profiles to run
# See available options: https://guides.ecg.co/alpaca/latest/configuration/#profiles
export PROFILES=prod

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.

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

Alpaca CLI (alpaca.cli)

Configurations can be modified in the application-prod.yml file located in the Alpaca CLI config directory. Configurations for the CLI are used to connect it to the Alpaca Server.

  • server-scheme: The scheme to use to connect to the Alpaca server. HTTPS is the only scheme that is currently supported.
  • server-address: The address of the Alpaca server.
  • server-port: The port to use to connect to the Alpaca server.
  • ssl-permissive: Whether to be permissive with insecure SSL (such as self-signed certificates).
alpaca:
  cli:
    serverScheme: https
    serverAddress: localhost
    serverPort: 8443
    sslPermissive: true

Logging Configuration

Location of Logging Configuration File

The log configuration file can be found at /etc/alpaca/server/config/logback-spring.xml.

As of Alpaca 10.4.0, the logging configuration can be edited and the changes will be live reloaded without having to restart Alpaca. If you choose to remove <configuration scan="true" scanPeriod="30 seconds"> from your config, live reloads will no longer happen.

Key Logging Settings

Rolling Policy: <rollingPolicy>

Defines the rules for log file rotation and archiving.

  • <fileNamePattern>: Sets the naming pattern for the archived logs.
  • <cleanHistoryOnStart>: Manages if the old logs should be deleted when the application starts.
  • <maxFileSize>: Sets the size limit for each log file.
  • <totalSizeCap>: Sets the size limit for all log files combined.
  • <maxHistory>: Controls how many old log files to keep before removing the oldest.

Logger Levels

These logging levels will control the verbosity of logging for specific packages or classes.

Available Levels

  • OFF: No logging.
  • ERROR: Logs error events only.
  • WARN: Logs warning and error events.
  • INFO: Logs informational, warning, and error events.
  • DEBUG: Logs debugging, informational, warning, and error events.
  • TRACE: Logs trace, debugging, informational, warning, and error events.
  • ALL: Logs all events.

Root Logger: <root level="INFO">

The level of the root logger sets the default logging level for the entire application.

JAVA_HOME

Required Java versions as of Alpaca 9.3.0:

  • Alpaca Server - Java 17
  • Alpaca Remote - Java 8

If the server that Alpaca Server or Remote is installed is running multiple versions of Java, and the required version for Alpaca is not the default, the JAVA_HOME variable for Alpaca can be manually set in the /ALPACA_HOME/configuration file. See below:

# Java Home
export JAVA_HOME=/usr/lib/jvm/<required_java_version>

IP Tables / Firewall-D

Notes

  • All of these configurations can be controlled by an external firewall. In this case, iptables/firewall-d are not needed.
  • This document is meant as an example of possible configurations. Your final setup may differ.
  • The following rules use the ports configured by default.
  • The following rules only limit the ports, they can be further enhanced to limit access from certain ip addresses or subnets.

Single Server Setup (Non-HA)

// HTTPS - Gateway
iptables -I INPUT -p tcp --dport 8443 -j ACCEPT
firewall-cmd --permanent --zone=public --add-port=8443/tcp

// RabbitMQ Management Interface
iptables -I INPUT -p tcp --dport 15672 -j ACCEPT
firewall-cmd --permanent --zone=public --add-port=15672/tcp

// JobRunr Web Interface
iptables -I INPUT -p tcp --dport 8001 -j ACCEPT
firewall-cmd --permanent --zone=public --add-port=8001/tcp

HA

// HTTPS - Gateway
iptables -I INPUT -p tcp --dport 8443 -j ACCEPT
firewall-cmd --permanent --zone=public --add-port=8443/tcp

// RabbitMQ Management Interface
iptables -I INPUT -p tcp --dport 15672 -j ACCEPT
firewall-cmd --permanent --zone=public --add-port=15672/tcp

// Eureka/Discovery between Alpaca Servers
iptables -I INPUT -p tcp --dport 8761 -j ACCEPT
firewall-cmd --permanent --zone=public --add-port=8761/tcp

// Mongo DB between Alpaca Servers
iptables -I INPUT -p tcp --dport 27017 -j ACCEPT
firewall-cmd --permanent --zone=public --add-port=27017/tcp

// Rabbit MQ between Alpaca Servers
iptables -I INPUT -p tcp --dport 5672 -j ACCEPT
firewall-cmd --permanent --zone=public --add-port=5672/tcp