CollabNet TeamForge 5

CollabNet TeamForge 5.2Site Administrator Guide

2009CollabNet Inc.

Contents

Legal fine print......................................................................................................................7CollabNet, Inc. Trademark and Logos.....................................................................................................7

Chapter 1: Manage users................................................................................9Create a new user account......................................................................................................................10

Create a user group.................................................................................................................................10

Add a user to a user group......................................................................................................................11

Find a user..............................................................................................................................................11

Edit a user account.................................................................................................................................11

Acting on multiple user accounts...........................................................................................................12

Reset the admin account password.........................................................................................................12

Chapter 2: Support projects.........................................................................13Create a new project...............................................................................................................................14

Approve a new project............................................................................................................................14

Rename a project....................................................................................................................................14

Delete a project.......................................................................................................................................15

Update a project template.......................................................................................................................15

Manage project categories......................................................................................................................15

Add a project category...............................................................................................................15

Edit a project category................................................................................................................16

Move a project category.............................................................................................................16

Delete a project category............................................................................................................16

Disabling project categorization.................................................................................................16

Chapter 3: Provide source control services.................................................19Integrate a source code server................................................................................................................20

Approve a source control repository request..........................................................................................21

Approve an unmanaged CVS server access request...............................................................................21

Edit SCM integration details..................................................................................................................21

Integrate an unmanaged CVS repository with CollabNet TeamForge 5.2 ............................................22

Create a loginfo trigger file........................................................................................................22

Create a modified verifymsg trigger file....................................................................................23

Chapter 4: Change your site's look and feel................................................27Customize anything on your site............................................................................................................28

Customize the home page of your site...................................................................................................29

Change a project's home page................................................................................................................29

Change your site's outgoing emails........................................................................................................30

CollabNet TeamForge 5.2 | TOC | 3

Chapter 5: Provide external applications....................................................31Create a site-wide linked application.....................................................................................................32

Edit a site-wide linked application.........................................................................................................32

Chapter 6: Require documents to be associated with artifacts.................33

Chapter 7: Check your server's status.........................................................35

Chapter 8: Keep your site secure..................................................................37Setting password requirements...............................................................................................................38

Preventing cross-site scripting (XSS).....................................................................................................38

Chapter 9: Support hardware provisioning................................................39Set up a new TeamForge Lab Management project...............................................................................40

Move hosts from one project to another.................................................................................................40

Forward a port........................................................................................................................................40

Stop port forwarding..............................................................................................................................41

Set up host URL mapping......................................................................................................................41

Stop URL mapping.................................................................................................................................42

Delete a project.......................................................................................................................................43

Undelete a project...................................................................................................................................43

Expand your domain with virtual guests................................................................................................43

Create a virtual guest..................................................................................................................43

Migrate a virtual guest................................................................................................................43

Delete a virtual guest..................................................................................................................44

Add and remove profiles........................................................................................................................44

Add a new profile.......................................................................................................................44

Stop using a profile....................................................................................................................45

Enable a profile..........................................................................................................................45

Appendix A: Frequently asked questions about site administration........47How do TeamForge licenses work?........................................................................................................48

What's the difference between a "managed" and "unmanaged" CVS server?.......................................48

Does CollabNet TeamForge 5.2 support merge tracking?.....................................................................49

What is a user group?.............................................................................................................................49

What elements of a site can I customize?..............................................................................................49

Images........................................................................................................................................49

Stylesheets..................................................................................................................................49

Velocity templates......................................................................................................................50

Arbitrary HTML.........................................................................................................................51

Email notifications.....................................................................................................................52

Scripts.........................................................................................................................................53

4 | CollabNet TeamForge 5.2 | TOC

What is the look project?............................................................................................................53

Frequently asked questions about providing TeamForge Lab Management services............................53

Frequently asked questions about providing TeamForge Lab Management services................53

Appendix B: Reference information.............................................................59Install reference......................................................................................................................................60

Minimum hardware requirements for CollabNet TeamForge 5.2 .............................................60

Supported software for CollabNet TeamForge 5.2 ....................................................................60

RPM packages installed with CollabNet TeamForge 5.2 ..........................................................61

CollabNet TeamForge 5.2 install scripts....................................................................................63

Scripts.....................................................................................................................................................64

apache_watchdog.......................................................................................................................64

bb-check-apache.sh....................................................................................................................64

bb-check-jboss.sh.......................................................................................................................64

bb-check-pgsql.sh.......................................................................................................................65

bb-check-tomcat.sh....................................................................................................................65

bootstrap-data.sh........................................................................................................................65

The collabnet script....................................................................................................................66

environment_check.sh................................................................................................................67

generate-site-options.sh..............................................................................................................67

install.sh......................................................................................................................................68

instance-set-install.sh.................................................................................................................69

jboss_watchdog..........................................................................................................................69

pgsql_watchdog..........................................................................................................................70

rotatelogs.pl................................................................................................................................70

snapshot.py.................................................................................................................................71

tomcat_watchdog........................................................................................................................72

upgrade-site.sh............................................................................................................................72

Log files..................................................................................................................................................73

JBoss logs...................................................................................................................................73

Oracle logging............................................................................................................................74

SCM (CVS, Subversion, and Perforce) logs..............................................................................74

Email logs...................................................................................................................................74

Search logs.................................................................................................................................75

Configuration files..................................................................................................................................75

The patch manifest file...............................................................................................................75

login-config.xml.........................................................................................................................76

httpd.conf....................................................................................................................................77

iptables.......................................................................................................................................78

The instance set manifest file.....................................................................................................78

Sample instance manifest file.....................................................................................................79

Reference information about TeamForge Lab Management .................................................................79

Reference information about TeamForge Lab Management .....................................................79

CollabNet TeamForge 5.2 | TOC | 5

6 | CollabNet TeamForge 5.2 | TOC

Legal fine print

Copyright © 2007 CollabNet, Inc. All rights reserved.

CollabNet is a trademark or registered trademark of CollabNet, Inc., in the U.S. and other countries. All other trademarks, brandnames, or product names belong to their respective holders.

CollabNet makes no representation with respect to accuracy or completeness of document, and specifically disclaims any impliedwarranties for any purpose and shall in no event be liable for any loss of profit or any other commercial damage, including but notlimited to special, incidental, consequential, or other damages.

Please submit comments and questions at www.collab.net.

CollabNet, Inc.Trademark and LogosThese trademarks are trademarks or registered trademarks of CollabNet, Inc. or its licensors in the United States and other countries.

• CollabNet• OpenCollabNet• CollabNet TeamForge• CollabNet SourceForge Enterprise• SourceForge Enterprise Edition• Powered by CollabNet™

• collabXchange™

This list will be updated from time to time to reflect additional trademarks and changes in registration status. If you have questionsor would like further information regarding CollabNet's trademarks, please contact the CollabNet, Inc., Legal Department [email protected].

Subversion is a registered trademark of the Subversion Corporation.

All other trademarks, logos, brand names, or product names belong to their respective holders.

Chapter

1Manage users

Topics:

• Create a new user account• Create a user group• Add a user to a user group• Find a user• Edit a user account• Acting on multiple user accounts• Reset the admin account

password

Create a new user accountTo participate in a CollabNet TeamForge 5.2 site, a person must have a user account on that site. CollabNet TeamForge 5.2administrators can create these user accounts.

Note: If your CollabNet TeamForge 5.2 installation authenticates against an LDAP directory, CollabNet TeamForge 5.2administrators cannot create new user accounts. On a site with LDAP authentication, each user must log into CollabNet TeamForge5.2 using his or her LDAP user name and password.

1. Click Admin in the CollabNet TeamForge 5.2 navigation bar.

2. On the site administration navigation bar, click Users.

3. Click Create.

4. On the Create New Account page, enter a user name for the user.

Note: Your user name must meet these criteria:

• 1 to 31 characters.• Only alphanumeric characters.• No spaces.• At least one letter.• The first character is a letter.

5. Enter and confirm a password for the user.

6. Enter the user's full name and email address.

Note: Unlike with user self-registration, the email address is not validated before creating the account.

7. Choose a user type.

• CollabNet TeamForge 5.2 administrator - Administrators have unlimited access to all data in CollabNet TeamForge 5.2.• Restricted user - Restricted users can only access projects of which they are members.

You can choose only one user type for each user.

Note: If you do not select Restricted user, the user will be unrestricted. Unrestricted users can access all projects that havenot been made private by a project administrator.

8. To send a welcome message to the user, select Send Welcome Message.

9. Click Create.

The user account is created.

Create a user groupTo manage multiple users at once, create a group that represents them.

1. Click Admin in the CollabNet TeamForge 5.2 tool bar.

2. On the Site Administration page, click Groups.

3. Click Create and provide a name for the group and a description of its purpose.

4. Click Create.

10 | CollabNet TeamForge 5.2 | Manage users

Add a user to a user groupPut together multiple users who share characteristics in a user group.

1. Click Admin in the CollabNet TeamForge 5.2 tool bar.

2. On the Site Administration page, click Groups.

3. Under Groups, click the group to which you want to add the user.

4. On the Edit Group page, clickAdd.

5. Use the picker to move users into the group, and click OK.

6. Click Return.

Find a userTo find a user, filter the list all CollabNet TeamForge 5.2 users on your site.



3. On the Users page, click Show to reveal the filter field at the top of each column.

4. Filter the user list using one or more filter menus.

Note: Search text is case-insensitive.

5. Click Apply.

All users meeting your filter criteria are displayed.

Edit a user accountWhen a user has trouble accessing the site, you may need to reset the user's password or change the user's account status.

Note: If your CollabNet TeamForge 5.2 installation authenticates against an LDAP directory, CollabNet TeamForge 5.2administrators cannot reset user passwords. Passwords must be reset in the LDAP system.

Important: In the case of the CollabNet TeamForge 5.2 admin account, you cannot make any of these edits:

• Delete the account.

• Change the account status to anything but active.

• Remove the CollabNet TeamForge 5.2 admin flag.

• Mark it as a restricted user.



3. On the All Users list, click the name of the user whose account you want to edit.

4. On the User Details page, click Edit.

5. On the Edit User Information page, make your changes and click Update.

CollabNet TeamForge 5.2 | Manage users | 11

Acting on multiple user accountsA CollabNet TeamForge 5.2 administrator can edit the status of multiple user accounts simultaneously.

For example, if you have multiple pending new accounts to approve, you can approve them in a batch instead of individually editingeach account.

Note: A pending user is a user who has requested an account but has not yet confirmed his or her email addresses.

Important: In the case of CollabNet TeamForge 5.2 admin accounts, you cannot make any of these edits:

• Delete the account.

• Change the account status to anything but active.

• Remove the CollabNet TeamForge 5.2 admin flag.

• Mark it as a restricted user.



3. On the Users page, select the users whose status you want to edit.

4. Click the desired status change.

• Delete - Deleted users are removed from all projects. All assigned items are removed from the user. Deleted users do notcount against your CollabNet TeamForge 5.2 license count.

• Deactivate - Deactivated users cannot log in to CollabNet TeamForge 5.2 and do not receive notification messages, but theyremain members of projects and selection lists.

• Activate - Active users have full use of CollabNet TeamForge 5.2, subject to RBAC permissions.

Reset the admin account passwordIf your CollabNet TeamForge 5.2 installation authenticates against an LDAP directory, follow these instructions to reset your adminaccount password.

If your installation does not validate against LDAP, click Forgot Your Password on the CollabNet TeamForge 5.2 home page toreset the password for the admin account.

1. With a web browser, go to the URL http://<host>sf/sfmain/do/forgotAdminPassword.

2. On the Admin Account Password Retrieval page, Click Send Email.CollabNet TeamForge 5.2 sends an email to the address specified for the admin user.

3. Check your email and click the link provided to reset your password.

4. On the Reset Password page, enter and confirm a new password.

5. Click Reset Password.

You can now log into CollabNet TeamForge 5.2 with your new password.

12 | CollabNet TeamForge 5.2 | Manage users

Chapter

2Support projects

Topics:

• Create a new project• Approve a new project• Rename a project• Delete a project• Update a project template• Manage project categories

Create a new projectCollabNet TeamForge 5.2 administrators can create new projects without having to submit them for approval.

Note: When a CollabNet TeamForge 5.2 administrator creates a new project, he or she is not made a member of the project,and the Founder Project Admin role is not created. To designate a project administrator, you must add the user to the project,then create and assign a project administrator role manually.


2. On the site administration navigation bar, click Projects.

3. In the list of CollabNet TeamForge 5.2 projects, click Create.

4. On the Create Project page, provide a name for the project.This is the name that will appear in all project lists and on the project home page.

5. Enter a URL name for the project, if appropriate.This is the name that will appear in the project's URL.

6. Write a description of the project.

7. Select a project template.

A project template is used to pre-populate new projects with the structure and configuration of an existing project. If you do notwant to use a project template, choose None.

8. Click Create.

The project is created.

Approve a new projectAny registered CollabNet TeamForge 5.2 user can request a new project. A new project is activated only after a site administratorapproves it.

Before approving a new project, you have the option to review the project details.



3. Click the Pending Projects tab.

4. On the Pending Projects page, select the projects you want to approve.

• Click Approve to approve the project and move it to the All Projects page with status Active.• Click Reject to reject the project and remove it from the list.

The project requester receives an email notification when the project is approved or rejected. If you entered a comment, that alsoappears in the email notification.

Rename a projectAs the focus of a project shifts, its name or description can become obsolete. A site administrator can update the name or descriptionto help keep the project current.


2. Click Projects.

3. In the CollabNet TeamForge 5.2 project list, click the project you want to edit.

4. On the project home page, click Project Admin.

14 | CollabNet TeamForge 5.2 | Support projects

5. On the Project Settings page, make the changes you need.

6. Click Save.

Delete a projectIf you no longer need a project or any of the data in it, you should delete it.

Deleting a project deletes all of the data within it, with the exception of SCM data, which is maintained on the SCM server.

Caution: Delete a project only if you are sure that you no longer need any of the data within it. Move any items that you wantto save.



3. From the CollabNet TeamForge 5.2 project list, choose the project that you want to delete and click Delete.

The project is deleted.

Update a project templateTo revise or correct an existing project template, overwrite it with a template of the same name.

You must be a site administrator to overwrite an existing project template.

1. Revise the project that will serve as the basis for the new project template.

2. Click Project Admin in the project navigation bar.

3. On the Project Settings page, click Create Project Template.

4. On the Create Template page, select Replace Existing Template and choose the template you want to are overwrite.

5. Change the name and description for the template if necessary.

Tip: It's a good idea to use the description to note the changes from the previous version of the template.

