WANdisco

 Subversion MultiSite v3.7 - Installation Guide

wandisco.com |Home | Pre-deployment | Installation | Upgrade | User Guide | Technical Guide | Glossary
*

Installation
1. Installation overview
2. Starting the installation
  2.1 Starting the installation
  2.2 Place your license key
3. Run the setup file
4. Complete setup through a browser
5. Login to the admin console
6. Setting up additional nodes
7. Create a replication group
8. Copy the installation files manually
9. Post installation configuration
  9.1 Using pre-commit hooks

Pre-deployment
1 Introduction
  1.1 Deployment Overview
  1.2 System requirements
  1.3 Setting up repositories
  1.4 Using two or more repositories
    1.4.1 Subversion location directive
    1.4.2 About Subversion ParentPath
  1.5 Using the Authz Module
  1.6 MultiSite and Subversion password files
  1.7 Quorum recommendations
  1.8 Firewalls and virus scanners
  1.9 Deployment checklist
  1.10 Creating a new Subversion repository?
  1.11 Configuring Apache
        1.11.1 Changing Subversion port (Unix)
        1.11.2 Sharing Apache, and Using HTTPS
        1.11.3 Using HTTP with Apache
        1.11.4 Apache and SVNKit
        1.11.4.1 SVNKit and Connection Pooling
        1.11.4.2 Optimize Your Configuration
        1.11.5 Apache 2.2/SVN-DAV (Windows)
2 Installing Java and Perl
  2.1 Installing Java
  2.2 Installing Perl

Upgrade
1. Upgrade using the upgrader script
2. Upgrade using backed-up data
3. Backup your settings
4. Delete directories
5. Extract and run the setup file
6. Browser based setup
7. Import your saved settings

User Guide
1. Procedures
1.1 Disabling Access to Subversions
  1.1.1 (selected nodes)
  1.1.2 (all nodes)
1.2 Establishing a baseline for replication
    1.2.1 Copying the Subversion Database
    1.2.2 Synchronizing with an older copy
    1.2.3 Copying Over the Network
    1.2.4 Sending repositories on disk
1.3 Finding the Last Committed Transaction
1.4 Adding a repository to a replication group
1.5 Removing a Repository from the Replication Group
1.6 Moving a Repository to another replication group
1.7 Adding a Node to the Replication Group
1.8 Removing a Node from the Replication Group
1.9 Creating a New Replication Group
    1.9.1 Considerations
    1.9.2 Considerations for Majority Quorum
    1.9.3 Procedure
1.10 Deleting a Replication Group
1.11 Emergency Reconfiguration of Quorum
1.12 Changing a prefs.xml File
    1.12.1 Changing One Node's prefs.xml File
    1.12.2 Changing All Nodes' prefs.xml Files
1.13 Performing a Synchronized Stop
1.14 Verifying That the replicator is working
1.15 Installing an updated .jar File
1.16 Changing the Distinguished Node
1.17 Using Subversion triggers for sending e-mails
1.18 Toggling the Quorum Check
1.19 Changing the admin console username
1.20 Changing the admin console password
1.21 Resetting or recovering the admin console password
    1.21.1 Restore the admin console password
    1.21.2 Reset the admin console password as "wandisco"
1.22 Setting Up Hooks"
    1.22.1 Pre-Replication Hook"
      1.22.1.1 Configuration
      1.22.1.2 Repository-Specific Hooks
1.23 Selective Replication
1.24 Updating Apache or Subversion
1.25 Checking Repository Consistency

2. Replicator Management
2.1 Setting Replicator to Start Up on System Boot
2.2 Setting up the Replicator as a Windows Service
2.3 Changing the Quorum Type
2.4 About Watchdog Mode
2.5 Temporary Files

3. Troubleshooting
3.1 How Do I Get WANdisco Support?
3.1.1 How Do I Run the Talkback Script?
3.2 General Subversion MultiSite
    3.2.1 Connection Request Timeout Messages
    3.2.2 VPN, NAT, Firewall Timeouts
    3.2.3 A node is in read-only mode
3.3 Error messages
    3.3.1 Missing License Key file
    3.2.1 Connection Request Timeout Messages
    3.3.2 I'm getting a severe exception
    3.3.3 Compressed Stream Invalid
    3.3.4 Java consistency check on relicator restart
3.4 Oops!
    3.4.1 I Directly Committed to Subversion, How Do I Rsync?
    3.4.2 I Pressed Ctrl-C During a Subversion Command

