2. Deployment Guide

Though you may have referred to the Deployment Checklist before or during an evaluation of Subversion Access Control we strongly recommend that you revisit the checklist and confirm that your system still meets all requirements.

Tip
Overlooked requirements are a common cause of difficult-to-diagnose setup problems that could take a lot of time more time to fix than you'll spend running through these checks.

2.1 Deployment Checklist

System setup
Operating Systems	We've tested the following operating systems: Fedora (32 or 64 bit): 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16 Red Hat Linux Enterprise Server (32 or 64 bit): 4, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8, 6, 6.1, 6.2, 6.3 Sun Solaris (32 or 64 bit): 9, 10, 11 Linux: Linux kernel 2.6 or higher CentOS: 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8, 6, 6.1, 6.2, 6.3 Windows Server: (32 or 64 bit) 2003, 2008 In principle, any operating system that can support a Java environment, Apache and Subversion.
Subversion server	Version 1.4 and above (we've tested up to version 1.6.13). Run the Apache Portable Runtime that matches your Subversion version. Certified Subversion Binaries are now available from WANdisco. Providing the latest builds, without the risks associated with Open Source distribution. Available as an uberAPP Subversion Access Control is now available in a version that integrates with uberSVN, WANdisco's free, easy-to-use Subversion ALM platform. Running Access Control with uberSVN Access Control is compatible with uberSVN "Chimneyhouse" Update 1 or later. Installation Access Control runs as a plugin on uberSVN. For the installation procedure follow our dedicated Guide to Installing Access Control on uberSVN. Disable SSL before Installation When run as an uberSVN plugin Access Control isn't compatible with uberSVN's SSL implementation. Before starting installation, ensure that SSL is disabled on the SVN Server screen. Once Access Control has been installed, use ProxyPass to re-enable SSL encryption - Read about ProxyPass in the uberSVN uberGUIDE
Subversion client	Any that are compatible with local Subversion servers.
Apache server	Your Apache server will need to be configured to handle Subversion repositories using the following paramenters: <VirtualHost *:8181> <Location /svnrepos> Order allow,deny Allow from 127.0.0.1 DAV svn SVNParentPath /tmp/dav AuthType Basic AuthName wandisco AuthUserFile /etc/httpd/conf/htpasswd Require valid-user </Location> </VirtualHost> AllowOverride None This tells Apache to ignore any .htaccess files that it finds on the file system. Order allow,deny Allow from 127.0.0.1 Sets default access state and tells Apache the order in which to processes permissions Following the Order allow deny with an Allow directive, so that only localhost is allowed access. Locking down the backend It's important that access to Subversion is locked down to ensure that users don't bypass the Access Control proxy. To this end we configure Apache to deny requests by default, but allow from localhost. AuthType Basic AuthName wandisco AuthUserFile /etc/httpd/conf/htpasswd Require valid-use Setting AuthType to basic ensures that authentication is required for Subversion acess. AuthName is used as a label on the authentication prompt telling the end-user what it is they're authenticating. AuthUserFile sets the location of the subversion password file. Require valid-use is used isntead of specifying valid user groups - it allows access to any user who exists in the password file who correctly enters their password.
System memory	Ensure RAM and swapping containers are at least four times larger than the largest Subversion file. Minimum: 2GB RAM; 4GB swapping container Minimum isn't Recommended By default, Access Control's Java process is allocated the following heap space: -Xms128m -Xmx1512m If you need to reduce the heap size you're probably not going to have a comfortable margin. Consider increasing your server's system memory. In case of problems getting Access Control running, you may need to alter the heap. Read Changing the default Java heap size If you need to reduce the heap size you won't be operating with a comfortable margin: consider increasing your server's system memory. Recommended: 4GB; 4GB swapping container Running with other apps In production you must always ensure that your system operates with a comfortable margin. The above memory recommendations don't take into account other applications that you may need to run on the server, notably when running Access Control with uberSVN. We recommend that you complete load testing and specify your server's memory based on peak usage.
Disk space	Subversion: Match to projects and branches. Checkouts: You need sufficient disk space to handle large, in-transit checkouts which may get buffered to a tmp directory beneath the replicator installation until that checkout has been completed. The required space can be calculated using the following guideline: Recommended storage = Number of clients checking out files(N) x average checkout sizes (Kilobytes)
File descriptor limit	Ensure hard and soft limits are set to 64000 or higher. Check with the ulimit or limit command.
Journaling file system	Replicator logs should be on a journaling file system, for example, ext3 on Linux or VXFS from Veritas. Alert NTFS is not a journaling file system: ext4 is a journaling file system, although its use of deferred writes makes it incompatible with Subversion MultiSite.
Max. User Process Limit	At least three times the number of Subversion users.
Java	Install JDK 6 (previously referred to as 1.6) or higher. We recommend using Oracle JDK 6. Alert Important: JDK 7 (AKA 1.7) is not compatible with Subversion Access Control. The problem may be fixed with the release of the first JDK 7 update, although this hasn't yet been confirmed.
Perl	Install version 5.6.1 or later. For Access Control: Perl::DBI module for Audit Reports other than Users and Groups. Alert Windows users: Use the 32bit edition of ActivePerl 5.8, even if you are running a 64bit Windows server. uberSVN Access Control When running Access Control through uberSVN, Perl is no longer a system requirement.
Audit reports	For reports other than Users and Groups, you'll need to use a database such as MySQL, and php.
mod_authz_svn	Optional but recommended. See Access Control - Using the Authz Module. Module may be bundled with your version of Apache.

2.2 Installation Procedure

Once you've checked through the deployment checklist and you're confident that your system meets all the requirements, run through the following section to get Subversion Access Control installed.

Tip
If you run into difficulties, be sure to check out our Knowledgebase before raising contacting Support.

1. Download the Access Control installation file "svnsec.tar.gz" from the WANdisco File Distribution website.

2. Create a home directory for the installation, e.g. /wandisco.

3. Extract the "svnsec.tar.gz" file to the wandisco folder.

4. The installation files are now in place, they are arranged in the following directory structure:

drwxr-xr-x 2 root root 4096 2010-08-12 13:54  audit
drwxr-xr-x 3 root root 4096 2010-08-12 13:42  bin
drwxr-xr-x 8 root root 4096 2010-08-13 13:04  config
drwxr-xr-x 3 root root 4096 2010-08-12 13:10  lib
rw-r--r-   1 root root 16237 2010-05-21 15:03 license.txt
drwxr-xr-x 2 root root 4096 2010-08-12 14:29  logs
drwxr-xr-x 3 root root 4096 2010-08-12 13:54  systemdb
rw-r--r-   1 root root 24 2010-07-21 13:05    version.txt

5. Copy your Subversion Access Control license.key file into the config directory.

    
-rw-r--r-- 1 root root  26165 2010-08-13 13:04 backup.xml
-rw-rw-r-- 1 User User    512 2010-08-12 15:46 license.key
drwxrwxr-x 2 User User   4096 2010-08-12 13:37 licenses
-rw-r--r-- 1 root root   3327 2010-05-21 15:03 log.properties
-rw-r--r-- 1 root root    366 2010-08-12 14:28 mailconfig.properties
drwxr-xr-x 5 root root   4096 2010-08-12 13:42 membership
drwxr-xr-x 2 root root   4096 2010-08-12 18:27 passwd
drwxr-xr-x 3 root root   4096 2010-08-12 13:42 prefs
-rw-r--r-- 1 root root   3047 2010-05-21 15:03 prefs-template.xml
-rw-r--r-- 1 root root   2813 2010-08-12 14:26 prefs.xml
-rw-r--r-- 1 root root  92160 2010-07-21 13:05 reports.tar
drwxr-xr-x 3 root root   4096 2010-08-12 13:42 scm
drwxr-xr-x 7 root root   4096 2010-08-12 14:29 security

6. Enter the bin directory and run the setup, using the command:

perl setup

******* Start WANdisco Logging **************
 version : unknown build unknown
 Default member id : 00000000-0000-0000-0000-000000000000
 current time : Fri Aug 06 12:20:03 CEST 2010
******* End Log header **********************

1281090002964 org.nirala.communication.transport.DConeNet.ListenReactor setupListener
INFO:  [listen-1] Listening on port : 0.0.0.0/0.0.0.0:6444

Point a web browser to http://10.2.5.124:6444/ to configure the product.

7. From a browser, enter the setup URL (http://<Server IP>:<port>). From the welcome screen, click Continue.

8. Read the WANdisco End User License Agreement, then click I Agree.

9. The next two screens introduces you to the notion that Access Control works as a proxy between the clients of Subversion users and the Subversion server. Subversion users can continue to connect using the the default HTTP port (80).

Click Next

10. On the SVN Security Agent Proxy Settings screen, enter the following details

Node Name: A name you will use for the Access Control server.
Node IP: The server's IP address
Bind Host: By default, this uses the wildcard 0.0.0.0 IP that binds to all network interfaces on the node. Read our Knowledgebase article about the benefits of using the wildcard IP
Client Port By default this is 80, allowing Subversion users to continue without making change to their client setup.

(Linux/Unix) In order to use port 80, Access Control must be run as root.

Admin Console Port 444 by default.



Click Next.

11. The next step automatically checks the Apache configuration. If the httpd.conf file isn't found, enter its path into the Configuration File entry box, then click Reload Configuration.

Look out for warning boxes for where setup finds a problem - like this one:

If a problem is highlighted, you'll need to manually edit the httpd.conf file, then click on Reload Configuration to have setup check your changes.

User: Owner of the file.
Group: The group in which the owner belongs.
KeepAlive: Setup will look to see that the Keep-Alive directive is set to On.
KeepAliveRequests: Setup will look for 0, which indicates that no maximum limit will be set for connection requests.
KeepAliveTimeout: Set very high (500,000 seconds) to ensure connections don't timeout.
Listening IP: For a node with multiple IPs, this will indicate the IP used for listening.
Listening Port: The default listening port for Apache is 8080.
Override Listen Directive with a virtual host: Tick this box if the Apache parser doesn't pick up the correct Listen IP/port, maybe as a result of setting up Subversion to be only accessible through a virtual host. If you tick the box you'll need to manually enter hostname/IP.


Click Next. To continue without the Apache config check, click Skip.

12. Setup now allows you to modify your Subversion settings. Watch for alerts that confirm the port and path that Access Control will associate with your Subversion repositories.



Subversion Server Port: the port on which Access Control talks to Subversion,(8080 by default).
SVN Executable: the fully qualified path to the Subversion executable. Setup will try to fill this in automatically, otherwise enter it manually.
Use authz-based access control? Tick the box to use Authz. If you tick the box you'll need to locate the fully qualified path to the Authz file.
Authorization File: Enter the path to the Authz file.


You can add additional repositories by clicking Add Repository. To continue setup, click Next. If you click Edit to change Repository you'll be able to edit the following settings:

Editing repository settings:
Directory on File System: Repository location. This needs to be the fully qualified path to the repository directly, not the URL that clients use for remote connection.
Manage Password File: tick the box to allow your Subversion password file to be controlled by Access Control. If selected you'll need to provide the username and password of the Subversion user account that will be used by Access Control to browse the repository. The account will need read and write access to the whole repository. For more information about why recommend that you enable this, see 3.1 Managing Users.


Settings in Apache
DAV Location: You can specify the location of the DAV file.
Multiple SVN Repositories: click Yes if you are using SVNParentPath for multiple repositories, or No if using SVNPath.

Click Update to apply your changes, or Cancel to return to the previous screen without making changes.

13. The next screen is for your email settings. Entering email settings will allow Access Control to send out alert emails that can help you identify problems.
SMTP Authentication: If you select No, you'll need to provide your account username and password.
Username and PasswordEnter these if you select that Yes to SMTP Authentication.
Use SSL/TLS: Choose yes if you wish to send emails over a secure connection.
Host: Enter the address of your mail server.
Port: Enter the SMTP port, 25 by default.
From Address Set the email address from which notification emails appear to come.
Send Admin Notification To: Enter the email address to which all notification emails will be sent.

Email settings are optional. If you don't need alert emails, click Skip to continue. Otherwise, click Next.

14. The setup has finished gathering information, You can go back and make changes or click Complete installation with these settings to save them and complete the installation.

15. When you click Complete installation with these settings Access Control's SVN Security Agent will automatically start up.

3. Setting up Authz

This optional section introduced the Apache Authz (Authorization) file which can be used to store Subversion user group and permission data. You only need to refer to this if you're planning on using Authz with your installation.

• 1. Ensure that the Authz module (authz_default_module) is loaded into Apache. You can confirm the module is loaded if you run:

  apachectl -M 

  This will produce a list of loaded modules, you should be looking for the authz_svn_module (shared).


• 2. Enable Authz on each node by adding the following SVN location directive to the Apache config file, /etc/httpd/conf/httpd.conf
  

  <Location /repos> 
     DAV svn 
     SVNPath /home/wandisco/repository 
     AuthType Basic 
     AuthName WANdisco 
     AuthUserFile /home/wandisco/htpasswd 
     Require valid-user 
     SVNAutoversioning on 
     ###
     # Authz module for authorization configuration
     ###
     AuthzSVNAccessFile /home/wandisco/authz
     </Location>
  

• 3. Add the Subversion user credentials (used by MultiSite to browse repositories) to the Authz file.
  
• 4. The httpd service will need to be restarted for the change to take affect.
  

  sudo /sbin/service httpd restart

  Create an empty authz file on each node:
  

  touch /home/wandisco/authz

• 5. Open Subversion MultiSite's admin console, click the Proxy tab and select SVN Settings on the side menu.


• 6. Check the Use authz-based access control? checkbox at the bottom of the svn settings panel.
  
  
  
  
• 7. The authorization file input will appear. Enter its absolute path. e.g.

  /home/wandisco/authz

  Alert
  Make sure MultiSite has permission to read and write to the svn.auth file. Also, this is a replicated change that will affect all nodes.



• 8. The /home/wandisco/authz file should be automatically updated with your current users and groups, check the contents of this file to verify that it has been updated.
  

  In the file, You should add an admin user for each repository: e.g. for repository mapped to /svn
  add the following:

   [svn:/]
  <admin username> = rw

  or for a repo mapped to /myrepo:

  [myrepo:/]
    <admin username> = rw

  where <admin username> is the username that the user enters when adding a repository.



• 9. If you brought the replicator to a stop in step 3, now return to the Proxy tab and click the Resume button.

Knowledgebase
Read more about how to use Authz - Authz basics

Copyright © 2010-2013 WANdisco
All Rights Reserved

This product is protected by copyright and distributed under licenses restricting copying, distribution and decompilation.