You are not logged in. Click here to log in.

codeBeamer ALM

Search In Project

Search inClear

Post-installation Configuration


See also:

Signing In the First Time

Once the codeBeamer server is started, you can access it from your browser and start configuring it. To access codeBeamer, start your web browser and enter this URL to access codeBeamer's main site:

http://hostname:8080 (use your hostname and the port you configured)

During codeBeamer's installation, a default system administrator user called bond with the password 007 is added to the system. You can log in to codeBeamer with this username / password the first time.

Login with User/Password: bond/007
We strongly recommend that you change this user account immediately for security purposes. After logging in the first time, click on Account Info then Edit Account to edit the username and password.

Configuration Options

Mail Server (SMTP)

After logging on as a System Administrator, click on the System Admin link and click Outgoing Email Connection. See Administrator's Guide

User Account Registration Method

After logging in as System Administrator, click on the System Admin link and click Miscellaneous . See Administrator's Guide

Maximum Document Upload Size

By default, the maximum document size that can be uploaded in codeBeamer is 5GB (starting with version codeBeamer 7.7.2). To change this limit (to for example 2GB), edit <cb-installation-dir>/tomcat/webapps/cb/WEB-INF/classes/my-applicationContext.xml and add the block below:

<bean id="uploadLimit" class="java.lang.Long">
    	<constructor-arg value="5368709120"></constructor-arg> <!-- 5 gigabytes -->
    	<!-- constructor-arg value="1048576"/ --> <!-- 1 megabyte -->
    	<!-- constructor-arg value="102400"/ --> <!-- 100 kilobytes -->
</bean>

After editing the file codeBeamer must be re-started.

Database Connectivity (Database Host, Username, Password)

codeBeamer is shipped and pre-configured to use Derby database that should be used only for evaluation purposes. For production either MySql or Oracle should be used.

Please refer documents below how to configure codeBeamer:

Cryptography System Key

You can configure the global key for the cryptographic system in <cb-installation-dir>/tomcat/webapps/cb/WEB-INF/classes/general.xml. There you should change the value for the default key:

<cryptography key="C1-9B-F8-79-EA-45-63-F1"></cryptography>

The key must be used securely, so please make sure that you have the access rights properly configured for the general.xml file.

JVM Version

The JVM of an existing CB installation can be configured for different JVM versions.

Linux, Unix, Solaris, MAC-OS

If codeBeamer finds JRE/JDK 1.6.x or higher in PATH that will be used, otherwise the version shipped with codeBeamer.

Windows

  1. Edit <cb-installation-dir>/tomcat/bin/cbservice.bat and change the line below:
    SET JRE=%CBPATH%\jre

  2. Save and execute <cb-installation-dir>/tomcat/bin/cbservice CodeBeamer CodeBeamer

JVM Memory Heap Size & MaxPermSize

For performance tuning or if you get (Java OutOfMemoryError) exceptions you can configure the JVM heap size.

Linux, Unix, Solaris, MAC-OS

  1. Edit <cb-installation-dir>/bin/cb
  2. Search for the line maxjavaheapsize=2500
  3. Modify 2500 to for example 4000
  4. Search for the line -XX:MaxPermSize=512M
  5. Modify 512M to for example 1024M
  6. Save the file and execute <cb-installation-dir>/bin/restart

Windows (Service mode)

  1. Stop CodeBeamer service
  2. Edit <cb-installation-dir>/tomcat/bin/cbservice.bat
  3. Search for --JvmMx 2500
  4. Modify 2500 to for example 4000
  5. Search for the line -XX:MaxPermSize=512M
  6. Modify 512M to for example 1024M
  7. You can add further JVM parameters in the last quoted section in this line (after MaxPermSize definition) separated by semicolon (;)
  8. Save and execute <cb-installation-dir>/tomcat/bin/cbservice CodeBeamer CodeBeamer
  9. Start CodeBeamer service

Please note:

  • If starting the service fails after the modification, you see the reason in the following files:
    • <cb-installation-dir>/tomcat/logs/commons-daemon-*current-date*.log
    • <cb-installation-dir>/tomcat/logs/stderr.log

Installing SCMLoop

The installation takes place on the SCM server machine. This takes typically a few minutes. Please follow the instructions given in the installation manual ScmLoop.pdf, which is part of <cb-installation-dir>/tomcat/webapps/cb/scmloop.zip.

SCMLoop System Requirements

SCMLoop works on Linux, Unix and Windows operating systems. On the SCM server site, a script installation is required, the script requires Java run time 1.6 or higher environment on the machine.

MySQL Database Backups

Dump the complete codeBeamer database (including stored procedures) with the command:

mysqldump --routines --protocol=tcp -u cbroot -pcbpassword --single-transaction codebeamer

External Network Storage for Documents

This feature is discontinued starting with version 7.5!

Different network systems can be used for different projects. CodeBeamer can be configured to store documents using either remote file systems or network storage systems. These configurations allow codeBeamer to manage a large number of documents or provide high security, depending on the project's needs.

