Deployment Guide

This guide describes what you need to consider before integrating WANdisco's Access Control and/or replication technology into your SCM platform. This document cannot address every possible set of conditions so take care to anticipate problems. Contact our support team with any questions or concerns.

1. Deployment checklist

Don't skip this section! Overlooked requirements are a common cause of setup problems that are difficult to diagnose. These problems may take a lot more time to fix than you will checking the list.

You may have read the Deployment Checklist before or during an earlier evaluation of Access Control Plus. However, we strongly recommend that you reread the checklist before deployment to confirm that your system still meets all requirements.

System setup
Operating systems We've tested the following operating systems:
  • 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
  • CentOS: 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 6, 6.1, 6.2, 6.3
  • Suse Linux Enterprise Server: 11

    Contact WANdisco Support for more information about running on this platform.

Reserved ports Access Control Plus requires that several TCP ports are reserved for its exclusive use:
  • application.port=6444: DConE port handles agreement traffic which coordinates replication between sites
  • content.server.port=6445: Used for the replicator's payload data: account / access control changes etc.
  • jetty.http.port=8082: Used for the MultiSite Plus management interface
Plan your ports
While default ports are assigned automatically if you don't select them, we do not recommend that you work with the defaults. Start your production deployment by selecting ports and verifying that they are available at all sites.

Repeat with WANdisco MultiSite products:
If you are running with Git MultiSite or SVN MultiSite Plus you should repeat this step for that application, making sure there are no port reservation conflicts.
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 ports.
Full connectivity Access Control Plus requires full network connectivity between all nodes. Ensure that each node's server is able to communicate with all other servers that will host nodes in your Access Control Plus installation.
VPN Set up IPsec tunnel, and ensure WAN connectivity.
VPN persistent connections Ensure that your VPN doesn't reset persistent connections for Subversion MultiSite.
Bandwidth Put your WAN through realistic load testing before going into production. You can then identify and fix potential problems before they the 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.
Deployment modes The deployment mode is completely controlled by the license.key file. If you need to run in a different deployment mode, or change any othe aspect of your license, see License updates.
Integration with SVN MultiSite Plus:
See Deployment Guide for SVN MultiSite Plus.

Integration with Git MultiSite:
See Deployment Guide for Git MultiSite Plus.

Integration with both (SVN and Git MultiSite):
Running Access Control Plus in this mode enables combined management of Git and Subversion teams and resources. See both MultiSite deployment guides.

Standalone mode
In standalone mode only Access Control data is replicated between nodes. Each Access Control Plus node only manages access to local repository data. Generated password/Authz files are stored directly on the Access Control nodes.
Standalone mode is available for SVN only
Currently the Standalone mode is not able to support Git.
Git or SVN clients Any that are compatible with Git or SVN servers.
Apache server You will need to configure an Apache server to handle repositories appropriately. See specific Git and SVN details in the corresponding guides:
Git MultiSite Authentication (HTTP)
SVN MultiSite Deployment Checklist (Apache)
SSH for Git or SVN SSH authentication is supported by Git MultiSite and SVN MultiSite.
To use SSH for both Git and SVN use two accounts
Make sure that you install Git MultiSite using one account and install Subversion MultiSite using a different account. Do this because the ~account/.ssh/authorized_keys file can only point to either of Git or SVN.

It is easy to set up and is attached to a service that is often already enabled. Occasionally, firewall rules may block clients. This is not as popular with Windows users:

Audit accounts need administrator to change SSH key settings!
Currently, only administrators can update or delete an audit account SSH key. A future release will enable audit account self-service options.

System memory Ensure RAM and swapping containers are at least four times larger than the largest repository file.

Minimum: 2GB RAM; 4GB swapping container
Note: We do not recommend using the minimum
By default, Access Control Plus's Java process is allocated the following heap space: -Xms128m -Xmx2048m
In case of problems getting Access Control Plus running, you may need to alter the heap.
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 do not take into account other applications that you may run on the server, e.g. running Access Control Plus with either the Git or SVN MultiSite products. 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:

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.
Maximum user process limit At least three times the number of Git or SVN users.
Java Install JDK 6 (previously referred to as 1.6) or higher. We recommend using Oracle JDK 6.

