Prerequisites

Linux prerequisites

The client executable uses GTK+ on linux, so you might need to install this, for example on CentOS 5 or RHEL 5:

yum install gtk+

(If you see an error with libgmodule.so missing while trying to run the client, then the version of gtk+ that we need is not installed on your system)

Important Information for Windows Vista Users

If you're running Windows Vista, there are two steps which you need to carry out before CB2SVN functions correctly.

  1. If using the installer, make sure that it's run as an Administrator (Right click on the installer and select 'Run as Administrator')
  2. After installing CB2SVN, you will need to run the Server and Client as an Administrator. There are a couple of ways to achieve this:
    • Right Click on the executable and select 'Run as Administrator' (You will have to repeat this every time you load the executable)
    • Right Click on the executable and select 'Properties'. Click on the 'Compatibility' tab and at the bottom, tick 'Run this program as an administrator' (This will mean every time the executable is run, it will be run as an Administrator)

Supported Platforms

Current platform support is as follows:

The CB2SVN clients, CB2SVN Servers and CB2SVN hooks have executables that are supported on the following platforms:

Platform

Introduced in CB2SVN Version

CentOS 5.3

v1.0

If you don't see the platform that you require above, please contact us at sales@clearvision-cm.com.

Platform-independent "Portable Hooks"

CB2SVN provides a special version of the Subversion hooks, which is independent of the operating system. This allows you to run Subversion on virtually any platform.

We recommend that you only use this if your platform is not supported by the executables as the installation is more involved.

To use the Portable Hooks, you must download the version that matches your version of Python. There are also a number of 'pre-requisite packages that must be installed.

These packages may already be installed on your system, but if they are not, please note that the software required is Open Source and can be downloaded and compiled from source as required. Note that on Linux, Sun and Mac, binary packages for your OS distribution may also be available.

Prerequisite Packages:-

Note that the version numbers indicated above are the versions of the tools CB2SVN has been tested with. CB2SVN may well work with other versions of the tools, but this cannot be guaranteed. Please make sure that the product works in your environment before purchase. An evaluation licence can be made available for that purpose.

Please refer to the appendix for guides on installing pre-requisite software for specific platforms.

Configuration planning

You will need to choose a machine to run the CB2SVN Server, and choose a port number for CB2SVN to use (eg, we recommend 54326). Note that the client machines will require access to this port on the Server (and this may require firewall configuration). As per the IANA recommendations, we recommend that you use one of the Dynamic and/or Private Ports from 49152 through 65535.

CB2SVN is designed with maximum flexibility in mind to cater for various network infrastructure requirements. Therefore, the physical location of all the components is flexible. In particular, the location of the CB2SVN Server is flexible to help mange network traffic and data latencies. It may be installed on your Subversion server machine; your CodeBeamer server machine; or on its own machine as shown below.

Fully Distributed System

In a fully distributed system, CB2SVN server, CB2SVN clients, Subversion and CodeBeamer live on different machines.

Fully Distributed System

Shared CB2SVN/CodeBeamer Configuration

In some environments, it makes sense to locate the CB2SVN server on the CodeBeamer machine itself.

Shared CB2SVN/CodeBeamer Server

Shared CB2SVN/Subversion Configuration

In other organisations, it might make sense to locate the CB2SVN Server on the Subversion server.

Share CB2SVN/Subversion Server

Alternative Configurations

Multiple Subversion servers with a single CodeBeamer Server

CB2SVN can support multiple subversion servers either using separate or shared CodeBeamer databases. So, for example, to use one common CodeBeamer database with two Subversion repositories, simply set up one CB2SVN Server for each Subversion repository, each pointing to the shared CodeBeamer Server. On each user machine, run two CB2SVN clients, each with its own CB2SVN.cfg file (pointing to its respective CB2SVN Server). This way, whenever a commit is made to either repository, the CodeBeamer record is requested from the user.

License

You must have obtained a license (from sales@clearvision-cm.com ). Note that this license will only let you run CB2SVN on a particular server machine, on a particular port, and will allow a maximum number of users. The license is time-limited.

To request a license you can download the get_license_info executable and run it on the machine you want to use as the CB2SVN server. The get_license_info tool can be found within the tools directory of the zip package. This will retrieve system information from the machine and present you with a license request to return to Clearvision at the below address. Alternatively, you can fill in the details below and send them to sales@clearvision-cm.com :

