Navigation: | Index | Deployment Guide | Upgrade | Installation Guide | User Guide | Technical Guide | API Guide | Glossary | Release Notes

Admin guide

Welcome to the Admin Guide for WANdisco's SVN MultiSite. This describes how to plan, install, and manage a deployment.

1. Get support

If you'd like more information, look at the other WANdisco SVN MultiSite documents:

Also, see our online Knowledgebase which contains updates and more information.

We use terms like node and replication group, and define them in the Glossary. This contains some industry terms, as well as WANdisco product terms.

For more information about MultiSite and WANdisco's replication technology see the SVN MultiSite Technical Guide.

If you need more help raise a case on our support website.

2. Give feedback

If you find an error or if you think some information needs improving, raise a case on our support website or email

3. Note the following

In this document we highlight types of information using the following boxes:

The alert symbol highlights important information.

The STOP symbol cautions you against doing something.

Tips are principles or practices that you'll benefit from knowing or using.

The KB symbol shows where you can find more information in our online Knowledgebase.

Deployment Guide

This Deployment Guide describes how to prepare your development environment to implement WANdisco's SVN MultiSite.

1. Skills requirements

This section describes the knowledge and technical requirements for deployment and operation of the WANdisco software. You should ensure that each of these sections is addressed before you begin the deployment.

Technical Skill Requirements
System administration
  • Unix or Windows operating system installation
  • Disk Management
  • Memory monitoring and management
  • Command Line administration and manually editing configuration files
Apache administration
  • Familiarity with Apache web server architecture
  • Management of httpd.conf / Apache2 configuration file management settings
  • WebDAV protocol
  • Start/stop/restart administration
  • User authentication options
  • Log set up and viewing
  • IP Address assignation
  • TCP/IP ports and Firewall setup
  • Familiarity with Subversion administration (svnadmin) to create repository Command line user commands (svn)
  • Repository creation, and repository and/or file-system copying and synchronization.
  • Familiarity with WANdisco's replication architecture
  • Understanding of the installation procedure relevant to the OS in use
  • Concept of node types and Replication groups
  • Quorum configuration options

If you're not confident about handling any of these tasks, you can request a supported Installation from WANdisco.

A single administrator can manage all the systems running MultiSite, although it's a good idea to have someone at each site who is familiar with the MultiSite Basics.

2. Deployment overview

As with any software implementation you should deploy WANdisco SVN MultiSite following a well-defined plan. This helps you keep control, understand the product, and find and fix and issues before production. We recommend including the following steps:

  1. Pre-deployment planning: Identify the requirements, people and skills needed for deployment and operation. Agree a schedule and milestones. Highlight any assumptions, constraints, dependencies, and risks to a successful deployment.
  2. Deployment preparation: Prepare and identify server specifications, locations, node configuration, repository set-up, replication architecture, and the server and software configurations.
  3. Testing phase: Actions for an initial installation and testing in a non-production environment, executing test cases, and verifying deployment readiness.
  4. Production deployment: Actions to install, configure, test, and deploy the production environment.
  5. Post-deployment operations and maintenance: Actions including environment monitoring, system maintenance, training, and in-life technical support.

3. System requirements

This section describes how to prepare your Subversion servers for replication. View this information as a set of guidelines, not as a fixed set of requirements.

3.1 Hardware recommendations

Hardware Sizing Guidelines
Size #Users Repository Size (GB) CPU speed (GHz) #CPU #Cores RAM (GB) HDD (GB)
Small 100 25 2 1 2-4 8-16 100
Medium 500 100 2 2 4 16-32 250
Large 1000 500 2.66 4 4 32-64 750
Enterprise 5000 1000 2.66 4 4-6 128 1500

3.1.1 Storage tips

For more information about calculating storage capacity requirements, read the Knowledgebase article, Hardware Sizing Guide.

3.1.2 Processor tips

3.2 Setup requirements

3.2.1 MultiSite servers

MultiSite servers require:

See the Deployment checklist for more details.

3.2.2 Subversion installations

Subversion installations require:

Run Subversion and MultiSite on the same server to gain the following benefits:

  • The installer can package a copy of your repositories when setting up nodes
  • SVN MultiSite can manage the Subversion password file
  • Support for pre-replication hooks

3.3 Creating copies of your repository

Each MultiSite server must begin with an exact replica of the Subversion repository. The method you use to copy repositories depends on how big they are.

When copying a repository to a node to be used in replication, you cannot use svnadmin hotcopy to copy an existing repo. Use rsync or similar tools.

3.3.1 Small repositories: less than 1GB

If a repository is relatively small, it can be bundled up with the MultiSite install files when you activate additional MultiSite nodes. However, this option is only practical for relatively small repositories.

3.3.2 Large repositories: 1GB or greater

For repositories that are bigger than 1GB, it's no longer practical to bundle them during the installation of MultiSite software. Instead, use the following process:

  1. Copy the Subversion repository to each server that will be set up as a node. You can do this while production continues because you'll resync them later.

    Ensure file ownerships and permissions are the same on all nodes.

  2. Complete the MultiSite installation for your first node.
  3. Shutting down SVN MultiSite. This puts the repository into a read-only mode. Therefore, it's best to complete the remaining steps outside of your developers' working hours.
  4. Use rsync to sychronize the live repository with the copy on all nodes.
  5. Restart SVN MultiSite.
  6. Go to the admin console and follow the procedure for Creating a replication group.

This process ensures that the Subversion repositories are exact copies, and causes minimal downtime for Subversion users.

3.4 Replicating multiple repositories

SVN MultiSite can replicate any number of Subversion repositories, using the Apache SVNPath or SVNParentPath directives. For more information, see Setting up Apache and Adding a repository.

3.4.1 SVN Location (SVNPath) directive

The SVNPath directive tells Apache where your Subversion repository is located. You can have multiple location directives, each pointing to a different Subversion repository.