6. Select the items you want to be available when new projects are created from this template.

The replacement project template is created. Its name and description appear on the Template tab of the Projects list, accessiblefrom your personal navigation bar.

Manage project categoriesTo help users navigate your site, help them sort projects into categories that make sense.

Add a project categoryWhen you set up project categories for your site, project administrators can use this taxonomy to organize their projects.

You can create any number of top-level categories and any number of sub-category levels.


2. On the site administration navigation bar, click Categories.

3. In the Project Categories tree, find the location where you want to create the new category.

• Highlighting Project Categories creates a new top-level category.• Highlighting any category creates a sub-category beneath it.

CollabNet TeamForge 5.2 | Support projects | 15

4. Click New.

5. In the Create Category window, write a name and description for the category.

6. Click Save.

The category is created. It appears in the Project Categories navigation tree, and is available for use by all project administratorswhen categorizing their projects.

Edit a project categoryA project category's membership and function may change over time. If it does, you can update the category's name or description.


2. On the site administration navigation bar, click Categories.The Project Categories tree displays the hierarchy of existing categories.

3. In the Project Categories tree, find the category that you want to edit.

4. Make the changes you need and click Update.

Move a project categoryYou can reorganize projects by moving a project category to another place in the project category hierarchy.

You can move a project category in the following ways:

• From a top-level category to a sub-category

• From a sub-category to a top-level category

• From a sub-category to another sub-category

When you move a project category, any sub-categories that it contains are also moved to the destination category.



3. On the Project Categories page, find the project category you want to move.

4. On the Edit menu, click Cut.

5. Find the location to which you want to move the selected project category.

You can move a project category either to the root category or into any other project category.

6. Choose the Paste option from the Edit menu.

The project category is now moved to the selected destination.

Delete a project categoryIf you no longer need a project category, you should delete it.

When you delete a project category, all of its sub-categories are also deleted.


2. On the site administration navigation bar, click Categories.The Project Categories tree displays the hierarchy of existing categories.

3. Using the document tree, find the project category that you want to delete.

4. Choose Delete from the Edit menu.

The project category and all of its sub-categories are deleted.

Disabling project categorizationIf you do not need to sort projects into categories, remove the ability to do so on your site.

By default, project categorization is disabled for new CollabNet TeamForge 5.2 installations.

Note: Disabling project categorization does not delete categories you have already set up.

16 | CollabNet TeamForge 5.2 | Support projects



3. On the Project Categories page, select Disabled and click Update.

Project categorization is disabled for your CollabNet TeamForge 5.2 installation.

CollabNet TeamForge 5.2 | Support projects | 17

Chapter

3Provide source control services

Topics:

• Integrate a source code server• Approve a source control

repository request• Approve an unmanaged CVS

server access request• Edit SCM integration details• Integrate an unmanaged CVS

repository with CollabNetTeamForge 5.2

Integrate a source code serverA site must have one or more servers to handle source code repositories and users. The source code server can be the same machineas the application server or a separate machine.

When you set up a managed software configuration management (SCM) server, you enable users to create, manage and sharerepositories through CollabNet TeamForge 5.2.

You can integrate more than one source code server of a given type. For example, you can have two or more Subversion servers onyour site. Consult a system administrator about the requirements for setting this up.

Tip: If you use a source code solution other than Subversion, CVS, or Perforce, you can integrate it using the CollabNetTeamForge 5.2 SOAP APIs. This enables you to exchange commit data with any SCM application. Consult your CollabNetTeamForge 5.2 system administrator.

Note: CVS servers must use file-based authentication to be integrated with CollabNet TeamForge 5.2. NIS and NIS+ integrationsare not possible.


2. Click Integrations.

3. On the SCM Integrations page, click Create.

4. On the Create Integration page, write a name and description for the integration.

5. Choose the type of SCM server you want.

Note: When you give a group access to a CVS or Wandisco Subversion repository, members of the group can view therepository but cannot do repository actions, such as commit and update. You must assign those permissions to usersindividually.

Note: The SCM Adapter option only works if you have created your own SCM integration using the CollabNet TeamForge5.2 SOAP APIs.

6. Supply the host name for the Soap Service Host.

This is the network address of the machine on which the integrated service, such as Subversion, is running.

Note: The default localhost will work only if the integration server is on the same server as the CollabNet TeamForge5.2 server.

7. Leave the default values in the SOAP Service Port field.

8. Specify whether users will use SSL to connect to their repositories.

9. Change the Repository Root value if you want to store the repository on your server in a different location.

The repository root is the top-level directory under which all source code repositories reside.

10. Select Requires Approval if an administrator must approve all repositories created on the server. By default, unmanaged serversrequire approval for all repositories, because repositories must be created and integrated manually.

11. For an unmanaged CVS server, supply the URL by which your users will access the service.

This will be of the form http://<myscmserver.com>/integration/viewvc/viewvc.cgi

Important: If your system administrator has upgraded your site to CollabNet TeamForge 5.2 from SourceForge EnterpriseEdition 4.4 or earlier, remove the port number in the SCM Viewer URL.

12. Click Save.CollabNet TeamForge 5.2 attempts to validate the SCM viewer URL. If it cannot validate the URL, you can:

• Correct it if you have entered it incorrectly.• Select Save with errors if the URL is different for an end user than it is for the CollabNet TeamForge server; for example,

if you have a firewall in place.

• If you are adding a managed SCM server, it is now added. All projects can now establish repositories on the server.

20 | CollabNet TeamForge 5.2 | Provide source control services

• If you are adding an unmanaged SCM server, all projects can now request repositories on the server. A CollabNet TeamForge5.2 administrator must create and integrate them manually.

Approve a source control repository requestWhen a user requests a source code repository on a source control server for which you have required approval, a CollabNet TeamForge5.2 administrator must approve the request before the repository is created.

When adding a source control server integration, you have the option to require CollabNet TeamForge 5.2 administrator approvalfor all repositories created on the server.

When a user requests a source code repository on a managed SCM server, the repository is created automatically after it is approvedby a CollabNet TeamForge 5.2 administrator.

Note: Before approving a source code repository request for an unmanaged SCM server, a CollabNet TeamForge 5.2 administratormust create and integrate the repository manually.


2. On the site administration navigation bar, click Integrations.

3. On the SCM Integrations page, click the Pending SCM Integrations tab.

4. From the list of pending SCM repository requests, select the SCM repositories that you want to approve.

• Click Approve to approve the repository.• Click Reject to reject the project and remove it from the list.

The person who requested the repository receives an email notification when the repository is approved or rejected. If you entered acomment, that also appears in the email notification.

Approve an unmanaged CVS server access requestWhen a user asks for access to an unmanaged CVS server, an administrator must approve or reject the request.

When a project administrator assigns a role that provides SCM access to a project member, a CollabNet TeamForge 5.2 administratormust manually create the user account on the SCM server. Because user creation is not managed by CollabNet TeamForge 5.2,CollabNet cannot verify that the user account has been created. A TeamForge administrator must confirm that he or she has createdthe account.

Requests for SCM access removal are also submitted for manual confirmation by a TeamForge administrator.



3. On the SCM Integrations page, click the SCM Access Requests tab.

4. Create the requested user account on the unmanaged CVS server.

5. After the user account is created, select the request and click Approve.

The user receives an email notification that the user account has been created.

Edit SCM integration detailsYou can move or reconfigure a source control server without having to reintegrate the server into CollabNet TeamForge 5.2.

Tip: If you edit or lose the permissions on your SCM server, use the Synchronize Permissions button on the SCM Integrationspage to recreate the correct permissions on your SCM server from CollabNet TeamForge 5.2.

CollabNet TeamForge 5.2 | Provide source control services | 21



3. On the SCM Integrations page, click the title of the SCM integration you want to edit.

4. On the Edit Integration page, make the changes you need and click Save.

Integrate an unmanaged CVS repository with CollabNet TeamForge 5.2After creating the repository, you must modify two triggers, verifymsg and loginfo, to complete the integration with CollabNetTeamForge 5.2.

The triggers must be modified manually, because much of the information in the triggers is specific to your CollabNet TeamForge5.2 installation.

Each trigger must be modified to run a .java program. These topics provide an annotated example and instructions on modifyingand installing the trigger files.

Note: You must create the CVS repository before you can modify and install the trigger files.

Important: CVS servers must be using file-based authentication to be integrated with CollabNet TeamForge 5.2. NIS andNIS+ integrations are not possible.

Create a loginfo trigger fileHere's now to create the loginfo trigger file.

1. Check out the module CVSROOT from the CVS repository.

The CVSROOT module is automatically created in all new CVS repositories, and contains the verifymsg and loginfofiles. When created, the files contain only comments.

2. Begin modifying the file by inserting ALL followed by a tab.

This enables CollabNet TeamForge 5.2 to see all modules in the repository.

3. Modify the path to your Java home directory as in this example and add it to the file, followed by a single space.

ModificationExample

Replace /usr/local/java/j2sdk1.4.1_01/with the directory in which you have installed Java.

/usr/local/java/j2sdk1.4.1_01/bin/java-cp

4. Modify the paths to the .jar files as shown here, then add them to the file separated by colons.

ModificationsExamples

Replace/yourdirectory/

/yourdirectory/sourceforge_home/lib/saaj.jar/yourdirectory/sourceforge_home/lib/axis-1.1rc1-va.jar

with the directory in/yourdirectory/sourceforge_home/lib/saturn.jarwhich you have installed/yourdirectory/sourceforge_home/lib/jaxrpc.jarCollabNet TeamForge5.2.

/yourdirectory/sourceforge_home/lib/externalintegration.jar/yourdirectory/sourceforge_home/lib/commons-discovery.jar/yourdirectory/sourceforge_home/lib/commons-logging.jar/yourdirectory/sourceforge_home/lib/log4j-1.2.8.jar

5. Modify the parameters as follows:


ModificationExample

Replace exsy1001with the ID of your

-Dintegration.name=exsy1001

SCM serverintegration withCollabNetTeamForge 5.2.

Note: To findthe ID, clickAdmin ➤

Integrations ➤IntegrationName . The IDappears at theend of the URL.

No change-Dcvs.cvsroot=$CVSROOT

Replace localhostwith the name of

-Dappserver.url=http://localhost:8080/sf-soap/services/ScmListener

your machinerunning CollabNetTeamForge 5.2.

Note: Ifneeded, replace8080 with yourSOAP serverport.

No change-Dcvs.username=$USER


-Dlog4j.configuration=file:/yourdirectory/sourceforge_home/etc/externalintegration/log4j.xml

with the directory inwhich you haveinstalled CollabNetTeamForge 5.2.

No change-Dexternalintegration.triggers.log.dir=/tmp

6. Add the following Java class containing the body of the trigger.

com.vasoftware.sf.externalintegration.triggers.cvstriggers.LogInfo %{sVv}

7. Check your file against the completed example shown on Completed loginfo trigger file.

8. When you are finished, check the modified file back into your CVS repository.

If you have not already done so, repeat the process for the verifymsg trigger file.

Note: If you make an error in the file, commits made to the repository will not fail, but you will receive error messages.

Create a modified verifymsg trigger fileHere's how to modify the verifymsg trigger file.


1. Check out the module CVSROOT from the CVS repository.

The CVSROOT module is automatically created in all new CVS repositories, and contains the verifymsg and loginfo files. Whencreated, the files contain only comments.

2. Begin modifying the file by inserting .* followed by a tab.

This enables CollabNet TeamForge 5.2 to see all modules in the repository.

3. Modify the path to your Java home directory as indicated below.

Add it to the file, followed by a single space.

ModificationExample

Replace /usr/local/java/j2sdk1.4.1_01/ with the directory in whichyou have installed Java.

/usr/local/java/j2sdk1.4.1_01/bin/java -cp

4. Modify the paths to the .jar files as shown in the following table.

Then add them to the file separated by colons.


Replace /yourdirectory/ with thedirectory in which you have installedCollabNet TeamForge 5.2.

/yourdirectory/sourceforge_home/lib/saaj.jar/yourdirectory/sourceforge_home/lib/axis-1.1rc1-va.jar/yourdirectory/sourceforge_home/lib/saturn.jar/yourdirectory/sourceforge_home/lib/jaxrpc.jar/yourdirectory/sourceforge_home/lib/externalintegration.jar/yourdirectory/sourceforge_home/lib/commons-discovery.jar/yourdirectory/sourceforge_home/lib/commons-logging.jar/yourdirectory/sourceforge_home/lib/log4j-1.2.8.jar

5. Modify the parameters as follows:


Replace exsy1001with the ID of your

-Dintegration.name=exsy1001

SCM serverintegration withCollabNetTeamForge 5.2.

Note: To findthe ID, clickAdmin ➤Integrations➤IntegrationName . TheID is at theend of theURL.

No change-Dcvs.cvsroot=$CVSROOT

Replace localhostwith the name of

-Dappserver.url=http://localhost:8080/sf-soap/services/ScmListener

your machinerunning CollabNetTeamForge 5.2. If



needed, replace8080 with yourSOAP server port.

No change-Dcvs.username=$USER


-Dlog4j.configuration=file:/yourdirectory/sourceforge_home/etc/externalintegration/log4j.xml

with the directoryin which you haveinstalled CollabNetTeamForge 5.2.

No change-Dexternalintegration.triggers.log.dir=/tmp

6. Add the following Java class containing the body of the trigger:com.vasoftware.sf.externalintegration.triggers.cvstriggers.VerifyMessage

7. Check your file against the completed example shown on Completed verifymsg trigger file.

8. Check the modified file back into your CVS repository.

9. If you have not already done so, repeat the process for the loginfo trigger file.

Note: If you make an error in the file and check it back into your CVS repository, all commits made to the repository will fail.To correct the file, you cannot simply check it out and fix it. You must fix it on the repository. After fixing the file on therepository, you must then check it out, fix it again, then check it back in.


Chapter

4Change your site's look and feel

For an overview of how site branding works, see Site customization filesThe values inthese files override the default look and feel of your site. You can edit these files to changesome aspects of your site's appearance and behavior.

Topics:

• Customize anything on your site• Customize the home page of your

siteNote: These instructions support only the most common types of customization.For more advanced customization options, post a question on the CollabNetTeamForge 5.2 discussion forum or talk to your CollabNet representative.• Change a project's home page

• Change your site's outgoingemails

http://forums.open.collab.net/ds/viewForumSummary.do?dsForumId=736

Customize anything on your siteFollow these general instructions to customize a page, picture, text string, or other element on your site.

Important: Custom branding changes can be overridden when your site is upgraded to a new version. You may have to reapplyany look-and-feel modifications after an upgrade.

