Using the accelerator.properties File

9 minute read

The accelerator.properties file allows you to modify parameters that affect a range of Accelerator behaviors. The file resides on the Cluster Manager in the following default location:

  • Linux: <install_dir>/i686_Linux/conf where <install_dir> is /opt/ecloud by default

  • Windows: <install_dir>\i686_win32\conf, where <install_dir> is C:\ECloud by default

  • Solaris SPARC: <install_dir>/sun4u_SunOS/conf, where <install_dir> is /opt/ecloud by default

  • Solaris x86: <install_dir>/i686_SunOS.5.10/conf, where <install_dir> is /opt/ecloud by default

The following topics discuss parameters configurable through the accelerator.properties file. After you modify the accelerator.properties file, you must apply the changes by restarting the Cluster Manager service. For more information, see Stopping, Starting, or Restarting the Cluster Manager Service.

Changing Log Locations

Modify the following parameters to change the location of build logs and accelerator logs:

  • ACCELERATOR_BUILD_LOGS_PATH=build_logs

  • ACCELERATOR_LOG=logs/accelerator.log

Disabling Agents by Default

Agents are enabled by default. If you wish to disable them by default:

  1. Change the ACCELERATOR_AGENTS_STARTUP_ENABLED property to false. This change affects agents installed after this point; existing agents on the Agents tab are not affected.

  2. If you want the property to change the behavior of existing agents, you must restart the Cluster Manager service.

User Authentication

Accelerator uses account information from multiple sources. In most cases, the primary account information source is an external LDAP or Active Directory repository: both user and group information is retrieved from the repository. Local users and groups can be defined within Accelerator.

Getting Started

  1. Go to the following directory on the Cluster Manager server: <ECloud install>/<arch>/conf

  2. Make a copy of the ldap_template.xml file if you intend to use LDAP, or the ad_template.xml file if you prefer to use Active Directory. Save the copy in the conf directory as any name you choose or use the name: securityContext.xml.

  3. Still working in conf, open the accelerator.properties file.

    • Locate the following commented-out text string: #ACCELERATOR_SECURITY_CONTEXT_FILES=conf/securityContext.xml

    • If you did not name your template copy securityContext.xml, replace `securityContext.xml ` with the file name you chose.

    • Uncomment the `ACCELERATOR_SECURITY_…​ ` text string by removing the lead “” sign.

    • Comment out `ACCELERATOR_SECURITY_CONTEXT_FILES= ` (which immediately follows the line you uncommented)

  4. Use the LDAP information and examples in the following sections to fill in your own copy of the LDAP template.

  5. Restart the Cluster Manager service.

  6. After the Cluster Manager is running, log in to the Cluster Manager UI as “admin”.

  7. Go to Administration > Permissions .

  8. Click Enable User or Enable Group.

  9. Search for the desired user or group (or search for “*” to see all). If you set it up correctly, the requested LDAP users are visible.

  10. Select the appropriate users or groups to enable using the corresponding checkbox(es).

  11. Ensure that the desired permissions are set for the users or groups. (The online help system contains additional information about permissions.)

If you experience permissions issues while reading the ldap_template.xml or ad_template.xml copy, verify that the account that runs the Cluster Manager also has read permission for that file. To diagnose problems that cause Cluster Manager startup issues, including LDAP/Active Directory configuration problems, check <ECloud install>/<arch>/logs/accelerator.log.

Configuring LDAP

A number of options must be customized for any LDAP configuration. The following sample configuration is from the ldap_template.xml file. After the sample, see a list of properties with a description.

Sample LDAP Configuration

<bean id="ldapDirectoryProvider"         class="com.electriccloud.security.ldap.    LdapDirectoryProviderImpl"><property name="providerName" value="LDAP"/><property name="url" value="ldap://myldaphost/dc=company,dc=com"/><property name="userBase" value="ou=People"/><property name="userSearchFilter" value="uid={0}"/><property name="userSearchSubtree" value="false"/><property name="userNameAttribute" value="uid"/><property name="fullUserNameAttribute" value="gecos"/><property name="emailAttribute" value="mail"/><!--<property name="managerDn" value="uid=admin,ou=People,dc=company,dc=com"/> --><!--<property name="managerPassword" value="password"/> --><!--<property name="groupBase" value="ou=Group"/> --><!--<property name="groupMemberFilter" value="(member={0})"/> --><!--<property name="groupMemberAttributes" value="member"/> --><!--<property name="groupSearchFilter" value="(objectClass=groupOfNames)"/> --><!--<property name="groupNameAttribute" value="cn"/> --><!--<property name="verifyCerts" value="true"/> --></bean>

Properties for Configuring LDAP Mapping

The following properties configure LDAP mapping:

Property Description

emailAttribute

(optional) The attribute in a user record that contains the user’s email address. If the attribute is not specified, the account name and domain name are concatenated to form an email address.

fullUserNameAttribute

(optional) The attribute in a user record that contains the user’s full name (first and last name) for display in the UI. If this attribute is not specified or the resulting value is empty, the user’s account name is used instead.

managerDn

