Configuring CodeBeamer

See also:

• CodeBeamer知識基礎/CodeBeamer免費版本
• CodeBeamer知識基礎/如何安裝

第一次登入

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) 

Login with User/Password: bond/007

設定選項

Container (Tomcat)設定檔 vs 應用軟體(CodeBeamer)設定檔

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

使用者帳號的註冊法

Click on the System Admin link and click Miscellaneous . See "Miscellaneous Options"

最大的 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.

SSL Certificate

CodeBeamer ships with a default self-signed SSL-Certificate from Intland. The SSL-Port incl. Certificate is configured in the ~/tomcat/conf/server.xml file in the section:

<!-- Define a SSL HTTP/1.1 Connector on port 8443 -->
<Connector port="8443"
           ...
           keystoreFile="webapps/cb/config/keystore"
           keystorePass="..."
           ...
/>

To configure an own SSL-Certificate, change the attributes keystoreFile and keystorePass, to point to the keystore with your certificate.

資料庫連結(Database Host, Username, Password 和 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 Derby database, but the configuration files also contain templates for connections to Permission denied [MySQL] and Oracle, that can be uncommented and modified accordingly. (If you need help configuring CodeBeamer with Oracle, please contact us.)

Cryptography System Key

See CodeBeamer知識基礎/CodeBeamer免費版本

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 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 the Notification E-mail
• Importing Data from Bugzilla

安裝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 Permission denied [scmloop.zip].

SCMLoop系統需求

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.

設定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.

在Sandbox執行Ant Builds

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 Permission denied [here].

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 ant-build.zip from the CodeBeamer 4.2 download area 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.

設定與MySQL的連結

Using CodeBeamer with MySQL

See Permission denied [NOTE:6540].

MySQL資料庫備份

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

運用外部檔案系統(an External File System Location)來儲存文件

You configure CodeBeamer to 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

與LDAP和Active Directory整合

LDAP Access

See CodeBeamer知識基礎/CodeBeamer免費版本

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"

    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"

將LDAP Groups對應到CodeBeamemer Groups 與 Roles

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

First, you have to implement your own LDAP mapping class (e.g. mydomain.mypackage.myLDAP) that extends codeBeamer's com.intland.codebeamer.security.realm.JndiRealm and overwrite the method accountSynchronizationHook to populate codeBeamer's roles and/or groups from LDAP.

Additionally, you may wish to overwrite method getAccount in case you would like to change codeBeamer's implementation of population codeBeamer's account data from LDAP.

protected void accountSynchronizationHook(UserDto user, boolean justCreated) {
	List portalRoles = Acl.getUserGroupRoles(user, GroupDto.ACCOUNT_GROUP);
	Acl.removeUserRole(user, portalRoles);

	Collection availablePortalRoles = Acl.getGroupRoles(GroupDto.ACCOUNT_GROUP);

	List newPortalRoles = ...

	Acl.setUserRole(user, newPortalRoles);
}

Next you have to edit applicationContext.xml and change in the definition for the

<bean id="cbrealm" class="com.intland.codebeamer.security.realm.JndiRealm" ...>

the attribute class to contain the fully qualified name of your custom class

<bean id="cbrealm" class="mydomain.mypackage.myLDAP" ...>