BLUEPRINT REQUIREMENTS CENTER 2010 BLUEPRINT TEAM REPOSITORY VERSION 2 September 2010
Contents Introduction... 2 Repository Configuration Files... 3 User Administration... 5 Appendix A. Instructions for LDAP Installations... 12 Appendix B. Starting and Stopping Apache... 14 Appendix C. HTPASSWD Reference... 15 Copyright 2010 Blueprint Software Systems Inc. This document contains confidential and proprietary information of Blueprint Software Systems, Inc. and is intended only for the person(s) to whom it is transmitted by Blueprint Software Systems Inc. Any reproduction or retransmission of this document or the information contained herein, in whole or in part, without the prior written consent of Blueprint Software Systems, Inc. is expressly prohibited. Blueprint Software Systems, Inc. reserves all right, title and interest in this document and the information contained herein. Unless otherwise set out in a written agreement between Blueprint Software Systems, Inc., and a recipient of this document, Blueprint Software Systems Inc. makes no representations or warranties with respect to the completeness or accuracy of the information contained herein and shall not under any circumstances, be held liable for any damages howsoever caused by reliance thereon. Blueprint Software Systems, Inc. 372 Bay Street, Suite 1600 Toronto, Ontario M5H 2W9 1
Introduction This document provides instructions for configuring users and permissions for the Blueprint Team Repository. For detailed additional information on installing the Blueprint Team Repository, please refer to the following document, available from the Blueprint Products download page: Blueprint Team Repository Version 2 Installation and Configuration Guide Before You Begin Updates to Blueprint Team Repository software and documentation are made available periodically. Please check the Blueprint Product downloads page for updates, and select the appropriate files. Directories & File Names: This document uses the directory locations and file names pre-selected by the application. If you select different locations or file names, remember to substitute your own choices when following the instructions. 2
Repository Configuration Files In order to configure or troubleshoot your repository, there are several files you will need to access, as follows: Apache Web Server Configuration File: httpd.conf Subversion Repository Configuration File: BTR.conf Subversion Repository Access File: svn-access-file Subversion Repository Authorization File: svn-auth-file Apache Web Server Configuration File The httpd.conf file is the main configuration file for the Apache Web Server. It provides the web server with information about your Subversion installation and repository installation, for user authentication and other web services. In a default installation, this file is located in the following directory for your operating system: Windows 7: C:\Program Files (x86)\collabnet\subversion Server\httpd\conf Windows XP: C:\Program Files\CollabNet\Subversion Server\httpd\conf Windows 2003 Server: C:\Program Files\CollabNet\Subversion Server\httpd\conf Subversion Repository Configuration File This configuration file, also referred to as the LOCATION BLOCK, provides information to the Apache Webserver about the Subversion Repository Server. In a default installation, this file is located in C:\BTR\BTR.conf This file provides the following: 1. Establishes a portion of the URL alias 2. Identifies the location of the repository 3. Identifies the location of the access file (svn-access-file) 4. Identifies the location of the authorization file (svn-auth-file) 5. Identifies the security policy 3
Subversion Repository Access File The Access file, also referred to as the ACL file, defines user permissions for the repository. In a default installation, this file is located in C:\BTR\svn-access-file For more information, see the section User Permissions. Subversion Repository Authorization File This is an encrypted file in which user credentials are stored by the system. In a default installation, this file is located in: C:\BTR\svn-auth-file IMPORTANT: Do not edit, move, or delete this file. The system must have read-write access to this file. 4
User Administration When a user requests access to the system, there are two conditions the server must be able to resolve: Authentication Permission The system first validates the authenticity of the user through authentication of a username and password combination. For a basic Blueprint Team Repository implementation, authentication is performed by the Apache Web Server. Alternatively, you may choose to configure the Apache Web Server to utilize LDAP for user authentication. User Authentication To implement the basic authentication system, the Apache utility htpasswd is used to generate and maintain user credentials. These credentials are maintained in an encrypted file. Adding Users * The following does not apply to a LDAP implementation. 1. Launch a command prompt. 2. Navigate to the \bin directory for Apache by typing the following: cd C:\Program Files(x86)\CollabNet\Subversion Server\httpd\bin 3. Enter the following, substituting <username> appropriately. htpasswd c:\btr\svn-auth-file <username> 4. Follow the prompts to provide and confirm the password. Resetting User Passwords 1. Launch a command prompt. 2. Navigate to the \bin directory for Apache by typing the following: cd C:\Program Files(x86)\CollabNet\Subversion Server\httpd\bin 3. Enter the following, substituting <username> appropriately. htpasswd c:\btr\svn-auth-file <username> 5
4. Follow the prompts to provide and confirm the new password. Removing Users 1. Launch a command prompt. 2. Navigate to the \bin directory for Apache by typing the following: cd C:\Program Files(x86)\CollabNet\Subversion Server\httpd\bin 3. Enter the following, substituting <username> appropriately. htpasswd -D c:\btr\svn-auth-file <username> User Permissions Permission is controlled by the Access file, also known as the ACL file. This file is maintained by the system administrator using any common text editor. IMPORTANT: This file is still required in an LDAP implementation. In its simplest form, each section names a repository and path within it, and then the authenticated groups/usernames and the options (R for read-only, W for read-write) for those groups/usernames. If the user is not mentioned at all, no access is allowed, assuming no implementation of wildcards i.e. [/] * = rw. Permissions are inherited from parent to child directories. Thus you can specify a sub-directory with a different access policy than its parent. The value of the section names are either: [repos-name:path] or [path] By default, the section name is root [/] and no user has any access to the repository at all. Therefore, if you are starting with an empty file, you will probably want to give at least read permission to all users at the root of the repository. You can do this by editing the ACL as follows. Note: use the asterisk variable (*) to represent ALL USERS. [/] * = r admin = rw This is a very common setup. This section name [/] directive makes all repositories readable to all users. Once all users have read access to the repositories, you can give explicit rw permission to certain users on specific subdirectories within specific repositories. In Project Access Examples; Example 1; [calc:/branches/calc/bug-142] is the section name. 6
Additionally, the user admin has been provided write access at the root of the repository, and will therefore be responsible for creating parent folders for all projects. Do You Need Path-Based Access Control? Administrators setting up Subversion for the first time often establish path-based access control. The administrator usually knows which teams of people are working on which projects, so it is easy to grant certain teams access to certain directories and not others. There are often costs associated with this feature. Firstly, the server needs to do a lot more work to ensure that the user has the right to read or write each specific path. In certain situations, there may be a noticeable performance loss. Secondly, unwanted barriers to collaboration may be established by over-enforcing path-based access control. Teams often spontaneously collaborate with each other; someone may want to help someone else by committing to an area she doesn't normally work on. Finally, path-based control rules need to be maintained as projects develop, new users are added, and so on. The net result can be extra work. As you are working with a version control system, it is useful to remember that even if somebody accidentally commits a change to something they should not, it is easy to undo the change. Project Access Examples Example 1 Configure a subdirectory for full access by one user and read-only access for a different user. [calc:/branches/calc/bug-142] Harry = rw Sally = r The user Harry has full read and write access on the /branches/calc/bug-142 directory in the calc repository. The user Sally has only read access on the same branch. Example 2 Specify a sub-directory with different access rights. 7
Permissions are inherited from parent to child directory; therefore you can specify a subdirectory with a different access policy for Sally. [calc:/branches/calc/bug-142] Harry = rw Sally = r [calc:/branches/calc/bug-142/testing] Sally = rw Sally can write to the testing subdirectory of the branch, but can still only read other parts. Harry meanwhile continues to have complete read-write access to the whole branch. Example 3 Specify a sub-directory with explicit denial rights. You may also want to explicitly deny permission to someone via inheritance rules by setting the group/username variable to do nothing. [calc:/branches/calc/bug-142] Harry = rw Sally = r [calc:/branches/calc/bug-142/secret] Harry = Harry can write to the entire bug-142 tree Harry has absolutely no access to the secret subdirectory within it. Groups The access file also allows you to define whole groups of users; for example: [groups] calc-developers = harry, sally, joe 8
paint-developers = frank, sally, jane everyone = harry, sally, jane, joe, frank Groups can be granted access control just like users. Distinguish them with an at @ prefix. [calc:/projects/calc] @calc-developers = rw [paint:/projects/paint] @paint-developers = rw jane = r Groups can also be defined to contain other groups: [groups] calc-developers = harry, sally, joe paint-developers = frank, sally, jane everyone = @calc-developers, @paint-developers Single Repository Example The following depicts a model using one repository. Each group has visibility only to their own projects. They have no read access to projects outside their group. [groups] Administrators = admin, TeamA =user1, user2, user3, user4, user5, TeamB = user6, user7, user8, user9, user10 TeamC =user11, user12, user13, user14, user15, [/] 9
* = r @administrators = rw [projects:/group1projects/] @TeamA = rw @TeamB = @TeamC = [projects:/group2projects/] @TeamA = @TeamB = rw @TeamC = [projects:/group3projects/] @TeamA = @TeamB = @TeamC = rw Multiple Repository Example The following depicts a model using multiple (3) repositories. Each group has visibility only to their own repository. They have no read access to projects outside their group. [groups] Administrators = admin, TeamA =user1, user2, user3, user4, user5, TeamB = user6, user7, user8, user9, user10 TeamC =user11, user12, user13, user14, user15, [/] 10
* = r @administrators = rw [projects1:/projects/] @TeamA = rw @TeamB = @TeamC = [projects2:/projects/] @TeamA = @TeamB = rw @TeamC = [projects3:/projects/] @TeamA = @TeamB = @TeamC = rw 11
Appendix A. Instructions for LDAP Installations Adapting Apache (httpd.conf) for LDAP In standard installations, the following lines are added to the end of the httpd.conf : # Blueprint Team Repository [22_16.1] Include C:/BTR/BTR.conf #Include C:/BTR/BTR-LDAP.conf If authentication for your installation will occur against an LDAP server, modify the lines above to look like the entry below: # Blueprint Team Repository [22_16.1] #Include C:/BTR/BTR.conf Include C:/BTR/BTR-LDAP.conf Note: only the # has been moved to include BTR-LDAP.conf & exclude BTR.conf Specifying LDAP Bind User In C:\BTR\BTR-LDAP.conf, specify your LDAP bind user name. The sole purpose of this account is to allow the Apache web server to bind to your LDAP server. An example of how to create an LDAP bind user follows: AuthLDAPBindDN "CN=AD SVN User,OU=People,OU=Toronto,DC=blueprint,DC=toronto" AuthLDAPBindPassword "Blueprint99" Specify your installation s authentication criteria in this line: AuthLDAPURL "ldap://bpsdcneo/dc=blueprint,dc=toronto?samaccountname?sub?(objectclass=*)" Please note: the entries stated in the lines above are examples only. They should be substituted with information pertaining to your own LDAP server. 12
LDAP Glossary The table below details a limited number of LDAP attributes that you should be familiar with before configuring users or modifying LDAP configuration files. We used the name Steve Smith as an example entry in our LDAP directory throughout the table. LDAP Attribute CN - Common Name givenname name samaccountname SN c company department OU DN or distinguishedname Example CN=Steve Smith. This LDAP attribute is made up from the givenname joined to SN. Firstname also called Christian name name = Steve Smith. Exactly the same as CN. samaccountname ssmith. This is a Microsoft Active Directory (AD) Attribute and may be substituted in other LDAP implementations with UID SN = Smith. This would be referred to as last name or surname. Country or Region Company or organization name Useful category to fill in and use for filtering Organizational unit. See also DN DN a key LDAP attribute. E.g. CN=Steve Smith,OU=toronto,DC=blueprint,DC=toronto 13
Appendix B. Starting and Stopping Apache Starting/Stopping /Restarting Apache Methods to starting and stopping Apache Web Server on Windows XP, Windows 2003 Server & Windows 7 differ slightly. The method described in this document is consistent with the three operating system versions, but you may observe minor changes depending on the operating system you re working with. 1. Click the Start button (located at the bottom left hand corner of your windows Desktop). 2. Highlight Computer or My Computer. 3. Right mouse click and select Manage 4. Under Services and Applications select Services 5. Highlight CollabNet Subversion Apache 6. Right mouse click and choose to STOP, START or RESTART the Apache service. 14
Appendix C. HTPASSWD Reference The command htpasswd is a utility provided by Apache for managing the list of acceptable usernames and passwords. htpasswd was referenced earlier in the document for adding and deleting users. More details are provided below on the options that can be used with this utility. Example: In this example, the user johndoe is deleted (-D) from the Subversion authorization file. htpasswd -D c:\btr\svn-auth-file johndoe Usage: htpasswd [-cmdpsd] passwordfile username htpasswd -b[cmdpsd] passwordfile username password htpasswd -n[mdps] username htpasswd -nb[mdps] username password -c Create a new file. -n Don't update file; display results on stdout. -m Force MD5 encryption of the password (default). -d Force CRYPT encryption of the password. -p Do not encrypt the password (plaintext). -s Force SHA encryption of the password. -b Use the password from the command line rather than prompting for it. -D Delete the specified user. On Windows, NetWare and TPF systems, the '-m' flag is used by default. 15