System Administrator s Guide Version 2.4.2

Transcription

1 Version connect. code. create.

2 This edition of the System Administrator s Guide refers to version of This document created or updated on March 3, Please send your comments and suggestions to: Black Duck Software, Incorporated 8 New England Executive Park, Suite 221 Burlington, MA USA. Copyright 2014 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 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, 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.

3 Table of Contents TABLE OF CONTENTS 1 Introduction architecture process Supported source control management (SCM) clients Understanding what indexes Logging in Managing Users Understanding user roles Understanding permissions Creating a new user role Creating a new user account Adding roles to a user Creating user groups Using LDAP or Active Directory authentication Managing Projects Understanding how Code Site connects to repositories Understanding projects Creating a project Configuring the connection to a code repository AccuRev Bazaar Borland StarTeam CVS File system adapter Git IBM Rational ClearCase Mercurial Microsoft Team Foundation Server (TFS) Perforce Subversion Zip archive adapter and other version control systems Page i

4 Table of Contents 3.5 Modifying a project Understanding project access Restricting who can search a project Adding team members to a project Hiding a project from search Understanding project crawling Understanding indexing schedules Setting the global indexing schedule Set the indexing schedule for a specific project Excluding a project from indexing Forcing to index a project Viewing project history Deleting a project Configuration Settings Configuring indexing settings Creating a global indexing schedule Configuring indexing to ignore directories and files Configuring SCM connection timeout Configuring settings Configuring proxy settings product registration Activating Reactivating Configuring updates Managing the Server Disk space requirements and usage Startup, configuration, and log Files Stopping and starting the Tomcat server running on Linux Stopping and starting the Tomcat server running on Windows Configuring password strength Enabling the consistency checker Backing up the database Creating a database backup on Linux Page ii

5 Table of Contents Creating a database backup on Windows Restoring the database on Linux Restoring the database on Windows APPENDIX A Data Gathered by APPENDIX B Using and Configuring LDAP or Active Directory B.1 Configuring to use LDAP or AD B.2 Importing and synchronizing users B.3 Granting roles to groups of users B.4 LDAP configuration examples B.4.1 Authentication searches directly below a domain component node B.4.2 Authentication searches restricted to a branch node Page iii

6 Preface PREFACE Target audience This manual is intended for the administrator responsible for configuring and managing Black Duck. Most of the setup described in this book is done using the Admin section of the user interface. You must log in to using an account that has been granted a role with administrative privileges to access this area. Related documents The documentation for consists of: Title File Description Installation Guide InstallationGuide.pdf Detailed installation instructions for. Release Notes RelNotes.pdf Description of what has changed from the previous release of. System Administrator s Guide AdminGuide.pdf Describes administrative and configuration tasks in. User s Guide UserGuide.pdf Describes how to use the search web page. SDK Code Examples Customizing the Code Sight User Interface CodeSightSDK_Examples.pdf Customizing_Code_Sight_UI.pdf Describes how to install the SDK and contains code examples. Note: The SDK documentation is available with a standard license, but the SDK requires a special license to run. Describes how to enable UI customization and provides some general examples of the types of customization that are commonly requested. The documentation for is included in the top-level directory of the installation media. After installation, the PDF guides are located in C:\Program Files\Black Duck Software\CodeSight\doc. Note: This directory may vary depending on your operating system. You can also access the PDF guides from links on the Welcome page in the online help. Page iv

7 Preface Customer support There are three versions of available, differentiated by license: A free unregistered version, which lets you index 200,000 lines of code. A free registered version with a trial license with limits set forth at: Support for the free versions is provided using the online support forum at: An enterprise version, which allows for potentially unlimited indexing (limited per your license agreement). Support for the enterprise edition is provided through the online support forum and through the regular Black Duck Technical Support channels: support@blackducksoftware.com Phone: , ext. 5 Fax: Page v

8 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. makes it easy for software developers to find code in source code repositories that they have access to. Once you have found a useful file or snippet, download it for use in a new project. Tip: 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 search engine with an index of billions of lines open source code. 1.1 architecture Black Duck is a web application. A implementation consists of several different components that work together: Database: uses an industry-standard PostgreSQL database. installs a dedicated local instance of PostgreSQL for its own use. stores local copies of the files downloaded from your repositories. Server: uses an Apache Lucene Solr search server that runs within an Apache Tomcat application server. User interface: uses a web-based user interface for both searching (Search home page) and configuration and administration (Admin pages). Users with Administrator privileges can create and manage users, define projects and code locations, and schedule crawling, indexing, and publishing. In addition, has a software development kit (SDK). The SDK lets you integrate development into your native development processes. It provides API access to development features and services. Page 1