<Location /repo>
DAV svn
SVNPath /home/svn/repo1
AuthType Basic
AuthName wandisco
AuthUserFile /home/scm/htpasswd
Require valid-user  </Location>

<Location /xyz>
DAV svn
SVNPath /home/projects/repositories/xyz
AuthType Basic
AuthName wandisco
AuthUserFile /home/scm/htpasswd
Require valid-user  </Location>

Example httpd.conf syntax for using SVNPath

3.4.2 SVNParentPath directive

Use the ParentPath directive if you have multiple repositories in the same directory. This tells Apache to match to the parent directory, under which there may be several repositories. E.g. and subversion-domain/svn/repo2 would map to repositories at /home/svn/repo1 and /home/svn/repo2.

<Location /svn>
DAV svn
SVNParentPath /home/svn/
AuthType Basic
AuthName wandisco
AuthUserFile /home/scm/htpasswd
Require valid-user  </Location>

Example httpd.conf syntax for using SVNParentPath.

A repository can belong to only one replication group at a time. Each replication group that a node belongs to requires its own SVNParentPath.

See an example of SVNParentPath in our Knowledgebase: Using SVNParentPath with multiple replication groups.

3.5 Using Authz for authorization

Use the Apache module, Authz, to control user authorization. Authz takes user information from the password file and associates access permissions.

We recommend using Authz with Access Control to fully control access to your Subversion repositories.

If you move from SVN MultiSite bundled with Access Control to the baseline MultiSite (that doesn't feature Access Control), you will need to manually remove the Authz directive from the Apache config file as well as the Authz file.

3.5.1 Setting up Authz

  1. Ensure that the Authz module, authz_default_module), is loaded into Apache. Confirm this by running:
    apachectl -M 
    This produces a list of loaded modules. Look for 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
  3. If this is a live system, perform a synchronized stop to prevent write transactions.
  4. You need to restart the httpd service at each node 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 SVN MultiSite's admin console, click the Proxy tab and select SVN Settings on the side menu.
  6. Tick the Use Authz-based access control? checkbox at the bottom of the svn settings panel.
    authz tick
  7. The authorization file input appears. Enter its absolute path. e.g.

    Make sure MultiSite has permission to read and write to the svn.auth file. This is a replicated change that affects all nodes.

  8. Check that the /home/wandisco/authz file has been automatically updated.

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

    <admin username> = rw

    For a repo mapped to /myrepo add:

    <admin username> = rw

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

  9. If you stopped the replicator in step 3, return to the Proxy tab and click the Resume button.

Read more about Authz basics.

3.6 MultiSite and Subversion password files

The Subversion server on every node must have the details of all users across the replication group. The easiest way to keep user details consistent is to allow MultiSite to control the Subversion password files: any user created in MultiSite's admin console is automatically added to Subversion servers across the replication group. Use this Access Control feature to simplify the management of Subversion users.

You can set up SVN MultiSite to control the Subversion password during installation. Identify the Subversion password file's location and the installer then incorporates it into the replication group.

If you have a lot of Subversion users, you can bulk import them into SVN MultiSite.

3.7 Quorum recommendations

MultiSite uses a quorum strategy to handle agreement between the nodes in a replication group. Read more about the different types of quorum. This section briefly describes the benefits of each quorum type, and what setup to use it in.

Setup Type Quorum Recommendation
MultiSite Singleton Response or Majority Response Quorum, balancing performance versus availability.
MultiSite with Sub Groups Majority Response quorum. If you select Singleton Response quorum, the distinguished node represents a single point of failure.
Stand-Alone Group at One Location Have a group of at least three nodes, which automatically handles the failure of any single replicator node and its subsequent recovery. With a two node group, select Singleton or Majority Response quorum, and the second node must be the distinguished node.

3.8 Firewalls and anti-virus software

The unexpected blocking of ports can be a problem when setting up SVN MultiSite. Before you start the installation you should determine if any of the nodes in your replication group will be accessing a firewall. You must ensure that any firewalls are configured so that the port numbers (6444, etc.) you specify during installation are not blocked or filtered.

If you have an AV software/virus scanner running on your network, you must configure it to not filter traffic on the ports you specify during installation.

3.9 Configuring Apache

You can either give SVN MultiSite exclusive use of Apache or share Apache with other applications/locations.

basic apache

Example of a simple configuration without MultiSite

Without SVN MultiSite, Subversion clients simply connect to Subversion on port 80.

basic apache

Example setup that includes SVN MultiSite

SVN MultiSite sits between the Subversion clients and Subversion server, acting as a web proxy. Subversion clients connect on the usual port 80, whilst Apache is set to listen on port 8080.

3.9.1 Changing Subversion listen port (Unix)

The listen port is set in Apache's config file, httpd.conf. See more information about the Listen directive in the Binding chapter of the Apache documentation.

# Listen: Allows you to bind Apache to specific IP addresses and/or
# ports, instead of the default. See also the <VirtualHost>
# directive.
# Change this to Listen on specific IP addresses as shown below to
# prevent Apache from glomming onto all bound IP addresses (
Listen 8080

Snippet of the httpd.conf file

With this configuration, Apache server listens on port 8080 instead of default port 80.

3.9.2 Sharing Apache and using HTTPS

You can choose to share Apache with other locations or applications, instead of dedicating it to Subversion. For example:

apache shared

Using HTTPS or sharing Apache with other applications/locations

In the above example all processes are running on the same machine. Apache is running on port 80, Apache's webDAV module is running on port 8181. WANdisco's SVN MultiSite is listening on port 8080, forwarding requests to Apache's WebDAV module on port 8181. Some clients are connecting via SSL (HTTPS) with their connection running on port 443.

You can use this configuration if you enable a proxy pass.

Default port settings required during the installation of SVN MultiSite are:

In the Apache config httpd.conf file, specify the following parameters:

# Define Apache port and pass anything that matches location /svnrepos to
# WANdisco SVN Replicator
NameVirtualHost *:80
<VirtualHost *:80>
ProxyPass /svnrepos
ProxyPassReverse /svnrepos