1. Download the sample branding files.

Choose one of these files:

Contains the files you need to do most of your brandingtasks. Use this file if you are doing your own branding.

http://collab.net/community/cif/csfe/50/Branding_Basic.zip orhttp://collab.net/community/cif/csfe/50/Branding_Basic.tar.gz

Contains all the files that can be customized. For use whensomeone from CollabNet is doing your branding for you.

http://collab.net/community/cif/csfe/50/Branding_Advanced.ziporhttp://collab.net/community/cif/csfe/50/Branding_Advanced.tar.gz

Note: It is important that you have the most recent available version of this archive as a starting point. Check that the versionnumber at the top of the readme.txt file in your copy of the branding package is the same as your version of theapplication. If it is not the same, check www.collab.net to see if there is a more recent version.

2. In the look project, check out the branding repository.

3. Copy the default version of the appropriate file from the branding zip file to the equivalent directory in your local copy of thebranding repository.

4. Change the file to produce the results you want.For example:

• To change a logo on your site's home page, overwrite the home.gif file with a new file of the same name.

• To change a logo on a project home page, overwrite the project.gif file with a new file of the same name.

5. Commit the changed files into your site’s branding repository.

Important: Your branding repository does not have to contain all the files that are in the sample branding zip file, but thestructure of your repository must be an exact mirror of the structure of the sample file set.

28 | CollabNet TeamForge 5.2 | Change your site's look and feel

http://collab.net/community/cif/csfe/50/Branding_Basic.zip

http://collab.net/community/cif/csfe/50/Branding_Basic.tar.gz

http://collab.net/community/cif/csfe/50/Branding_Advanced.zip

http://collab.net/community/cif/csfe/50/Branding_Advanced.tar.gz

Customize the home page of your siteTo change the content of your site's main page, replace the home.vm file.

Note: For the general steps for changing the look and feel of a page, see Customize anything on your site on page 28.

The home.vm template controls the look, feel and structure of the standard home page. The default version allows users to log in andconditionally sign up for new user accounts if CollabNet TeamForge 5.2 is configured to allow user self creation.

Edit the home.vm template to produce the page you want.

You can change these objects on the site home page:

DescriptionObject

The html block that shows site news. The html block itself is notcustomizable.

siteNews

The html block that shows the most active projects. The html block itselfis not customizable.

mostActiveProjects

A flag that indicates that the activity graph should be displayed.displayActivityGraph

A flag that indicates that CollabNet TeamForge 5.2 quick links should bedisplayed.

displayCollabNet TeamForge 5.2Links

Change a project's home pageTo change the main pages of the projects on your site, edit the project_home.vm file.

Note: For the general steps for changing the look and feel of a page, see Customize anything on your site on page 28.

Edit the project_home.vm template to produce the project page you want.

You can change these objects on the project home page:

DescriptionObject

The object that contains the information about the project. It implements theinterface com.collabnet.ce.customization.IProjectData.

projectData

The list of project administrators. Each object of the list implements the interfacecom.collabnet.customization.IUserRow.

adminList

The list of project members. Each object of the list implements the interfacecom.collabnet.customation.IUserRow.

memberList

A flag that indicates that the user is a member of the project.projectMember

The button that contains the link to the Join Project page. It returns acom.collabnet.ce.customization.widgets.Button.

joinProjectButton

A flag that indicates that the page shows the Wiki Home page instead of thestandard Home page.

useCustomHomePage

The html that displays as the Project Home page.customHomePage

The button that is used to edit the custom Home page. It returns acom.collabnet.ce.customization.widgets.Button.

editCustomHomePageButton

CollabNet TeamForge 5.2 | Change your site's look and feel | 29

DescriptionObject

A flag that indicates whether or not the current user is a Project Admin.projectAdmin

A flag that indicates that the Wiki project logo image will be used instead ofthe standard project logo.

useCustomProjectLogo

The url from where the custom project logo image can be loaded.customLogoPathString

Change your site's outgoing emailsWhen you site sends out automated emails, the text of the emails can be customized to fit your site's specific needs.

Note: Before customizing your site, download the branding files. See Get the site branding filesTo start customizing your site,download the files that you will edit to control your site's look and feel. .

You control screen labels and messages by overriding the resource bundle keys that specify the text strings that appear in Velocitymacros and JSPs.

1. Check out the branding repository from the look project.

Tip: To find the look project, click Projects in the navigation bar and select All Projects.

2. In your local copy of the branding repository, create a directory called templates/mail.

3. In the templates/mail directory, create a file containing the custom content for an email that the system sends out. Givethe file the same name as the equivalent sample email file in the brnading files package.For example, to override the email that is sent out to new members of the site, name the filetemplates/mail/user_welcome.vm. Use Velocity syntax to identify the parts of the email, like this:

##subject

Welcome to our CSFE 5.0 site!

##subject

##body

Here is the content that I want to appear in emails coming from my site...

##body

Note: To customize a template in a specific language, identify the locale as an extension to the file name. For example, tocreate a user welcome file in Japanese, name the file templates/mail/user_welcome_ja.vm

4. Commit your new and changed files into the repository.

30 | CollabNet TeamForge 5.2 | Change your site's look and feel

Chapter

5Provide external applications

Topics:

• Create a site-wide linkedapplication

• Edit a site-wide linked application

Create a site-wide linked applicationWhen you create a site-wide linked application, it appears in all projects on your CollabNet TeamForge 5.2 site.

Site-wide linked applications are especially useful for incorporating corporate standard external applications, such as a companyintranet sites, into your CollabNet TeamForge 5.2 installation.


2. On the site administration navigation bar, click Integrations ➤ Site-wide Linked Applications .

3. On the Site-wide Linked Applications page, click Create.

4. On the Create Site-wide Linked Application page, provide a name for the linked application.This name appears on the link in the CollabNet TeamForge 5.2 navigation bar.

5. Enter the server location or URL for the linked application.

6. Select whether you want to enable single sign-on for the linked application.

• If you use single sign-on, access to the linked application is managed through the CollabNet TeamForge 5.2 authenticationsystem. Users are not required to log into the linked application after they have logged into CollabNet TeamForge 5.2.

• If you do not use single sign-on, users will be required to log in to the linked application using its native authentication system.

7. Choose how you want the linked application to appear when a user clicks it.

• In the same window. The linked application takes over the entire browser window, replacing whatever the user was lookingat.

• In a new window. The linked application launches in a separate browser window.• In an iframe. The linked application appears in a box in the same window, framed by the CollabNet TeamForge 5.2 site's

header and navigation controls.

8. Click Save.

A link for the site-wide linked application is added to your CollabNet TeamForge 5.2 navigation bar. Clicking the link displays theapplication in the main CollabNet TeamForge 5.2 window.

Edit a site-wide linked applicationWhen the use patterns of a linked application change, you may need to change the way the application integrates with CollabNetTeamForge 5.2.


2. On the site administration navigation bar, click Integrations ➤ Site-wide Linked Applications .

3. On the Site-wide Linked Applications page, click the name of the linked application that you want to edit.

4. On the Edit Site-wide Linked Application page, make the changes you need.

You can edit these elements:

• The name of the application.• The application's URL.• Whether the application uses single sign-on.• Whether the application is displayed in a new window, in the same window, or in an IFrame.

Note: You cannot change the application icon.

5. Click Save.

32 | CollabNet TeamForge 5.2 | Provide external applications

Chapter

6Require documents to be associated with artifacts

"Orphan" documents are documents that are abandoned because they are not connectedto any tracked activity.

1. Open the conf/site-options.conf file in a text editor.

2. Change the value of the sf.requireAssociationOnDocumentCreate variableto true

3. Change the value of the sf.allowedAssociationTypeOnDocumentCreatevariable to [TrackerArtifact]

4. If you want to prevent users from associating documents with closed artifacts,change the value of the sf.requireArtifactToBeOpenOnDocumentAssociationvariable to true

5. Save conf/site-options.conf.

6. Recreate the runtime environment.

sudo ./install.sh -V -r -n -d <SITE_DIR>./install.sh -V -r -d <SITE_DIR>

Chapter

7Check your server's status

Note: The Server Status page provides only the current status of each server. Itis not a diagnostic tool, and you must correct any connection or configuration issueson the server in question.


2. On the site administration navigation bar, click System Tools.

3. On the System Tools menu, click Server Status.

4. On the Server Status page, find the status of the server you are interestedin.

• SOAP server• Email server• Search server• All integrated SCM servers

For each server, you see one of the following status messages:

• OK - The server is running and connected to the main CollabNetTeamForge server.

• Could Not Connect - The server is not running or is not connected tothe main CollabNet TeamForge server.

Chapter

8Keep your site secure

Topics:

• Setting password requirements• Preventing cross-site scripting

(XSS)

Setting password requirementsFor security reasons, you may want to enforce a password policy that requires certain password characteristics.

You can specify the following characteristics:

• Minimum number of characters

• At least one number

• At least one non-alphanumeric character

• Mixed upper and lower-case characters

In the <install_dir>/sourceforge_home/etc/sourceforge_configuration.propertiesfile, set the following flags to true or false.

Note: Default values are indicated by brackets.

• system.password.min-length=[5]• password.requiresNumber=true | [false]• password.requiresNonAlphaNum=true | [false]• password.requiresMixedCase=true | [false]

Preventing cross-site scripting (XSS)By using the upload document function, an attacker could potentially upload an HTML page to CollabNet TeamForge 5.2 that containsactive code, such as JavaScript. This active code would then be executed by clients' browsers when they view the page.

To prevent an attack of this sort, you can specify whether or not HTML code is displayed in CollabNet TeamForge 5.2. This flagapplies to all documents, tracker, task, and forum attachments, and files in the file release system.

In the<SOURCEFORGE_SITE_DIR>/sourceforge_home/etc/sourceforge_configuration.propertiesfile, set the sf.safeDownloadMode flag to one of the following values.

• none: All file types that can be displayed inline are displayed inline, including HTML and text.

Note: This is the CollabNet TeamForge 5.2 default.

• html: HTML files are not displayed inline. All other file types that can be displayed inline are displayed inline, such as text.When a user tries to launch an HTML file, he or she is prompted to download and save the file locally.

• all: No file types are displayed inline. When a user tries to launch any file, he or she is prompted to download and save thefile locally.

38 | CollabNet TeamForge 5.2 | Keep your site secure

Chapter

9Support hardware provisioning

Topics:

• Set up a new TeamForge LabManagement project

• Move hosts from one project toanother

• Forward a port• Stop port forwarding• Set up host URL mapping• Stop URL mapping• Delete a project• Undelete a project• Expand your domain with virtual

guests• Add and remove profiles

Set up a new TeamForge Lab Management projectTo use TeamForge Lab Management with your CollabNet Enterprise Edition or CollabNet TeamForge 5.2 project, create or selecta CEE or SFEE project to link to.

Before a project is set up in TeamForge Lab Management, the project must first be created inside of CollabNet Enterprise Edition(CEE) or CollabNet CollabNet TeamForge 5.2 .

1. Log into TeamForge Lab Management as an administrator.

2. Click the Administration tab.

3. On the Administration menu, click Manage Projects.

4. In the Name field, give the TeamForge Lab Management project a brief and descriptive name.

5. In the Summary field, write a brief summary of the project.

Note: The TeamForge Lab Management project summary may be different from the CEE or SFEE project summary.

6. Click Add New button.

Your project is added. You can now pass the project on to the Project Admin of the project to begin administrating and configuring.

Note: If your project is an SFEE project, you will see that TeamForge Lab Management has added some Roles to your project.

Move hosts from one project to anotherWhen a project has too many machines or needs more, you may wish to reallocate hosts between projects.

You must be a domain administrator to move hosts between projects.

1. Notify the project administrator of the project you are taking hosts from, so their project members won't lose important workwhich they may not have saved on that system.

2. On the Project Home page for the project which contains the host you are moving, click the host you want to re-allocate.

3. Click the Admin tab for the host.

4. From the Project drop-down box, select the project that you want to move to.

Note: If you do not see a drop-down box here, it means:

• The host is a virtual guest. Virtual guests must remain in the same project as their parents.• The host contains virtual guests that are not all allocated to the same user. From the web interface, you can only change

the project of a virtual host if the parent and all its guests are allocated to the same user.

5. Click Update to move the host (and its guests, if any).

6. If you are concerned about the security or contents of the machine that has been moved to the new project, rebuild the machineas soon as possible.

This is the only way to ensure that only the exact software and users that you specified will be on the machine.

Note: For a more flexible way of moving hosts between users and projects, you can use a TeamForge Lab Management APIclient to perform the move.

Forward a portSet up port forwarding with the (?) screen. (This needs a better summary...)

40 | CollabNet TeamForge 5.2 | Support hardware provisioning

1. (Step missing here: "Go to some page or tab...")

2. Fill in the information.

The TeamForge Lab Management host that you want to access the network service from. For example,cu014.TeamForge Lab Management.TeamForge Lab Managementdemo.net

Host

The port on the Host -- the hostname you selected above -- that you want to access the network service on.For example, if you would like to forward a web server, you would select Host Port 80.

Host Port

The port on the TeamForge Lab Management Manager host that you would like to forward the traffic to.For example, if you would like to forward the above web server on Host cu014.TeamForge Lab

External Port

Management.TeamForge Lab Managementdemo.net and Host Port 80 to port 8080 onthe TeamForge Lab Management Manager host, you would enter 8080 in this field.

Note: Only certain ports may be selected for the External Port. The list of ports is given at the topof the screen.

The protocol or protocols to support when forwarding traffic. Choose one of these:Protocol

• TCP• UDP• Both TCP and UDP

Note: If you're unsure, ask the requestor for clarification. Most network services will only requireTCP.

A textual description of the service that is being forwarded. All users in the project will see this descriptionwhen they view the Summary page for the Host.

Description

Note: The Description is mandatory.

3. Click Add New to add your new forwarding.

The new forwarding is active immediately. To test your new forwarding, try accessing the External Port on the TeamForge LabManagement Manager from your desktop.

Tip: If the network service requires special client software, especially if the forwarding is using the UDP protocol, youmay not be able to easily test it. In that case, contact the requestor and ask them to verify that the forwarding works properly.

Stop port forwardingWhen you don't want to forward a port, you can delete or suspend forwarding for that port.

1. (Missing step: "Go to page...")

2. If you want to remove the port forwarding permanently, click Deletefor the forwarding you wish you delete.

Forwarding for this port is immediately disabled and deleted forever.

Note: You can always create a new forwarding with the same properties in the future.

3. If you think you might need this forwarding again soon, unchecking clear Enableand click Update for the forwarding you wishto disable.Enable the forwarding again by selecting Enable again and click Update again.

