4. Reference Guide

Welcome to the Admin Guide for WANdisco's Access Control Plus.

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. Designed to work in conjunction with WANdisco's SCM replication products or as a stand-alone solution. Integration with LDAP and Active Directory ensures that users are automatically assigned to the Subversion and Git teams that correspond to their authentication server groups. Security administrators can delegate authority to team leads to further reduce administrative overhead.

4.1 Installation Directory Structure

What follows is an overview of the files installed as part of Access Control Plus.

rwxr-xr-x  2 wandisco wandisco   4096 May  6 10:17  backups

drwxr-xr-x  2 root     root       4096 May  6 10:17  bin
     -r-xr-xr-x 1 root root 11405 May  6 09:58 backup
     -r-xr-xr-x 1 root root 10103 May  6 09:58 import42backup
     -r-xr-xr-x 1 root root  1334 May  6 09:58 scm-access-control-plus
     -r-xr-xr-x 1 root root  4073 May  6 09:58 watchdog


drwxr-xr-x  2 wandisco wandisco   4096 May  6 10:17 config
     -rw-r--r-- 1 root root 123 May  6 10:17 main.conf


drwxr-xr-x  2 wandisco wandisco   4096 May  6 10:36 content
     -rw-r--r-- 1 wandisco wandisco 6010 May  6 10:36 8e09a1a2-0539-4ff1-b83a-f868ccc1a6c0


drwxr-xr-x  7 wandisco wandisco   4096 May  6 11:59 database
     -rw-r--r-- 1 wandisco wandisco 8424 May  6 10:36 20140514.103607.290_Shadow_ACP_Model_Backup.zip
     drwxr-xr-x 3 wandisco wandisco 4096 May  6 10:17 application
     drwxr-xr-x 2 wandisco wandisco 4096 May  7 14:39 backup
     drwxr-xr-x 2 wandisco wandisco 4096 May  8 08:27 DConE.application.db
     drwxr-xr-x 3 wandisco wandisco 4096 May  6 10:36 h2


drwxr-xr-x  4 root     root       4096 May  6 10:17 docs
     drwxr-xr-x 4 root root 12288 May  6 10:17 api
     drwxr-xr-x 2 root root  4096 May  6 10:17 licenses


drwxr-xr-x  6 root     root       4096 May  6 10:17 gfr
     drwxr-xr-x 3 root     root     4096 May  6 10:17 bin
     drwxr-xr-x 2 wandisco wandisco 4096 May  6 10:17 log
     drwxr-xr-x 2 wandisco wandisco 4096 May  6 10:17 tmp
     drwxr-xr-x 2 wandisco wandisco 4096 May  6 10:17 var


drwxr-xr-x  2 root     root       4096 May  6 10:17 lib
-rw-r--r--  1 root     root     198000 Apr 25 17:31 LICENSE.htm
-rw-r--r--  1 root     root      45311 Apr 25 17:31 LICENSE.txt
drwxr-xr-x  4 wandisco wandisco   4096 May  6 10:27 logs
     -rw-r--r-- 1 wandisco wandisco     366 May  6 10:27 multisite.log
     drwxr-xr-x 2 wandisco wandisco    4096 May  7 10:27 recovery-details
     -rw-r--r-- 1 wandisco wandisco   23226 May  6 10:27 scm-access-control-plus.20140506-101717.log
     -rw-r--r-- 1 wandisco wandisco   42441 May  6 10:27 scm-access-control-plus.20140506-102521.log
     -rw-r--r-- 1 wandisco wandisco 3550637 May  8 09:17 scm-access-control-plus.20140506-102749.log
     drwxr-xr-x 2 wandisco wandisco    4096 May  8 08:27 thread-dump
     -rw-r--r-- 1 wandisco wandisco    3232 May  6 10:27 watchdog.log


drwxr-xr-x  2 wandisco wandisco   4096 May  6 10:17 properties
     -rw-r--r-- 1 root     root     1036 May  6 10:17 application.properties
     -rw-r--r-- 1 wandisco wandisco  512 May  6 10:17 license.key
     -rw-r--r-- 1 root     root     1514 Feb 26 10:00 log4j.properties
     -rw-r--r-- 1 root     root     1969 Feb 25 11:20 logger.properties
     -rw-r--r-- 1 root     root      185 May  6 10:17 user.properties


