1. Introduction

Welcome WANdisco Subversion Access Control admin guide. Subversion Access Control is a network proxy that provides Subversion Administrators with a comprehensive, easy to setup security agent that offers the following capabilities:


1.1 Technical Overview

Subversion Access Control works as a proxy between Subversion users and the Subversion server. Subversion users connect to Access Control using the standard port 80. Access Control relays user interactions to the Subversion server using port 81. Subversion users never have direct access to Subversion, allowing administrators to keep control over their Subversion repositories.

SVN Access Control 01

1.2 Release Notes

Release: 4.0 Build: 9336 (March 14, 2012)

Issues Addressed

Release: 4.0 Build: 9243 (March 01, 2012)

Issues Addressed

Release: 4.0 Build: 7797 (October, 03 2011)

What's new

Issues Addressed

Release: 4.0 Build: 7579 (September 09, 2011)

Issues Addressed

Release: 4.0 Build:5974 (April 26, 2011)

What's new

Release: 4.0 Build:5876 (March 24, 2011)

Issues Addressed

Release: 4.0 Build:5295 (Jan 11, 2011)

What's New

Issues Addressed

Release: 4.0 Build:4851 (Nov 10, 2010)

Issues Addressed

Release: 3.7 Build:3926 (July 23, 2010)

Issues Addressed

Release: 3.7 Build: 3855 (Jul 08, 2009)

Issues Addressed

Release: 3.7 Build: 3660 (Jun 01, 2009)

Issues Addressed

Release: 3.7 Build: 1951 (Dec 03, 2009)

Issues Addressed

Release 3.7 Build: 1634 (Nov 12, 2009)

Issues Addressed

Release 3.7 Build: 1464 (Nov 3, 2009)

What's new


Issues Addressed Known Issues

On Windows platforms, installation directory must remain 'svn-security' and must not renamed. Also the installation directory may not be in a path with whitespaces.

2. Important WANdisco Access Control Terms

Login id
The actual Subversion account name that can be successfully authenticated by Subversion or SSH daemon (if using the ext SSH protocol). The Subversion login id is also the primary key for a user in the Access Control user database.
Principal
Principal can be any valid user or group. After authentication, Access Control maps a login id to a set of rules that include the actual user and all its associated groups and sub-groups.
Resource
Resource is a file, directory, module or the SVNROOT itself. Resource patterns can be specified as Perl-style regular expressions in the ACL. All directory paths should be specified in the slash-terminated form. For example, specify /a/b/c/, not /a/b/c.
IP Mask
A Perl-style regular expression specifying the Subversion client's IP address. It is used in the ACL to restrict access to a specific client network, subnet or a machine.
Privilege
Privileges are needed by a user to execute specific Subversion commands. WANdisco Access Control supports these privileges: List, Read, Write, Copy, Delete, Admin
GUID
Globally Unique Identifier. WANdisco Subversion Access Control assigns a GUID to the site where WANdisco is on installation.
prefs.xml
The preferences files contain information on the Access Control. The preference file is located in svn-security/config.

3. Setting up Subversion Access Control

Installation requirements

 System setup

 Operating Systems

We've tested the following operating systems:
  • Fedora (32 or 64 bit): 6, 7, 8, 9, 10, 11
  • Red Hat Linux Enterprise Server (32 or 64 bit): 4, 5.2, 5.3, 5.4
  • Sun Solaris (32 or 64 bit): 9, 10
  • Linux: Linux kernel 2.6 or higher
  • CentOS-4: (5.2, 5.3, 5.4 and 5.5)
  • Windows Server: (32 or 64 bit) 2003, 2008

  • In principle, any operating system that can support a Java environment, Apache and Subversion.

 Subversion server