4. Frequently Asked Questions
4.1 Why Are So Many Java Processes Running?
4.2 Can I Store Logs or Content on NFS?
4.3 Why is Installer Configuring IP Addresses as 0.0.0.0?
4.4 Should I Worry About Time Changes or Time Zones?
4.5 Does WANdisco Support Dynamic DNS?
4.6 Can I Use SSH Tunnel to Navigate a Firewall?
4.7 WANdisco Authentication
4.8 Encryption Around WANdisco Protocol
4.9 How Do I Restrict Direct Access to My Repository?
44.10 About MultiSite log files
4.11 How do I deal with failover agent failure?

5 Guide to the Admin Console
5.1. Security
  5.1.1 Create Roles
  5.1.2 List Roles
5.2. User Administration
  5.2.1 Create User
  5.2.2 List Users
  5.2.3 Import Users
  5.2.4 Change Admin Password
5.3. Group Administration
  5.3.1 Create Group
  5.3.2 List Groups
  5.3.3 Assign Users
  5.3.4 Remove Users
  5.3.5 Import Groups
5.4. ACL Administration
  5.4.1 Create ACLS
  5.4.2 List ACLS
  5.4.3 ACL Options
5.5. System
  5.5.1 Log Viewer
  5.5.2 System Settings
  5.5.3 Transaction Status
  5.5.4 Log Level
  5.5.5 Free Memory
  5.5.6 Dashboard
  5.5.7 Export Settings
  5.5.8 Import Settings
5.6. Proxy
  5.6.1 Proxy Status
  5.6.2 Log Viewer
  5.6.3 SVN Settings
  5.6.4 Email Settings
  5.6.5 Change Distinguished Node
  5.6.6 Stop Proxy
  5.6.7 Shut Down Node
  5.6.8 Nodes
  5.6.9 Replication Groups
  5.6.10 Replication Group History
5.7 Reports
  5.7.1 Configure URI
  5.7.2 User Group Report
  5.7.3 Audit Reports

Technical Guide
1. Introduction
2. MultiSite Overview
3 WANdisco Concepts
  3.1 How Replication Works
  3.2 Replication Example
  3.3 WANdisco is Listening
  3.4 Synchronized Stop of all nodes
4. Handling Node and Network Failure
  4.1 Node Failure
  4.2 Network Failure



1. Installation overview

The installation guide runs through setting up Subversion MultiSite for the first time. If you're already using an earlier version of MultiSite, follow the Upgrade section instead.

