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)
Configuration Options
Mail Server (SMTP)
After logging on as a System Administrator, click the System Admin link and click Outgoing Email Connection. Refer the Administrator's Guide
User Account Registration Method
After logging in as System Administrator, click the System Admin link and click Miscellaneous . Refer the 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>
<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
}
"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 Oracle should be used.
Please refer documents below how to configure Codebeamer:
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
a. 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
Monitoring
By default, Codebeamer has the following application configuration:
"monitor": {
"enableGlobalThreadDump" : true
}
"enableGlobalThreadDump" : true
}
"enableGlobalThreadDump" : true enables the creation of global thread dump files. To preserve the optimal performance and stability of Codebeamer, PTC recommends setting the value of this property to false. Set enableGlobalThreadDump to true only for troubleshooting purposes, or when advised by PTC Technical Support. For detailed information, refer to "monitor"
Additional Information.
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.
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.
System Administrator GUI for Project Document Storage Location Definition
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])(?=.*[@#$%^&+=]).*$" >
| | 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
In order to examine your directory and find out the appropriate settings, before trying to configure Codebeamer accordingly.
LDAP/Active Directory can be configured via > :
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 omit 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 then 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
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 notbe 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
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) {
}
}
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
Starting from 20.11 LTS 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 Save (Note that config is saved and user synchronization job is scheduled).
5. After saving the configuration, the Test sync button will be available.
6. Click Test sync, this returns the user count on the LDAP server eligible for synchronization.
| | Synchronization will run only once with all user, not in bulk 500s. New users are always created in active status, already existing user's status is untouched. New user's license can be configured by login.newAccountType configuration, for more information see Application Configuration |
| | Since Codebeamer 22.04 release, the synchronization of LDAP groups only for existing users is supported. For this, the existing users only checkbox displayed on the below screenshot needs to be selected before the synchronization process. |
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
}
"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 |