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 14088 Jul 24 11:50 backup -r-xr-xr-x 1 root root 13030 Jul 24 11:50 import42backup -r-xr-xr-x 1 root root 11909 Jul 24 11:50 replace-link -r-xr-xr-x 1 root root 13178 Jul 24 11:50 rollback -r-xr-xr-x 1 root root 1334 Jul 24 11:50 scm-access-control-plus -r-xr-xr-x 1 root root 12349 Jul 24 11:50 sysInfo.sh -r-xr-xr-x 1 root root 22794 Jul 24 11:50 talkback -r-xr-xr-x 1 root root 4073 Jul 24 11:50 watchdogdrwxr-xr-x 2 wandisco wandisco 4096 May 6 10:17 config-rw-r--r-- 1 root root 123 May 6 10:17 main.confdrwxr-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-f868ccc1a6c0drwxr-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 h2drwxr-xr-x 4 root root 4096 May 6 10:17 docsdrwxr-xr-x 4 root root 12288 May 6 10:17 api drwxr-xr-x 2 root root 4096 May 6 10:17 licensesdrwxr-xr-x 6 root root 4096 May 6 10:17 gfrdrwxr-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 vardrwxr-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.logdrwxr-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.
4.5 System Stats
The System stats provide a view of the overal scale of the deployment.
- 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 ModesThe following Modes are available:
- Standalone - A one or more nodes deployed at one or more sites. To be clear, the 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.
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 a one or more sites in conjunction with both of WANdisco's SCM replication products.
Which mode is running?
You can check which mode your installation is currently in by following these steps:
- 1. Login to Access Control Plus.
- 2. Click on the Settings link on the top menu bar.
On the side menu you'll see a reference to the mode. In the example above, we're in "Both", which means that the installation is configured to support both Git and Subversion repositories, within a replicated environment.
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. Access Control Plus sends an archive of files (can contain multiple Authz, git Authz, passwd, git authorized keys, etc) as well as 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:
- SVN MultiSite GFR (acp-gfr-scripts-svn-installer.sh)
- Git Multisite installer (acp-gfr-scripts-git-installer.sh)
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.
/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 lib log var
To log out of Access Control Plus, click on the admin link in the top-right corner.
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.
- Any returned rules will be displayed in the Permissions table.
- The type of permission granted, Read or Read/Write
- This field rapidly displays where a match occurs for
The repositories section stores the settings for each repository that has been entered into Access Control Plus.
This section covers the internal setting for Access Control Plus.
The Application Settings currently contains the settings for the Batch Update Mode. Read about Batch Updates.
4.7 Batch Updates Mode
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
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
- 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 Repository templates
- Creation/modification of LDAP Authorities
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:
- 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.
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:
- 1. Login to the admin console.
- 2. Click on the Account drop-down in the right-hand corner of the screen.
- 3. Toggle the Enforce On.
- 4. The admin console's top bar will change to a mid grey colour and an "Current" symbol apears next to the Access Control Plus logo - this is to remind you that you're currently in the enforced view.
- 5. To leave the Current view, simply repeat the procedure, this time toggling back to the Off setting.
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.
AuthZ rules are applied to users and teams through the following tokens:
- Allow/Deny the user read access
- Allow/Deny the user write access
- Allow/Deny the user ref create access
- Allow/Deny the user ref delete access
- Allow/Deny the user rewind access (Not supported in 1.2.1 release)
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+
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)
If you have a user, Tom requesting Write access to branch "master" on repo Repo1.git, the Authz rule resolution goes like this:
- Determine that the repo Repo1.git exists on the local node. If not, error out.
- Lookup Tom's rules for branch master on Repo1.git
- If rules exist for Tom which grant/deny the access he needs, apply them
- 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.
- 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.
- If Tom has permissions assigned against Repo1.git, apply them.
- If no relevant rules exist for Tom, check again for each of the teams he is a part of.
- 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:
- 1.Create a new file here:
- 2. Open the new file, adding the lines:
#Git AuthZ Version:1.0 [groups] team1 = user1 team2 = user2 [/opt/git/Repo20] user1 = R+W+C+D+ user2 = R+W+C+D+ [/opt/git/Repo20:BRANCH/branch1] user2 = W+D+C+
- 3. Set the ownership of the file to match your requirements, eg.
chown wandisco:wandisco /opt/wandisco/git-multisite/replicator/properties/authz.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
- Path to the authz file.
- Property that tells Git MultiSite to use authz.
- 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.
- 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.
An Access Control Plus deployment runs with four seperately licensed elements which combine to make up the product license:
- Deployment mode - The license controls which deployment mode Access Control will operate in; Standalone, MultiSite with Git, MultiSite with SVN or MultiSite Both (Git and SVN). This license element changes which features are exposed in the Access Control Plus admin console - if your license is for Git MultiSite mode, then you will not see any features or tools that are distinct to handling SVN repository data.
- Account Licenses - The number of active account holders running on the deployment.
- Installation timelimit - Expiration based on license renewal period.
- Per-node license - The number of deployed nodes - tracked by the node's IP address.
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
- All components are checked on Access Control Plus's startup.
- Once started, each node will check all licensed components once every 24 hours.
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.
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.
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.
- 1. Contact WANdisco's support team and request that a new license.key file be generated. Once you are sent this new file you can complete the update.
- 2. Copy the new license.key file to each of your Access Control Plus nodes.That's all of them. As each node's IP address is encoded into the key, changes to IP allocation or the addition of new nodes will require that a fresh license.key file be placed on every node.
- 3. From a terminal navigate to Access Control Plus's config directory. e.g.
- 4. Backup or delete your old license.key file, then copy the new file into place.
- 5. Once the license.key file is replaced on all nodes, restart each node - you should 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 will be written to the main log file, found here:
- Enable (Checkbox)
- Tick the checkbox to enable Batch updates.
- 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.
- 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.
- Run Now
- Generate New Files
- Location Identity
- The unique ID string that is used by the replication system to identify the node.
- The name given during installation that is used to identify the node to humans.
- A unique identifier for the replication network in which the node is operating.
- This identity is used to distinguish the specific distributed state machine.
- API IP
- The IP adress 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.
- 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.
4.11 Access Control Updates
The Access Control Updates panel stores the settings for the Batch Updates Mode which helps mitigate the affects 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.
Use these settings to enable the Batch Update mode, which will benefit replication performance in large deployments.
Batch Actions gives you immediate control over Batching.
4.12 Repository Templates
The Repository Template section is used when connecting new SCM repositories to Access Control Plus. A repository template stores the paths for the repositories authentication and authorization files which are used by the Generic File Replication scripts to ensure that changes on each node are synced to all other nodes.
4.13 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, in which case user "jsmith" and "JSmith" would be considered the same user. While Access Control Plus can handle case insensitivity internally - using authz can become very problematic as this will remain case sensitive.
Enable Global Downcasing to ensure that Subversion users have their usernames forced into lowercase which ensures consistency and protects against the possibility of authz rules being applied incorrectly.
By default Global Downcasing is disabled.
Enabling Global Downcasing will trigger 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.
WARNING: If you downcase usernames using the Apache directive AuthzForceUsernameCase they must make sure no case-sensitive users will pass authN for this location. If they 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.
4.14 Node Management
Within the Node Management section we place the Node Induction information that lists all the Access Control Plus nodes that are connected together.
4.15 Node Induction
Within the Node Management section we place the Node Induction information that lists all the Access Control Plus nodes that are connected together. Induction is the term we use for connecting nodes together to form a distributed system for replicating data. Nodes that are connected together form a 'membership' which is governed by the requirements of our distributed system. One such requirement is that there must be a minimum number of nodes (a quorum) available for being able to come to agreement on the ordering of replicated changes.
Insufficient nodes to create agreement
If enough nodes are lost (disconnected or experiencing unrecoverable failure) then quorum will be lost and replication will stop. On the Node Induction screen you would see the warning "ACP operations currently impossible - Quorum is unavailable."
In this situation it may be possible to run through an Emergency Reconfiguration.
The Emergency Reconfiguration tool allows the administrator to remove a 'downed' node from membership, allowing the remaining nodes to continue to replicate using a new membership - the type of which will depend on the number and type of remaining nodes.
In the event that you need to perform a perminent removal of a node (an emergency reconfiguration) then you should contact WANdisco's support team for assistance. The operation poses a number of risks to the overall operation of Access Control Plus, for this reason we're recommend that customers not attempt the procedure by themselves.
4.16 Node Repairs
The Node Repair tool allows you to get repositories back into sync.
These attributes are only important in the event that you need to engage in troubleshooting of replication problems.
4.17 External Applications
The external applications section is used to connect with MultiSite products (Git MultiSite and / or SVN MultiSite).
4.18 Connect to MultiSite
4.19 Connect to LDAP
4.20 Email Notifications
4.21 Batch Mode View
Copyright © 2010-2014 WANdisco plc.
All Rights Reserved
This product is protected by copyright and distributed under licenses restricting copying, distribution and decompilation.
Access Control Plus
Last doc build: 17:35 09 May 2014