9 Introduction 1.2 process In order to configure and troubleshoot, it is helpful to understand the Crawl/Index/publish cycle that employs. The process flow is as follows: 1. Your system administrator installs and any source control management (SCM) clients needed to access your repositories. 2. Your system administrator configures to access your company s code repositories. This involves the following: a. Creating projects. The project definition includes connection strings, which tell how to access your code from one or more SCM repositories. b. Setting up a schedule for how often should revisit the projects to look for new or updated files. 3. connects to your repository via an SCM adapter and crawls the source code in your projects. 4. records the source file metadata in the database and generates a Solr index. 5. checks the index for consistency and merges the index with any other project indexes. 6. publishes the merged index, making the new project data available for user searches. 7. Developers access the search page ( to search your repositories for code. 8. repeats the Crawl/Index/Publish cycle based on the schedule specified by the system administrator. 1.3 Supported source control management (SCM) clients supports the following open source and commercial SCM clients: AccuRev Bazaar Borland StarTeam CVS Git IBM ClearCase Mercurial Microsoft Team Foundation Server Perforce Subversion Note: File System Adapter and Zip are built into and do not require a client. Page 2

10 Introduction 1.4 Understanding what indexes As examines your projects, it indexes the following types of files: ActionScript Ada ASP ASP.NET Assembly 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, provides advanced parsing. This allows filtering to definitions and provides a special outline view. For the other languages it indexes, 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.5 Logging in No login is required for search in or run reports. However, to create and index projects, you must log in with a privileged account. To log in to 1. Launch a browser and navigate to the URL for your server, which should be sometime similar to the following: Page 3

11 Introduction 2. Select the Login link. 3. Enter your Username and Password and click Login. Note that passwords are case-sensitive. 4. Select the Admin link in the upper right corner. displays the administrative area, which is where you define how gets to the code it needs to index. The default page view is the Progress tab, which shows the current status of indexing on this machine. The status may show as RUNNING if the machine has been configured to run the indexer continuously, always looking for new projects. Alternately, indexing can be run at scheduled intervals. Page 4

12 Managing Users 2 MANAGING CODE SIGHT USERS Depending on your company policies for allowing access to code repositories, you can configure to allow or restrict user access to your projects and files: Any user can search and access projects and files (no user ID required). Only logged in users can search and access projects and files. Only named users can search and access files for a project. You configure the list of named users for each individual project. Users are allowed access to projects based on their user roles. Roles are either system-wide (overall roles) or project-level (project roles). 2.1 Understanding user roles You use roles to grant user permissions to features and actions within. has two different types of roles: Overall roles grant global permissions that are applicable throughout. Project roles grant permissions that apply only to an individual project. comes with three pre-configured user roles with varying permission levels. When you create a new user, you assign one or more roles to the user ID to grant the user permissions to various pages and actions within. The default overall roles are: Administrator Indexer Project Searcher (This is the default role.) The pre-configured roles are locked and cannot be edited or deleted. You can, however, create custom roles and assign them to users as appropriate for your business needs. You can create both custom overall and project-specific roles. Page 5

13 Managing Users Understanding permissions Table 1 shows the combinations of permissions in the default system roles. Table 1 Permission matrix Project Role Overall Role Can read registration settings Can change registration settings Project Searcher Can read user-management configuration data X X Can have update access to user management configuration data Can create user management configuration data Can delete user management configuration data Can access the Admin area X X Can read application settings X X Can change application settings X X Can create a project X X Can start/stop the index engine X X Can publish (index data for projects) X X Can see the team members on a project X X Can assign team members to a project X X Can search the code of a project X X X Can read project data X X Can update project data X X Can delete a project X X Can index a project X X Can schedule a project (indexing) X X Can show/hide a project X X Indexer X X X X X Administrator Most of the permissions are quite specific and allow access to individual controls within. 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. Page 6

14 Managing Users Creating a new user role You may want to create new, custom roles with different combinations of permissions than the default system roles. In general, when combining permissions to create a role: If you have delete access, you should also have read, update, and create access. If you have create access, you should also have read and update access. If you have update access, you should also have read access. Read access can stand alone. Caution: Many pages within are tied to various permissions. If you turn these permissions off, you cannot see the pages. If you are creating custom roles to use instead of the default roles, make sure that your new roles provide access to all of the existing permissions and do not leave any holes, that is, a permission not covered by a role. 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 go to the Admin Users Roles page to turn the permission back on. To create a new user role 1. Log in to as a user with administrator privileges. If you have not yet created an administrator account, you can use the pre-configured default account: User name: sysadmin Password: blackduck 2. Select the Admin link in the upper right corner. 3. Select the Users Roles tabs. 4. Click Create Role. The Create a Role dialog box opens. Page 7

15 Managing Users 5. Enter a name for the role. 6. Enter a description for the role. 7. Specify whether the role is overall (system-wide) or will be specific to a particular project. 8. Select one or more check boxes to set permissions for the role. 9. Click Save. Page 8

16 Managing Users To modify a user role 1. Log in to as a user with administrator privileges. 2. Select the Admin link in the upper right corner. 3. Select the Users Roles tabs. 4. In the Roles table, highlight the role to select it. 5. To delete the role, click Delete Role. 6. To modify the role, edit the role and click Save. 2.2 Creating a new user account Notes: includes a default system administrator s account. Black Duck recommends changing the default password immediately after installation. - The default administrator 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, 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. Table 2 shows the data contained in a user record. You are only required to enter a user name and password in order to create a user record. 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. Table 2 User Account Fields Field *Username *Password *Password Confirmation First Name Last Name Description 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. Passwords are case-sensitive, and cannot be blank. They do not expire. By default, does not enforce any restrictions on user names or passwords. For information about enforcing password requirements, see Configuring Password Strength on page 52. This field needs to match the password entered above. The user s full name is useful for identifying an individual by more than just their user name. displays the user s name in the Users table on the Users Users tab and in dialog boxes that let you select a user. (see previous) Page 9

17 Managing Users Field Address Job Title Phone Location Active Description The address is useful as a reference. It is not currently used within the product. The job title for a user is useful as a reference. displays the job title in the Users table on the Users Users tab. The phone number is useful as a reference. It is not currently used within the product. 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. An account must be set to active to enable logins. Tip: First and last names and job title are only displayed in the Users section. It is useful to add the user s first and last name, so that when you are adding users to a group you can identify the individual by more than just the user name. To create a new user account 1. Log in to as a user with administrator privileges. If you have not yet created an administrator account, you can use the pre-configured default account: User name: sysadmin Password: blackduck 2. Select the Admin link in the upper right corner. 3. Select the Users Users tabs. 4. Click Create User. The Create a New User dialog box opens. Page 10

18 Managing Users 5. Enter a unique user name for the account. 6. Enter a password for the user. 7. Optionally, enter any additional information that you want to record about the user. 8. Click Save. By default, all user accounts have the Project Searcher role assigned to them. Typically, users have distinct needs depending on their project assignments, and therefore you can assign multiple overall and project roles to each user Adding roles to a user After you create an account, you must add roles to the account that permit access to projects and repositories. You can view the roles assigned to a user on the Users Users Roles tab. Note: All users have the Project Searcher role by default. This role is not displayed on the Users Users Roles tab. See Figure 1. Page 11

19 Managing Users Figure 1 New user account with no roles To assign overall roles to a user ID 1. Log in to as a user with administrator privileges. 2. Select the Admin link. 3. Select the Users Users tabs. 4. In the Users table, click the user name to select it. 5. Select the Roles subtab. Page 12

20 Managing Users 6. Click Add Overall Role. 7. Select one or more roles. 8. Click Save. 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. To assign project roles to a user ID 1. Log in to as a user with administrator privileges. 2. Select the Admin link. 3. Select the Users Users tabs. 4. In the Users table, click the user name to select it. 5. Select the Roles subtab. 6. Click Add Project Role. Page 13

21 Managing Users 7. Select one or more roles. 8. Select one or more projects. Note: For project-specific roles, you must indicate both the role and the project name. 9. Click Save. 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. 2.3 Creating user groups A user group is an easy way to configure multiple user accounts with the same roles. To create new user group 1. Log in to as a user with administrator privileges. 2. Select the Admin link. 3. Select the Users User Groups tabs. 4. Click Create User Group. Page 14

22 Managing Users 5. Enter a group name. 6. Click Save. The next step is to assign permissions to the group by assigning roles. To assign users to a user group 1. On the Users User Groups tab, click a user group to select it. 2. If necessary, in the bottom half of the page, scroll until you can see the Group Members table. 3. Click Add Member. 4. Select one or more members to add to the group. 5. Click Save. Note: Any time you modify users roles, they must log out and log back in again to see the changes take effect. To assign permissions to a user group 1. On the Users User Groups tab, highlight a user group to select it. 2. If necessary, in the bottom half of the page, scroll until you can see the Roles tables. Page 15

23 Managing Users 3. To add system roles to the group: a. Click Add Overall Role. b. Select one or more roles. c. Click Save. 4. To add project roles to the group: a. Click Add Project Role. b. Select one or more roles. c. Select one or more projects. d. Click Save. Note: If users already belong to the group, they will need to log out and log back in to see the changes take effect. Page 16

24 Managing Users 2.4 Using LDAP or Active Directory authentication supports authentication using its own standard username and password scheme. It also supports using lightweight directory access protocol (LDAP) or Active Directory (AD). See Appendix B Using and Configuring LDAP or Active Directory for details on configuring this feature. Page 17

25 Managing Projects 3 MANAGING PROJECTS In order for users to be able to search your code, you must configure to know where your source files are, and how it can access them. The basic entity within is the project. A project describes the location of your source files, which users can access them, and how often the files should be crawled and indexed. 3.1 Understanding how Code Site connects to repositories Your source files likely reside in a remote SCM repository. Within, you create a project, which points to locations within your repositories. The system where the server is installed must have the client software installed for the repositories and that client software must be in the path visible to the process. 3.2 Understanding projects A project is the basic entity within. In a project record only requires a name and the connection information for the repository. You can enter multiple source code locations for a single project. These can be separate subdirectories, branches, or completely different source control management repositories. During the crawling phase, visits each location (in the order you enter them) and retrieves the files. visits each repository as directed by the project s overall schedule. Note: You can also create a project with no source code. 3.3 Creating a project Tip: Always enter useful information in the Project Description field, because this text is searchable. To create a project 1. Log in to as a user with administrator privileges. 2. Select the Admin link in the upper right corner. Page 18

26 Managing Projects 3. Select the Projects tab to view the projects already configured on this system. 4. Click Create Project. The Project Setup dialog box opens. 5. Enter a unique name for the project. Note that the name and description are both searchable. 6. Enter the connection details for the repository containing the project. Page 19

27 Managing Projects Note: For information about configuring and connecting to SCM clients, see Configuring the Connection to a Code Repository. If your repository does not require a username and password, you can leave those fields blank. 7. Optionally, you can enter multiple locations for where your source code is located. a. Select the Add Code Location link. b. Enter the connection details for the repository containing the project. 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. c. To add additional code locations, repeat steps a through b for each code location. 8. Optionally, in the Advanced Settings section, you can restrict the search visibility (who can search the project). Page 20

28 Managing Projects 9. Optionally, in the Advanced Settings section, you can change the indexing schedule (schedule of how often the project is crawled by ). 10. Click Save. 3.4 Configuring the connection to a code repository The system where the server is installed must have the client software installed for the repositories, and that client software must be in the path visible to the process. Note: 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. has built-in support for several different SCM systems, as well as the File System Adapter that can be used with almost any version control system. The Settings SCM Settings tab (see Figure 2) shows a list of the clients that has detected on your system. The File System and Zip adapters are built into. Page 21

29 Managing Projects Figure 2 SCM settings Tip: The link at the bottom of the tab takes you to the topic in the online Help system where you can find additional information about each supported repository client. SCM repositories used with have several common aspects. Depending on the SCM type, these fields may be separate or may be combined into the connection string. The connection string for a repository is similar to the command you would use to interactively connect to the repository. In order to connect to a code repository, you will need the following information: Username/password you use to access the repository Connection string of the SCM client Note: The connection string for a repository is similar to the command you would use to interactively connect to the repository. Tip: The online Help system includes examples for connecting to an open source repository of each supported type. Branch or tag where your source code is located within the repository Page 22

30 Managing Projects AccuRev Tips: - Always make sure the AccuRev executable is in your path. - Visit 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] Bazaar 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: Example Connection String (anonymous user): Borland StarTeam Tips: - Always make sure the Borland StarTeam executable is in your path. - Visit for more information. The standard connection information for a Borland StarTeam repository looks like the following: Username: user Password: ***** Connection String: host:49201/project[view/folder] CVS 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:anoncvs@cvs.apache.org:/home/cvspublic Berlios connection string :pserver:anonymous:@cvs.projectname.berlios.de :/cvsroot/ Page 23