Listen 8181
NameVirtualHost *:8181

<VirtualHost *:8181>
<Location /svnrepos>
AllowOverride None
Order allow,deny
Allow from
DAV svn
SVNParentPath /tmp/dav
AuthType Basic
AuthName wandisco
AuthUserFile /etc/httpd/conf/htpasswd
Require valid-user
# For the SSL option
Listen 443
<VirtualHost *:443>
ProxyPass /svnrepos
ProxyPass /!svn!svn
ProxyPassReverse /svnrepos
ProxyPassReverse /!svn!svn
SSLEngine on
SSLCertificateFile /etc/httpd/conf/ssl.crt/server.crt
SSLCertificateKeyFile /etc/httpd/conf/ssl.key/server.key
SSLCACertificateFile /etc/httpd/conf/ssl.crt/ca-bundle.crt

3.9.3 Using HTTP with Apache

This section applies to all Apache configurations.

To make a Subversion repository function in a distributed environment, SVN MultiSite requires exactly the same Apache/Subversion setup at all the nodes.

Even without SVN MultiSite, Apache benefits from some tweaking in order to work effectively with Subversion.

  1. Change Apache's connection KeepAlive settings to allow long-lived HTTP connections. Add this to the Apache configuration file conf/httpd.conf or included conf/extra/httpd-defaults.conf. For example:
    # Timeout: The number of seconds before receives and sends time out.
    Timeout 7200
    # KeepAlive: Whether or not to allow persistent connections (more than
    # one request per connection).
    KeepAlive On
    # MaxKeepAliveRequests: The maximum number of requests to allow
    # during a persistent connection. Set to 0 to allow an unlimited amount.
    MaxKeepAliveRequests 0
    # KeepAliveTimeout: Number of seconds to wait for the next request from the
    # same client on the same connection.
    KeepAliveTimeout 14400

    Example httpd.conf snippet showing recommended Apache timing configuration

  2. Ensure the SVN DAV settings in Apache's configuration files are exactly the same at all nodes. The top-level location URI prefix should be the same.

    If you are using ProxyPass, avoid using a single / (slash) DAV location because this is not compatible with MultiSite and can cause replication to crash.

    We recommend copying the current httpd.conf file, and then changing the host:port settings. For example, here is a conf file snippet with Apache virtual hosts. You do not have to use Apache virtual hosts. This is an example:

    # Site A
    $ cat conf/extra/httpd-svn-dav.conf
    NameVirtualHost site-a:8181
    <VirtualHost site-a:8181>
    <Location /dir0>
    DAV svn
    SVNPath /home/site-a/svnroot
    AuthType Basic
    AuthName wandisco
    AuthUserFile /home/site-a/apache2/dist/conf/htpasswd
    Require valid-user
    # Site B
    $ cat conf/extra/httpd-svn-dav.conf
    NameVirtualHost site-b:9191
    <VirtualHost site-b:9191>
    <Location /dir0>
    DAV svn
    SVNPath /home/site-b/svnroot
    AuthType Basic
    AuthName wandisco
    AuthUserFile /home/site-b/apache2/dist/conf/htpasswd
    Require valid-user

    Example httpd.conf file illustrating the use of Apache virtual hosts

  3. The Apache usernames and passwords should match at all nodes.

    SVN MultiSite must have a valid username inside the HTTP authorization header to be passed for all DAV commands.

3.9.4 Apache and SVNKit

There are potential problems with connection pooling when using Apache and SVNKit. Adding SVN MultiSite does not change these issues, but you may need to revisit them after installing MultiSite.

We recommend using JavaHL with Eclipse IDE, which does not use connection pooling and thereby eliminates the problem.

3.9.5 SVNKit and connection pooling

SVNKit uses connection pooling. For a given client, SVNKit opens two connections and keeps them open for later use. On a system with a heavy load this can affect performance. An open connection consumes an Apache worker thread and, with lots of clients and pooling going on, Apache may run out.

Apache provides some tuning parameters to optimize connection pooling, while still releasing unused connections. The tunable parameters are Timeout, KeepAliveTimeout, MaxKeepAliveRequests, and KeepAlive. For more details see the Apache configuration documentation.

3.9.6 Optimize your configuration

Apache has two timeout configurations: Timeout and KeepAliveTimeout. In general, the Timeout value should be lower than the value for KeepAliveTimeout.

Setting KeepAlive to false is not recommended. If you set KeepAlive to false, a client's transactions create an enormous overhead setting up and destroying connections.

3.9.7 Apache logging

Apache's logs are dumped to a single file. This can cause problems when the log file grows so big that it needs to be truncated. When this happens, Apache service is interrupted while the file is restarted. On Linux/Unix servers you can pipe logs to another process. For more information see our Knowledgebase article, Piping Apache logs

4. Deployment checklist

Though you may have referred to the Deployment checklist prior to an evaluation of SVN MultiSite we strongly recommend that you re-read the checklist and confirm that your system still meets all requirements.

System setup
Operating systems We've tested the following operating systems:
  • Red Hat Linux Enterprise (RHEL) Server (32 or 64 bit): 4, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8, 5.9, 5.10, 6, 6.1, 6.2, 6.3, 6.4, 6.5
  • Oracle Linux (Running Red Hat Compatible Kernel): Oracle 5 (v2.6.18), Oracle 6 (v2.6.32)
  • Sun Solaris (32 or 64 bit): 9, 10, 11
  • SuSE Linux Enterprise Server: 11
  • Ubuntu: 10.04, 12.04
  • Debian: 5, 6
  • CentOS: 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8, 6, 6.1, 6.2, 6.3, 6.4, 6.5
  • Windows Server: (32 or 64 bit) 2003, 2008, 2012