(optional) The DN of a user who has read-only access to LDAP user and group directories. If this property is not specified, the server attempts to connect as an unauthenticated user. Not all servers allow anonymous read-only access.

This user does not need to be an admin user with modify privileges.

managerPassword

(optional) If the managerDn property is set, this password is used to authenticate the manager user.

providerName

This human readable name is displayed in the user interface to identify users and groups that come from this provider.

userBase

This string is prepended to the basedn to construct the directory DN that contains user records.

userNameAttribute

The attribute in a user record that contains the user’s account name.

userSearchFilter

This LDAP query is performed in the context of the user directory to search for a user by account name. The string “{0}” is replaced with the user’s login ID. Typically, the query compares a user record attribute with the substituted user login ID.

userSearchSubtree

This property, if true, searches the entire subtree as identified by context. If false, (the default) then only the level identified by the context is searched.

url

The LDAP server URL is in the form protocol://<host>:<port>/basedn. Protocol is either ldap or ldaps (for secure LDAP). The port is implied by the protocol, but can be overridden if it is not at the default location (389 for ldap, 636 for ldaps). The basedn is the path to the top level directory that contains users and groups at this site. This is typically the domain name where each part is listed with a dc= and separated by commas.

Spaces in the basedn must be URL encoded (%20).

verifyCerts

(optional) This property enables certificate verification for LDAPS connections if true.

In addition to user information, the LDAP server can be queried for group information. This query is optional because the local group mechanism can refer to LDAP users as well as local users. However, the following elements can be used to tell the server how to map groups in LDAP:

Property Description

groupBase

(optional) This string is prepended to the basedn to construct the directory DN that contains group records.

groupMemberAttributes

(optional) A comma separated attribute names list that identifies a group member. Most LDAP configurations only specify a single value, but if there is a mixture of POSIX and LDAP style groups in the directory, multiple attributes might be required.

groupMemberFilter

(optional) This LDAP query is performed in the groups directory context to identify groups that contain a specific user as a member. There are two common forms of group record in LDAP directories: POSIX style groups where members are identified by account name, and groupOfNames or uniqueGroupOfNames records where members are identified by the full user DN. Both forms are supported, so the query is passed two parameters: “{0}” is replaced with the full user record DN, and “{1}” is replaced with the user’s account name.

groupNameAttribute

(optional) The group record attribute that contains the name of the group.

groupSearchFilter

(optional) This LDAP query is performed in the context of the groups directory to enumerate group records.

Determining LDAP Mapping

A typical POSIX user record in LDAP looks similar to the example below. To set up a mapping for this record, it is necessary to identify various record components.

First, identify the path in the directory that contains user records. In this example, the build user has a distinguished name (dn) of uid=build,ou=People,dc=mycompany,dc=com. This name uniquely identifies the build user account and this path splits into three parts:

  • base dn: dc=mycompany,dc=com

  • user base: ou=People

  • user element: uid=build

The baseDn is the parent of the directory that contains users. This value is combined with the protocol and server to form the URL. In this case, the URL ends up as ldaps://dir/dc=mycompany,dc=com. The userBase is the portion of the path that identifies the directory containing all user account records. This value is used directly as the userBase configuration element. The remaining portion identifies the user without the People directory: uid=build. The user name is replaced in this value with the string “{0}” to form the userSearchFilter: uid={0}. This query allows the server to search for a user’s account name by looking for a record with a matching uid attribute. The final mapping step is to identify user record attributes that hold the account name, full user name, and (optionally) the user’s email address. In this example, the account name is uid (identified earlier), the full user name attribute is gecos, and there is no email attribute.

At this point, the server is able to authenticate a user, look up a user by name, and determine the user’s full name. For many installations this is sufficient.

Sample LDAP User Record

#build, People, electric-cloud.com
dn: uid=jdoe, ou=People, dc=mycompany,dc=com
loginShell: /bin/bash
uidNumber: 508
gidNumber: 508
objectClass: account
objectClass: posixAccount
objectClass: top
objectClass: shadowAccount
uid: jdoe
gecos: John Doe
cn: John
homeDirectory: /net/filer/homes/build

Also, you can configure the server to look for LDAP groups that refer to user accounts. A typical group record is shown below. Like a user account, an LDAP group has a distinguished name with a baseDn, a group base, and a group element. In this case, the base dn is still dc=mycompany,dc=com. The groupBase configuration element is ou=Group, and the group name is cn=build_users.

The server must identify records in the directory that correspond to groups—it does this by applying the groupMemberFilter to the records in the groupBase directory. In this case, group records are members of the posixAccount object class, so the filter can be set to objectClass=posixGroup. To display a group by its name, the server must know which attribute represents the group name. In this case, set the groupNameAttribute to cn.

Finally, the server needs a filter to determine which accounts belong to the group and the attribute name that represents a single group member. Group membership can be identified in one of two ways. Either the members are listed by account name, or by their LDAP distinguished name. In this case, POSIX group membership is determined by account name, so set the groupMemberAttributes property to memberUid, and set the groupMemberFilter to memberUid={1}.

Sample LDAP Group Record

