WANdisco Access Control Plus® User Guide

1. Introduction

Welcome to the User Guide for WANdisco’s Access Control Plus 1.9 - See version

Access Control Plus delivers a single, easy-to-use point-and-click solution that fully protects valuable source code across all of your Subversion and Git repositories. It is designed to work in conjunction with WANdisco’s SCM replication products or as a standalone solution. Integration with LDAP and Active Directory ensures that users are automatically assigned to the Subversion and/or Git teams that correspond to their authentication server groups. Security administrators can delegate authority to team leads to further reduce administrative overhead.

To view User Guides for previous versions of Access Control Plus visit the Archive

1.1. Get support

See our online Knowledgebase which contains updates and more information.

For more information about Subversion MultiSite Plus, Git MultiSite, and WANdisco’s replication technology see:

We define some industry terms, as well as WANdisco product terms in our Glossary.

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

If you find an error or if you think that some information needs improving, raise a case or email docs@wandisco.com.

1.2. Symbols in the documentation

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

Alert
The alert symbol highlights important information.
Tip
Tips are principles or practices that you’ll benefit from knowing or using.
Stop
The STOP symbol cautions you against doing something.
Knowledgebase
The i symbol shows where you can find more information in our online Knowledgebase.

1.3. Release Notes

View the Release Notes. These provide the latest information about the current release, including lists of new functionality, fixes, and known issues.

2. 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 team with any questions or concerns.

2.1. Deployment checklist

Important
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 take to check the list.

2.2. Hardware and Operating System

2.2.1. Operating systems

See the Release Notes for which operating systems are supported for your ACP version.

Tip
Runlevel differences between supported operating systems Read our Knowledge base article about How Linux Runlevels apply to our version control system products.

2.2.2. System memory

Memory recommendations
Hardware sizing characteristics Java Heap

<500 users

<10 repos

<100 teams

2GB

500 < users < 1500

10 < repos < 100

100 < teams < 200

3GB

1500 < users < 3000

100 < repos < 400

200 < teams < 400

4GB

3000 < users < 4000

400 < repos < 800

400 < teams < 800

6GB

Bigger

8GB+

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.

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.

GB or GiB
We should clarify how we refer to measures of memory and data. WANdisco ALM products (such as ACP) have adopted the binary prefixes as provided by the International Electrotechnical Commission. We therefore use Mebibyte (1,048,576 bytes) instead of Megabytes (1,000,000 bytes) within our products. However, we’ll still refer to Megabytes and Gigabytes where these are more commonly understood - such as in the above table. If you’re not familiar with the difference between binary prefixes and the SI prefixes then we recommend that you read this Wikipedia article.

2.2.3. 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: Link:https://support.wandisco.com/index.php?/Knowledgebase/Article/View/39/0/hardware-sizing-guide[Knowledgebase - Hardware Sizing Guide]

2.2.4. 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 ACP UI / 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.

2.2.5. 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. All ACP nodes must be able to talk to all other ACP nodes using all the Reserved ports, noted above.

2.2.6. Full connectivity

Access Control Plus requires full network connectivity between all nodes. The reserved port on each node must be accessible to all other nodes, so each application instance needs to communicate with every other application instance on each and every listed port above).

2.2.7. VPN

Set up IPsec tunnel, and ensure WAN connectivity.

2.2.8. VPN persistent connections

If working in MultiSite Plus, GitMS or combined mode, ACP requires connectivity. If it cannot detect connection loss, then this may cause loss of quorum. ACP uses the MSP/GitMS API to both poll in repos and to push out to the GFR script on each host (using the MSP/GitMS API). However, these are HTTP calls and, as such, are not overly sensitive to loss of a persistent connection.

2.2.9. 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.

2.2.10. DNS setup

Not using SSL: 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.

Using SSL You will need to use Fully Qualified Domain Names (FQNSs), since the server certificates are specified to domain names not IPs.

Changing a node’s IP address
If you need to change the IP address of an existing ACP Node, contact WANdisco support. The support team handles changes to node IPs because new software license files must be generated, also, incorrectly running the procedure could severely impact a deployment.

2.2.11. File descriptor limit

Ensure hard and soft limits are set to 64000 or higher. Check with the ulimit or limit command.

2.2.12. File systems

Supported file systems include:

  • ext4

  • VXFS from Veritas

  • XFS on RHEL/CentOS 7

    • XFS version 2.8.10 (or newer) combined with Kernel version 2.6.33 (or newer) - this requirement is met by RHEL7.2 and above

Write barriers should always be enabled.

2.2.13. Journaling file system

Replicator logs should be on a journaling file system, for example, ext4, or VXFS from Veritas.

Write barriers should be enabled.

2.2.14. Maximum user process limit

At least three times the number of Git or SVN users.

Systemd default limit of concurrent processes

Some distributions of Linux, including RHEL7, Ubuntu 16, etc, now install with tighter defaults concerning the maximum number of concurrent processes handled by systemd. For up to date information see the GitHub page for systemd news. In the context of Access Control Plus - which can need very high thread counts - the value should be the same as that assigned for the hard and soft limits above. For example the assignments:

  1. In system.conf, set TasksMax=64000

  2. In logind.conf, set UserTasksMax=64000

The above is necessary only if the "pids" cgroup controller is enabled in the kernel.

2.3. Applications/Tools

2.3.1. Component compatibility

When upgrading Access Control Plus, you must upgrade the Generic File Replication scripts to the version that matches the Access Control Plus version. Contact WANdisco Support for more information.

2.3.2. Java

Install the JRE / JDK version shown in the Release Notes for your ACP version.

Standalone mode is available for SVN only
Currently the Standalone mode is not able to support Git.
However, a form of "Git Standalone" is supported by using a single-system instance of GitMS (with a non-replicated Replication Group). Please contact WANdisco sales (or support).

2.3.3. Git or SVN clients

Any that are compatible with Git or SVN servers.

2.3.4. 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

2.3.5. SSH for Git or SVN

SSH authentication is supported by Git MultiSite and SVN MultiSite.

Access Control Plus accounts can support multiple multiple SSH keys, managed through the Account screen and or through LDAP.

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.

2.3.6. 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 other 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.

2.3.7. License model

2.3.8. Wildcard support

If you are installing ACP, either for the first time or as an upgrade, you can enable the use of wildcards. See Enable wildcard support.

2.4. Installation Procedure

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.

Release Notes

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

Help
If you have problems, see the information on our Knowledgebase before contacting Support.
  1. Download the Access Control Plus installation script scm-access-control-plus_XXX_installer.sh from the WANdisco File Distribution website, plus the necessary license key. The installer file’s name is now specific to the platform/package type.

  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 ACP-INSTALLER-FILE.EXTENSION
    Tip
    Your installer’s file name will vary by platform and package type,
    e.g. "ACP-1.7.4.1-0100-suse11-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.
    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.2.3-4567
    
    Do you want to continue with the installation? (Y/n) Y
Frequent changes are made to the installer
Please note that small changed in wording and flow may occur between product versions. These instructions provide an example flow that may vary slightly with your installation.
  1. Enter Y to continue. The installer checks for prerequisite applications.

  2. 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
    # DO NOT DELETE
    ACP_USER=wandisco
    ACP_GROUP=wandisco
    ACP_MEM_LOW=128
    ACP_MEM_HIGH=2048

    After making changes to the JAVA heap, you must restart the server for the changes to take effect.

    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.

  3. 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.

  4. 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
  5. 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
  6. 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:

  7. 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 node 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

    Remember, once you have assigned a single node, choosing "y", all other nodes must have "N" selected.

  8. 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:
  9. 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
  10. 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".

  11. You are presented with the Access Control Plus End-user Agreement. Read through the agreement, then click Accept to continue.

    acp install license2
    End user agreement
  12. Log in for the first time. Enter the username and password that you provided earlier. Then click Let’s do this

    acp login
    Login

    You see Access Control Plus’s Management Screen. This summarizes the accounts, teams and SCM repositories that Access Control Plus manages, and rules that dictate the SCM resources that account holders can access.

    acp login2
    Management screen

2.5. Install auditing function

2.5.1. At first ACP install

If you select to install Auditing you won’t see the login screen until you complete additional Auditing setup questions.

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: . Enter y.
  1. During the ACP installation you are asked:

    Do you wish to install auditing components for use with Access Control Plus? (Y/n)
  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 Access Control Plus "flume receiver" auditing component on one node.

    • A logger account is created during install. You need to provide a account name and password for this.

    • By default, the Flume process is run as the WANdisco account. 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!

    Workaround
    It’s actually true that the Apache access_log (or ssl_access_log) can be read by the MultiSite Plus account. The problem is that the normal permissions on the /var/log/httpd directory enable only root.
    Workaround: Change the group of the /var/log/httpd directory to be the same as the one that the MultiSite Plus account has as its primary group and then chmod 0750 /var/log/httpd .
    • 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 configure an "svnserve" log file for auditing, make sure that it exists (else the auditing daemon aborts).
          Make sure that, whichever account is running, the flume_sender can actually read the log file permissions (normally wandisco or apache account). You will need to set the following environment variables:

    • FLUME_INSTALL_DIR: Flume install location for acp-flume-receiver

      • ACP_USER_ID: Logger account ID to connect flume→acp

      • ACP_USER_PASSWORD: Logger account password to connect flume→acp

      • ACP_USER_EMAIL: Logger account 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_KEYSTORE_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

        Make sure that you are certain that you want to install these components.
        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:

  3. Change:

    acpSender.sources =  svnWebdavSource

    to:

    acpSender.sources =  svnWebdavSource svnServeSource
  4. 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
  5. Save the file.

  6. Restart the SVN Flume sender

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

    acpSender.sources =  svnWebdavSource svnServeSource

2.5.2. 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.

2.5.3. With ACP Upgrade to 1.5

During the 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 Install Auditing Function.

2.5.4. Flume sender

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

2.5.5. Flume receiver

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-git-multisite 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.

2.5.6. 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

Note
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 a value that is higher than the default if you find that Apache, svnserve, etc. logfile entry rate is high. We recommend that you find what value works for your deployment; If set too low the Flume log file will show an error and the Flume agent will have exited.

2.6. 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. The GFR installer follows the same naming convention as your main installer file, except that it will include "GFR" in its name, e.g. ACP-GFR-git-1.7.4.1-0100-installer-rpm. If you do not install the RPMs you will need to review your MultiSite log files for indications what what’s missing.

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

2.6.1. SVN MultiSite Plus

On all nodes:

  1. Make the RPM executable

    chmod 777 <GFR-INSTALLTER-FILE>
  2. Install the RPM:

    rpm -ivh <GFR-INSTALLER-FILE>

    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
    Note
    The postDeliveryAZPW file listed above is not part of the GFR scripts.
  4. Login to ACP and generate a set of authZ and password files.

  5. Check that the ACP authZ and password files are replicated across all Git nodes correctly.

2.6.2. Git MultiSite

On all nodes:

  1. Make the RPM executable:

    chmod 777 <GFR-INSTALLER-FILE>
  2. Install the RPM:

    rpm -ivh <GFR-INSTALLER-FILE>

    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
  4. Check that the ACP authZ and password files are replicated across all Git nodes correctly.

3. 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.

3.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: admin: 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.

3.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: admin: Enable LDAP Auth

  4. SSL: Enable SSL encryption

  5. Email notifications: Set up 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.

3.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 account which 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 account has been skipped. The sys admin must then ensure that the local account is removed.

3.3.1. Managing Permissions with LDAP/AD

The following diagrams show the flow used in the two phases of authentication when using ACP with SVN MultiSite Plus:

acp ldap phase01
acp ldap phase02
Authentication

3.4. Access Control Settings

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

    acp settings01
    Settings
  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.

    acp settings02
    Setting Menu

    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 MultiSite or SVN MultiSite Plus products.

3.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 an authentication or authorization files. See Adding repository templates, Managing Repository Templates.

Global Downcasing

If the LDAP Authority that ACP will be talking to is Active Directory then the Global Downcasing setting should be turned on. Otherwise you should leave it off. Once turned on it should not be turned off without consulting WANdisco support.

3.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 redundancy. This is also used to remove ACP nodes that have experienced an unrecoverable failure. See Inducting a node.

Node Repairs

Node Repairs enables the correction of ACP nodes in the rare case where some divergence in the account or auditing information has occurred. The "repair" operation essentially copies the most up-to-date ACP account, team, rules, etc. data from a "known good node" to a "known bad node". WANdisco Support should be contacted before running a repair. See Running a node repair.

3.7. External Applications

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

Connect to MultiSite

If you are running Access Control Plus with WANdisco’s Git MultiSite or SVN MultiSite Plus 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 Notifications to connect to an available relay server so that Access Control Plus can send notification emails to administration staff. See Enable email notifications.

Don’t ignore email notification
Important product alerts and logging depend on the email notification system. Please make sure that you complete its configuration.

4. Non-interactive Installation

You can start installing a node without terminal access to the server, known as a silent or scripted 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 scripted installation the following script must be run with the environmental variables set:

export ACP_USER=(user_to_Run_ACP)
export ACP_GROUP=(Group_to_Run_ACP)
export ACP_PORT=(Port to host UI/API): default is 8082
export ACP_DCONE_PORT=(DCone Port): default is 6445
export ACP_CONTENT_PORT=(Content delivery port): default is 6444
export ACP_NODE_NAME=(Name for current ACP node): Each install needs to be unique

If creating the initial Admin account (user) you also need to set:

export ACP_ADMIN_USER=(Username for new admin user)
export ACP_ADMIN_FIRST_NAME=(Real name for new admin user)
export ACP_ADMIN_LAST_NAME=(Real name for new admin user)
export ACP_ADMIN_EMAIL=(Email for new Admin user)
export ACP_ADMIN_PASSWORD=(Password for new Admin user)
export ACP_MEM_LOW=(Min Memory for ACP Process): default is 128
export ACP_MEM_HIGH=(Max Memory for ACP Process): default is 2048
export ACP_LICENSE_FILE=(Full path to ACP License file)
export ACP_HOSTNAME=(Address to host ACP on)
export GITMS_UMASK=(Umask to apply): default is 022
export ACP_STATEMACHINE_CREATOR=(true/false): If this machine is the state machine creator, should only be true on first node.
export ENABLE_AUDITING=(true/false): true if Flume auditing should be installed

If ENABLE_AUDITING=true you also need to set:

export FLUME_INSTALL_DIR=/opt/wandisco/flume-scm-access-control-plus :Full Path to where Flume should be installed, default is shown
export FLUME_MAX_MEMORY=(Max memory for flume process): Default is 256

To create a new Logger user in ACP you also need to set: export ACP_USER_ID=(username for the new logger user) export ACP_USER_PASSWORD=(password for new logger user) export ACP_USER_EMAIL=(Email for new Logger User)

export ACP_AVRO_HOST=(Address to host Flume on should match ACP Host) export ACP_AVRO_PORT=(Port to host Flume on default is 8441, this is port provided to GITMS and ACP) export FLUME_ACP_HOST=(address for flume to connect to acp, default is the same as ACP host) export FLUME_ACP_PORT=(port for flume to connect to ACP should match ACP Port) export FLUME_AVRO_SSL=(true/false if flume is to have ssl enabled)

export FLUME_AVRO_KEYSTORE_LOC=(Full Path to Flume Keystore) export FLUME_AVRO_KEYSTORE_PASS=(FlumeKeyStorePass) export FLUME_AVRO_TRUSTSTORE_LOC=(Full Path to TrustStoreFile) export FLUME_AVRO_TRUSTSTORE_PASS=(FlumeTrustStorePass)

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.

4.1. Environmental variables

Basic Install:
*export ACP_USER*= _user running install_ +
*export ACP_GROUP*= _group running install_ +
*export ACP_LICENSE_FILE*= _path to ACP license_ +
*export ACP_NODE_NAME*= _name of this node_ +
*export ACP_STATEMACHINE_CREATOR*= _set false if this node is to be a non state machine creator_ +
Basic StateMachine Creator Install:
export ACP_USER= user running install
export ACP_GROUP= group running install
export ACP_LICENSE_FILE= path to ACP license
export ACP_NODE_NAME= name of this node
export ACP_STATEMACHINE_CREATOR= set true if this node is to be a state machine creator
export ACP_ADMIN_USER= admin
export ACP_ADMIN_PASSWORD= password
export ACP_ADMIN_FIRST_NAME= mr export ACP_ADMIN_LAST_NAME= admin export ACP_ADMIN_EMAIL=admin@youremailaddress.com
With Flume Added To the Install:
export ENABLE_AUDITING=true
export FLUME_MAX_MEMORY=Maximum memory size default is 256
export FLUME_INSTALL_DIR=Flume install location for acp-flume-receiver
export ACP_USER_ID=Logger user ID to connect flume→acp
export ACP_USER_PASSWORD=Logger user password to connect flume→acp
export ACP_USER_EMAIL=Logger user email
export ACP_AVRO_HOST=Flume receiver IP
export ACP_AVRO_PORT=Flume receiver port
export FLUME_ACP_HOST=ACP IP for Flume to connect to
export FLUME_ACP_PORT=ACP rest port for Flume to connect to
export FLUME_AVRO_SSL=true/false to enable/disable SSL
export FLUME_AVRO_KEYSTOE_LOC=Only required if FLUME_AVRO_SSL=true, keystore location
export FLUME_AVRO_KEYSTORE_PASS=Only required if FLUME_AVRO_SSL=true, keystore password
export FLUME_AVRO_TRUSTSTORE_LOC=Only required if FLUME_AVRO_SSL=true, truststore location
export FLUME_AVRO_TRUSTSTORE_PASS=Only required if FLUME_AVRO_SSL=true, truststore password
Note
The silent install is halted by the request to set the ENABLE_AUDITING variable to true or false.

5. Upgrades

This section describes what you need to consider to upgrade an existing copy of WANdisco’s Access Control / Access Control Plus. We cannot address every set of conditions so take care to consider all possible problems. If you have any questions or concerns, contact WANdisco support team.

Check component compatibility

You should check that the different application components are compatible with each other.

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 recommend that you contact WANdisco to discuss supported configurations.

5.1. Upgrade paths

Upgrading to Access Control Plus 1.5 or higher with auditing

You will need to set several environment variables when you upgrade to ACP 1.5 and enable the auditing functions. See Install auditing function.

Upgrading from Access Control Plus 1.0 to 1.5 requires upgrade to 1.1 first

To upgrade from Access Control Plus 1.0 to 1.5, you must first upgrade to 1.1. Then, from 1.1, upgrade to 1.5 by repeating the steps described in this section. If you have problems, follow the Rollback Procedure and contact WANdisco support team.

Upgrading from Access Control 4.2

To upgrade from Access Control 4.2 to Access Control Plus you must contact WANdisco support team. This is necessary to complete the validation using new scripts.

5.2. Upgrade Overview

This section gives an overview of the upgrade procedure. The procedure starts with creating a import file by invoking the export script in the current installation. This stores system and user settings in an external XML file for later re-importation. Next, the upgrade script is run. This takes the latest JAR files and places them into the current install. The final post-install portion performs any necessary changes to database structure and restores the previous installation’s settings.

The Pre-installation step invokes the backup script which stores the system and user settings that are imported into the latest version.

5.2.1. Installing Flume while upgrading

If you are running a version of Access Control Plus that didn’t include Flume, it’s possible to install Flume during an upgrade of Access Control Plus. The procedure differs a little from that used when installing both ACP and Flume from scratch. For that, see Install Auditing Function.

5.3. Pre-upgrade: turn off batch updates