License Request for Clearvision CB2SVN:
     Evaluation: yes/no
     IP Address: 192.168.64.1
           Port: 54326
    MAC Address: 00-50-56-C0-00-05
          Users: 50
        Company: You Company name here
  Email Address: yourco@yourco.com
    Expiry Date: 2008-03-31
        Product: CB2SVN

The get_license_info executable is run from a command prompt, eg on Windows:

get_license_info.png

Cut and paste the highlighted section; check all the fields and fill in the empty ones (Company Name, etc) and send to sales@clearvision-cm.com .


CodeBeamer Setup

CB2SVN ties into the existing CodeBeamer functionality for issue tracking and associating tracker items with Subversion commits.

The only setup required in CodeBeamer is the creation of a report to be used by CB2SVN to extract a list of tracker items for a user.

Create a CodeBeamer Report

Create a report to get the list of issues that a typical CB2SVN user would be interested in. For example, all open tracker items for the 'Current User'.

Take a note of the report id, which is a number like '1010'. If you browse to the report in CodeBeamer, you can see the report id at the end of the URL in your web browser, e.g. https://cb.mycompany.com:8443/cb/proj/report/execute.do?doc_id=1019 indicates a report id of '1019'.

Note that you will need the report id later on when configuring the CB2SVN server.

---

CB2SVN Installation

CB2SVN has three separate parts: a Client, a Server and a set of files which must be installed in your Subversion repository's hooks directory. There is also a tool to get license information from your CB2SVN Server in the tools directory.

Start by unpacking the zip file into the C:\Program Files location on all of the machines that you will be installing on (any location can be used, however all the configuration files and instructions below use C:\Program Files as an example). The following directory structure will be created:

/!\ NOTE Please take care when editing any configuration files. We recommend the use of professional text editors such as Vim. Wordpad should also work, but don't use Notepad or MS Word.

CB2SVN Server

On your CB2SVN Server machine:

[CB]
report_id=1010
cb_server=http://cb.mycompany.com:8080

[License]
company_name=Your Company Plc
licence_email=admin@yourcompany.com
expiry_date=2009-12-31
users=999
license_key=PLEASE_ADD_YOUR_LICENCE_key_HERE
license_certificate=PLEASE_ADD_YOUR_LICENCE_certificate_HERE

[Server]
server_ip=192.168.1.2
server_port=54326

cd c:\Program Files\Clearvision\cb2svn\server
cb2svn_server.exe

Configuring the Server to run on startup

On Windows, we recommend that you add the CB2SVN Server as a 'Scheduled Task', 'When my computer starts'. An alternative would be to add an item in the autoexec.nt file so that the server is started on boot and is available for all users. Alternatively, you may want to start the Server manually, eg whenever subversion is started.

There is a -f command argument that you can use to choose a particular config file like this:

cb2svn_server.exe -f c:\my_cb2svn_server.cfg

You may also want to refer to the tools/run_server.sh sample script for Unix platforms.

CB2SVN Client

[Server]
server_ip=192.168.1.2
server_port=54326

Configuring User Ids for each CB2SVN Client

CB2SVN uses two user ids: your CodeBeamer user name and your Subversion user name.

On each client machine, you must configure the CodeBeamer user id and password and optionally a subversion user id. By default, CB2SVN uses the current login name as its id for Subversion. If you want to use an alternative id, configure this on the client's machine with the svn_uid option in cb2svn_client.cfg as follows:

[CB]
cb_uid=joe_bloggs
cb_password=my_secret_password

[Options]
svn_uid=jbloggs

Note: The default server configuration disables the ability to use svn_uid on the clients. If you want to enable this functionality, please see the Customization section later.

Note that if you prefer not to set a password in the config file (e.g. for security reasons), you can comment out the cb_password configuration variable (by adding a semi-colon at the start of the line as below), and you will then be prompted in a window to enter your password when the client starts.

[CB]
cb_uid=joe_bloggs
;cb_password=my_secret_password

Configuring the Client to run automatically

You will probably want to have the CB2SVN Client running whenever a user is logged on to his/her machine so that CB2SVN is available whenever they check in to Subversion.