JDK 7 Although we currently develop primarily to support Java 6's feature set, Access Control Plus is also compatible with Java 7.

Component compatibility When upgrading Access Control Plus, Git MultiSite or Subversion MultiSite Plus, you must upgrade the Generic File Replication script to match your version of these products. We have tested ACP 1.0 (build 1266) and ACP (build 6503) with ACP GFR 1.0 (build 1635) and MSP/GitMS 1.1 and earlier. Contact WANdisco Support to plan an upgrade to a later version.
ACP 1.0.1 (build 1737) was tested with ACP GFR (build 1737) and MSP/GitMS 1.2* and 1.3.0, 1.3.1.
License model See License Management.

2. Deployment types

You can deploy Access Control Plus in various modes, including:

After installation you can see which mode you're in: Check your mode

3. Install Access Control Plus

When you've checked through the deployment checklist and you're confident that your system meets all the requirements, follow the steps in this section to install Access Control Plus.

Don't forget to check the Release Notes for the current version. They may refer to known limitations that affect you. See Release Notes

If you have problems, see the information on our Knowledgebase before contacting Support.

  1. Download the Access Control Plus installation script from the WANdisco File Distribution website, plus the necessary license key.
  2. Create a home directory for the installation, e.g. /opt/wandisco.
  3. Ensure that the license.key file is placed on your server. You need to provide a path to it during installation. Before you start, make sure the license matches the version of Access Control that you need.
  4. Ensure that the installation script is executable, e.g., enter the command:
    chmod a+x 
  5. Run the installation script.

    Running Apache?
    Run Access Control Plus with the same user and group that is used for Apache. This will help prevent permission problems.

    Non-interactive installation You can complete an installation without user interaction. See Non-interactive installation.

    [root@redhat6 wandisco]# ./
    Verifying archive integrity... All good.
    Uncompressing WANdisco Access Control Plus..........
        ::   ::  ::     #     #   ##    ####  ######   #   #####   #####   #####
       :::: :::: :::    #     #  #  #  ##  ## #     #  #  #     # #     # #     #
      ::::::::::: :::   #  #  # #    # #    # #     #  #  #       #       #     #
     ::::::::::::: :::  # # # # #    # #    # #     #  #   #####  #       #     #
      ::::::::::: :::   # # # # #    # #    # #     #  #        # #       #     #
       :::: :::: :::    ##   ##  #  ## #    # #     #  #  #     # #     # #     #
        ::   ::  ::     #     #   ## # #    # ######   #   #####   #####   #####
    Welcome to the WANdisco Access Control Plus installation
    You are about to install WANdisco Access Control Plus version 1.0.0-1229
    Do you want to continue with the installation? (Y/n) Y
  6. Enter Y to continue. The installer checks for prerequisite applications.
  7. If there's a problem with Java, recheck the deployment checklist for information about their requirement. When Java is confirmed as installed, heap settings are applied for running Access Control Plus.
    Checking prerequisites:
    INFO: Using the following Memory settings:
    INFO: -Xms128m -Xmx2048m
    Do you want to use these settings for the installation? (Y/n) Y

    Use the default settings and enter Y. For production, match these settings to your requirements. In this case, enter N and type in the start and maximum heap values.

    Changing Java heap after installation

    The Java heap settings are stored in the configuration file /opt/wandisco/scn-access-control-plus/main.config, e.g:
    # Access Control Plus configuration

    Setting the LOG_FILE environmental variable

    If you need to capture a complete record of installer messages, warnings, errors, then you need to set the LOG_FILE environment variable before running the installer.
    export LOG_FILE="opt/wandiscoscp/log/file.file"
    This file's permissions must allow being appended to by the installer. Ideally, the file should not already exist (or it should exist and be empty) and its directory should enable the account running the installer to create the file.
  8. The installer confirms TCP ports that it requires:
    Which port should ACP listen on? [8082]: 8082
    Which port should DConE listen on? [6444]: 6444
    Which port should the Content Delivery service listen on? [6445]: 6445
    You can use the default values. However, we strongly recommend that you allocate ports as part of a detailed site survey so that you can be sure that there are no conflicts and that all required ports are available on all sites.
  9. Enter the path to your license.key file, then press Enter:
    A license file is required to use Access Control Plus
    Path to the license file: /opt/wandisco/license.key	
  10. Enter a name for the Access Control Plus Node. This is used to refer to this particular instance of Access Control Plus. Choose a unique name consisting of numbers and letters:
    Node name: node70
  11. Enter system user and group details for running Access Control Plus. Note the warning about not using root user. In this case we've created a specific user and group to use with our SCM-related services and applications:
    We strongly advise against running Access Control Plus as the root user.
    Which user should Access Control Plus run as? wandisco
    Which group should Access Control Plus run as? wandisco	
  12. The next option configures the node for operating as part of a replication group. If you are installing a single Access Control Plus node, select Y. If you are installing multiple Access Control Plus nodes for replication, you need to decide which nodes will have this option enabled:
    One of your Access Control Plus nodes needs to be configured as a state machine creator. This MUST only be configured on ONE node.
    Configure this node as the statemachine creator? (y/N) y
    We entered y. If you're installing multiple Access Control Nodes then select enter y for just one of them.
  13. Enter the details for an administrator account. You use these details to access the Access Control admin console:
    Access Control Plus needs an admin user to be configured
    First Name: Adie
    Last Name: Ministrator
    Username: admin
    Email Address:
    Enter a password for admin:
    Confirm the password for admin:
  14. You are given a summary of your entries. Check them and enter y if you are happy to continue:
    Installing with the following settings:
    System user:                 wandisco
    System group:                wandisco
    Node name:                   node70
    Application Port:            8082
    DConE Port:                  6444
    Content Delivery Port:       6445
    Application Hostname:
    License:                     /opt/wandisco/license.key
    Admin user:                  admin
    Application Minimum memory:  128
    Application Maximum memory:  2048
    Statemachine Creator:        true
    Do you want to continue with the installation? (Y/n) y
  15. The installation completes and confirms a restart:
    Restarting scm-access-control-plus services...
    Stopping scm-access-control-plus:[  OK  ]
    Starting scm-access-control-plus:[  OK  ]
    Installation Complete
    [root@redhat6 wandisco]#
    At this point the Access Control Plus is running. Open a browser and point it at http://<serviceIP>:8082/ui.
    If you chose a different application port earlier in the process then you need to use it instead of the default "8082".

    Include /ui/ from the URL
    The browser-based admin console requires that you include the /ui/ directory in its URL. A future release will ensure that any request on the application port will redirect to the admin console.

  16. You are presented with the Access Control Plus End-user Agreement. Read through the agreement, then click Accept to continue.
    Access Control Plus Login
  17. Log in for the first time. Enter the username and password that you provided earlier. Then click Let's do this
    Access Control Plus Login
    You see Access Control Plus's Management Screen. This summarises the accounts, teams and SCM repositories that Access Control Plus manages, and rules that dictate the SCM resources that account holders can access.
    Access Control Login 2