-rw-r--r--  1 root     root      34113 May  6 09:55 scm-access-control-plus-client.jar
-rw-r--r--  1 root     root       8024 May  6 09:55 scm-access-control-plus-cryptPassword.jar
-rw-r--r--  1 root     root     651749 May  6 09:55 scm-access-control-plus.jar
-rw-r--r--  1 root     root       9882 May  6 09:55 scm-access-control-plus-resetSecurity.jar
-rw-r--r--  1 root     root       1024 Apr 28 17:56 template-application.properties
-rw-r--r--  1 root     root       3064 Apr 29 11:16 THIRD-PARTY.txt
drwxr-xr-x  2 wandisco wandisco   4096 May  6 10:17 tmp
drwxr-xr-x 11 root     root       4096 May  6 10:17 ui
drwxr-xr-x  3 wandisco wandisco   4096 May  6 10:17 var
-rw-r--r--   1 root     root        689 May  6 09:46 VERSION-TREE

4.2 Properties Files

The following files store application settings and constants that may need to be referenced during troubleshooting. However, you shouldn't make any changes to these files without consulting WANdisco's support team. 

-rw-r--r-- 1 root     root     1036 May  6 10:17 application.properties
- file contains settings for the replicator and affects how Access Control Plus performs. 
-rw-r--r-- 1 root     root     1514 Feb 26 10:00 log4j.properties
- 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.

4.3 Log files

The following log files are generated during operation. 

-rw-r--r-- 1 wandisco wandisco     366 May  6 10:27 multisite.log
- Logs the application starts and stops. 
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
- This is 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 should it unexpectedly shut down.

4.4 Admin Console Master Screen

Below is a screenshot of Access Control's adminc console master screen. From here you can seem all the component parts of your access control setup, accounts, teams, repositories (when not assigned to templates), resources and rules.
admin console master screen rulelookup Settings accountlogout System Stats Accounts repositories Rules

4.5 System Stats

The System stats provide a view of the overal scale of the deployment.

ACP
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 withing 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 so far created.

4.6 Deployment Modes

Access Control Plus supports a wide number of different configurations that dictate how it can be used. When installed, the license key that you were issued will tell Access Control Plus which features to expose.

Available Modes

The following Modes are available:

Which mode is running?

You can check which mode your installation is currently in by following these steps:

4.8 Generic File Replication

WANdisco's replication technology has mostly been used in the replication of repository data between nodes. The Generic File Replication script uses the system to replicate other kinds of files. Right now these are the files that are used to coordinate changes in Access Control and repository management between nodes. We sent an archive of files (can contain multiple Authz, git Authz, passwd, git authorized keys, etc) plus 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 params 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 thereof. Please contact WANdisco support for more information.

Generic File Replication for MultiSite

Access Control Plus comes with a number of GFR scripts (See Internal Scripts) which are used exclusively in its stand-alone mode. The Generic File Replication scripts that are used to manage MultiSite Access Control are actually supplied in seperate packages:

Installation

SVN MultiSite GFR (acp-gfr-scripts-svn-installer.sh)
  • acp-gfr-scripts-svn-1.0.0-XX.noarch.rpm
  • acp-gfr-scripts-svn-installer.sh
  • acp-gfr-scripts-svn_1.0.0-XX_all.deb
Git Multisite installer (acp-gfr-scripts-git-installer.sh)
  • acp-gfr-scripts-git-1.0.0-XX.noarch.rpm
  • acp-gfr-scripts-git-installer.sh
  • acp-gfr-scripts-git_1.0.0-XX_all.deb

The corresponding package should be installed on each MultiSite Plus / Git MultiSite node. Each package is available as an rpm, debian package and .sh shell script.

Internal Scripts