Perform the upgrade during a time when you can halt changes to ACP configurations (e.g. stop changing teams, rules, accounts, etc.). If you are running with Batch Mode on, this needs to be disabled and Access Control Plus will need enough time to catch up with all batched operations. Because Batch Mode is being turned off, all automation scripting should be turned off as well (halt any scripting that talks to ACP via the REST API) prior to turning off Batch Mode.

Disable batch updates before shutting down for upgrade
You must complete these steps before shutting down. We recommend that you disable batch updates at least 1 hour before you shut down the application.
  1. Login to Access Control Plus.

  2. Click Settings.

  3. Click Access Control Updates.

  4. Click the Disable Batch Updates button.

After an upgrade you must re-enable batch mode (an upgrade installation disables batch mode so that the upgrade progresses).
If you perform an import from an earlier version of Access Control you must ensure that Access Control Plus does not poll the LDAP authorities during the process. You can do this by setting the Synchronization Period to 999 (minutes) Just for the duration of the import.
Changing a node’s IP address
If you need to change the IP address of an existing ACP Node, contact WANdisco support. The support team handles changes to node IPs because new software license files must be generated, also, incorrectly running the procedure could severely impact a deployment.

5.4. Upgrade procedure

Having completed the necessary pre-upgrade steps, it’s now time to complete the upgrade. You’ll need to have downloaded the installer for the latest version of Access Control Plus. Place the script on your server and run through the following steps:

  1. Open a terminal window and log in to the server.

  2. Get the latest installer file and make sure it is executable:

    chmod a+x ACP-INSTALLER-FILE.EXTENSION
  3. Run the installer: After providing Access Control Plus admin credentials, the installer script verifies that there’s an existing installation and completes the necessary back up of settings:

    [root@redhat6 wandisco]# ./ACP-INSTALLER-FILE.EXTENSION
    Verifying archive integrity... All good.
    Uncompressing WANdisco Access Control Plus..........
    Running in non-interactive mode, installing with user 'wandisco' and group 'wandisco'. Output will be logged to the daemon.info syslog facility
    Please enter the username of an administrative user: admin
    Please enter the password for 'admin':
    Checking credentials: OK
    State machines are stopped
    Backing up platform: OK
    Backing up ACP: OK
    Backup complete
  4. The installer performs the upgrade. In most cases the installer handles everything:

    Stopping scm-access-control-plus:.[  OK  ]
    Upgrading from version 1.0.1
    Starting upgrade of backup found in /opt/wandisco/scm-access-control-plus/database/backup/2014-07-28T13:30:19Z_DConE_Backup
    
    Transformation complete
    Jun 27, 2014 4:26:43 PM com.wandisco.acp.backup.Restore main
    . . . . . . . .
    Please run '/opt/wandisco/scm-access-control-plus/bin/replace-link' once all nodes have been upgraded. This will automatically start the replicator.
    Stopping scm-access-control-plus services...
    Stopping scm-access-control-plus:[  OK  ]
Do not run replace-link yet - repeat the upgrade on all nodes
At the end of the upgrade you see a message about running replace-link. Do not run this yet. First you need to repeat the upgrade on all your nodes.

5.5. Post upgrade: bring nodes back up

When all nodes have been upgraded, bringing them back up by running:

service scm-access-control-plus start

5.6. Enable Wildcard support

With Subversion, MultiSite Plus and Access Control Plus installed:

  1. Click Settings then Connect to MultiSite.

  2. Click the check box Enable Wildcards. Note:

    This cannot be undone without reinstalling
  3. Select either:

    1. Low Priority

    2. High Priority
      Default is High Priority. See Setting priorities

  4. Click Save.

The wildcards option is now enabled for rules applying to MultiSite Plus repositories. Note that you can change the priority setting at any time.

Remember: You cannot disable wildcard support when wildcard rules have been set.

5.7. Rollback Procedure

If you need to roll back from an attempted upgrade and return to your current installation, for example going back from 1.5 to 1.1.1:

  1. From the /opt/wandisco/scm-access-control-plus/backups directory, copy the file similar to scm-access-control-plus-backup_20141217154840.tar.gz to somewhere safe.

  2. Uninstall the current version of ACP.

    [root@redhat6 init.d]# yum remove scm-access-control-plus
    Loaded plugins: product-id, rhnplugin, security, subscription-manager
    Updating certificate-based repositories.
    Setting up Remove Process
    Resolving Dependencies
    --> Running transaction check
    ---> Package scm-access-control-plus.noarch 0:1.0.1-1711 will be erased
    --> Finished Dependency Resolution
    epel/metalink                                            |  27 kB     00:00
    epel                                                     | 4.4 kB     00:00
    epel/primary_db                                          | 6.3 MB     00:00
    
    Dependencies Resolved
    
    =============================================================================
    Package    Arch   Version    Repository                                  Size
    =============================================================================
    Removing:
    scm-access-control-plus
    noarch 1.0.1-1711 @/scm-access-control-plus-1.0.1-1711.noarch  55 M
    =============================================================================
    Transaction Summary
    =============================================================================
    Remove        1 Package(s)
    
    Installed size: 55 M
    Is this ok [y/N]: y
    Downloading Packages:
    Running rpm_check_debug
    Running Transaction Test
    Transaction Test Succeeded
    Running Transaction
    Erasing    : scm-access-control-plus-1.0.1-1711.noarch                    1/1
    Stopping scm-access-control-plus services...
    Stopping scm-access-control-plus:[  OK  ]
    Installed products updated.
    Verifying  : scm-access-control-plus-1.0.1-1711.noarch                    1/1
    
    Removed: scm-access-control-plus.noarch 0:1.0.1-1711
    
    Complete!
  3. Re-install the previous version of Access Control Plus.

  4. Stop the replicator.

  5. Ensure that the permissions are correct.

  6. Run the rollback script.

    cd /opt/wandisco/scm-access-control-plus/bin
    ./rollback
  7. Repeat the rollback procedure on each node.

  8. When all nodes have been rolled back, start ACP via the scm-access-control-plus service start as usual.

Your nodes will start up, returning production to the earlier version of Access Control Plus.

5.8. Import Access Control 4.2 backup data

A deployment from Access Control/Subversion MultiSite 4.2 assumes that you are running with the latest 4.2 versions.

IMPORTANT
This section provides an overview of the procedure. However, you should contact WANdisco Support before attempting to follow it.

5.8.1. Pre-install

  1. On your Access Control/SVN MultiSite 4.2 deployment, perform a sync stop.

  2. Run the Export tool, creating a backup directory.

    WARNING
    When you import this exported 4.2 data, the existing Access Control Plus data will be removed, including the local admin account. You should ensure that there is a local admin account present on your 4.2 deployment prior to completing this export. Furthermore, ensure that you don’t disable local accounts on Access Control Plus prior to re-importing the data.

Should you get locked out of Access Control Plus you can run the Password change/recovery utility which will enable local account access and prompt you to create a new admin account. See Password change/recovery.

  1. You may need to perform a cleanup of the export. Contact WANdisco’s support team about whether this will be necessary.

  2. Shutdown Access Control/SVN MultiSite 4.2. You may wish to save the installation to an archive so that it’s no longer present on the server.

  3. If you’re installing SVN MultiSite Plus then delete your current installation of Subversion. The latest version of MultiSite requires that you install a modified version of SVN.

5.8.2. Install Access Control Plus

  1. Run through the instructions provided in the Deployment Guide.

  2. When the installation and node induction is complete you can run the special import script that is available in the Access Control Plus installation which handles 4.2 backup files. Login to the server via a terminal and navigate to the bin directory, by default this is /opt/wandisco/scm-access-control-plus/bin/.

  3. Providing that you have logged on with appropriate permissions, you can run the script as follows:

  4. You will need to provide Access Control Plus admin login credentials. You’ll then be asked for a the absolute path to the 4.2 backup. e.g.:

  5. You can confirm the import was successful by viewing the available accounts in Access Control Plus.

5.9. Install Auditing (through Apache Flume)

These steps are only for a first-time installation of Flume or during an upgrade of Access Control Plus.

5.9.1. Installation overview

There are two ways to install flume:

  • Interactive (manual)

  • Non-interactive (silent)

5.9.2. Interactive

Use ACP’s installer to handle the upgrade, the installer will detect that you are performing an upgrade and that Flume is not yet installed. The installer will ask:

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

Just answer the brief series of question to install Flume.

5.9.3. Non-interactive

For the non-interactive upgrade, to install Flume for a first time for ACP you will need to set the following variables:

variables
ENABLE_AUDITING=true
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_KEYSTORE_LOC # Only required if FLUME_AVRO_SSL=true, keystone location
FLUME_AVRO_KEYSTORE_PASS # Only required if FLUME_AVRO_SSL=true, keystone 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
INSTALL_FLUME_ON_UPGRADE=set # to true if first install of flume on an upgrade
Example

An example of these exports would be like the following (excluding the use of SSL)

export ENABLE_AUDITING=true
export FLUME_INSTALL_DIR=/opt/wandisco/flume-scm-access-control-plus
export ACP_USER_ID=logger
export ACP_USER_PASSWORD=logger
export ACP_USER_EMAIL=logger@logger.com
export ACP_AVRO_HOST=localhost
export ACP_AVRO_PORT=8441
export FLUME_ACP_HOST=localhost
export FLUME_ACP_PORT=8441
export FLUME_AVRO_SSL=false
export INSTALL_FLUME_ON_UPGRADE=true

Once you have exported these variables, run the upgrade.

6. Administration

6.1. Housekeeping

The following section details basic day-to-day tasks that may be required when running Access Control Plus.

6.1.1. Starting up

To start Access Control Plus:

  1. Open a terminal window on the server and log in with suitable file permissions.

  2. Run the scm-access-control-plus service from the /opt/wandisco:

    lrwxrwxrwx  1 root root        65 Apr 24 11:43 scm-access-control-plus -> /opt/wandisco/scm-access-control-plus/bin/scm-access-control-plus
  3. Run the service using the following command

    [root@localhost /opt/wandisco]#  service scm-access-control-plus start
    
    
    Starting scm-access-control-plus:.                         [  OK  ]

Access Control Plus starts. Read more about the svn-multisite init.d script.

6.1.2. Shutting down

To shut down:

  1. Open a terminal window on the server and log in with suitable file permissions.

  2. Run the svn-multisite service:

    lrwxrwxrwx  1 root root        65 Apr 24 11:43 scm-access-control-plus -> /opt/wandisco/scm-access-control-plus/bin/scm-access-control-plus
  3. Run the stop script:

    [root@redhat6 /opt/wandisco]#   service scm-access-control-plus stop
    
    Stopping scm-access-control-plus:.                         [  OK  ]

    The process shuts down.

6.1.3. Reporting problems: talkback

WANdisco uses a talkback agent to capture log information to help investigate problems. When you report a problem to WANdisco support, you should run talkback and attach the output file.

  1. Run talkback from /opt/wandisco/scm-access-control-plus/bin. Talkback retrieves node details and gathers information. You see a message like:

    THE FILE sysInfo/sysInfo_10.2.5.52-20150122-173254.tar.gz HAS BEEN CREATED BY sysInfo
    Please enter your WANdisco support FTP username (leave empty to skip auto-upload process):
  2. Enter your WANdisco support FTP username to upload the file directly to our support team
    or
    Click Enter to skip auto-FTP upload. You must then manually upload the file, e.g. /opt/wandisco/scm-access-control-plus/talkback-201501221732-10.2.5.55.dhcp.shef.wandisco.com.tar.gz, to WANdisco support with a description of the issue.

Do not email the talkback files
Upload the files fia FTP or attach them via the web ticket user interface.

6.1.4. init.d management script

The start-up script for persistent running of Access Control Plus is in the /etc/init.d folder. Run the script with the help command to list the available commands:

[root@redhat6 /opt/wandisco/]#  service scm-access-control-plus help
help command
usage: /etc/init.d/scm-access-control-plus (start|stop|restart|force-reload|status|version)

start         Start Access Control Plus services
stop          Stop Access Control Plus services
restart       Restart Access Control Plus services
force-reload  Restart Access Control Plus services
status        Show the status of Access Control Plus services
version       Show the version of Access Control Plus

Check the running status (with current process ID):

[root@redhat6 /opt/wandisco/]# service scm-access-control-plus status
Checking scm-access-control-plus:running with PID 29516    [  OK  ]

Check the version

[root@redhat6 /opt/wandisco/]# service scm-access-control-plus version

6.1.5. Password change/recovery

This section describes what to do if an administrator loses their password and needs to regain entry to Access Control Plus. Currently the method uses a script that resets Access Control Plus’s authentication. If you have set up to use LDAP, this will be disabled, returning access to local users. A new administrator-level local user is created with credentials that you supply when you run the script.

Disable LDAP/external authentication
If you need to disable LDAP authentication and return your deployment to the default internally managed users, use the following procedure. Your LDAP authorities will not be deleted, only disabled. They can be re-enabled from the Settings screen.
  1. Open a terminal on your node and navigate to the replicator directory:

    $  cd /opt/wandisco/scm-access-control-plus
  2. Run the following command-line utility:

    [root@redhat6 scm-access-control-plus]# java -jar scm-access-control-plus-resetSecurity.jar
    Enter full path to the replicator properties folder: /opt/wandisco/scm-access-control-plus/properties
    Enter your username: temporary
    Enter your new password:************
    Confirm your new password:************
    Enter your first name: Temporary
    Enter your last name: Account
    Enter your email address: admin@theadmin.com
    A new user has been created, in order for this to take effect you will need to restart this node.
    [root@redhat6 scm-access-control-plus]#
  3. Respond to each prompt. It is important to note that the account name specified to the "username:" prompt should not exist. Make it as obscure as necessary so that it represents an account name that does not exist.

  4. When you’ve entered everything, restart Access Control Plus to add the new accounts.

  5. Log in using the original authentication form:

    acp recovery01
    Log in

6.1.6. Searching Access Control Plus

Use the ACP Search tool to find Accounts, Teams, Rules and Resource permissions.

  1. Enter a search term into the entry field and select from the available categories.

    acp filter00
    Search

    Search by:

    • Accounts

    • Teams

    • Rules

    • Resources (Repository files and folders)

  2. A filter panel will open with the results of your search. Results will appear for all available search criteria. On the side panel you can deselect unwanted criteria by unticking each corresponding checkbox.

    acp filter01
    Search results
  3. Drill down into search results by clicking on the arrow at the end of the search result bar.

6.1.7. Searching tips

  • Currently search results will only display the first 10 of however many "Accounts", "Teams", "Rules" or "Resource Permissions" are returned (for each category).

  • Search by repository name, without using refinements for high-level searches that don’t require sub-repository paths. e.g., Search svn-repo1 for everything

Resources: svn-repo1
  • Search by folder name. e.g,

    Search svn-repo1 for all folders called "source"

Resources: svn-repo1:%/source
  • Use wildcards to created advanced filters when searching.

Asterix is not a search wildcard
Take note that the asterisk ('*') used in wildcard rules are not used as wildcards in the search (when input into the "Resources" field) - they are treated as literal characters and will match rules that have an asterisk in that position. So there is a rule that has a wildcard refinement or a rule where the asterisk character is explicitly marked as not a wildcard, then you might search for such a rule by putting '%:/branches/*' into the Resources field. In this case the percent sign ('%') is a wildcard in the search (matching everything) and the asterisk is a literal (only matching an asterisk).

Search git-repo1 for all TAGS:

Resources: git-repo1:/TAG/
Searching on Git deployments

When performing searches on Git deployments, if you need to search for references to Branches or Tags, you must add the following to your search patterns:

Branch

Searching for a branch, add the prefix /BRANCH/, e.g.

/BRANCH/mybranch

TAG

Searching for a Tag, add the prefix /TAG/, e.g.

/TAG/mytag

6.2. Accounts

The Accounts panel lists all connected accounts.

ref accounts
Connected accounts
Type

Type of account. Local accounts are imported from a file or entered into the ACP admin screen. LDAP-based. accounts are added using LDAP queries. Accounts that are LDAP-based.

Rules

Number of rules that apply to the account.

An account is a collection of information that tells Access Control Plus which resources the account holder can access and what level of access they should have. Accounts are the fundamental building blocks for Access Control, although the Access Control model actually handles permissions only on a per-team basis, not directly on individual accounts.

Your license allows a maximum number of accounts
A user license is consumed for each account that is in a least 1 team and is not disabled. If the number of accounts that meet these two conditions ever exceeds your license limit, you will receive warnings to remove or disable accounts. If you ignore the warnings for 10 days then ACP will go into read-only mode. Then only administrators, or team leads with appropriate privileges, can remove or disable accounts. See Remove Account.

6.2.1. Create an account

There are three methods for four routes to create an account. This procedure describes steps to follow after clicking Create User on the Accounts pane that appears on the master screen. You can also create an account from within the Create Team procedure. Usually you will add accounts by setting up a query to an available LDAP authority. To add accounts using LDAP, see Connect to LDAP.

  1. Log in to Access Control Plus. Click the + Create button on the Accounts panel.

    acp admin account01
    Create an account
  2. An entry table opens. Enter the account holder’s details, as described below.

    acp admin account03
    Enter account details
    First Name

    The account holder’s first name.

    Last Name

    The account holder’s last name.

    Account Name

    The account name that Access Control Plus will use internally to refer to the account holder.

    Password

    The password for the account (obfuscated entry).

    Caution: passwords cannot contain only numbers
    Passwords can be alphanumeric, containing a mix of letters and numbers, or only letters.
    Confirm Password

    A repeat entry of the password to confirm it was correctly entered.

    Email Address

    The email address associated with the account holder.

    Public Keys (for Git or SVN access)

    The account holder’s public key when running with Git or SVN that is using SSH authentication. When you copy this into the form ensure that you add no breaks. A key is one unbroken line of characters.
    It’s now possible to have zero or more public keys from LDAP and zero or more locally defined public keys. Public keys loaded directly from the LDAP Authority for the account are not editable by the user (they will need to get their LDAP authorities to update those keys and then ACP will get those updates).

    SSH Keys
    To enter or change SSH keys, all users need to use their self-service page.
    Disabled (Checkbox)

    Use this checkbox to disable the account. When ticked the account holder is completely locked out. All authorization is disabled. This feature offers administrators a means of removing access without completely removing an account or messing with rules. The account is effectively disabled from the moment the screen is updated, unless you have batched updates.

    User types

    User type dropdown:

    acp admin account04
    User types

    The User type drop-down menu sets one of the following account types:

    Standard

    A standard account holder supports all levels of access on all available resources, subject to the rules that apply to the teams for which the account is a member.

    Audit User
    Error message:
    Currently you cannot select this user type. If you do, you receive an error message. This is a known error that we will fix in future.

    An Auditor account can never be granted write permissions. This provides administrators with complete confidence when adding accounts for employees who need access to repository data but who are not qualified to make changes.

    Application Administrator

    This account type is specifically for SCM administrators who will themselves manage Access Control Plus. Administrators can access the admin console and have permissions to change all Access Control Plus settings.

    Create/Update (button)

    During account creation this button is labelled "Create". Use this button to submit the account details (newly entered or updated) into the form, or for that matter any changes that are made during the edit of an existing account.

  3. After entering the account holder’s details, click Update to save the changes to Access Control Plus’s internal database. The account is ready to add to teams, which will then enable you to apply rules to it, which ultimately provide access control for available SCM resources.

    Access to nothing by default
    All accounts are created with no access to any resources. For an account to gain access to a repository it must first become a member of a team, then that team must have a rule set up that associates repository resources along with permission levels. For more details see the section about Rules.

6.2.2. Edit an account

