Alpaca 7.2

Configuration

This guide details all configurations that are available within Alpaca. All configurations can be used in the application-prod.yml file located in the /etc/alpaca/server.

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:
          announcementRepositoryUsername: "BoNjOuRlEsAmIs049"
          announcementRepositoryPassword: "viveLEROILouis14"
          htmlEncodeExports: true

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

      broadworks:
    profileServer:
    - cluster: Production
      fileRepo: ProfileServer
      username: fileadmin
      password: P@ssw0rd
    - cluster: Lab
      fileRepo: ProfileServer
      username: fileadmin
      password: P@ssw0rd

  • Comments are denoted by #.

      # Alpaca Configuration
  alpaca:
      # Migration Configuration
      migration:
        announcementRepositoryUsername: "BoNjOuRlEsAmIs049"
        announcementRepositoryPassword: "viveLEROILouis14"
        htmlEncodeExports: 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 pre-defined configurations. The complete list of configuration options can be found here.

Example Configuration

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

alpaca:
    auditLogs:
      fireAlertsForTasks: false
      retentionDays: -1
      skipReads: true
    client:
      hideAuthenticationReset: false
      deviceNameConfig:
        deviceNameTemplate: "{deviceName}"
        templateList:
        - 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}"
      userReplace:
        userIdMask: "New User Id"
        userIdPattern: "^[A-Za-z0-9._%+-]"
    communigate:
        communigateClusterNickname: "Cluster1"
        communigateServiceProviderId: "Voice_Mail_Only"
        communigateLoginDisabledEmail: "voip.admin@acme.com"
        communigateVoicemailDnLength: 10
    fileStore:
      cleanupInterval: 90
      location: /opt/alpaca/filestore
    mail:
      baseUrl: http://127.0.0.1:8080
      from: alpaca.alerts@email.com
    migration: 
      announcementRepositoryUsername: "BoNjOuRlEsAmIs049"
      announcementRepositoryPassword: "viveLEROILouis14"
      authenticationUsernameChangeableRegex: ".*(Polycom|Linksys|Cisco).*"
      authenticationPasswordChangeableRegex: ".*(Polycom|Linksys|Cisco).*"
      blfCachingEnabled: true
      deviceFileMigrationRuleList:
        -
          deviceTypeRegex: ".*(Polycom|Linksys|Cisco).*"
          fileRegexes: [
            "%BWMACADDRESS%-directory.xml",
            "%BWMACADDRESS%-calls.xml",
          ]
      deviceRebootDelayMillis: 5000
      htmlEncodeExports: true
      ignoreLinePortTransforming: false
      updateExpiredConferenceSchedules: true
      userDeletionDuringGroupDestroyThreshold: 450
      ignoreNSSyncError: false
    security:
      allowRegistration: true
      rememberMe:
        key: XxXxXxXxXxXxXxXxXxXxXxXxX
    uc-one:
            enabled: 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:
                device-type-name: "Connect - Mobile"
                service-pack-name: "UC Connect - AddOn"
                line-port-template: |
                    'connect-mobile-' + user.userId
                device-name-template: |
                    'connect-mobile-' + user.userId.split('@')[0]
            tablet:
                device-type-name: "Connect - Tablet"
                service-pack-name: "UC Connect - AddOn"
                line-port-template: |
                    'connect-tablet-' + user.userId
                device-name-template: |
                    'connect-tablet-' + user.userId.split('@')[0]
            desktop:
                device-type-name: "Communicator - Desktop"
                service-pack-name: "Communicator - AddOn"
                line-port-template: |
                    'connect-desktop-' + user.userId
                device-name-template: |
                     'connect-desktop-' + user.userId.split('@')[0]
broadworks:
    asynchronousTimeoutMillis: 12000
    autoFireMillis: 1000
    connectionReconnectAttempts: 4
    connectionReconnectDelayMillis: 500
    connectionTimeoutMillis: 60000
    encoding: "ISO-8859-1"
    maxRequestsPerSecond: 40
    maxRetriesForSystemError: 3
    numberOfSocketsPerServer: 1
    profileServer:
        - cluster: Production
          fileRepo: ProfileServer
          username: fileadmin
          password: P@ssw0rd
        - cluster: Lab
          fileRepo: ProfileServer
          username: fileadmin
          password: P@ssw0rd
    sslPermissive: true
    synchronousTimeoutMillis: 60000
    validateRequestsOnFire: false
communigate:
  framework-address: 192.168.1.1:8888/framework2.0/framework.php
  api-key: a58845119f2c1ff84255433300ee555efa5ee259b423296904b0894a891ef859
  domain: domain.net
spring:
    data:
      mongodb:
        database: alpaca
        uri: mongodb://localhost:27017
    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
    server:
      port: 8443
      ssl:
        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
        keyAlias: 1
        keyPassword: myKeyPassword!        
        keyStore: config/keystore.pkcs12
        keyStorePassword: myStorePassword!
        keyStoreType: PKCS12
        protocol: TLSv1.2
    servlet:
      multipart: 
        location: tmp
        maxFileSize: 1000MB
        maxRequestSize: 1000MB

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.

  • fireAlertsForTasks: If disabled, Alpaca will not fire alerts for audit logs that are the result of a task that Alpaca started, i.e. Enterprise Migration.
  • retentionDays: The number of days audit logs are retained for. -1 will cause the audit logs to be retained indefinitely.
  • skipReads: If set to true, audit logs that are "reads" will be ignored by Alpaca.