/opt/wandisco/svn-multisite-plus/replicator/gfr
            bin
               drwxr-xr-x 2 root root  4096 Apr 24 11:43 acp [Folder]
		   
			-rwxr-xr-x 1 root root 2187 Apr  9 10:39 acp_build_copy_authorized_keys_file.sh
			-rwxr-xr-x 1 root root  135 Apr  8 11:50 acp_copy_file.sh
			-rwxr-xr-x 1 root root  223 Apr  8 11:50 acp_pre_placement_script_1.sh

	       -rwxr-xr-x 1 root root 15547 Apr 22 16:36 acp_gfr_main.sh
	       -rw-r--r-- 1 root root   649 Feb  7 16:54 README

            lib
            log
            var

The README file states the following:

gfr folder contains scripts and test data for placement scripts, see jira ACP-139
acp_resource folder contains test folders that, when tared, can be handled by main placement script,
acp_gfr_main.sh and acp folder should exist on the replicator node within install_dir/gfr/bin
you can create new testfiles folder in acp_resource, to tar it run:

acp_resource/acp_tar_this_folder.sh name_of_your_test_folder_no_end_slash,
e.g. 
./acp_tar_this_folder.sh test_tar_file_3

To execute the main placement script run: acp_gfr_main.sh path_to_tar_file
main plecement script will create a log file in the same directory as the script, called: local_log.log

Logout

ACP

To log out of Access Control Plus, click on the admin link in the top-right corner.

Rules lookup

ACP

The Rules Lookup tool is provided to help administrators plan, audit or troubleshoot user access. In a deployment with large numbers of accounts, repositories and rules, then the Rules lookup tool gives you a quick means of testing what rules apply to a given account.

Account name
Enter an account name to view rules that currently apply to that account.
Repository name
Enter a repository name to view rules that currently apply to that repository.
Resource refinement
Use the Resource refinement field to add a repository subdirectory as a search criteria.
Permissions
Any returned rules will be displayed in the Permissions table.

Lookup Results

ACP
Type:
The type of permission granted, Read or Read/Write
Result
This field rapidly displays where a match occurs for

Repositories

ACP

The repositories section stores the settings for each repository that has been entered into Access Control Plus.

Resources

Accounts

2. Settings

This section covers the internal setting for Access Control Plus.
Settings 01

Application Settings

The Application Settings currently contains the settings for the Batch Update Mode. Read about Batch Updates.

Settings 01

4.7 Batch Updates Mode

Introduction

Many operations in Access Control Plus require that the Authz and that SCM password files be regenerated. In a rapidly changing source code management environment, the number and frequency of account, team and rule changes can degrade performance (chiefly from a basic disk I/O perspective).

If you need to ensure that performance is not affected by Access Control traffic, the answer is to use the Batch updates feature.

WARNING: When Access Control Batch updates is enabled, changes to accounts, teams, SCM resources or rules are not instant. 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 what is actually going on.

Apply changes in batches

Batch Mode illustration

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 up to be replicated to the other MultiSite nodes at a user-defined frequency, the default is 600 seconds (10 minutes).

Access Control Changes that can be batched

Not affected

WARNING: Changes to LDAP Authorities do not trigger password / authz file rewrites, however when an authority is run, any resulting user or team changes will.

Pending Mode v.s. Current Mode

When Batched Updates are enabled the admin console can be viewed in two separate modes:

Pending:
When Batched Updates is enabled, the admin console will present a view of Access Control that includes objects (users, teams and rules) that are not yet enforced, because they're waiting to be applied in the next batch update. This is the mode you use to make any access control changes, which will immediately be added to the current waiting batch.

So the Pending Mode is actually showing you how access control will be applied once the current batch has been updated - which 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.
Current:
The Current view is available for looking 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 wouldn't make sense to create Access Control objects (users, teams or rules) in this mode as they wouldn't appear until the current batch was run.

If you need to make immediate Access Control changes, disable the Batched Updates feature before applying the change.

Enabling Current View

You can look at your nodes through the Current View, this will exclude any changes that are still waiting in the next batch update. To use the Current view:

4.9 Password and Authz File Management

The following snippets provide a basic understanding of how Authorization is controlled from within the authz file when deploying with an Authz file/ Git MultiSite.

Permissions

AuthZ rules are applied to users and teams through the following tokens:

R(+/-)
Allow/Deny the user read access
W(+/-)
Allow/Deny the user write access
C(+/-)
Allow/Deny the user ref create access
D(+/-)
Allow/Deny the user ref delete access
RE(+/-)
Allow/Deny the user rewind access (Not supported in 1.2.1 release)

Implied Permissions

Naturally if you are assigned a Deny Read Permission, this implies that you will not have Write Access:
R- is by implication a W-
W+ is by implication a R+

Reference Permissions

When controlling access to branches and tags you don't deal with Reads or Writes, only Create or Delete. Therefore C and D are used. Other permissions can be specified for branches or tags, but they will be ignored.

Authz Rules Hierarchies

AuthZ rules have 2 hierarchies which are considered in the evaluation of whether a user has a requested level of access. They are the Resource level hierarchy (Repo->Branch|Tag), and the Account level hierarchy (Account->Team).

Rule conflicts within these hierarchies are resolved by picking the rule which is most precisely defined (granular)

Example
If you have a user, Tom requesting Write access to branch "master" on repo Repo1.git, the Authz rule resolution goes like this:

  1. Determine that the repo Repo1.git exists on the local node. If not, error out.
  2. Lookup Tom's rules for branch master on Repo1.git
  3. If rules exist for Tom which grant/deny the access he needs, apply them
  4. If rules do not exist for Tom, check each of the teams Tom is a part of.
    - Tom may be a part of multiple teams which have conflicting rule permissions. One could grant, and one could deny access. In the case where the permissions conflict at the same point on the hierarchy, we always pick the most permissive rule.
  5. If Tom's teams have no rules for the master branch either, we move up the Resource hierarchy and check the permissions assigned against Repo1.git.
  6. If Tom has permissions assigned against Repo1.git, apply them.
  7. If no relevant rules exist for Tom, check again for each of the teams he is a part of.
  8. If no permissions exist at this point, apply the default policy permissions. (gitms.authz.policy)

Creating an Authz File

Follow this procedure to create an Authz file for use with Git:

Authz File Configuration

The following lines need to Git MultiSite's application.properties file

/opt/wandisco/git-multisite/replicator/properties/application.properties 
gitms.authz.file=/opt/wandisco/git-multisite/replicator/properties/authz.git
gitms.authz.enabled=true
gitms.authz.policy=deny
gitms.authz.poll.timer=30L
gitms.authz.file
Path to the authz file.
gitms.authz.enabled
Property that tells Git MultiSite to use authz.
gitms.authz.policy
The policy determines whether access is allowed to users who do not have defined authz rules defined. Default: Deny

gitms.authz.policy must be set to Deny That is, unless you want to run your repository access on the basis of assumed access - where accounts that do not have authz rules defined get full Write access by default.

gitms.authz.poll.timer
A number (followed by "L") representing how many milliseconds between each polling of the Authz file to determine if there are any changes. Default: 30L.
Long Value suffix
Placing the "L" (stands for Long value) ensures that it is converted correctly.

4. 10 License Management

Presented here are the guidelines used by Access Control Plus's license model. It is designed to ensure that deployments run in accordance with their agreed capabilities, whilst ensuring minimum disruption to customers, should they accidently exceed their license limits.

License components

An Access Control Plus deployment runs with four seperately licensed elements which combine to make up the product license:

Each component is tracked. Should any one component fail to match with the license then the installation will fail it's next license check. When running in conjunction with a WANdisco MultiSite product, these will run with their own product licenses which will apply their own limits completely independent of Access Control Plus.

How Access Control Plus monitors licensing

License Alerts

Should a check fail the thread will write out a warning to the and send out a notification email.

Grace Period

This warning will trigger a grace period of 10 days in which time you will need to remedy the license failure, either by modifiying your deployment to bring it back into line with your license or contacting WANdisco and increasing your license allowance. If the issue is not resolved, after 10 days Access Control Plus will enter 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 shutdown, 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, Rules will be locked (read-only) until the license issue is remedied.

License Updates

The license under which you deploy Access Control Plus is set during installation - with the placement of your license.key file. Changing your license only requires that you replace the license.key file and restart Access Control Plus.