System Administrator's Guide...ADMINISTRATOR 'S GUIDE iii Table of Contents 1 INTRODUCTION...

System

Administrator's Guide

Version 2.2.1

This edition refers to Version 2.2.1 of Black Duck™ Code Sight.

This document created or updated November 13, 2012.

Please send your comments and suggestions to:

Black Duck Software, Incorporated

8 New England Executive Park

Burlington, MA – 01803 USA

Copyright © 2009-2012 by Black Duck Software, Inc.

All rights reserved. All use of this documentation is subject to the license agreement between Black Duck Software, Inc. and the licensee. No part of the contents of this document or help system may be reproduced or transmitted in any form or by any means without the prior written permission of Black Duck Software, Inc.

Black Duck, Know Your Code and the Black Duck logo are registered trademarks of Black Duck Software, Inc. in the United States and other jurisdictions. Black Duck Suite, Black Duck Code Center, Black Duck Code Sight, Black Duck Protex, Black Duck Export, Black Duck Transact, and Koders are trademarks of Black Duck Software, Inc. All other trademarks or registered trademarks are the sole property of their respective owners.

iii ADMINISTR ATOR'S GUIDE

Table of Contents

1 INTRODUCTION ................................................................................. 1

1.1 ARCHITECTURE .................................................................................. 1 1.2 CODE SIGHT PROCESS ........................................................................... 1 1.3 WHAT GETS INDEXED? ........................................................................... 2 1.4 SUPPORTED SOURCE CONTROL MANAGEMENT CLIENTS........................................... 2

2 USER ACCOUNTS ............................................................................... 3

2.1 CREATING A NEW USER ACCOUNT ............................................................... 3 2.2 USING LDAP OR ACTIVE DIRECTORY AUTHENTICATION .......................................... 5 2.3 PRECONFIGURED USER ROLES ................................................................... 5 2.4 PERMISSION MATRIX ............................................................................. 6

3 CREATING PROJECTS .......................................................................... 7

3.1 ABOUT PROJECTS AND REPOSITORIES ............................................................ 7 3.2 CREATING A PROJECT ........................................................................... 8 3.3 MODIFYING A PROJECT .......................................................................... 9

3.3.1 Adding Source Code Locations ........................................................ 9 3.3.2 Set the Indexing Schedule for a Project ............................................. 9 3.3.3 Adding Team Members to a Project ................................................. 10

3.4 DELETING A PROJECT ........................................................................... 11 3.5 INDEXING PROJECTS ............................................................................ 11

3.5.1 Exclude a Project from Indexing or Searching .................................... 11 3.5.2 Project History .......................................................................... 12

3.6 CONFIGURING SOURCE CODE LOCATIONS ....................................................... 12 3.6.1 SCM Repository Configurations ....................................................... 12 3.6.2 Connection Strings ..................................................................... 12 3.6.3 File System Adapter .................................................................... 12 3.6.4 Zip Archive Adapter .................................................................... 13 3.6.5 Sample Open Source Connection Strings ........................................... 14 3.6.6 Sample Connection Strings for Commercial Products ............................ 16

4 PRODUCT CONFIGURATION ................................................................ 19

4.1 INDEX SETTINGS ................................................................................ 19 4.1.1 Creating a Global Schedule ........................................................... 19 4.1.2 Ignoring Files and Directories ........................................................ 20

4.2 SCM SETTINGS ................................................................................. 21 4.3 MAIL SETTINGS ................................................................................. 21 4.4 PROXY SETTINGS ............................................................................... 22 4.5 UPDATE STATUS ................................................................................ 22 4.6 PRODUCT REGISTRATION ....................................................................... 23

5 SYSTEM CONFIGURATION ................................................................... 25

5.1 DISK SPACE REQUIREMENTS AND USAGE ........................................................ 25 5.2 STARTUP CONFIGURATION AND LOG FILES ...................................................... 25 5.3 STOPPING AND STARTING THE TOMCAT SERVER ................................................. 26 5.4 SETTING UP FOR SSL ENCRYPTION .............................................................. 30 5.5 BACKING UP THE CODE SIGHT DATABASE ....................................................... 35

5.5.1 Code Sight Database Name ........................................................... 36 5.5.2 Back Up Procedure - Linux ............................................................ 36

iv TABLE OF CONTENTS

5.5.3 Back Up Procedure - Windows ....................................................... 36 5.6 RESTORING THE CODE SIGHT DATABASE ........................................................ 38

APPENDIX A—DATA GATHERED BY CODE SIGHT .............................................. 43

APPENDIX B —USING AND CONFIGURING LDAP OR ACTIVE DIRECTORY ................. 45

B.1 HOW DOES IT WORK? ........................................................................... 45 B.2 CONFIGURING CODE SIGHT TO VALIDATE USING LDAP OR ACTIVE DIRECTORY ................. 45 B.3 IMPORTING AND SYNCHRONIZING USERS ........................................................ 48 B.4 GRANTING ROLES TO GROUPS OF USERS ........................................................ 49 B.5 LDAP CONFIGURATION EXAMPLES .............................................................. 51

PREFACE

Preface

TARGET AUDIENCE This manual is intended for the developer responsible for using and configuring Black Duck Code Sight.

Most of the setup described in this book is done using the Admin section of the Code Sight interface. You must log in to Code Sight using an account with the appropriate role to access this.

RELATED DOCUMENTS The documentation for Code Sight is included in the top-level directory of the installation media. It consists of:

Title File Description

System Administrator's Guide AdminGuide.pdf Administrative and Configuration tasks.

User's Guide UserGuide.pdf Description of how to use the Code Sight search web page. This is available from a link on the search page.

Release Notes RelNotes.pdf Description of what has changed from the previous release.

Installation Guide InstallationGuide.pdf Detailed installation instructions for Code Sight.

Note: After installation, the printable books are located in C:\Program Files\Black Duck Software\CodeSight\doc. They are also available from links in the online help.

CUSTOMER SUPPORT There are three versions of Code Sight available, differentiated by license:

A free unregistered version, which allows indexing of 200k lines of code.

A free registered version with a trial license with limits set forth at http://www.blackducksoftware.com/go/codesight_additional_terms. Support for the free versions is provided using an online support forum: http://www.blackducksoftware.com/code-sight/support/forum/

An enterprise version, which allows for potentially unlimited indexing (limited per your license agreement). Support for the enterprise edition is provided through the forum and the regular Black Duck Technical Support channels:

Email: [email protected]

Phone: +1 781.891.5100, ext. 5

Fax: +1 781.891.5145

http://www.blackducksoftware.com/go/codesight_additional_terms

http://www.blackducksoftware.com/code-sight/support/forum/

mailto:[email protected]?subject=Help%20with%20Black%20Duck%20Code%20Center%20Installation

vi INTRODUCTI ON

This page is intentionally blank.

INTRODUCTION

1 INTRODUCTION

A significant portion of application development involves a process of find, copy, paste, and integrate. This process can be greatly accelerated when you can find and download existing source code that has already been debugged, tested, and approved. Code Sight makes it easy for software developers to find code in source code repositories that they have access to. Once you have found an interesting file or snippet, download it for use in a new project.

Tip: Code Sight is intended to work with your company’s repositories and local directories. While you could also crawl and index any open source projects you found on the web, if you are interested in doing this you should check out Black Duck Ohloh Code. This is a free, hosted version of the Code Sight search engine with an index of billions of lines open source code.

1.1 Architecture

Black Duck Code Sight consists of the following elements:

• An HTML-based GUI where administrators define projects and their source locations, manage user access, and schedule recrawls.

• An HTML interface for public or named-user searching within your projects. When you find what you are looking for, you can download the file.

• A backend database containing local copies of the files downloaded from your repositories. The database has an index built by examining those files specifically for source content.

1.2 Code Sight Process

The basic process of using Code Sight is as follows:

1. Install Code Sight and any source control management (SCM) clients you need to access your repositories.

2. Log into Code Sight as an administrator and create a project. The project definition includes connection strings, which tell Code Sight how to access your code from one or more SCM repositories.

3. Set up a schedule of how often Code Sight should revisit your project to look for new or updated files.

