| Revision History | ||
|---|---|---|
| Revision 0.5 | 2003-06-29 | vv |
| Added support for CVS Tags | ||
| Revision 0.4 | 2003-06-17 | vv |
| Pointed to sarovar.org | ||
| Revision 0.3 | 2002-12-14 | vv |
| Added more information to the ‘how’ section | ||
| Revision 0.2 | 2002-12-07 | vv |
| Revised the documentation to be in sync with the code | ||
| Revision 0.1 | 2002-09-29 | vv |
| Initial version of the document created | ||
Table of Contents
Abstract
This is the detailed documentation for the CVSPermissions toolkit. This will contain all relevant and necessary information for deploying and using the CVSPermissions toolkit.
CVSPermissions is a toolkit that will allow CVS administrators to setup directory level access permissions in CVS. This toolkit is a collection of shell scripts and few CVS configuration information to achieve the said functionality.
CVS, for the uninitiated, is a source code version control tool that is very popular in the open source world. The tool is extremely stable and robust with good scalability for large products. More information about CVS can be found at the following sites.
CVS supports the concept of multiple users. These users are allowed to commit and checkout files in all directories in the repository. The ability read and write access for each user in the repository is a built-in capability of CVS and is controlled by the files. CVSROOT/readers and CVSROOT/writers files.
CVS does not have the capability to restrict commits by users at the directory/sub-directory level in a repository. There is a need by more than one user of CVS for fine grained access control in CVS at the directory/sub-directory level. Thus was born the CVSPermissions toolkit.
The pre-requisites for using the CVSPermissions toolkit are
CVS server must be running on a *NIX system (all the scripts have been written in /bin/sh). The clients can be on any platform though.
System Authentication must be used (SystemAuth=yes in CVSROOT/config)
The toolkit can be downloaded the open source software site Sarovar.org. The latest version of the toolkit is Version 0.3 and can be downloaded from the following link CVSPermissions Download page
Login as root in your *NIX system
create the directory /usr/local/bin/cvstools to host the files
untar the file cvspermissions-0.3.tar.gz in /usr/local/bin/cvstools
Ensure that all the shell scripts have execute permission chmod +x *.sh
CVSPermissions requires a one-time configuration that can be done anytime after a CVS repository has been created. This configuration is done using the configuration script cvspermsetup.sh. This script must be executed after you have logged into CVS. The sequence of steps is shown below.
<div> |
This script will create/modify the necessary files in the CVSROOT module of the repository to enable CVSPermissions.
New users in CVSPermissions belong to three categories.
Regular users: Users who have complete commit and tagging privileges for all the directories in the repository.
Restricted users: Users who have restricted commit and tagging privileges to some of the directories in the repository.
Read only users: Users who have read-only access privileges to the entire repository. They will not be able to commit/tag files to the repository.
For all the three types of users, the first step is to create an Operating system (OS) user. After an OS user has been created, the cvspermuseradd.sh script will help setup the different kinds of users
Regular Users: Regular users can be setup using the following command
<div> |
Restricted Users: Restricted users can be added using the following command
<div> |
This will setup a restricted user but the actual directory level permissions for the user is not setup now. The default setup will create a user with NO commit permission to the entire repository but complete read only access to the entire repository. A different script will setup the actual directory permissions.
Read-only Users: Read-only users can be setup using the following command
<div> |
An existing user can be removed from CVS using the following command
<div> |
This script will revoke all access permissions to an existing user in CVS. Further, this command will also remove all the directory restriction settings for a restricted user.
There are situations when a user has to be temporarily disabled from committing/tagging files to the repository. At a later point in time the same user has to be re-enabled with prior access restrictions intact. In such a situation, the following command can be used.
Disable user(s)
<div> |
Enable user(s)
<div> |
This section deals with commands that will help establish the access permissions for restricted CVS users. As described before, access control is at the directory level within a repository. Access includes, committing files and tagging files. The command cvspermuserdir.sh can add or remove directories to which the user has commit rights.
Add access rights for a directory
<div> |
Revoke access rights for a directory
<div> |
The directory name must be a full path of the directory name including the repository starting prefix. A partial directory name will result in allowing write access to directories that has this partial name as part of its path.
CVSPermissions is a group of shell scripts and configuration files. The shell scripts can be broken into two categories
Configuration Scripts: Scripts that will help the CVS administrator add users, modify directories etc.,. These scripts in turn add or change information in the configuration files that will be used by the Control scripts during CVS operations.
Control Scripts: Control scripts are executed by CVS server automatically when a particular action occurs. For example during file commits, tagging files etc., These scripts read information from the configuration files to determine whether the particular action is permitted. If the action is not permitted, it exits with return code 1 to indicate to the CVS server to abort the operation. The server in turn would communicate back to the client the error message returned by the control script.
CVSROOT/writers and CVSROOT/readers: These files are part of base CVS configuration. They control all the read/write accesses to the repository. User IDs present in these files are allowed to have read/write access to the repository. CVSPermissions uses these files extensively to control access to the repository. Further, it builds on top of this capability to provide directory level permissions.
CVSROOT/users.restricted: This file is used by CVSPermissions to determine the list of users who have restricted access in the system. The control script uses this list of users to determine whether further permission verification is required
CVSROOT/$USER.permission: Each user listed in CVSROOT/users.restrictedshould have a corresponding file that tracks specific permissions for that user. User level access permission is maintained in the CVSROOT/$USER.permission file.
In the CVS toolkit collection of scripts, the script cvspermissions.sh and cvspermtagcheck.share control scripts that will be triggered each time a file is committed or tagged to the CVS database respectively. These scripts get information from the various configuration files to determine whether the particular commit operation is valid. If the operation is invalid due to access permissions setup for the particular user in a folder, the script will exit with a return code of 1. This will cause CVS to fail the current process and return an error message to the person changing the file.
The configuration scripts will modify the information stored in the configuration files for the control scripts to work. These configuration files are in turned stored in the “CVSROOT” module of the repository. Further, these files are setup in such a way that any changes to them will cause CVS to rebuild its administrative database.
The shell script cvspermsetup.sh performs the initial setup of the repository including association of the control files with CVS commit operations and adding the configuration files to the CVSROOT module.