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>
isC:\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:
-
Change the
ACCELERATOR_AGENTS_STARTUP_ENABLED
property tofalse
. This change affects agents installed after this point; existing agents on the Agents tab are not affected. -
If you want the property to change the behavior of existing agents, you must restart the Cluster Manager service.
For more information, see Stopping, Starting, or Restarting 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
-
Go to the following directory on the Cluster Manager server:
<ECloud install>/<arch>/conf
-
Make a copy of the
ldap_template.xml
file if you intend to use LDAP, or thead_template.xml
file if you prefer to use Active Directory. Save the copy in theconf
directory as any name you choose or use the name:securityContext.xml
. -
Still working in
conf
, open theaccelerator.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)
-
-
Use the LDAP information and examples in the following sections to fill in your own copy of the LDAP template.
-
Restart the Cluster Manager service.
For more information, see Stopping, Starting, or Restarting the Cluster Manager Service .
-
After the Cluster Manager is running, log in to the Cluster Manager UI as “admin”.
-
Go to Administration > Permissions .
-
Click Enable User or Enable Group.
-
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.
-
Select the appropriate users or groups to enable using the corresponding checkbox(es).
-
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 | ||
---|---|---|---|
|
(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. |
||
|
(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. |
||
|
(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.
|
||
|
(optional) If the managerDn property is set, this password is used to authenticate the manager user. |
||
|
This human readable name is displayed in the user interface to identify users and groups that come from this provider. |
||
|
This string is prepended to the |
||
|
The attribute in a user record that contains the user’s account name. |
||
|
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. |
||
|
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. |
||
|
The LDAP server URL is in the form
|
||
|
(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 |
---|---|
|
(optional) This string is prepended to the |
|
(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. |
|
(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 |
|
(optional) The group record attribute that contains the name of the group. |
|
(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 |
---|---|
|
The name of the SMTP mail server. |
|
The mail server port. Typically, this is ‘25’ for SMTP or ‘465’ for Secure SMTP. |
|
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 |
---|---|
|
The user name required for authentication. |
|
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:
-
Go to the Messages > Message Policies page.
-
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.
-
Go to the
accelerator.properties
file. -
Add your custom text to the `ACCELERATOR_CLIENT_MISMATCH_DETAIL ` property.
-
Restart the Cluster Manager service.
For more information, see Stopping, Starting, or Restarting 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.