The mount point to the external system should be configured in <cb-installation-dir>/tomcat/webapps/cb/WEB-INF/classes/general.xml, in the line:

<document display-plain-text-as-html="false" storage-path="" relocatable="false"></document>

using the storage-path and relocatable parameters.

The codeBeamer server must have r/w permissions on the file system and the external file system must be accessible before CodeBeamer server is started.

If storage-path is not empty it must contain a directory name where all codeBeamer documents should be stored instead of the default:

<cb-installation-dir>/repository/docs

If relocatable is set to true the system administrator can specify via GUI for any project where the codeBeamer documents of the project should be stored.

Figure: System Administrator GUI for Project Document Storage Location Definition

Figure: System Administrator GUI for Resetting the Mount Point

Account Password policy when not using LDAP

When a user logs in to codeBeamer, the authentication will follow with user account and password. To install a special policy to assure the security quality of entered passwords, assign a regular expression to the attribute 'passwordPolicy' of the <login> section in CB_HOME/tomcat/webapps/cb/WEB-INF/classes/general.xml file.

For example: To require passwords to be at least 6 chars long and to contain at least one lower case letter, one upper case letter, one digit and one special character @#$%^&+=

<login ...   passwordPolicy="^.*(?=.{6,})(?=.*\d)(?=.*[a-z])(?=.*[A-Z])(?=.*[@#$%^&amp;+=]).*$" >

Please note that the regular expression code specified in passwordPolicy is an XML attribute value, therefore certain characters have to be escaped according to XML standards (as in our example the ampersand character "&" is substituted with "&"). This is important because a syntactical error in general.xml configuration file can cause codeBeamer to fail at startup. See more on regular expressions on https://docs.oracle.com/cd/E19683-01/817-0717/6mggffse0/index.html, and a tutorial and overview of regular expressions in Mastering Regular Expressions, Jeffrey E. F. Friedl, O'Reilly and Associates, 1997, ISBN: 1-56592-257-3.

LDAP and Active Directory Integration

LDAP Access

codeBeamer allows you to authenticate users against an existing LDAP/Active Directory server, in addition to or instead of maintaining your own user accounts.

If you are uncertain about the structure of your LDAP/Active Directory, try using a free LDAP Browser like

to examine your directory and find out the appropriate settings, before trying to configure codeBeamer accordingly.

LDAP/Active Directory can be configured via System Admin -> User Authentication:

Server URLs You must specify at least one (primary) LDAP server URL (with ldap or ldaps protocol).
If more than one URL is specified, these are alternative servers in descending precedence.
Base domain If all codeBeamer users are stored in a single sub-domain of the directory, you can specify that domain here, so that it will be automatically added to all (relative) names you specify as Lookup or Search criteria.
Username The full distinguished name of an LDAP user to login
Password The password to authenticate the user.
Anonymous? If anonymous access is allowed, you can check this option and ommit the Username and Password
Connect timeout The timeout for establishing connections to the LDAP server (default 10s)
Read timeout The number of milliseconds to wait for responses (default 30s).
Referrals Must be "follow" for Active-Directory, otherwise "ignore"


Take care when increasing or disabling these timeouts, otherwise slow or non-responding LDAP servers can also slow down or stall codeBeamer!

There is known problem with Active Directory Server 2003:
If login via a Distinguished Name (e.g. "cn=Manager,dc=intland,dc=com") fails, you should try the users domain name (sAMAccountName@domain): e.g. "Manager@intland.com".
You must also set Referrals="follow".



To enable/disable the user authentication against the LDAP/Active Directory, check/uncheck the appropriate option.
If disabled, only the internal codeBeamer accounts will be used.

There are two methods to map a codeBeamer user (by login name) to the appropriate LDAP/AD user entry.

Lookup user

If the distinguished name (DN) of the user's LDAP entry contains the username presented for authentication, and is otherwise the same for all users, it is best to lookup users by DN, where as is the distinguished name (DN) pattern (relative to Base domain), with "{0}" marking where the username should be substituted.

You can also specify multiple patterns to try, each pattern enclosed in ().
For example: (uid={0},ou=people,dc=intland,dc=com)(cn={0},ou=partner,dc=intland,dc=com)

Search user

If looking up users by distinguished name pattern is not applicable for you, you must perform a user search:

with Is the search criteria that must uniquely identify the user, with "{0}" marking where the username should be substituted.
For Active Directory, the search criteria should be: sAMAccountName={0}
in Is the distinguished name (DN) of the root node (relative to Base domain), where the search should start.

In CB-9.1 and newer, you can also specify multiple repository branches/domains to search in: (domain1)(domain2) ... (domainX)
  • Each domain is the distinguished name of the domain/branch root element, relative to the Base domain, and must be enclosed in ().
  • You should specify domains in descending order of search hit probability.
recursively Whether to only search the root node, or to search recursively in the whole subtree