Client (client)

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

  • hideAuthenticationReset: If set to true, the SIP Authentication Reset action will not be hidden from Users.

Device Name Config (deviceNameConfig)

Configuration to determine Device naming during a Device Migration.

  • deviceNameTemplate: 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.
  • templateList : 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.

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

CommuniGate (communigate)

Client configurations used for the CommuniGate Voicemail tool.

  • communigateClusterNickname - The nickname of the BroadWorks cluster to associate Communigate with.
  • communigateServiceProviderId - This is the Service Provider ID that Users will be created within.
  • communigateLoginDisabledEmail - Where login disabled assistance requests will be sent.
  • communigateVoicemailDnLength - The required number length for User creation. This is validated by the client.

File Store (fileStore)

Configurations that deal with the Alpaca Filestore.

  • cleanupInterval: The number of days between file store cleanups.
  • location: The absolute or relative location on the filesystem where exported files will be stored.

Mail (mail)

Configurations for sending emails from Alpaca.

  • baseUrl - 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.

  • 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.
  • blfCachingEnabled: 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.
  • 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.
  • 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 '.
  • ignoreLinePortTransforming: 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.
  • updateExpiredConferenceSchedules: If true, during a migration, expired Meet Me Conferences will be updated to the current time. Otherwise, the conference will not be migrated.
  • userDeletionDuringGroupDestroyThreshold: 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.
  • ignoreNSSyncError: Configuration that will ignore an NS SYNC error returned from BroadWorks during a VoiceVPN Get Request call.

Security (security)

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

  • allowRegistation - If true, Users will be able to register via the registration page, otherwise they will have to be manually added by an admin.
  • rememberMe.key - A unique key used for remember-me tokens

UC-One (uc-one)

Configurations that can be used to control the way that Alpaca provisions services related to UC-One clients.

  • enabled: Controls whether the UC-One client provisioning task is available to users. Defaults to false.
  • service-pack-definitions: An array of service packs that will be created and authorized on the Service Provide and Group when provisioning UC-One 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.
  • mobile: Sub-elements of mobile control the provisioning of mobile endpoints for UC-One clients.
  • mobile/enabled: Controls whether mobile devices are provisioned as part of the UC-One 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 UC-One clients.
  • tablet/enabled: Controls whether tablet devices are provisioned as part of the UC-One 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 UC-One clients.
  • desktop/enabled: Controls whether desktop devices are provisioned as part of the UC-One 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 deskstop sections are normally defined in service-pack-definitions.

Broadworks (broadworks)

broadworks is the root header for Alpaca Library related configurations.

  • asynchronousTimeoutMillis: Timeout for asynchronous calls.
  • autoFireMillis: When using a RequestBundler this timeout controls how long to wait before firing a request with less than 15 entries.
  • connectionReconnectAttempts: How many times to attempt a reconnect to BroadWorks once a connection is lost.
  • connectionReconnectDelayMillis: How long after a connection lost to attempt to reconnect.
  • connectionTimeoutMillis: How long before an un-answered request is deemed timed out.
  • encoding: The encoding to use for the outgoing and incoming parsing of BroadWorks messages.
  • maxRequestsPerSecond: 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.
  • maxRetriesForSystemError: The number of times to retry a request if it comes back as a System Error.
  • numberOfSocketsPerServer: How many sockets will be opened per BroadWorksServer connection.
  • sslPermissive: Whether to disable SNIExtension and use a universal trust strategy for SSL.
  • synchronousTimeoutMillis: Timeout for synchronous calls.
  • validateRequestsOnFire: 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.

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.

  • frameworkAddress: The CommuniGate server to connect to.
  • api-key: The api key provided by CommuniGate.
  • domain: The domain used for CommuniGate.

Spring (spring)

MongoDB (data.mongo)

The MongoDB configuration can be put in the data portion of your application-prod.yaml 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.

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.

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.

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

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

  1. # cp keystore.pkcs12 /opt/alpaca/config/
  2. # chown alpaca:alpaca /opt/alpaca/config/config/keystore.pkcs12

Configurations (server.ssl)

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

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

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.

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

Alpaca Remote (alpaca.remote)

Configurations used for the Alpaca Remote application. Alpaca Remote's application_prod.yml file is located in the config directory of the Alpaca Remote root directory.

  • maximum-queue-size-per-server-in-megabytes - The maximum size the audit log queue can be before transmitting to the server.
  • servers - List of configured Application Servers.
    • scheme - The scheme to use to connect to the alpaca server. HTTPS is the only scheme that is currently supported.
    • hostname - The hostname of the Alpaca server to send logs to.
    • port - The port that the Alpaca server is running on.
    • broadWorksLicensePath - The path to the BroadWorks License on the Application Server. (Only needs to be provided for the primary)
    • authenticationToken - The authentication token generated from the Server that identifies the reader.
    • reader.directory - The directory to read from.
alpaca:
  remote:
    maximum-queue-size-per-server-in-megabytes: 3
    servers:
    -
      scheme: https
      hostname: alpaca.prod.com
      port: 8443
      broadWorksLicensePath: /path/to/license.txt/on/as
      authenticationToken: GwW_T5DMrxrADm5SibMAd3owKD0nrowE
      reader:
       directory: /path/to/as1
    -
      scheme: https
      hostname: alpaca.prod.com
      port: 8443
      authenticationToken: UjUZarkK8dKAAYu_kpJgLAE6EqiHBSyh
      reader:
       directory: /path/to/as2

Alpaca CLI (alpaca.cli)

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

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