Configuring CodeBeamer

See also:

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

Signing In the First Time

When you have started CodeBeamer server you can access it from your browser and configure it. To access CodeBeamer, start your web browser, and enter the URL to access CodeBeamer's main site:

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

During the installation a default system administrator user called bond with the password 007 is added to the system. You can log on to CodeBeamer with this username / password at the first time.

Login with User/Password: bond/007

Configuration Options

Container (Tomcat) Configuration File Versus Application (CodeBeamer) Configuration File

You can modify manually the following files to configure Tomcat and CodeBeamer options, respectively:

For CB-4.x:

~CB-4.x/tomcat/conf/server.xml
~CB-4.x/tomcat/webapps/cb/config/general.xml

For CB-5.x:

~CB-5.x/tomcat/conf/server.xml
~CB-5.x/tomcat/webapps/cb/WEB-INF/classes/general.xml

Mail Server (SMTP)

Click on the System Admin link and click Mail. See E-mail Notification Server Setup

User Account Registration

Click on the

System Admin link and click Miscellaneous . See "Miscellaneous Options"

Maximum HTTP POST Size

Tomcat by default sets a limit on the maximum size of HTTP POST requests to 2 Mb. If you get the error message Post too large edit

<Connector> element in install_dir/tomcat/conf/server.xml and add an attribute maxPostSize and set a larger value (in bytes) to increase the limit. Setting it to 0 will disable the size check.

LDAP (Active Directory) Access

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

CodeBeamer allows to utilize an existing LDAP/Active Directory server, in addition to or instead of maintaining own user accounts. This authentication mechanism is based on the Apache Tomcat JNDI Realm, so you may also have a look at their documentation.

If you are uncertain about the structure of your LDAP/Active Directory, we suggest to use 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.

For CB-4.x, the LDAP configuration is specified as a <Resource> in the

~CB-4.x/tomcat/webapps/cb/META-INF/context.xml

file:

<Resource name="cbrealm/RealmFactory" auth="Container"
   ...
   jndi="true"
   ...
   fallback="true"
   ...
/>

For CB-5.x, the LDAP configuration is specified in the <LDAP> section of the

~CB-5.x/tomcat/webapps/cb/WEB-INF/classes/general.xml

file:

<LDAP
   LDAPAuthenticationEnabled="true"
   ...
   fallback="true"
   ...
/>

To enable LDAP, the attribute LDAPAuthenticationEnabled (in CB-4.x: jndi) must be set to "true". If LDAPAuthenticationEnabled="false", only the internal CodeBeamer accounts will be used.

The attribute fallback controls, whether authentication is done exclusivly via LDAP (fallback="false"), or if authentication should fall back to the default CodeBeamer account in case the LDAP authentication fails (fallback="true").

If LDAP is enabled (LDAPAuthenticationEnabled="true"), additional parameters have to be set:

The attribute connectionURL must contain the primary URL of the LDAP server. An alternative URL can be specified in the optional attribute alternateURL. The example below assumes that the LDAP server is on the host amd and the port is 389:

    connectionURL="ldap://amd:389"

If anonymous access to your LDAP directory is not allowed, you have to specify the distinguished name and password of the LDAP user, to be used for directory access, in the attributes connectionName and connectionPassword. For example:

    connectionName="cn=Manager,dc=intland,dc=com"
    connectionPassword="secret"

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".

The lookup of the user to be authenticated can be done in one of two ways: By pattern or by search.

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, the userPattern attribute may be used to specify the DN, with "{0}" marking where the username should be substituted.

    userPattern="uid={0},ou=people,dc=intland,dc=com"

You can also specify multiple patterns to try, each pattern enclosed in (). For example:

    userPattern="(uid={0},ou=people,dc=intland,dc=com)(cn={0},ou=partner,dc=intland,dc=com)"