Subversion server Version 1.4 and above (we have successfully tested the recent 1.8 release). Run the Apache Portable Runtime that matches your Subversion version. SVN MultiSite is now compatible with Subversion 1.7's HTTPv2 implementation. MultiSite 4.0 Users: Read our Knowledgebase article on a workaround that lets you Run MultiSite 4.0 with Subversion 1.7.

There is a known issue that results in incorrect error reporting during "disk full" scenarios running with Subversion 1.7. Read our knowledgebase article: Incorrect error reporting when running SVN MultiSite 4.2 with Subversion 1.7.

Certified Subversion Binaries
These are now available from WANdisco. They provide the latest builds, without the risks associated with Open Source distribution.

Subversion client Any that are compatible with local Subversion servers.
  • Pre-commit hooks are not recommended. Use pre-replication hooks instead.
  • Any pre-replication hooks must be deterministic, i.e. have the exact same behavior and outcome at every node. Post-commit hooks can be tested at only one node.
System memory Ensure RAM and swapping containers are at least 4 times larger than the largest Subversion file. Minimum recommended: 2GB RAM; 4GB swapping container
Disk space Subversion: Match to projects and issues. MultiSite Transaction Journal: Equivalent of seven days of changes. To estimate your disk requirements, you need to quantify some elements of your deployment:
  • Overall size of all of your SVN repositories
  • Frequency of commits in your environment
  • Types of files being modified - text,binaries (SVN clients only send deltas for text)
  • Number and size of files being changed
  • Rate that new files are being added to the repository

Changes to the network layer introduced in 4.1 mean that MultiSite no longer buffers replicated data. This removes the requirement for sufficient disk space to handle large concurrent checkouts for large numbers of users.

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.

NFS must not be used with Subversion MuliteSite. See Why you shouldn't use NFS. You can use ext4 as your journaling file system, although it must be configured appropriately. See Using Ext4 filesystem for journaling.

Avoiding Data Loss
For a description of several implementation strategies that militate against potential data loss as a result of power outages, see Data Loss and Linux.

Max. User Process Limit At least 3 times the number of Subversion users.
Java Install JDK 6 or JDK 7. We require that you use Oracle JDK 1.6.

Java 7 is supported in the latest 4.2 releases (4.2 build 6801 and later). If you want to use Java 7, you need to upgrade.

Perl Install version 5.6.1 or later. For Access Control: Perl::DBI module for Audit Reports other than Users and Groups.

Windows users: Use the 32-bit edition of ActivePerl version 5.8, even if you are running a 64-bit Windows server.

Network settings
Reserved ports When the installer confirms the admin console port (6444 by default), the next 9 consecutive ports (by default 6445-6453) are now also reserved for various MultiSite network activities (REST, DCone, DFTP). Not all these ports are currently assigned, some are reserved for possible future use. We also recommend having a port available in case you have to copy (rsync) the repository from one node to another.
Firewall or AV software If your network has a firewall, ensure that traffic is not blocked on the reserved ports noted above. Configure any AV software on your system so that it doesn't block or filter traffic on the reserved port
VPN Set up IPsec tunnel, and ensure WAN connectivity.
VPN persistent connections Ensure that your VPN doesn't reset persistent connections for SVN MultiSite.
Bandwidth Put your WAN through realistic load testing before going into production. You can then identify and fix potential problems before they impact productivity.
DNS setup Use IP addresses instead of DNS hostnames. This ensures that DNS problems won't hinder performance. If you are required to use hostnames, test your DNS servers performance and availability prior to going into production.
Apache setup
Apache version All nodes must have the same version, 2.2.3 or above.
Apache modules version All nodes have the same version of mod_dav and mod_svn_dav.
mod_deflate.c for SVN_DAV DO NOT USE mod_deflate. You must check that it is not enabled, removing it if necessary. You should also repeat this check if you make system changes that might result in mod_deflate being enabled, e.g:
sudo a2dismod deflate
Restart apache:
sudo service apache2 restart
Then verify that deflate.conf is not present in:
ls /etc/apache2/mods-enabled/
Location URI Ensure the Apache config file on all nodes have the same location URI for Subversion repository access.
Valid user for write methods Ensure that all WebDAV methods require authentication for SVN-DAV protocol.
Use port 80 for WANdisco Standard Port 80 avoids confusion. Change the default Apache port if using 80.
Apache server port Use non-standard Apache server port to avoid conflict with replicator port. See Dedicated Apache - Changing Subversion Port On
MultiSite setup
Quorum Default is singleton, providing performance over availability. Read more about Quorum options.
Rotating quorum schedule Ensure the distinguished node is in the active time zone.
Disk space for recovery journal Provision large disk for svn-replicator/systemdb, at least number of commits within a 2 to 4-hour window.
Batch processing If there are any batch processes that interact with WANdisco, turn the deferred-writes to "false".
LDAP integration
Pre-replication authentication Because it is difficult to keep authentication credentials synchronized between sites, it's essential that you set up pre-replication authentication. Without pre-replication authentication, authentication credentials can be changed on one site while SVN changes made on another site are still being made. On arrival these transactions would be rejected forcing the Subversion Repository into a read-only mode.
Large LDAP deployments If you are planning to deploy with large numbers (thousands) of LDAP-managed users, you should apply the following changes to the system setup:
  1. Increase the java HEAP to at least 6GB. Read Changing the default Java Heap Size.
  2. Restart the replicator immediately after completing a backup data import.
  3. Change the following Apache timeout setting (in subversion.conf):
    KeepAliveTimeout = 14400
    This is a drop from the usual default recommended value of 500000.
Access Control
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. The module may be bundled with your version of Apache.

Installation Guide

The installation guide describes setting up SVN MultiSite for the first time. If you're already using an earlier version of MultiSite, see the Upgrade section.

1. Installation process

