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.

Any changes made while Alpaca is running will not take effect until after a restart. Use the following command to restart Alpaca - service alpaca-<server|remote> restart.

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
  access-logs:
    access-log-format: "%h %l %u %t "%r" %s %k %b %T %D "%{Referer}i" "%{User-Agent}i""
  broadworks:
    connectionTimeoutMillis: 60000
    sslPermissive: true
    requireDomainOnCredentialAdd: false
  client:
    hideEnableCiscoSoftClient: true
    hideAuthenticationReset: false
    header-text: 'BW Web Portal'
    header-image-u-r-l: 'https://www.my-site.co/assets/logo.svg'
    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
    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
    ip-fencing:
      SYSTEM:
        - "0.0.0.0/0"
      USER:
        - "192.168.0.1/24"
        - "192.168.0.2/24"
  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: 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: 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: 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!"
broadworks:
  asynchronousTimeoutMillis: 12000
  autoFireMillis: 1000
  connectionReconnectAttempts: 4
  connectionReconnectDelayMillis: 500
  encoding: "ISO-8859-1"
  maxRequestsPerSecond: 40
  maxRetriesForSystemError: 3
  numberOfSocketsPerServer: 1
  trusted-host: true
  profileServer:
    - cluster: Production
      fileRepo: ProfileServer
      username: fileadmin
      password: P@ssw0rd
    - cluster: Lab
      fileRepo: ProfileServer
      username: fileadmin
      password: P@ssw0rd
  synchronousTimeoutMillis: 60000
  validateRequestsOnFire: false
communigate:
  host: communigate.server
  port: 106
  login: postmaster
  password: password
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.

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.

• connectionTimeoutMillis: How long before an un-answered request is deemed timed out.
• sslPermissive: Whether to disable SNIExtension and use a universal trust strategy for SSL.
• requireDomainOnCredentialAdd: Whether or not a domain is required when credentials are being added for a BroadWorks Cluster.

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 be hidden from Users.
• hideEnableCiscoSoftClient: 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.
• 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.

Breadcrumb Visibility (breadcrumb-visibility)

Configuration to change the visibility and depth of Alpaca breadcrumbs based off of 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 bread crumb 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 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.

• 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.
• mailServerDomains - List of mail server domain options to be used with the Communigate Voicemail Tool.

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

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: Controls whether mobile devices are provisioned 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: Controls whether tablet devices are provisioned 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: Controls whether desktop devices are provisioned 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 deskstop 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.

Tasks

• retentionPeriodDays: How many days to keep a task. Defaults to 30.
• trunkGroupUserCreationMonitorMinutes: How long to monitor for a BroadWorks TrunkGroupUserCreation task to complete. Defaults to 15 minutes.

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.
• 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.
• 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.
• trustedHost: 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.

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.

SSO Configuration

Single Sign-On 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:
        provider:
          google:
            issuer-uri: https://accounts.google.com

• registration.{service-name} - A name for the client that 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.
• 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"
            identityprovider:
              entity-id: http://www.okta.com/xxxxxxxxxxx
              verification.credentials:
                - certificate-location: "classpath:credentials/idp-certificate.cert"
              sso-url: sso.url.account.xyz  

• 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.
• sso-url - The authentication URL as provided by the SAML provider.

Profiles

• prod - This is the primary configuration for production.
• https - Enables ssl. See the SSL Configuration.
• 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,https

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.

• servers - List of configured Servers.
  • scheme - The scheme used to connect to the Alpaca server. HTTPS is the only scheme that is currently supported.
  • hostname - The hostname of the Alpaca server.
  • port - The port the Alpaca server is running on.
  • authenticationToken - The authentication token generated from the Alpaca server that identifies the reader.
  • clients - List of configured clients.
    • type - The type of client. Valid options are AUDIT_LOG, ACCESS_LOG, and BW_LICENSE.
    • path - The path to the directory to read.
    • maximum-queue-size-per-server-in-megabytes - (Optional) The maximum size the audit log queue can be before transmitting to the server. Defaults to 5mb if not specified.
    • outbound-message-size-in-megabytes - (Optional) The size at which to send outbound messages. Defaults to 1mb if not provided.

# ===================================================================
# Remote Configuration on BW Application Server
# ===================================================================
alpaca:
  remote:
    servers:
      - scheme: https
        hostname: alpaca.server.com
        port: 8443
        authenticationToken: XXXXYYYYZZZZ1111
        clients:
          - type: AUDIT_LOG
            path: /path/to/audit/logs
            maximum-queue-size-per-server-in-megabytes: 3
          - type: BW_LICENSE
            path: /path/to/bw/license           

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

JAVA_HOME

Required Java versions as of Alpaca 8.0.0:

• Alpaca Server - Java 11
• 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>