Software Configuration Management

---

Subversion and Mercurial are version control systems which introduce many features absent from CVS. The CIMS systems group operates an instance of Apache to serve subversion and mercurial repositories. While it is not neccesary to serve subversion or mercurial through Apache, doing so allows for greater flexibility in authenticaion and finer grained access control.

Repositories in home directories

If you don't intend to use subversion or mercurial with colloborators then there is no need to use the server. You may simply setup a repository in your home directory and access it through the local filesystem or over ssh. To create a repository simply execute the following command on a CIMS unix system (e.g., access.cims.nyu.edu), replacing path with the directory under which you would like to create the repository (for example, /home/username/repos):

For subversion:

svnadmin create --fs-type fsfs path

For mercurial

hg init path/project_name

Repositories hosted on CIMS SCM Server

To have a repository setup on the server submit our SCM Repo Request Form.  A description of the available authentication and access control methods follows.  This information applies only to repositories hosted on the CIMS SCM server and not to personal repositories.

Authentication

Except in cases where a repository is configured for anonymous access clients must authenticate to read or write to a repository. Authentication can be performed against CIMS accounts and/or accounts stored in a plain text file. The text file option is useful for situations where collaborators without CIMS accounts require access. When a repository is created you will be given the location of a text file to use for storing non-CIMS accounts. Insructions on how to manage this file are here.

Access Control

A repository can be configured to use one of two access control schemes: repository-wide access or path-based access. These schemes are mutually exclusive, it's either one or the other. Repository-wide access grants authenticated users read and write access to the entire contents of a repository. If repository-wide access is too coarse for your purposes, e.g., if you would like to grant some users read-only access, or limit the directories to which certain users can write, a repository can be configured with path-based access. It is possible to switch the access control scheme after a repository has been created, so if the access requirements change at some point it is not a problem. (Note: path-based control requires that the server perform access checks at each level of the repository, which produces a noticable delay for most operations. You should only request that a repository be configured with path-based access if it is absolutely necessary.)

Repository-wide Access

Repository wide access can be controlled through group information in LDAP (CIMS Unix groups) or a text file. Email helpdesk@cims.nyu.edu to grant a CIMS Unix group access to a repository. A plain text file can also be used to control access. The path of this file will be provided to you when the repository is created. Users can be added or removed with a text editor. The file will have the following form:

     <groupname>: <user> [<user>...]

An example:

     svn_users: peter kevin mary orlando

Do not change the group name, just the users included in the group. Valid users are either CIMS usernames or those specified in the non-CIMS account file described in the Authentication section of this document.

Path-Based Access Control

Path-based access control allows one to control access to a repository at the level of individual directories. Child directories inherit the permssions of parents unless they are explicitly overridden. Path-based permissions are defined in a text file whose location will be given to you when the repository is created. Path-based access have the following form:

     [groups]
     <groupname> = <user>[,<user>...]
     ...

     [<path in repository>]
     @<group> = [rw|r]
     <user> = [rw|r]
     * = [rw|r]

     [<repository name>:<path in repository>]
     @<group> = [rw|r]
     <user> = [rw|r]
     * = [rw|r]
     

An example of an access control file follows:

        [groups]
        subversion = jimb,sussman,kfogel,gstein,brane,joe,ghudson,fitz, \
                     daniel,cmpilato,kevin,philip,jerenkrantz,rooneg, \
                     bcollins,blair,striker,naked,dwhedon,dlr,kraai,mbk, \
                     epg,bdenny,jaa
        subversion-doc = nsd,zbrown,fmatias,dimentiy,patrick
        subversion-bindings = xela,yoshiki,morten,jespersm,knacke
        subversion-rm = mprice
        ...and so on and so on...

        [/]
        # Allow everyone read on the entire repository
        * = r
        # Allow devs with blanket commit to write to the entire repository
        @subversion = rw

        [/trunk/doc]
        @subversion-doc = rw

        [/trunk/subversion/bindings]
        @subversion-bindings = rw

        [/branches]
        @subversion-rm = rw

        [/tags]
        @subversion-rm = rw

        [/branches/issue-650-ssl-certs]
        mass = rw

        [/branches/pluggable-db]
        gthompson = rw
        ...

        [/secrets]
        # Just for demonstration
        * =
        @subversion = rw

For more infomation on path-based access please see http://svnbook.red-bean.com/en/1.6/svn.serverconfig.pathbasedauthz.html.

Anonymous Access

If you would like to have anonymous access setup for a repository then the repository must also be configured with path-based access. Otherwise anonymous users will be able to read and write to the entire repository. If you would like to enable anonymous access to a repository contact helpdesk@courant.nyu.edu.

Using subversion

For information on how to use the subversion client you should consult the online documentation or download the PDF. Section 1 covers the fundamental concepts of working with subversion and section 2 describes basic usage of the subversion client. To access a repository on the CIMS server you will need to know its URL. This generally will be of the form https://subversive.cims.nyu.edu/repository name/ where repository name is the name of the repository.

Using mercurial

For information on how to use the mercurial client you should consult the online documentation. In particular, Chapter 2 covers the basics of using mercurial. To access a repository on the CIMS server you will need to know its URL. This generally will be of the form https://subversive.cims.nyu.edu/repository name/ where repository name is the name of the repository.