Set up host URL mappingSummary to come...

CollabNet TeamForge 5.2 | Support hardware provisioning | 41

Note: Only TeamForge Lab Management domain administrators can administer host URL mappings.

1. On the Administration tab, click Host URL Mapping in the navigation bar.

2. Provide the following information about the service you wish to map:

The TeamForge Lab Management host that you want to access the network service from. For example,cu014.TeamForge Lab Management.TeamForge Lab Managementdemo.net

Host

The port on the Host -- the hostname you selected above -- that you want to access the web service on. Forexample, if you would like to map a web server running on port 8080, you would select Host Port 8080.

Host Port

The URL on the Host that you want to map to. For example, if you want to map the URLhttp://cu014.TeamForge Lab Management.TeamForge Lab Managementdemo.net:8080/build/, you wouldenter /build for the Host URL.

Host URL

The location on the TeamForge Lab Management manager to map the Host URL to. The location will beunder the directory /apps. For example, if you enter mybuild for Mapped URL in our example, you will

Mapped URL

then be able to reach http://cu014.TeamForge Lab Management.TeamForge LabManagementdemo.net:8080/build/ as http://mgr.TeamForge Lab Management.TeamForge LabManagementdemo.net/apps/mybuild/.

Valid characters for Mapped URL's are: Letters, numbers, spaces, underscores, and hyphens.

Whether or not to force requests for the mapped URL to use SSL. Mapped URL's will always be accessiblevia SSL, even if this box is not checked. But, if you check this box, it will be impossible to access this

Use SSL

URL without SSL. In general, unless there is a very good reason for turning the Use SSL option off, werecommend keeping it on.

Set to either Safer or More Aggressive. Using the Safer option, only HTML attributes which are knownto contain URL's are dynamically rewritten. But in some cases, especially with applications that use

DynamicRewriting

embedded Javascript code, this will not be sufficient and some parts of your application will not workproperly. In this case, try the More Aggressive option. This option still attempts to be careful about whatit rewrites, but looks into the HTML more deeply and will rewrite a wider variety of HTML tags andattributes.

A textual description of the web service that is being mapped. All users in the project will see this descriptionwhen they view the Summary page for the Host.

Note: The Description is mandatory.

Description

3. Click Add Newto add your new URL mapping.

The new URL mapping is active immediately. To test it, try accessing the resulting URL from your desktop.

Stop URL mapping

Note: Only TeamForge Lab Management domain administrators can administer host URL mappings.

1. On the Administration tab, click Host URL Mapping in the navigation bar.

2. Click Delete for the URL mapping you want to stop.

The URL mapping is immediately disabled and deleted forever.

Note: You can always create a new URL mapping with the same properties in the future.

To temporarily disable a URL mapping, clear Enable and click Updatefor the URL mapping you wish to disable. To enable the URLmapping again, select Enable and click Update again.


Delete a projectTo remove a project from your TeamForge Lab Management site, delete the project.

Only TeamForge Lab Management Domain Admins can delete and undelete projects. When a project has been deleted, only TeamForgeLab Management Domain Admins can access it, and then only to undelete it.

Projects that contain hosts cannot be deleted.

Important: Deleting a project in TeamForge Lab Management does not delete the corresponding project in CollabNet TeamForge5.2 or CollabNet Enterprise Edition.

1. Check that there are no hosts allocated to this project.

You cannot delete the project if there are hosts currently allocated to it.

2. On the Projects tab, click the name of the project you want to delete.

3. Click Edit Project navigation bar.

4. On the Edit Project page, click Delete, then Confirm Delete.

The project is deleted from the system.

Undelete a projectTo bring a project back into your TeamForge Lab Management site, you can undelete the project.

Only TeamForge Lab Management Domain Admins can delete and undelete projects. When a project has been deleted, only TeamForgeLab Management Domain Admins can access it, and then only to undelete it.

1. On the Administration tab, click Manage Projects in the navigation bar.In the list of all the projects in the system, deleted projects are in italics and are marked "Currently deleted.".

2. Click the project you want to undelete.

3. On the Edit Project page for the deleted project, click Undelete button, then Confirm Undelete.

The project is restored to being a fully active TeamForge Lab Management project.

Expand your domain with virtual guestsUse virtual guests to maximize the productivity of your hardware.

Create a virtual guestHere's how to create a virtual guest.

Need a new task here...

Migrate a virtual guestWhen a virtual guest consumes too many system resources, or you wish to rebuild or perform other more drastic maintenance on thevirtual guest's current virtual host's use, migrate the guest to a different host.

Before moving a virtual guest, make sure the following is true:

• You are a TeamForge Lab Management domain administrator.

• The current virtual host and guest, and the desired new virtual host, are all in the same project.

• The target virtual host has enough RAM, disk, and CPU to accommodate the virtual guest you wish to migrate to it. (TeamForgeLab Management displays a drop-down list of hosts that fulfill all these criteria.)


• The virtual guest being moved and the target virtual host are on the same subnet.

1. Go to the Host|Admin page for the virtual guest that you wish to migrate.

2. In the Move to Virtual Host drop-down box, select the host you wish to migrate this virtual guest to, and click Update.

Note: If you do not see this drop-down box, but instead see the text "No hosts are eligible for re-parenting," there are noother virtual hosts in this project that could accommodate this virtual guest. You must delete or reduce the hardware resourcesassigned to one or more existing guests.

3. Click Confirm Update.

The virtual guest immediately shuts down and begins migrating. The owner of the virtual guest (not necessarily the user that requestedthe migration) receives an e-mail when the migration is complete.

Note: There is no exact time frame or estimate for how long a guest migration takes. A typical "base" system without muchdata (e.g., under 10GB) usually migrates in 5-15 minutes. The time required is mostly dependent on the size of the virtualmachine, coupled with the load on the source and destination virtual hosts.

Delete a virtual guestYou delete a virtual guest the same way you delete a physical host.

Important: Before you delete your guest, be aware of one very important difference: As soon as you delete a virtual guest, thevirtual guest system and all its data are wiped out forever! This is in contrast to deleting a physical host, in which case themachine gets removed from TeamForge Lab Management, but the contents of its hard drive are not wiped out, and could stillbe rescued by an administrator with physical access to the system.

1. On the Host|Admin screen, click Delete Host.

2. Click Confirm Delete.

The virtual guest is permanently deleted.

Add and remove profilesLike hosts and projects, profiles must be added at the domain level before they can be used by individual projects. Likewise, theycan be administratively disabled from use at the domain level.

Add a new profileTo add a new profile, follow these steps:

1. Log into TeamForge Lab Management as a user with TeamForge Lab Management Domain Admin privileges.


3. On the Administration menu, click Manage Profiles and click the Add New Profile tab.

4. Enter the following information.

Note: All fields are mandatory.

The name of the profile. Must already exist in the site's Subversion repository before it can be addedinto TeamForge Lab Management. This name can never be changed, so be sure to get the profile namedproperly when you initially create it.

Profile name

A brief summary of the profile. The Summary can be changed later on using the Profile Admin page.Summary

What project the profile belongs to. If you leave it blank, the profile will belong to the domain, andeither be accessible to all projects (if the profile is public) or no projects (if the profile is private). Thisproperty can be changed later on using the Profile Admin page.

Project


Whether the profile is public (can be used by any project) or private (can only be used by the projectwhich owns the profile). This property can be changed later on using the Profile Admin page.

Public

Whether or not the profile is a VMware or other prebuilt image file. This profile property cannot bealtered once the profile is created. If your profile is an image file, this will be Yes. If your profile installsvia a network install method like Kickstart(tm) or Jumpstart(tm), this will be No.

Prebuilt

The minimum disk size required to build and run this profile. The minimum disk size should be at least10 GB.

Size (in GB)

5. Click Add New to add the new profile.

Stop using a profileProfiles in TeamForge Lab Management cannot be permanently deleted. Instead, we refer to them as disabled. It is possible to makeprofiles accessible again.

When a profile is disabled, it gets removed from all projects that currently allow the profile. If you disable a profile and then enableit later, project managers who previously allowed that profile will have to go back into their project's Profile Library and add theprofile again.

Important: Use caution before disabling a profile. Contact the owners of the systems using that profile, and owners of projectsthat include that profile, before disabling the profile.

1. Log into TeamForge Lab Management with TeamForge Lab Management Domain Admin privileges.


3. On the Administration menu, click Manage Profiles.

4. In the list of all profiles currently in the system, click the profile you wish to disable.

5. Click the Admin tab.

6. Click Disable Profile.

The profile is disabled and removed from all projects that currently allow it.

Enable a profileTo build a machine with a profile that has been disabled, you must re-enable the profile.

1. Log into TeamForge Lab Management with TeamForge Lab Management Domain Admin privileges.


3. On the Administration menu, click Manage Profiles.

4. In the list of all profiles currently in the system, click the profile you wish to re-enable.

5. Click the Admin tab.

6. On the Admin page, click Enable Profile to re-enable the profile.


Appendix

AFrequently asked questions about site administration

Topics:

• How do TeamForge licenseswork?

• What's the difference between a"managed" and "unmanaged"CVS server?

• Does CollabNet TeamForge 5.2support merge tracking?

• What is a user group?• What elements of a site can I

customize?• Frequently asked questions about

providing TeamForge LabManagement services

How do TeamForge licenses work?You can use CollabNet TeamForge 5.2 in a limited version for free, but to get the full benefit of TeamForge, you must have a licensekey.

• When you purchase a license key and install it in your CollabNet TeamForge 5.2 site, you can use CollabNet TeamForge 5.2 forone year.

• How many users your site can support depends on the type of license. Check with your CollabNet representative if you aren'tsure what kind of license you have.

• Your license key is attached to the IP address of the server where your site runs. You can get a license key for a single IP addressor for a range of IP addresses.

• Your service year starts the first time you log into your site, or the first time you create or edit any item on your site, such as atracker artifact or a document. Whichever of these events comes first starts the clock.

• The expiration date of your license is shown on the License Keys page. (See the About CollabNet TeamForge 5.2 page for thecompany name associated with the license.)

• When your service year expires, you can still see the project data on your site, but you cannot make any changes to it. However,you can still carry out some critical maintenance functions for your site:

• Enter a new license key.• Deactivate or delete users.• Change user passwords.• Get forgotten user passwords.• Use documentation on http://help.collab.net.

What's the difference between a "managed" and "unmanaged" CVS server?You can use CollabNet TeamForge 5.2 to control a CVS server, or you can run the CVS server on a stand-alone basis.

Note: Only CVS servers can run unmanaged. Subversion and Perforce servers must be managed by CollabNet TeamForge 5.2.

Managed server

A managed server gets its instructions from the CollabNet TeamForge 5.2 site that it is integrated with. You use TeamForge for suchSCM tasks as:

• Creating the repositories.

• Adding and removing users.

• Enabling or disabling user access to the repositories.

Both new SCM servers and those with existing repositories can be managed by CollabNet TeamForge 5.2.

Unmanaged server

On an unmanaged CVS server, you use the CVS's own utilities to handle repository management, user management, and accesspermissions.

Add an unmanaged server if you know that all repository and user creation and management must be done manually. For example,set up an unmanaged CVS server when:

• A corporate IT policy prohibits applications such as CollabNet TeamForge 5.2 from making any changes to the users or repositorieson the corporation's CVS servers.

• A CVS server has existing repositories that cannot be changed to adhere to CollabNet TeamForge 5.2 standards.

48 | CollabNet TeamForge 5.2 | Frequently asked questions about site administration

http://help.collab.net

Does CollabNet TeamForge 5.2 support merge tracking?The Subversion repositories that are installed with CollabNet TeamForge 5.2 run on Subversion 1.5, which supports merge tracking.

Any Subversion 1.5 servers you have integrated with CollabNet TeamForge 5.2 support merge tracking. If you need the mergetracking feature and your Subversion server is running a version earlier than Subversion 1.5, you must upgrade to Subversion 1.5 toget this functionality.

If you used svnmerge.py (http://www.orcaware.com/svn/wiki/Svnmerge.py) to do merge tracking before Subversion 1.5, andyou want to convert your svnmerge.py data to the Subversion 1.5 merge tracking data format, CollabNet provides a migrationtool here:

http://svn.collab.net/repos/svn/trunk/contrib/client-side/svnmerge/svnmerge-migrate-history.py

What is a user group?To manage multiple users at once, create a group to represent them.

You can create a group to facilitate managing many users who share one or more characteristics.

For example, giving all the users in the accounting division access to all financial projects might be laborious if you assigned thepermissions one at a time. Instead, create a group and assign it access to the financial projects category.

A user group can have any number of roles. When a role is assigned to a group, every member of that group has that role.

Note: A user who has a role in a project by virtue of group membership is not necessarily a member of that project. Becominga member of a project is a separate process.

Group permissions are cumulative. This means that each member of the user group has all the access permissions allowed by all ofthe assigned roles, plus any permissions that may have been assigned by other methods, such as application permissions or individuallyassigned roles.

What elements of a site can I customize?You can customize the site home page and the default home page of every project on the site. You can also customize the menu bars,headers and footers of any page.

ImagesEvery image in CollabNet TeamForge 5.2 can be edited or replaced by a new image file.

Images are stored in an images directory in the branding repository.

Note: The default CollabNet TeamForge 5.2 image files are included in both the QuickStart and Advanced branding zip file.

Examples

• To replace the masthead graphic, replace the image file images/masthead/logo.gif

• To replace the folder graphic, replace the image file images/my/all_projects.gif

Stylesheets

The look and feel of much of CollabNet TeamForge 5.2 is controlled by cascading style sheets (CSS).

All default CSS styles can be customized to alter the look of the application. You can customize fonts (color, size, font face, etc.),links, backgrounds, headings, tables, tabs, and anything else that CSS can control.

The default CollabNet TeamForge 5.2 CSS file is css/styles_new.css.

CollabNet TeamForge 5.2 | Frequently asked questions about site administration | 49

http://www.orcaware.com/svn/wiki/Svnmerge.py

http://svn.collab.net/repos/svn/trunk/contrib/client-side/svnmerge/svnmerge-migrate-history.py

New CSS files can be added to the css/ directory and reference them via templates/body_header.vm.

Tip: If you override an existing CSS file, it will be used instead of the default CSS file. So you must be sure to include all thedefault styles in your customized file. A best practice is to add any new or overridden styles to the bottom of the CSS file sothat they can be easily identified.

Velocity templatesVelocity is the templating language that CollabNet TeamForge 5.2 uses to render areas of the site with dynamic information.

Velocity templates are located in the templates directory in the branding repository.

You can override the instructions contained in any of these Velocity templates by placing a file of the same name in the equivalentpath in the branding repository in the look project on your site.

DescriptionVelocity file

Controls the rendering of the top bar across all pages in the system. Displays a smalllogin form, the site logo and current user information as well as the search andprojects drop down menus.

menu_bar.vm

Contains only the top logo, without the menu that appears below it.blank_menu_bar.vm

Rendered immediately after the opening body tag. If a site requires everything tobe contained in some other container, this template can be used.

body_header.vm

Rendered immediately before the closing body tag. If a site requires everything tobe contained in some other container, this template can be used.

body_footer.vm

Controls the rendering of the bar beneath the menu bar, which contains the “QuickJump” link as well as the buttons that appear on any project page (the one containing

button_bar.vm

the applications). Site admin pages, user settings pages (e.g. my workspace,dashboard) and project pages use different sets of buttons that are passed into thistemplate for rendering.

Rendered after the button bar; wraps the actual contents of the page being viewed.content_header.vm

Rendered before the body footer; wraps the actual contents of the page being viewed.Contains the Copyright notice.

content_footer.vm

Velocity template that generates the site home page.sfmain/home.vm

Velocity template that generates the default project home page.sfmain/project_home.vm


Arbitrary HTMLCollabNet TeamForge 5.2 “Snippets” are customizable HTML text fragments that can be inserted in predefined locations in CollabNetTeamForge 5.2 pages.

Snippets can be added in the following locations:

• Below the page title on all CollabNet TeamForge 5.2 templates.• Above the footer on all CollabNet TeamForge 5.2 templates.

Snippets get checked into the templates/html/ directory in the branding repository.

• The file name for the header looks like this:

<applicationname>-<actionname>-Top.html

• The file name for the footer looks like this:


<applicationname>-<actionname>-Bottom.html

For example, to put your own custom snippet at the top of the Tracker ViewArtifact page, name the filetracker-viewArtifact-Top.html.

Note: The file names are case-sensitive.

Tip: You can find the application name and the action name in the URL of the page you are customizing. For example, considera URL such as http://sf5latest/sf/sfmain/do/createProject. Here, the application name is “sfmain”(the main CollabNet TeamForge 5.2 application) and the action name is “createProject.” If this page had a custom snippet nearthe header, the file containing the custom snippet would betemplates/html/sfmain-createProject-Top.html.

Email notificationsThe default text for CollabNet TeamForge 5.2 email notifications can be customized.

Email templates are located in the templates/mail directory in the branding repository.


Some email templates that are commonly customized are:

• user_welcome.vm• account_request_rejection.vm• project_approve_pending.vm• user_forgot_password.vm

Email template formatting follows the standard Velocity conventions:

user_welcome.vm ##subject Welcome to CollabNet TeamForge 5.2 5.0! ##subject ##body The Welcome message goes here... ##body Email subject line Email message text

ScriptsThe JavaScript scripts used in CollabNet TeamForge 5.2 can be customized.

Existing JavaScript scripts are located in the js/ directory in the branding repository.

New scripts can be checked into the js/ directory then referenced from Velocity templates.

What is the look project?The look project contains special files that can override your site's default appearance and content, such as the default icons, fonts,colors, and labels.

Unlike most projects, the look project has no members. It is only visible to users with site administration permission. Its onlypurpose is to control your site's look and feel, including such things as fonts, background colors, icons, and the wording of the onscreenlabels that appear throughout your site.

Any project on your CollabNet TeamForge 5.2 site can have one or Subversion repositories associated with it. The look projecthas just one Subversion repository. That repository is named branding.

When a user requests a page from your site, CollabNet TeamForge 5.2 checks the branding repository to see if any files therespecify custom fonts, colors or text strings. If such specifications are found, CollabNet TeamForge 5.2 displays the page accordingto those specifications. If not, the page displays according to the default design.

Having your custom look-and-feel specifications in a Subversion repository enables you to roll back changes, track contributions,and use all the other features of a source code versioning system.

Frequently asked questions about providing TeamForge Lab ManagementservicesNavigation title:Site administrator FAQ

Use this background knowledge to help you support TeamForge Lab Management projects.

Frequently asked questions about providing TeamForge Lab Management servicesNavigation title:Site administrator FAQ

Use this background knowledge to help you support TeamForge Lab Management projects.

What is an audit log?Every action performed by the user in the TeamForge Lab Management system is recorded in the Audit Log.

For example, when a host is rebuilt using a profile, these are some of the details captured in the Audit log:


• The old profile.• The new profile.• How long it took to complete the rebuild process.

What happens when I move a machine between projects?When you move a machine from one project to another, the machine is not automatically rebuilt. It still runs the same profile and allthe same software it was running in the original project.

There can be reasons for wanting to move a machine between projects without rebuilding it. For example, due to a reorganization,the same users and hosts may be providing the same service, but under a different department or project.

Moving a machine does not reboot the machine or stop any running processes.

If the old project was running processes on the machine that you do not want, you will have to stop them manually.

Moving a machine changes the access rights on the machine, but does not end existing login sessions.

Once the machine has changed projects, after a few minutes, the authentication will have changed so that users from the old projectcan no longer log in and users from the new project can now log in.

Existing user login sessions, however, are not terminated. Those users will not have root (UNIX) or Administrator (Windows)access any more.

Moving a machine does not reset the contents of the localadm group.

The localadm group is used to maintain a list of users on the system who are local administrators. This group is not emptied whena machine moves projects. It could contain users which you do not want as administrators on the host in the new project.

What is port forwarding?Use port forwarding to let TeamForge Lab Management hosts connect to machines on other networks.

While TeamForge Lab Management is a secure and isolated environment, occasionally there are valid reasons to let other traffic inand out of TeamForge Lab Management.

Port forwarding consists of routing traffic from one network port on one host to another (same or different) network port on anotherhost.

Take great care when exposing network services running on TeamForge Lab Management hosts to the outside world. Acquaintyourself with your organization's security policies, or develop them if you don't already have them, and make sure all services thatare exposed comply with these policies. Even better, work with CollabNet to establish access controls around the access to TeamForgeLab Management, so only authorized hosts from within your enterprise -- and trusted partners -- can access TeamForge LabManagement.

Important: CollabNet strongly recommends that any service that can yield a shell account on a TeamForge Lab Managementnode -- such as SSH -- not ever be port forwarded to outside the TeamForge Lab Management environment using this interface.

For CollabNet Hosted customers: CollabNet performs regular scans of its network, and if we see a dangerous or vulnerablenetwork service configured, we may take any steps necessary to protect the overall security of the TeamForge Lab Managementcustomer environment, including disabling the offending network service and the associated port forwarding.

What is host URL mapping?Host URL Mapping in TeamForge Lab Management allows you to access web services running inside the TeamForge Lab Managementenvironment from anywhere, using a simple and consistent URL, with optional SSL encryption services added on.

Host URL Mapping provides three major benefits:

• Maintains a consistent URL even if the service is moved to a different TeamForge Lab Management node or different base URL.• Provides external access to resources that would otherwise be only accessible inside the TeamForge Lab Management environment.

Because Host URL Mapping uses standard HTTP/HTTPS ports, you will not be blocked by firewalls that sometimes preventport forwarding from working properly.

• Allows you to transparently add SSL encryption to web services running inside your TeamForge Lab Management environment.


If your application mixes absolute and relative URL's, host URL mapping dynamically rewrites the absolute portions of your URLsto help ensure that your applications display properly when they are mapped. While not perfect, this feature has been tested with anumber of web applications and found to be effective.

Caution: Take the utmost care when exposing web services running on TeamForge Lab Management hosts to the outsideworld. Acquaint yourself with your organization's security policies, or develop them if you don't already have one, and makesure that all services that are exposed comply with these policies. Even better, work with CollabNet to establish access controlsaround the access to TeamForge Lab Management, so only authorized hosts from within your enterprise -- and trusted partners-- can access TeamForge Lab Management.

CollabNet strongly recommends that any web service that you expose be password-protected, or otherwise require authentication toaccess.

CollabNet Hosted customers: CollabNet performs regular scans of its network, and if we see a dangerous or vulnerable web serviceconfigured, we may take any steps necessary to protect the overall security of the TeamForge Lab Management customer environment,including disabling the offending service and the associated URL mapping.

Note: While you can convert non-SSL URL's into SSL using Host URL Mapping, you cannot map SSL URL's. You can usePort Forwarding to expose SSL URL's outside of the TeamForge Lab Management environment, however.

How does host URL mapping compare with port forwarding?URL mapping is good if you don't want your connection blocked, while port forwarding is good if you need non-HTTP services.

• Port forwarding is a facility for making any TCP or UDP network service available outside the TeamForge Lab Managementenvironment. Host URL mapping only allows you to expose HTTP-based services.

• A major limitation of port forwarding is that many organizations' firewall security policies prohibit outgoing connections toarbitrary high ports. Because URL mappings all use standard HTTP/HTTPS ports 80 and 443, they will never be blocked. If youcan access TeamForge Lab Management itelf, you will be able to access any application configured with host URL mapping.

• Host URL mapping can automatically add SSL encryption to your web services that are not running SSL encryption. With portforwarding, if you want SSL encryption, you must set it up on each host.

• Using host URL mapping, you can expose only a part of a server's URL space. With port forwarding, the entire URL space isvisible.

• Port forwarding does not need to rewrite links inside the HTML, so more web applications will work under port forwarding.

Why doesn't URL mapping work for me?My page doesn't look right. Images and graphics are wrong, or functionality doesn't work. The same page looks and works fine whenviewed through Port Forwarding.

Host URL Mapper attempts to "clean up" HTML pages which pass through it in order to clean up absolute links. But it is not hardto construct an application that will slip through TeamForge Lab Management's filters and still not properly render all of its referencedobjects inside of its pages. We make all reasonable attempts to clean up HTML, but not all applications can be properly renderedusing Host URL Mapping. This is especially true for applications which make heavy use of Javascript, ActiveX, Java applets, andother types of rich client-side web programming.

To test this, use either a direct connection to the host (if available) or a port forwarded connection to the host to see if this behavioris present on the original version of the page. If the original page does not have this behavior, the first step is to verify the DynamicRewriting level is set to More Aggressive. If that does not work, please file a support request with CollabNet to evaluate the page.

How are virtual guests different from physical machines?Virtual guests work like physical hosts, with some important differences.

Creating a new virtual guest

The process of creating a new virtual guest is very similar to the process of creating a new physical host, with the following differences:

• You must select a virtual host -- a physical machine -- to run the virtual guest on. You cannot run a virtual guest inside of anothervirtual guest.

• The virtual guest's project cannot be set independently of the virtual host, and the virtual guest will always be in the same projectas its virtual host.

• You are constrained, with hard limits, by the RAM and hard disk available on the virtual host. TeamForge Lab Managementrequires that each host have a minimum of 512MB of free RAM and 10GB of disk free.


• Even if you are within the hard limits for RAM and hard disk space usage, you are still sharing other resources -- notably diskI/O bandwidth, network bandwidth, and CPU cycles -- with the host machine and any other guests already on the virtual host.Before creating a new virtual guest on a virtual host, we recommend carefully examining the virtual host's system performanceto make sure it can handle the additional load. Of course, if you do find out later on that performance of your virtual guest is notas good as you would like, you can always migrate the virtual guest to another virtual host.

• You are not as constrained on your selection of MAC address with virtual guests ; you can choose any available address in theallowed range. Valid values for MAC addresses for virtual guests in TeamForge Lab Management are 00:50:56:01:00:01 to00:50:56:3F:FF:FF. Using anything outside of this range will either result in the host not being reachable on the network, or thehost coming in conflict with another MAC address on the network.

• You cannot specify the architecture or chip type for the virtual guest, since those properties are inherited from the parent.

• You do not need to specify a Lights Out Management IP address for the virtual guest, since the IP address used to manage theguest is always the IP address of the virtual host.

Disk size

While disk space is allocated to virtual guests at the time of virtual guest creation, it is not actually occupied on the host until it isneeded by the guest. At the same time, TeamForge Lab Management does not keep an up-to-date count of exactly how much diskspace is in use on the virtual host.

In practice, this means:

• You will likely have more disk space on your host than your virtual guests would indicate. But it is also possible to have lessspace than your virtual guests would indicate. For example, let's say you have a 100GB disk on your host, with two virtual guests,each with a 40GB disk allocated. But if you're only using 5GB of that 40GB in each guest, the remaining 70GB in unallocated.But on the flip side, let's say you allocated those two virtual guests at 10GB each, but they were using a total of 90GB on yourlocal disk to store files. TeamForge Lab Management would let you make this allocation, but your virtual machines would crashwhen you tried to put more than a combined 10GB on them both.

• This translates into freedom in your management of disk space on the virtual hosts: you are free to temporarily "borrow" diskspace from virtual guests that is not being currently used and use it for your virtual host.

• Along with this freedom comes the responsibility of being vigilant about maintaining sufficient space on your virtual hosts toalways have enough disk space for any guests on the system. Monitor your usage carefully using Analytics page for the host.

Modifying hardware parameters of existing virtual guests

Some virtual guest hardware parameters can be modified after the virtual guest has been created.

While changing the size of the disk is supported in TeamForge Lab Management, the change will not bereflected until you re-image your guest. And, in certain cases, it is possible for a change in the disk size of

Changing disk size

your guest to cause the guest to become unreachable, especially if you reduce the disk size. Therefore, werecommend that you change disk size on virtual guest only if you are going to immediately rebuild theguest.

Changing RAM size is a very low-risk operation. In order for the change to take effect, the virtual guestmust be rebooted after the change is made in TeamForge Lab Management. Reducing the RAM availableto your virtual guest can make the system run much slower.

Changing RAM size

Note: In between changing RAM size of the virtual guest and rebooting the virtual guest, you mustwait approximately 5 minutes to insure your change is propagated.

Virtual guests can support either one or two processors. Two CPUs for virtual guests are supported onlyif the virtual host has at least two CPUs. Like changing a virtual guest's RAM allocation, changing the

Changing the numberof CPUs

number of CPUs in a virtual guest is a low-risk operation, and the virtual guest must be rebooted after thechange has been made in TeamForge Lab Management.

Note: In between changing number of CPU's for the virtual guest and rebooting the virtual guest,you must wait approximately 5 minutes to insure your change is propagated.


What is involved in migrating a virtual guest?When you migrate a virtual guest to a different host, there are a few things to keep in mind.

• The user performing the migration must be a TeamForge Lab Management Domain Admin.• The current virtual host and guest, and the desired new virtual host, must all be in the same project. In other words, you cannot

change both the project allocation and the parentage of a host in a single step.• The target virtual host must have enough RAM, disk, and CPU to accommodate the virtual guest you wish to migrate to it. The

rules governing the RAM, disk and CPU needed are the same as if you were creating a new virtual guest on the host.

TeamForge Lab Management calculates these values for you and presents you with a drop-down list of hosts that fulfill all thesecriteria. But if you are wondering why a host is not a valid potential new virtual host, see the host's current hardware parametersand allocations on the Host|Admin page for the virtual host.

• If your TeamForge Lab Management installation is composed of more than one subnet, both the virtual guest being moved andthe target virtual host must be on the same subnet. If you are not sure if your installation has more than one subnet, check withyour local TeamForge Lab Management support contact.

• Only one virtual guest at a time can be migrated to a given virtual host, although there is no limit on the number of virtual gueststhat can be moved from a given virtual host. The reason for this restriction is that moving a virtual guest to a host is a veryI/O-intensive operation that will consume all available disk I/O on the destination host. Allowing more than one simultaneousmove will not be any faster, and increases the risk of over system instability for the virtual host.

• If more than one virtual guest migration to a given virtual host is started at the same time, they will complete serially. The exactorder of the migrations may not correspond exactly to the order in which they were initiated and cannot be accurately predicted.

• Occasionally, after the migration has completed successfully, the virtual guest will require an extra reboot to start up properly.

What's a good way to read log information?To read log entries, download the log as a CSV file.

You can also filter the logs using the Filter option at the top of all audit log screens.

On any log page, you can click Download all log entries in csv format to download the corresponding CSV file.

Note: The CSV file is formatted in Microsoft Excel format. If you import it into OpenOffice, set Text Delimiter to " (doublequotes).

How are systems in my domain being utilized?Improved features for quickly determining site utilization across all hosts and all projects in your TeamForge Lab Managementdomain are coming soon!

Until that point, the best way to see cross-project utilization is to look at each project's Analytics tab separately and compare acrossprojects manually.


Appendix

BReference information

Topics:

• Install reference• Scripts• Log files• Configuration files• Reference information about

TeamForge Lab Management

Install referenceThis reference information includes details to support installing the application.

Minimum hardware requirements for CollabNet TeamForge 5.2The following hardware is the minimum recommended for the server on which CollabNet TeamForge 5.2 is installed and the serveron which the database is installed.

CollabNet TeamForge 5.2 requires the following minimum server characteristics.

• 2 x CPU 2GHz

• 2 GB RAM

• >40GB hard drive

Required hard drive capacity depends on the estimated amount of document and file release uploads.

Note: We strongly recommend running the CollabNet TeamForge 5.2 application and its database on separate physical servers.Each server should meet the same dual-processor, 2-GHz standard.

Supported software for CollabNet TeamForge 5.2This is the official list of software that is compatible with CollabNet TeamForge 5.2.

Operating systems

CollabNet TeamForge 5.2 has been tested on these operating systems:

RestrictionsArchitectureVersionOperating system

Must have RHN orequivalent

32-bit5.3Red Hat Enterprise Linux



32-bit5.2CentOS

32-bit4.7CentOS

64-bit4.7CentOS

Important: Red Hat Enterprise Linux 5.3 machines must have access to the Red Hat Network or equivalent (satellite server,spacewalk, or RHN proxy). For more information, see www.redhat.com.

Operating system

CollabNet TeamForge 5.2 runs on Red Hat Enterprise Enterprise Linux 5.3 (32-bit).

Databases

These database products have been tested with CollabNet TeamForge 5.2:

• PostgreSQL 8.2.12

• Oracle 10.2

Database

CollabNet TeamForge 5.2 uses PostgreSQL 8.2.12 for its database.

60 | CollabNet TeamForge 5.2 | Reference information

https://www.redhat.com/rhn/rhndetails

Browsers

These browsers have been tested with CollabNet TeamForge 5.2:

• Mozilla Firefox 3.0.x

• Microsoft Internet Explorer 6.0.x

• Microsoft Internet Explorer 7.0.x

Software configuration management tools

These software configuration management (SCM) tools have been tested with CollabNet TeamForge 5.2:

• CVS 1.11.x

• Subversion 1.5.5 (FSFS)

• Perforce 2006.2

Java SDK

Java SDK 1.5.0_12 has been tested with CollabNet TeamForge 5.2.

Oracle client

Oracle 10gR2 - 10.2.0.1.0 Standard Edition has been tested with CollabNet TeamForge 5.2.

Note: The Express Edition is not supported.

Microsoft applications

These Microsoft applications have been tested with CollabNet TeamForge 5.2:

• Microsoft Project 2002 (with Service Pack 1) on WinXP Service Pack 2 and Win20002 Service Pack 4

• Microsoft Project 2003 (with Service Pack 1) on WinXP Service Pack 2 and Win20002 Service Pack 4

• Microsoft Office XP (with Service Pack 3) on WinXP Service Pack 2 and Win20002 Service Pack 4

• Microsoft Office 2003 (with Service Pack 1) on WinXP Service Pack 2 and Win20002 Service Pack 4

LDAP (Lightweight Directory Access Protocol) application

OpenLDAP 2.3.27-5 has been tested with CollabNet TeamForge 5.2.

RPM packages installed with CollabNet TeamForge 5.2The CollabNet TeamForge 5.2 install utility downloads all the software necessary for running a CollabNet TeamForge 5.2 site inthe form of RPM packages.

Overview

Which RPMs are installed depends on the platform version. Packages are provided for these platforms:

• The 32-bit and 64-bit versions of Red Hat Enterprise Linux 4

• The 32-bit version of Red Hat Enterprise Linux 5

If you prefer not to download the packages (for example, if you don't have an Internet connection), you can copy them to thedownloads directory under the location where you unzipped the installer. The installer skips downloading any required packageit finds in that location.

RPM file names normally have the following format: <name>-<version>-<release>.<arch> .

Note: The only way to upgrade the installed RPMs is by upgrading the application. The rpm -U command is not supported.

Tip: You can also list the RPM packages with the rpm –qa command.

CollabNet TeamForge 5.2 | Reference information | 61

RPMs for 32-bit Red Hat Enterprise Linux 4

• apr-0.9.12-2.i386.rpm

• apr-util-0.9.12-1.i386.rpm

• compat-postgresql-libs-4-2PGDG.rhel4.i686.rpm

• cvs-1.11.17-9.RHEL4.i386.rpm

• httpd-2.0.52-25.ent.i386.rpm

• jdk-1_5_0_12-linux-i586.rpm

• mod_dav_svn-1.5.0-1.i386.rpm

• neon-0.27.2-1.i386.rpm

• neon-devel-0.27.2-1.i386.rpm

• postgresql-8.2.4-1PGDG.i686.rpm

• postgresql-docs-8.2.4-1PGDG.i686.rpm

• postgresql-libs-8.2.4-1PGDG.i686.rpm

• postgresql-server-8.2.4-1PGDG.i686.rpm

• python-chardet-1.0-1.python2.3.i386.rpm

• python-curl-7.12.1-1.2.el4.rf.i386.rpm

• python-fpconst-0.7.2-3.rhel4.noarch.rpm

• SOAPpy-0.11.6-3.rhel4.noarch.rpm

• subversion-1.5.0-1.i386.rpm

• subversion-devel-1.5.0-1.i386.rpm

• subversion-perl-1.5.0-1.i386.rpm

• subversion-python-1.5.0-1.i386.rpm

• ZSI-1.7-1.noarch.rpm


• apr-0.9.12-2.x86_64.rpm

• apr-util-0.9.12-1.x86_64.rpm

• compat-postgresql-libs-4-2PGDG.rhel4.x86_64.rpm

• cvs-1.11.17-9.RHEL4.x86_64.rpm

• httpd-2.0.52-25.ent.x86_64.rpm

• jdk-1_5_0_12-linux-amd64.rpm

• mod_dav_svn-1.5.0-1.x86_64.rpm

• neon-0.27.2-1.x86_64.rpm

• neon-devel-0.27.2-1.x86_64.rpm

• postgresql-8.2.4-1PGDG.x86_64.rpm

• postgresql-docs-8.2.4-1PGDG.x86_64.rpm

• postgresql-libs-8.2.4-1PGDG.x86_64.rpm

• postgresql-server-8.2.4-1PGDG.x86_64.rpm

• python-chardet-1.0-1.python2.3.x86_64.rpm

• python-curl-7.12.1-1.2.el4.rf.x86_64.rpm



• subversion-1.5.0-1.x86_64.rpm

• subversion-devel-1.5.0-1.x86_64.rpm

• subversion-perl-1.5.0-1.x86_64.rpm

• subversion-python-1.5.0-1.x86_64.rpm

• subversion-tools-1.5.0-1.x86_64.rpm

• ZSI-1.7-1.noarch.rpm



• compat-postgresql-libs-4-1PGDG.rhel5.i686.rpm

• cvs-1.11.22-5.el5.i386.rpm

• httpd-2.2.3-6.el5.i386.rpm

• jdk-1_5_0_12-linux-i586.rpm

• mod_dav_svn-1.5.0-1.i386.rpm

• neon-0.27.2-1.i386.rpm

• neon-devel-0.27.2-1.i386.rpm

• postgresql-8.2.4-1PGDG.i686.rpm

• postgresql-docs-8.2.4-1PGDG.i686.rpm

• postgresql-libs-8.2.4-1PGDG.i686.rpm

• postgresql-server-8.2.4-1PGDG.i686.rpm

• python-chardet-1.0-1.python2.4.i386.rpm

• python-curl-7.15.5-1.2.el5.rf.i386.rpm



• subversion-1.5.0-1.i386.rpm

• subversion-devel-1.5.0-1.i386.rpm

• subversion-perl-1.5.0-1.i386.rpm

• subversion-python-1.5.0-1.i386.rpm

• ZSI-1.7-2.el5.mdsc.i386.rpm

CollabNet TeamForge 5.2 install scriptsThis is the minimum set of utilities that must be present for an installation of CollabNet TeamForge 5.2 to proceed.

• install.sh

• platform.py

• installer.py

• generate-site-options.sh

• environment_check.sh

• bootstrap-data.sh

• instance-set-install.sh

• tools.sh

• updater.sh

• upgrade-site.sh

• scripts/CEEInstallUtils.py

• scripts/CommandLine.py

• scripts/CommonUtils.py

• scripts/component.py

• scripts/Downloader.py

• scripts/generate-site-options.py

• scripts/__init__.py

• scripts/installer_util.py

• scripts/instance-set.py

• scripts/manifest.py

• scripts/Packager.py

• scripts/platform.sh

• scripts/ProcessPkgs.py

• scripts/RelengErrUtil.py


• scripts/system_check.sh

• scripts/upgrade.py

ScriptsSystem administrators can use these utilities to control the behavior of the application.

apache_watchdogThis script monitors the health of the site's Web server.

Usage

You can run this script from the command line as follows:

sudo [RUNTIME_DIR]/scripts/apache_watchdog

The script is run by a cron job every five minutes.

Overview

This script determines whether Apache is active by sending a lookup request. If Apache does not respond to the lookup request, thescript takes several actions.

• Logs a warning message in [LOG_DIR]/httpd/apache_watchdog.log.

• Takes a snapshot of the current state of the server.

• Logs the output of the snapshot to [LOG_DIR]/runtime/snapshot.log.

• Checks for and kills any stray Apache processes.

• Attempts to restart Apache.

Requests are sent every 10 seconds for six attempts. A final warning message is logged in the[LOG_DIR]/httpd/apache_watchdog.log file and the script exits if no response is received after the sixth attempt.

bb-check-apache.shThe bb-check-apache.sh script monitors the health of the Apache service every three to five minutes and reports its statusto Big Brother.

Location

<SITE_DIR>/runtime/scripts/

Status

The BigBrother UI shows a red or green status.

Red indicates that the Apache service is non-responsive. This status requires immediate attention.Red

Under normal operating conditions, when Apache is responsive, the status is green.Green

bb-check-jboss.shThe bb-check-jboss.sh script monitors the health of the JVM service every three minutes and reports its status to BigBrother.

Location



Status

BigBrother displays the status that the script reports.

Red indicates that the JBoss service is non-responsive. This status requires immediate attention.Red

Under normal operating conditions, when JBoss is responsive, the status is green.Green

bb-check-pgsql.shThe bb-check-pgsql.sh script monitors the health of the PostgreSQL database every three minutes and reports its status toBig Brother.

Location


Status


Red indicates that the PostgreSQL database is non-responsive. This status requires immediate attention.Red

Under normal operating conditions, when PostgreSQL is responsive, the status is green.Green

bb-check-tomcat.shThe bb-check-tomcat.sh script monitors the health of the source code management (SCM) integration server every threeminutes and reports its status to Big Brother.

Location


Status


Red indicates that the integration server is unresponsive. This status requires immediate attention.Red

Under normal operating conditions, when the integration server is responsive, the status is green.Green

bootstrap-data.shThe bootstrap-data.sh script prepares application and database data for new installations. Preparing application and databasedata is referred to as "bootstrapping" the data.

Overview

Important: This script is only for new installations. If you run it on a site that already has data, all data will be wiped.

This script resides in the <installation_source> directory and calls the wrapper-bootstrap-data.py scriptwhen run. The [log_file_directory]/runtime/bootstrap.log file is created when this script is run. Allsuccess and error messages from this script are written to this log file.

Usage

Run this script as follows:

cd <installation_source>

sudo ./bootstrap-data.sh -d <SITE_DIR>


./bootstrap-data.sh -d <SITE_DIR>

Example

The following command forces a bootstrap of the data, showing all actions on the screen:

sudo ./bootstrap-data.sh -n -F -V -d <SITE_DIR>

./bootstrap-data.sh -n -F -V -d <SITE_DIR>

Options

The following options are available for the bootstrap-data.sh script:

Specify installation directory. This argument is required.-d | --directory

Provides a list of all available options for this script.-h | --help

Runs the script in a non-interactive mode. The script will fail with an error message when usedwith this option if an existing [DATA_DIR] is located. You can use the -F option to forcebootstrapping on sites that have an existing [DATA_DIR].

-n | --non-interactive

This option is only valid when the -n option is used. This option forces the bootstrapping ofdata when a [DATA_DIR] exists.

-F | --force

Writes all script actions to the screen. Without this option the script runs silently and logsmessages to the [log_file_directory]/runtime/bootstrap.log file.

-V | --verbose

Do not show script output.-q | --quiet

Points to the site-options.conf configuration file for the site. This argument isoptional.

-f | --site-options=[filename]

Cluster location

This script runs on the application server machine.

The collabnet scriptRun this script to start or stop TeamForge, or to get the status of the application or a component.

Overview

You can use this script to start or stop the application as a whole or to start and stop an individual service. You can also use it todetermine the status of an individual service.

Important: On production sites, this script must be invoked by the root user.

Usage


sudo <SITE_DIR>/runtime/scripts/collabnet [--verbose|-V] [--service|-sserviceName] <command>

<SITE_DIR>/runtime/scripts/collabnet [--verbose|-V] [--service|-s serviceName]<command>

For example, the following command checks the status of the jboss component:

sudo <SITE_DIR>/runtime/scripts/collabnet -s jboss status

<SITE_DIR]/runtime/scripts/collabnet -s jboss status


Parameters

Action to perform. The supported commands are:Command

Starts the application / servicestart

Stops the application / servicestop

Provides the status of the service(s)status

Restarts the application / servicerestart

Prints this message and exits.help

Perform the command for the service serviceName-s | service serviceName

Print debug messagesverbose

-q | --quiet

Force option to perform the specifed operation forcefully-F | --force

To perform the operation silently without providing the output-S | --silent

Logging

collabnet writes entries to the following logs:

• log/runtime/service.log: The master service log.

• log/{service}/service.log: Log entries from starting up individual services end up in the service.log fileof the corresponding service log folder (e.g. log/apps/service.log)

environment_check.shThe environment_check.sh script verifies whether all environment packages required for installing CollabNet TeamForgeare present.

Overview

Use the environment_check.sh script to verify that you have all required environment packages for installing SourceForge.

Note: You may be prompted to manually remove any older packages identified on your system before running theinstall.sh script.

Usage

From the <INSTALLATION_SOURCE> directory, run this script as follows:

sudo ./environment_check.sh

./environment_check.sh

generate-site-options.shThe generate-site-options.sh script extracts the settings from a SourceForge 4.4 or 4.4 SP1 site and creates asite-options.conf file suitable for installing SourceForge 5.0.

Usage


generate-site-options.sh [-d <site_dir>] [-h] [-s]


Options

The generate-site-options.sh script has these options:

-d <site_dir>

Normally, this program uses /etc/sourceforge.properties to figure out the directory whereSFEE 4.4 or 4.4 SP1 is installed, but if the directory has been moved since install, you can specify itslocation.

-h

Print this usage summary

-s

Generate hosted version of site-options.conf (for CollabNet internal use only)

install.shThe install.sh script handles all operations related to installing and removing the application.

Options-r | --runtime

Create the runtime instance using the site configuration file

-R | --internalruntime

Create the internal runtime instance using the site configuration file

-F | --force

Force the operation that is performed wherever appropriate (eg. install/uninstall)

-i | --install

Install application packages

-u | --uninstall

Uninstall application packages

-S | --startnow

Start application services after completing the other operations (if possible)

-s | --startup

Start application services on reboot and start it now: equivalent to -I -S

-d | --directory type='str', argname='installation_base_dir',

Path where the site would get installed

-f | --siteoptionsfile

Path to the site configuration file (default: ./conf/site-options.conf)

-c | --conf-file

The environment configuration file (usually of the form environment-<platform>.conf), used to identifythe platform.

Note: This is not to be confused with the the site-options.conffile.

-I | --initscript

Start application services on reboot

-V | --verbose

Show all output in noninteractive mode

-E | --check_environment


Check if the system environment is suitable for this installation

-a | --all

Performs these operations in sequence - Install, create runtime and setup initscripts (equivalent to: -I-r -i)

-D | --debug

Displays traceback errors if any

-C | --cleanup

Stop/Kill the application processes, wipes out application packages and site directory.

Caution: THIS OPTION WILL WIPE OUT THE SITEDATA.

-n | --noninteractive

Used to run the installer in non-interactive mode

instance-set-install.shUse this script to install and remove instance sets from a SourceForge installation.

Overview

The instance-set-install.sh script takes these steps:

1. Verifies that the user invoking the script is the equivalent of a root user.

2. Checks the specified directory for the existence of a valid SourceForge installation.

3. If SourceForge is running, asks you to stop the services and then rerun the script.

4. Validates the feasibility of continuing with the process. For installations, checks for a previously installed instance on the server.For uninstalls, verifies that the instance set currently installed matches the manifest designated.

5. Installs or uninstalls the instance set.

6. Recreates the runtime environment. This will only occur if there is an existing runtime environment. If there is no existing runtimeenvironment this step is skipped.

Options

The instance installation script takes these options:

Location of the installed version of SourceForge-d | --directory

Note: This option is required.

Location of the manifest file-f | --file


Print this usage message and exit-h | --help

Alias for uninstall -- remove the instance-r | --rollback

A flag indicating a test run -- no changes-t | --test

Remove the instance-u | --uninstall

jboss_watchdogThis script monitors the health of the site's JBoss Java virtual machine.


Usage


sudo [RUNTIME_DIR]/scripts/jboss_watchdog


Overview

This script determines whether JBoss is active by sending a lookup request. If JBoss does not respond to the lookup request, the scripttakes several actions.

• Logs a warning message in [LOG_DIR]/apps/jboss_watchdog.log.



• Checks for and kills any stray jboss processes.

• Attempts to restart JBoss.

Requests are sent every 10 seconds for six attempts. A final warning message is logged in the[LOG_DIR]/apps/jboss_watchdog.log file and the script exits if no response is received after the sixth attempt.

pgsql_watchdogThis script monitors the health of the site's database server.

Usage


sudo [RUNTIME_DIR]/scripts/pgsql_watchdog


Overview

This script determines whether PostgreSQL is active by sending a lookup request. If PostgreSQL does not respond to the lookuprequest, the script takes several actions.

• Logs a warning message in [LOG_DIR]/pgsql/pgsql_watchdog.log on the server that is hosting the database.



• Checks for and kills any stray PostgreSQL processes.

• Attempts to restart PostgreSQL.

Requests are sent every 10 seconds for six attempts. A final warning message is logged in the[LOG_DIR]/pgsql/pgsql_watchdog.log file on the server that is hosting PostgreSQL, and the script exits if noresponse is received after the sixth attempt.

rotatelogs.plThis script rotates the current logs on a configured schedule. The rotated logs are archived and a new log file is opened.

Overview

The rotatelogs.pl script is located in the [RUNTIME_DIR]/scripts directory.

This script is automatically run as a cron job, triggered by the 05-rotatelogs.sh script. You can also run it manually ondemand.

• The script is responsible for rotating the log files. It runs at least once every 24 hours to archive the current log files in the[LOG_DIR].


• The rotatelogs.pl script closes the current log files in [LOGGING_DIR] and moves them to the [LOGGING_DIR_ARCHIVE]directory.

• After the files are rotated to the [LOG_DIR_ARCHIVE] directory, new log files are created in the [LOGGING_DIR] directory.

• Files in the [LOG_DIR_ARCHIVE] directory are compressed.

Usage


sudo <SITE_DIR>/runtime/scripts/rotatelogs.pl

Options

These options are available:

This option displays the help information for the script.-h | --help

This option prints the version of the script.-v | --version

This option provides debugging information.-d | --debug

When this option is used, only the non-empty log files are rotated.-n | --non-zero

This option supports debugging by displaying what the script would do, but without actuallydoing it.

-p | --noop

snapshot.pyUse this script as a debugging tool to troubleshoot system errors. It records a snapshot of the current state of the machine.

Overview

Run this script manually to generate debugging information before restarting the instance.

Usage


sudo <SITE_DIR>/runtime/scripts/snapshot.py<SITE_DIR>/runtime/scripts/snapshot.py

Options

The following options are available for the snapshot.py script:

Provides information on using the script.-h|--help

An arbitrary command whose output should be placed in the generated log file. For example, you canhave snapshot.py execute the lsof command like this:

--extra '/usr/sbin/lsof -n -P -b -i -U'

--extra

Enclose commands with options in quotes.

Provides output on the actions performed by the script.-v|--verbose

Note: The output from snapshot.py is written to a log file in the [LOG_DIR]/runtime directory. Use the output(snapshot.log) to troubleshoot any system or CollabNet related errors.

Cluster location

Important: The snapshot.py script generates a log file for the node on which it is run. When a CollabNet site is deployedon a cluster and you need information to troubleshoot problems, it is recommended that you run this script on all the nodes.


tomcat_watchdogThis script monitors the health of the Java virtual machine that handles the integration of external services, such as source control.

Usage


sudo [RUNTIME_DIR]/scripts/tomcat_watchdog


Overview

This script determines whether Tomcat is active by sending a lookup request. If Tomcat does not respond to the lookup request, thescript takes several actions.

• Logs a warning message in [LOG_DIR]/integration/tomcat_watchdog.log on the server that is hostingthe integration.



• Checks for and kills any stray Tomcat processes.

• Attempts to restart Tomcat.

Requests are sent every 10 seconds for six attempts. If no response is received after the sixth attempt, final warning message is loggedin the [LOG_DIR]/integration/tomcat_watchdog.log file on the server that is hosting the integration, and thescript exits.

upgrade-site.shWith this script, you can perform a cumulative patch upgrade or downgrade on a running instance.

Overview

This is a wrapper for the upgrade.py script.

The script verifies the following:

• The user invoking the script is the equivalent of a root user.

• The specified directory has a valid SourceForge installation.

It performs the following actions depending on the options specified:

• Displays a summary of what would happen during the patch installation.

• Downgrades or upgrades the site to the specified patch level.

• Reverts the site to the previous patch level it was at, before the current patch was applied.

• Downgrades the patch level on the site by one.

• Starts SourceForge after successfully installing the patch.

• Allows a test "dry run" of the patch installation.

Usage


sudo ./upgrade-site.sh -d <INSTALL_DIR> [-r] [-u] [-t] [-l level] [-f file][-n] [-h] [-V] [v]

./upgrade-site.sh -d <INSTALL_DIR> [-r] [-u] [-t] [-l level] [-f file] [-n][-h] [-V] [v]


Example

To perform a component upgrade from a base SourceForge installation (patch level 0) to patch level 2, use this command:

sudo ./upgrade-site.sh -t -d /opt/collabnet/teamforge -l 2

Options

The manifest file with the appropriate information for this upgrade.-f [manifest] | --file [manifest]

The directory where the application is installed.-d [INSTALLATION_DIR] |--directory [INSTALLATION_DIR]


Rolls back the previous (most recently applied) patch. For example, if you upgrade the sitefrom patch level 1 to patch level 4, and then run upgrade-site.sh with this option,the resulting patch level on the site is patch 1.

-r | --rollback

The patch level to which the SourceForge site must be upgraded (or downgraded).-l [level] | --level [level]

Displays script output including traceback errors. If this option is not used, the script displayserror messages but not the actual traceback errors.

-V | --verbose

Displays the script version.-v | --version

Non-interactive mode.-n | --noninteractive

Displays a summary of the actions that will be performed as part of the upgrade ordowngrade. Use this option to view a description of what would take place during a patchupgrade (or downgrade) before you actually apply the patch.

-t | --testrun

Note: You must use this option along with the l, r, u, or f options.

Decrements the patch level on the site by one. For example, if you upgrade the site frompatch level 1 to patch level 4, and then run upgrade-site.sh with this option, theresulting patch level on the site is patch 3.

-u | --uninstall

Prints usage information.-h | --help

Note: Do not use the following combinations of options in the same command:

• -u (uninstall) with -r (rollback)

• -f (manifest) with -l (level)

• any combination of -u, -r, -l, -f

If you do, the script exits with a corresponding error message.

Log filesSystem administrators can use logs to debug problems and ensure that the application is performing to expectations.

JBoss logsThe JBoss application server writes several different logs under the <INSTALL_DIR>/log directory.

Lgs the JBoss startup and shut down notifications. This log is overwritten each time JBoss is(re)started.

boot.log


The Records access to the application from a remote host, similar to the Apache access_log. Thislog is rotated each day, and the files have a date stamp appended to their name, such aslocalhost_access2004-11-26.log.

localhost_access

Logs all the activities of the application server, including any exceptions. This log is the bestplace to begin debugging CollabNet TeamForge 5.2 server error exception ids (exid).

server.log

Records when new sessions are created. This log is overwritten each time JBoss is (re)started.session-info.log

Records CollabNet TeamForge 5.2-specific actions, including some SQL queries that are sentto the backend database. This log is rotated each time it reaches 100MB in size. When rotated

vamessages.log

the older files have a number appended to the end, such as vamessages.log.1 andvamessages.log.2.

Oracle loggingThe most important Oracle log is the alert log, which is found in$ORACLE_HOME/admin/$SID/bdump/alert_$SID.log .

An Oracle database performs logging on a wide array of functionality. The majority of the logs that are generated are stored under$ORACLE_HOME/admin/$SID/. Many logs are stored under this directory hierarchy, but alert is the most important. Thislog records all database activity, including serious problems.

The alert log is not rotated or overwritten, and can become quite large over time, especially on an active database.

Additional logs are created under the same directory hierarchy, for specific incidents. If a problem is recorded in the alert log, theother logs should be inspected for additional details.

For more information, as well as support in the maintenance of an Oracle database, contact Oracle Support or Oracle's Metalink site.

SCM (CVS, Subversion, and Perforce) logsSoftware configuration management (SCM) servers generate several logs from the CollabNet TeamForge 5.2-managed integrationserver in <install_dir>/log. Not all of them are unique to CollabNet TeamForge 5.2; however, in the interest of completenessthey are all documented here.

This log contains information on the startup and runtime activities of the Tomcat server.This log is not rotated, nor is it overwritten, and is appended continuously over the lifetimeof the server.

catalina.out

This log contains a record of CVS or Subversion browsing URL construction. When auser attempts to browse a CVS or Subversion repository in his or her web browser, the

localhost_log

URL construction process is documented in this log. This log is rotated for each date thatthere is activity.

This log contains a record of the initial startup and deployment of the managed integrationserver. A new date stamped log is generated each time the integration server is started.

localhost_admin_log

This log contains information on the operations that are being executed by the managedintegration server. This log is stored in <install_dir>/log.

vaexternalintegration.log

Email logsBoth the CollabNet TeamForge 5.2 email and search backends are managed from a parent daemon known as Phoenix. If the mailbackend is not operating properly, the first troubleshooting step is to check the phoenix.log to see if it encountered difficulties startingup.


Overview

The Phoenix daemon logs its activities to the phoenix.log file, which is stored underinstall_dir/james/james-2.2.0/logs. This log is overwritten each time Phoenix is (re)started. Phoenix is run aspart of the CollabNet TeamForge 5.2 standalone server init script.

CollabNet TeamForge 5.2 email is handled by the JAMES server. JAMES logs all of its activities underinstall_dir/james/james-2.2.0/apps/james/logs. A new log is created for each date when there is activity,and additional logs are created if james is restarted on a date when there is activity. The date is embedded in the log name (such asjames-2005-04-28-01-00.log).

Active logs

Sixteen different logs are created by james for different components of its functionality. This topic describes only the ones that areused actively by CollabNet TeamForge 5.2.

The James log records the overall mail handling behavior of the James server.james-$date.log

The mailet log records how each piece of email is handled. If there is a mail deliveryproblem, this log is the best place to begin investigation.

mailet-$date.log

The mailstore log records the behavior of mail spools, and the storage of mail. This logshould normally not contain errors unless James is unable to write or read mail to or fromthe file system.

mailstore-$date.log

The smtpserver log records all inbound mail handling results. If email to discussion forumsis not posting, or is getting rejected, this log would be the best place to begin investigation.

smtpserver-$date.log

The spoolmanager log records the processing of mail spools. This log could be of valuein troubleshooting mail delivery or handling problems.

spoolmanager-$date.log

Search logsBoth the CollabNet TeamForge 5.2 search and email backends are managed from a parent daemon known as Phoenix. If the searchbackend is not operating properly, the first troubleshooting step is to check the phoenix.log file to see if it encountered difficultiesstarting up.

The Phoenix daemon logs its activities to the phoenix.log file, which is stored underinstall_dir/james/james-2.2.0/logs. This log is overwritten each time Phoenix is (re)started.

Phoenix is run as part of the CollabNet TeamForge 5.2 standalone server init script.

Once started successfully, the search server waits for new content to be indexed or searches to be performed. The search server logsits activities under install_dir/james/james-2.2.0/apps/search/logs. The logs that are created are allnamed default with the date stamp appended to them (such as default-20041126.log). A new log is created for eachdate that there is indexing activity.

If the search server is not running, or expected search results are not being provided, the default log is the best place to investigatefurther.

Configuration filesEdit these configuration files to get the behavior you want.

The patch manifest fileThe patch manifest file contains all the information about the patch.


Overview

The manifest file for each patch is named manifest-[patch#]. The manifest file is a text file containing a set of configurationtokens.

Note: The first patch is named manifest-1.

Contents

The manifest file contains these tokens:

The patch level which this patch provides.PATCH_LEVEL

Note: The PATCH_LEVEL value is used (along with information in[DISTRIBUTION_DIR]/version/core-version.txt ) to fill in[DISTRIBUTION_DIR]/conf/patches with the current release and patchlevel. If [DISTRIBUTION_DIR]/conf/patches does not exist, it is created.

A description of the patch.PATCH_DESCRIPTION

A list of RPMs to uninstall (using relative paths, comma separated).UNINSTALL_LIST

A list of RPMs to install (using relative paths, comma separated).INSTALL_LIST

Note: Comments in the manifest file are identified by a leading hash (#).

login-config.xmlThis is the sample application-policy block that you can copy into your login-config.xml file to support LDAPauthentication.

Notes

Replace the default application-policy block of the login-config.xml file with this code, then make the modificationsspecified in Set up LDAP integration for the CollabNet TeamForge 5.2 serverFollow these steps to convert your CollabNet TeamForge5.2 installation to authenticate against your corporate LDAP server. . Option values that must be modified are highlighted in bold.

• When the username is passed to the login module from SourceForge, it is translated into a DN for lookup on the LDAP server.The DN that is sent to the LDAP server is <principalDNPrefix><username><principalDNSuffix>.

• In this example application-policy block, the username is stored in the People organizational unit in thedev.sf.net domain. This is represented as ,ou=People,dc=dev,dc=sf,dc=net

• This example contains a single login-module section. If you are authenticating against multiple LDAP servers, include onelogin-module section per LDAP server, with the required option values modified appropriately for each one. If the sameusername exists in more than one LDAP server, the instance on the first LDAP server will be used.

Sample code

<application-policy name="SourceForge"> <authentication> <login-module code="org.jboss.security.auth.spi.LdapLoginModule" flag="sufficient" > <module-option name="allowEmptyPasswords">false</module-option> <module-option name="principalDNPrefix">uid=</module-option> <module-option name="principalDNSuffix">,ou=People,dc=dev,dc=sf,dc=net</module-option> <module-option name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</module-option> <module-option name="java.naming.provider.url">ldap://util.dev.sf.net:389/</module-option> <module-option name="java.naming.security.authentication">simple</module-option>


</login-module> </authentication> </application-policy>

httpd.confThese are the changes you must make to the /etc/httpd/conf/httpd.conf file.

### SFEE configuration### mod_deflate for improving performanceDeflateFilterNote Input instreamDeflateFilterNote Output outstreamDeflateFilterNote Ratio ratioLogFormat '"%r" %{outstream}n/%{instream}n {%{ratio}n%%}' deflate<Location /> AddOutputFilterByType DEFLATE text/html # Netscape 4.x has some problems... BrowserMatch ^Mozilla/4 gzip-only-text/html # Netscape 4.06-4.08 have some more problems BrowserMatch ^Mozilla/4\.0[678] no-gzip# NOTE: Due to a bug in mod_setenvif up to Apache 2.0.48 # the above regex won't work. You can use the following # workaround to get the desired effect: BrowserMatch \bMSI[E] no-gzip # Don't compress images SetEnvIfNoCase Request_URI \ \.(?:gif|jpe?g|png)$ no-gzip dont-vary # Make sure proxies don't deliver the wrong content Header append Vary User-Agent env=!dont-vary</Location>

# mod_expires for even better performanceExpiresActive OnExpiresDefault "access plus 0 seconds"ExpiresByType image/gif "access plus 1 days"ExpiresByType image/jpeg "access plus 1 days"ExpiresByType image/png "access plus 1 days"ExpiresByType text/css "access plus 7 days"ExpiresByType text/javascript "access plus 7 days"ExpiresByType application/x-javascript "access plus 7 days"ExpiresByType image/x-icon "access plus 7 days"

# SFEE rewrites to make the app 'live' on port 80 and not 8080RewriteEngine onRewriteLog logs/rewriteRewriteLogLevel 1# Added to supress http trace for security reasonsRewriteCond %{REQUEST_METHOD} ^TRACERewriteRule .* - [F]# make '/' redirect to SFEERewriteRule ^/$ http://%{SERVER_NAME}/sf/ [R]# now pass the URL to the actual SFEE application serverRewriteRule ^/sf$ http://localhost:8080/sf [P]RewriteRule ^/sf/(.*) http://localhost:8080/sf/$1 [P]

# Pass ScmListener SOAP requestsRewriteCond %{REQUEST_URI} ^/sf-soap/services/ScmListenerRewriteRule ^/sf-soap/(.*) http://localhost:8080/sf-soap/$1 [P]#Pass all non-listeners SOAP requests. Delete next 4 lines if you don't use SOAP APIs.RewriteCond %{REQUEST_URI} !^/sf-soap/services/[^/]*Listener


RewriteRule ^/sf-soap/(.*) http://localhost:8080/sf-soap/$1 [P]RewriteRule ^/sf-soap42/(.*) http://localhost:8080/sf-soap42/$1 [P]RewriteRule ^/sf-soap43/(.*) http://localhost:8080/sf-soap43/$1 [P]

# route SCM requests to the SFEE integration serverRewriteCond %{REQUEST_URI} !^/integration/servicesRewriteCond %{REQUEST_URI} !^/integration/servletRewriteRule ^/integration/(.*) http://localhost:7080/integration/$1 [P]ProxyPassReverse / http://localhost:8080/ProxyPassReverse / http://localhost:7080/### end SFEE configuration##

iptablesThis is the /etc/sysconfig/iptables output that will enforce the recommended security configuration.

# Firewall configuration written by redhat-config-securitylevel# Manual customization of this file is not recommended.*filter:INPUT ACCEPT [0:0]:FORWARD ACCEPT [0:0]:OUTPUT ACCEPT [0:0]:RH-Firewall-1-INPUT - [0:0]-A INPUT -j RH-Firewall-1-INPUT-A FORWARD -j RH-Firewall-1-INPUT-A RH-Firewall-1-INPUT -i lo -j ACCEPT-A RH-Firewall-1-INPUT -p icmp --icmp-type any -j ACCEPT-A RH-Firewall-1-INPUT -p 50 -j ACCEPT-A RH-Firewall-1-INPUT -p 51 -j ACCEPT-A RH-Firewall-1-INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 443 -j ACCEPT-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 25 -j ACCEPT-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 80 -j ACCEPT-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 22 -j ACCEPT-A RH-Firewall-1-INPUT -j REJECT --reject-with icmp-host-prohibitedCOMMIT

The instance set manifest fileThe instance set manifest file contains all relevant information for the instance. The manifest file is a text file containing tokens whosevalues you can set.

Overview

The manifest file for each patch is named [instance name]-manifest.

Tokens

The manifest file contains the following tokens:

The name of the instance package set. The instance set name includes the name ofthe instance and the version of SourceForge and minimum patch number required.

For instance, an instance set name of "netbeansinst-5.0.2.1" indicates that thenetbeansinst package set and can only be installed onto a server with SourceForge

INSTANCE_SET_NAME

version 5.0 with the second patch installed and that this is the first version of thisinstance. The INSTANCE_SET_NAME is used to populate the [DIST_DIR]/conf/instance file with the current release and patch level.


A list of all the packages included in the instance set. The packages include the nameof the instance package with the appropriate version number. For example:

INSTANCE_SET_PACKAGES

SCAST-netbeansinst-1.0-0-2.6.0.212.2.i386.rpm is the name of the netbeans instancepackage.

The instance is qualified to run only with the version of SourceForge indicated here.For instance if the value for this token is "5.0.2" this instance is qualified to work

REQUIRED_SOURCEFORGE_VERSION

only with SourceForge version 5.0.2 with all patches up to and including the secondinstalled.

Indicates the version of the instance.RELEASE_ID

Note: You may see comments in the manifest file. Comments are identified by a leading hash (#).

Sample instance manifest fileThe instance manifest is customized for the operating system it runs on.

This is a sample manifest file:

INSTANCE_SET_NAME=sampleinst-1.0-5.0.0.0.177REQUIRED_APPLICATION_VERSION=5.0.0.0.177RELEASE_ID=1INSTANCE_SET_PACKAGES=CN-sampleinst-1.0-5.0.0.0.177.i386.rpm

Reference information about TeamForge Lab ManagementHere are some sample files and other resources to help you figure out what is what in this CollabNet product.

Reference information about TeamForge Lab ManagementHere are some sample files and other resources to help you figure out what is what in this CollabNet product.

Log filesSystem administrators can use logs to debug problems and ensure that the application is performing to expectations.Project Build Library audit logYou can use this screen to view the complete list of actions performed in the Project Build Library.

Contents

Information about the following types of actions is displayed in this screen:

• Change a File Description

• Create a Directory

• Delete a File or Directory

• Download a File

• Move a File or Directory

• Upload a File

Note: The value displayed in the Event field is the value passed in the --comment parameter from the Project Build Libraryclient.

Getting there

On the project home page, click Build Library in the left navigation bar and select the Audit Log tab.


Access

This screen is accessible for all users who have at least the view permission for the project.

Profile audit logYou can use this screen to view the complete list of actions performed on a profile.

Getting there

On the Profile Library screen, click the Audit Log tab.

Access

This screen is accessible for all users who have at least the view permission for the project to which the profile is allowed.

x

Example

When a user updates any of the profile fields on the Profile Admin screen, the following details are displayed in this screen:

• The old value for the field.

• The new value for the field.

• The name of user who updated the field.

• The time when the change occurred.

User Audit LogYou can use this screen to view the list of actions performed by the user in the TeamForge Lab Management system.

For example, when a user logs into the web interface of the TeamForge Lab Management system, the eventis displayed in this screen.

AccessThis screen is accessible to all users who have at least the Domain Administrator role.

Getting there

On the Administration tab, click User Audit Logs in the left navigation bar.

Host audit logYou can use this screen to view the complete list of actions performed on a host.

Getting there

On the TeamForge Lab Management Host home page, click the Audit log tab.

Access

This screen is accessible for all users who have at least the view permission for the project to which the host is assigned.

Example

When the IP address for the host is changed, the following details are displayed in this screen:

• The old IP address.

• The new IP address.

• The name of user who changed the IP address.

• The time when the change occurred.

Project audit logThe Project audit log screen shows the complete list of changes applied to a project.


Getting there

On the TeamForge Lab Management Project home page, click Audit Logs in the left navigation bar.

Access

This screen is accessible for all users who have at least the view permission for the project.

Example

When a profile is added to the list of buildable profiles for this project, the following information appears on this screen:

• The action that was taken.

• The user who performed the change.

• The time when this change occurred.

ScriptsSystem administrators can use these utilities to control the behavior of the application.pbl.pyThe pbl.py utility enables you to upload files to the Project Build Library and perform various operations on them.

Options

Print out a help message and exit.--help|-h

Your TeamForge Lab Management login name. Required for all upload operations.--api-user|-u username

Your TeamForge Lab Management API key. Required for all upload operations.--api-key|-k key

The URL to the TeamForge Lab Management API's. Will generally behttps://$external_host/cubit_api/1. Required for all uploadoperations.

--api-url|-l url

Print out a comment on this operation. The comment is always optional. The commentstring will be logged in the audit log, but is not recorded in the PBL. For example, if you

--comment|-c "yourcomment"

are deleting some files, you might want to use a comment to explain why you were deletingthose files, for future auditing purposes.

Print out more detail on what the pbl.py is doing.--verbose|-v

If this option is not specified, the pbl.py client reads in the XML returned from theserver and presents the results to you in nicely formatted text. If you'd like to instead seethe raw XML returned from the server, select this option.

--xml-server-output|--xml

As a convenience, the pbl.py function caches the value of the --api-user and--api-key parameters in your home directory, in a subdirectory named

--no-auth-cache

.TeamForge Lab Management , the first time a successful authentication isperformed against the server. This is analogous to the Subversion client's use of the.subversion directory to store authentication credentials. Selecting the--no-auth-cache option turns off this caching.

The TeamForge Lab Management project in which the file you are operating on is located.--project|p projname

The visibility type of the file, either pub (the file is in the public area of the PBL) orpriv (the file is in the private area of the PBL).

--type|t {pub|priv}

The remote path on the server, excluding the base directory, the project, and the visibilitytype. Examples are below.

--remotepath|r path


Documents

CollabNet TeamForge 5