4. Setting up

After installing you need to set up Access Control Plus to work to your deployment requirements. Different deployments require different steps. Below are checklists for some example deployments.

4.1 Standalone mode

In Standalone mode there's no integration with an SCM replication product (e.g. Git MultiSite).

In this example you run with multiple Access Control Plus nodes, using LDAP authentication and SSL end-to-end encryption of traffic. Click each step to be taken to the relevant sections. Ignore or replace steps that aren't required. For example, if you are not running with LDAP, you might replace that step with Adding Accounts.

Follow the links in these steps if you are deploying in Standalone mode:

  1. Induction: Connecting your nodes
  2. LDAP: Enable LDAP Auth
  3. SSL: Enable SSL encryption
  4. Email notifications: Set up email notification
  5. Repositories templates: Create repositories templates
  6. Resources: Add resources
  7. Teams: Create a team
  8. Rules: Create a rule

If you are running with only one Access Control node, you can drop the Induction step.

4.2 Access Control Plus with MultiSite

Follow the links in these steps if your are deploying with a MultiSite product:

  1. Induction: Connecting your nodes
  2. Git/SVN MultiSite: Connect to MultiSite
  3. LDAP: Enable LDAP Auth
  4. SSL: Enable SSL encryption
  5. Email Notifications: Setup Email notification
  6. Repositories Templates: Create repositories templates
  7. Resources: Add resources
  8. Teams: Create a team
  9. Rules: Create a rule