This is the installation process:

  1. Check the deployment checklist. Make sure that you have everything set up and ready to save you having problems during installation. The main boxes you need to check are:
    • Subversion authenticating: Subversion installed, and using authentication.

      Authentication Must be enabled within the location directive of the Apache config file. Otherwise, changes to the repository will not be replicated.

    • JDK6/JDK7: You need to have Java JDK 6 or JDK7. We require that you use Oracle JDK 1.6.

      Java 7 is supported in the latest 4.2 releases (4.2 build 6801 and later). If you want to use Java 7, you need to upgrade.

    • Java Memory Settings: MultiSite starts with 128MB and sets a maximum of 2GB of memory when it starts up. See Changing the default Java heap size.
    • System resources: Ensure that your system is going to operate with a comfortable margin. See Hardware Sizing Guide.
  2. Check that your repository is copied on all nodes. See 2.3.3 Creating copies of your repository
  3. Check that Apache is running and that the Apache config file has been updated to support MultiSite.
  4. Download and copy the MultiSite files onto one node.
  5. Run the setup, then complete the installation from a web browser.

2. Before you start

Before installing the software, note:

3. Start installing

  1. Save the svnrep.tar.gz archive to your Installation node.
  2. Extract the setup files using a compression utility that supports the .gz (gzip) format.

    Install to a writable directory
    Ensure that you install the SVN MultiSite to a directory that is writable by the user running MultiSite on all nodes. If this is not the case, some operations will fail when the system attempts to make changes to MultiSite's files.

    Don't alter SVN MultiSite's directory structure
    Ensure that you install the SVN MultiSite files to a directory called svn-replicator and that you preserve the following subdirectory structure:

    svn-replicator directory contents
    /audit The audit trail logs for Access Control.
    /bin Scripts like svnreplicator and shutdown
    /config Contains prefs.xml which contains MultiSite configuration information. The license file needs to be place here before you can run MultiSite.
    /lib The Java archives (jar) files required to run the MultiSite.
    license.txt The SVN MultiSite End User License Agreement. This is the same license that appears during installation.
    /logs Logs and other temporary files. MultiSite's main log file is named SVNProxyServer-prefs.log.0
    /systemdb The system database with its transaction journal. Warning: Deleting or modifying files from systemdb is likely to corrupt your installation.
    /utils Several extra programs, such as the sample startup script, upgrade conversion scripts, the perl script for running the Windows service and the LDAP Admin reset script.
    version.txt The installation's version number. This is useful for confirming the version number without having to run the installer.
    /webapp The code for SVN MultiSite's web server.

    If you are using selective replication, you need separate instances of MultiSite installed, but each one situated in a directory called svn-replicator, for example:


    Selective replication is used when you need to replicate only specific repositories. See Selective Replication.

  3. Place the license.key file in the svn-replicator/config directory.
  4. Complete the setup by running through steps in a browser-based wizard. From the /bin directory, start setup with the following command:
    perl setup
    WANdisco products use port 6444 by default. If you're not able to use this port on your network, you can set a different port by starting setup using the command:
    perl setup <chosen port number>
  5. Setup begins by confirming how much memory needs to be allocated to Java. By default, MultiSite starts with 128MB and reserves 2048MB (2GB).
    WANdisco Java processes will start with the following memory settings:
    -Xms128m -Xmx2048m -ea -server
    Change the environment variable WD_JVMARGS if you wish to start java differently WARNING: if the host does not meet these specified memory requirements, you will encounter problems starting the WANdisco processes. Continue, Y or N ? [Y] : y Mar 29, 2010 11:29:47 AM org.nirala.trace.Logger info INFO: Invoked from WANdisco installation at: /wandisco/svn-replicator [I] using specified port: 6444 [I] Starting Subversion web installer

    You can change how memory is allocated by editing references to SERVER_JVM_ARGS in the bin/ file. See Changing the default Java heap size.

    If you're happy with the allocation, type 'y' and then press return.

    Point a web browser to to configure the product.
  6. Setup now starts up the web interface. Open a browser and type in the given address. The default port is 6444. If you entered a different port (step 3.1) then use this instead:
    http://<server IP>:<WANdisco port you selected when starting setup>

4. Complete setup using a browser