For all authentications, you can additionally specify

  • whether codeBeamer should also store the entered passwords into the internal account settings,
    or if passwords are only stored within LDAP/AD.
  • whether authentication is done exclusively via LDAP
    or if authentication should fall back to the default codeBeamer account in case connecting to LDAP/Active Directory fails, or the user lookup/search does not return a result.
  • whether codeBeamer should remember successful and failed authentications (and how long).
    This can reduce the number of requests to the LDAP/AD server, should the number of requests or the duration of server roundtrips become an issue.
    Subsequent logins for the same user and password within the caching period will then yield identical results (without asking the LDAP server).


If authentication via LDAP/Active Directory is enabled, codeBeamer will only authenticate a user against its codeBeamer account, if

  • none of the LDAP/Active Directory servers was reachable or the lookup/search did not find an appropriate entry
  • and the fallback option is enabled.

Users, that were found in LDAP/Active Directory but where the LDAP/Active Directory authentication failed, are always rejected (independend of the fallback setting)!


If not all users contained in the search scope should be allowed to log into codeBeamer, you can define a special group, e.g. ("codeBeamer") in Active Directory, and only make the users that should be allowed to log in to codeBeamer members of that group.

You should then extend the default Search with: sAMAccountName={0} to also check group membership, e.g.

(&(sAMAccountName={0})(objectCategory=person)(objectClass=user)(memberOf=<distinguished name of group>))

Active Directory Forests

An Active Directory installation may support multiple domains at the same time. To distinguish users between domains, an identifier called a User Principle Name (UPN) can be added to a user's entry in the directory. This UPN usually takes the form of the user's account name, followed by the domain components of the particular domain, for example somebody@nz.example.com.

To make this practical, Active Directory supports the concept of a Global Catalog. This Global Catalog is a read only copy of selected attributes of all the Active Directory servers within the Active Directory forest. Querying the Global Catalog allows all the domains to be queried in a single query, without the query spanning servers over potentially slow links.

If enabled, the Global Catalog is an independent directory server that runs on port 3268 (3269 for SSL). To search for a user, do a subtree search for the attribute userPrincipalName, with an empty search root, like so:

with userPrincipalName={0}
in


Users will need to enter their User Principal Name as a login, in the form somebody@nz.example.com.

User Attribute Synchronization


When a user logs into CodeBeamer for the first time and the LDAP authentication is successful, a CodeBeamer account will be created automatically and LDAP attributes (for example e-mail address, name, phone number etc.) will be stored (mapped) into the CodeBeamer account database.

These attributes will be synchronized with the LDAP server after each successful login into CodeBeamer.

For all of the shown Codebeamer account attributes, you can enter the name of the appropriate LDAP/AD attribute.
For example: For Active Directory, the Account Name is stored in the attribute "sAMAccountName"

If an attribute is not available in LDAP/AD, leave the appropriate field empty.

Testing server connection, authentication and user attribute mapping

To test all your settings, you can enter a username and password and test it.
The mapped attributes of the authenticated user will be shown behind the appropriate mapping.

Matching LDAP Groups to codeBeamemer Groups and Roles

This section is only important if you want to extend/override the default CodeBeamer LDAP authentication process!

The old way, of overriding a JndiRealm method does not longer work with CB-5.5 (because this class doesn't exist any more).

Instead, you have to implement and register an AccountSynchronizationHook listener.

import com.intland.codebeamer.ldap.LdapDao;
import com.intland.codebeamer.persistence.dto.UserDto;
import com.intland.codebeamer.event.BaseEvent;
import com.intland.codebeamer.event.AccountSynchronizationHook;

public class MyAccountSynchronizationListener implements AccountSynchronizationHook {
   /**
    * This method gets called when a new user account is created from LDAP.
    * The {@link BaseEvent#getSource()} is the newly created account
    * The {@link BaseEvent#getSecondarySource()} is the {@link LdapDao}
    */
   public void accountCreated(BaseEvent<UserDto,LdapDao,Void> event) {
      UserDto user = event.getSource();
      LdapDao dao = event.getSecondarySource();

      ...
   }

   /**
    * This method gets called when a user account is synchronized from LDAP.
    * The {@link BaseEvent#getSource()} is the newly synchronized account
    * The {@link BaseEvent#getSecondarySource()} is the {@link LdapDao}
    */
   public void accountSynchronized(BaseEvent<UserDto,LdapDao,Void> event) {
   }
}


You must compile this class and put the output under ~/CB-.../tomcat/webapps/cb/WEB-INF/classes.

See You must login to see this link. Register now, if you have no user account yet. how to deploy and register you custom listener.

Set Managed Repository Access URLs

When you use SVN, Git or Mercurial repositories, codeBeamer shows their access URL under the SCM tab. The codeBeamer system administrator can configure different access methods and URLs to these repositories depending on each SCM installation, i.e.

svn://CODEBEAMER-HOSTNAME/My_second_project

or

http://CODEBEAMER-HOSTNAME/svn/My_second_project

For more information on configuring these URLs, see Administrator's Guide