To edit an existing account:

  1. Log in to Access Control Plus and find the account that you want to change:

    acp admin account05
    Edit Account

    Search by filter: Click Filter to show a search entry box. You can select from Name, Username, Email) for the search.

    Selecting an account: Click on the Account holder’s name to bring up the account screen.

    An account screen shows the account’s team memberships and access privileges:

    acp admin account07
    Teams and access privileges
  2. To return to the account’s entry form and make edits click Details. The main panel lists teams of which the account is a member and lists all rules that currently apply to the account.

    Change teams membership: From the teams table click a Team name to remove the account from that team or subteam. Change a rule: Click any rule in the Rules table to remove the account from the rule.

    Change a rule: Click any rule in the Rules table to remove the account from the rule.

  3. When you wave finished working with the account screen, click the tab on the left of the panel to close the screen.

    acp admin account08
    Close Account screen
LDAP-based users
The Edit screen is renamed Details for LDAP users because you cannot edit an LDAP-based user through Access Control Plus. If you need to modify an LDAP user you need to go through your LDAP service. The sole exception to this are any "local" SSH public keys. They can be added, modified and/or removed.
acp ldapteam08
Details screen for LDAP users
Important: When LDAP authority tries to enter in an account that has a username that already exists on the system
When LDAP sync discovers there is already existing account with the same username it will log a warning and not will synchronize this account. The existing account name can be local (entered into Access Control Plus directly) or from different LDAP authority. However, if the user exists in LDAP and can authorize against SVN, then it will get in and AuthZ will apply any rules.
In version 4.2:
As only usernames were used to match users a conflict would not be detected. In this situation users with duplicate usernames would be synchronized.
Solution: If Apache is suitably configured, the local accounts, via the passwd file would get precedence, so it should work OK for local users. However, if the username conflict is between two LDAP authorities then you currently still can get the clash. It is therefore best to only have 1 LDAP authority.
Do not create multiple LDAP authorities to access multiple replicas of the same LDAP service like you might have done in 4.2. This is both unnecessary by the architecture of ACP+MSP but is also known to cause severe difficulties.

6.2.3. Adding public SSH keys

Public SSH keys can be managed from:

  • ACP admin console (by admin or account holder)

  • LDAP authorities

  • Combination of local and LDAP

Keys coming from LDAP are not modifiable through the ACP admin console, you will need to make changed through the LDAP authority.

An administrator can add/change/remove any SSH keys associated with an account except those coming from LDAP. An account owner (user) can add/change/remove any of their own account’s SSH keys except those coming from LDAP.

IMPORTANT
Accounts that are LDAP_based can have SSH keys added locally (via the ACP admin console), but only if SSH keys have not been set through LDAP. LDAP keys that are added locally will always be editable.

Following the above stated rules, use this procedure to add any number of public SSH keys to an ACP account.

  1. Click on the account (local or LDAP) onto which you wish to add a public SSH key.

    acp multiple ssh01
    Select Account
  2. Click on View/Edit link.

    acp multiple ssh02
    Edit Account
  3. The Account form includes a Public Key(s) (For SSH access paths) table. The table supports any number of separate SSH keys for accessing whatever resources.

    acp multiple ssh03
    Add Public Key
    Add New Public Key

    Enter a public key into the field. Remember, no spaces!

    Add An Alias For New Public Key (optional)

    Enter an Alias to give your key a meaningful reference name, e.g. "LDAP" for a key used for accessing an LDAP resource.

    Click Add Key to save the new key to the account.

  4. The public key will now show up in the Public Key(s) table.

    acp multiple ssh04
    View Public Key
    Key Alias

    Reference name given to a locally added key to help you remember what it is for. This is especially useful if the account is to support multiple SSH keys.

    SshKey(s)

    The public SSH Key.

    Local

    Identifies if the key is controlled locally (true) or managed by LDAP (false).

    Select to Delete

    Checkbox for selecting a key for deletion. See the next section for more information.

6.2.4. Removing public SSH keys

Follow this procedure for removing public SSH keys from an account.

  1. Navigate to an existing public key that you wish to delete. Click on the corresponding Select to Delete checkbox and click the Delete SSH Key(s)

    acp multiple ssh del01
    Delete SSH Key

    You can delete multiple SSH keys at once by selecting multiple keys to delete.

  2. A message Account successfully updated will appear. Click Close.

    acp multiple ssh del02
    Close
  3. The SSH key(s) that you have deleted will no longer appear on the Public key(s) table.

    acp multiple ssh del03
    SSH key has been deleted
Self Service page

There is a separate page for modifying an "admin" account’s credentials. It can be found on the account edit screen:

acp selfservice
Self Service

6.2.5. Audit accounts

Audit accounts are accounts that can see everything but do nothing. They are used by auditors to validate ACP configuration, etc. They can also be used by scripts that ONLY read ACP data.

6.2.6. Audit Logging accounts

When you install the auditing function, you are asked for the name of the Account Access Logging service account. The logging service account is created during installation. We refer to this as "logger" here but you can call it what you want. The logger account is used to log account access information from monitors on log files where information about accounts accessing the SCM systems is. Logging this information is the only thing that the logger account can do. Even administrative accounts cannot use the logging REST API: only logging service accounts can do so. It is not possible to log in to the UI using the logger account. You will see the message:

For security reasons, the logger user cannot log into the UI, please log in again as a more privileged user.

Best practice is to:

  1. Create a new logging service account.

  2. Update all of the ACP Flume receivers to use the new credentials.

  3. Remove the original logging service account.

Two jar files are delivered with ACP 1.5 that enable the maintenance of the logging service account:

scm-access-control-plus-flumeReceiverConfig.jar

Lets you update the username and password in the Flume configs.

scm-access-control-plus-manageLoggerUser.jar

Lets you create/update/delete logger users. You cannot do this through the UI.

6.2.7. Query audit database

Using command line

Use curl commands to query the database accounts. For example, to query the last access by a particular user, you need to look up the account’s ID via an API query then use the ID:

curl --user admin:pass http://192.168.58.190:8082/api/audit/<account_id>

You see a report similar to:

<auditrecord>
  <dateCreated>1455132322046</dateCreated>
  <dateLastModified>1455132322046</dateLastModified>
  <id>041e7448-f2dc-42b6-8994-1fd786bda0f5</id>
  <accessTime>2016-07-11T17:09:37+02:00</accessTime>
  <accessType>READ</accessType>
  <accountName>acct10001</accountName>
  <historicRepositoryLocation>/opt/repo/first</historicRepositoryLocation>
  <historicRepositoryName>first</historicRepositoryName>
  <historicRepositoryType>SVN</historicRepositoryType>
  <repositoryLocation>/opt/repo/first</repositoryLocation>
  <repositoryName>first</repositoryName>
  <repositoryType>SVN</repositoryType>
</auditrecord>

Note the reference to accountName, rather than accountID. Also the "historic" entries, which are indicated in cases where the repository moves over the course of its lifetime.

To query when a user accessed a particular repository:

curl --user admin:pass http://192.168.58.190:8082//api/audit/<user_account_id>/repo/<repo_name>

To query the last access by all users:

curl --user admin:pass http://192.168.58.190:8082/api/audit/all

Accounts which have not accessed the repositories are reported with a timestamp of 0 (with the year 1969 or 1970).

Audit does not monitor SVN commits using file://
Commits over file:// do not generate anything in the logs that auditing monitors. This means that nothing is sent to the auditing mechanism to report to the user.
More information about the REST API
Read the RESTful API Guide.

6.2.8. Using UI

Use the dashboard Reports tab to query the audit database from the UI:

dash audit
Reports tab

You can choose from the following types of report:

audit reports 2
Report types
  • Select Accounts Audit Report to list the last access time for all accounts:

    last access time all acs
    Accounts Audit Report
  • Select Repository Audit Report to list the last access time for all the repositories:

last access time all repos
Repository Audit Report

Note: You may see a message warning that the report could take a long time, i.e. a few seconds:

long time message

Confirm that you want to continue.

dash audit conflicts
Conflicts

For example, there may be a Priority Conflicts report:

priority conflicts 2
Conflicts Report

To report on the last access time by an account, as an administrator, from the dashboard Accounts section select an admin, then click View/Edit dropdown for Access Details:

last repo user
Access Details

Click View Account Report to show the last access time for a single account:

last access time by ac
Account Audit Report

6.2.9. Conflict reports

Any conflict report is shown in the Reports menu. If there are any current conflicts in the system then a report of those conflicts can be found in the reports dropdown. The triangle-with-exclamation-point icon signifies that there are existing conflicts.

Conflicts explained
When creating a rule, if the rule to be created causes any priority conflicts, the user will be made aware that conflicts exist and ask to confirm their action.

6.2.10. Remove an account

Important: Benefits of not removing accounts
Access Control Plus lets you quickly and easily remove accounts, either manually or through LDAP. Many customers prune their Access Control Plus account pools to make group creation and management more manageable, especially in large organizations that have a rapid turnover of teams. However, there are some good reasons to avoid the outright removal of accounts:
  • You can free up licenses by disabling accounts instead of deleting them.

  • An account’s history is lost when it is deleted. Don’t delete accounts if you need to store historical data for all accounts.

  • Should a user return to a team it is easier to re-enable an account than it is to recreate it. You may need to remove accounts if you exceed the maximum number for your license. Consider disabling accounts or removing them from all teams instead of removing them in case the account holder needs access restored in future.

To remove an account from Access Control Plus:

  1. Log in to the admin console. From the management screen, find the account that you want to remove.

    acp admin account09
    Select Account
  2. Tick the check box to the left of the Account holder’s name, then click the - Remove button on the top of the Accounts pane.

    acp admin account10
    Remove Account

    A pop-up warning asks "Are you sure?".

    Important: No undo for account removal
    Be sure that you want to remove the account. There is no restore function.
  3. If you are sure, click OK.

The account is completely removed from Access Control. It no longer appears on the accounts list, or in any teams or rules. If the account is an LDAP account and that account is a member of an LDAP group that is used to define an ACP Team via an LDAP query then that account will be re-created and re-instantiated into the team upon next LDAP poll.

If you need to check the account’s particulars to ensure that you are removing the correct account, go to the accounts details screen, you’ll find a Delete button at the bottom. This does the same thing as the remove link on the main management screen.

Before removing LDAP-based accounts
We recommend that you remove the LDAP team queries before removing those LDAP accounts included in those teams. This will ensure that the removed account is not automatically re-added.

6.2.11. Disable an account

Disabled accounts remain stored in Access Control Plus. They are, however, unable to log in or interact with any repository resources. You can quickly add back a disabled account by re-enabling it.

acp disabled accounts01
Disabled accounts
Disabled accounts are not counted towards the licensed number of users
You can store users in a disabled state even if you need to make room for additional users within the limit of your current license.
  1. Log in to the admin console. From the management screen, locate the account that you wish to disable.

  2. Click the account holder’s name to open up the Account page.

  3. Click the Edit button to view the account’s basic details. From the accounts details screen, tick the Disabled check box, then click the Update button. Disabled accounts display with greyed out strike-through text.

6.3. Teams

Teams make organizing account permissions much simpler. They allow you to apply rules to many accounts at the same time, rather than for each individual account. Another benefit is the ability to delegate administration to a team administrator

Audit accounts are now automatically removed from teams
The Audit account is strictly reserved for special use cases and are not intended to have access to repository data. Earlier versions of the product did not guard against audit accounts being placed on teams, where they may inherit repository file access. For this reason, upgrading to ACP 1.9 will automatically remove all audit accounts from any teams they have been assigned to.

6.3.1. Create a team

Use this procedure to set up a new Access Control team. This is the same method as for adding accounts manually. You can also manage your team structure through LDAP, setting up a query that filters for the specific account holders that you need for a particular team. For more information see Adding an LDAP-based team.

  1. Log in to the admin console.

  2. On the Teams panel, click the + Create button.

    create team02
    Create
  3. Complete the entry form for your new team.

    create team03
    Enter Team info
    Team Name

    Name for the team.

    Team Description

    Enter a description for the team.

    Team Leaders

    During the team creation process this section is not available.

    Create (button)

    Click the button to save the new team.

  4. The team’s screen now appears. From here you define the team in terms of it’s Subteams, Members, Resources, and Rules.

    create team04
    Team Screen

    Subteams
    Subteams are themselves teams of accounts. Subteams differ from teams in that they can only be formed as a subset of their parent team’s accounts and available resources. The main benefit of subteams is that they allow administrators to dole out portions of accounts to subordinate team leaders who are able to manage their subteam, without having wider access to members and resources that fall outside of their responsibility. This means that administrators can delegate day-to-day user creation, user removal, etc. to team leaders, and still limit full SCM access.

    Members
    Accounts that are added to a team become Members. You can add existing accounts using the + Add button, then selecting accounts. From the screen you can also create a new member using the +Create button, which opens up the Create Account panel.

    create team05
    New members

    Resources
    Resources are representations of repository templates. If you create a team you’ll not be able to add resources until you have established some Repository Templates from the Settings section.

Resources are repositories that have been associated with repository Templates (or refinements thereof).

6.3.2. Adding an LDAP-based team

Follow this procedure to create a team that is populated from an LDAP authority.

6.3.3. Expected LDAP account behavior

  • A disabled LDAP-managed account will NOT be re-enabled if manually associated with a new team. In this scenario an administrator must re-enable the account by hand.

6.3.4. Mix and Match

When LDAP-based accounts have been added to Access Control Plus, they appear within the Accounts pane and can be added to any team. However, it’s easier to track and manage LDAP users if they’re enabled through their own team, where the team is set up to get its members from an authority. However, so long as you tick the checkbox Allow local users, you can also add local users to an LDAP-managed team.

6.3.5. Add an LDAP-based team

  1. Log in to Access Control Plus. If you have not done so already, add an LDAP authority, in this case the one from which you will be pulling accounts.

  2. On the Teams pane, click the + Create button.

    acp ldapteam01
    Create team
  3. Fill out a Team Name and Team Description, then click the Create button.

    acp ldapteam02
    Add Team info
  4. The Team is created. Now click the Edit link.

    acp ldapteam03
    Edit team
  5. From the Team edit window, enter the relevant details for an LDAP authority that you wish to associate with the team. Select the authority from the dropdown. You’ll need to add one. When you have entered those details, click Update. It is intended that you use a single LDAP authority and filter the relevant accounts using queries. Please note that Active Directory and OpenLDAP use different methods to startup the LDAP Authority and different formats for the queries but they both work.

    acp ldapteam04
    Add LDAP details
  6. Click Close.

    acp ldapteam05
    Close once updated
  7. You are returned to the master screen. The team should now be populated from LDAP.

    acp ldapteam06
    See team details
    Polling for LDAP accounts can take some time.
    When adding teams from an LDAP authority, consider that it may take a little time for the new accounts to be imported. Don’t panic if accounts don’t appear immediately. You may need to wait a while before refreshing the team page.
  8. Return to the team by clicking its name. You can now select which users from LDAP are added to the group. Also add any other team components (Resources, Rules, subteams etc) that you need.

acp ldapteam07
Edit team

6.3.6. Remove an LDAP-based association from a team

From ACP 1.9 it’s possible to remove LDAP-based team members from a team. Previously, you were required to delete then recreate the team.

  1. Navigate to a team with an LDAP association that you wish to break.

    acp remove ldapteam01
    Select team
  2. Click on the Team’s Edit link.

    acp remove ldapteam02
    Edit
  3. Click on the Associated LDAP dropdown.

    acp remove ldapteam03
    Select associated LDAP
  4. From the dropdown, select No LDAP authority.

    acp remove ldapteam04
    Select 'No LDAP authority'
  5. Select whether to remove all LDAP-based users from the team. Check the Remove the associated LDAP users? checkbox to remove team members. If left unticked then after the LDAP association is broken, LDAP users will be left on the team. Click Update.

    acp remove ldapteam05
    Tick box
  6. If you selected to remove users you will be prompted to confirm your choice. Click Confirm.

    acp remove ldapteam06
    Confirm
  7. You will receive a confirmation message Team successfully updated

    acp remove ldapteam07
    Confirmation

6.3.7. Edit a team

  1. Log in to the admin console.

  2. On the Teams pane, click the name of the team that you want to edit.

    acp admin team01
    Select team
  3. The team’s screen opens.

    acp admin team02
    Team’s screen

    From here you can create additional Subteams, Add more resources, Add/Remove Members or Rules.

6.3.8. Add Team Leader

On the Team edit screen you can add team leaders for the team:

  1. On the Edit Team dialog, click + Add Team Leaders button.

    add team leader00
    Add Team Leaders
  2. Select those team members that you wish to elevate to Team Leader positions by selecting them using the checkboxes.

    add team leader01
    Select members

    A permissions panel will be displayed for each account that you add. The panel will provide checkboxes for each of the following actions:

    Create Subteams

    Account will be permitted to create subteams for those teams to which they belong.

    Create Accounts

    Account will be permitted to create new accounts for their teams/subteams.

    Disable Accounts

    Account will be permitted to disable accounts.

    Modify Resources

    Account will be permitted to alter the properties of the team’s/subteam’s available resources.

    Modify Members

    Account will be able to make changes to team/subteam membership.

    Modify Rules

    Account will be able to make changes to any applicable rules.

6.3.9. Delete a team

Use the following procedure to remove a team from ACP.

  1. Log in to the admin console.

  2. Click the Team or Subteam that you wish to delete.

    acp team delete01
    Select team
  3. Click Edit to view the teams/subteams settings, then click Delete.

    acp team delete03
    Delete
  4. You are prompted to confirm the deletion. You cannot undo deletions so Access.

    acp team delete04
    Confirm
  5. Control Plus always checks before deleting an object.

6.4. Resources

Resources are Repositories that have been activated by being associated with a repository Template.

6.4.1. Create resources

For SVN deployments, you can create "local" (non-replicated) resources. This is not possible for Git deployments because GitMS is the AuthZ enforcement mechanism for Git.

Use this procedure to create team resources, when not syncing with WANdisco’s MultiSite products. If you are connecting to MultiSite then resources are created from whatever repositories that are automatically added. See Create a resource in a MultiSite Environment.

6.4.2. Create a resource in a MultiSite environment

Use this procedure to create additional resources, if syncing with WANdisco’s MultiSite products. If you are connecting to MultiSite then resources are selected from whatever repositories that are automatically added.

May 26, 2015 8:55:55 PM com.wandisco.acp.repository.integration.RepositoryPollingThread
logVerboseWarningWhenPollingFails