If the lookup by distinguished name pattern is not applicable for you, you must perform a user search. For searching, you have to specify the DN of the root node in the LDAP directory, where the search should start (userBase), a search criteria that must uniquely identify the user (userSearch), and whether the whole subtree should be searched recursivly (userSubtree). For example:

    userBase="ou=people,dc=intland,dc=com"
    userSearch="uid={0}"
    userSubtree="true"

For Active Directory, the search criteria should be userSearch="sAMAccountName={0}"

If the user lookup was successful, the authentication process will now verify user identify via the entered password. Please refer to the Tomcat documentation for details. Set userPassword only if the user authentication cannot be done in bind mode (but in Comparison mode). In this case, set userPassword attribute to the name of a directory attribute in the user's entry that contains the password.

    userPassword="userPassword"

When a user logs onto CodeBeamer for the first time and the LDAP authentication was 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 onto CodeBeamer. The following LDAP attributes can be mapped (if they are available) onto CodeBeamer accounts: title, firstName, lastName, company, address, postalCode, city, state, country, timeZone, telephoneNumber, mobile, mail.

For example: The firstName of the user is stored in the LDAP attribute givenName, the lastName in sn and the mail address in mail :

    firstName="givenName"
    lastName="sn"
    mail="mail"

As a default, CodeBeamer stores the entered passwords also into the internal account settings. The example shown below can be used to disable it and in this case the passwords remain only on the LDAP server:

storePassword="false"

Database Connectivity (Database Host, Username, Password and Connection Pooling)

To work with a database on other hosts, the CodeBeamer server needs the following configuration. This description assumes that you understand how to configure database and database accesses.

For CB-4.x, the database configuration is defined as a <Resource> in the ~CB-4.x/tomcat/webapps/cb/META-INF/context.xml file:

<Resource name="jdbc/CodeBeamerDatasource" auth="Container"
	driverClassName="com.mysql.jdbc.Driver"
	url="jdbc:mysql://localhost:12751/codebeamer?autoReconnect=true"
	username="cbroot" password="cbpassword"
	type="javax.sql.DataSource" maxActive="20" maxIdle="10" maxWait="-1" />

For CB-5.x, the database configuration is defined in the <database> section of the ~CB-5.x/tomcat/webapps/cb/WEB-INF/classes/general.xml file:

<database
   JDBC_Driver="com.mysql.jdbc.Driver"
   JDBC_ConnectionURL="jdbc:mysql://localhost:3306/codebeamer?autoReconnect=true&zeroDateTimeBehavior=convertToNull&emulateLocators=true"
   JDBC_Username="cbroot"
   JDBC_Password="cbpassword"
/>

CodeBeamer comes preconfigured with a local You must login to see this link. Register now, if you have no user account yet. database, but the configuration files also contain templates for connections to You must login to see this link. Register now, if you have no user account yet. and You must login to see this link. Register now, if you have no user account yet., that can be uncommented and modified accordingly.

NOTE:CodeBeamer must be restarted after you have modified database connection parameters

Cryptography System Key

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

You can configure the global key for the cryptographic system in the general.xml file. There you should change the value for the default key:

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

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.

The line below in /install_dir/bin/cb[.bat] must be customized:

JREPATH="$CBPATH"/jre

You can just rename $CBPATH"/jre to old.jre and copy a newer jre into there.

JVM Heap Size

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

Linux / UNIX

1. Edit /install_dir/bin/cb
2. Search for the line -Xmx250M
3. Modify 250M to for example 400M
4. Save the file and execute /install_dir/bin/restart

Windows

1. Edit /install_dir/tomcat/bin/cbservice.bat
2. Search for -JvmMx 250M
3. Modify 250M to for example 400M
4. Save and execute /install_dir/tomcat/bin/cbservice CodeBeamer
5. Restart CodeBeamer

See next

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

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 part of 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.4 or higher environment on the machine.

Configuring Ant Builds

By default, Ant builds started via the CodeBeamer Build management, execute in a separate Java Virtual Machine (JVM) with the same permissions than the CodeBeamer server.