Version 1.4 and above (we've tested up to version 1.6.13). Run the Apache Portable Runtime that matches your Subversion version.

tip"Certified Subversion Binaries
are now available from WANdisco. Providing the latest builds, without the risks associated with Open Source distribution.

 Subversion client

Any that are compatible with local Subversion servers.


 Triggers
  • Pre-commit triggers are not recommended. Use pre-replication hooks instead.
  • Any pre-replication hooks must be deterministic,
    i.e. have the same exact behavior and outcome at every node. Post-commit triggers can be tested at only one node.

 System memory

Ensure RAM and swapping containers are at least four times larger than the largest Subversion file.
Minimum recommended: 2 GB RAM; 4 GB swapping container


 Disk space

Subversion: Match to projects and issues.
MultiSite Transaction Journal: Equivalent of seven days of changes.

To estimate your disk requirements, you need to quantify some elements of your deployment:
  • overall size of all of your SVN repositories.
  • frequency of commits in your environment.
  • types of files being modified - text,binaries (SVN clients only send deltas for text).
  • number and size of files being changed.
  • rate that new files are being added to the repository.
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:

Recommended storage = Number of clients checking out files(N) x average checkout sizes (Kilobytes)


 File descriptor limit

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


 Journaling file system

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

    ** Alert! **Alert
    NTFS is not a journaling file system: ext4 is a journaling file system, although its use of deferred writes makes it incompatible with Subversion MultiSite.


 Max. User Process Limit

At least three times the number of Subversion users.

 Java

Install JDK 1.6 or higher. We recommend using Oracle JDK 1.6.


 Perl

Install version 5.6.1 or later. For Access Control: Perl::DBI module for Audit Reports other than Users and Groups.

** Alert! **Alert
Windows users: Use the 32bit edition of ActivePerl 5.8, even if you are running a 64bit Windows server.



 Audit reports

For reports other than Users and Groups, you'll need to use a database such as MySQL, and php.


 mod_authz_svn

Optional but recommended. See Access Control - Using the Authz Module. Module may be bundled with your version of Apache.

Installation Procedure

1. Download the Access Control download file "svnsec.tar.gz" from the WANdisco download website.

2. Create a home directory for the installation, e.g. /wandisco.

3. Extract the "svnsec.tar.gz" file to the wandisco folder.

4. The installation files are now in place, they are arranged in the following directory structure:

drwxr-xr-x 2 root root 4096 2010-08-12 13:54  audit
drwxr-xr-x 3 root root 4096 2010-08-12 13:42  bin
drwxr-xr-x 8 root root 4096 2010-08-13 13:04  config
drwxr-xr-x 3 root root 4096 2010-08-12 13:10  lib
rw-r--r-   1 root root 16237 2010-05-21 15:03 license.txt
drwxr-xr-x 2 root root 4096 2010-08-12 14:29  logs
drwxr-xr-x 3 root root 4096 2010-08-12 13:54  systemdb
rw-r--r-   1 root root 24 2010-07-21 13:05    version.txt

5. Copy your Subversion Access Control license.key file into the config directory.

    
-rw-r--r-- 1 root root  26165 2010-08-13 13:04 backup.xml
-rw-rw-r-- 1 User User    512 2010-08-12 15:46 license.key
drwxrwxr-x 2 User User   4096 2010-08-12 13:37 licenses
-rw-r--r-- 1 root root   3327 2010-05-21 15:03 log.properties
-rw-r--r-- 1 root root    366 2010-08-12 14:28 mailconfig.properties
drwxr-xr-x 5 root root   4096 2010-08-12 13:42 membership
drwxr-xr-x 2 root root   4096 2010-08-12 18:27 passwd
drwxr-xr-x 3 root root   4096 2010-08-12 13:42 prefs
-rw-r--r-- 1 root root   3047 2010-05-21 15:03 prefs-template.xml
-rw-r--r-- 1 root root   2813 2010-08-12 14:26 prefs.xml
-rw-r--r-- 1 root root  92160 2010-07-21 13:05 reports.tar
drwxr-xr-x 3 root root   4096 2010-08-12 13:42 scm
drwxr-xr-x 7 root root   4096 2010-08-12 14:29 security

6. Enter the bin directory and run the setup, using the command:

perl setup

You'll be directed to the browser based setup screen:
******* Start WANdisco Logging **************
 version : unknown build unknown
 Default member id : 00000000-0000-0000-0000-000000000000
 current time : Fri Aug 06 12:20:03 CEST 2010
******* End Log header **********************

1281090002964 org.nirala.communication.transport.DConeNet.ListenReactor setupListener
INFO:  [listen-1] Listening on port : 0.0.0.0/0.0.0.0:6444

Point a web browser to http://10.2.5.124:6444/ to configure the product.

7. From a browser, enter the setup URL (http://<Server IP>:<port>). From the welcome screen, click Continue.
SVN Access Control 01

8. Read the WANdisco End User License Agreement, then click I Agree.
SVN Access Control 01

9. The next two screens introduces you to the notion that Access Control works as a proxy between the clients of Subversion users and the Subversion server. Subversion users can continue to connect using the the default HTTP port (80).
SVN Access Control 01

Click Next

SVN Access Control 01
Click Next.

10. On the SVN Security Agent Proxy Settings screen, enter the following details

Node Name: A name you will use for the Access Control server.
Node IP: The server's IP address
Bind Host: By default, this uses the wildcard 0.0.0.0 IP that binds to all network interfaces on the node. Read our Knowledgebase article about the benefits of using the wildcard IP
Client Port By default this is 80, allowing Subversion users to continue without making change to their client setup.


(Linux/Unix) In order to use port 80, Access Control must be run as root.

Admin Console Port 444 by default.

SVN Access Control 01

Click Next.

11. The next step automatically checks the Apache configuration. If the httpd.conf file isn't found, enter its path into the Configuration File entry box, then click Reload Configuration.

Look out for warning boxes for where setup finds a problem - like this one:

SVN Access Control 01

If a problem is highlighted, you'll need to manually edit the httpd.conf file, then click on Reload Configuration to have setup check your changes.

User: Owner of the file.
Group: The group in which the owner belongs.
KeepAlive: Setup will look to see that the Keep-Alive directive is set to On.
KeepAliveRequests: Setup will look for 0, which indicates that no maximum limit will be set for connection requests.
KeepAliveTimeout: Set very high (500,000 seconds) to ensure connections don't timeout.
Listening IP: For a node with multiple IPs, this will indicate the IP used for listening.
Listening Port: The default listening port for Apache is 8080.
Override Listen Directive with a virtual host: Tick this box if the Apache parser doesn't pick up the correct Listen IP/port, maybe as a result of setting up Subversion to be only accessible through a virtual host. If you tick the box you'll need to manually enter hostname/IP.

SVN Access Control 01
Click Next. To continue without the Apache config check, click Skip.

12. Setup now allows you to modify your Subversion settings. Watch for alerts that confirm the port and path that Access Control will associate with your Subversion repositories.

Subversion Server Port: the port on which Access Control talks to Subversion,(8080 by default).
SVN Executable: the fully qualified path to the Subversion executable. Setup will try to fill this in automatically, otherwise enter it manually.
Use authz-based access control? Tick the box to use Authz. If you tick the box you'll need to locate the fully qualified path to the Authz file.
Authorization File: Enter the path to the Authz file.

Use LDAP for authentication: Tick the box to use an LDAP service. Provide the URL to your LDAP server.

Disabling LDAP for Admin Authentication
LDAP connection URL: the URL for the LDAP server, using the format ldap(s)://hostport/basedn?attribute
Truststore File: Select the location of a Truststore file that points to your trusted SSL certificates.
Truststore password: Select the location of the Truststore file that points to your trusted SSL certificates.

If you're specifying secure email (using a truststore) and LDAP authentication over SSL (using a truststore), the same truststore mustbe used for both sets of certificates. If different truststores are used then the LDAP truststore will overwrite the email truststore and secure emails will stop working.

Use LDAP for WANdisco admin authentication: Tick this option to use LDAP to manage the admin login credentials for Access Control's admin console. If you select this option you will need to provide a URL for the LDAP server in the format ldap(s)://host:port/basedn?attribute

The option to use LDAP for WANdisco admin authentication is only available when you first select Use LDAP for authentication (which applies to all users).

Test LDAP Connection Click this button to confirm that you're able to connect to your LDAP server before continuing with the setup.

At the bottom of the screen is a table that confirms the DAV Location and password control for your repositories. You can click Edit to make changes.

LDAP Admin Authentication URL syntax

The LDAP Admin login functionality lets you specify an LDAP group or subtree that contains users who can login as administrators. The format of the URL is:

ldap(s)://host:port/basedn?attribute?scope?filter
ldap
For regular LDAP, use the string ldap. For secure LDAP, use ldaps instead.
host:port
The name/port of the LDAP server.
basedn
The DN of the branch of the directory where all searches should start from. This would typically specify a group populated with admin users
attribute
The attribute to match user names against. If no attributes are provided, the default is to use uid. It's a good idea to choose an attribute that will be unique across all entries in the subtree you will be using.
scope
The scope of the search. Can be either one, sub or obj. The default is to use a scope of sub.

-one: Entities will be searched below the DN one level only - if an entity with a matching attribute=username is found then the user is considered an admin.
-sub: Entities will be searched below the DN throughout the entire subtree - if an entity with a matching attribute=username is found then the user is considered an admin.
-obj: A specific object is being identified by the DN - if this object is located AND a matching attribute=username is found then the user is considered an admin.
filter
A valid LDAP search filter. If not provided, defaults to (objectClass=*), which will search for all objects in the tree.

Once a user is deemed to be an admin based on the criteria above, authentication is carried out against the LDAP Authority system, so it is important to ensure a relevant LDAP authority has been defined.


SVN Access Control 01
You can add additional repositories by clicking Add Repository. To continue setup, click Next. If you click Edit to change Repository you'll be able to edit the following settings:

Editing repository settings:
Directory on File System: Repository location. This needs to be the fully qualified path to the repository directly, not the URL that clients use for remote connection.
Manage Password File: tick the box to allow your Subversion password file to be controlled by Access Control. If selected you'll need to provide the username and password of the Subversion user account that will be used by Access Control to browse the repository. The account will need read and write access to the whole repository.

Settings in Apache
DAV Location: You can specify the location of the DAV file.
Multiple SVN Repositories: click Yes if you are using SVNParentPath for multiple repositories, or No if using SVNPath.

Click Update to apply your changes, or Cancel to return to the previous screen without making changes.

SVN Access Control 01

13. The next screen is for your email settings. Entering email settings will allow Access Control to send out alert emails that can help you identify problems.
SMTP Authentication: If you select No, you'll need to provide your account.
Username and Password: Enter these if you select Yes to SMTP Authentication.
Use SSL/TLS: Choose yes if you wish to send emails over a secure connection.
Host: Enter the address of your mail server.
Port: Enter the SMTP port, 25 by default.
Send Admin Notification To: The email address (You can only specify a single address, not a comma delimited list) to where notifications will be sent.

Email settings are optional. If you don't need alert emails, click Skip to continue. Otherwise, click Next.
SVN Access Control 01

14. The setup has finished gathering information, You can go back and make changes or click Complete installation with these settings to save them and complete the installation.

SVN Access Control 01

15. When you click Complete installation with these settings Access Control's SVN Security Agent will automatically start up.

SVN Access Control 01

4. Admin Console Guide

Welcome to the admin guide for WANdisco's Subversion Access Control. This guide will help you take control and manage the access of your Subversion repositories.

Access Control has a browser-based Admin Console for making user access changes, changing settings or viewing system logs.

Connecting to the Admin Console

Connect to the Admin Console through a web browser, using your server's hostname or IP address, along with the administration port (defaults to 6444).

On connecting you'll be prompted for a login. The default admin username is admin and the password is specified during setup. This section will run through the different screens available in the Admin Console, explaining what they do.

4.1 Security

The security tab is the business end of the Admin Console, it handles all user related functionality.

SVN Access Control 01

Password fields appear for users only if you chose to have Access Control manage the Subversion password file during installation. For DAV, Access Control does not handle the user authentication.

4.1.1 Role Administration

Roles are used to define the permissions available to different kinds of users.

Create Roles: Create new roles and assign them privileges. Subversion permissions are: list, read, write, delete, copy, admin. See Managing Roles and Permissions.

List Roles: Display all roles, including pre-defined and any new roles created using the 'Create Roles' screen. Privileges are also displayed. To delete a role, click on the corresponding checkbox and click Delete Selected.
SVN Access Control 01

4.1.2 User Administration

Manage Subversion user accounts.

Create User: Create any Subversion user.
SVN Access Control 01

tip"Tip
Usernames can contain any characters except for ~ (tilde), " (double quote) or : (colon). When importing users, it's possible to include a comma in a username by using an escape character, e.g. ,"Reninngton\, Jr.","Oscar"

List Users: This command displays all users.
SVN Access Control 01
The Last Recorded Access column shows the date and time that each user last accessed (or attempted to access) a Subversion repository.

** Alert! **Alert
The finer details about how the Last Recorded Access is handled:


Import Users: You can import an existing list of users. The import file must be a comma delimited text file, of the format userid,role,lastname,firstname,email.
SVN Access Control 01

Change Admin Password: You can change the Access Control Admin password with this screen.
SVN Access Control 01

4.1.3 Group Administration

Control the groups used for organising Subversion users.

Create Group Create a new group.
SVN Access Control 01

List Group Shows all the groups. You can list all users in each group.
SVN Access Control 01

Assign Users Allows you to assign users to groups. If a user is already in a group, his or her name does not appear in the list of available users.
SVN Access Control 01

Remove Users Use this to remove users from a group.
SVN Access Control 01

Import Groups You can import a list of existing groups. The import file must be a comma delimited text file, of the format groupname,parentname[,description]. If there is no parent name, specify null.
SVN Access Control 01

4.1.4 ACL Administration

This menu can be toggled off. See Toggling the ACL Display. For a complete discussion on ACLs, See About Access Control Lists.

Create ACL Create more than one at a time, use List ACLs.
SVN Access Control 01

List ACLs Lists all existing ACLs. You can create, edit or delete ACLs with this command. Use this command when creating multiple ACLs.
SVN Access Control 01

4.1.5 Ext Auth

Make use of external authentication, allowing for the administrator to automatically synchronize the user properties (user id, password) from an LDAP/NIS database.

LDAP/NIS - Stores settings for an external LDAP / NIS service.
New Users - Add new users.
Ignore Users - List users to ignore.

4.2 System

The system tab is used to manage system functions such as viewing the Access Control log or importing and exporting user settings.

4.2.1 System

Log Viewer - View Access Controls log file.
SVN Access Control 01

Limiting Log lines

Logs can be generated over multiple lines, which can make reading/performing greps difficult. It's possible to limit each log to a single line by using the following procedure:


Disk Monitor - Set how Access Control monitors disk usage, warning you if the system's available disk space gets too small.
SVN Access Control 01

System Config - Used to control the display of Role ACLs and Sibling Groups.
SVN Access Control 01
Log Level - Access Control uses one log, and the default level is info. The levels vary from severe, where you get only the most severe warnings, to finest, which logs every action.
SVN Access Control 01

Free Memory -This command frees the memory (GC stands for garbage collection) for the current node. The command occurs when you click on this menu selection. The display shows information on the command that was just performed.
SVN Access Control 01

4.2.2 Backup

Export Settings - This command allows you to export WANdisco settings, including all users.
SVN Access Control 01

Import Settings - This command allows you to import WANdisco settings, including all users.
SVN Access Control 01

4.3 Proxy

The Proxy tab handles Access Control proxy settings which alter the way that Access Control works between Subversion and users.

4.3.1 Status

Proxy Status - Displays the node's status in the tab's main panel.
SVN Access Control 01

Log Viewer - You can view the logs, including the main log - SVNProxyServer-prefs.log.
SVN Access Control 01

4.3.2 Node

SVN Settings - The current values are displayed. You can edit them here.
SVN Access Control 01

Email Settings - Email settings that Access Control uses to send status alerts.
SVN Access Control 01

Stop Proxy -Stops Access Control and prevents client access.
SVN Access Control 01

Shut Down Node - Shuts down Access Control completely.
SVN Access Control 01

4.4 Reports

Configure URI - Configure the address that will be used for viewing reports externally. Read about Audit Reports.
SVN Access Control 01

User Group Reports - Generate User Group reports and view them with Log Viewer in the System and Proxy tabs.
SVN Access Control 01

Audit Reports - Access Control logs any Subversion user access, these logs are controlled through the Audit Reports tab.
SVN Access Control 01

5 Managing Users

This chapter provides information on setting up users for Access Control version. You can create users, delete users, and search users by several criteria.

If you have an existing LDAP or NIS database, you can integrate it with Access Control. WANdisco offers a free, unsupported LDAP plug-in to support integration.

5.1 Password file control

During installation you choose whether to have Access Control take control of Subversion's password file.

If Access Control is managing the password file:
New users entered into Access Control automatically gain access to Subversion using the same authentication details.

If Access Control is not managing the password file:
New users created in Access Control must also have accounts (with identical details) created in Subversion.

If a user reports of getting an Access Denied message on their client, check they have been regisered on both Access Control AND Subversion.


To check if Access Control is managing the password file:
Go to the Proxy tab (1), click SVN Settings (2), and clicking Edit on the repository list. If the Manage Password box is checked (3), Access Control is managing the password file.

SVN Access Control 01


If you didn't set Access Control to manage the password file, but would like it to do so, check the Manage Password file checkbox, browse to the password file, and click Update.

5.2 Creating or importing users

For Access Control, all users must have a role. Use either a predefined roles, or create your own. See Managing Roles and Permissions and Managing Users.


If Access Control is managing the password file:
Use the import tool to bulk import a number of users up to the limit of your license. If the user exists in the Subversion password file, and you also import that user into Access Control, the entry is not overwritten. If the user is imported, but does not exist in the password file, the password is set to the user's email address.

If Access Control is not managing the password file:
A number of new users can be created up to the license limit, once Subversion authenticates them. You can also use the Import Users command.

For Access Control, you must specify a role for each user. Roles are discussed in About Roles and Groups. Use a CSV file to import groups of users. The file should follow the format userid,lastName,firstName,role,email[,group1[,group2...groupN]].


To add a new user, click on Create User in the Security tab. Specify a (Subversion) username. Enter the password, and the user's names. The email address is optional.

5.3 Deleting Users

To remove users, click List Users. Select the users you want to delete with the checkbox on the left and click Delete Selected.

5.4 Listing and Searching for Users

To get a list of all the registered users, click on the List Users link under User Administration on the Security tab. The User List page shows all users by default. The page size is set to show 25 users per page, but you can change that by selecting View Per Page on top of the user list. Arrows at the right corner allow you to scroll to the next or previous page.

Use the Search box to find users. Begin typing a user's first or last name, and an incremental search starts. Return to the full list by clearing the Search box.

All the columns in the user list are enabled for sorting. Clicking on the column header lets you sort in ascending or descending order. The sortable columns include: Userid, last name, first name, and email.

SVN Access Control 01

You can click on the Userid link to edit the user's details. You can also delete as many users as you like. Delete all users by checking the checkbox in the table header, and then click the Delete Selected button.

5.5 Importing Users

You can import an existing list of users with Import Users, found under User Administration on the Security tab. The import file must be a comma delimited (CSV) text file with the format: userid,lastname,firstname,email.

If Access Control is controlling the Subversion password file, user passwords are changed to user email addresses upon importation. We recommend notifying users to change their Subversion password, as described in the next section.

5.5.1 Subversion Password Change

Use this only for imported Users. Importation changes user passwords to their email addresses. Users can change Subversion passwords in WANdisco without logging in to WANdisco. Have the users go to:


http://<Access Control IP>:6444/

The Admin Console will appear. Have the users click on Change User Password.

SVN Access Control 01

The Change Password box appears. Users can enter their Subversion username, and their password (which is now their email address). Have them enter a new password and confirm it, then click Change Password. The users have successfully changed their passwords.

SVN Access Control 01

6 About Roles and Groups

This chapter provides information on setting up Access Control's users, roles and groups. Most customers find that managing users' roles and groups offer enough control. However, you can gain finer control with specific Access Control Lists

There's more information about using the Authz module in conjunction with Access Control Using the Authz Module.

Default Permissions: Access Control initially does not allow any user access to any resource. By default, all users are denied. This is essential for security: it closes the window of vulnerability that would allow everyone full access between the time WANdisco is first installed and the time it takes an administrator to create access rules. In order to grant access, the administrator has to explicitly create roles, groups (which define resources) and users.

Parent Directory Inheritance: Group members automatically gain membership of subgroups created under their group. As a result they'll get access to all resources available to the subgroup. So, access is controlled down the directory tree, while inheritance, goes up the directory tree.

6.1 Managing Roles and Permissions

Access Control's roles are based on Subversion permissions. The default permissions are:


The following table maps some actual Subversion commands to the minimum permission needed to execute them. This isn't a complete list.

Subversion Command Permission Required
info List
log List
ls List
status Read
cat Read
diff Read
checkout Read
cleanup Read
update Read
revert Read
annotate Read
propget Read
proplist Read
update Read
commit Write
import Write
add Write
unlock Write
move Write
mkdir Write
copy Copy
delete Delete

Access Control comes with a few default roles with preset permissions. You can modify these roles as you wish. You can also create new roles. The permissions are inherited, meaning if a role has the write privilege, it also has the list and read permissions as well. The roles work with groups, which you defined as files or directories. So the roles are applied within the groups (the defined files or directories).

Default Role Privileges
Audit list
Manager read
Developer write, copy, delete
QA copy
Admin admin

List Roles ,under Role Administration, shows all roles: the default roles and any you have created. The permissions for the roles are also listed.

SVN Access Control 01

Admin serves as a permission, a role and a group. The Admin privilege has no constraints on it whatsoever. An admin has full permission to everything in the repository and is intended to be used by a System Administrator.

If you assign a user the Admin role, or give a user Admin privileges, or put a user in the Admin group, that user has full access to everything in the repository. Do not make any ACLs for anyone with Admin role, privilege, or group. If you need to exclude a user from certain files, assign that user another role without any use of the Admin privilege, role or group.

6.1.1 Special Permissions

Special consideration should apply for list and read access rules. Unlike write operations, the read and list operations can traverse directory hierarchy. Therefore it makes sense to always allow/deny read and list privileges on all files under a directory. This can be done by specifying a wild-card pattern (|.*), for example:

allow read from /svnroot/trunk/module1(|.*).

6.1.2 Creating New Roles

In the Security tab, select Create Role. Enter a name for the role and select the Subversion permissions you would like this role to have. Any user you assign to this role has the permissions you specify for this role.

6.1.3 Editing Existing Roles

Select List Roles. The defined roles display. Select the name of the role you wish to edit. The Edit Role page displays, listing all possible privileges. The role's existing privileges are checked.

Make any changes, and click Update Role. Any user assigned to that role, both for current and future assignments, has these same privileges.

Make any changes, and click Update Role. Any user assigned to that role, both for current and future assignments, has these same privileges.

6.1.4 Deleting Roles

Select List Roles. Use the checkboxes to mark the roles for deletion. Select Delete Selected. The role is deleted throughout Access Control, even if users are assigned to that role.

Think carefully when deleting roles. If you delete a role, make sure no user is assigned to that role before you delete it.


SVN Access Control 01

6.2 Managing Groups

Creating groups allows you to manage projects, providing a convenient way of organizing many users into a related category for controlling access. You assign each group to a set of files, a directory hierarchy, or to individual directories, to either allow or deny access to specified files and directories.

You can create and delete groups, associate files, directories and modules to a group, add to and remove users from a group, and perform bulk imports of existing groups. You can also restrict access to a group by client IP address.

Groups are hierarchical, with a parent-child association between a group and a sub-group.

SVN Access Control 01

6.2.1 Creating New Groups

To add a new group, select Create Group. The Group Properties page appears:

SVN Access Control 01

The name can contain any character, including white space, except the underscore character. The group name is the primary key into the group database, therefore it cannot be changed once it is created. Enter relevant text in the description field. Access Control automatically tracks the creation and modification time on the groups, which you can see in groups-reports.txt in Log Viewer.

You can optionally create this group for a specific client IP pattern. If you do enter an IP pattern in the Client IP Pattern field, no other client IPs are allowed unless you create specific ACLs for those other client IP addresses. You must use regular expressions.

6.2.1.1 Defining Group Rules

The Rule section allows you to define the files and directories for this group. Select add allow or add deny, and browse to the file or directory.

SVN Access Control 01

Add as many entries as necessary for a group, ensuring that all required directory permissions are accounted for:

6.2.2 Creating a Sub-Group

A group inherits all of the resources and privileges of its sub-groups. Follow these steps to create a sub-group.
1. Make the sub-group as you would a group.
2. Go to List Groups.
3. Click Edit for the sub-group. The Group Properties page appears.
4. In the Group Assignment section, check the radio button of the subgroup's parent.
5. Click Save Changes.
6. Go back to List Groups and confirm the structure is correct.

6.2.3 Deleting a Group

To delete a group, click List Groups.

SVN Access Control 01

Click Delete. You'll be asked to confirm the deletion.

When you delete a group, the association between the group and any users who belonged to that group is broken. The associations between any sub-groups and users are also deleted. If you want to keep a sub-group, first select a new parent for that sub-group, and then delete the old parent group. The sub-group then does not get deleted.

6.2.4 Assigning Users to a Group

To add users to a group, click Assign Users on the Group Administration section of the menu.

SVN Access Control 01

Select a group on the left (1). The list of users on the right (2) updates to reflect potential new members for the group you selected. Users already in the group are excluded from the Users list.

If a user belongs to a parent group, they automatically belong to any sub-groups underneath it, even though the list does not reflect that. However, a user can belong to a sub-group and not belong to the parent group.

Select the users to add to the group (2) . To add several users at once, hold down the Control key while you click on your selections.

6.2.5 Assigning Users to a Sub-Group

You can assign a user to any number of groups with the Assign Users command. Note by selecting a group, the user is automatically assigned to the group and all its sub-groups. To unassign, check the checkbox and click Save Details.

6.2.6 Deleting Users from a Group

To delete users from a group, click List Groups, on the Groups list, click List Users.

SVN Access Control 01

The list of users on the right updates to reflect that group's users. Select the users to remove from the group. To remove many users at once, tick multiple users. Click Delete Selected.

If a user belongs to a parent group, they automatically belong to any sub-groups underneath it; however, the screen does not reflect this. If a user is removed from a parent group, they are also removed from any sub-groups.

6.2.7 Who Is In a Group?

To view a list of which users belong to which groups, click List Groups(1).

All the groups are displayed. Click List Users(2). All the users in that group are displayed. To view users who are explicitly members of this sub-group and those members inherited from any parent groups, check the Show Inherited checkbox. Use the Group drop-down list to view the users belonging to another group.

The Userids are linked to the User Properties page, in case you need to edit a user. You can also edit and delete groups from this page.

6.2.8 Importing Existing Groups

You may have groups already set up outside Access Control. If so, you can import them using the Import Groups command, in a comma separated text file, of the format groupname,parentname[,description].

Type in the pathname to the file, and click Import. The new groups are added to the existing groups. Define the resources for this group or subgroup, and assign users.

SVN Access Control 01

7 About Access Control Lists

Many people find that managing users' roles and groups offer enough access control. However, Access Control allows you to have very specific control of users through the use of Access Control Lists (ACLs).

7.1 How WANdisco Enforces Rules

When a user tries to execute a Subversion command, Access Control's ACL engine always follows the same process to make an allow or deny decision.

First, the ACL engine checks if a user is registered or licensed in the WANdisco user database. If the user is not registered or licensed, the user is denied access.

In order for a rule to be matched, the ACL engine verifies that a user's name or the group(s) a user belongs to, IP address and file/directory matches the patterns specified in the ACLs. Rules applicable to a specific user override the rules applicable to a group.

User access rights Group access rights Access Control allows or denies
none specified allowed allowed
none specified multiple groups, any of which is allowed allowed
none specified multiple groups, any of which is allowed denied
denied multiple groups, any of which is allowed denied
allowed denied allowed
denied denied denied

Access Control allows you to automatically edit multiple rules. When you submit changes to ACLs, Access Control guarantees either all the rules are updated or none at all.

When setting up a rule on a specific directory, note that the directory name is treated as a regular expression pattern. For example, if you want to allow write access to all the files under a directory /svnroot/trunk/docs, you need to specify one of the following patterns:
/svnroot/trunk/docs|/svnroot/trunk/docs/.*
or
/svnroot/trunk/docs.*

The first pattern allows write into the directory (to create new files or directories) as well as all files under the .../docs/ subdirectory. The second pattern allows access to all files and subdirecties that match /svnroot/trunk/docs, including, /svnroot/trunk/docs, /svnroot/ trunk/docsmaker, /svnroot/trunk/docs2, etc.

Special considerations should apply for list and read access rules. Unlike write operations, the read and list operations can traverse directory hierarchy. Therefore it makes sense to always allow or deny read and list privileges on all files under a directory. This can be done by specifying a wild-card pattern, for example:
allow read from /svnroot/trunk/module1|/svnroot/trunk/module1/.*.

To use the copy privilege, specify it on the source directory. It allows a user to copy from a given directory. Make sure you enable the write privilege on the parent directory of the intended destination. Granting write privilege does not imply the user has delete or copy privilege. This allows the administrator to control who can create tags or branches and who can delete version controlled files. For example, to allow copy from /trunk to /tags/rel1, you create two access rules:

7.2 Toggling the ACL Display

You can toggle the display of role ACLs. The default is on. Go to the System page, and click System Config. Select the Yes or No radio button for Show ACLs?

SVN Access Control 01

When toggled on, you see any ACLs created by roles and groups listed on the Group Properties page, shown in the next illustration.

7.3 Creating ACLs

To create ACLs, go to the Security tab and click Create ACL. If you are creating multiple ACLs, click on List ACLs.

7.4 Toggling the Use of Access Control Lists

The following properties in the prefs.xml file can be used to control the ACL engine.

<Security>
 <AccessControl>
  <Enable>true</Enable>
  <Replicate>true</Replicate>
  <ClientTimeout>15s</ClientTimeout>
 </AccessControl>
</Security>

By default, Access Control has access control enabled. To turn it off, add the lines to prefs.xml and set Enable to false.

7.5 Example ACLs

8 About Audit Reports

Access Control logs any Subversion user access (allowed or denied) in an audit trail file. Access Control produces a standard report, Users and Groups, but recommends you import the data into a database such as MySQL, so that you can make complex queries. WANdisco offers three such reports when set up with a database: Transaction History, Access Violation Report, and File.

To set up the more detailed reports, you need to:

To ensure no audit records are lost, WANdisco recommends you schedule a job (using cron, for example) to import the audit records into a database periodically.

8.1 Setting Up the Reports

Access Control does not automatically import data into the database. You can do this manually or set up a cron job.

Installing MySQL

1. Download and install a database such as MySQL.

You can download MySQL from http://dev.mysql.com/downloads/mysql/#downloads
During the installation, don't create an anonymous account or allow root access from external sites. Choose to run as a service, starting automatically.

2. Download and install Perl DBD module.

3. Set up a user in the database.

4. Grant that user all privileges to manage the database wd_audit_db.

5. Use the PPM utility to install DBD::Mysql

6. Create the user to be used for running the queries and the database for storing the audit data:

To do this, run the following commands from a terminal window:

        %> mysql -u root -p
        ... [enter <password> at prompt]
        mysql> CREATE USER <user> IDENTIFIED BY <password>;
        mysql> GRANT ALL PRIVILEGES ON *.* TO <user>@%;
        mysql> CREATE DATABASE wd_audit_db;
        mysql> exit  
   

7. Log in using the newly created user so that you can view the database:

%> mysql -h <current computer name> -u <user> -p
... [enter <password> at prompt]
mysql> SHOW DATABASES;
8. You now have access to the newly created 'wd_audit_db' database.

Installing PHP

Download PHP 5.2.14 installer [20,877KB] - 22 July 2010
Begin the installation choosing "Apache 2.2.x module". When prompted for "Choose Items to Install", select "MySQL" from "Extensions".

Configuring Apache for PHP

9. Providing that you pointed the PHP installer to the Apache conf directory, the installer should have appended the following lines to the end of the httpd.conf file:

#BEGIN PHP INSTALLER EDITS - REMOVE ONLY ON UNINSTALL
PHPIniDir "C:/Program Files (x86)/PHP/"
LoadModule php5_module "C:/Program Files (x86)/PHP/php5apache2_2.dll"
#END PHP INSTALLER EDITS - REMOVE ONLY ON UNINSTALL    

Edit the Apache httpd.conf file:

In the PHP installation directory, edit the php.ini file to ensure that "short_open_tag=On"

Installing the admin reports

I will not replicate existing instructions, only highlight what is missing. The following block of code needs to be placed within a virtual host block of code in subversion.conf:

Alias /reports/ "c:\svn-replicator\reports"
<Directory "c:\svn-replicator\reports">
 Options Indexes MultiViews
 AllowOverride None
 Order allow,deny
 Allow from all
</Directory>

For HTTPS, put Apache section under port 80 virtual host in the subversion.conf file.

You should ensure that the importauditdb script is run as a Windows scheduled task:

Ensure the command is correct by running it from the command prompt first.

Restart Apache

10. Shutdown the replicator and restart Apache.

11. Decompress the php scripts at svn-security/config/reports.tar.

12. Edit the reports/config.php to point to the database you just created.

Modify the config.php file to update the server, username and password entries along with the scm type, which is svn.

13. Edit the importauditdb script to match the changes to config.php: dbhost, dbuser, and dbpass. It is recommended to not use the default user, root.

14. Update your Apache httpd.conf file to point to the scripts. Make sure to replace /home/wandisco/reports with your installation directory. You may also want to rename the /reports/ alias (e.g. /wandisco_reports). For example,

Alias /reports/ "/home/wandisco/reports/"
<Directory "/home/wandisco/reports">
 Options Indexes MultiViews
 AllowOverride None
 Order allow,deny
 Allow from all
</Directory>


15. Restart Apache.

16. Run the import tool. See Using the Import Tool.

17. You can now run the reports. See Running a Report.

8.1.1 Using the Import Tool

The import tool requires the Perl::DBI module you've installed. Please run svn-security/bin/ checkdbi to verify that the module is properly installed, and the correct database driver is available on your system.

The import tool is called importauditdb, and its usage is as follows:
perl importauditdb -host dbserver -user dbuser -pass dbpassword -f ../ audit/audit-trail.0 Here is an example of how to use the import command:
[admin@smp1 ~/svn-replicator]$ bin/importauditdb -h
Usage:
importauditdb [-host <db-host>] [-port <db-port>] [-user <db user>]
[-pass <db user password>] [-db <database to use>]
-f file-pattern1 file-pattern2 .. file-pattern-N
Defaults:
host : localhost
port : Default DB Port
user : root
password : empty
Database : wd_audit_db

Before using import, you must create a database on the database server.

The import tool automatically creates the table schema in that database, the first time it runs. The import tool uses standard SQL syntax, and makes use of a system function FROM_UNIXTIME. Please ensure your database version supports it. MySQL and Microsoft SQLServer both support this function.

Here is an example of how you would import a file:
perl importauditdb -host dbserver -user dbuser -pass dbpassword -f ../ audit/audit-trail.0 The audit-trail.0 file is located in the svn-security/audit directory. The file has a complete history of all Subversion actions, listed in the following format:

# Column syntax -
# 0 seq | 1 time | 2 txid | 3 cmd | 4 user | 5 ipaddress | 6 access |
# 7 dir | 8 file | 9 rev

The columns are described in this table:

Column no. Description
0 Record Sequence Number
1 Transaction ID
3 Subversion Command Name
4 Subversion User ID
5 IP Address of user
6 Access Decision (Allow or Deny)
7 Subversion Directory being accessed
8 Subversion File being accessed
9 User's File Revision

8.2 Configuring Audit Properties

Auditing is controlled in the prefs.xml file. By default, Access Control enables auditing. You can turn it off by setting the Disable element to true.

<Audit>
  <MaxFileSize>10485760</MaxFileSize>
  <MaxFileCount>10</MaxFileCount>
  <Disable>false</Disable> <!-- this is the default -->
</Audit>

By default, Access Control automatically rotates the files up to 10 times when they get to 10 megabytes. You can change these defaults in the prefs.xml file. The MaxFileSize element specifies a size in bytes, and the MaxFileCount element specifies how many files to rotate before recycling the files. To create audit files in a different directory, create a symbolic link (svn-security/audit) to another directory.

You do not want to lose any audit history. Make sure that any interval you schedule to import the files into a database is short enough so that all files in the MaxFileCount element are captured (and not overwritten).

8.3 Running a Report

1. Configure the report URI. Go to the Reports tab in the Admin Console. Click Configure URI. Enter in the IP address of the <reports apache server>:8080/<reports directory>. For example,

http://10.1.13.236:8080/reports (port 8080 providing you are not using SSL)

Click Update.

2. Go to that URL.

3. Select File Report from the main menu.

4. Enter the criteria for the report. For example, select a user from the dropdown, specify an access level or a Subversion command to filter the results. Note: use % for wildcards.
5. Click Run Report.

8.3.1 Report Types

Report Name Description
Transaction History Shows all transactions against Subversion
File List file access and filter by parameters such as:
date, access, command, user, ip address, directory,
filename, revision or branch.
User Show Subversion allowed / denied access per user.
Access Violation Display all denied access to Subversion

8.3.1.1 The User Report

8.3.1.2 The Transaction History Report

8.3.1.3 The Access Violation Report

8.3.1.4 The File Report