#build_users, Group, mycompany.com
dn: cn=build_users,ou=Group,dc=mycompany,dc=com
objectClass: posixGroup
objectClass: top
gidNumber: 100
memberUid: jdoe
memberUid: mary
cn: build_users

Sample Active Directory Configuration

The following XML element defines parameters needed to connect to an Active Directory server and the query to use for looking up user information.

<bean id="adDirectoryProvider"                                                         class="com.electriccloud.security.ldap.ActiveDirectory    Provider"> <property name="providerName" value="ActiveDirectory"/>
     <property name="url" value="ldap://server/dc=company,dc=com"/>
     <property name="managerDn"value="cn=myuser,cn=Users,dc=company,dc=com"/>
     <property name="managerPassword" value="mypw"/>
      <property name="userBase" value="cn=Users"/>
      <property name="userSearchFilter" value="(sAMAccountName={0})"/>
     <property name="userSearchSubtree" value="false"/>
     <property name="userNameAttribute" value="sAMAccountName"/>
      <property name="fullUserNameAttribute" value="name"/>
      <property name="emailAttribute" value="userPrincipalName"/><!-- <property name="groupBase" value=""/> --> <!-- <property name="groupMemberFilter" value="member={0}"/> --><!-- <property name="groupMemberAttributes" value="member"/> --> <!-- <property name="groupSearchFilter"value="(objectClass=group)"/> --> <!-- <property name="groupNameAttribute" value="cn"/> -->
     <property name="pageSize" value="500"/>
</bean>

Setting Up Email Notification

To configure the Cluster Manager to send email notifications through SMTP, define your SMTP connection properties. SMTP connection properties are contained in accelerator.properties. The following properties must be defined:

Property Description

ACCELERATOR_MAIL_HOST

The name of the SMTP mail server.

ACCELERATOR_MAIL_PORT

The mail server port. Typically, this is ‘25’ for SMTP or ‘465’ for Secure SMTP.

ACCELERATOR_MAIL_PROTOCOL

The mail server protocol. This can be ‘smtp’ for SMTP or ‘smtps’ for Secure SMTP.

If your mail server requires an authenticated user to send mail, you must also set the following properties:

Property Description

ACCELERATOR_MAIL_USERNAME

The user name required for authentication.

ACCELERATOR_MAIL_PASSWORD

The password to use for authentication.

For example:

ACCELERATOR_MAIL_HOST=smtp.electric-cloud.com
ACCELERATOR_MAIL_PORT=25
ACCELERATOR_MAIL_PROTOCOL=smtp
ACCELERATOR_MAIL_USERNAME=cm
ACCELERATOR_MAIL_PASSWORD=mypass

This example sets up the Cluster Manager to send mail as the 'cm' user through the smtp.electric-cloud.com server listening for SMTP connections on port 25.

After making changes to the mail configuration, you must restart the Cluster Manager service. For more information, see Stopping, Starting, or Restarting the Cluster Manager Service .

Configuring the Mail Policy

On the Administration > Server Settings page, you can configure various aspects of the global email notification policy. Cluster Manager sends mail notifications when messages are added to the message log. The following settings control how and when mail is sent:

Setting Description

Email Interval

The number of minutes between email notifications.

Email Item Limit

The maximum number of messages that will be sent in a single email at the end of each interval. If more messages than the limit arrive, they are ignored.

Email From

The name you use in the ‘From’ line in the email header.

Email Prefix

A string prepended to every subject line of each outgoing email. This string can be used to assist with mail filtering.

User Email Preferences

Each user that logs in to the Cluster Manager web interface can configure which mail notifications to receive. By default, a user receives no email notifications.

For users to configure their own mail notifications (for messages and build completions), they must have Modify permission defined in the User field on the Permissions page. The administrator can edit a user’s permission on the Administration > Permissions page. By default, the User field is set to None.

To receive notifications about messages in the message log:

  1. Go to the Messages > Message Policies page.

  2. Select the Watch Messages checkbox to enable message notifications. Watch Level controls the minimum severity level of messages that generate a notification.

To receive notifications when builds complete, go to the Builds > Build Classes page. For each build class in the list, select the checkbox in the Notify column to control whether the current user is notified when a build of that class completes. Users can selectively enable notifications for a set of build classes that interest them.

Adding Custom Protocol Mismatch Error Text

You can insert custom error text that is displayed when there is a protocol mismatch.

  1. Go to the accelerator.properties file.

  2. Add your custom text to the `ACCELERATOR_CLIENT_MISMATCH_DETAIL ` property.

  3. Restart the Cluster Manager service.

Using the Database Connection Monitor

You can configure the Cluster Manager to monitor the connection to the database. The following properties in accelerator.properties control the monitor’s behavior:

  • ACCELERATOR_DB_WATCHDOG_FAILURE_THRESHOLD=3

By default, if the database connection fails three times in a row, the server is restarted. You can change the threshold to a number that meets your needs. Changing the threshold to 0 turns off database connection monitoring.

  • ACCELERATOR_DB_WATCHDOG_INTERVAL=20000

By default, the monitor check the database connection every 20000 milliseconds (20 seconds). You can change the threshold to an interval that meets your needs.