Post-installation Configuration
After installing Codebeamer and starting the server, administrators configure essential system settings to ensure secure, stable, and efficient operation. Post-installation configuration includes setting up authentication, email services, document storage, and database connectivity, as well as adjusting system performance parameters such as JVM memory and monitoring options.
This topic describes the available configuration tasks and provides instructions for customizing Codebeamer to align with organizational requirements.
For more details on installing codebeamer and important files and directories, see Installing Codebeamer and Important Files and Directories
Signing In for the First Time
Once the Codebeamer server starts, you can access it from your browser and start configuring it. To access Codebeamer, start your web browser and enter the URL given below to access Codebeamer 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 then click Outgoing Email Connection.
User Account Registration Method
After logging in as System Administrator, click the System Admin link and then click Miscellaneous.
Maximum Document Upload Size
By default, the maximum document size that can be uploaded in Codebeamer is 5GB. To change this limit, edit <cb-installation-dir>/tomcat/webapps/cb/WEB-INF/classes/my-applicationContext.xml and add the configuration given 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 restarted.
Starting from release 9.4 you can change this by setting uploadFileSizeLimit setting in Application Configuration in interactive section:
"interactive": {
"uploadFileSizeLimit":1610612736
}
 |
The minimum configurable value is 1GB.
|
Database Connectivity (Database Host, Username, Password)
For production environments, you must use a PostgreSQL or an Oracle database.
Please refer Preparing Oracle Database for Installation topic to see how to configure Codebeamer:
JVM Version
The JVM of an existing CB installation can be configured for different JVM versions.
Linux, Unix, Solaris
If JRE/JDK is available in the system PATH, Codebeamer uses that version.
For 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.
Follow the steps given below if you are using Linux, Unix, Solaris:
1. Edit <cb-installation-dir>/bin/cb.
2. Search for the line maxjavaheapsize=2500.
3. Add the CB_MAXHEAPSIZE=<memory> line before it
1. Use the required memory size in megabytes. For example, CB_MAXHEAPSIZE=42000
4. Save the file and execute <cb-installation-dir>/bin/restart
Follow the below given steps while the windows is in service mode:
1. Stop Codebeamer service.
2. Edit <cb-installation-dir>/tomcat/bin/cbservice.bat
3. Locate --JvmMx and set it to a suitable value for your environment, for example --JvmMx 4096.
◦ You can add further JVM parameters under the REM Set extra parameters line, in the "%JMXPARAMS%<JVM parameters>" section. Each JVM parameter must be surrounded by semicolons (;).
4. Save and execute <cb-installation-dir>/tomcat/bin/cbservice Codebeamer Codebeamer
5. Start Codebeamer service.
|
|
If starting the service fails after the modification, the reason for failure can be viewed 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. 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.
Account Password policy when not using LDAP
When a user logs in to Codebeamer, the authentication follows 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 under Application Configuration.
For example: The passwords must be at least six characters 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])(?=.*[@#$%^&+=]).*$" >
 |
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 the Application Configuration can cause Codebeamer to fail at startup.
|
|
|
For more details on regular expressions, see https://docs.oracle.com/cd/E19683-01/817-0717/6mggffse0/index.html. 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 Access and Active Directory Integration
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.
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 the 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 time is ten seconds.
|
|
Read timeout
|
The number of milliseconds to wait for responses Default time is thirty seconds.
|
|
Referrals
|
Must be follow for Active-Directory, otherwise ignore.
|
Slow or non-responding LDAP servers can also slow down or stall Codebeamer when increasing or disabling the timeouts.
|
|
There is known problem with Active Directory Server 2003: If login via a Distinguished Name, for example, "cn=Manager,dc=intland,dc=com" fails, you should try the users domain name (sAMAccountName@domain): for example, "[email protected]". You must also set Referrals="follow".
|
To enable or disable the user authentication against the LDAP/Active Directory, select the appropriate option.
If disabled, only the internal Codebeamer accounts are used.
There are two methods to map a Codebeamer user by using the login name to the appropriate LDAP/Active Directory user entry.
Lookup user
If the distinguished name (DN) of the user's LDAP entry contains the username provided 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 which is 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.
You can 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.
|
You can additionally specify the following for all the authentications:
• Whether Codebeamer should also store the entered passwords into the internal account settings, or if passwords are only stored within LDAP/Active Directory.
• 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 for how long.
This can reduce the number of requests to the LDAP/Active Directory server, if 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 can yield identical results that too without asking the LDAP server.
If authentication via LDAP/Active Directory is enabled, Codebeamer will only authenticate a user against its Codebeamer account in the following cases:
• None of the LDAP/Active Directory servers was reachable or the lookup/search did not find an appropriate entry.
• The fallback option is enabled.
Users, that are found in LDAP/Active Directory but where the LDAP/Active Directory authentication failed, are always rejected independent 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, for example 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, for example
(&(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 [email protected].
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.
|
with
|
userPrincipalName={0}
|
|
in
|
Users need to enter their User Principal Name as a login, in the form [email protected].
User Attribute Synchronization
For all of the shown Codebeamer account attributes, you can enter the name of the appropriate LDAP/Active Directory attribute. For example, for Active Directory, the Account Name is stored in the attribute sAMAccountName.
If an attribute is not available in LDAP/Active Directory, 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, 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 is rejected, even if authentication via LDAP/Active Directory is successful.
• A new account is created, but it can be activated by an account administrator.
◦ If a user, that does not have a Codebeamer user account yet and tries to log into Codebeamer and the authentication via LDAP/Active Directory is successful:
▪ A new Codebeamer user account is created and populated with information from LDAP/Active Directory according to the configured user attribute mapping.
▪ But the new account is not activated yet. Therefore the login is rejected with the hint, that the user should wait for the account to be activated. And at the same time, all Codebeamer system administrators 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 receives a notification via email and can now login successfully.
• A new account is created and activated immediately.
◦ If a user does not have a Codebeamer user account yet and tries to log into Codebeamer and the authentication via LDAP/Active Directory is successful:
▪ A new Codebeamer user account is created and populated with information from LDAP/Active Directory according to the configured user attribute mapping.
▪ The new account is 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 important if you want to extend or override the default Codebeamer LDAP authentication process
An old way, of overriding a JndiRealm method no longer work with CB-5.5 as this class does not 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 on how to deploy and register you custom listener.
LDAP user synchronization
There is support to synchronize users in bulk from LDAP server.
Follow the steps given below to synchronize users from LDAP server:
1. Configure LDAP server.
2. Configure user synchronize block and enable it.
3. Configure user mapping. The test authentication will not work without configuring authentication section as well.
4. Click Save. The config is saved and user synchronization job is scheduled.
5. After saving the configuration, the Test sync button is available.
6. Click Test sync, this returns the user count on the LDAP server eligible for synchronization.
|
|
Synchronization runs 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
|
|
|
The synchronization of LDAP groups only for existing users is supported. For this, the existing users only checkbox displayed on the below image 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: Specifies the format used to interpret the LDAP "modifyTimestamp" attribute during synchronization operations.
• 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)
• recursively: When not selected, it searches using the ONELEVEL_SCOPE search method. When selected, it searches using the SUBTREE_SCOPE search method.
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, which is 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, that is:
svn://codebeamer-HOSTNAME/My_second_project
or
http://codebeamer-HOSTNAME/svn/My_second_project
For more information on configuring these URLs, see Working with Git Submodules.