Access Control Plus is now installed. Before you start setting up accounts, teams, etc. you should run through the Settings screen. First, check off what other elements on your platform need to be integrated into Access Control Plus.

4.3 Setting up LDAP

It is common practice to use one or more LDAP authorities for managing which employees need accounts created in Access Control Plus. You connect any number of LDAP authorities, adding them through the Settings screen.

Local users are exempt from updates and removal for synchronization of team admins and team members. This means that a local admin who appears in an authority won't suddenly be added to a team or be made into a sys admin. Instead a message is logged to indicate that this user has been skipped. The sys admin must then ensure that the local user is removed.

4.4 Access control settings

1. From the admin console, click the Settings link on the menu bar.
Settings 01

2. The settings are displayed in an accordion-style menu. Click either the links on the side menu or the title bars in the right-hand panel.
Settings 01

Full details on setting up each section are provided in the Settings reference guide. Apply settings suitable for your deployment of Access Control Plus. The product's appearance and functionality differs depending on whether you are running it in a standalone mode or in conjunction with WANdisco's Git or SVN MultiSite products.

4.5 Application Settings

These settings extend Access Control Plus's functionality:

4.6 Node Management

These settings control how Access Control Plus communicates with other Access Control Plus nodes on the replication network, specifically when Access Control Plus is used with WANdisco's DConE replication protocol.

4.7 External Applications

These connect Access Control Plus to supporting systems for additonal functionality.

5. Non-interactive installation

You can start installing a node without root-level terminal access to the server, known as a silent installation. When the installation has finished you can complete the configuration of the node through a browser (interactive-style) or script the configuration using REST API calls. Note, however, that induction of the nodes still requires interaction with the admin UI.

For a silent installation run:

The installation then runs without user interaction. When completed, the browser-based admin console starts. You then need to complete the node setup from the restart stage.

You should be able to build additional automation into the installation by using various calls to the REST API, e.g. setting up an admin account, setting up defaults for resources, templates and LDAP settings, etc. However, you cannot yet complete the induction of nodes without support from WANdisco's support team.

Environmental variables used are:
ACP_USER=wandisco: System user for the Access Control Plus process
ACP_GROUP=wandisco: System group used by Access Control Plus process
ACP_PORT=9000: Port allocated for web access to the admin console
ACP_DCONE_PORT=9050: Port allocated for replicated data
ACP_CONTENT_PORT=8000: Port allocated for Access Control's internal content delivery
ACP_NODE_NAME=node1: Name of the Node which is different for each node
ACP_ADMIN_USER=admin: Admin account username
ACP_ADMIN_FIRST_NAME=mr: Admin account first name
ACP_ADMIN_LAST_NAME=admin: Admin account last name Email address for the admin account - needed to allow Access Control Plus to send out notification emails
ACP_ADMIN_PASSWORD=password: Admin password
ACP_MEM_LOW=128: The minimum amount of memory allocated to Access Control Plus
ACP_MEM_HIGH=2048: The maximum amount of memory allocated to Access Control Plus
ACP_LICENSE_FILE=/home/wandisco/keys/License.key: The full path to the license.key file
ACP_STATEMACHINE_CREATOR='true': True only for a single (induction controller) node, false for the rest
ACP_HOSTNAME=node1: The IP address or fully qualified domain name of the node which must match with those encoded into to the license.key file