SVN Access Manager Documentation |
|
1. SVN Access Manager overview
2. Getting started2.1 Download the Software3. Using SVN Access Manager
2.2 Installation procedure2.2.1 Install the software2.3 First steps after installation
2.2.2 Setup the Apache web server
2.2.2.1 General2.2.3 Setup a MySQL database and a database user
2.2.2.2 ViewVC
2.2.4 Setup a PostgreSQL or Oracle database
2.2.5 Using the installer
2.2.5.1 Instructions2.2.6 SELinux
2.2.5.2 Database settings
2.2.5.3 LDAP settings
2.2.5.4 Website settings
2.2.5.5 Administrator account
2.2.5.6 Web server settings
2.2.5.7 Miscellaneous settings
2.2.5.7 Installation errors
3.1 My account menuMailinglists3.1.1 General3.2 Administration menu
3.1.2 Password
3.1.3 Password policy
3.1.4 Preferences
3.2.1 Users3.3 Reports menu
3.2.2 Groups
3.2.3 Repositories
3.2.4 Projects
3.2.5 Repository access rights
3.2.6 Create access files
3.2.7 Group administrators
3.2.8 Bulk add LDAP Users3.3.1 Repository access rights
3.3.2 Log
3.3.3 Locked users
3.3.4 Granted user rights
3.3.5 Show user report
3.3.6 Show group report
Credits
License
Warranty
SVN Access Manager is a powerful tool for managing access to subversion repositories. The tool provides user and group management and access rights (read /write) to dedicated paths in a repository as well.
SVN Access Manager uses projects to give users the rights to manage their own modules in a repository. Project is used substitutionary for a toplevel directory.
Let's have a small example of a repository structure:
testproject1 trunk /dir1 /dir2 /dir3 /dir4 /dir5 branches version-1-0 /dir1 /dir2 /dir3 /dir4 /dir5 version-1-1 ... tags version-1-0-0-0 /dir1 /dir2 /dir3 /dir4 /dir5 version-1-0-0-1 ... testproject2 trunk ... branches ... tags ... testproject3 trunk ... branches ... tags ...
As you can see the subversion repository is organized in modules containing their trunk, branches and tags each. Each of the modules is called project. One of SVN Access Manager's goals is to have the possibility to give one or more users the responsibility to organize the access rights in their project. In large repositories with a lot of projects it makes administration easier because the responsibility for giving or revoking access rights can be divided up upon more users.
Because of the fact that you can give access rights (read/write) to each directory within a repository the organization structure of a repository does not matter. SVN Access Manager can work with every subversion repository structure.
Authentication is done by the Apache web server. Only valid users may access the repositories. Authorization is done by the mod_authz module which takes the permissions from the generated svn access file.
To use SVN Access Manager you need at least:
If you need support installing and configuring Oracle oci8 driver for PHP, please refer to the PHP documentation.
First download the source archive from sourceforge.net. SVN Access Manager is available as bzip2, gzip compressed archive, as zip archive and as RPM packages as well.
The installation is divided up in several parts. Just follow the instructions below.
For the installation description it is assumed that SVN Access Manager ist installed to /usr/share/svn-access-manager, the web server is accessed as localhost and the Subversion Repository and the MySQL database are on the same host. The directory containing the repositories is assumed as /svn/repos. The files needed for authentication and authorization are assumed in /etc/svn.
The configuration file for SVN Access Manager will be placed in /etc/svn-access-manager directory. Please make sure that your webserver has enough rights to wirte the configuration into this directory. This installation description assumes that the webserver user is the user apache with the group apache.
Please make sure that in your php.ini file the varibale mysql.allow_persistent is set to on! Otherwiese you may have problems with login after the installation. Please set the variable mysql.allow_persistent to on before you proceed with the installation. Don't forget to restart your webserver after changing the value of mysql.allow_persistent!
Go to a directory where the software can be accessed by your Apache web server. Unpack the archive. For our example do the following:
# mkdir /etc/svn # mkdir /etc/svn-access-manager # mkdir /usr/share/svn-access-manager # chown apache:apache /etc/svn /etc/svn-access-manager # cd /usr/share/svn-access-manager # tar -xvfz svnaccessmanager-0.5.0.0.tar.gz
For RPM based systems it is recommended to use the RPM packages for installation.
If you have SElinux running in enforcing mode you have to use the SELinux context for SVN Access Manager. You will find the files in the "doc" folder. The contect assumes that you will install the configuration file to /etc/svn-access-manager and the repository access files to /etc/svn. If you want to allow repository creation directly from SVN Access Manager you must extend the SElinux context accordingly to allow the webserver user to do so.
To install the SELinux module just do the following:
# semodule -i svnaccessmanager.pp
You must ensure that the software ist installed directly into the directory /usr/share/svn-access-manager. Otherwise you have to create your own SELinux module.
Proceed with setting up the Apache web server described in the next step.
Your Apache web server must know about the SVN Access Manager if it is not installed in the DocumentRoot of your web server. In the latter case you can include a line similar to this in your web server configuration:
Alias /svnaccessmanager /usr/share/svn-access-manager/svn_access_manager
To get user authentication and authorization work you have to add DAV support to your web server and configure it accordingly. You can use a configuration similar to this:
<Location /svn/repos> DAV svn SVNParentPath /svn/repos AuthType Basic AuthName "Subversion Repository" AuthUserFile /etc/svn/svn-passwd AuthzSVNAccessFile /etc/svn/svn-access Require valid-user SVNIndexXSLT /svnstyle/svnindex.xsl </Location> CustomLog /var/log/apache2/svn.log "%t %u %{SVN-ACTION}e" env=SVN-ACTION
The configuration above assumes that no anonymous access to the repository is allowed. If you need anonymous read access you have to limit the Require valid-user to write operations. See the Apache web server documentation for further information.
After adding this don't forget to reload your web server to make sure the configuration changes are active.
Btw. The settings above are printed out from the installer after a successful installation. The installer output is modified according to your settings.
If you plan to use LDAP authentication you can use a configuration similar tp this:
LDAPSharedCacheSize 200000 LDAPCacheEntries 1024 LDAPCacheTTL 600 LDAPOpCacheEntries 1024 LDAPOpCacheTTL 600 LoadModule dav_svn_module modules/mod_dav_svn.so LoadModule authz_svn_module modules/mod_authz_svn.so Alias /svnstyle /usr/share/doc/subversion-1.4.2/tools/xslt/ <Location /svn/repos> DAV svn SVNParentPath /svn/repos SSLRequireSSL AllowOverride ALL Satisfy All AuthType Basic AuthBasicProvider ldap AuthName "SVN LDAP Auth Test" AuthLDAPURL "ldap://127.0.0.1:389/ou=people, \\ ou=example?uid?sub?(objectclass=*)" AuthLDAPBindDN ou=apache,ou=example AuthLDAPBindPassword password AuthLDAPGroupAttribute member AuthLDAPGroupAttributeIsDN on AuthzLDAPAuthoritative off AuthLDAPCompareDNOnServer On Require valid-user AuthzSVNAccessFile /etc/svn/svn-access SVNIndexXSLT /svnstyle/svnindex.xsl LogFormat "%t %u %{SVN-ACTION}e" svn_common CustomLog svn_common env=SVN-ACTION #CustomLog logs/svn.log "%t %u %{SVN-ACTION}e" env=SVN-ACTION
After adding this don't forget to reload your web server to make sure the configuration changes are active.
Btw. The settings above are printed out from the installer after a successful installation. The installer output is modified according to your settings.
If you plan to use ViewVC anyone who can access ViewVC can access all repositories storing data in the ViewVC database. SVN Access Manager is capable to create a ViewVC web server configuration to limit access. It will consist of a group file and a web server configuration file.
To use the ViewVC configuration files you have to configure
root_as_url_component = 1
in the viewvc.conf file of your ViewVC installation. Without this configuration setting the generated files will not work properly.
SVN Access Manager will create the group file for allowing access to the repositories stored in ViewVC. It will also create a configuration file for the Apache web server to use this group file. To use the Apache configuration file you have to advice your Apache web server to load the configuration file. You have to define a command for reloading the Abache web server configuration which can be executed by the web server itself.
Here's a short description of a setup using Apache web server 2.2 with Debian Etch. For the example it is assumed, that SVN Access Manager creates the configuration files to /etc/svn and ViewVC version 1.0.5 is already installed to /usr/local/viewvc-1.0.5. It is also assumed that you have configured Python accordingly. The ViewVC web server configuration consists of two files:
For user authentication the password file created from SVN Access Manager is used as well.
Example configuration:
First go to /etc/apache2/sites-available. Create a file "viewvc" containing the following:
ScriptAlias /viewvc /usr/local/viewvc-1.0.5/bin/cgi/viewvc.cgi
Go to /etc/apache2/sites-enabled and create a link to the file created before:
ln -s /etc/apache2/sites-available/viewvc viewvc
Now change to /etc/apache2/conf.d and create a link to the ViewVC configuration created bySVN Access Manager:
ln -s /etc/svn/viewvc-apache.conf viewvc-apache.conf
For automatic configuration reload of the web server you can define a sudo command like this:
www-data ALL = NOPASSWD: /etc/init.d/apache2 graceful
Now restart your web server.
Detailed information about ViewVC can be found on the ViewVC Homepage and in the INSTALL file in the ViewVC archive.
You need a database for SVN Access Manager and an user with full access to this database. To create the database do the following as root user of your MySQL database:
CREATE DATABASE svnadmin;
To create a user having access to this database do the following as root user of your MySQL database:
CREATE USER 'svnadmin'@ 'localhost' IDENTIFIED BY '*******'; GRANT USAGE ON * . * TO 'svnadmin'@ 'localhost' IDENTIFIED BY '*******' WITH MAX_QUERIES_PER_HOUR 0 MAX_CONNECTIONS_PER_HOUR 0 MAX_UPDATES_PER_HOUR 0 MAX_USER_CONNECTIONS 0 ; GRANT ALL PRIVILEGES ON `svnadmin` . * TO 'svnadmin'@ 'localhost';
After finishing the database work continue with installing SVN Access Manager.
If you get an error "No database selected" during installation check if the database user has sufficient rights to access and to work with the database!
Please refer to the database documentation for information about to setup a PostgreSQL or Oracle database.
Important notice:
Please remove the installer script after finishing the installation. It is a security risk to have the installer on a global accessible site! You can achieve this by removing the install.php script or by making it unaccessible for the user running the web server.
The installer is started by entering the following URL into your web browser presuming that you have the alias names as mentioned above. Otherwise please use the values fitting your installation:
http(s)://localhost/svnaccessmanager/install/install.php
It is recommended to use https to access the installer over the internet because of the fact that passwords are sent to the web server!
After the installer is started, please fill in the values fitting your requirements. Below you find a short description of the several settings. The installer consists of six pages. After you finished filling the appropriate values click Start installation. If there are errors please correct them. Otherwise the installer starts and gives you a success information. Additional the web server configuration is printed out.
The installation instructions inform you about the installation process and about of missing settings in the php.ini file. |
SVN Access Manager supports MySQL, PostgeSQL and Oracle databases. Select the database you want to use.
You can change the sort order of LDAP users by setting the values for LDAP User sort attribute and LDAP user sort order.
LDAP bind with user login data changes the behaviour for Active Directory users. LDAP bind will be done with the user credentials. If you say 'Yes' here you must fill in the LDAP Bind Dn Suffix too.
Using LDAP will change the behaviour of SVN Access Manager. You will not be able to add users with your own uswernames. The users will be fetched from the LDAP directory and you can only add the users to SVN Access Manager to give the users the chance to work with your subversion repository.
Impoartant notice:
The admin user you choose must exist in the LDAP directory you connect to. Otherwise you will not be able to login to SVN Access Manager!
You will have to setup your Webserver to work with LDAP authorization. After installation on the result page a sample configuration for Apache webserver will be shown depending on your input.
SVN access file sort order makes it possible to change the sort order of the pathes in the access file.
Anonymous read access creates an entry in the SVN Access File letting anonymous users reay a repository.
To use the ViewVC restrictions you must select to create the configuration files, specify the directory where to write the configuration files, enter the alias you use for ViewVC in the web server and give a command which enables the web server to restart itself. You can find detailed explanations about the setup of the ViewVC restrictions here. You can find information about ViewVC on the ViewVC Homepage.
SVN Access Manager makes use of the svn and the grep commands. Please check the installer's suggestions and correct them if necessary.
The Page size sets the default value of how many records will be displayed on a screen. This value can be overwritten by the preferences each user can set.
The password length fields set the minimal length for user and administrator passwords. It is strongly recommended to have strong and long enough passwords. Please keep in mind that a repository which has weak user and administrator passwords can easily be accessed by a malicious user.
You can use crypt or md5 to crypt the passwords. You can switch the configutation at every time by changing the setting in the config.inc.php file. The passwords are stored encrypted in the database. Once an user changes his password it will be encrypted with the new algorithm.
The user default access right is the default walue which will be shown during creation of an user.
You can setup up to thee custom fields for users e. g. phone number, fax number. These fields will only show up when you set custom field names here.
This page shows you all errors found during installation. |
After a successful installation of SVN Access manager you should configure the application to your needs. That means that you create the necessary users and groups, define the repositories usable in projects and define the projects and its responsible persons.
To do this it is recommended to do the following steps:
To start using SVN Access Manager type the following into your web browser:
https://localhost/svnaccessmanager/
If you installed with a different alias or on a different domain please use the values accordingly.
This section describes the menu items from the My account block.
The General menu item gives you access to the data stored about you. Please keep in mind that you have to have a correct and working email address. If not you do not get messages concerning your account. This can result in a blocked account. You can enter a security question and the answer to that questions also. Doing so allows you to recover your password yourself. Without a security question and an answer to it you need the help of an administrator to recover a lost password.
To change your password type in your current password and the new password. To avoid typos you have to enter the new password twice. Your new password must fit the password policy to be accepted.
Note that your new password becomes valid for the SVN Access Manager Webinterface immediately, but may take some time for repository access itself. The latter depends from if and how your system administrator has setup the update-interval for passwords.
Here you find the actual password policy.
Set your personnel preferences. In the moment only the Page size can be set.
The menu items described below are only accessible if you have administrative rights. Depending on your rights you might see all or only particular menu items.
The following buttons are used:
is used for selecting an entry for changes.
is used to select an entry for delete.
is used to delete all selected entries
is used to submit
is used to cancel
The Repository user right determines if a user has write access to repositories. If you specify read here you can not give the user write access to any repository in the defined projects!
The global user rights determine what the user is allowed to do. The right can be none, read, edit or delete. Higher rights also include the lower rights. E. g. the delete right includes edit and read.
If you have been granted subadministration rights you are not allowed to edit all fields of an user. And you are never allowed to grant higher permissions than the pemission your user has. E. g. if your user has the right to add users you will only be allowed to create users with the privilege 'add'.
With subadministration rights you may be allowed to edit your own user. Be careful in lowering your own rights. You will need an administrator with more rights to give you the rights back!
Groups are useful to make access right administration easier. You have the possibility to assign rights to whole groups. So adding a member to a group gives the new member all the access rights the group has.
Here you define the repositories you want to administer. Please keep in mind that removing a repository removes it only from the database.
Subversion grants access rights recursively. That means that creating access rights to repositories is not as complex as it seams. Let's have a small example.
Repository testrepo: trunk /dir1 /dir2 /dir3 /dir4 /dir5
Let's assume that there are two user defined for this repository, user A and user B. User A should have read access to the whole repository but should only be allowed to write into "dir2" without the sub directories. User B should have write access to the whole repository except "dir5". For dir5 he should not have any access.
You can set the access rights with SVN Access Manager according to this created access file:
[testrepo:/trunk/] A = r B = rw [testrepo:/trunk/dir2] A = rw [testrepo:/trunk/dir2/dir3] A = [testrepo:/trunk/dir2/dir4] A = [testrepo:/trunk/dir5] B =
You can create the access files you selected during installation. If you decided not to use any access files this menu item does not show up.
Before the access files are created you must confirm to do so.
The global user rights determine what the user is allowed to do. The right can be none, read, edit or delete. Higher rights also include the lower rights. E. g. the delete right includes edit and read.
Several reports are predefined. The idea behind the reports is to give an auditor access to the given access rights, the users and their rights and the log without having any permissions to administer SVN Access Manager.
First specify the date you want to see the access rights. After submitting the date you will see a list of all access rights valid for this date.
SVN Access Manager is able to write log messages into a database table. This must be selected during installation. If logging is deselected this menu item does not show up.
Users are locked automatically if their password expires. This repost shows the currently locked users.
Each user can be granted administrative rights. This report shows you the rights each user has within SVN Access Manager. Access rights to repositories are not included. There's an extra report for that.
The show user report gives an overview to which groups an user belogs and which access rights the user has. Rights that are gained though group memership are included too.
The show group report gives an overview which access rights the group has. The members are listet as well as the group administrators.
There's a mailinglist called svn-access-manager-announce for announcements of new releases of SVN Access Manager. The list requires a subscription which can be done here in the Mailman Web Interface.
New releases are announced on freshmeat.net and sourceforge.net as well.
SVN Access Manager uses JQuery, JQuery UI, Chosen, a Select Box Enhancer and the Aria Sort Tables.
Thanks to everyone for submitting feature requests, sending patches or submitting bugs.
Special thanks to Maik, Tobias and Jan for a lot of testing and providing patches to fix some bugs.
SVN Access Manager is distributed under the GPL v2.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.