Additionally, although each Ant build script belongs to a specific project, code within the script is not restricted to this project, but can access everything (programs and files) on the host system, that is accessible by CodeBeamer (including the CodeBeamer installation itself).

In a corporate environment, where the CodeBeamer installation is only accessible within the corporate network, and users are authenticated against a central corporate user directory, this should not be a problem. But on open installations that are publicly available on the Internet, and allow anybody to join and create new projects, Ant builds can impose a severe security risk, because members of one project can indirectly access data from other projects via a malicious Ant script, and even worse, the host machine file system, bypassing any CodeBeamer authentication mechanism.

Running Ant Builds in a Sandbox

The suggested method to secure Ant builds, is to run Ant in a Java sandbox, similar to Applets.

For this purpose, a special Java security policy file ant-build.policy and ant-build[.bat], a wrapper around the original ant script, are provided in the ~CB/ant/bin directory or can be downloaded from You must login to see this link. Register now, if you have no user account yet..

The ant-build[.bat] script sets up the sandbox security manager for Ant:

ANT_OPTS = -Djava.security.manager -Djava.security.policy=ant-build.policy

and then propagates the call to the ant script.

The Ant build sandbox imposes the following restrictions:

• Only source code and libraries within the source directory of the CodeBeamer project from where the build was started, are accessible.
• Executing operating system commands via <exec> is restricted. This indirectly means that the <… fork=”true”> flag of some tasks may not work.
• Opening network connections to remote hosts is not allowed.

Securing Ant in Existing CodeBeamer 4.2.x Installations

To upgrade existing CodeBeamer installations, to use secure Ant builds, download You must login to see this link. Register now, if you have no user account yet. from the CodeBeamer 4.2 download You must login to see this link. Register now, if you have no user account yet. and unpack to the ~CB/ant/bin directory of the CodeBeamer installation to upgrade.

Because CodeBeamer 4.2.x invokes Ant builds via ~CB/ant/bin/ant[.bat], the following additional modifications are necessary:

1. Go to the ~CB/ant/bin directory
2. Rename ant[.bat] to ant-launch[.bat]
3. Copy ant-build[.bat] to ant[.bat] (On Unix: Set executable flag if necessary)
4. Edit ant[.bat] (the copied ant-build[.bat]), go to the end and modify the call to ant script from ant to ant-launch

Securing Ant in CodeBeamer 5.x

In CodeBeamer 5.x, all Ant builds are by default run in a Java sandbox defined in ~CB-5.x/ant/bin/ant-build.policy, without intermediate ant-build[.bat] script.

Backups

MySQL Database Backups

For the database backup CodeBeamer and the database server must be stopped. Please check whether any java/javaw and mysqld processes are stopped, else you might loose data.

You can dump the database with the command:

mysqldump --protocol=tcp -P 12751 -u cbroot -pcbpassword codebeamer

You can use the following command to backup the database without source code, SCM and attachment data:

mysqldump --protocol=tcp -P 12751 -u cbroot -pcbpassword \
--ignore-table=codebeamer.xref \
--ignore-table=codebeamer.symbols \
--ignore-table=codebeamer.scm_change_set \
--ignore-table=codebeamer.scm_change_file \
--ignore-table=codebeamer.scm_change_set_task \
--ignore-table=codebeamer.files \
--ignore-table=codebeamer.dirs \
--ignore-table=codebeamer.task_attachment \
codebeamer | gzip > db.dump.gz

Using an External File System Location to Store Documents

You configure codeBeamer to use use remote file system, or network storage system for document storage purposes to manage large number of documents and for higher security purposes.

UNC (virtual directory service in Windows). The mount point to the external system should be configured in the

general.xml

file, by the

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

parameter. You must ensure that the “codebeamer” user/group (the user who starts codebeamer) has

1. r/w permission,
2. can create files on the external file system, and that the

external file system is accessible before Codebeamer is started.