On Windows

Logon

We recommend that you add a shortcut to the CB2SVN Client as an item in the StartMenu/Programs/Startup folder for each CB2SVN User. This setup ensures that whenever a user logs on to Windows, they automatically register with CB2SVN. You may want different configurations for each user, or you may be able to share one configuration (eg if there are no clients that require custom user ids and all users use the same repository). There is a -f command argument that you can use to choose a particular config file like this (remember to add this to your shortcut):

cb2svn_client.exe -f c:\Program Files\Clearvision\cb2svn\client\cb2svn_client.cfg

Depending on your setup, an alternative may be to add the startup as a 'logon script' in the Profile tab of the Computer Management/Users settings.

Another alternative is to use a Windows 'Scheduled Task' and run the client 'When I Log On'.

Logoff

You may be able to assign a logoff script as documented here and write a simple batch script (using the DOS taskkill command) to kill the process on shutdown, for example:

taskkill /f /t /im cb2svn_client.exe

On Linux

You can run the CB2SVN Client by adding a line to your login script (eg ~/.bash_login), and you may want to copy the configuration file to your home directory ~/.cb2svn.cfg, and use your personalized settings like this:

/opt/Clearvision/CB2SVN/client/cb2svn_client -f ~/.cb2svn_client.cfg

You may also want to refer to the tools/run_client.sh sample script for Unix platforms.

Setting permissions on Linux

On Linux, you will have to set permissions appropriately. Log files are written to the current working directory (i.e. wherever you run the process from), so this directory will require write-access. All of the executables, i.e. the client, server and all of the hook files will require execute permission. As an example, we've provided the tools/post_install.sh script which will need to be customized, e.g.:

# This is an example post-installation script which you
# will need to customize according to your installation.
#
# Run this before copying the hook files to your Subversion repository.
# Also please make sure that the files and directories are readable.
CB2SVN_HOME="/opt"  # change this appropriately
chmod +x $CB2SVN_HOME/Clearvision/cb2svn/client/cb2svn_client
chmod +x $CB2SVN_HOME/Clearvision/cb2svn/server/cb2svn_server
chmod +x $CB2SVN_HOME/Clearvision/cb2svn/subversion_hooks/*

# if you run the client and server in-place, you will need
# to make the directories writable for the log files:
chmod +w $CB2SVN_HOME/Clearvision/cb2svn/client
chmod +w $CB2SVN_HOME/Clearvision/cb2svn/server

Subversion Hook Setup

A couple of hooks need to be installed into each Subversion repository's hooks directory. The hooks and related programs are delivered in the C:\Program Files\Clearvision\cb2svn\subversion_hooks directory. These need to be installed in your hooks directory, and will require a small amount of customization for your local setup. If you have local (non CB2SVN) Subversion hooks to run (such as CodeBeamer's SCM Loop hooks), you may integrate these with CB2SVN.

Please note that CB2SVN hooks must appear before the CodeBeamer SCM Loop hooks. Also, please make sure that pre-commit hooks act on return values from CB2SVN hooks. If a CB2SVN hook returns a non-zero code, hook scripts should terminate. On Unix this can be achieved as follows:-

#/bin/sh
cd $1/hooks
./cb2svn-pre-commit $1 $2
retval=$?
if [ $retval -ne 0 ]
then
   exit $retval
fi
exec "/opt/CodeBeamer/CB-5.3.1/repository/scmloop/scmloop" -mode svn_pre_commit "$@"

On Windows, you can achieve the same result as follows:-

@ECHO OFF
%1\hooks\cb2svn-pre-commit.exe %1 %2
set ERRVAL=%ERRORLEVEL%
IF NOT %ERRVAL%==0 exit %ERRVAL%
"C:/CB-53~1.1/repository/scmloop/scmloop.bat" -mode svn_pre_commit ^
        %1 %2 %3 %4 %5 %6 %7 %8
exit %ERRORLEVEL%

On your Subversion Server machine:

[Server]
server_ip=192.168.1.2
server_port=54326

Portable Hooks

To use the portable hooks rather than executables, please replace pre-commit and post-commit with portable-pre-commit and portable-post-commit. Note that you must rename the portable-xxx files as otherwise they will be ignored by Subversion.

/!\ Also note that, unlike the executables, the portable version requires a set of software tools to be installed on your system. Please refer to the Prerequisites section at the top of this document for details.


Customization

CB2SVN can be customized according to your local requirements in a number of ways. This section describes all of the configuration options.

Configuration Options

There are a number of options to control the behaviour of CB2SVN. The default options are configured to enable an enforcement policy. Using the options below, you can allow a more permissive policy for your system.

The options are set in the configuration files in a section called [Options]. There are options for the server, for the hooks and for the clients. The server configuration options control site-wide behaviour of clients, such as allowing multiple records to be selected or allowing configuration of the subversion user id. The hook configuration options control commit behaviour for that repository such as permitting anonymous commits or allowing clients to not choose a change record for their changeset. The clients can set their user id for Subversion (if this is allowed by the server).

All of these options are detailed below.

CB Configuration

Tracker Item Selection

The set of tracker items displayed to a CB2SVN user are defined by the CodeBeamer report that you use. You can therefore freely customise this to select any tracker items that you like with any criteria. Note that the report is set for the CB2SVN Server, so is shared for all users. This means that if you restrict the report based on user settings, you will probably want to use the <CURRENT-USER> setting.

CB2SVN Server Configuration Options

Allow Multiple CodeBeamer Tracker Items per Changeset

The default configuration pops up a GUI which allows the user to select a single CodeBeamer tracker item to associate with the Subversion changeset. This policy can be changed site-wide by setting the allow_multiple_choices=1 option in cb2svn_server.cfg, for example:

[Options]
allow_multiple_choices=1

Allow Subversion User Id Configuration on Clients

Normally a client will use the operating system's user id as its Subversion user id. Depending on your local policy and setup, you may need to allow clients to tell CB2SVN that they have a different user id for Subversion.

To enable this configuration option on all clients, you can set the allow_client_svn_uid_configuration=1 option in the server configuration file.

[Options]
allow_client_svn_uid_configuration=1

Then, a client can configure their svn_uid option (see below).

Allow Tracker Items to be Moved to the Next State

The default configuration pops up a GUI which allows the User to select a tracker item to associate with the Subversion changeset. Sometimes it is useful to let a user also move that tracker item to its next state (for example saying that development is complete, and a fix is ready to be tested).

The allow_next_state option enables this functionality for all clients. Once enabled, the clients will be presented with an enhanced pop-up window that allows them to optionally progress the state of a record (please see the User Guide for an image of the GUI).

PLEASE NOTE: If you enable this feature, you must also specify a configuration that specifies which state to move to depending on the current state of a tracker item. This can be done through the cb_workflow_matrix option in the CB section.

The example below shows a workflow matrix suitable for the CodeBeamer life cycle. You can customise this workflow by adjusting the setting using the following format: cb_workflow_matrix=<current_state_name>:<next_state_name>[;<current_state_name>:<next_state_name>...].

To enable this feature, set the allow_next_state option to 1 in the [Options] section of cb2svn_server.cfg, and define the workflow matrix in the cb_workflow_matrix option in the [CB] section.

[Options]
allow_next_state=1

[CB]
; Format: cb_workflow_matrix==<current_state_name>:<next_state_name>[;
<current_state_name>:<next_state_name>...]
cb_workflow_matrix=New:Unconfirmed;Unconfirmed:Verified;Verified:Resol
ved;Resolved:Closed;Closed:Reopened;Reopened:Resolved

Show Extra Field Information in CB2SVN GUI

Sometimes the tracker item id and title are not enough to decide which tracker item to attach a change to. If this is the case, you can show more information in the CB2SVN GUI by adding extra fields and values to the information displayed in the GUI.

You can enable this feature using the show_extra_fields configuration option in the [CB] section of the server configuration. The format is as follows:-

; Format: show_extra_fields=<field_id>[,<field_id>, ...]
show_extra_fields=assignedTo,priority

The following field id's are currently supported.

CodeBeamer Field Name

Field ID

Status

status

Assigned To

assignedTo

Priority

priority

Category

categories

Severity

severities

Resolution

resolutions

Enabling CB2SVN Command Line Mode

If you prefer not to get pop-ups on commits, you can use CB2SVN to verify tracker item id's provided by the user in the Subversion log message.

Without CB2SVN, CodeBeamer will check log messages for strings that look like tracker item id's and match these up against tracker items in the CodeBeamer database. Any strings that could be tracker items but cannot matched against tracker items in the database will be ignored.

With this option turned on, CB2SVN will verify tracker item id's in the log message against the database, and if not match is found, an error is displayed and the commit is aborted.

You can turn this option on by adding the allow_change_ids_in_svn_log=1 option to the [Options] section in your server config file (the default is off).

[Options]
allow_change_ids_in_svn_log=1

Issue id's need to be provided at the beginning of the log message with no preceding white spaces and followed by a space character. Multiple issue id's can be provided, separated by semicolons.

The following examples are log messages with tracker item id's in CB2SVN format.

#1017 Fixed problem

#1010;#1104 Fixed two problems

Note that if this option is enabled and you specify a log message that starts with a word that looks like a tracker item id then you can prevent CB2SVN from scanning the log message by starting your log message with a space (or any other character):-

 #1 Fixed
 #2 Also fixed

This fixes problem #1 and #2.

Both examples above work fine as CB2SVN will not consider #1 a CodeBeamer tracker item id as it does not appear at the beginning of the log message. Note that if you specify a CodeBeamer tracker item id at the beginning of the log message that is not part of the set of issues returned by the CodeBeamer report, CB2SVN will give an error.

Note that with the allow_change_ids_in_svn_log option it is possible to run CB2SVN without a client. However, since CB2SVN needs to be able to access the CodeBeamer server, you need to specify a default CodeBeamer user name and password in the server config file. The default_cb_uid and default_cb_password is only used if the user is not logged in through a client.

default_cb_uid=myuser
default_cb_password=mypassword

Please note that once these options are set, any CB2SVN user can make use of the default user name and password. If this is not desirable, then it may be preferable to require each user to log in to the CB2SVN server through a CB2SVN client even when using the command line mode. You can do this by not specifying the default_cb_* options in the config file.

Note, however, that if a user is logged in through a client, CB2SVN will pop-up the client GUI if the information provided in the Subversion log is not sufficient.

Configure Connection Timeout

When network problems occur, clients may not be able disconnect cleanly from the server, causing the server to believe that clients are still connected and wait for a response.

With the connection_timeout setting in the Options section, you can configure the time in seconds before the server considers a connection broken.

Setting the value too low can cause clients to be disconnected on slow systems. A value that is too large can cause commits too hang until the server recognises the broken client connection.

Note that connections are checked regularly and in most cases a reasonable large timeout such as 30 or 60 seconds should be suitable.

[Options]
connection_timeout=30

Hook Configuration Options

Allow Commit Without Change Id

A user who is logged in to the CB2SVN system normally must choose a tracker item to go with their changeset. If they cancel their choice, CB2SVN will abort the Subversion commit.

If you want to allow them to optionally not select any of their current tracker items and 'cancel' their choice in the GUI (ie allow commits without any change record), you can set this option.

/!\ WARNING: Enabling this will mean that some changes are NOT recorded in your change control system!

[Options]
allow_commit_without_change_id=0

Allow Anonymous Commits

Default behaviour is to check that a user has logged on to the CB2SVN Server, and to abort any commits from users who are not yet logged on (a policy-'enforcing' mode). You can disable this behaviour here (for example if some of your users do not use change records)

/!\ WARNING: this will mean that those users not running a Client will NOT be using this system to correlate Subversion with your change control system, and effectively bypassing CB2SVN altogether!

[Options]
allow_anonymous_commits=1

Allow Commit On Error

Normally, if an error occurs in the system, CB2SVN will try to abort the commit. If you want to let the commit proceed (for example as a temporary measure until you fix a system problem), you can set this option:

[Options]
allow_commit_on_error=0

Note that this is not guaranteed to work as it depends on the exact problem that is occurring, so please use with caution.

Client Configuration Options

Changing the Subversion User Id

If the server is configured to allow it, you can configure the subversion user id that a client uses with the svn_uid option in the cb2svn_client.cfg:

[Options]
svn_uid=jbloggs

Note: The default server configuration disables the ability to use svn_uid on the clients. If you want to enable this functionality, please see the allow_client_svn_uid_configuration option above.

Prompting for a password

You can now avoid including the password in the config file if you desire (e.g. for security reasons). Simply comment out the cb_password configuration variable (by adding a semi-colon at the start of the line as below), and you will then be prompted in a window to enter your password when the client starts.

[CB]
cb_uid=joe_bloggs
;cb_password=


Troubleshooting

To check that a CB2SVN client or server is running on Windows, open the Windows Task Manager. You should see 2 entries for the server (on a server machine) and 2 for the client (on a client machine). To kill the process, right click on the process in the Processes tab and select 'End Process Tree' (to kill both processes at once). If the process is not running, check your log file for any errors. On Linux, use ps -ef | grep cb2svn - these processes can be safely killed.

(!) To investigate setup problems, it can be helpful to increase the logging level from the default of 'Warning' to 'INFO' (see cb2svn.cfg)

/!\ Note that when an error occurs, the default behaviour is to abort the commit. Some possible reasons are:

  1. When your User Id is not recognized as a Subversion User Id (you may want to set svn_uid) in your client's config file to override the default user id

  2. When the user is not logged on to CB2SVN (check in Task Manager that cb2svn_client.exe is running and that is is using the expected uid)

  3. When there are no valid records assigned to the user (or there are no eligible tracker items - run the report in the CodeBeamer web interface with the userid and check the results.).

  4. If Subversion svnserve.conf file uses anon-access = write.

If you have a local repository and are using the file protocol via the command line client, your commits will not use your windows logon id, they will be anonymous. So, to work with CB2SVN you must use something like:

svn commit myfile.txt --username engineer

Note that you can use this command, but Subversion still works anonymously if you have asked it to (eg using svnserve with anon_access=write).

The config files use unix line-endings, so please be careful to use a well-behaved text editor such as Cream/Vim or Wordpad rather than Notepad or MS Word.

Installation Support

If you experience any issues during the installation please report your issues via the Clearvision Support Centre, which can be found at http://www.clearvision-cm.com/support-home/support-center.html.


Appendix A: RHEL4 Pre-requisites

Subversion 1.4.4

CB2SVN is built against Subversion 1.4.4. Pre-built RPM packages for Subversion and its dependencies are available from the following site. Note that this is not part of the Clearvision product, but is required for CB2SVN to run. The following site is referenced from the standard Subversion download page:

To install these rpms after downloading, run rpm -Uvh <rpmname> on each rpm file.

Appendix B: Portable Hooks Examples

Sun Solaris 10

This appendix gives guidance on installing prerequisite tools for portable hooks on a Solaris 10 system. Please note that the instructions below are for guidance only and your system may require different steps.

Set path to pick up GNU tools

export PATH=/usr/ccs/bin:/usr/sfw/bin:$PATH

Python

Python 2.4 is available on the Solaris CD, and other versions (including python 2.5) are available from Sunfreeware.com. These use the standard Sun pkgadd. We would recommend using python 2.5 if possible.

Twisted 8.2.0

/!\ This package has long file names, therefore it requires 'gtar' to be unpacked.

python setup.py install

Zope 3.3.1

Twisted requires the interfaces package in Zope. /!\ This package has long file names, therefore it requires 'gtar' to be unpacked.

./configure --with-python=/opt/python/bin/python  # use your python location here.
make
make install

PySVN 1.6.2

Note that PySVN requires GNU's version of make, "gmake".

The version of gcc that we used had a problem with finding the right linker. GCC has hard-coded search paths (for as, ld, etc.). Our version was missing the path to the GNU linker, but had the Sun linker, so failed with an invalid (GNU-specific parameter, ie --rpath). To work around this problem, we moved /use/css temporarily (see below)

cd Source
python setup.py configure
mv /usr/ccs /usr/ccs.BAK    # see above
gmake
cp -r pysvn /opt/python/lib/python2.5/site-packages/   # use your python location here.
mv /usr/ccs.BAK /usr/ccs


Copyright (c) 2009 Clearvision CM All Rights Reserved
Registered in England No. 5643578 VAT Registration No. UK881364801
Registered Address Laurel Farm, Winters Hill, Durley Southampton, SO32 2AH

http://www.clearvision-cm.com