From the Welcome screen in your browser:

  1. Follow the link to the pre-installation checklist to check that everything is ready for a successful installation, then click Continue.
    MultiSite setup 3
  2. Read through the WANdisco End User License and click I Agree.
    MultiSite setup 4
  3. The default username to access the admin console is admin. Enter a password for the admin account, then click Next.
    MultiSite setup 5
  4. The next two screens explain how MultiSite acts as a proxy between Subversion clients and the Subversion server. Click Next.
    MultiSite setup 6
  5. By default, MultiSite listens on port 80, while Subversion listens on port 8080. This ensures that Subversion end-users don't need to make any changes. Click Next.
    MultiSite setup 7
  6. To enable SSL encryption check the check box to open the SSL Settings screen. Click Next.
    MultiSite setup 5.5
  7. If you tick the Configure SSL keystore check box, you'll see the SSL Settings screen:
    MultiSite setup 5.5.5 SSL stuff

    KeyStore Filename: Path to file where private keys are stored.

    KeyStore Password: Password for the KeyStore file.

    TrustStore Filename: Path to the file where public keys are stored. This may also be the KeyStore file.

    TrustStore Password: Password for the TrustStore file.

    The settings are populated with default values to help setup. Make sure that these match your environment and security requirements. Click Next.

    You may want to set up the SSL encryption after you've successfully set up MultiSite without SSL. If you then experience problems with your SSL setup you'll know that the underlying replication is working.

  8. Confirm the proxy settings. These are populated with the default port settings noted in the previous screens. MultiSite setup 8

    Node Name: The name that Access Control uses for the server on which it's installed. The name cannot contain spaces, but can be changed later using the Admin Console.

    Node IP: The server's IP address.

    Bind Host: By default, this uses the wildcard IP that binds to all network interfaces on the node. Read about the benefits of using the wildcard IP.

    Client Port: By default this is 80, allowing Subversion users to continue without making changes to their client setup.

    To use port 80, run MultiSite as root.

    Admin Console Port: 6444 by default.

    Reserved Ports: 6444-6453 by default.

    Use Manually Distributed Ports: Tick this check box to manually assign the range of ports instead of using the default range (6444-6453).

    MultiSite setup 8

    Admin Console Port: The port used to access SVN MultiSite's admin console. The default is 6444.

    WANdisco Port: The port that DConE, the WANdisco replication service, will run on. The default is 6444, the same port that is used for the admin console.

    DFTP Port: The direct file transfer protocol port is used for communication between nodes.

    Shutdown Port: Listener that is contacted by the shutdown and LDAP admin reset scripts (binds to localhost only).

    Use SSL: Enable SSL to use encrypted communication between nodes. If SSL is enabled, then https: is also required for browsing to the web console.

    When you've finished making any changes to the proxy settings, click Next to continue.

  9. Setup checks the Apache config file for settings that might cause problems for MultiSite. See Configuring Apache. MultiSite setup 9

    If the httpd.conf file isn't found, enter its path into the Configuration File entry box, then click Reload Configuration. Warning boxes appear where setup finds a problem, like this one:

    MultiSite setup 10

    If a problem is highlighted, you need to manually edit the httpd.conf file, then click Reload Configuration so that setup checks your changes. User: Owner of the file. Group: The group in which the owner belongs. KeepAlive: Setup checks that the Keep-Alive directive is set to On. KeepAliveRequests: Setup looks for 0, which indicates that no maximum limit will be set for connection requests. KeepAliveTimeout: Set high to ensure connections do not timeout. Listening IP: For a node with multiple IPs, this indicates the IP used for listening. Listening Port: The default listening port for Apache is 8080.

    When you want to continue, click Next. To continue without the Apache config check, click Skip.

  10. Modify the Subversion settings. Watch for alerts that confirm the port and path that MultiSite will associate with the Subversion server. MultiSite setup 12

    Use Pre-Replication Hooks: Select Yes or No.

    If you select Yes you must select the version of Subversion installed on your server. If you don't know the version as you run through the setup you can select "Unknown". However, when the installation is complete, you must confirm the version of Subversion you are using, then edit the option from the SVN Settings page.

    MultiSite setup

    Subversion Host: The host name for the server on which Subversion is running. We recommend that this is the same as the server running MultiSite, e.g. 'localhost.

    Subversion Server Port: 8080 by default.

    SVN Executable: This is the fully qualified path to the Subversion executable. Setup tries to fill this in automatically. Otherwise type it into the entry box.

    Use Authz-based access control?: Tick the box for MultiSite to use Authz authentication.

    Authz and regular expression-based Access Control rules
    If you use Authz to manage user authorization through Apache, note that Access Control rules that use regular expressions to define resources are not supported by Authz so they won't be written to the Authz file. Selecting Authz access reveals an additional entry field for recording the location of the Authz file.

    For example, given the root /svnroot with the repositories /svnroot/one, /svnroot/two and /svnroot/three the value would be: one,two,three.

    Bind SVN proxy to localhost only: The SVN MultiSite binds to the localhost. HTTP/Jetty server uses the node settings. SVN MultiSite will be "locked down" and not directly accessible to users. This setting can be used if you plan to use a seperate instance of Apache in front of SVN MultiSite, for example, running with Kerberos authentication.

    Replicate Revision Timestamps: Enable this setting to ensure that timestamps on revisions are the same across all replicated repositories. You also need to enable the pre-revprop-change Hook.

    If you need consistency in the revision timestamps on each of your nodes, follow this procedure after ticking the above Replicate Revision Timestamps: checkbox.

    1. Navigate to each repository's hooks directory and edit the existing template or create the pre-revprop-change file with:
      vi pre-revprop-change
    2. Add the following script to limit changes to just the revision date:
      if [ "$ACTION" = "M" -a "$PROPNAME" = "svn:date" ]; then exit 0; fi
      echo "Changing revision properties other than svn:date is prohibited" >&2
      exit 1
    3. Save the file.
    4. Ensure the hook can be run:
      chmod +x pre-revprop-change
    5. Repeat the procedure on ALL nodes and for all applicable repositories.

    Note: Unlike other hooks, this hook MUST exist for revision properties to be changed. If the hook does not exist, Subversion behave as if the hook were present, but failed. The reason for this is that revision properties are UNVERSIONED, meaning that a successful propchange is destructive.

    At the bottom of the screen is a table that confirms the DAV Location and password control for your repositories.

  11. Click Edit to make changes.
  12. To add additional repositories click Add Repository or to continue setup, click Next.

    If you click Edit to change Repository you'll be able to edit the following settings:

    MultiSite setup 12b

    Directory on Files System: Fully qualified path to the Subversion repository, not the URL used by clients to connect.

    Manage Password File: Check the box to allow your Subversion password file to be controlled by Access Control.

    Password File: If you tick Manage Password File, you'll see a browsable entry field for the password file's location.

    Pre-Commit Hook: Equivalent to normal pre-commit hook but it is automatically picked up and invoked in a replication safe manner.

    Pre-lock Hook: Equivalent to normal pre-lock hook (invoked when a user attempts to lock a resource) but it is automatically picked up and invoked in a replication safe manner.

    Pre-Unlock Hook: Equivalent to normal pre-unlock hook (invoked when a user attempts to destroy an exclusive lock) but it is automatically picked up and invoked in a replication safe manner.

    Authentication Realm: Associate an authentication realm with the repository. See the Apache documentation for more information about the AuthName Directive.

    MultiSite setup 12b

    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.

    If you select Yes, SVNParentPath is used in Apache location directive, you are shown a list of Root Names, and can add more subdirectories by entering their names in the Add Root box.

    For example:
    Given the root /svnroot with the repositories /svnroot/one, /svnroot/two and /svnroot/three the value would be: one,two,three.

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

    When you've finished making changes to the repository settings, click Update to return to the previous screen, then click Continue.

  13. You can enter email settings so that MultiSite can send alerts when problems are detected. For example:

    Example emails

    The distinguished node sends alerts on behalf of the whole replication group. The subject line notes the node and repository that the alert applies to.

    MultiSite setup 13

    SMTP Authentication: If you select No, you need to provide your account. Username and Password: Enter these. 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. Send Admin Notification To: The email address to where notifications will be sent. Note: You can only specify a single address, not a comma delimited list.

    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.

    MultiSite setup 14

    When you click Complete installation MultiSite starts running. You are prompted to reload the admin console.

    MultiSite setup 15