31 Managing Projects Mozilla connection string Enter the following on a single line for the Connection Template field on the Add/Edit Repository page: :pserver:anonymous:anonymous@cvs-mirror.mozilla.org:/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:anonymous@forgecvs1.novell.com:/cvsroot/. Note: The period (.) at the end of this template is used to represent all modules for the given CVS root File system adapter The file system adapter enables to index source code stored on a local machine. The file system adapter acts as a universal adapter, allowing you to use with any SCM application. Simply access your repository and retrieve the files to a local directory, then point 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 Git Tip: You do not need to download a Git client. This functionality is included in your 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 set 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 Page 24

32 Managing Projects full project path in the connection string IBM Rational ClearCase Tip: Download IBM Rational ClearCase or the IBM Rational ClearCase Remote Client and make sure it is in your path. Template: PathToView\VobName$SubPath Example: c:\views\someview\sources$initialcomponent\ Note: The adapter assumes PathToView contains a valid and configured ClearCase View. Using the Remote Client: Username: username@domain.com Password: ****** Connection String: C:\view\myView\myVOB$mycmpnt\ Or, you can combine the fields into a single connection string: --username user@bds.com --ser --pas changeme M:\MyFirstUCMView\ Mercurial Tip: Download Mercurial and make sure it is in your path. Template: Example Connection Template: Example Project Path: hgweb/octave/ Microsoft Team Foundation Server (TFS) Tips: - Always make sure the TFS executable is in your path. - A TFS client cannot go beyond 259 characters. - Go to 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@ The password component is optional. Server specification is typically a UNC path or http path with a port specified following a colon (as in TFS uses a web services base, so users having poor luck or inconsistency with UNC paths may find using an http specification easier Perforce Tip: Download Perforce and make sure it is in your path. Page 25

33 Managing Projects 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/ Subversion 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 Code.Google.com connection string Or, depending on your specific project, you may need to specify a branch instead. In this case, use the /tags qualifier instead of /trunk: For example, a sample connection string is: co 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 to access the project files Zip archive adapter The Zip archive 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, so 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. Page 26

34 Managing Projects and other version control systems can be used with other version control systems as well. When integrating with other version control systems, use the file system adapter. 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. 3.5 Modifying a project After a project has been created, you can edit the information and schedule. To modify a project, complete the following steps: 1. Log in to as a user with administrator privileges. 2. Select the Admin link in the upper right corner. 3. Select the Projects tab to see the projects already configured on this system. 4. Highlight a project name to select it. 5. In the lower half of the screen, select the Setup subtab. 6. Click Edit Project. The Edit Project Setup dialog box contains the same fields as the Create Project Setup dialog box. Page 27

35 Managing Projects 7. Modify the project definition as appropriate. 8. Click Save. 3.6 Understanding project access You can set up your project for user-based search access. Rather than allowing everyone to search the project code, you can restrict access to a list of named users or user groups. You can also hide a project from all searchers Restricting who can search a project You can restrict who can search a project when you first create it or you can modify this setting for existing projects. To restrict project search to named users/groups, complete the following steps: 1. Log in to as a user with administrator privileges. 2. Select the Admin link in the upper right corner. 3. Select the Projects tab to see the projects configured on this system. 4. Select the checkbox for the project in the Projects table. 5. From the More actions menu, select Restrict for search. Page 28

36 Managing Projects 6. Alternately, you can Select the Setup tab and edit the project to change the Search Visibility setting to Restricted. The project will only be visible to users listed as a Team Member on the project. Page 29

37 Managing Projects 7. Add users to the list of team members for the project. For instructions, see Adding Team Members to a Project Adding team members to a project When you set the Search Visibility setting for a project to Restricted, the only users who can search the project are users or groups listed on the Team Members tab for the project. To add team members to a project, complete the following steps: 1. On the Projects tab, highlight the project name to select it. 2. In the lower half of the screen, select the Team Members tab. 3. To add a user to the project, click Add User. The Add User to Project dialog box opens. Page 30

38 Managing Projects a. Highlight a user name to select it. b. Select one or more roles for the user. c. Click Add User. The change takes effect immediately. 4. To add a user group to the project, click Add User Group. a. Highlight a user group to select them. b. Select one or more roles for the user group. c. Click Add User Group. The change takes effect immediately. Note: You can also use the Users tab to add the project to the user s record or the User Groups tab to add the project to a user group s record Hiding a project from search 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 project from all searchers, complete the following steps: 1. Log in to as a user with administrator privileges. 2. Select the Admin link in the upper right corner. 3. Select the Projects tab to see the projects configured on this system. 4. Select the checkbox for the project in the Projects table. 5. From the More actions menu, select Hide for search. Page 31

39 Managing Projects 6. Alternately, select the Setup tab and edit the project to change the Search Visibility setting to Hide. The project will be hidden from all users searching. Page 32

40 Managing Projects 3.7 Understanding project crawling Once you have defined a project, the next step is to have examine the source files (also known as crawling ) and then index the project. During this process, 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. The system administrator specifies which projects or repositories that is allowed to crawl and sets the schedule for when it should happen. 3.8 Understanding indexing schedules When you create a project or add and save a new source code location, immediately performs an initial crawl and index of the project. After that, will revisit the project based on the default global schedule. You can modify a project to use its own indexing schedule. The indexing schedule can be configured on a per-project basis, that is, each project can have a different indexing schedule. There are several ways to start the indexing process for a project: Immediately when the project is created. Based on a global schedule. By default, projects are revisited based on the global schedule. Tip: The No schedule setting can be used to disable indexing. Based on an individual schedule. On-demand with the Index Queue for next job action Setting the global indexing schedule The Settings Index Settings subtab (see Figure 3) controls the global schedule of how often Code Sight indexes your projects. It also controls which files should be ignored during the crawl. By default, when the indexing job completes, publishes the new index automatically. To keep your old index, clear the Auto Publish checkbox. This may be useful if you want to temporarily freeze the index in its current state. Page 33

41 Managing Projects Figure 3 Index Settings subtab To set the default (global) indexing schedule 1. Log in to as a user with administrator privileges. 2. Select the Admin link in the upper right corner. 3. Select the Settings tab. 4. Select the Index Settings subtab. 5. Click Global Schedule. The Global Indexing Schedule dialog box opens. 6. Specify how often you want to index your projects. Tip: The No schedule setting can be used to disable indexing. 7. Click Save Set the indexing schedule for a specific project By default, projects are revisited based on the global schedule. You can modify a project to use its own schedule. Page 34

42 Managing Projects To specify the indexing schedule for project 1. Log in to as a user with administrator privileges. 2. Select the Admin link in the upper right corner. 3. Select the Projects tab to see the projects already configured on this system. 4. Highlight a project to select it. 5. In the lower half of the screen, select the Setup subtab. 6. Click Edit Project. The Edit Project Setup dialog opens. 7. In the Advanced Settings Indexing Schedule section, specify how often you want to index this project. 8. Click Save Excluding a project from indexing At certain times you may want to freeze the current state of the project and disable indexing. To exclude a project from indexing 1. Log in to as a user with administrator privileges. 2. Select the Admin link in the upper right corner. 3. Select the Projects tab to see the projects already configured on this system. 4. Highlight a project to select it. Page 35

43 Managing Projects 5. In the lower half of the screen, select the Setup subtab. 6. Click Edit Project. The Edit Project Setup dialog opens. 7. In the Advanced Settings Indexing Schedule section, select No schedule. 8. Click Save Forcing to index a project There may be times when you want to index a project at a time other than the scheduled frequency or you may want to force to index a project that had been previously excluded from indexing. To force to index a project 1. Log in to as a user with administrator privileges. 2. Select the Admin link in the upper right corner. 3. Select the Projects tab to see the projects already configured on this system. 4. If necessary, use the Search field on the Projects tab to locate the project. 5. Select the checkbox next to the project that you want to index. 6. From the More actions menu, select Index Queue for next job. Page 36

44 Managing Projects 3.9 Viewing project history You can track the status of your projects with the Projects History subtab (see Figure 4). This page shows the operations that has performed (crawl, index, and publish) and any warnings that were generated. Page 37

45 Managing Projects Figure 4 Viewing the project history 3.10 Deleting a project When you delete a project it is no longer searchable. will fully remove the project the next time the index is updated (published). To delete a project 1. Log in to as a user with administrator privileges. 2. Select the Admin link in the upper right corner. 3. Select the Projects tab to see the projects already configured on this system. 4. If necessary, use the Search field on the Projects tab to locate the project. 5. Select the check box next to the project name. 6. From the More actions menu, select Delete. Page 38

46 Managing Projects 7. In the confirmation message, click OK. Page 39

47 Configuration Settings 4 CODE SIGHT CONFIGURATION SETTINGS This chapter describes configuration settings for the server. The Admin Settings tab contains product configuration settings. In general, these settings only need to be configured once, before doing any other tasks on your system. 4.1 Configuring indexing settings The Admin Settings Index Settings tab (see Figure 5) controls the global schedule for how often should index your projects. You also use this tab to configure which files should ignore while indexing. Figure 5 Index settings By default, when the indexing job completes, the new index is published automatically. You can clear 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 Creating a global indexing schedule The global indexing schedule controls how often revisits the projects in your repositories to scan for changes that require re-indexing. To set the global indexing schedule 1. Log in to as a user with administrator privileges. 2. Select the Admin link in the upper right corner. 3. Select the Settings tab. 4. Select the Index Settings subtab. 5. Click Global Schedule. Page 40

48 Configuration Settings 6. In the Global Indexing Schedule dialog box, specify how often you want to index this projects 7. Click Save. Tip: You can also set an individual schedule by creating a project schedule after the project has been created. See Set the Indexing Schedule for a Specific Project for details Configuring indexing to ignore directories and files 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 which files should ignore during indexing. By default, 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, correctly looks inside the archive to find and index your non-binary files. The following file types are ignored by default: bmp doc gzip lib xls chm exe jar pdf zip com gif jpeg png dll gz jpg tar 4.2 Configuring SCM connection timeout The Admin Settings SCM Settings tab (see Figure 2) lists the SCM clients installed on your system and detected by. If cannot access your SCM client software, then it will not show that repository type when you are adding the source location to your project. The File System, Git, and Zip clients are built into and are always present. Tip: You can set the timeout variables to prevent long delays when there are problems connecting to remote repositories. Page 41

49 Configuration Settings 4.3 Configuring settings You use the Admin Settings Mail Settings tab (see Figure 6) to define how should send to the system administrator. Currently, this is only used after a failure of an automatic upgrade. Figure 6 Mail settings Administrator Address: 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: sent from comes from this address. SMTP Username and Password: Used to connect to your mail server. 4.4 Configuring proxy settings You use the Admin Settings Proxy Settings tab (see Figure 7) to specify how should access the servers at Black Duck Software. This connection information is needed for license verification and for downloading updates. Figure 7 Proxy settings 4.5 product registration There are three registration options for using : Free Unregistered: You are limited to indexing 200,000 lines of code. You can obtain a free Page 42

50 Configuration Settings registration key by visiting Free Registered: See the limits set forth at: Paid Registration: You are allowed to index projects 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 you register immediately after installation. However, it is not required. If you do not register, the software behaves normally, except that it stops publishing after reaching 200,000 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: Activating To activate your license 1. Have your enterprise or free license key ready. 2. Log in to as a user with administrator privileges. 3. Select the Admin link in the upper right corner. 4. Select the Settings tab. 5. Select the Product Registration subtab. 6. Click Activate. Page 43

51 Configuration Settings 7. On the registration page, enter your registration ID and the connection details specifying how your installation of will contact Black Duck for updates. 8. Click Register. Note: Your license may include an expiration date. After that time has passed, you can continue to search your projects, but further publishing is disabled Reactivating If you want to change your registration at a later time, go to Admin Settings Product Registration (see Figure 8). Enter your new registration ID and click Reactivate. Page 44

52 Configuration Settings Figure 8 Product registration Note: Your license may include an expiration date. After that time has passed, you can continue to search your projects, but further publishing is disabled. 4.6 Configuring updates Note: You cannot update your software until you have registered either a free or enterprise license. To perform a update 1. Log in to as a user with administrator privileges. 2. Select the Admin link in the upper right corner. 3. Select the Settings tab. 4. Select the Update Status tab. displays a page where you can select update times and Page 45

53 Configuration Settings a list of the most recent updates available. 5. From the Auto Install Software Update menu, select when you want new updates to be downloaded and installed: Never: You will never get updates. During Scheduled Times: You will get updates only during the times that you configure in the Day Settings section. When Available: You will get updates when they are available. 6. In the Day Settings section, specify when your 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. 7. If you want to download and install manually, and if there are updates available, select 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. 8. Select the Install link to integrate this update into your system. 9. 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. Page 46