Deployment Guide

This guide describes 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

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.

2. Deployment types

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

• Standalone: One or more nodes that handle repository access control within a non-replicated SCM environment. I.e. Access Control Plus can still be replicated between multiple nodes. "Standalone" indicates that it is not dealing with replicated Git or SVN data.
• With Git MultiSite: One or more nodes deployed at one or more sites in conjunction with WANdisco's Git MultiSite product.
• With SVN MultiSite: One or more nodes deployed at one or more sites in conjunction with WANdisco's SVN MultiSite product.
• Both (with Git & SVN MultiSite): One or more nodes deployed at one or more sites in conjunction with both of WANdisco's SCM replication products.

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.

1. Download the Access Control Plus installation script scm-access-control-plus_rpm_installer.sh 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 scm-access-control-plus_rpm_installer.sh 

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.

   Workaround if /tmp directory is "noexec"
   Running the installer script will write files to the system's /tmp directory. If the system's /tmp directory is mounted with the "noexec" option then you will need to use the following argument when running the installer:
   --target <someDirectoryWhichCanBeWrittenAndExecuted>
   E.g.

   ./scm-access-control-plus_rpm_installer.sh --target /opt/wandisco/installation/

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

   [root@redhat6 wandisco]# ./scm-access-control-plus_rpm_installer.sh
   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 aIpplied 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
   # DO NOT DELETE
   ACP_USER=wandisco
   ACP_GROUP=wandisco
   ACP_MEM_LOW=128
   ACP_MEM_HIGH=2048
         	

   
   

   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.
   Run:

   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: adie@theorganization.com
    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:        10.0.5.96
    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.
    
17. Log in for the first time. Enter the username and password that you provided earlier. Then click Let's do this
    
    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.
    
    

3.1 Install auditing function

3.1.1 At first ACP install

At the end of the ACP install process you are asked:

Do you wish to install auditing components for use with Access Control Plus? (Y/n)

Make sure that you are certain that you want to install these components. For example, currently, when enabling global wildcards you receive no warning that this action cannot be reversed. You receive the message:

This cannot be undone without reinstalling.