5. Log in to the Admin Console for the first time

The browser refreshes to show the admin console login screen:

MultiSite setup 15
  1. To log in for the first time, enter the username "admin" and the password you entered during setup.
  2. When you first enter the admin console you are prompted to create a new user and other nodes.
    MultiSite setup 16 For more information see the guide to the admin console.

Proxy stopped
When a node starts up for the first time the proxy remains stopped until manually started. This ensures that replication is started in a controlled way. This only applies to the first startup, after which the proxy starts automatically.

6. Copy the installation files manually

Follow these instructions if you did not use the automated packaging option described in section 7.

MultiSite creates a [node name].zip file for each of the nodes in a replication group. The first node is installed, so perform the following for all new nodes in the group:

  1. Copy the [node name].zip to the new node.
  2. At the new node, extract the [node name].zip file to a temporary directory called wandisco.
  3. From a command prompt type:
    cd wandisco
    perl unpackage
  4. Follow the directions provided by the unpackage script.

7. Post-installation configuration

You may need to make some changes before using Subversion through MultiSite. Make these changes through the admin console. For more information see the Admin Console Guide.

7.1 Using pre-commit hooks

If you are going to be using pre-commit hooks, these become WANdisco pre-replication hooks. See Setting up hooks in the User Guide.

User Guide

1. Replicator Management

1.1 Adding a node

To add a node to an existing replication group, you have to create a new replication group that contains the new node and then activate the new replication group. See Creating a New Replication Group.

Plan how to copy the repository to the new node. See Creating copies of your repository.

Verify before replication
Before you replicate your repositories, run the svnadmin verify command to ensure that there are no corrupted revisions. See svnadmin verify.

  1. Open the admin console, click the Proxy tab, then Nodes in the Replication list, then Create Node.
    Add Node 01
  2. Enter the properties for the new node:
    Add Node 02

    Node properties:

    • Name: A name for the node.
    • Host: DNS name or IP address of the node.
    • Bind Host: Select Bind all or Bind advertised host only.
    • Port:Port number allocated to the node. The default port is 6444.
    • Use Manually Distributed Ports: Tick this check box to manually assign the range of ports instead of using the default range (6444-6453):
      Manually Distributed Ports

    Subversion Properties (for remote node): The Subversion Properties are populated with settings of the first node, which assumes that your new node will use the same proxy setup. Change them if required.

    SSH Properties: SSH is used by MultiSite to automatically install on your additional nodes. You enter the details here for giving SSH access to the new node.

    Why don't I see SSH settings?
    You won't see SSH settings if you have created the current replication group using the manual approach, instead of selecting Activate the nodes automatically via SSH?

    SSH Port: Default port for SSH is 22. Assign if a different port is required.

    Authentication: By username/password or by Private Key File.

    SSH Username: The SSH authentication username.

    SSH Password: The SSH authentication password.

    JAVA Home: The path to JAVA on the new node. This field is optional. If not specified here, the value for the environmental variable JAVA_HOME is used.

  3. Click Create Node or Create and Test. The test confirms the SSH properties that will be used to push out the installation files to the new node, as well as the Java home directory. Add Node 03

The new replication group is activated with all nodes.

1.2 Removing a node

You cannot remove a node from an active replication group. Instead you create a new replication group that excludes the node(s) that you want to remove:

  1. Follow the procedure for creating a new replication group. The new replication group should contain all the nodes in your current replication group, except for the node(s) you want to remove.
  2. Activate the new replication group.
  3. When the old replication group is no longer active you can delete it, along with any nodes that are no longer members of the active replication group.
    Create Replication Group 01

    Select any inactive replication group and click the Delete Selected button.

Only one replication group can be active at a time.

1.3 Creating a new replication group

You can create as many replication groups as you like, although only one replication group can be active at a time. You can't delete the active replication group, first you need to create a new replication group and make it the active group. See Deleting a replication group

Create replication groups from the node that will be the distinguished node in the new replication group.