4. Code Sight automatically examines the projects and publishes an index.

5. All users can then search the code in your projects using the search page (http://<CodeSightServer>).

1

http://code.ohloh.net/

2 INTRODUCTI ON

1.3 What Gets Indexed?

As Code Sight examines your projects, it indexes the following types of files:

ActionScript Ada ASP ASP.NET Assembler

Boo C C# C++ Cobol

ColdFusion Delphi Eiffel Erlang Fortran

F# Groovy Haskell Java JavaScript

JSP Lisp Lua Mathematica Matlab

Modula ObjectiveC Ocaml Perl PHP

Prolog Python REBOL Rexx Ruby

Scheme Smalltalk SQL Tcl VB

VB.NET Xml

For C, C++, C#, Java, JavaScript, Ruby, and Python sources, Code Sight provides advanced parsing. This allows filtering to definitions, and provides a special outline view. For the other languages in this table, Code Sight provides syntax highlighting where applicable.

Other non-source file types, including .log and .html, are also available for basic searching, but they are not parsed and indexed for source content.

1.4 Supported Source Control Management Clients

• Code Sight supports the following open source and commercial SCM clients:

AccuRev Bazaar Borland StarTeam CVS

Git IBM Clearcase Mercurial Microsoft Team Foundation Server

Microsoft Visual SourceSafe Perforce Subversion Zip

USER ACCOUNTS

2 USER ACCOUNTS

Depending on your company policy, people using Code Sight just for searching may or may not need user accounts. If desired, you can configure each project individually such that only authorized users can access its files.

Code Sight is preconfigured with a set of roles of varying permission levels that can be assigned to a user account. The access permissions associated with these roles can be changed, or you can create customized roles and assign them to users as appropriate for your group. Users can also have multiple roles assigned to them to give expanded access when needed.

Roles are assigned based on a scope of: System-wide or Project-level.

2.1 Creating a New User Account Note: Code Sight includes a default overall system administrator's account called, sysadmin. The default password is “blackduck”, but we recommend changing this immediately after installation. This account cannot be deleted or disabled, and can be used to add all of the other user accounts you will need. If you are using an LDAP server, please see Appendix B —Using and Configuring LDAP or Active Directory.

A user with Administrator privileges can create new user accounts. Each account includes descriptive information about its owner. Note that the account information does not indicate what project the person is working on. That kind of information is considered the user's role, and is defined in a subsequent step.

To create a new user account, go to Admin Users Create User.

The following table shows the characteristics that can be set for a user account. Only the username and password fields are required.

Table 1 User Account Fields

Characteristic Description

Username A unique name for this person to use when logging in. The name is not case-sensitive. The name is attached to history records of the user's actions within Code Sight.

Password Passwords are case-sensitive, and cannot be blank. They do not expire.

Password Confirmation This field needs to match the password entered above.

First Name The first and last names, and job title are only displayed in the Users section. These attributes are useful when you are adding users to a group and you need to know who a person is.

Last Name (see above)

Email Address The email address is useful as a reference. It is not currently used within the product.

2

4 PRODUCT CONFIGUR ATI ON

Job Title The title is shown on the list of users and is useful as a reference. It is not currently used anywhere else within the product.

Phone The phone number is useful as a reference. It is not currently used within the product.

Location The location is shown on the list of users and is useful as a reference. It is not currently used anywhere else within the product.

Active An account must be set to "active" to enable logins.

Figure 1 Creating a New User Account

After you create an account, you need to add roles to it that permit access to projects and repositories. Select the user from the table at the top of the page, and then click the Roles subtab in the lower frame.

Note: Any time you change a user's role, they need to log out and log back in again for the change to take effect.

Figure 2 New User Account with No Roles

Next, click either the Add Overall Role or Add Project Role button. For a project-specific role, you must indicate both the role and the project name.

5 BL ACK DUCK CODE SIGHT ADMINISTR ATOR’S GUIDE

Figure 3 Adding a Project Role to a User

2.2 Using LDAP or Active Directory Authentication

Code Sight supports authentication using its own standard username and password scheme. It also supports using LDAP or Active Directory.

See Appendix B —Using and Configuring LDAP or Active Directory for details on configuring this feature.

2.3 Preconfigured User Roles

Code Sight includes several preconfigured roles that you can assign to user accounts on your system. Typically, users have distinct needs depending on their project assignments, and therefore you can assign the appropriate multiple roles to each user.

Overall roles are applicable throughout Code Sight. Project-specific roles apply only to an individual project. The pre-configured roles are locked, and cannot be edited or deleted.

You may want to create new, custom roles with different combinations of permissions. If you create a custom role with fewer permissions than the default roles, be sure to check the table in Section 2.4: Permission Matrix to make sure you do not leave any "holes" that are not covered by a role. Many screens within Code Sight are tied to various permissions, and if you turn these permissions off, you cannot see the screens. For example, if you remove "read user management configuration data" from your own role, you cannot see the User section. In that case, you would not be able to visit the Admin Users Roles page to turn the permission back on.

In general:

• if you have delete access, you should also have read, update, and create

• if you have create access, you should also have read and update

• if you have update access, you should also have read

• read access can stand alone


2.4 Permission Matrix Table 2: Permission Matrix

Project Specific Roles

Overall Role

This table shows the combinations of permissions in the pre-configured roles.

Inde

xer

Proj

ect

Sear

cher

Adm

inis

trat

or

Read registration settings X

Change registration settings X

Read user-management configuration data X X

Update user-management configuration data X

Create user management configuration data X

Delete user management configuration data X

Access the Admin area of Code Sight X X

Read application settings X X

Change application settings X X

Create a project X X

Start/stop the index engine X X

Publish the index of a project X X

See the team members on a project X X

Assign team members to a project X X

Search the code of a project X X X

Read project data X X

Update project data X X

Delete a project X X

Index a project X X

Schedule indexing for a project X X

Show/hide a project X X

Most of the permissions are quite specific, and allow access to individual controls within Code Sight .

One of the more powerful permissions is the ability to create user management configuration data. This permission allows you access such as creating users and giving them roles. This should only be granted to System Administrators.

REPOSITORIES AND PROJECTS

3 CREATING PROJECTS

In order for users to be able to search your code, you must configure Code Sight to know where your source files are, and how it can access them. The basic entity within Code Sight is the Project. A project describes the location of your sources, who can access them, and how often the files should be revisited.

3.1 About Projects and Repositories

Your source files likely reside in a remote source control management (SCM) repository. Within Code Sight, you create a project, which points to locations within your repositories. The system where the Code Sight server is installed must have the client software installed for the repositories, and that client software must be in the path visible to the Code Sight process.

Note: Code Sight uses the PATH environment variable to look for SCM clients. Make sure your SCM client can be found using the system path, and not your user path.

The Settings SCM Settings page shows the clients that Code Sight has detected on your system.

Figure 4 SCM Settings

Tip: The link at the bottom of the screen takes you into the online help system where you can find additional notes about each type of repository.

3


3.2 Creating a Project

A project is the basic entity within Code Sight.

1. Select the Projects tab to see the projects already configured on this system.

2. Click the Create Project button.

3. On the popup dialog, enter a unique name for the project. Note that the name and description are both searchable.

4. Enter the connection details for the project. You can enter multiple locations if necessary. If your repository

does not require a username and password, you can leave them blank.

5. Optionally, you can change the schedule of how often the project is revisited by Code Sight. You can also

restrict search access.

9 BL ACK DUCK CODE SIGHT ADMINISTR ATOR'S GUIDE

3.3 Modifying a Project

After a project has been added, the information and schedule can be edited.

Figure 5 Edit Project Details

The Edit Project Setup dialog has the same fields as the Create Project Setup dialog.

3.3.1 Adding Source Code Locations

You can add multiple source code locations for your project from one or more SCM repositories. Code Sight visits each repository as directed by the project’s overall schedule.

From the project’s Setup page, click the Edit Project button. Then, click the Add Code Location link.

Figure 6 Multiple Code Locations

See Section 3.6: Configuring Source Code Locations for information specific to each repository type.

Tip: Many repository types allow browsing for a specific branch or tag. Use the Test Connection button to determine your proper connection string, and then use Browse to find the subdirectory you want.

3.3.2 Set the Indexing Schedule for a Project

By default, projects are revisited based on the global schedule. You can modify a project to use its own schedule.

There are several ways to start the indexing process for a project:

• Immediately when the project is created.

The first crawl starts automatically when you add and save a new source code location.

• Based on a global schedule (go to Settings Index Settings Global Schedule)


Tip: The No schedule setting can be used to disable indexing.

• Based on an individual schedule (select the project, choose the Setup tab, and click Edit Project)

• On-demand with the Index Queue for next job setting

3.3.3 Adding Team Members to a Project

You can set up your project for user-based search access (see Section 3.5.1). Rather than allowing everyone to search your code, Code Sight only allows access to named users or user groups.

One way of specifying these users is to edit the user’s account and assign them a project-specific role for your project. The other way is to select the project and add the users using the Team Members tab. Click either the Add User or Add User Group buttons.

11 BL ACK DUCK CODE SIGHT ADMINISTR ATOR'S GUIDE Figure 7 Adding a User to a Project

Select the user or user group who should have search access to the project and click the Add User button. The change takes effect immediately.

3.4 Deleting a Project

To delete a project, select the checkbox next to the name in the main table, and select Delete from the More actions pull-down menu. Confirm your choice by clicking OK on the confirmation dialog.

Figure 8 Deleting a Project

The deleted project is no longer searchable and will be fully removed from the index the next time the index is updated.

3.5 Indexing Projects

Once you have defined a project, the next step is to have Code Sight examine the source files (also known as "crawling") and then index the project. During this process, Code Sight retrieves any new or changed files from the SCM repository and performs a special analysis pass on them based on their file type. Then, it publishes the new index, making the project searchable for all users.

When you initially created the project, it was automatically set to be crawled and indexed based on your default global schedule. This can be modified on a per-project basis. See Section 3.3.1 for details.

3.5.1 Exclude a Project from Indexing or Searching

At certain times it may be necessary to make a project non-searchable while still maintaining the option to index it later. Or, you may want to freeze the current state of the project and disable indexing. Both of these cases are possible.

To hide (disallow searching) a project from all users:

1. Select the checkbox for the project in the Projects table.

2. Select Hide for Search from the More actions menu.

To hide a project from most users:

1. Select the checkbox for the project in the Projects table.

2. Select Restrict for Search from the More actions menu. Alternately, you can select the Setup tab and change the Search Visibility setting to “Restricted.”

3. Go to the Users tab. From here, you can select users or user groups and grant them a Project Searcher role,


which allows them access to this particular project. The project remains invisible to all other users.

To freeze a project and disable indexing:

1. Click the project row in the Projects table.

2. Go to the Setup subtab.

3. Click the Project Indexing Schedule link.

4. Select the No schedule radio button.

5. Click Save.

3.5.2 Project History

Track the status of your projects with the Projects History subtab. This page shows the operations that have been performed (crawl, index, and publish) and any warnings that were generated.

Figure 9 Viewing the Project History

3.6 Configuring Source Code Locations Note: Code Sight uses the PATH environment variable to look for SCM clients. Make sure your SCM client can be found using the system path, and not your user path.

3.6.1 SCM Repository Configurations

Code Sight has built-in support for several different SCM systems, as well as the File System Adapter which can be used with almost any version control system. SCM repositories used with Code Sight have several common aspects. Depending on the SCM type, these fields may be separate or may be combined into the connection string:

1. Username/password you use to access the repository

2. Connection string of the SCM client

3. Branch or tag where your source code is located within the repository

3.6.2 Connection Strings

The Connection String for a repository is similar to the command you would use to interactively connect to the repository. The online help includes examples for connecting to an open source repository of each supported type.

3.6.3 File System Adapter

The File System Adapter enables Code Sight to index source code stored on the local machine. The File System


Adapter acts as a universal adapter, allowing you to use Code Sight with any SCM application. Simply access your repository and retrieve the files to a local directory - then point Code Sight at the local files.

The connection string when using the File System Adapter is the absolute path to the top-level directory, such as C:\MySourceCode\.

Note: When using the adapter for this purpose, you are responsible for making sure that the source code in the path specified is synchronized with the repository server.

3.6.4 Zip Archive Adapter

The Zip adapter is useful for looking inside .zip archive files.

1. Create a new project using Zip as the SCM Client type.

2. For the Connection String, enter the absolute path to a top-level directory containing your Zip files. For example: /etc

3. Use the Browse button to find and select your ZIP files.

Tips: The File System Adapter does not open .ZIP archive files. Therefore, you may need to use both repository types to fully index your project. Also, the Zip adapter does not handle nested zip archives, so these would need to be expanded manually. The Zip adapter only expands the first level.


3.6.5 Sample Open Source Connection Strings

The following examples show connection strings for all supported SCM adapters.

Sample Bazaar Connection String

Tip: Download Bazaar and make sure it is in your path.

The Bazaar connection string includes the server location and project branch in the following format: http://host.com/path/to/my/branch

Example Connection String (anonymous user): http://bzr.savannah.gnu.org/r/emacs

Sample CVS Connection String

Tip: Download CVS for All Platforms and ensure cvs.exe is in your path before starting the Code Sight service.

Generic Non-Anonymous Connection String :pserver:username:password@serverIP:/path/cvsroot

Apache Connection String :pserver:anoncvs:[email protected]:/home/cvspublic

Berlios Connection String :pserver:anonymous:@cvs.projectname.berlios.de :/cvsroot/

Mozilla Connection String

Enter the following on a single line for the Connection Template field on the Add/Edit Repository page:

:pserver:anonymous:[email protected]:/cvsroot

When adding a project that uses this repository, specify the project name and path. You can use the Browse button or enter the values directly.

Novell Connection String :ext:[email protected]:/cvsroot/.

Note: The period (.) at the end of this template is used to represent all modules for the given CVS root.

http://wiki.bazaar.canonical.com/Download

http://www.nongnu.org/cvs/


Sample GIT Connection String

Tip: You do not need to download a Git client. This functionality is included in your Code Sight installation.

Due to the decentralized nature of the Git SCM system, you cannot use the Browse feature to list projects in the repository. Also, you cannot use the Test Connection button unless you include the full path to the project in the repository connection string.

For example, consider that you want to index the following project – git://github.com/mislav/will_paginate. You could set the repository’s Connection String to git://github.com/mislav/, and the project’s Project Path to will_paginate. However, this method would not allow you to test the connection. A better practice is to include the full project path in the connection string.

Sample Mercurial Connection String

Tip: Download Mercurial and make sure it is in your path.

Template: http://hg.address Example Connection Template: http://hg.savannah.gnu.org/ Example Project Path: hgweb/octave/

Sample Subversion Connection Strings

Tip: Download Subversion and make sure it is in your path.

Generic Subversion Connection String svn://svnserver.mycompany.com/trunk/

If you are connecting to a system that allows anonymous logins, you may be able to omit the username and password fields.

Apache Connection String http://svn.apache.org/repos/asf/

Code.Google.Com Connection String http://projectname.googlecode.com/svn/trunk/

Or, depending on your specific project, you may need to specify a branch instead. In this case, use the /tags qualifier instead of /trunk:

http://projectname.googlecode.com/svn/tags/

For example, a sample connection string is:

co http://oreguile.googlecode.com/svn/trunk/

Often, projects on Google Code say that to download them, you must pass "projectname-read-only" as a parameter. This is not necessary when using Code Sight to access the project files.

http://mercurial.selenic.com/downloads/

http://www.open.collab.net/downloads/subversion/


3.6.6 Sample Connection Strings for Commercial Products

AccuRev

Tips:

- Always make sure the AccuRev executable is in your path.

- Visit http://www.accurev.com/ for more information.

- AccuRev requires both a valid server connection string and a valid stream name. If the stream name is not provided, the test connection will work, but crawling will fail.

The standard template connection string for an AccuRev repository looks like the following:

Username: myname Password: ****** Stream: Host:Port Branch or Tag: /Project[view/folder]

Borland StarTeam

Tips:

- Always make sure the StarTeam executable is in your path.

- Visit http://www.borland.com/us/products/starteam/ for more information.

The standard connection information for a StarTeam repository looks like the following:

Username: user Password: ***** Connection String: host:49201/Project[view/folder]

IBM ClearCase

Tip: Download ClearCase or the ClearCase Remote Client and make sure it is in your path.

Template: PathToView\VobName$SubPath Example: c:\views\SomeView\sources$InitialComponent\

Note: The Code Sight adapter assumes PathToView contains a valid and configured ClearCase View.

Remote Client:

Username: [email protected] Password: ****** Connection String: C:\view\myView\myVOB$mycmpnt\ Or, you can combine the fields into a single connection string: Combined Connection String: --username [email protected] --ser http://localhost:12080/TeamWeb/services/Team --pas changeme M:\MyFirstUCMView\

http://www.accurev.com/

http://www.borland.com/us/products/starteam/


Microsoft Team Foundation Server (TFS)

Tips:

- Always make sure the TFS executable is in your path.

- A TFS client cannot go beyond 259 characters.

- Visit Team Foundation Information for more information.

The standard template connection string for Team Foundation Server looks like the following:

Template: tfs://username:password@server$/ UNC Server: tfs://username:password@\\myserver$/ourproject Web Server: tfs://username:password@http://myserver:8080$/ourproject/path

The password component is optional. Server specification is typically a UNC path or http path with a port specified following a colon (as in http://myserver:8080). TFS uses a web services base, so users having poor luck or inconsistency with UNC paths may find using an http specification easier.

Microsoft Visual SourceSafe (VSS)

Tip: Download VSS 6 and make sure it is in your path.

Local SourceSafe Database user:password@c:\VSSDatabase$/

UNC SourceSafe Database guest@\\koders\vss_share$/

TCPIP SourceSafe Database guest@http://myserver.com$/

Note: Only VSS8 has support for TCP/IP.

Perforce

Tip: Download Perforce and make sure it is in your path.

Connection strings for Perforce must have the username, password, and server location specified in separate fields.

For example:

Username: guest Password: <blank> Connection String: public.perforce.com:1666//public/perforce/utils/aegis/

http://msdn.microsoft.com/en-us/vstudio/ff637362

http://www.perforce.com/perforce/loadprog.html


Other Version Control Systems

Code Sight can be used with other version control systems as well. When integrating with other version control systems, the File System Adapter (see Section 3.6.3) can be used. The File System Adapter enables indexing, but it does not ensure that the local source code cache is up-to-date.

Note: When using the File System Adapter, the system administrator must make sure that the local source code folders are kept current by creating the necessary scheduled scripts or commands.

PRODUCT CONFIGURATION

4 PRODUCT CONFIGURATION

The Admin Settings area contains several screens used to configure your Code Sight environment. In general, the settings need to be made once, before doing any other tasks on your system.

4.1 Index Settings

The Index Settings page controls the global schedule of how often Code Sight indexes your projects. It also controls which files should be ignored.

Figure 10 Index Settings

By default, when the indexing job completes, the new index is published automatically. You can uncheck the Auto Publish box if you want to keep your old index. This may be useful if you want to temporarily freeze the index in its current state.

4.1.1 Creating a Global Schedule

All of the projects in your repositories need a schedule of how often their files should be revisited for re-indexing. This is controlled by the global schedule.

The global schedule is set using Admin Settings Index Settings. Click the Global Schedule button to launch the dialog box.

4


Figure 11 Creating a Global Schedule

Tip: You can also set an individual schedule by creating a project schedule after the project has been created. See Section 3.3.2: Set the Indexing Schedule for a Project for details.

4.1.2 Ignoring Files and Directories

You may have files or directories in your projects that do not need to be indexed. These might include binary files, build artifacts, and SCM control files. Use the Index Settings page to indicate what should be ignored.

By default, Code Sight is configured to ignore certain binary file types during indexing. You can modify the list to include more or fewer entries. Note that ignoring “tar” or “zip” files here is not related to using the Zip repository type. In that case, Code Sight correctly looks inside the archive to find and index your non-binary files.

The following file types are ignored by default:

bmp chm com dll doc

exe gif gz gzip jar

jpeg jpg lib pdf png

tar xls zip


4.2 SCM Settings

The SCM Settings page lists the source control management (SCM) clients installed on your system and detected by Code Sight. If Code Sight cannot access your SCM client software, then it will not show that repository type when you are adding the source location to your project.

Figure 12 SCM Settings

The File System, Git, and Zip clients are built into Code Sight, and are always present.

Tip: The timeout variables are available to prevent long delays when there are problems connecting to remote repositories.

4.3 Mail Settings

The Mail Settings page defines how Code Sight can send email to the system administrator. Currently, this is only used after a failure of an automatic upgrade.

Figure 13 Mail Settings

• Administrator Address: E-mail is sent to this address if something fails during an update.

• SMTP Server: Used for sending mail from this client.

• SMTP Port: Connection port used for sending mail.

• SMTP Sender: E-mail sent from Code Sight comes from this address.


• SMTP Username and Password: Used to connect to your mail server.

4.4 Proxy Settings

The Proxy Settings page controls how Code Sight can access the servers back at Black Duck. This is important for license verification and for downloading updates.

Figure 14 Proxy Settings

4.5 Update Status Tip: You cannot update your software until you have registered either a free or enterprise license.

To perform an update, follow these steps:

1. Log in as a System Administrator.

2. Choose Admin Settings Update Status. Code Sight displays a panel for selecting update times and a list of the most recent updates available (none in this example).

Figure 15 Update Page

3. In the Auto Install Software Update menu, select when you want new updates to be downloaded and installed – Never, During Scheduled Times, or When Available.

4. In Day Settings section, select a schedule of when your Code Sight server can look for updates from Black Duck. If you specify a long duration, the Black Duck site is checked repeatedly over that time interval. If you


have selected the option to automatically install the update, the system handles this appropriately.

5. If you want to download and install manually, and if there are updates available, click the Download link for the first update to download it to your site. After downloading is complete, the state changes to "downloaded" and the action changes to an "Install" link.

6. Click the Install link to integrate this update into your system.

7. When installation is complete, a Delete link displays that lets you clean up the space used for download. This also removes the entry from the Active Updates list, in order to keep the list short.

Note: When you connect to the Black Duck server for updates, some statistical and identification data is transmitted along with your request. See Appendix A—Data Gathered by Code Sight for a description of this data.

4.6 Product Registration

There are three registration options for using Code Sight:

• Free Unregistered – You are limited to indexing 200k lines of code. You can obtain a free registration key by visiting http://www.blackducksoftware.com/code-sight/upgrade.

• Free Registered – See the limits set forth at http://www.blackducksoftware.com/go/codesight_additional_terms

• Paid Registration – Allows indexing up to a limit specified in your license agreement.

The two free options display a message on the Progress dashboard, indicating that indexing is limited. Otherwise, the software is the same for all options. Note that this message is not shown to users of the search page.

Typically, registration is handled immediately after installation. However, it is not required. If you do not register, the software behaves normally, except that it stops publishing after reaching 200k lines of code. Also, system updates are disabled until you register.

Tip: At any time, unregistered users can obtain a free trial license for more lines of code by visiting the Black Duck website listed above.

Once you have a license key, go to Admin Settings Product Registration and click the Activate button. Use the dialog box to enter your key and register your software.

http://www.blackducksoftware.com/code-sight/upgrade

http://www.blackducksoftware.com/go/codesight_additional_terms


Figure 16 Registration Page

If you want to change your registration at a later time, go to the Admin Settings Product Registration page. Enter your new registration ID and click the Reactivate button.

Figure 17 Product Registration

Note that your license may include an expiration date. After that time has passed, you can continue to search your projects, but further publishing is disabled.

SYSTEM CONFIGURATION

5 SYSTEM CONFIGURATION

This chapter describes configuration settings for the Code Sight server.

5.1 Disk Space Requirements and Usage

Black Duck recommends a minimum of 100GB of free disk space for the Code Sight server. The installation checks for a minimum of at least 20GB, but you can quickly use up this space once you start indexing new projects.

Tip: As Code Sight accesses repositories and downloads new project files, it copies those files to the local system under the Black Duck user account. On Linux systems, this would be in the /home/blackduck directory. For Windows, it is under the Users area for the blackduck user. The files are then processed and indexed, with some data saved into the PostgreSQL database. During the installation, you can specify a different location for this database. Using different devices can help to manage your overall disk usage.

5.2 Startup Configuration and Log Files

The following files are listed for a Linux system, when using the installation default locations.

The locations are slightly different for Windows. Depending on your version, they may be in C:\Documents and Settings\<username>\Local Settings\Temp.

Type Path

Server Installation logs /tmp/Black_Duck_Code_Sight_Install_<date>.log

/tmp/installer_debug.txt

/tmp/codesight_InstallLog.log

/tmp/BDS_IACA_codesight_server.log

Tomcat Server logs /opt/blackduck/CodeSight/tomcat/logs/Catalina.out

(Older version logs) /opt/blackduck/CodeSight/tomcat/logs/blackduck_log.txt.<date>

(Older version logs) /opt/blackduck/CodeSight/tomcat/logs/blackduck_access_log.<date>.txt

Startup Configuration and Memory Management

/opt/blackduck/CodeSight/tomcat/config

Duck Update Download and Installation logs

/opt/blackduck/CodeSight/downloads/CodeSight/<version>/<update_dir>/.download.log /opt/blackduck/CodeSight/downloads/CodeSight/<version>/<update_dir>/.install.log

5

26 SYSTEM CONFIGUR ATION

Type Path

The update_dir corresponds to the individual directory created for each update. The version corresponds to the current stream version of Code Sight.

On Windows systems, the Code Sight uses the %TEMP% environment variable to find the temp area. Also, default installation area is Program Files\Black Duck Software\CodeSight.

5.3 Stopping and Starting the Tomcat Server

There are instances where you may need to stop and restart the Tomcat server. The following example outlines this process. It requires the following actions:

Stopping the Job Server.

Stopping the Tomcat Server.

Starting the Tomcat Server.

Starting the Job Server.

Note: Both of these phases require that you log in as root on Linux.

Stopping Tomcat on Linux To stop the Tomcat server, follow these steps:

1. In Code Sight, go to Admin Process and click the Stop button. The Status changes from “Running” to “Shutting Down.”

Important: Wait for the status to change to “Disabled.” Stopping Tomcat without allowing all jobs to complete can lead to data consistency issues.

Figure 18 Disabled Status

2. In Linux, log in as root.

3. Enter the following command:

root@linux:~> /etc/init.d/bds-codesight-tomcat stop

4. Ensure that all Tomcat processes have stopped by using the following command to check the process status:

root@linux:~> ps aux | grep tomcat

5. If the shell indicates that Tomcat is still running, enter the following command to delete the Tomcat lock:

root@linux:~> rm -f /var/lock/subsys/bds-codesight-tomcat

Starting Tomcat on Linux To start the Tomcat server, follow these steps:

1. In Linux, log in as root.

2. Enter the following start command:

root@linux:~> /etc/init.d/bds-codesight-tomcat start

27 BL ACK DUCK CODE SIGHT ADMINISTR ATOR'S GUIDE 3. In Code Sight, go to Admin Process and click the Start button.

Stopping Tomcat on Windows To stop the Tomcat server, follow these steps:

1. In Code Sight, go to Admin Process and click the Stop button. The Status changes from “Running” to “Shutting Down.”


Figure 19 Disabled Status

2. In Windows, go to Start Control Panel Administrative Tools Services to open the Services Manager.

3. Right-click the Black Duck Code Sight Tomcat service and select Stop.

Figure 20 Stop Tomcat on Windows


Starting Tomcat on Windows To start the Tomcat server, follow these steps:

1. Go to Start Control Panel Administrative Tools Services to open the Services Manager.

2. Right-click the Black Duck Code Sight Tomcat service and select Start.

5.4 Configuring Password Strength

By default, Code Sight does not enforce any restrictions on user names or passwords. However, you can configure Code Sight to enforce the following password requirements:

• User name must contain at least x number of characters (length specified by the Administrator)

• Password must contain at least x number of characters (length specified by the Administrator)

• Password must contain at least one uppercase letter

• Password must contain at least one number

• Password must contain at least one special character (list of required characters specified by the Administrator, for example, @ # $ % *, etc.)

• Password may not contain specific characters (list of illegal characters specified by the Administrator, similar to required characters)

Important: Enabling any of the above password restrictions with also automatically activate the rule that prevents user names and passwords with the same value. The test for matching user ID and passwords is case insensitive. So for example, JohnDoe\johndoe would fail the validation and generate an error message.

Step 1: Determine Your Password Requirements Determine which password requirements you are going to enforce, and what the values will be.

Configuration Setting Values

validation.user.name.minlength The minimum number of characters that you want to require for user names.

validation.user.password.illegalchars List of characters that are illegal as part of a password, for example, !@#$%^&.

Note: Code Sight uses braces { } around the list of illegal characters in password error messages.

validation.user.password.minlength The minimum number of characters that you want to require for passwords.

validation.user.password.numeric Require a number as part of the password? (true, false)

validation.user.password.requiredchars List of characters, at least one of which must be included in the password, for example, !@#$%^&

Note: Code Sight uses braces { } around the list of required characters in password error messages.

validation.user.password.uppercase Require an uppercase letter as part of the password? (true, false)

Note: Password restrictions only affect passwords created after the restrictions are configured. Passwords created before the password restrictions were configured will not be affected. In order to have all user

29 BL ACK DUCK CODE SIGHT ADMINISTR ATOR'S GUIDE passwords meet the new password restrictions, you must have existing users create new passwords.

Step 2: Modify the Tomcat Configuration Settings To configure password requirements on the Tomcat server, complete the following steps:

Use the following instructions on Linux systems:

1. Edit the startup file /opt/blackduck/CodeSight/config/bds-codesight-tomcat.start to include the password requirements that you want to use. For example,

-Dvalidation.user.password.uppercase=true

-Dvalidation.user.password.numeric=true

-Dvalidation.user.password.requiredchars=!@#$%^&

-Dvalidation.user.password.illegalchars=*

-Dvalidation.user.password.minlength=10

-Dvalidation.user.name.minlength=5

2. In Code Sight, go to Admin Progress and click the Stop button. The Status changes from “Running” to “Shutting Down.”


3. Restart Tomcat (as root), using the following command:

/etc/init.d/bds-codesight-tomcat restart

Use the following instructions on Windows systems:

1. Use the regedit command to edit the system registry.

2. Expand the hierarchy to locate HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Procrun 2.0\codesighttc6\Parameters\Java.

3. Edit the Options entry, adding the password requirements that you want to use. For example,

-Dvalidation.user.password.uppercase=true

-Dvalidation.user.password.numeric=true

-Dvalidation.user.password.requiredchars=!@#$%^&

-Dvalidation.user.password.illegalchars=*

-Dvalidation.user.password.minlength=10

-Dvalidation.user.name.minlength=5


Figure 21 Registry Changes for Password Restrictions

4. Exit the Registry Editor.

5. In Code Sight, go to Admin Progress and click the Stop button. The Status changes from “Running” to “Shutting Down.”


6. Restart Tomcat using the Services Manager.

5.5 Setting up for SSL Encryption

The Secure Socket Layer (SSL) allows secure communications between browsers and web servers. The data sent is encrypted by one side, transmitted, and then decrypted by the other side before processing. Both the server and the browser encrypt all communication packets before sending out data.

Besides encryption, SSL also provides client authentication on initial communications between the server and the


browser. The server sends, and may request, certificates from the browser. This ensures proof that the site is who and what it claims to be. See the Tomcat website (http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html) for more information.

Although the Tomcat server runs on your internal network, you may want to enable SSL encryption to protect communication between the server and browsers. The process involves four phases, as follows:

I. Get a certificate from a third-party provider (for example, GoDaddy.com).

II. Import the certificate.

III. Upload the keystore to the Tomcat server.

IV. Update the product registration.

The following overview is for a Linux server. Please visit the Code Sight online support forum if you need instructions for a Windows system. The steps are different on Windows, and include editing the Registry.

Phase I: Get a Certificate To get a certificate, follow these general steps:

1. At the command line, generate a SSL key and certificate signing request (CSR) using the following command:

openssl genrsa -out <keyfile> <keystrength>

openssl req -new –key <keyfile> -out <CSRfile>

Example

openssl genrsa -out server.company.com.key 1024

openssl req -new -key server.company.com.key -out server.company.com.csr

This example creates a request for server.company.com to get a certificate signing request (CSR) from the signing authority.

Note: It is important that the name entered for your server be the full hostname that your SSL server will reside on, and that the organization name be identical to what is in the 'whois' record for the domain.

2. Send the CSR to the key signing authority in some way. (This is usually done via their web interface). Choose "Apache" as the web server type. Pay for their service and wait for them to send you a signed certificate.

The signing authority may ask for detailed information regarding your organization. They verify the information you provided to see if it matches with your domain registry information.

http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html


Phase II: Import the Certificate To import the certificate to the keystore format used by the Tomcat server, follow these general steps:

Once you receive a signed certificate, you need to import it to the Tomcat server. Tomcat uses a keystore for holding certificates and keys. Note that the keystore can be stored in any file, but in this example it is called ".keystore". What was generated earlier and what was received from your key signing authority is in a standard format that needs to be converted to pkcs12 format.

No Chain Example:

If your certificate was not formed by a chain, use the following syntax to convert the format:

openssl pkcs12 -in <certificate> -inkey <key> -export -out /root/keystore.tomcat -name tomcat -passout pass:changeit

For example:

openssl pkcs12 -in server.company.com.crt -inkey server.company.com.key -export -out /root/keystore.tomcat -name tomcat -passout pass:changeit

Chain Example:

If your certificate is formed by a chain (such as those created by GoDaddy.com), use the following syntax:

openssl pkcs12 –export –chain –CAfile -in <certificate> -inkey <key> -out \

.keystore -name tomcat –passout pass:<password>

For example:

openssl pkcs12 –export –chain -CAfile gd_bundle.crt -in server.company.com.crt -inkey server.company.com.key -out .keystore -name tomcat –passout pass:changeit

In both cases, the password must be entered as the password for the certificate key. If you do not enter a password in the command, Tomcat prompts you for it.

The crt file will be named differently depending on the issuing registrar. Also, this example uses the default key password used by Tomcat, which is, "changeit." This might be different on your system.

Phase III: Upload the Keystore To upload the keystore to the Tomcat server, follow these steps:

Use the following instructions on Linux systems:

1. Upload the ".keystore" file to the /root directory on your Tomcat server.

2. Open the /opt/blackduck/CodeSight/tomcat/conf/server.xml file on your server. This file defines the ports that users use to connect to Code Sight. You will see the definition of the default port 80.

3. Add the following line to the default port definition: redirectPort="443"

4. Create the new port definition with the following elements. Be sure to note the highlighted lines, which are related to the new keystore information:

<Connector port="443"

protocol="HTTP/1.1"

SSLEnabled="true"

maxThreads="150"

scheme="https"

secure="true"

clientAuth="false"

33 BL ACK DUCK CODE SIGHT ADMINISTR ATOR'S GUIDE sslProtocol="TLS"

keystoreFile="/root/.keystore"

keystorePass="changeit"

keystoreType="PKCS12" />

5. Next, edit the startup file /etc/sysconfig/bds-codesight-tomcat.start, and change two fields from the default http://127.0.0.1:80 to the https protocol, domain name, and new port for your system. The server name and domain name needs to match with your certificate. For example:

export JAVA_OPTS=" -Dblackduck.baseURL=https://myServer.mydomain.com:443/ ${JAVA_OPTS}"

export JAVA_OPTS=" -Dblackduck.codesight.solrserver.url=https://myServer.mydomain.com: 443/solr ${JAVA_OPTS}"

Important: If Code Sight is running, stop the Job Server before performing the next step. In Code Sight go to Admin Process and click the Stop button. The Status changes from “Running” to “Shutting Down.” Wait until the Status changes to “Disabled” before restarting Tomcat. Stopping Tomcat without allowing all jobs to complete can lead to data consistency issues.

6. Restart Tomcat (as root), using the following command:

/etc/init.d/bds-codesight-tomcat restart

Use the following instructions on Windows systems:

1. Upload the ".keystore" file to a directory visible to your default system account. For example, you could create a C:\keystore directory. It is important that the system account has read access to this directory and the file within it.

2. Edit the C:\Program Files\Black Duck Software\CodeSight\tomcat\conf\server.xml file on your server. This file defines the ports that users use to connect to Code Sight. You will see the definition of the default port 80.

3. Add the following line to the default port definition: redirectPort="443"

4. Create the new port definition with the following elements. Be sure to note the highlighted lines, which are related to the new keystore information:

<Connector port="443"

protocol="HTTP/1.1"

SSLEnabled="true"

maxThreads="150"

scheme="https"

secure="true"

clientAuth="false"

sslProtocol="TLS"

keystoreFile="C:\keystore\.keystore"

keystorePass="changeit"

keystoreType="PKCS12" />

5. Next, use the regedit command to edit the system registry. Expand the hierarchy to locate HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Procrun 2.0\codesighttc6\Parameters\Java.

6. Edit the Options entry, where you must change two fields: -Dblackduck.baseURL and -Dblackduck.codesight.solrserver.url. Change the values to the

34 SYSTEM CONFIGUR ATION https protocol, domain name, and new port for your system. The server and domain names need to match with your certificate.

Figure 22 Registry Changes for SSL

Important: If Code Sight is running, stop the Job Server before performing the next step. In Code Sight go to Admin Process and click the Stop button. The Status changes from “Running” to “Shutting Down.” Wait until the Status changes to “Disabled” before restarting Tomcat. Stopping Tomcat without allowing all jobs to complete can lead to data consistency issues.

7. After saving your registry changes, restart Tomcat using the Services Manager.

Now, any communications between the port on the server and client are encrypted using SSL. Connections to HTTP are automatically redirected to use https://<myCodeSightServer>:443.


Phase IV: Update Local Registration Settings To modify the local registration settings to reflect the use of the HTTPS protocol, follow these general steps:

1. To modify your local registration settings, log in to Code Sight.

2. Select Administration Settings Product Registration.

3. In the Registration ID field, enter your registration key.

4. In the External access protocol drop-down, select https.

5. Click Reactivate. The page refreshes with the new information.

5.6 Backing Up the Code Sight Database

Your Code Sight data should be backed up on a regular basis. The process is simple, but requires some manual steps on your part.

This section describes how to back up the database used by your Code Sight installation. Section 5.5.1 describes the files and how often you should back them up. Section 5.5.2 provides instructions on how to perform these backups.

Important: When backing up your database, we recommend that you log in to the Code Sight Admin area, click the Stop button to stop the job server, and allow any current indexing jobs to finish before starting this procedure. When indexing completes (Status = Disabled), shut down the Tomcat application server. This ensures that nobody is using Code Sight and making changes during the procedure.

In addition to the database files, you should also include the following files/directories in your normal system backups:

• C:\BDS-CodeSight\solr OR /var/lib/bds-codesight/solr

This directory contains the actual index data. While it can be recreated automatically during the crawl/index/publish cycle, this process could take many hours depending on the number of projects and total lines of code you are indexing. If you do not back it up, when you restore the Code Sight database you should delete the Solr directory contents and let Code Sight recreate the index. If you choose to back up the index, you must back it up at the same time as the database. The database and index must remain synchronized.

• C:\Program Files\Black Duck Software\CodeSight OR /opt/blackduck/CodeSight

This is your product installation directory.

• C:\Documents and Settings\blackduck OR /home/blackduck/CodeSight

As Code Sight crawls the source code locations of your projects, it copies files to this user-area location (which may be different on your operating system.) As with the index, this can be recreated automatically after restoration of your database. However, if you do choose to back up the source directory, it should be backed up at the same time as the index files, to keep them synchronized.

Please use the following sections as guidelines for developing your own best practices for database backups.


5.6.1 Code Sight Database Name

Code Sight uses a single database:

Table 2 Database Name and Backup Frequency

Database Name Backup Frequency

bds_codesight Back up daily – contains project information such as source locations, plus product information such as users and roles.

5.6.2 Back Up Procedure - Linux

Back up the most important data first and label your backup media carefully. The standard process for backing up a PostgreSQL database is to first copy it to a file. This serves as your backup. You may then want to copy your backup files to some removable media such as a CD or DVD. If you are ever in a situation where you lose some data or a database gets corrupted for any reason, you can restore the database using this file.

Note: Code Sight is unavailable during this procedure while Tomcat is shut down.

The process begins with the creation of the dump file as outlined below.

To back up the PostgreSQL database, follow these steps:

1. Log in as root.

2. Stop Tomcat. In a distributed system, stop it from the system where it is installed.

/etc/init.d/bds-codesight-tomcat stop

3. Change to the bds_codesight user. This is the user that owns the PostgreSQL installation.

su – bds-codesight

Your prompt changes to indicate the new user, and your current directory changes to/var/lib/bds-codesight.

4. Dump the database to a location with sufficient free space (this example uses /tmp). The pg_dump command should be on bds-codesight’s command search path. If not, the command is located at: /opt/blackduck/CodeSight/postgresql/bin.

bds-codesight~> pg_dump –Fc –f /tmp/bds_codesight.dump bds_codesight

This puts the bds_codesight database into a file called 'bds_codesight.dump' in the /tmp directory.

5. Take the bds_codesight.dump file and save it on another device.

6. Change back to the root user, and then restart Tomcat.

su

/etc/init.d/bds-codesight-tomcat start

5.6.3 Back Up Procedure - Windows

Note: This procedure requires a database password. Contact Black Duck Customer Support for the password for your database. Please use the online forum to contact Support.

On Windows systems, you can use the pgAdmin III tool to back up your databases. This tool is included with the Code Sight installation and is available in your Start menu.

1. Start the pgAdmin tool: Start All Programs PostgreSQL 8.4 pgAdmin III.

2. Right-click the Black Duck Code Sight database, and choose the Properties option.

37 BL ACK DUCK CODE SIGHT ADMINISTR ATOR'S GUIDE 3. Change the Username from "bds-codesight" to "blackduck", and click OK. This is a privileged user account

that you will use to access the database.

4. Next, right-click the Black Duck Code Sight server, and choose the Connect option. Enter the password you

obtained from Black Duck Customer Support.

5. Right-click the bds_codesight database and choose the Backup option.

6. Enter a name for the backup file, such as bds_codesight.dump, and click OK.


7. When the process completes, click Done.

5.7 Restoring the Code Sight Database

The restore program lets you retrieve files you have backed up with the pg_dump command. Once you have saved any (or all) of your databases to a file, you can then restore that particular database if required. Note that if you have also backed up the index and source files, they should be restored at the same time, prior to restarting Tomcat.

LINUX To restore a damaged or corrupted database, follow these steps:

1. Login as root on the system on which the Code Sight database server is installed.

2. Stop Tomcat.

/etc/init.d/bds-codesight-tomcat stop

3. Change to the bds-codesight user (this is the Linux user account that owns the Code Sight PostgreSQL database):

su – bds-codesight

4. Delete the original database (if still present), using the following command (or env):

dropdb bds_codesight

5. Re-create the database using the following command:

createdb bds_codesight

This creates a new database and gives output that shows CREATE DATABASE. (If you have made configuration modifications to improve performance, you may need to supply various options to CREATE DATABASE depending on your circumstances). Upon creation, you need to upload your database with your data.

6. Issue the following command:

psql -c "grant all on database bds_codesight to blackduck" template1

39 BL ACK DUCK CODE SIGHT ADMINISTR ATOR'S GUIDE 7. To upload your database, use the following command:

pg_restore -d bds_codesight bds_codesight.dump

Alternately, if you have a multi-core processor, you can increase the speed of the restoration by using the –j qualifier to specify the number of parallel processors to use. Do not set this value higher than the number of available processors (4 to 6 is a reasonable starting point).

pg_restore -j 4 -d bds_codesight bds_codesight.dump

The restore may generate multiple warning messages that can be ignored.

8. Change back to the root user, and then restart Tomcat.

su

/etc/init.d/bds-codesight-tomcat start

Once this is done, you have successfully reverted to your old database.

WINDOWS On a Windows system, you can use the pgAdmin III tool to restore your backup files. The general steps are: drop the old database, re-create it, grant access to the bds-codesight user, and then restore the data from your backup file.

1. Start the pgAdmin tool: Start All Programs PostgreSQL 8.4 pgAdmin III.

2. Right-click the Black Duck Code Sight database, and choose the Properties option.

3. Change the Username from "bds-codesight" to "blackduck", and click OK. This is a privileged user account that you will use to access the database.

4. Next, right-click the Black Duck Code Sight server, and choose the Connect option. Enter the password you

obtained from Black Duck Customer Support.


5. Drop the database you are going to replace.

6. Next, create a new, empty database with the same name.

7. Grant access to the bds-codesight user.


Figure 23 Restoring a Database on Windows

DATA GATHERED BY CODE SIGHT

Appendix A—Data Gathered by Code Sight Periodically, your Code Sight installation interacts with servers managed by Black Duck and hosted at secure data centers. Black Duck treats this communication as confidential information as further described in your agreement with Black Duck Software, Inc.

The Black Duck network contains the following components:

• Registration Server – Used to register and maintain all registration information.

• Update Server – Provides software updates to customers when available.

The following data is collected automatically to verify compliance with the Black Duck agreement:

• Collection date — Time when data was gathered.

• Collection period — Time since previous data collection.

• Update level — Current system update level.

• Timestamp — Current date and time.

• Update ID — Unique identifier of the update being installed.

• Registration ID — Unique registration key of your installation.

• System ID — A random number assigned by Code Sight during installation.

• Product name — "Code Sight"

• Product stream — Version of Code Sight installed.

• Indexed Lines of Code – Total number of lines indexed for search.

• Indexed File Size – Total size in bytes of indexed files.

The following generic information is collected for product planning purposes:

• Java runtime environment version

• Operating system name

• CPU architecture

• Total system memory

• Free disk space in the installation directory

• Free disk space in the database table space directory.

A


This page is intentionally blank.

USING LDAP AND ACTIVE DIRECTORY

Appendix B —Using and Configuring LDAP or Active Directory

This section describes how to connect Code Sight to your LDAP or Active Directory (AD) environment. This chapter assumes that you already have a server set up and working on your system.

Tip: To complete this task, it may help to use an LDAP browser such as JXplorer to examine your current LDAP server settings. See http://www.jxplorer.org/ for download information.

B.1 HOW DOES IT WORK? Code Sight requires a valid username and password to log in. This user-based system is important for distinguishing who is able to accomplish various tasks within Code Sight. If you do not have an LDAP or AD server, Code Sight validates users against its internally-stored passwords. If you do have an LDAP server available, Code Sight can validate against the LDAP/AD server instead.

There is no difference to the user, except that they only need to maintain one password instead of two.

B.2 CONFIGURING CODE SIGHT TO VALIDATE USING LDAP OR ACTIVE DIRECTORY

1. Go to Admin Users LDAP/AD.

2. Check the LDAP is enabled box.

3. Set up the appropriate details for connecting to your LDAP/AD server. You may need the assistance of your LDAP/AD manager to know how to complete the fields.

4. Click Save.

You do not need to restart Code Sight. Any login attempts after the change will automatically use the new method.

B

http://www.jxplorer.org/


Figure 24 Configuring LDAP/AD Authentication

Table 3 LDAP Configuration Fields

Field Description

LDAP Server Specify the address of the LDAP/AD server you want to use for authentication.

LDAP Authentication Type Select from the following types of LDAP authentication mechanisms:

• none (anonymous) supply the Manager DN and leave the Manager password empty

• simple (with a plain-text password in the request/response challenge) supply the Manager DN and the Manager password

• digest-md5 (hashed password in request/response challenge) supply the Manager DN as a sAMAccountName value and the Manager password

LDAP Manager DN If your system requires an LDAP/AD manager account for access, specify the Distinguished Name of the LDAP/AD manager account. Code Sight accesses the server using this username. Note that some systems allow anonymous access, so this field may not be required.

LDAP Manager Password If required, specify the password for the LDAP/AD manager account.

LDAP URL for Reset Password

Specify the URL a user can access to reset their password. A link to this address will appear in the user's Code Sight profile page. Leave this field blank if you do not want users to be able to change their LDAP/AD passwords from within Code Sight.

LDAP User DN Pattern The relative Distinguished Name (DN) pattern that the search base it appended to. Users’ DNs are constructed by replacing the placeholder {0} with the username supplied by the user during authentication.

An example pattern would be "uid={0}, ou=developers" where a search base of "dc=mycompany,dc=com" would be appended to form an absolute DN.

LDAP User Search Base Code Sight accesses the LDAP/AD system and searches the directory information tree (DIT) for the user's login information. This field contains the starting point on the tree to use for the search.


LDAP User Search Filter Specify an optional filter to use when searching for names to validate against the LDAP/AD server.

LDAP Group Search Base Code Sight can grant overall roles to all members of an LDAP/AD group. This field contains the starting point on the tree to use for the search.

LDAP Group Search Filter Specify the search filter that provides the list of LDAP/AD groups for the display page.

LDAP Group Name Attribute Specify the attribute used to store group names in the LDAP/AD server.

Local Code Center User Specify one default user with at least the System Administrator role who will always have an account in the Code Sight system. This will be the only user who can still log in using their Code Sight password if your LDAP/AD system is not available.

Tip: Use the default system administrator account that was set up when you first installed Code Sight.

Create Users On Login Set this flag to allow new users to automatically create a new Code Sight account for themselves based on their LDAP account. Otherwise, user accounts can be created in bulk by synchronizing with an LDAP system, or individually using the Admin Users Users Create User function.

Group Assigned to Users Created On Login

Specify a default group for new users created using the "on login" process.

Paging Limit Set this field to a value at or below the paging limit on your LDAP server. If paging is not configured on your server, you can leave this field blank.


B.3 IMPORTING AND SYNCHRONIZING USERS Your LDAP/AD server likely contains a large list of users. You can import user accounts from LDAP/AD directly into Code Sight using the Admin Users LDAP Synchronization page. This saves you the effort of creating users one at a time, and can be used to regularly synchronize the Code Sight users with changes in LDAP.

Figure 25 Configuring LDAP/AD Synchronization

The All Users Search Filter selects the group from which the users are read. Then, use the User Field Mapping section to indicate the LDAP element for each Code Sight field that you want filled in. In this example, only the username is transferred from the LDAP system.

If the synchronizing process finds accounts in Code Sight that are not in LDAP/AD, it disables them. If it finds accounts in LDAP/AD that are not in Code Sight, it adds them to Code Sight and enables them. Accounts that exist in both systems are synchronized to match the LDAP/AD data and are enabled.

This process does not grant any roles to the users – it simply allows them to log in and read the online Help. You can grant overall roles to groups of users using the procedure described in the next section.


B.4 GRANTING ROLES TO GROUPS OF USERS If your LDAP/AD server has users in various groups, you can choose a particular group and grant them all the same role in Code Sight.

1. Go to Admin Users User Groups. The table shows the groups configured on your system. Some of these correspond to groups in your LDAP system.

2. Click Create LDAP Group. Code Sight connects to your LDAP server and shows a list of your LDAP

groups.

3. Select an entry from the table of LDAP Groups. Click Save. This creates a Code Sight group with the same name as in LDAP.

Figure 26 List of Groups on the LDAP/AD Server

4. The new group in Code Sight is empty. (LDAP users in the group are automatically added to this new group when they log in.) You can now add overall and/or project roles.


Figure 27 Grant Roles to an LDAP/AD Group


B.5 LDAP CONFIGURATION EXAMPLES B.5.1 AUTHENTICATION SEARCHES DIRECTLY BELOW A DOMAIN COMPONENT NODE

It is possible to configure LDAP to search directly below a domain node. For example, if the domain is specified as blackducksoftware.com, then it is possible to search for users directly below the blackducksoftware domain node as well as recursively within any child nodes.

The Jxplorer screenshot in Figure 25 below shows an example LDAP node tree with domain nodes com and blackducksoftware. Domain nodes are indicated with a blue dot as well as having an objectClass attribute of “domain” listed in the right-hand side attributes table.

Figure 28 Jxplorer View of a Domain Component

In this example, the goal is to find users directly below the domain node blackducksoftware (e.g., users Bob Brady and Olga Garber) as well as users in the organizational units (indicated with the node tree icon) Development, IT, Sales, etc., matching a filter query.

The LDAP configuration is shown in the Figure 26 below. The fields that are key to the search are, “LDAP User Search Base”, “LDAP User DN Pattern”, and “LDAP User Search Filter”. The search base specifies the starting node from where recursive searches will take place. Because the goal is to start the search from directly below the blackducksoftware domain node, the value given is “dc=blackducksoftware,dc=com”. Note the order of the node elements in the search base: it starts with the child node and goes up the tree to parent nodes when read left-to-right. This ordering is critical because it is an LDAP convention that is used with specified search criteria and distinguished names (dn values). The user dn pattern is relative to the search base. The {0} in the field will be replaced by the username supplied by the user during login. The LDAP software will construct the search dn by taking the user dn pattern and prepending it to search base. In the configuration example, the constructed dn will be “sAMAccountName={0},dc=blackducksoftware,dc=com. Jxplorer can be used to verify that the format of the constructed dn is appropriate.


Note: This example uses screen captures from Black Duck Code Center, but the principles are the same for Code Sight.

Figure 29 LDAP Configuration for Searches Directly Below a Domain Component

The Jxplorer screenshot in Figure 27 shows the attributes, including dn, for user node Bob Brady which is a direct child node of the domain node blackducksoftware. Note that the sAMAccountName is bbrady. The user should use bbrady as the username during login. Furthermore, the “sAMAccountName=bbrady,dc=blackducksoftware,dc=com” dn is equivalent search-wise to the listed dn “cn=Bob Brady,dc=blackducksoftware,dc=com”, so the constructed search dn in the configuration should work successfully. The entire tree below the blackducksoftware node will be searched for users having a dn that matches the constructed one. If the user attempting to authenticate cannot be found with the given dn pattern, then the search filter will be used in an attempt to find the user. The filter “sAMAccountName={0}” given in the configuration will be used by the search if the user can not be found with the constructed dn pattern. Since the example LDAP tree is configured so that every user has a sAMAccountName attribute, users like Ronan Fagan (see Figure 28) in ou (organizational unit) Sales will still be found.


Figure 30 Jxplorer View of a User Directly Below a Domain Component

Figure 31 Jxplorer View of a User in an Organizational Unit Below a Domain Component


B.5.2 AUTHENTICATION SEARCHES RESTRICTED TO A BRANCH NODE It is also possible to configure the LDAP authentication searches so that they are restricted to a branch within the LDAP tree. For example, if it was desired to restrict access to only users within the Development OU within the LDAP tree given in Figure 25, then the search base in the Figure 26 configuration would be changed to be “ou=Development,dc=blackducksoftware,dc=com”, the dn pattern and search filter could be left unchanged as “sAMAccountName={0}”. Note again that the ordering within the search base text is essential. The lowest level child node, Development, is given first, with each successive parent node from the above level added as the text is read from left to right.

The search base will restrict searches to within the development.blackducksoftware.com branch, even if the dn pattern search should fail and the filter be invoked. This means that users located outside the branch, like Bob Brady in the previous example, would be unable to successfully authenticate, even if they passed a valid password at login.

System Administrator's Guide...ADMINISTRATOR 'S GUIDE iii Table of Contents 1 INTRODUCTION...

Documents

Transcript of System Administrator's Guide...ADMINISTRATOR 'S GUIDE iii Table of Contents 1 INTRODUCTION...