1. Enter y.
2. Confirm the details, using defaults as appropriate, to create an Apache log file and use Flume to send/receive the log details:

   Notes:

   • You only need to install the auditing component on one node.
   • A logger account is created during install. You need to provide a user name and password for this.
   • By default, the Flume process is run as the WANdisco user. For the sender (installed on Git MultiSite and SVN MultiSite Plus) to be able to capture the auditable events it needs to have access to the correct log file. If for example the apache access_log is owned by root, WANdisco cannot read it!
   • You need to set at least one log location per product. Otherwise, Flume will not monitor any logs at all:
     • FLUME_GITMS_LOG is the log location of the Git MultiSite log to monitor
     • MultiSite Plus uses:
       • SVN_ACCESS_LOG=<svnServe log location>
       • SVN_WEBDAV_LOG=<apache log location - normally /var/log/httpd/access_log>
     Note: If you configures an "svnserve" log file for auditing, make sure that it exists (else the auditing deamon aborts).
     Make sure that, whichever user is running, the flume_sender can actually read the log file permissions (normally wandisco user or apache user).
   • You will need to set the following environment variables:
     • FLUME_INSTALL_DIR: Flume install location for acp-flume-receiver
     • ACP_USER_ID: Logger user ID to connect flume->acp
     • ACP_USER_PASSWORD: Logger user password to connect flume->acp
     • ACP_USER_EMAIL: Logger user email
     • ACP_AVRO_HOST: Flume receiver IP
     • ACP_AVRO_PORT: Flume receiver port
     • FLUME_ACP_HOST: ACP IP for Flume to connect to
     • FLUME_ACP_PORT: ACP rest port for Flume to connect to
     • FLUME_AVRO_SSL: true/false to enable/disable SSL
     • FLUME_AVRO_KEYSTOE_LOC: Only required if FLUME_AVRO_SSL=true, keystore location
     • FLUME_AVRO_KEYSTORE_PASS: Only required if FLUME_AVRO_SSL=true, keystore password
     • FLUME_AVRO_TRUSTSTORE_LOC: Only required if FLUME_AVRO_SSL=true, truststore location
     • FLUME_AVRO_TRUSTSTORE_PASS: Only required if FLUME_AVRO_SSL=true, truststore password

   Note: The query regarding "SVN access log" applies to SVNServe. Unless you have SVNServe set up with logging enabled, then answer "n" to this question.

   Please enter Flume installation location.  We recommend the use of a separate file system with sufficient disk space for several days of auditing events. [/opt/wandisco]: 
   
   Do you want to monitor an Apache log? (Y/n) y
   
   Location of Apache access log. [/var/log/httpd/access_log]: 
   
   Do you want to monitor an SVN Access log? (Y/n) y
   
   Location of SVN access log. [/var/log/httpd/access_log]: 
   
   Please enter Flume Receiver connection details.
   
   Flume Receiver Hostname or IP address: 192.168.58.190
   
   Flume Receiver Port: 8441
   
   Is SSL enabled? (y/n) n
   
   ACP Logger User: logger
   
   ACP Logger User Password:
   
   ACP Logger User Email Address: l@l.com

   The monitoring questions above (regarding Apache, SVNServe, etc.) enable auditing for the standalone license of ACP. Instances of ACP talking to either one or both of Git MultiSite and MultiSite Plus should not require ACP's monitoring because they should be monitored by the Flume installed by those products.

   Note: If you set up SVNServe later, you need to modify the sender config file, for example for SVN, /opt/wandisco/flume-svn-flume-sender/conf/acp_sender.conf:

   1. Change:

      acpSender.sources =  svnWebdavSource

      to:

      acpSender.sources =  svnWebdavSource svnServeSource

   2. Add the following sections as applicable:

      acpSender.sources.svnServeSource.type = exec
      acpSender.sources.svnServeSource.command = tail -F <svnServe-log-location>
      acpSender.sources.svnServeSource.restart = true
      acpSender.sources.svnServeSource.channels = memChannel

   3. Save the file.
   4. Restart the SVN Flume sender.

   If you want to then disable SVNserve, remove svnServe from this line:

   acpSender.sources =  svnWebdavSource svnServeSource

   If you are installing or upgrading in non-interactive "silent" mode:
   One of the final steps you must implement is to call the following REST API after EULA acceptance, and with all ACP nodes operational:

   curl -u admin:pass -X PUT localhost:8082/api/settings/createauditstatemachine

   Note: This call outputs a task id, and you need to follow it to make sure that it finishes. To do that, you make the following call, until the status returns isDone=true:

   curl -u admin:pass -X GET /api/task/<returnedTaskID>

   When the task is complete, after approximately 30 seconds to a minute, you must do the following check at all ACP nodes:

   curl -u admin:pass -X GET /api/settings/auditstatemachineid

   If the call returns null on all of your nodes then you must:

   1. On one of the nodes that returned null, make a REST call to:

      curl -u admin:pass -X PUT /api/settings/resetproposedauditdsmid

      Make sure that a task id is returned.
   2. Then make a REST call to:

      curl -u admin:pass -X GET /api/task/<returnedTaskID>

      Confirm that the task has completed.
   3. At this point you must start the procedure over.

   If the call returns a mix of nulls and non-nulls, then call WANDisco Support.

   3.1.2 With ACP upgrade to 1.5

   During the 1.5 upgrade installation you must set the ENABLE_AUDITING variable. If you set this variable to TRUE then you also need to set the variables listed in section 3.1.1.

   3.1.3 Flume send

   Flume config file is acp_sender.conf.

   Note: This is only for the Standalone license.

   To start the Flume sender use:

   /etc/init.d/flume_sender start

   To stop the Flume sender use:

   service svn-msp-flume-sender start|stop

   3.1.4 Flume receive

   Flume location can be set on install. It defaults to /opt/wandisco/flume-<product-name> so is /opt/wandisco/flume-svn-multisite-plus or /opt/wandisco/flume-scm-access-control-plus:

   cd /opt/wandisco/flume/-<product-name>./runFlume.sh

   Note: You only need to use this if you need to stop the auditing separately from the system. System startup/shutdown automatically starts/stops the Flume components as well as ACP.

   3.1.5 FLUME_MAX_MEMORY

   When upgrading from ACP 1.5.1.1, the environmental variable FLUME_MAX_MEMORY is not currently set correctly. You need to set the value in /opt/wandisco/scm-access-control-plus/config/main.conf.

   Default value: 256m, (MiB RAM)
   Recommended value: 256m

   You need to set the variable in the main.conf, if you set the variable only through the console, the upgrade will work but afterwards, flume-agent will not start.

   Memory sizes in the main.conf file are in MiB but must be integers. Do not append the 'm'.

   You will need to set the value up higher if Apache, svnserve, etc. logfile entry rate is higher. If set too low the Flume log file will show an error and the Flume agent will have exited.

   3.2 Install Generic File Replication RPMs

   On all replicating nodes where you have SVN MultiSite Plus and/or Git MultiSite installed, you need to install the relevant RPMs for Generic File Replication. One RPM is dedicated for SVN MultiSite Plus and one for Git MultiSite. For example, for Access Control Plus 1.0 GA Build 1365, the SVN GFR RPM is ACP GFR SVN 1.0 GA Build 1365. If you do not install the RPMs you receive an error message.

   The RPMs contain the receiver scripts noted in the Generic File Replication for MultiSite section.

   3.2.1 SVN MultiSite Plus

   On all nodes:

   1. Make the RPM executable:

      chmod 777 acp-gfr-scripts-svn.noarch.rpm

   2. Install the RPM:

      rpm -ivh acp-gfr-scripts-svn.noarch.rpm

      You see the following output:

      Preparing...                ########################################### [100%]
         1:acp-gfr-scripts-svn    ########################################### [100%]
          

   3. To verify the RPM executed successfully, navigate to the directory where SVN MultiSite is installed and check that the ACP GFR scripts are present. For example:

      [root@node1 bin]# cd /opt/wandisco/svn-multisite-plus/replicator/gfr/bin
      [root@node1 bin]# ls
      acp  acp_gfr_main.sh  acpLockAndRun  postDeliveryAZPW

      The postDeliveryAZPW file listed above is not part of the GFR scripts.

   4. Check that the ACP authz and password files are replicated across all Git nodes correctly.

   3.2.2 Git MultiSite

   On all nodes:

   1. Make the RPM executable:

      chmod 777 acp-gfr-scripts-git.noarch.rpm

   2. Install the RPM:

      rpm -ivh acp-gfr-scripts-git.noarch.rpm

      You see the following output:

      Preparing...                ########################################### [100%]
         1:acp-gfr-scripts-git    ########################################### [100%]

   3. To verify the RPM executed successfully, navigate to the directory where Git MultiSite is installed and check that the ACP GFR scripts are present. For example:

      [root@node2 bin]# cd /opt/wandisco/git-multisite/replicator/gfr/bin
      [root@node2 bin]# ls
      acp  acp_gfr_main.sh  acpLockAndRun  postDeliveryAZPW

      The postDeliveryAZPW file listed above is not part of the GFR scripts.

   4. Check that the ACP authz and password files are replicated across all Git nodes correctly.

   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.
   

   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.
   

   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:

   • Access Control Updates: This option contains settings for running Access Control in Batch updates mode. For more information see the reference section on Batch updates.
   • Repository Templates: This option defines Git or SVN repositories. For Access Control Plus to manage access to a repository, you must add a template that corresponds with an existing repository, along with appropriate references to a password or authorization file.

     See Adding repository templates, Managing Repository Templates.

   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.

   • Node Induction: The Node Induction option describes how to connect this particular instance of Access Control Plus to a replication network. Again, this applies to deployments where multiple instances of Access Control Plus are running, which would allow each development site to have its own replica of the access control service. See Inducting a node.
   • Node Repairs: Use this option if one or more nodes are lost or experiencing a lengthy disconnection from the replication network. This redefines the replication group so that the remaining nodes can continue to operate. See Running a node repair.

   4.7 External Applications

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

   • Connect to MultiSite: If you are running Access Control Plus with WANdisco's Git or SVN MultiSite products then you need to enter the necessary details for Access Control Plus to talk to MultiSite via its REST API interface. See Connecting to SVN MultiSite and Connecting to Git MultiSite.
   • Connect to LDAP: Most deployments use an existing LDAP authority to manage their employee system accounts. This option lets you connect to multiple LDAP authorities and set up queries to filter for accounts that need access to SCM resources. See Adding an LDAP Authority, Manage LDAP Authorities.
   • Email Notifications: Set the Email Notifcations to connect to an available relay server so that Access Control Plus can send notifcation emails to administration staff.

     See Enable email notifcations and Manage email settings.

   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:

   ACP__USER=wandisco
   ACP_GROUP=wandisco
   ACP_PORT=9000
   etc...
   export ACP_USER ACP_GROUP ACP_PORT ACP_DCONE_PORT ACP_CONTENT_PORT ACP_NODE_NAME etc...
   ./scm-access-control-plus_rpm_installer.sh 
       

   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
   ACP_ADMIN_EMAIL=mr@admin.com: 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
   

   Note: The silent install is halted by the request to set the ENABLE_AUDITING variable to true or false, the default.