WARNING: git-polling-thread1:[Error polling repositories from https://10.20.28.155:8082/api/ as user
admin, password is set, [com.wandisco.vcs.api.exception.VCSAPIConnectionException:
com.sun.jersey.api.client.ClientHandlerException: javax.net.ssl.SSLException:
Unrecognized SSL message, plaintext connection?
Repositories (w/o templates) currently can’t be deleted until they are assigned a template.
  1. Log in to the admin console. On the main management screen, click the Assign template button of a repository that has been synced from Git and or SVN MultiSite.

  2. A window appears and lists the available Repository Templates that correspond with the relevant version control system. Select one of the available templates.

  3. Click Save. You are returned to the main screen, with the new resource added to the list.

6.4.3. Edit a resource

You can easily edit resources by clicking on the resource’s name.

Access Control Plus supports repository resources in various configurations:

  • Replicated: managed and replicated through a WANdisco MultiSite product

  • Non-replicated: stored in a MultiSite node and not replicated to other nodes

  • Standalone mode: Non-replicated "local repositories" are stored directly on the Access Control Plus server.

You can tell the type of a particular resource by checking the text under its title. It says either "Replicated" or "Non-replicated".

  1. Change any of the editable values, then click Save.

    acp resources edit01
    Edit

6.4.4. Refine a resource

You can refine a resource to specify a Subversion sub-repository path or a Git Branch or Git Tag:

  1. Click the relevant Team, or create a team and add members.

  2. Click Add in the Resources pane.

  3. Click the checkbox to the left of the repository that you want to add a refinement for. A repository shows on the right-side pane.

    refine resource
    Refine resource
  4. Click Refine.

  5. Enter the sub-repository path, (/proj-1 in the example above) then click Add. This is confirmed in the Being added list.

  6. Click Finish, then Confirm.

You can now add this resource to a rule for the team. See the Rules section.

6.4.5. Remove a resource

You can remove the resource from the main screen. Change any of the values, then click Save. See the Refinements with wildcards

Removing a repository

We need to avoid changes being made to the repositories after they are removed from replication, so only the repository instance on the server used by the Git/SVN client gets updated instead of the replica family - thereby diverging that instance from the replicas.

  1. Remove all references to the repository as a resource from ACP.

  2. Generate AuthN/AuthZ files from ACP and verify distribution to all MSP (or GitMS) nodes. See Authorization and Authentication file delivery.

  3. Remove repository from your MultiSite product. Remove an SVN Repository / Remove a Git Repository.

6.5. Rules

Rules define which resources and permission levels are applied to accounts. Rules are always applied through an account’s team membership, never directly to accounts. Accounts can only have rules applied to them if they are first assigned to a team.

6.5.1. Using Rule lookup

The Rule lookup provides administrators with a means of testing what access and permissions apply to a specific account. Given that accounts can belong to multiple teams and have multiple rules applied, the Rule lookup tool can useful.

  1. Click the Rule lookup link on the top menu bar.

    rule lookup0
    Rule lookup
  2. Enter an account name, a repository name and resource path for which you want to test access.

    rule lookup1a
    Rule lookup
    Account name

    The name of the account that you want to investigate

    Repository name

    The name of the repository that you wish to test against

    Resource path

    The file system path to a specific part of the repository.

    • To check the whole repository leave this field as None.

    • To specify a path, select SVN Path for SVN repositories or Git Branch/Git Tag for Git repositories.

    Permissions

    Those access permissions that apply to the selected account, for the selected repository resources will be listed in the Permissions table. For more information on permissions, see Create a rule.

Click the Lookup button to start the search. All rules that apply to the account for the specified resources are displayed in the Permissions table.

If you deploy with both Git and SVN repositories
An additional entry field is listed that you use to select between SVN and GIT.
rule lookup1
Lookup
Repository type

Select between the two available SCM system types.

Resource refinement

When both Git and SVN are deployed then the Resource Path entry field is changed to Resource refinement.

rule lookup2
Resource refinement
New in ACP 1.9
SVN wildcards and priorities are now honored when performing searches using the Rule Lookup tool.
acp wildcards honored
Permissions

In the example, conflicts are being handled correctly now with most permissive rule on a path being displayed correctly on rule look up.

6.5.2. Create a rule

To create a new rule:

  1. Log in to the admin console. As rules can only be assigned to a Team, click the Team’s name.

    rule create01
    Select team
  2. On the Team screen, click the + Create button at the top of the Rules panel.

    rule create02
    Create Rule
  3. Enter a name and click Create.

    rule create03
    Enter name
  4. You now add accounts for which the rule you are creating will apply. You choose from the existing members of the Team you selected in step 1.

    rule create04
    Add accounts
  5. You can Apply Rule to all current and future team members by ticking the top checkbox. You can select specific members for the rule by ticking their corresponding checkboxes.

    rule create05
    Specify members
    Important temporary limitation
    Currently, when "This rule applies to all current and future team members" is checked for a rule, if we use the search box to look up an account, those rules will not show up as being associated with an account.
    Workaround
    Click on the account and then all their associated rules will be visible. If an account is manually added to a rule, the rule will show up in the search.
  6. Click Confirm to save your Member settings.

    rule create06
    Confirm to apply rule
  7. All selected members will now appear on the rule screen. Now add some resources by clicking the + Add button at the top of the Resources panel.

    rule create07
    Add resources
  8. Tick the top checkbox to select all available resources for the team or select them one by one by ticking the corresponding checkbox for each applicable resource.

    rule create08
    Remove resources

    Any resources that are mistakenly added, can be removed using the - Remove button.

  9. When all the resources that you want included in the rule are added, click Confirm.

    rule create09
    Confirm
  10. Finally, Select the permission types that you want to apply to each resource.

    rule create10
    Select permissions
Permissions
Inactive

Permission are not recorded for the selected resources.

Read

Accounts have permission to access/read files

Read/Write

Accounts have both read and write access to the selected resources.

Git deployments only
Additional permissions are set for Git:Create and Git:Remove.
Git Create
Inactive

Permission inactive. No permission level is recorded, as if the user was removed from the system.

Deny

Selected accounts do not have ability to Git Create.

Allow

Selected accounts DO have ability to Git Create

Git Remove
Inactive

Permission inactive.

Deny

Selected accounts do not have ability to Git Remove

Allow

Selected accounts DO have ability to Git Remove

6.5.3. Edit a rule

  1. To edit a rule click its name on the main screen. This opens the Rule panel so that you can modify its properties.

    edit rule01
    Select rule
  2. To edit a rule click its name on the main screen. This opens the Rule panel so that you can modify its properties.

    edit rule02
    Rule panel
  3. Make a change to the Rule’s properties, such as turning on the "Apply Rules to all current and future team members"

    edit rule03
    Make change
  4. Click the Save selection button.

    edit rule04
    Save

6.5.4. Delete a rule

  1. To delete a rule, login to the Access Control UI.

    delete rule01
    Rules panel
  2. Tick the checkbox that corresponds with the rule that you wish to delete, then click on the - Remove button.

    delete rule02
    Select rule
  3. A prompt will appear. Click OK to confirm the deletion.

    delete rule03
    Confirm removal

6.5.5. Authentication failure instead of authorization error

When troubleshooting user access problems (in deployments that manage htpasswd/sshd files) you may notice that an active account for which only DENY rules currently apply will generate an authentication rather than authorization error on any Git/SVN access attempt. It’s as if the account didn’t exist or the wrong password was given, instead of not having the appropriate access permissions. This apparent quirk is by design. If an account doesn’t have access to any resources at all, we don’t bother writing it to the password or sshd rules file. In fact, if the account doesn’t have any associated rules then "Deny" rules are applied by default and the account will not be written to the AuthZ file either.

You should note that this does not occur if authentication is delegated to LDAP/AD or any method which does not use passwd/sshd files.

6.6. Enable/disable batch updates

Follow this procedure to enable Batch mode. Make sure you understand what it does and how it works before you do though.

WARNING
We strongly recommend that you use the Batch mode. This is especially critical if you are using the ACP REST API for automated configuration updates.

Batch updates is a mechanism that will improve performance in deployments that have large number of accounts, repositories and rules and/or deliver to many Subversion MultiSite Plus or Git MultiSite nodes. See the Reference Guide for more information about Batch Updates Mode.

  1. Log in to Access Control Plus and click the Settings link.

  2. Click the Access Control Updates bar.

  3. Tick the Enable checkbox. Confirm the switch period (in seconds) and select which node will manage the batching process. Ideally this should be the longest period that you can tolerate the AuthN/AuthZ files being behind changes to the ACP configuration - for example 1 hour. In large deployments this should not be set to less than 10 minutes.

    acp batchupdates02
    Batch updates
  4. Click on Save.

See Access Control Updates for more details.

6.7. Node Management

6.7.1. Connecting your Access Control Plus nodes

If you are deploying multiple Access Control Plus nodes, follow these steps so that the nodes communicate with each other correctly

Important
1. Nodes that are not the state machine creator are locked down until they are inducted
You won’t be able to create any objects (accounts, teams, rules, etc.) on the non-state machine creator nodes until you have completed the following procedure.
2. Don’t refresh the UI during an induction
Do not reload the browser session or navigate away while you are using the browser to complete an induction. Doing so is likely to cause problems, possibly causing the induction to stall and/or fail.
3. There can be only one.
When installing your nodes, remember that the step to assign one node as the state machine creator should only be answered Y on one of your nodes. It can be any node. It does not have to be the first one that you install. This procedure refers to the state machine creator node as the induction controller node.
  1. Repeat the Installation Procedure on your additional Access Control Plus nodes.

  2. When all nodes have been installed and are running, log in to each node that you did not assign as the induction controller node. These nodes are in a waiting state, locked down until they have been inducted into the replication network.

    acp install induction01
    Need to induct node

    You need to copy the above details into the induction controller node’s Inductor entry fields.

  3. Log in to the Induction Controller Node, go to Settings, then click Node Induction, under Node Management.

    acp install induction02
    Node induction
  4. Copy the details of each node into the form. Ensure that the Inductor host name does not include the protocol prefix "http:/". When entered, click Confirm. The node appears in the list of pending nodes. Induction completes quickly.

    Permit no actions until induction completes
    Although the induction process is usually very fast, if it takes a while make sure that there is no attempt to interact with the admin console screens until the induction controller node reports that the process has completed. Don’t refresh the browser session or navigate away from the UI until the induction is confirmed to have finished.
    Stuck in pending state
    If any node gets stuck in a pending state, you can cancel its induction and try again. See troubleshooting.

6.7.2. Node repair

Node repair is not used to handle the loss of one or more nodes when replication is setup. It is used to re-align the ACP accounts, teams, resources and rules should divergence occur. It essentially copies all of this data from the helper node to the target node.

Removing inducted nodes is done via the Node Induction page on the Settings area.

important
The Node Repair tool efficiently returns a divergent node back into alignment with the other nodes. However, its misuse can worsen the situation. Until we place blocks against potentially destructive actions, we strongly recommend that you don’t use the Repair Tool unless under direct instruction from WANdisco’s support team.

6.8. Enable SSL encryption

Access Control Plus supports the use of Secure Socket Layer encryption (SSL) for securing network traffic. Currently SSL properties are not exposed through the admin console, instead you need to make edits to Access Control Plus’s applications properties file.

Problem: Access breaks when running Access Control with a MultiSite product (Git MultiSite or SVN MultiSite)
In any deployment consisting of Multiple WANdisco ALM products, SSL must either be turned ON or OFF in all products. Not adhering to this requirement will mean that ACP will lose contact with the other WANdisco ALM product(s) you use and be unable to deliver the required Authentication or Authorization files. Do not change the SSL setting in one product without changing the SSL settings in all products.
/opt/wandisco/scm-access-control-plus/properties/applications.properties

If you plan to use SSL you need to run through the following steps before going into production.

6.8.1. Overview

SSL is enabled for both UI and the underlying Rest API (the administrator’s access to HTTP port will automatically redirect to HTTPS) AND for internal communication between nodes on 'application.port' and 'content.delivery port'. For this reason the switchover needs to be done on all nodes at once, otherwise those nodes that delayed their switch will no longer be able to talk to those nodes running with SSL.

6.8.2. Use stronger and faster encryption

Java’s default SSL implementation is intentionally weak so as to avoid the import regulations associated with stronger forms of encryption. However, stronger algorithms are available to install, placing the legal responsibility for compliance with local regulation on the user.

See Oracle’s page on the Import limits of Cryptographic Algorithms.

If you need stronger algorithms, i.e. AES which supports 256-bit keys, then you can download JCE Unlimited Strength Jurisdiction Policy Files that can be installed with your JDK/JRE.

To follow this procedure you will need to create a keystore and a truststore.

Keystores and truststores in a nutshell
You might be familiar with the public key system that allows two parties to use encryption to keep their communication with each other private (incomprehensible to an intercepting third-party).

The keystore is used to store the server certificates and the keys that enable access to them that are used in this system. However, in isolation, the system remains susceptible to the untrustworthy server certificates, where a server certificate and the client can then be unaware that it will communication with an impostor. Certificate Authorities, CAs, are trusted third parties that issue digital certificates that verify that a given server certificate is trustworthy. The information about which server certificates to trust is stored in the truststore. The truststore is like a keystore file, but used for certificates instead of keys. An SSL implementation requires the use of both truststore and keystore files.

6.8.3. SSL enabling procedure

  1. Create a new directory in which to store your key files. This directory can be placed anywhere. In this example it is within the Access Control file structure.

  2. Open a terminal and navigate to /opt/wandisco/scm-access-control-plus/config/.

    -rw-rw-r-- 1 wandisco wandisco 29 Apr  5 16:53 main.conf
    
    [User@redhat6 config]$ mkdir ssl
  3. Go into the new directory.

cd ssl

Copy your private key into the directory. If you don’t already have keys set up you can use JAVA’s keygen utility, using the command:

keytool -genkey -keyalg RSA -keystore wandisco.ks -alias server -validity 3650 -storepass  <YOUR PASSWORD>
Knowledgebase
Read more about the Java keystore generation tool in the KB article link:[Using Java Keytool to manage keystores.
-genkey

Switch for generating a key pair (a public key and associated private key). Wraps the public key into an X.509 v1 self-signed certificate, which is stored as a single-element certificate chain. This certificate chain and the private key are stored in a new keystore entry identified by alias.

-keyalg RSA

The key algorithm. In this case RSA is specified.

wandisco.ks

This is the filename for your private key file that will be stored in the current directory.

- alias server

Assigns an alias "server" to the key pair. Aliases are case-insensitive.

-validity 3650

Validates the keypair for 3650 days (10 years). The default is 3 months.

- storepass <YOUR PASSWORD>

This provides the keystore with a password.

No password specified
If no password is specified on the command, you are prompted for it. Your entry is not masked so you (and anyone else looking at your screen) will be able to see what you type.
Most commands that interrogate or change the keystore need to use the store password. Some commands may need to use the private key password. Passwords can be specified on the command line (using the -storepass and -keypass options).

However, you should not specify a password on a command line or in a script unless it is for testing purposes, or you are on a secure system. When placed into the Access Control Plus properties file you first need to manually encrypt it, as described in the section below:
The utility prompts you for the following information:

What is your first and last name?  [Unknown]:
What is the name of your organizational unit?  [Unknown]:
What is the name of your organization?  [Unknown]:
What is the name of your City or Locality?  [Unknown]:
What is the name of your State or Province?  [Unknown]:
What is the two-letter country code for this unit?  [Unknown]:
Is CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct?  [no]:  yes
Enter key password for <mykey>
(RETURN if same as keystore password):
  1. With the keystore now in place, you next need to make the edit to the application.properties file.

node.id=bouncer
application.hostname=172.16.5.94
application.port=6888
#content server port
content.server.port=6845
jetty.http.port=8882
database.location=/opt/wandisco/scm-access-control-plus/database
application.location=/opt/wandisco/scm-access-control-plus
content.location=/opt/wandisco/scm-access-control-plus/content
jetty.https.port=8084
ssl.enabled=true
ssl.debug=false
ssl.keystore=
ssl.keystore.password=

#Option SSL parameters

ssl.key.alias
ssl.key.password - SimpleCrypt encrypted
ssl.truststore
ssl.truststore.password - SimpleCrypt encrypted
xxsl.enabled

Switch for enabled SSL. Value: true<./dd>

ssl.debug

debugging mode. Don’t enable by default. Value: false.

ssl.keystore

The absolute path to the keystore.

ssl.keystore.password

The password for the keystore - this password must be encrypted using the SimpleCrypt class. We’ve provided a little utility to handle the encryption:

/opt/wandisco/scm-access-control-plus/scm-access-control-plus-cryptPassword.jar

Use the utility as follows:

java -jar scm-access-control-plus-cryptPassword.jar password
Gbwkzxmo70xNNy1/oVMb/7PuE3yB1+fhHX7O9qxIg6k3eNDuU6bzOCKO4Ldi0SJDDycScJjnGq2FxOYYAl0JiBRXIDGRxEVBj <snip>

6.8.4. Optional SSL parameters

These additional parameters support a more robust implementation of SSL that uses trust certification:

ssl.key.alias: Specify an alias for the private key. This is the name used to identify the key inside the keystore.

Critical
The key password must be identical to the keystore password. JAVA’s implementation does not allow these 2 to be different.

ssl.key.password: Password if the cert is password protected. Encrypt it as described above.

ssl.truststore: Path to the truststore file

ssl.truststore.password: Password for the truststore - must be encrypted as above.

Changes in any of these values require a restart of Access Control Plus. Any invalid value is likely to result in Access Control Plus not running properly.

SSLv3 Support
SSLv3 is supported (though not enforced). If your browser setting has SSLv3 disabled, you will get a handshake error message. If it has both SSLv3 and TLS enabled then, depending on the browser, it will try to switch from TLS to SSLv3 during the handshake. If you receive a handshake error message in your browser, make sure that TLS is disabled and only SSLv3 is enabled. All current browsers support SSLv3.

6.8.5. Set the server key

In the keystore, the server certificate is associated with a key. By default, we look for a key named server to validate the certificate. If you use a key for the server with a different name, enter this in the SSL settings.

6.8.6. Export the certificate

Next, if using self-signed certificates, you need to export the certificate so that it can be added to the truststore as the trusted certificate. Again, using Java’s Keytool. Note that some administrators may want to simply combine all of their server certificates into a single keystore and then use that keystore as the truststore. The only thing they’ll need to do is

keytool -export -alias server -file <Cert-Name>.cert -keystore wandisco.ks
Enter keystore password:
Certificate stored in file <Cert-Name>.cert

After exporting the certificate use creates a keystore file named myTrustStore in the current working directory and imports the first certificate into the truststore with an alias of <Cert-Name-Alias>. The format of myTrustStore is JKS. Each additional run of the command adds additional certificates to the TrustStore. When completed, myTrustStore is available to be used as the truststore.

6.8.7. Auditing setting and SSL

If auditing is installed: . Update the setting acp_agent.sinks.acpSink.acp_ssl_enabled in the <flume install dir>/receiver/conf/flume_acp_receiver.properties file to:

acp_agent.sinks.acpSink.acp_ssl_enabled = true
additional settings
acp_agent.sources.avroSrc.ssl = true or false
acp_agent.sources.avroSrc.keystore = kestore file
acp_agent.sources.avroSrc.keystore-password = password for keystore
acp_agent.sources.avroSrc.truststore = truststore file
acp_agent.sources.avroSrc.truststore-password = password for truststore
  1. Restart the Flume receiver:

<flume install dir>/receiver/stopFlume.sh
<flume install dir>/receiver/runFlume.sh

6.8.8. SSL Troubleshooting

A complete debug of the SSL logging will be required to diagnose the problems. To capture the debugging, run the java process with:

'-Djavax.net.debug=all' flag.

To enable the logging of SSL implemented layer, turn the logging to FINEST for the com.wandisco.platform.net package.

Problem: Access breaks when running Access Control Plus with a WANdisco MultiSite product (Git MultiSite or SVN MultiSite Plus).

Example error message

May 26, 2015 8:55:55 PM com.wandisco.acp.repository.integration.RepositoryPollingThread logVerboseWarningWhenPollingFails
WARNING: git-polling-thread1:[Error polling repositories from https://10.20.28.155:8082/api/ as user admin, password is set, [com.wandisco.vcs.api.exception.VCSAPIConnectionException: com.sun.jersey.api.client.ClientHandlerException: javax.net.ssl.SSLException: Unrecognized SSL message, plaintext connection?

6.9. Connect to MultiSite

This section describes how to connect Access Control Plus to an existing Git or SVN MultiSite setup:

  1. Log in to the admin console. Click the Settings link on the top menu.

  2. Click the Connect to MultiSite bar in the External Applications section.

    acp ms01
    Connect to MultiSite
  3. Enter the required MultiSite details:

    acp ms03
    Enter SVN details
    acp ms03b
    Enter Git details
    API IP

    The IP address of the MultiSite node.

    API PORT

    The port used for Rest API traffic (Default is 8082).

    API User

    Username for Access Control Plus to use to access the MultiSite node.

    Managing Node (Drop-down)

    Select which Access Control Plus node will manage communication with MultiSite.

    Poll Period

    The frequency (in seconds) that Access Control Plus will check for changes on the MultiSite node. Default = 3600 (1 hour). Minimum = 60. First poll happens immediately on setting this value.

    Don’t set this value too low
    If you have a large deployment, synchronization will be resource hungry.
    Use SSL (checkbox)

    Enable SSL encryption for the API traffic.

    Password

    Password for the MultiSite account.

    Retype Password

    Repeated password entry (to ensure you entered it correctly above.

    Save/Cancel (buttons)

    Click Save to store the details, or Cancel to clear them. When you have added all the details, click Save.

  4. Return to the main Access Control Plus screen. If there are Repositories being handled by MultiSite, they’ll be automatically synced with Access Control Plus, appearing in the Repositories panel.

    acp ms04
    Repositories

    At this point the repositories are known to Access Control Plus, but it still needs to be configured with authentication and/or authorization files for each repository using the Repository templates options.

6.10. Connect to LDAP

This section describes how to configure Access Control Plus to query one or more LDAP authorities in order to pull in accounts for your Git or Subversion users.

LDAP changes from ACP 1.7.2 onwards
  • The "Group DN" attribute can now be a comma separated list.

  • The "Group DN" field is no longer required. Whether or not a customer’s environment requires the "Group DN" field very much depends on their LDAP schema.

6.10.1. Team LDAP query field

The following table shows you how the Group DN is used, when evaluating the Team LDAP query field.

Table 1. Team DN Behavior
Contents of the Team LDAP query field: Resulting evaluation:

is a DN

The DN will be used to define the team membership (without using the Group DN)

is not a DN AND the Group DN is not empty

Team LDAP query contents are considered a filter, applied to Group DN field

Team LDAP query contents are not a DN AND the Group DN field is empty

Team LDAP query contents are considered a filter and applied to the Account DN field

Team LDAP query contents not a DN AND Group and Account DNs are empty

Error message is emitted

The result of this set of behaviors is a very high degree of flexibility which is required to support the vast range of possible LDAP schemas.

6.10.2. Example LDAP/AD deployments using "Team Query"

  • If your LDAP schema is such that all groups can be found as sub-entries of a single Group DN then you should fill this in. It will be used during the "Test" phase of defining the LDAP authority and will be used later when the filter specified in the Team LDAP query filed is tested and used.

  • If your LDAP schema is not flat, and your groups are DNs found scattered around the LDAP DIT (directory information tree) then you don’t need to fill in the Group DN Attribute. If you do fill it in then it will be used during the "Test" phase of defining the LDAP authority. It may be used later on as well but need not be (see above). In this case the Team query field will usually be a DN (but simple teams could be constructed by filters against the "Account DN").

6.10.3. LDAP Settings

The settings tell Access Control Plus how to use any available LDAP authorities that you connect up.

Synchronization Period (minutes)

Access Control Plus reruns your LDAP queries with this frequency, picking up any changes that may have occurred within the LDAP service. Default = 60 (1 hour). Minimum = 1. First synchronization happens immediately on setting this value.

Do not set the period too low, or to zero.
You shouldn’t need to constantly hit your LDAP authority. If you have a large deployment, synchronization will be resource hungry. Please do not set this to less than 5 minutes in any environment other than one used for demonstration purposes.
If you perform an import from an earlier version of Access Control you must ensure that Access Control Plus does not poll the LDAP authorities during the process. You can do this by setting the Synchronization Period to 999 (minutes) just for the duration of the import.
Allow Local Users

This checkbox is ticked by default. When ticked it is possible to field both LDAP-controlled and manually entered Accounts. Some organizations don’t permit manually entered accounts because they need to be sure that all accounts are managed through their LDAP. If this is the case, untick the checkbox when your LDAP accounts have been successfully imported.

If you are running with Local Users disabled and your LDAP service fails, you can re-enable local users as part of the account password recovery process. This process automatically re-enables local users, allowing you to gain access to the admin console.

6.10.4. Entering LDAP Authority details

This is the entry form for adding any number of LDAP Authorities. Multiple Authorities are checked in the order that matches their order number (see below). The lower the order number, the earlier the authority is checked.

acp16 ldap01
LDAP settings
LDAP Settings
Synchronization Period (minutes)

How long Access Control Plus waits before each poll of the LDAP service for updates. Default:60 minutes

Maximum LDAP team Size before prompting

This property acts as a safety valve for when you create new teams in very large organizations. If an LDAP query generates a team that is larger than this number, you will be asked to confirmation before it is imported. This can be used to prevent the accidental creation of teams that contain hundreds of thousands of accounts that would negatively impact performance during

LDAP Authorities

Lists the existing LDAP services that are connected to Access Control Plus. LDAP authorities are added using the Add LDAP Authority table.

Add LDAP Authority
acp16 ldap02
Add LDAP authority
Order

The priority given to the LDAP URL. For example, a location order of 1 means that Access Control will look within that defined authority for a user first. If unsuccessful then Access Control will then check the authority with the next order number, e.g. 2.

Name

A given name for the authority. Names are only used as labels in Access Control Plus to make it easier to manage multiple LDAP authorities.

Regex

Enter a regular expression to set a pattern for matching against the account name for the available LDAP authorities. The expression, is applied locally to limit unnecessary queries against available LDAP authorities. For instance, setting an expression that specifies a top-level domain can ensure that authentication of a user (whose username is their email address) doesn’t need to run through all LDAP authorities. Instead it can be checked only against those servers that match the regular expression, in this case, the .* match anything wildcard.

Using the Regex field:
In general the Regex field should be considered as Deprecated; please contact WANdisco support if you currently use anything other than ".*"
Base URL

The base URL is the point in the LDAP "tree" where you start your searches. Using the format ldap(s)://hostport/basedn?attribute.

Bind DN

The distinguishing Name is used by ACP to authenticate to LDAP in order to read LDAP groups, etc. In the case that the customer’s LDAP disallows unauthenticated LDAP queries.

Bind password

Corresponding password for the administrator account.

User DN Settings

The User DN is for the Subversion accounts that ACP will pull in from LDAP, that will be used for building teams and for adding to the authz file. This includes both user accounts and service/application accounts.

User DN

Distinguishing name for the account users.

User DN Attribute

The name of the uid attribute for a user in the directory.

User DN Scope

DN Scope determines how deeply into a directory searches are made. Combined with the Base DN and User DN filter to set the limits for which users are matched for authentication. Options are Base, One or Subtree.

User DN Filter

LDAP Search string used to filter the directory for applicable accounts.

Auth DN Settings

The Auth DN is used by ACP to authenticate LDAP accounts that are logging into ACP.

Auth DN

The distinguished name of the a directory container that can be combined with the Auth DN Attribute and the Auth DN Attribute value (what the user typed for an account) to form a complete LDAP DN.

Auth DN Attribute

Used to identify the LDAP account name’s type (e.g. "uid").

Auth DN Scope

Auth DN Scope determines how deeply into a directory searches are made. Combined with the Base DN and User DN filter to set the limits for which accounts are matched for authentication. Options are Base, One or Subtree. See further explanation of the different scope options.

Auth DN Filter

LDAP string that is used to filter a directory for valid accounts.

Group DN Settings
Group DN

Group distinguished name identifies a container for applicable accounts in a directory.

Group DN Attribute

The directory attribute that corresponds with the group distinguished name, used to authenticate against.

Group DN Scope

Group DN Scope determines how deeply into a directory searches for groups are made. Options are Base, One or Subtree.

Group DN Filter

LDAP string used to filter for valid groups.

User Request Page Size

This property is only used in conjunction with Group DN-based LDAP queries. It is used to override the system default for the maximum number of user records that can be requested by a single userDN query. A request for a large number of users is split into multiple requests to safeguard server performance and stability.

acp16 ldap03
User request page size
First Name Attribute

Attribute used for an account holder’s first name.

Last Name Attribute

Attribute used for an account holder’s last name.

Email Address Attribute

Attribute that corresponds with a user’s email address.

Public Key Attribute

Used with the LDAP service is encrypted, requiring Access Control Plus to be setup with an SSH key pair. As with any public key entry, make sure that no line breaks are introduced to the key, it should be one long string, no breaks.

Managing Node

Identifies the node from which LDAP settings are managed.

Case Insensitive (checkbox)

Tick this checkbox if you need MultiSite to stop distinguishing between usernames that differ only by their case pattern. For example, with the "Case Insensitive Usernames?" unticked (by default), MultiSite treats username "MelissaJones" and username "melissajones" as two distinct users. Support for username case insensitivity is a feature that may be required when Active Directory.

Admin Group (checkbox)

Tick this checkbox if the authority will return "System Administrators" accounts that are able to access the MultiSite admin console.

Ignore Workstations

This function is no longer applicable in Access Control Plus’s current form and will be removed in a future release. This feature allowed calls from workstations such as build servers to be ignored, when Access Control was based on a proxy architecture.

CAUTION
We strongly recommend that you do not add LDAP-based accounts that use the same account name. Currently you can have two accounts with the same name, because accounts can be distributed across any number of authorities. If you attempt to add two accounts that use the same account name, their addition fails and an error message appears in the logs that warns you: Incorrect result size: expected 1, actual 2.

6.10.5. Apache configuration for LDAP authentication

This how-to guide will give an example of how to set up LDAP authentication for subversion repo’s when checking out via apache. Then it will move on to how to set it up so that you can use the ldaps:// protocol (that is LDAP with SSL). Finally, it will show you how connect it all up to ACP (the easy part). Note: every LDAP server is a bit different, these instructions apply to our test openLDAP server, dse01.qava.wandisco.com (the org/group one). I will talk about our test Active Directory server too, pdc01.wandiscoqa.internal too as a separate example, but that one is a bit more sketchy as a result of its client certificates not being fully supported by apache.

Requirements
  • You have a working apache configuration over which you can perform subversion checkouts etc for normal users.

  • You have a working LDAP server (specifically access to the dse01.qava.wandisco.com server or pdc01.wandiscoqa.internal) that is set up to support SSL

  • An understanding that this won’t necessarily work for other ldap servers, the apache configurations may be different.

  • An understanding that this might not work with some versions of StartTLS (in the LDAP implementation) if you are using SSL/TLS encryption

Suggested Environment
  • Apache 2.2 - (the directives needed are sometimes different for other versions of apache)

  • openLDAP or Active Directory - but this is no guarantee that things will be the same.

  • CentOS 6 msp-flume vagrant vm

  • Repo1 in /opt/Subversion/

LDAP Authentication without ACP/authz files and without SSL encryption
ANY LDAP SERVER

Starting out without ACP and without SSL encryption. This set up will prevent anyone but an LDAP user from checking out a repo via svn.

  1. Find the file '/etc/httpd/conf.d/subversion.conf' and set it up as follows:

    # Needed to do Subversion Apache server.
    LoadModule dav_svn_module modules/mod_dav_svn.so
    
    # Only needed if you decide to do "per-directory" access control.
    LoadModule authz_svn_module modules/mod_authz_svn.so
    
    
    Listen 80   # This can also be in your httpd.conf file
    MaxKeepAliveRequests 0
    KeepAlive On
    KeepAliveTimeout 30000
    Timeout 7200
    
    <Location /svn>      # specified as the path when you do a checkout - ie svn co http://192.168.56.190/svn/Repo1
        DAV svn
        SVNParentPath /opt/Subversion  # the actual filepath
        AuthType Basic
        AuthName "SVN LDAP Repo"
        AuthBasicProvider ldap
        AuthzLDAPAuthoritative on
        AuthLDAPURL "ldap://dse01.qava.wandisco.com:389/cn=Users,dc=wandisco,dc=com?uid"    #  ie. ldap://<host>:<port>/<user DN>?<user DN attribute>
        AuthLDAPBindDN "cn=Directory Manager"
        AuthLDAPBindPassword password
        Require valid-user
    </Location>

    The setup above will work with any type of LDAP server, it is the minimum number of settings needed to make it work and just requires that the 'AuthLDAPURL', 'AuthLDAPBindDN' and 'AuthLDAPBindPassword' are set to your LDAP authority. Additional filters can be added to the end of the 'AuthLDAPURL' if needed by adding ?<filter> to the end of the 'AuthLDAPURL' directive. At this point no other authentication is set - ie. your authz file will make no difference.

  2. Restart Apache by running service httpd restart before trying to do a checkout.

LDAP Authentication with SSL but without ACP/authz files
OpenLDAP
  1. Firstly, you should obtain the SSL certificate from your LDAP server. This is relatively simple, in terminal run the command below. Note: If you need to do this with another LDAP server then note the use of port 636, its the standard for the ldaps protocol (as opposed to 389 for the ldap protocol) and this will probably be the same for your ldap server:

    openssl s_client -connect dse01.qava.wandisco.com:636

    This will return a long print out including the SSL certificate you will need. It will look like below. Save a copy of it in a .crt file, including the '---BEGIN CERTIFICATE---' and '----END CERTIFICATE----' lines.

    -----BEGIN CERTIFICATE-----
    
    MIICRDCCAa2gAwIBAgIFAKKMkgowDQYJKoZIhvcNAQEFBQAwZjEZMBcGA1UEChMQ
    
    U3VuIE1pY3Jvc3lzdGVtczEZMBcGA1UEAxMQR....................
    
    -----END CERTIFICATE-----
  2. Now edit your /etc/httpd/conf.d/subversion.conf file so that it looks like below. Look at where I’ve added in my SSL certificate, I’ve used the CA_BASE64 flag. If you are using a different LDAP server you may have a different type of certificate, I currently do not know how to work out which flag you will need for a particular certificate, there are a few and it may require trial and error to get the correct flag. You can find the options here: http://httpd.apache.org/docs/2.2/mod/mod_ldap.html#LDAPTrustedGlobalCert

    # Needed to do Subversion Apache server.
    LoadModule dav_svn_module modules/mod_dav_svn.so
    
    # Only needed if you decide to do "per-directory" access control.
    LoadModule authz_svn_module modules/mod_authz_svn.so
    
    Listen 80
    MaxKeepAliveRequests 0
    KeepAlive On
    KeepAliveTimeout 30000
    Timeout 7200
    
    LDAPTrustedGlobalCert CA_BASE64 /opt/ssl/orgldap.crt    # this is the certificate I saved in step 1
    
    <Location /svn>
        DAV svn
        SVNParentPath /opt/Subversion
        AuthType Basic
        AuthName "SVN LDAP Repo"
        AuthBasicProvider ldap
        AuthzLDAPAuthoritative on
        AuthLDAPURL "ldaps://dse01.qava.wandisco.com:636/cn=Users,dc=wandisco,dc=com?uid"   # note switched over to the ldaps protocol and port 636
        AuthLDAPBindDN "cn=Directory Manager"
        AuthLDAPBindPassword password
        Require valid-user
    </Location>
  3. Don’t forget to restart apache before trying to check out.

Active Directory

Similar to above, with the AuthLDAPURL, AuthLDAPBindDN and AuthLDAPBindPassword changed to reflect the different LDAP server, but there is no need to get the certificate. Unfortunately, client certificates in Active Directory are not supported by Apache (again see: http://httpd.apache.org/docs/2.2/mod/mod_ldap.htm at the SSL/TLS Certificates section), so we’ll need to add a line to stop apache from trying to verify the ticket otherwise this will not work. Don’t forget to restart apache after changing the subversion.conf file!

# Needed to do Subversion Apache server.
LoadModule dav_svn_module modules/mod_dav_svn.so

# Only needed if you decide to do "per-directory" access control.
LoadModule authz_svn_module modules/mod_authz_svn.so

Listen 80
MaxKeepAliveRequests 0
KeepAlive On
KeepAliveTimeout 30000
Timeout 7200

LDAPVerifyServerCert off   # Stops apache trying to verify the certificate

<Location /svn>
    DAV svn
    SVNParentPath /opt/Subversion
    AuthType Basic
    AuthName "SVN LDAP Repo"
    AuthBasicProvider ldap
    AuthzSVNAccessFile /opt/Subversion/authz-svn.authz
    AuthzLDAPAuthoritative on
    AuthLDAPURL "ldaps://pdc01.wandiscoqa.internal:636/CN=Users,DC=wandiscoqa,DC=internal?sAMAccountName"
    AuthLDAPBindDN "CN=Administrator,CN=Users,DC=wandiscoqa,DC=internal"
    AuthLDAPBindPassword P4ssw0rd
    Require valid-user
</Location>
Using AuthZ authentication:

This is the easy bit, generate your apache authz file and then place inbetween the <Location> </Location> tags the following directive:

AuthzSVNAccessFile /opt/Subversion/authz-svn.authz

swapping the path for your own.

LDAP Authorities and Other Users Checking out the Same Repo

Simply add multiple locations, such as /svn and /ldap, under which you can specify different types of authentication. Below /svn uses the apache passwd file for authentication, whereas /ldap uses ldap authentication plus an svn authz file for access control.

# Needed to do Subversion Apache server.
LoadModule dav_svn_module modules/mod_dav_svn.so

# Only needed if you decide to do "per-directory" access control.
LoadModule authz_svn_module modules/mod_authz_svn.so


Listen 80   # This can also be in your httpd.conf file
MaxKeepAliveRequests 0
KeepAlive On
KeepAliveTimeout 30000
Timeout 7200

<Location /ldap>      # so to do a checkout using this location do - svn co http://192.168.56.190/ldap/Repo1
    DAV svn
    SVNParentPath /opt/Subversion  # the actual filepath
    AuthType Basic
    AuthName "SVN LDAP Repo"
    AuthBasicProvider ldap
    AuthzLDAPAuthoritative on
    AuthLDAPURL "ldap://dse01.qava.wandisco.com:389/cn=Users,dc=wandisco,dc=com?uid"    #  ie. ldap://<host>:<port>/<user DN>?<user DN attribute>
    AuthLDAPBindDN "cn=Directory Manager"
    AuthLDAPBindPassword password
    AuthzSVNAccessFile /opt/Subversion/authz-svn.authz  # Access control file
    Require valid-user
</Location>

<Location /svn>   # to do a checkout using this location do - svn co http://192.168.56.190/svn/Repo1
    DAV svn
    SVNPath /opt/repo/
    AuthType Basic
    AuthName "SVN Repo"
    AuthUserFile /opt/WANdisco/apache22/conf/svn.passwd # the apache passwd file (created with htpasswd)
    Require valid-user
</Location>

6.11. Email notification

The mail notification system lets you connect Access Control Plus to an email gateway server. This enables it to send an alert email concerning important system events. It’s possible to add as many email gateways as you like, so that the loss of a single mail server need to result in the halting of notifications.

The following procedure shows you have to set up an email gateway.

  1. Log in to the Access Control Plus admin console. Click the Settings link.

  2. Click the Email Notifications bar.

    acp email
    Select email notifications
  3. Fill out the entry form for your gateway.

    acp email00
    Enter information
    IP/Hostname of SMTP Server

    Your email server’s address.

    SMTP Server Port

    The port assigned for SMTP traffic (Port 25 etc).

    Encryption Type

    Select your server’s encryption type: None, SSL (Secure Socket Layer) or TLS (Transport Layer Security). SSL is commonly used. For tips on setting up suitable keystore and truststore files see Setting up SSL Key pair.

    If you’re not familiar with the finer points of setting up SSL keystores and truststores we recommend that you read: Using Java Keytool to manage keystores.

    Authentication Required

    Show whether you need a username and password to connect to the server by entering either "true" or "false".

    User Name

    If authentication is required, enter the authentication username here.

    Password

    If authentication is required, enter the authentication password here.

    Sender Address

    Provide an email address that your notifications will appear to come from. If you want to be able to receive replies from notifications you’ll need to make sure that this is a valid and monitored address.

    Number of Tries Before Failing

    Set the number of attempts SVN MultiSite Plus makes to send out notifications.

    Interval Between Tries (Seconds)

    Set the time, in seconds, between your server’s attempts to send notifications.

  4. When you’ve entered all the details, click the Add button.

    acp email003b
    Add
  5. When a gateway is in place you need to add a list of email addresses to where Access Control Plus will actually send notification emails. Enter addresses on the Add destination entry field and click + Add.

  6. Before notifications can be sent, enable the service by ticking the Enable notifications by clicking the Enable notifications button.

    acp email004b
    Enable notifications

    You can reclick the button if you need to disable the feature, without removing or editing the gateway or destination settings.

6.11.1. Notifiable events

The following events currently trigger notifications when suitably configured:

  • InfoDiskMonitoringEvent

  • SevereDiskMonitoringEvent

  • VCSReadyEvent

  • Restart

  • FileReplicationScriptErrorEvent

6.12. Create a repository template

In Access Control Plus’s backend, you can manage and replicate the core password and/or AuthZ files. To do this you need to create a template that will contain the path location for these files, as well as a number of optional parameters. When set up, repositories that are added to Access Control can be assigned the template, telling Access Control Plus how to handle the repository’s necessary files.

If you configure repository templates to send files, the files are sent even if they are not linked to repositories.

To create a repository template:

  1. Log in to the admin console. Click the Settings link on the top bar.

    acp reptemplate000
    Settings
  2. Click the Repository Templates bar under in the Applications Settings, near the top of the list. Click the Create button.

    acp repotemplate00
    Create template
  3. Complete the small entry form:

    acp reptemplate01b
    Add information
    Name

    A useful label for the product to refer to this repository.

    Description

    A description of the template to help you distinguish from it from potential others.

    Type

    From the dropdown list select your SCM product: Git or SVN.

    Never change the Type of a repository template!
    Do not add Generators to a repository template for more than one Type of repository. If you have accidentally started to create the wrong Type of template, always Delete the template and start over.
  4. Click the Add button to save the entry form.

  5. The screen is parsed, your selection detected and a Generators dropdown list appears. From this dropdown you can select multiple user access assets:

    acp reptemplate01c
    Select user access
    SSH Key File Generator

    Transports SSH keys between nodes, read more

    Apache Password File Generator

    Transports Apache password files between nodes, read more

    SVN AuthZ File Generator

    Handles the AuthZ file (under SVN), read more

    GIT AuthZ File Generator

    Handles the AuthZ file (under Git), read more

    Check that you have just 1 of each type of generator
    Make sure that you create just 1 of each type of generator by navigating away and then back again. Click Remove to get rid of duplicate generators.

    For more information on how these files are managed and distributed see Generic File Replication.

  6. Enter the Target Location. Find location of generated file on target node. Absolute path.

    acp repotemplate4
    Enter the Target Location

    Click on Show optional parameters to see a number of extra entry fields. When you have completed the entries you need, click on the Update button.

  7. You can create any number of Repository Templates, reflecting how many separate collections of repositories you are running where each requires a different series of user management files.

    acp repotemplate03
    Create multiple templates
    Take care when creating repository templates with the same paths!
    We recommend that you do not configure multiple repository templates with identical files and/or paths. You can do this if your configuration consists of non-overlapping system restrictions. For example, you can use the Advanced features so that repoTemplateA only delivers to systems A, C, E and repoTemplateB only delivers to systems B, D, F.

6.12.1. Repository template configurations

The Repository Template section covers the configuration of a number of different template types that are used to integrate SVN or Git repositories into Access Control Plus.

List of template types

SVN Auth File Generator

This is used to generate SVN AuthZ files.

Don’t create more than 1 authorized_keys generator, it may cause AuthN or AuthZ failures.
If multiple templates deliver their generated file into the same file system location then only the last written file will apply.
The ability to have multiple generators of the same type, especially when the file to be delivered must be at a specific place in the file system (e.g. the "authorized_keys" file must be located in the ".ssh" directory of the account that GitMS/MSP are running as), is predicated on using the "Node limits" tunable property or using a pre-placement script to combine multiply delivered data-files.
repotemplate svnauth01
SVN AuthZ
Target Location

Final location of generated file on target node.

Common Repository Path Segment

Common path segment which will be removed from the repository location to determine it’s name in AuthZ file, e.g. /var/repos will cause /var/repos/my_repo to appear as my_repo in AuthZ file.

SVN SSH Keys File Generator

This section looks at the options available when setting up a repository template for SVN SSH Keys File Generator. This option generates SSH keys files to be turned into authorized_keys for SVN SSH access.

repotemplate sshkeygenerator01
Generate SSH keys
Name

A logical name, give to your File Generator.

Description

A description that you can use later to identify the purpose of your template.

Path to Svnserve

Path to Svnserve command (e.g. /bin/svbserver, or leave empty to run just as svnserve.)

Svnserve Root Path

Absolute path in the file system which is reserved as root (svnserve -r argument, in SSH keys file generator for SVN)

repotemplate sshkeygenerator02
Update template
SSHD option

SSHD options passed to the command (e.g. .no-port-forwarding,no-pty,no-agent-fowarding)

Node limits

Space separated list of node names to be excluded from (if preceded with '-' sign) or included in file replication.

Placement Policy

Specifies the conditional placement of generated files: 0 - create the whole path, 1 - skip if file is missing (default), 2 - skip if dir is missing, 3 - fail if file is missing, 4 - fail if dir is missing.

Pre Placement Script

Script at or under …​/gfr/bin/ that is to be executed before the placement of files takes place. Please refer to Pre-placement scripts

Post Placement Script

Script at or under …​/gfr/bin/ that is to be executed after the placement of files takes place. Please refer to 9.1.2 in the ACP Reference Guide for the full location

Apache Password File Generator
acp repotemplate sample
Apache password file generator

These settings set the target location of the AuthZ file and the common path segment of the SVN repositories:

Target Location

%l/conf/authz

Common Repository Path Segment

/opt/svn/

Git AuthZ File Generator
acp repo git authz file
Git AuthZ file generator
Name

A name for the Git AuthZ file.

Description

A brief description of the purpose of the file.

Target Location

Final location of generated file on target node. Absolute path.

Node Limits

Space separated list of node names to be excluded from (if preceded with '-' sign) or included in file replication.

Placement Policy

Specifies the conditional placement of generated files:

0

Create the whole path

1

Skip if file is missing (default)

2

Skip if dir is missing

3

Fail if file missing

4

Fail id directory is missing

Pre Placement Script

Script at or under …​/gfr/bin that is to be executed before the placement of files takes place. Please refer to Placement Scripts in the User Guide for a full location.

Post Placement Script

Script at or under …​/gfr/bin/ that is to be executed after the placement of files takes place. Please refer to Placement Scripts in the User Guide for a full location.

Git SSH Key File Generator
acp repo git ssh key02
Git SSH key file generator
Name

A name for the Git SSH Key file

Desc

A description that might help identify the purpose of the file.

SSHD options

SSHD options passed to the command, (e.g.

Table 2. Each option should be separated by a comma

no-port-forwarding

no-pty

no-agent-forwarding

no-X11-forwarding each option

Node Limits

Space separated list of node names to be excluded from (if preceded with '-' sign) or included in file replication

Placement Policy

Specifies the conditional placement of generated files:

0

Create the whole path

1

Skip if file is missing (default)

2

Skip if dir is missing

3

Fail if file missing

4

Fail id directory is missing

Pre Placement Script

Script at or under …​/gfr/bin that is to be executed before the placement of files takes place. Please refer to Placement Scripts in the User Guide for a full location.

Post Placement Script

Script at or under …​/gfr/bin/ that is to be executed after the placement of files takes place. Please refer to Placement Scripts in the User Guide for a full location.

6.12.2. svnserve.conf

'svnserve.conf' controls the behavior of the SVNServe daemon on a per-repository basis. It is located in the conf subdirectory of the repository, e.g. '/opt/svn/repo/conf/svnserve.conf'.

[general]
anon-access = none
auth-access = write
authz-db = authz
[sasl]

anon-access

Determines the access level for unauthenticated users. "write" allows all repository operations. "read" allows all operations except committing and changing revision properties. "none" allows no unauthenticated access. The default level is "read".

auth-access

Determines the access level for authenticated users, using the same access levels as above. The default level is "write".

authz-db

Controls the location of the authorization rules for path-based access control. filename may be relative to the repository conf directory. There is no default value. If you don’t specify an authz-db, no path-based access control will be set.

6.12.3. Server-side

The following configuration is required on the server:

  • Create an "authorized_keys" file at:

/home/wandisco/.ssh/authorized_keys
  • Change the permissions and ownership as follows:

chmod 600 /home/wandisco/.ssh/authorized_keys
chown wandisco:wandisco /home/wandisco/.ssh/authorized_keys
Client-side

The following configuration is required for clients:

  • If required generate SSH keys:

ssh-keygen -t rsa
  • Copy the SSH key to the server entering the password for the wandisco user when prompted:

ssh-copy-id wandisco@<ip address>
Client-side access

Access the repository using:

svn co svn+ssh://wandisco@<ip address>/repo
Adding additional entries to authorized_keys file

The authorized_keys file that we build can now work with additional entries, added by the user. These entries need to be created in one of two blocks; authorized_keys.prepend or authorized_keys.append.

Using both prepended and appended entries

These blocks, authorized_keys.prepend and authorized_keys.append can be used together, so that custom entries are written to both ends of the authorized_keys file.

Not replicated

This feature works an a per-machine basis, it is not automatically replicated to all servers. To implement a global policy you will need to set up a uniform deployment of the files to all MultiSite nodes.

Example

In the account .ssh directory on your MultiSite machine create a file called authorized_keys.prepend. It should look something like this:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCf/5GZcLFVbDSOV51RoLKgbi8afL9N5zl3Im6MA4MgXt67u5D43+UjeU4vjH6wUW5zGdhK2BWX820qQvCwCYJCL6oEG+Lv/jMu0NgenO/jKYgeDVx4wsffkVYcABsz55cPO+qsM/BSxY00RGEMroVEQhAGVQF++340VRrcZCe6O0vGwLgFrl+Thb0z9RuDzj+a+Swl99dhkKMS1wlAPl0HIUpBYdhtoEc9dnn+mPNUV9CKaPBq79ANJxYEsmPKxUolhuIQH9GNxsAC3v3pmffKVNdy0kLeK6htQ4LPqRd1zmLgq7fNtiFszYJNZk6c0efTEf0yjYUKZvWEu26fnGht appendUserKey@appendUserKey.local

In Access Control Plus, navigate to Settings → Access Control Updates → Generate Authorization Files

The authorized_keys file on your MultiSite node should now included the appended entries after those added automatically by Access Control Plus.

7. Troubleshooting

7.1. Problem: Replication runs very slowly while server load and traffic are both light.

Solution
It is possible that pending tasks are currently stuck and are therefore holding up further replication. To test if this is what is happening:

  1. Go to Settings/Node Induction.

  2. Check for any pending tasks.

  3. If you find that there are pending tasks then you should consider aborting them.

  4. Recheck replication to see if things improve (it can take a few mins for backlogs to clear)

8. Admin UI Reference Guide

Welcome to the Reference Guide for WANdisco’s Access Control Plus.

This section of the documentation provides a description of the admin UI, along with supporting information about how Access Control Plus work.

8.1. Installation directory structure

This shows the files installed as part of Access Control Plus:

/opt/wandisco/scm-access-control-plus
[wandisco wandisco]  ├── backups
[root     root    ]  ├── bin
[wandisco wandisco]  ├── config
[wandisco wandisco]  ├── content
[wandisco wandisco]  ├── database
[wandisco wandisco]  │   ├── application
[wandisco wandisco]  │   │   └── resettable.db
[wandisco wandisco]  │   ├── backup
[wandisco wandisco]  │   ├── DConE.application.db
[wandisco wandisco]  │   ├── h2
[wandisco wandisco]  │   │   ├── audit
[wandisco wandisco]  │   │   ├── enforced
[wandisco wandisco]  │   │   └── shadow
[wandisco wandisco]  │   └── recovery
[wandisco wandisco]  │       ├── application.integration.db
[wandisco wandisco]  │       ├── DConE.system.db
[wandisco wandisco]  │       └── DConE.topology.db
[root     root    ]  ├── docs
[root     root    ]  ├── flume
[root     root    ]  ├── gfr
[root     root    ]  │   ├── bin
[root     root    ]  │   │   └── acp
[wandisco wandisco]  │   ├── lib
[wandisco wandisco]  │   ├── log
[wandisco wandisco]  │   ├── tmp
[wandisco wandisco]  │   └── var
[root     root    ]  ├── lib
[wandisco wandisco]  ├── logs
[wandisco wandisco]  │   ├── recovery-details
[wandisco wandisco]  │   ├── tasks
[wandisco wandisco]  │   └── thread-dump
[wandisco wandisco]  ├── properties
[wandisco wandisco]  ├── tmp
[root     root    ]  ├── ui
[wandisco wandisco]  └── var
[wandisco wandisco]      └── watchdog

8.2. Properties files

The following files store application settings and constants that may need to be referenced during troubleshooting.

IMPORTANT
Do not make any changes to these files without consulting WANdisco’s support team.
-rw-r--r-- 1 root     root     1036 May  6 10:17 samples/application.properties.txt

Settings for the replicator and affects how Access Control Plus performs.

-rw-r--r-- 1 root     root     1514 Feb 26 10:00 samples/log4j.properties.txt

Properties that control how the log4j Logging library works.

-rw-r--r-- 1 root     root     1969 Feb 25 11:20 logger.properties

Defines how the product’s logging is handled.

-rw-r--r-- 1 root     root      185 May  6 10:17 user.properties

Stores the details of the primary administration account that is set up during the installation.

8.3. Logging

There are two logging systems running on ACP, firstly logger.properties which is used by DConE and contains the java.util.logging configuration. This file should not be changed.

The other logger uses log4j. We use it for application logging because it has a better range of functionality. See log4j.properties

8.3.1. Log files

The following log files are generated during operation:

-rw-r--r-- 1 wandisco wandisco     366 May  6 10:27 multisite.log

Records the use of the "scm-access-control-plus" application control script (normally executed via the "service" command).

drwxr-xr-x 2 wandisco wandisco    4096 May  7 10:27 recovery-details

Contains information about how the nodes are set up and connected to each other.

-rw-r--r-- 1 wandisco wandisco   23226 May  6 10:27 scm-access-control-plus.<time-date-stamp>.log

The main log file containing most application logging.

drwxr-xr-x 2 wandisco wandisco    4096 May  8 08:27 thread-dump

Contains any thread-dumps that might occur.

-rw-r--r-- 1 wandisco wandisco    3232 May  6 10:27 watchdog.log

Logs changes to the watchdog process that ensures that Access Control Plus automatically restarts if it unexpectedly shuts down.

8.3.2. java.util.logging

The logger fil will look like this:

# Properties file which configures the operation of the JDK
# logging facility.

# The system will look for this config file, first using
# a System property specified at startup:
#
# >java -Djava.util.logging.config.file=myLoggingConfigFilePath
#
# If this property is not specified, then the config file is
# retrieved from its default location at:
#
# JDK_HOME/jre/lib/logging.properties

# Global logging properties.
# ------------------------------------------
# The set of handlers to be loaded upon startup.
# Comma-separated list of class names.
# (? LogManager docs say no comma here, but JDK example has comma.)
handlers=org.slf4j.bridge.SLF4JBridgeHandler

# Default global logging level.
# Loggers and Handlers may override this level
.level=INFO

# Loggers
# ------------------------------------------
# Loggers are usually attached to packages.
# Here, the level for each package is specified.
# The global level is used by default, so levels
# specified here simply act as an override.

# Handlers
# -----------------------------------------

# --- FSFSFileHandler ---
# Override of global logging level
com.wandisco.fsfs.logging.FSFSFileHandler.level=ALL

# Naming style for the output file:
com.wandisco.fsfs.logging.FSFSFileHandler.pattern=fsfswd.%g.log

# Limiting size of output file in bytes -defaulted to 1MB:
com.wandisco.fsfs.logging.FSFSFileHandler.limit=1048576

# Number of output files to cycle through, by appending an
# integer to the base file name:
com.wandisco.fsfs.logging.FSFSFileHandler.count=500

# Style of output (Simple or XML):
com.wandisco.fsfs.logging.FSFSFileHandler.formatter=com.wandisco.fsfs.logging.FSFSLogFormatter

8.3.3. log4j

ACP uses a logging system called log4j. We use it rather than java.util.logging because it has a better range of functionality

We still need to provide a log file that contains the log output of DConE and the ALM product. We do this by bridging between java.util.logging and log4j. All the log output of java.util.logging is directed to log4j which writes out the log messages for DConE and the ALM application to a single log file. We use slf4j to do this : http://www.slf4j.org/

We also have log rotation , were we rotate to a new log file after it has grown over a size defined in the logrj.properties file.

Our log4j.properties file looks like this :

# Direct log messages to a file
log4j.appender.file=com.wandisco.vcs.logging.VCSRollingFileAppender
log4j.appender.file.File=fsfswd.log
log4j.appender.file.MaxFileSize=100MB
log4j.appender.file.MaxBackupIndex=10
log4j.appender.file.layout=org.apache.log4j.PatternLayout
log4j.appender.file.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss} %-5p [%c{1}:%M] - %m%n
log4j.appender.file.append=true

# Root logger option
log4j.rootLogger=INFO, file

Although you can edit this file, we do not recommend it. If you get it wrong then it will affect the format of the logs we get through our Talkback system.

If do need to make changes, the following parameters can be changed :

log4j.appender.file.File= < flog filename the customer wants >
log4j.appender.file.MaxFileSize= < max logfile size before rotation>
log4j.appender.file.MaxBackupIndex= < # log file rotations before we rotate back to the start >

8.4. Database fsync setting

It’s possible to configure ACP to prioritize either robustness or performance. Add the following property to the application.properties file:

acp.database.enable.fsync=true
true

(Default value) This makes the database operations more robust during a system outage with less chance of data lose.

false

If database speed is preferable then this feature can be turned off by setting the property to false.

Take Note
If you configure for performance over robustness then you will likely see divergence between the different node’s database of Accounts, Teams, Rules, etc. If you notice this then you would need to repair 1 or more nodes using the repair facility in the Node Repair tool under the Settings-Node Repair section. Given that multiple node databases could fall into different states we really don’t recommended choosing performance over correctness, for long term stability.

8.5. Admin Console master screen

Below is a screenshot of Access Control’s admin console master screen. From here you can see all the component parts of your access control setup, accounts, teams, repositories (when not assigned to templates), resources, and rules.

acp master01
Admin console

8.6. System stats

The System stats show the overall scale of the deployment. They appear if you click on System stats or the cog icon:

acp systemstats
System stats
Uptime: Replicator

The time that has passed since the Access Control Plus process was started.

Session length

The time that has passed since the current browser session was started.

Total teams

The current number of teams managed within Access Control Plus.

Total members

The total number of members (active and inactive).

Total resources

The total number of repository resources defined.

Total Rules

The number of rules created.

8.7. Settings

The settings screen gives you access to ACP’s various application settings.

acp settings mixed
Settings
License Type

The type of deployment. See Which mode is running?

License Expiry

The date on which the current license expires.

8.7.1. Application Settings

Access Control updates

The Access Control Updates panel stores the settings for the Batch Updates Mode which helps mitigate the effects on system performance from very large numbers of password file and or AuthZ writes. See Enable/Disable Batch updates for more information about how and why you should use the Access Control Updates.

Batch Updates

Use these settings to enable the Batch Update mode, which will benefit replication performance in large deployments.

acp accesscontrolupdates01
Batch Updates
Enable (Toggle)

Click the toggle button to enable/disable Batch updates.

acp accesscontrolupdates02
Enable
Switch Period

This is the frequency at which batched changes are applied to the AuthZ and or password files. The default frequency is once per 600 seconds (10 minutes), so by default Access Control will never wait more than 10 minutes before applying an Access Control change.

Access Control Plus will not create and deliver a new set of AuthN/AuthZ files unless something is changed during the period. However, see below on how to force-generate and deliver a new set of files.
Managing Node

This is the node that you select to manage the Batch process. Batched changes are collated and stores on just one node (this Managing Node) and then applied to all nodes on the next batch update.

Batch Actions

Batch Actions gives you immediate control over Batching.

Run Now

Run a batch update immediately.

Generate Authorization Files

Click to force the creation and delivery of a new set of Authorization files.

The managing node for Git MultiSite and/or Subversion MultiSite Plus must be set or else generated files will not be delivered.
Pending Changes

The Pending Changes table will list all those changes that are waiting for the next batch update in order to take effect.

Due to browser caching, sometimes the entries in the Pending Changes table will be out of date. Please force-refresh this page (shift refresh) in order to verify what actual pending operations exist.

8.7.2. Repository templates

The Repository Template options are used when connecting new SCM repositories to Access Control Plus. A repository template stores the paths for the repositories authentication and authorization files that are used by the Generic File Replication scripts to ensure that changes on each node are synced to all other nodes.

acp reptemplate01c
Repository templates - Git
Name

Name that you wish to associate with the template.

Description

A brief description of what the template will be used for.

Type

SCM system type, SVN or GIT.

Generators
  • Git/SVN SSH Keys File Generator

  • Apache Password File Generator

  • Git/SVN Auth File Generator

acp reptemplate02c
Repository templates - SVN
You create a template for either Git or SVN
We recommend that you do not edit the Type of the template in future because this could result in you overwriting the original. We recommend that you create one repository template for Git and another one for SVN.

8.7.3. Global downcasing

Access Control Plus needs to handle situations where the customer’s Active Directory/Windows-based systems are maintaining user accounts that are case-insensitive, i.e. account "jsmith" and "JSmith" are considered the same account. ACP treats account names as case sensitive by default. In summary, the manner in which ACP handles "case insensitivity" is via "downcasing" all account names before comparison (and storage).

Enable Global Downcasing to ensure that Subversion users have their usernames forced into lowercase. This ensures consistency and protects against the possibility of AuthZ rules being applied incorrectly.

acp downcase01
Global downcasing

By default Global Downcasing is disabled and accounts are all considered case sensitive.

acp downcase02
Confirm enable

Enabling Global Downcasing triggers a warning message:

Enabling the global account name downcasing setting requires adjustment of VCS access paths to properly handle authorization. Inappropriate settings may incorrectly grant or deny user access to repositories.
If you downcase usernames using the Apache directive AuthzForceUsernameCase, you must make sure no case-sensitive users will pass Authn for this location. If you mix sensitive/insensitive users, you will need to define a separate location for each of them. See more about AuthzForceUsernameCase in mod_authz_svn Configuration Directives.
acp downcase03
Beware of possible user duplication with downcasing:

Please be aware of the following situation concerning the use of downcasing:

User bjensen and then the team(s) associated with that user get removed from ACP. The user will appear in the Accounts section as "bjensen".

If downcasing is not enabled and we then create a new team and pull this user in again (and the username on LDAP is BJensen), there will now be 2 users in the account section; bjensen and BJensen. In order to be able to Global downcase the user BJensen, the administrator should manually remove the user bjensen.

8.7.4. Edit Local Node Settings

The Edit Local Node Settings panel lets you modify node properties any time after the node has been setup and inducted.

acp editlocalnodesettings01
Local node settings
Node Name

The Node’s given name.

  1. When Access Control Plus is used in a replicated setting the following DConE Port entry field also appears.

    DConE Port

    The TCP port used for handling the DConE coordination traffic.

8.7.5. Managing nodes

This section describes how the Access Control Plus nodes work when connected together.

Node Induction

Induction refers to connecting nodes together to form a distributed system for replicating data. Nodes that are connected together form a membership that is governed by the requirements of the distributed system. One requirement is that there must be a minimum number of nodes (a quorum) available to agree on the ordering of replicated changes.

There may be insufficient nodes to create agreement, for example, if enough nodes are lost because they are disconnected or experiencing unrecoverable failure. Quorum is then lost and replication stops. On the Node Induction screen you see the warning: ACP operations currently impossible - Quorum is unavailable.

lostquorum b
Node indcution

In this situation it may be possible to run through an Emergency Reconfiguration - please contact WANdisco Support.

8.7.6. Node repairs

The Node Repairs tool allows you to get ACP data around Repositories, Resources, RepoTemplates, Teams, Rules, Accounts, etc. back into sync.

acp repair01
Node repairs
Location Identity

The unique ID string that is used by the replication system to identify the node.

node.name

The name given during installation that is used to identify the node to humans.

eco.system.membership

A unique identifier for the replication network in which the node is operating.

eco.system.dsm.identity

This identity is used to distinguish the specific distributed state machine. These attributes are only important if you need to troubleshoot replication problems.

Emergency Reconfiguration

The Emergency Reconfiguration tool allows the administrator to remove a downed node from membership. This allows the remaining nodes to continue to replicate using a new membership. Membership type depends on the number and type of remaining nodes.

Important: Don’t attempt an EMR without help
In the event that you need to perform a permanent removal of a node (an emergency reconfiguration) then you should contact WANdisco’s support team for assistance. The operation poses several risks to the overall operation of Access Control Plus. Therefore, we recommend that you do not attempt the procedure by yourself.

8.7.7. External applications

8.7.8. File Generation

When ACP is run in Standalone mode, this section includes a File Generation settings screen.

acp settings filegeneration01
File generation
File Generation

Manages properties that apply to the Generic File Replication GFR system.

Managing Node

Select the node for managing file generation.

Enable Wildcards

Tick the checkbox to enable Wildcard support.

Once enabled you can’t disable
Be warned that enabling Wildcard support for the File Generation system can not be undone. Should you need to disable Wildcard support you will be forced to reinstall ACP.
acp settings enablewildcards01
Conflict strategy
Conflict Strategy

We default to wildcards OFF and Conflict Strategy is set to Low Priority (Lowest Wins). Once wildcards is turned ON, we send round a proposal to get agreement from all other nodes and then auto turn on the High Priority Highest Wins strategy. It can take some time to occur though as we reach node agreement so its possible that the admin would need to refresh their page before the policy shows as set within the UI.

Generation Number

Displays the accumulating Generation count number. If you need to start the count again, click the Reset Generation Number button.

8.7.9. Connect to LDAP

Settings for connecting ACP to an LDAP service for managing users and access.

acp settings connectoldap
Connect to LDAP
LDAP Settings
acp settings connectoldap02
LDAP settings
Do not set the period too low, or to zero.
You shouldn’t need to constantly hit your LDAP authority. If you have a large deployment, synchronization will be resource hungry.
If you perform an import from an earlier version of Access Control you must ensure that Access Control Plus does not poll the LDAP authorities during the process. You can do this by setting the Synchronization Period to 99999 (minutes) just for the duration of the import.
Allow Local Users (Checkbox)

This checkbox is ticked by default. When ticked it is possible to field both LDAP-controlled and manually entered Accounts. Some organizations don’t permit manually entered accounts because they need to be sure that all accounts are managed through their LDAP. If this is the case, untick the checkbox when your LDAP accounts have been successfully imported and you have promoted multiple LDAP accounts to be administrative (since local administrative accounts will be disable too).

If you are running with Local Users disabled and your LDAP service fails, you can re-enable local users as part of the account password recovery process. This process automatically re-enables local users, allowing you to gain access to the admin console via a newly created local administrative account.
LDAP Authorities
acp settings connectoldap03
LDAP authorities

List of connected LDAP authorities.

Add LDAP Authority

Entry fields for adding LDAP (see Add LDAP Authority):

acp settings connectoldap04
Enable LDAP

8.7.10. Email Notification

Email notification settings. See Email Notification

acp settings email notification
Email Notification

8.7.11. Connect to MultiSite

Settings for the connected SVN MultiSite Plus node or Git MultiSite node.

acp connect multisite02b
Settings

Use the external applications settings to connect with MultiSite products (Git MultiSite and / or SVN MultiSite).

API IP

The IP for the application’s server.

API Port

The port used by the API (and the applications User Interface).

API User

The application user account that is used by Access Control Plus to connect to the external application.

Password

The password for the account that is used by Access Control Plus.

Managing Node

The Access Control Plus node that will handle the communication with the external applications.

Poll Period (seconds)

The frequency with which Access Control Plus connects with the external application.

Use SSL (Check box)

Tick the checkbox to use SSL encryption for the traffic between Access Control Plus and the external application. If using SSL you must configure the SSL configuration parameters via the application.properties files setting (see Enable SSL).

acp connect multisite01
Enable Wildcards
SVN Only
Subversion MultiSite settings provide settings for enabling but not disabling Wildcards support.
Enable Wildcards

See Enable Wildcard Support.

Once enabled you can’t disable
Be warned that enabling Wildcard support for the File Generation system can not be undone. Should you need to disable Wildcard support you will be forced to reinstall ACP.
acp settings enablewildcards01
Enable Wildcards
Conflict Strategy

We default to wildcards OFF and Conflict Strategy is set to Low Priority (Lowest Wins). Once wildcards is turned ON, we send round a proposal to get agreement from all other nodes and then auto turn on the High Priority Highest Wins strategy. It can take some time to occur though as we reach node agreement so its possible that the admin would need to refresh their page before the policy shows as set within the UI.

8.8. Teams

The Teams panel lists all the ACP teams that have been set up.

ref teams02
Teams
Members

Number of accounts associated with the team

Subteams

Number of Subteams

8.9. Accounts

The Accounts panel lists all connected accounts.

ref accounts
Accounts
Type

Type of account. Local accounts are imported from a file or entered into the ACP admin screen. LDAP-based. accounts are added using LDAP queries.

Rules

Number of rules that apply to the account.

8.9.1. Repositories without templates

Lists all available SCM repositories.

ref repositories
Repositories
Name

Lists names of available repositories from either associated SCM system, SVN or Git. Before a repository can be applied you need to assign a template, click Assign template.

8.10. Resources

Lists available SCM repositories that have been applied to ACP using a template. See Create resources.

acp resources
Resource

8.11. Rule Lookup

  1. Click the Rule lookup link on the top menu bar.

rule lookup1
Rules lookup
Account name

The name of the account that you want to investigate

Repository name

The name of the repository that you wish to test against

Resource path

The file system path to a specific part of the repository.

  • To check the whole repository leave this field as None.

  • To specify a path, select SVN Path for SVN repositories or Git Branch/Git Tag for Git repositories.

Permissions

Those access permissions that apply to the selected account, for the selected repository resources will be listed in the Permissions table. For more information on permissions, see Create a rule.

Click the Lookup button to start the search. All rules that apply to the account for the specified resources are displayed in the Permissions table. See Using Rule Lookup.

8.12. ACP UI User Access

ACP Users who are not assigned Admin permissions can login to the ACP UI to take a limited number of actions.

acp user login
User access

The user can edit their entry details by clicking on the View/Edit link, if their account is "local". They cannot do so if the account has been polled from LDAP.

Last Repo Access

Reports the last repository that the Account user accessed.

Last Access Time

Time of the Account user’s last repository access.

Change Password

Allows the user to change their account password, (if the account is local - not available if the account is LDAP). See Password change/recovery

Add or Delete Public Key(s)

Allows the user to add or remove public SSH keys associated with the account. See Adding public SSH keys.

Rule lookup

The user gets access to the Rule lookup tool.

9. Deployment modes

Access Control Plus supports many different configurations that dictate its use. When installed, your license key tells Access Control Plus which features to expose.

9.1. Available modes

The following Modes are available:

  • Standalone: One or more nodes deployed at one or more sites. Standalone mode still supports the replication of Access Control data. However, without the MultiSite products you wouldn’t be able to reliably support far-flung development teams that collaborate on the same repository data. Each instance of Access Control would manage their local repository data. Generated password/AuthZ files are stored directly on the Access Control nodes.

SVN only
Currently the standalone mode is only available for SVN deployments.
  • GitMS (with Git MultiSite): One or more nodes deployed at a one or more sites in conjunction with WANdisco’s Git MultiSite product.

  • MSP (with SVN MultiSite): One or more nodes deployed at a 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.

9.2. Which mode is running?

To check which mode your installation is currently in:

  1. Log in to Access Control Plus.

  2. Click the Settings link on the top menu bar:

    acp mode01b
    License type

    On the side menu you can see a reference to the License Type. The example shows Standalone which means that it is set up to work with SVN and is only concerned with the local SVN server. It might show both where both Git and SVN are running, or, it might instead show "Git & SVN MultiSite Plus", which would mean that the installation is configured to support both Git and Subversion repositories within a replicated environment.

9.3. Batch updates mode

Many operations in Access Control Plus require that the AuthZ and SCM password files are regenerated. In a rapidly changing SCM environment, the number and frequency of account, team and rule changes can degrade performance of both ACP and whatever other WANdisco ALM products it connects to. This can consume both Disk I/O as well as CPU an networking resources.

We strongly advise the use of the Batch updates feature.

Changes are not instant
When Access Control Batch updates is enabled, changes to accounts, teams, SCM resources or rules are not quickly available. In order to see the actual current state (excluding changes that will only take effect after the next scheduled password/AuthZ rewrite) you need to use the Current View. The Current view is intended for troubleshooting, where you need to see the state of accounts/teams/rules, etc. that match the latest delivered AuthN/AuthZ files.
batchmode
Batch mode

When Batch updates is enabled, all Access Control Plus changes that would result in a regeneration of the password or AuthZ files (see the list below) are batched rather than updated for each individual change. Default is 600 seconds (10 minutes). This should be set to the largest tolerable period of time (e.g. 1 hour). For large implementations (in terms of nodes, accounts, repositories, etc.) the period should not be less than 5 minutes.

Access Control changes that can be batched are:

  • Create/delete users

  • Create/modify/delete teams

  • Create or modify rules (apply a change to access permissions for either a individual users or teams)

Changes to LDAP Authorities do not trigger password/AuthZ file rewrites.
However, when an authentication authority is polled for updates, any resulting user or team changes do trigger rewrites as of the next batch update.

9.4. Pending view vs current view

When batched updates are enabled you can view the admin console in two modes:

Pending view:
The admin console presents a view of Access Control that includes objects (users, teams and rules) that are not yet enforced, because they are waiting to be applied in the next batch update. This is the mode you use to make any access control changes, which are immediately added to the current waiting batch. Pending view actually shows you how access control will be applied when the current batch has been updated. This makes it difficult for troubleshooting and testing, where you would only want to see objects as they are actually applied to users here and now, via the delivered AuthN and AuthZ files.

Current view:
Using Current view allows you to look at Access Control with all pending changes filtered out. This is specifically for troubleshooting and testing. Most Access Control creation or edit tools are disabled. It is not useful to create Access Control objects (users, teams or rules) in this mode because you will not see pending changes and therefore could create incorrect or conflicting changes.

  1. Make changes.

  2. Navigate to Settings → Access Control Updates.

  3. Click Run now.

Note: Turning off batch mode could cause severe issues if batch mode is required for any of the reasons already described.

To change between Pending view and Current view, toggle between them from the admin tab. See next section.

9.5. Enable current view

Current View excludes any changes that are still waiting in the next batch update. To use the current view:

  1. Log in to the admin console.

  2. Click the Account drop-down menu in the right-hand corner of the screen.

    acp ref enforced01
    Account drop-down
  3. Click Current.

    acp ref enforced02
    Select current mode
  4. The admin console’s top bar changes color and a "Current" symbol appears next to the Access Control Plus logo. This reminds you that you’re currently in the Current view.

    acp ref enforced03
    Current view
  5. To leave the Current view click Pending.

10. Wildcards

The Deployment Guide describes how to install ACP and enable wildcard support.

Note
You only have the option to deselect the Use wildcards checkbox before you save changes to the resource you have added. However, this is only likely to be required if you, extremely rarely, need to use the asterisk as a non-wildcard (normal) character.

10.1. How the wildcards work

With Subversion 1.8 you can use the following wildcards with directory entries, "DE" (files, directories, symbolic links):

  • To match one DE: *
    For example:

    1. To match all directory entries in the branches directory: /branches/*

    2. To match all DEs in the tags directory: /tags/*

    3. To match all directory entries named "Makefile" in all top-level branch directories: /branches/*/Makefile

  • To match zero or more DEs: **
    For example:

    1. To match all directory entries called "Makefile" anywhere in the repo: /**/Makefile

    2. To match all directory entries called "Project" below the "Red" branch: /branches/Red/**/Project

  • To match any directory entry starting with “Text”: Text* For example, to match all directory entries in the branches directory starting with "project": /branches/project*

  • To match any directory entry ending with “Text”: *Text
    For example, to match all directory entries in the branches directory ending with "private": /branches/*private

10.2. Working with Rules

You can create a new rule or edit existing rules.

  1. Rules for the same repository and identical path extension collapse into a single section.

  2. Sections at the same priority sort by:

    1. Sections for repositories are supported by repository name in strict <character-set> order.

      1. Shorter paths sort before longer paths where:

        1. Wildcard "sort-specific path subset" is the shortest path that includes no wildcards (e.g. "/a/b/c/" in "/a/b/c/*.suffix").

        2. Wildcard rules with matching "sort-specific path subset" sort via strict <character-set> sort on the remaining path segment (e.g. "/a/b/c/.suffix") after "/a/b/c/README.") with the caveats:

          1. The wildcard character itself, *, always sorts before every other character in the <character-set> being used.

          2. If the * is not a wildcard then it sorts in its normal location within the <character-set>.

        3. Wildcard rules sort before non-wildcard rules.

  3. Sections at higher priority sort after sections at lower priority and vice versa.

Note
If the wildcard flag is not set then the entire rule must be treated as a non-wildcard so the * is sorted based on <character-set> order only. Priority is still observed.
Note
  • The section header must start with :glob: for wildcards to be honored. All asterisks within that section are considered to be wildcards.

  • Sections without wildcards can have :glob: but with no effect.

  • Sections without :glob: with asterisks (‘*’) mean non-wildcard/literal.

    For example:

[:glob:repo:/path/*]
@group1 = rw

is a wildcard reference while:

[repo:/path/*]
@group2 = r

is NOT a wildcard reference

10.3. Create a rule for all .xml files on a branch

You might want to stop users writing to XML files. For example, …​

to create the rule to deny write access:

  1. Make sure that you have refined a resource within a repo.

  2. Go to the Rules page.

  3. Add /branches/myBranch/**/*.xml" as a Path. Because asterisks are used in the pathname then Use wildcards is automatically checked.

    wildcards refined
    Add path
  4. Click Save selection. If there are wildcard conflicts, the save fails and you are asked to Confirm that you want to create the rule.

    wildcards conflictmessage
    Save
  5. If you confirm that you want to create the rule, even though there is a priority conflict between this new rule and an existing one, then the rule is saved. The priority chosen for the rules in conflict will depend on the global setting for conflict resolution, by default set to "Highest Wins". The conflict is then included in the count shown on the page header.

You are returned to the Team page.

10.3.1. Create a rule for a specific file on all branches

You might want to stop users committing to a specific file on all branches. For example, to create the rule to deny write access:

  • Follow the steps above but add branches/*/secret.txt as a *Path*.

10.3.2. Create a rule for intermediate directories

You might want to stop users committing to a group of files. For example, to …​

To create the rule to deny access:

  • Follow the steps above but add /branches/myBranch/**/private as a Path.

10.4. Setting priorities

To enable policy via wildcards you can specifically order certain wildcard sections before others. To enable this in ACP, each repository path refinement has an associated priority. The priority value ranges between -9 and +9. Default is 0 (zero).

Most rules should not require priority adjustment.

Rules for the same repository and identical path refinements collapse into a single section. Sections for repositories plus path refinements are sorted in strict <character-set> order (see above):

  • Conflicts are created by Team Leads or Administrators replying "Continue" to "Do you really want to do this?".

For example:

  • TeamAlpha with a Priority 0 rule "repo1:/a/\**"

  • TeamZed with a Priority 3 rule "repo1:/a/\**"

both collapse to a single rule in the AuthZ file:

[:glob:repo1:/a/**]
@TeamAlpha = r
@TeamZed = rw

This section sorts with Priority 3 sections after sections with priority 2 but before sections with 4 (not priority 0).

10.4.1. Set priority for resources within rules

You can set a priority from -9 to +9 (0 is default) for every Subversion resource within every rule.

Note

At any time, you can change the priority for Subversion resources from the Rules page.

  1. Set the priority of a resource on the Rules page.

  2. Click Save selection.

10.4.2. Wildcards conflict

Critical conflict interactions occur where there is:

  • Direct matching: If a section matches a directory then the permissions associated pertain to the entire directory tree, unless other parts of the tree are directly matched by another rule. However: the "" atom directly matches every single directory entry at or below directly. In general, a rule need not match every directory entry directly since inheritance from a directory above it will normally suffice. Therefore, minimize the use of the "" atom.

  • Buried access: If a wildcard pattern enables "r" or "rw" rights to a directory entry, but that directory entry is below a directory with no rights, then SVN allows direct access if explicitly requested. For example:

[repo1:/a/b]
@group =

[repo1:/a/b/c]
@group = RW

Then direct access works if the path is known:

svn ls http://myserver/svn/repo1/a/b/c
Example Solution

[repo1:/trunk/secret] @group =

[repo1:/**/Makefile] @group = RW

[repo1:/**/Makefile] @group = RW

[repo1:/trunk/secret/**] @group =

Makefiles everywhere are accessible

Makefiles are accessible everywhere except within the /trunk/secret tree. @group =

10.4.3. Resolving conflicts in resource priorities

If a conflict is detected while creating or editing a rule then you see a message:

These changes will create priority conflicts. Are you sure you want to continue and create priority conflicts?

Click Continue or Cancel.

Wildcard conflicts are counted in the page header by Priority Conflicts.

Click Priority Conflicts to display:

wildcards priorityconflicts
Priority Conflicts

Alternatively you can run an API call conflict/conflictsreport which then lists:

  • Details of one rule

  • Details of the second rule

  • Repository details

  • Whether wildcards are enabled

The report of priority conflicts will depend on the privileges of the account running the report. Administrative accounts can see them all. Team leaders can only see rules that they have rights to see (not rules in other teams where they have no rights). Ultimately it might take an administrator to resolve a conflict dispute.

10.4.4. More Examples

Trailing ** above

Consider the following AuthZ snippet:

[:glob:ourRepo:/branch/**]
@group1 = rw

[ourRepo:/branch/secret]
@group1 =

group1 gets read/write for the path /branch/secret/source and for everything in /branch/secret but no rights for /branch/secret. So a checkout from “/” won’t get secret but a direct checkout of /branch/secret/private works, which a good reason to limit the /** wildcard.

Trailing ** below

Consider the following AuthZ snippet:

[ourRepo:/branch/secret]
@group1 = rw

[:glob:ourRepo:/branch/**]
@group1 =

In this case group1 members are completely out of luck since "/branch" itself and the entire subtree is directly matched and they are given no rights. Even if the rules were reversed this would not be good since they would then only have read/write rights to the "/branch/secret" directory but nothing in it or below and they would not see it on a checkout from "/".

Again, really need to be careful when using the ** wildcard rules.

* vs **

Consider:

[:glob:myRepo:/branch/*]
@team1 =

[:glob:myRepo:/branch/**]
@team1 = rw

The result is that team1 has read/write on /branch and below because the last matching wins

10.4.5. Resolving Conflicts

To resolve conflicts you need to compare priorities. Either:

  • Team leads can change the priority of their own Team’s rule.

  • Administrators can change priority of any rule.

Then:

  1. Select the Rule.

  2. Change the Priority.

  3. Click Save.

11. Auditing

ACP Application administrators can check when accounts were last active within the repositories by looking up the account in the UI and then clicking Edit. The last access, either READ or WRITE, is shown. If the date displayed matches the Linux date epoch (e.g. 1970-01-01T00:00:00 GMT) then the account has never accessed a repository. Note that the epoch changes based on the timezone of the ACP server process.

The auditing data stores the latest access time, and whether the access was a READ or WRITE, for each account known to ACP for each repository that the account has accessed. Access history is not stored. You can query the data from ACP by using the appropriate REST API calls, see the RESTful API Guide. Custom reports can then be constructed.

Note: Audit does not report SVN commits using file://
Commits over file:// do not generate anything in the logs that auditing monitors. This means that nothing is sent to the auditing mechanism to report to the user.

For information about the installation of the auditing function and Flume see Install auditing.

The Flume agents are located where you installed them, either when installing Git MultiSite or Subversion MultiSite Plus or Access Control Plus. They default to being installed into /opt/wandisco. The Flume sender does a tail -F on the appropriate log file(s) and sends log messages to the Flume receiver. The Flume receiver processes the data streams from the Flume sender, determining via regular expressions the data necessary to forward on into Access Control Plus. WANdisco supplies regular expressions that will match normal log file entries. If you have changed your log file entries, for instance by changing how and where Apache logs information, then you may need to modify the regular expressions in the Flume receiver configuration files.

The log messages contain user name, time of access, repository name and access type ('read' or 'write'). Every time Git or Subversion is accessed the auditing events are sent from the Flume sender to the Flume receiver. The Flume receiver caches the records, discarding all but the most recent record and then periodically sends the data into Access Control Plus.

12. Authorization and Authentication file delivery

WANdisco’s replication technology has mostly been used to replicate repository data between nodes, using Generic File Replication. The GFR script uses the system to replicate other kinds of files. Currently these are the files that are used to coordinate changes in Access Control and repository management between nodes. Access Control Plus sends an archive of files (can contain multiple Authz, git Authz, passwd, git authorized keys, etc.) and a set of instructions about where to put all these files. The locations are defined by the administrator during the setup of the Repository Templates (all as defined by the repository templates). Then the scripts unpack the files and place them according to the instructions. There are some advance parameters for templates, which let you specify certain nodes to skip, or to place only on given nodes, and also to call a script before placement (which can trigger skip) and after.

The Generic File Replication script handles the final delivery for AuthZ and Password changes. Customers modifying this code assume all responsibility for the execution of it. Contact WANdisco support for more information.

To receive notification of GFR failures, you must configure email notifications correctly on all Git MultiSite and Subversion MultiSite Plus nodes.
Currently the API only returns the success or failure of the node that ACP is directly connected to. Therefore, you need to configure email notifications correctly on your WANdisco product.

12.1. ACP Placement scripts (for GFR)

Access Control Plus comes with some GFR scripts that are used exclusively in standalone mode. The GFR scripts that are used to manage MultiSite Access Control are supplied in separate packages:

SVN MultiSite GFR

ACP-GFR-svn-<major>.<minor>.<patch>.<release_candidate>-<4-digits-of-build>-installer.sh

E.g.

  • ACP-GFR-svn-1.7.4.1-0100-installer.sh

Git Multisite installer (acp-gfr-scripts-git-installer.sh)

ACP-GFR-git-<major>.<minor>.<patch>.<release_candidate>-<4-digits-of-build>-installer.sh

E.g.

  • ACP-GFR-git-1.7.4.1-0100-installer.sh

Install the corresponding package on each SVN MultiSite Plus / Git MultiSite node. Each package is available as an rpm, debian package, and .sh shell script.

12.2. Placement scripts

The pre-placement and post-placement scripts are passed the following arguments:

  • ARGV[1] = path to temporary file that is about to be delivered

  • ARGV[2] = path to final destination of file to be delivered

The following restrictions apply to the pre-placement or post-placement script names as they are configured in the repository template:

  • The template can only have a single entry which is the partial path, or leafname, of the script to be invoked.

  • There can be no arguments.

  • There can be no quoting, neither single nor double quotes.

Regarding the account/group identity that the pre and post-placement scripts are run as:

  • The scripts are run using the same account as the connected product (GitMS or MSP) is run as.

  • The scripts have the same primary group as the connected product (GitMS or MSP) is run as.

The current working directory of the pre and post-placement scripts is …​/gfr/tmp. See the location of the gfr directory specified in the Pre-placement section, below.

12.2.1. Notes

  • The pre-placement script is normally used to modify the contents of the temporary file so as to customize the delivered contents. The contents of the temporary file are atomically moved into the operational location when the pre-placement script exits 0 (zero). If the pre-placement script exits anything other than 0 (zero) then this is taken as failure and the delivery is aborted.

    Atomic delivery is accomplished via the rename(2) system call after having copied the data into temporary file in the final location directory. In this way there are no race conditions between the prior file and the fully instantiated newly delivered file.

  • The post-placement script is normally used to do notification of the delivery. The post-placement script should not modify the contents of either of the files pointed to by the arguments.

    Modifications made by the post-placement script present race conditions to the agents that need to interpret those files. For the AuthZ files this might be Apache, svnserve, GitMS, etc. For AuthN files this could be SSHD or Apache. In any case these race conditions can and will cause unexpected failures in your environment and are easily avoided - use a pre-placement script to make any changes.

12.2.2. Pre-placement directories

The pre-placement scripts for the authorized_keys and password files must be located within the appropriate gfr directory for the type of SCM being delivered to. There are 3 options:

Table 3. Pre-placement script comparison
Repository type License type Location Default

SVN

Standalone

ACPInstallDirectory/gfr/bin

/opt/wandisco/scm-access-control-plus/gfr/bin

SVN

MultiSite Plus

MSPInstallDirectory/replicator/gfr/bin

/opt/wandisco/svn-multisite-plus/replicator/gfr/bin

Git

Git MultiSite

GitMSInstallDirectory/replicator/gfr/bin

/opt/wandisco/git-multisite/replicator/gfr/bin

12.2.3. Pre-placement script exit values

The delivery behavior depends on the pre-placement script’s exit value:

  • '0': Delivery of the file continues to use the current file contents

  • '101': Delivery of the file is skipped and no notification occurs

  • '>not 0' or '101': Delivery of the file is aborted and failure notification is attempted. In this situation, the exit value of the post-placement script is ignored since the delivery has already happened.

12.2.4. Example Pre-placement script

This pre-placement script lets you overcome the limitation of having a single authorized_keys generator. The key principle is that each generator is represented by a UUID that does not change from delivery to delivery:

#!/bin/bash --noprofile

# keep a record of each template's keys
# then sort -u them all together into the "$1":

set -e

myname=${0##*/}

myfile="$1"
myfile="${myfile%%/authorised_keys_folder*}"
myfile="${myfile##/*/}"

mydir="$1"
mydir="${mydir%%/../*}"
mydir="${mydir%/*}/tmp/authkeys"

mkdir -p "${mydir}"
sed -e 's:svnserve -t:svnserve --log-file /opt/repo/SvnServe.log -t:' "$1" > "${mydir}/${myfile}"

tf=${myname}.$$

APPEND=~/.ssh/authorized_keys.append.combo
PREPEND=~/.ssh/authorized_keys.prepend.combo
if [[ -f "${PREPEND}" ]]; then
    cp "${PREPEND}" $tf
else
    touch $tf
fi
sort -u "${mydir}/"* >> $tf
if [[ -f "${APPEND}" ]]; then
    cat "${APPEND}" >> $tf
fi
mv $tf "$1"

exit 0

12.3. acpLockAndRun Script

The "acpLockAndRun" script is part of the GFR packages that install with GitMS and MSP. It is used to prevent parallel updates to the delivered files. It also prevents hangs by having a built-in timeout.

12.3.1. Timeout

  • If the timeout is hit then it will kill off any delivery scripts in progress. The default timeout is 20 seconds.

  • In certain circumstances (e.g. very large number of SVN repositories using "svnserve" access) the actual delivery can take longer. ACP GFR 1.9.0 (and beyond) enables a configuration file to override the built in 20-second timeout with a user specified value.

The configuration file is not required. If it exists it will be read. The configuration file must be located here:

Use exact name/spelling:
.../gfr/etc/acpLockAndRun.conf

Comments starting with a hash character ('#') are ignored within the file. Blank lines are ignored. Currently the only configurable value is "GFRTIMEOUT". An example entry would be:

GFRTIMEOUT=60

The default value for GFRTIMEOUT is 20 seconds.

12.3.2. acpLockAndRUn.conf in Large deployments

If your implementation has a vary large number of AuthN or AuthZ files that need to be delivered then you may timeout. If this happens you will see errors to the effect of "message='acpLockAndRun: Error: Received signal ALRM, sending SIGINT to PGRP 32707 and exiting"_ in your GitMS and/or MSP log files. To work around this increase the timeout.

Recommended Timeout Limit
Do not set this timeout to more than 1 minute without contacting WANdisco support.

12.4. Generic File Replication log rotation

The version of GFR that ships with ACP 1.9.0 does not require GFR log rotation (it is now built in). If you previously had installed GFR file log rotation via the "logrotate" facility you should now remove those settings. More details in the ACP 1.7 User Guide - 9.1.5 Set up GFR log file rotation.

13. Configure the repository template

When configuring the repository template, note that the relative path fragment configured into the repository template for the script (both pre- and post-placement) will be pre-ended with the path, defined in the section GFR Pre-placement directories, above.

example:

You might locate all of your placement scripts inside of a directory called "myCompany". With this policy you would fill in the pre-placement relative path with "myCompany/preplacement" and the post-placement relative path with "myCompany/postplacement". The actual location of the script is determined as shown in the above table. If this was a Git MultiSite installation, installed in the default locations, then the two scripts should be installed in the following location on all of your GitMS nodes that the repository template represents.

/opt/wandisco/git-multisite/replicator/gfr/bin/myCompany/preplacement
/opt/wandisco/git-multisite/replicator/gfr/bin/myCompany/postplacement

The scripts should be marked as executable, normally 0755 or rwxr-xr-x.

In general, there should be 1 template per GitMS or MSP ecosystem. This is because AuthN files such as "authorized_keys" get delivered to exactly 1 path in the file system (i.e. the ".ssh" subdirectory of the home directory of the application account that GitMS or MSP runs as). So the "normal" use is 1 template and 1 generator per type for each ecosystem.

14. Managing password and Git MS Authorization file format

The format of the GitMS Authorization file.

This is normally automatically generated by ACP and delivered via the GFR mechanisms detailed above.

Such information can be useful if you need some special customization of ACP’s generated file (e.g. by using a pre-placement script).

Rule conflicts within these hierarchies are resolved by picking the rule that is most precisely defined (granular).

15. License management

This section gives the guidelines used by Access Control Plus’s license model. They ensure that deployments run in accordance with their agreed capabilities, while also ensuring minimum disruption if you accidentally exceed your license limits.

15.1. License Components

The license you use to deploy Access Control Plus is set during installation by the placement of your license.key file. Changing your license only requires that you replace the license.key file and restart Access Control Plus.

  1. Contact WANdisco’s support team and request that a new license.key file is generated. When you are sent this new file you can complete the update.

  2. Copy the new license.key file to all of your Access Control Plus nodes. Because each node’s IP address is encoded into the key, changes to IP allocation or the addition of new nodes require that a fresh license.key file is placed on every node.

  3. From a terminal, navigate to Access Control Plus’s config directory. e.g:

    /opt/wandisco/scm-access-control-plus/properties
  4. Back up or delete your old license.key file, then copy the new file into place.

  5. When the license.key file is replaced on all nodes, restart each node. Do this one after another so that you can test that each one restarts successfully. If there’s a problem with the license.key file, a warning is written to the main log file, found here:

    /opt/wandisco/scm-access-control-plus/logs/acp.log
Log rotation
Old logs are renamed to "acp.log.<date-time-stamp"

15.2. License monitoring

All components are checked on Access Control Plus’s startup. When started, each node checks all licensed components once every 24 hours. If a check fails, the thread writes out a warning to the log file and sends a notification email, so it is important to properly configure your notification settings.

This warning triggers a grace period of 10 days. In this time you need to remedy the license failure. Either:

  • Modify your deployment to bring it back into line with your license.

  • Contact WANdisco and increase your license allowance.

  • If the issue is not resolved, after 10 days Access Control Plus enters a read-only mode.

Example
There’s an installation of Access Control Plus running with a license for 30 users. During the day we exceed this limit after adding users from LDAP. Access Control Plus is not shut down, but the check is done within 24 hours. A notification email will be sent that informs the administrator (the email account holder nominated in the notifications set up) of the breach. If the issue is not resolved then in 10 days Access Control Plus will no longer allow you to make any changes. Accounts, Resources, and Rules will be locked (read-only) until the license issue is remedied.

16. RESTful API Guide

Access Control Plus offers increased control and flexibility through the support of a RESTful (REpresentational State Transfer) API.

16.1. Functionality

Note the following:

All calls use the base URI:

http(s)://<server-host>:8082/api/<resource>

The internet media type of the data supported by the web service is application/xml. The API is hypertext driven, using the following HTTP methods:

Table 4. table of ACP commands
Type Action

POST

Create a resource on the server

GET

Retrieve a resource from the server

PUT

Modify the state of a resource

DELETE

Remove a resource

To avoid call-to-call data inconsistency, you must compute a pageSize big enough to obtain all of the data in one page. To do this make one call with an initial small pageSize and verify that all of the data was returned. Otherwise compute the required pageSize, add a buffer for growth, and make a second call to obtain all of the data.

16.2. Online documentation

You can review a copy of the bundled API documentation. This documentation is taken straight from a live installation. Because the documentation is automatically generated, it frequently links to local files and resources that will not be available here.

API documentation is still in development
Note that the API documentation is incomplete and requires clarification of available endpoints. Currently the documentation includes automatically generated endpoints that are not valid for their corresponding classes.

16.2.1. API Searches with UserType

When performing API calls that filter on UserType, you need to use the following enumeration to match the appropriate searchValueList integer value.

Account Type

searchValueList

STANDARD

0

SYSTEM_ADMIN

1

AUDIT_USER

2

LOGGER_USER

3

Changes to the REST API in ACP 1.9

The "publicKey" fieldList item is no longer available from the /api/users REST endpoint e.g.

/api/users?fieldList=publicKey

Instead, the array of public keys is now available via:

/api/users/<accountId> endpoint

Additionally, there is no other way to obtain the list of SSH Public Keys associated with an account in ACP 1.9.0.
In a future release we will enable the inclusion of the sshKeys data into the /api/users endpoint via a fieldList request.

WANdisco Access Control Plus 1.9.0.16 Build 26
Release: 16 November 2016