Post-installation Configuration

See also:

• Installing codebeamer
• Important Files and Directories

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)

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.

Starting from release 9.4 it can be changed by setting "uploadFileSizeLimit" setting in Application Configuration in "interactive" section:
( from release 10.0 the minimum configurable value is 1GB)

"interactive": {
 "uploadFileSizeLimit":1610612736
}

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:

• Preparing MySQL Database for Installation
• Preparing Oracle Database for Installation

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

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. Add the CB_MAXHEAPSIZE=<memory>line before it
   1. Please use the required memory size in megabytes. e.g CB_MAXHEAPSIZE=42000
4. 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. You can add further JVM parameters in the last quoted section in this line (after MaxPermSize definition) separated by semicolon (;)
6. Save and execute <cb-installation-dir>/tomcat/bin/cbservice CodeBeamer CodeBeamer
7. 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

You must login to see this link. Register now, if you have no user account yet.

Figure: System Administrator GUI for Resetting the Mount Point

You must login to see this link. Register now, if you have no user account yet.

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])(?=.*[@#$%^&+=]).*$" >

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

• the Softerra LDAP Browser or
• the Active Directory Explorer

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 :

You must login to see this link. Register now, if you have no user account yet.

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.

You must login to see this link. Register now, if you have no user account yet.

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:

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:

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

User Attribute Synchronization

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.

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

User Registration

In codeBeamer 10.1 and newer, there is a new Registration setting, that defines, whether LDAP/Active Directory users, that match the Lookup/Search criteria (see above), can log into codeBeamer, even if they do not have a codeBeamer user account yet:

• Only account administrators can create new accounts, so no account will be created.
  • If a user, that does not have a codeBeamer user account yet, tries to log into codeBeamer, the login will be rejected, even if authentication via LDAP/Active Directory should be successful
• A new account will be created, but it will have to be activated by an account administrator.
  • If a user, that does not have a codeBeamer user account yet, tries to log into codeBeamer and the authentication via LDAP/Active Directory is successful:
    • A new codeBeamer user account will be created and populated with information from LDAP/Active Directory according to the configured user attribute mapping
    • But the new account will not be activated yet.
      • Therefore the login will be rejected with the hint, that the user should wait for her/his account to be activated.
      • At the same time, all codeBeamer system administrators will receive an email, with the request to validate and either activate or disable the new user account.
        • This allows the administrators to choose the appropriate user license and groups
      • If the account gets finally activated, the user will receive a notification via email and can now login successfully.
• A new account will be created and activated immediately.
  • If a user, that does not have a codeBeamer user account yet, tries to log into codeBeamer and the authentication via LDAP/Active Directory is successful:
    • A new codeBeamer user account will be created and populated with information from LDAP/Active Directory according to the configured user attribute mapping
    • The new account will be activated immediately and the user login will succeed.

In codeBeamer 10.0 and older, there is no Registration setting:

• If a user, that does not have a codeBeamer user account yet, tries to log into codeBeamer and the authentication via LDAP/Active Directory is successful
  • A new codeBeamer user account will be created and populated with information from LDAP/Active Directory according to the configured user attribute mapping
  • The new account will be activated immediately and the user login will succeed.

Testing server connection, authentication and user attribute mapping

You must login to see this link. Register now, if you have no user account yet.

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 Listener API how to deploy and register you custom listener.

LDAP user synchronization

Since CB 20.11-LTS (Carmen)

Starting from Carmen release there is support to synchronize users in bulk from LDAP server.

To synchronize users from LDAP server the following steps is needed:

1. Configure LDAP server.
2. Configure user synchronize block and enable it.
3. Configure user mapping (note that test authentication will not work without configuring authentication section as well).
4. Click on Save (It should note that config is saved and user synchronization job is scheduled).
5. After saving the configuration, the Test button will be available.
6. Click on Test sync, this will return the user count on the LDAP server eligible for synchronization.

Note: synchronization will run only once with all user, not in bulk 500s.

Note: new users are always created in active status, already existing user's status is untouched.

Note: new user's license can be configured by login.newAccountType configuration, see: Application Configuration

If the existing users only box is checked, only those LDAP users are synchronized that exist in codebeamer as well, therefore, no new users are created.

The following fields are added:

• Interval: job running interval, can be defined with expression like: 2D, 5H, 10H 35S, the supported time units are D, H, M, S
• Page size: page size for a single LDAP query, fetched users are processed after every single fetch
• Modify timestamp format: ISO 8601 (see) description of the LDAP server modify timestamp format in the search result
• Search with: expression to filter search result, wildcard is supported, like: givenName=* or uid=*
• Search in: search base or bases for user search, multiple values are supported by using parentheses, like: (ou=employee,ou=people)(ou=shareholders,ou=people)
• Recursive: search scope one (not selected) or sub (selected)

To store user sync configuration in AppConfig a new section is added to LDAP, example:

"sync" : {
    "syncEnabled" : true,
    "syncInterval" : "1D",
    "syncLdapModifyTimestampFormat" : "yyyyMMddHHmmssX",
    "syncPageSize" : 500,
    "syncUserBase" : "ou=people",
    "syncUserSearch" : "uid=*",
    "syncUserSubtree" : true
}

Also added Modify timestamp to user mapping. Default is modifyTimestamp, unlikely to change.

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