Before we begin, here is a recap of the installation process:

  • 1.1 Revisit the pre-deployment checklist. Taking extra time making sure you have everything set up and ready may save you from running into problems during the installation process. The main boxes you need to tick are:

    • Subversion authenticating: Subversion installed, and using authentication (as set in the Apache config file. MultiSite will only replicate changes to your Subversion repository if authentication is used.

    • JDK1.6: You need to have Java JDK 1.6 installed.

    • Java Memory Settings: MultiSite will start with 1GB and reserve 2GB of memory when it starts up. Changing the default Java heap size.

    • System resources: Ensure that your system is going to operate with a comfortable margin. Hardware Sizing Guide Knowledgebase article.
  • 1.2 Have your repository in place at all the servers you plan to replicate. MultiSite can automatically transfer small (less than 1GB) repositories when you add additional MultiSite nodes.
  • 1.3 Make sure that Apache is running and the Apache config file as been updated to support MultiSite.
  • 1.4 Copy the MultiSite files into place.
  • 1.5 Run the setup, then complete the installation from a web browser.

You are going to run the installer at the first node. You don't need to run the installer at any other node, MultiSite will create install packages for other nodes and transfer them automatically.

Once Subversion MultiSite is installed and you have synchronized repositories, NEVER make a change to your repository that will bypass MultiSite's replicator. This causes the repositories to be out-of-sync.

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

Once Subversion MultiSite is installed, we strongly recommend that you set up the replicator as a service to ensure that it automatically restarts on a system reboot.

2 Starting the installation

2.1 Extract the setup file

2.1.1 Save the svnrep.tar.gz archive to your Installation node.

2.1.2 Extract the setup files using a compression utility that supports the .gz (gzip) format.

Ensure that you install the MultiSite files to a directory called svn-replicator and that you preserve the following subdirectory structure:

Directory Contents
/audit Contains the audit trail logs for Access Control.
/bin Contains scripts like svnreplicator and shutdown
/config Contains the svn-replicator/config/prefs.xml file used to configure MultiSite. The license file needs to be place here before you can run MultiSite.
/lib Contains the Java archives (jar) files required to run the MultiSite.
/logs Stores logs and other temporary files. MultiSite's main log file is named SVNProxyServer-prefs.log.0
/systemdb Contains the system database with its transaction journal. Warning: Deleting or modifying files from systemdb will likely corrupt your installation.

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

<replicator01>/svn-replicator
<replicator02>/svn-replicator
<replicator03>/svn-replicator 

Selective replication is used when you need to replicate only specific repositories. You can find further information in 1.23 Selective Replication.

2.2 Place your license key

2.2.1 To validate your installation you need to copy the license.key file to the svn-replicator/config directory.

3. Run the setup file

3.1 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>

3.2 Setup will begin by confirming how much memory needs to be allocated to JAVA. By default, MultiSite starts with 1024MB (1GB) whilst reserving 2048MB (2GB).

MultiSite setup 1

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

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

MultiSite setup 2

3.3 Setup will now start up the web interface. Open a browser and type in the given address. The default port is 6444. If you entered a different port (step3.1) then use this instead:

http://<server IP>:<6444>

4. Complete setup through a browser

4.1 In your browser you'll see the setup welcome screen. Follow the link to the pre-installation checklist to make a final check that everything is place for a successful installation. When you're ready, click continue.

MultiSite setup 3


4.2 Read through the WANdisco End User License, click I Agree to continue.

MultiSite setup 4


4.3 The default username for getting into Access Control is admin. In the next step you need to enter a password for the admin account. Once you've chosen a password, click Next.

MultiSite setup 5


4.4 The next two screens explain how MultiSite will act as a proxy between Subversion clients and the Subversion server. Click Next to continue.

MultiSite setup 6


4.5 By default, Access Control will listen on port 80, while Subversion will listen on port 8080. The benefit of this setup is that Subversion end-users don't need to make any changes. Click Next to continue.

MultiSite setup 7


4.6 Next, you'll confirm the proxy settings. These will be populated with the default port settings noted in the previous screens.

Node Name: The name that Access Control will use for sever 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.
Bind Host: By default, this uses the wildcard 0.0.0.0 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 change to their client setup.

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

Admin Console Port: 6444 by default.


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

MultiSite setup 8


4.7 Setup will now check the Apache config file for settings that might cause problems for MultiSite.
More about Apache configuration changes for MultiSite.

MultiSite setup 9

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:

MultiSite setup 10

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.

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


4.8 Setup now allows you to modify your Subversion settings. Watch for alerts that confirm the port and path that MultiSite will associate with the Subversion server.

MultiSite setup 12
Subversion Server Port: 8080 by default.
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, once the installation is completed, you must confirm the version of Subversion you are using, then edit the option from the SVN Settings page.

MultiSite setup

SVN and WANdisco are on the same server: Select Yes or No. There are benefits to running MultiSite and Subversion on the same server.
SVN Executable:This is the fully qualified path to the Subversion executable. Setup will try to fill this in automatically, otherwise type it into the entry box.
Use authz-based accss control? Tick the box to have MultiSite use Authz authentication.
Use LDAP for authentication Tick the box to use an LDAP service. Provide the URL to your LDAP server.


At the bottom of the screen is a table that confirms the DAV Location and password control for your repositories. You can click Edit to make changes. 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:

MultiSite setup 12b

Directory on Files System: This is the fully qualified path to the Subversion repository, not the URL used by clients to connect.
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
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.


4.9 You can enter email settings so that MultiSite can send alerts.

MultiSite setup 13

SMTP Authentication: If you select No, you'll need to provide your account.
Username and Password in the following entry boxes.
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 (You can only specify a single address, not a comma delimited list) to where notifications will be sent.

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


4.10. 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 will start running. You'll be prompted to reload the admin console using an SSL connection.

MultiSite setup 15

5. Login to the Admin Console for the first time

5.1 The browser will refresh to show the Admin Console login screen.

MultiSite setup 15

To enter for the first time, the username is admin and the password will whatever you entered during setup (step 4.3).


5.2 When you first enter the Admin Console you'll be prompted to create a new user and other nodes.

MultiSite setup 16

There's a detailed guide to the Admin Console in the User Guide.

6. Setting up additional nodes

Once you've confirmed that your first node is up and running, it's time to add the nodes at your other sites.

Add additional nodes using the Admin Console. Don't repeat the setup process.

6.1 Click on Click here to create new nodes.

MultiSite nodes 1

The Node Properties page appears.

MultiSite nodes 2

Enter the details of your new node:

Node properties
Name: A name by which MultiSite will refer to the Node
Host Name: DNS name or IP address of the node
Bind Host: The IP bound to MultiSite. We suggest using 0.0.0.0. why we bind to 0.0.0.0.
Port:Port number allocated to the node. The default port is 6444.

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.
SSH Port: Default port for SSH is 22. Assign if a different port if required.
Authentication: By username/password that you provide below, or by Private Key File.
Java Home: The path to JAVA on the new node.

Click Create Node to continue. Click Create and Test to connect to the node and check for JAVA using the details you have provided. If you get an error relating to JAVA, see Installing Java

MultiSite nodes 3

You've set up an additional node. Repeat the process to add more.

Once you've created all your nodes, you need to create a Replication Group.

7. Create a Replication Group

7.1 Click Replication Groups on the side menu.


MultiSite nodes Replication Group 1


7.2 Click Create Replication Group.

MultiSite nodes Replication Group 2


7.3 Enter the details for your Replication Group:

MultiSite nodes Replication Group 3


Replication Group Name: A name by which MultiSite will refer to your replication group.
Quorum Configuration: Select a quorum type from the drop-down menu. Before choosing, ensure that you understand the benefits of each type. Quorum Recommendations.
Distinguished Node: If you select a quorum type which uses a distinguished node, it's identified here.
Nodes: You can select which nodes you've created are to be added to the replication group.

Once you've entered all the details, click Create Replication Group.

7.4 Next, click on Activate.

MultiSite nodes Replication Group 4

7.5 Time to decide on how you'll package and put in place the MultiSite and your repositories.

Activation Information
You need to decide if MultiSite will transfer files to the other nodes using SSH, or whether you need to transfer the archive files manually, for instance, you're unable to connect to the other nodes using SSH.

Packaging Options
You can have MultiSite automatically transfer an archive of your repository to the other nodes. There's guidance on this option in the Pre-deployment guide, under Setting up repositories.

If you choose to manually transfer the repository, an archive file will be created for you, which will be saved to the Packaging Directory.

If you change the packaging directory, make sure that it isn't set as a child or parent of the product installation.

MultiSite nodes Replication Group 5

When you've completed the settings, click Continue. If you are dealing with multiple Replication Groups, you can select which group you wish to activate using the Activate Replication Group drop-down.

7.6 If you've selected to SSH either the MultiSite files or the repository, MultiSite will check that it can connect to all the nodes. If the test completes successfully, click Continue. If the test fails, check that all your nodes are running SSH, and that there isn't a firewall or network restriction that is blocking SSH.

MultiSite nodes Replication Group 6

7.7 MultiSite will now transfer its files to the other nodes. You can watch the progress as it runs.

MultiSite nodes Replication Group 7

7.8 Click on Deploy Nodes to start up the additional nodes. If you've selected to package your repository, it will be copied across first.

MultiSite nodes Replication Group 9

7.9 The transfer is shown using progress bars. If you have singleton quorum and the distinguished node is the local node, you can release the local node to users before the transfer completes. MultiSite will resync the repositories when the other nodes activate.

MultiSite nodes Replication Group 10

7.10 When the transfer is complete you can click on the Proxy Status link to confirm that all nodes have started properly.

MultiSite nodes Replication Group 11

7.11 You can click on the Show Dashboard with Selected to view replicated transactions. It's a good idea to do some Subversion commits in order to verify that replication is working properly.

MultiSite nodes Replication Group 12

8. Copying the installation files manually

Follow these instructions if you were unable or chose not to use the automated packaging option Covered 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:

8.1 Copy the [node name].zip to the new node

8.2 At the new node, extract the [node name].zip file to a temporary directory called 'wandisco'.

8.3 From a command prompt type:

cd wandisco
perl unpackage

8.4 Follow the directions provided by the unpackage script.

9. Post Installation Configuration

There are some changes you may need to make before starting to use Subversion through MultiSite. These changes are made through the Admin Console, theres a detailed guide to the Admin Console in the User Guide

9.1 Using pre-commit hooks?

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





Copyright © 2010 WANdisco
All Rights Reserved

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