Only one replication group can be active at a time.

  1. From the Proxy tab, click Replication Groups. All defined replication groups are listed, including the active one. Click the Create Replication Group.
    Create Replication Group 01

    Replication Groups screen listing one existing replication group

  2. Name the new replication group and select the appropriate quorum. See quorum selection. Tick the nodes that you want to replicate within the group, then click Create Replication Group. Create Replication Group 01

    Replication Groups basic settings

  3. Check that the details of the replication group are correct, then click Activate.
    Create Replication Group 01

    Replication group created - awaiting activation

  4. Activate the new replication group. The current replication group becomes inactive. Any nodes that are not members of the new replication group continue to be accessible to local users but no longer replicate.

    Activating a replication group stops all nodes and temporarily prevents write transactions. Nodes that are retired from replication should be shut down.

    Activation Information: Determines how the replicas of the node are transferred to the other servers.

    WANdisco Directory: Confirms the installation directory, which is not editable because it must mirror the directory structure on the current node.

    Activate Nodes via SSH?: Click Yes, Activate the nodes automatically via ssh to copy the node's setup files to the new nodes via SSH.

    To copy the files yourself, for example if you are using Windows and do not have SSH functionality, click No. I will copy the archives manually. The files are copied and zipped up. When this is complete, click Continue then follow the steps on screen:

    Manually Copy Files

    Packaging Options: Delete Packaging Dir?: This option appears if node package files already exist in your specified Packaging directory. You can select to automatically overwrite the exiting package files or provide a warning:

    Create Replication Group 01

    Package Repository: To have the repositories automatically packaged click Yes, Create an archive of the repositories. To transfer the repositories using a sync utility, such as rsync, click No. I will synchronize the repositories manually.

    SVN MS Packaging Ops

    Set Owner / Group: To allow the owner and group to be automatically set during the archive creation, click Yes. Set the owner and/or group of the copied files. If you want to assign the owner and group yourself, click No. Do not set the owner and/or group of the copied files.

    If you manually transfer your repositories, ensure that their owner and group are set appropriately, otherwise permission errors may occur during replication.
    Packaging Dir: The directory in which the package files will be transferred.
    Active Replication Group: A dropdown selector where you choose the replication group to make active.
    When all options have been made, click Continue.

    Create Replication Group 01
  5. Test the nodes' SSH details. If SSH connections can be made to each node, click Continue.
    Create Replication Group 01

    If the test fails, check your SSH settings, and that the node can accept connections on the SSH port (port 22 by default).

  6. The package files are created. When finished, the current node automatically resets. The distinguished node is then ready.
    Create Replication Group 01
  7. Click Deploy Node(s) to transfer the package files to each node.
    Create Replication Group 01
  8. The package files for each node are now transferred. If you selected (in step 4.) to bundle up the repository file, it is also transferred.
    Create Replication Group 01
  9. If you selected to manually transfer your repositories:
    Create Replication Group 01

    You should ensure that copies of the repository are in place on each node before clicking Continue.

  10. Confirm that the repositories for each node have been copied into place or synched. If you choose yes, the node starts up with write access to the repository enabled.
    Create Replication Group 01
  11. The replication group is now activated. Click the Proxy Status link to check that all nodes are up and working.
    Create Replication Group 01

1.4 Deleting a replication group

You can only delete a replication group that is inactive.

  1. Click the Proxy tab, then click Replication Groups on the menu.
  2. Tick the checkbox of the replication group that you want to delete, then click Delete Selected.
    Delete Replication Group 01
  3. You see a confirmation message that the group has been deleted.
    Delete Replication Group 01

1.5 Adding a repository

You can add any number of repositories to the replication group at any time, using the following procedure:

  1. Ensure that the repository that you're adding can't be changed (in a read-only state) then copy it to each node in the replication group.
  2. Add a reference to the new repository to the Apache config file on each node. The form of reference depends on whether you are using SVNParentPath or SVNPath. See Replicating multiple repositories.
  3. Open the admin console using a browser. Click the Proxy tab and then click SVN Settings from the menu.
    Delete Replication Group 01
  4. Click the Add Repository button, found at the bottom of the list of repositories.
    Delete Replication Group 01
  5. Fill in the details of the new repository:
    Delete Replication Group 01

    Directory on File System: The fully qualified path to the Subversion root in which repositories are stored
    Manage Password File: Checkbox to show whether SVN MultiSite will take control of the Subversion password file
    Pre-commit hook: Equivalent to normal pre-commit hook but it is invoked in a replication safe manner
    Pre-Lock Hook: Equivalent to normal pre-Lock hook but it is invoked in a replication safe manner
    Pre-UnLock Hook: Equivalent to normal pre-Unlock hook but it is invoked in a replication safe manner
    Settings in Apache: DAV Location is the path used to access the repository via Apache. For example, if your repository has a DAV location of 'zeppo', then the URL to reach the repository would be

    The DAV location is set within the Apache config file, using the location directive. For example:

    <Location /zeppo>
    AllowOverride None
    Order allow,deny
    Allow from
    DAV svn
    SVNParentPath /tmp/dav
    AuthType Basic
    AuthName wandisco
    AuthUserFile /etc/httpd/conf/htpasswd
    Require valid-user
    Multiple SVN Repositories: Click Yes if you're using SVNParentPath or No if you're using SVNPath.

1.6 Removing a repository

  1. Perform a synchronized stop of the replication group.
  2. If the repository was referenced in the Apache config file (using SVNPath) you should now delete the reference (the whole location directive), then restart Apache for the change to take effect. This step is unnecessary if you are using SVNParentPath.
  3. Go to the admin console, click the Proxy tab. Click the SVN Settings link on the menu.
  4. In the Repository section, go to the line that corresponds with the repository that you are removing. Click the Delete icon (white cross in a red circle).
    Delete Replication Group 01
  5. Restart the replication group. Go to the Proxy tab and click Resume.
    Delete Replication Group 01

1.7 Moving a repository to another replication group

To move a repository from one replication group to another:

  1. Remove the repository from the nodes of the current replication group using the Remove a repository procedure.
  2. Add the repository to the nodes of the new replication group, using the Add a repository procedure.

1.8 Setting MultiSite to start up on system boot

SVN MultiSite comes with sample scripts debiansvnreplicator-init.d-sample and svnreplicator-init.d-sample which are in the /utils/init.d/<OS specific dir> directory.

View a copy of the script: debiansvnreplicator-init.d-sample. This was written for Debian, but is also compatible with Ubuntu.

1.9 Changing the Subversion replicated client port

To change the Subversion replication port that clients use to connect to repositories:

  1. Navigate to the admin console's Proxy tab.
    Change SVN replicated Port 01
  2. Click Nodes on the left side menu.
    Change SVN replicated Port 02
  3. Select a node, then click the corresponding Edit Node link.
    Change SVN replicated Port 03
  4. Ensure that Replicate Changes is set to Yes. Update the node definition at all nodes in this replication group..
    Change SVN replicated Port 04
  5. Enter a new port number in the Subversion Replicated Client Port field.
    Change SVN replicated Port 05
  6. Click the Update Node button at the bottom of the screen. A confirmation message appears near the top of the screen confirming that the change has been made.
    Change SVN replicated Port 06

1.10 Shutting down MultiSite

You can shut down a replicator at any time. Either: