Author: Bo Berglund
Notice:
This guide is written as an installation help for CVSNT 2.5.03 and higher on Windows 2003 server.
Most of the discussion is also valid for installation on Windows XP-Pro (see below for an important setting).
NOTE! You cannot use XP-Home for CVSNT!
The guide uses the Innosetup based installer that I maintain but similar results can probably be obtained by using the Innosetup installer published by Oliver Giesen as well.
I am not using the MSI installer from the official CVSNT website since I cannot accept non-opensource software if anything else is available.

Table of contents
CVSNT Installation
Configuring the server
Adding CVS users
Adding CVS administrators
Disabling pserver as security measure
The cvs passwd command for adding users
Managing pserver and sserver users
Using the SSPI protocol
Fine-tuning user access of CVS
Using spaces with CVSNT

Links:
CVSNT Auditing Configuration Tutorial
Innosetup CVSNT Installer download
CVSMailer homepage, Automatic email on commits and other events
ViewCvs Installer download
CVSNT command reference
CVSNT download (where you can download the latest CVSNT versions)

Karl Fogel's book 'Open Source development with CVS'
The free part of Karl Fogel's book in HTML format
DevGuy's CVS information pages
CVS-Gui (WinCvs) homepage
WinCvs Dialy use guide
WinCvs 1.3 manual (PDF format)

WinCvs download (on SourceForge)

Installation of the CVSNT server

File system type
Make sure your system is only using the NTFS file system!
Also make sure you are logged on as an administrator of the PC (using an account with administrative priviliges).
And most important: Use the local disk on the CVSNT server!

IMPORTANT for XP-Pro users:
You MUST switch off Simple File Sharing, which is the default for XP (as recommended by Microsoft to make XP somewhat compatible with Win95-98-ME)!
You do this by opening a Windows Explorer and then use the menu command Tools/Folder Options. Select the View tab and scroll down to the bottom where you find this item. Uncheck it now!


Now for the actual installation and configuration:

1. Get the latest release of CVSNT
Get the latest CVSNT Innosetup installation from Innosetup CVSNT Installer download

2. Create CVS directories
Create two directories on the target machine, c:\cvsrepos and c:\cvsrepos\cvstemp. If you have a separate disk partition to spare for CVS then use that instead. The important point here is that the disk where the repository is located on is NTFS.

3. Directory security and permissions
Give c:\cvsrepos\cvstemp security settings that allows full control for all accounts including SYSTEM.
Important:
The cvstemp directory must NOT be located in either c:\WINNT\Temp or anywhere in the "C:\Documents and Settings" tree because these locations have imposed restrictions on user access!
Notice that on XP-Pro out of the box from Microsoft the permissions cannot be set like this until "Simple File Sharing" is switched off (see above). So you must do this if you use XP-Pro. XP-Home is totally unsuitable for CVSNT!

4. Install CVSNT
Run the downloaded CVSNT setup file and make sure to change the installation path to c:\programs\cvsnt (I am paranoid about removing any spaces in paths used by cvs!)
Start screen:


License agreement:


Install directory selection:
Note:
I strongly recommend that you install CVSNT to a path that does NOT contain any embedded spaces, for example like this:


Installation component selection screen:


Start menu selection:


Task selection screen:


Ready to install!


Install in progress


Release notes


Installation done!

Configuring the CVSNT server and repository

1. CVSNT Control Panel configuration
CVSNT is configured from the CVSNT Control Panel, which can be reached via the shortcut link placed under the Start menu during installation.


Now open the CVSNT control panel applet and do the following:

2. Shut down the CVSNT service
Check that the CVSNT Service is not running (Start button is enabled). This is the initial screen showing that both services are running:


If it is started then stop it. You can leave the Lock Service running.

3. Repository creation
The tab will initially look like this:



4. Add repository
Now you will add a repository to the server. This is done using the "Add" button. When you click this a dialogue shows up where you will define your repository.



5. Repository folder
Click the ellipsis button for Location to bring up the folder browser.
Now you can browse to the location you want for your repository and add a new folder here.
NOTE:
I strongly advice NOT to use paths with embedded spaces for CVS!



6. Name repository
Now fill in the description and the name of the repository as well.
NOTE:
Do NOT accept the suggested name, which is the same as the folder path!
Instead only use the bare folder name with a leading / like this:



7. Initializing the repository
When you click the OK button there will be a dialog where CVSNT offers to initialize the new repository.
When you click Yes then the new folder will be converted to a real repository:




8. First repository added!
Now the list of repositories has been populated with the first repository:




You can add as many as you like (almost) but please do not fall for the temptation to use one repository for each and every project! There are a lot of possibilities to streamline the development process using CVSNT, but many of these use the virtual modules concept and this is only possible within a single repository.


9. Server Settings
Now go on to the Server Settings tab.
Here the default settings are all right for now, except the Temporary Directory setting.



NOTICE about Domains:
You can set the Default domain entry to either the CVSNT server PC name (as in the example above) or the domain name to which the CVSNT server belongs. CVSNT will strip the domain part from all accounts that log on using the default domain before processing. All other logons will be processed using their complete names (DOMAIN\username). The result of this is that all users that "belong" to the domain specified in this box will be logged using only the account name, likewise these usernames will be supplied to the administrative scripts without the domain name. All others will have a domain name added. This must be accounted for in any admin script used.
The CVSROOT/users file is one such admin file that needs to be handled with care concerning domain and non-domain entries.

Temp dir: Use the ellipsis button to browse for the folder prepared for this purpose above:



10. Compatibility
On the next tab (Compatibility Options) there is nothing you need to change for now:




11. Plugins and protocols
The Plugins tab define a lot of the extra features of CVSNT including some aspects of the connection protocols. The sceen list the available plugins and when you select a line you will be able to configure this plugin by clicking the configure button:




12. Sserver configuration
Here is the configuration window for the SSERVER protocol plugin. Please set it like this:




13. Advanced settings
The final tab on the Control Panel deals with advanced configuration settings and you need not change anything here.




14. Apply configuration changes
Now click the Apply button! This is really important, nothing will happen unless you do this! Note that after you have done this the Apply button is disabled.

15. Start the CVSNT service
Go back to the first tab and click the Start button. After a few moments the Stop button will be highlighted.
Now CVSNT runs (success!)

16. Restart the server
In order for you to be able to use the command line cvs you need to have the path variable set to include the location of the cvs.exe just installed (c:\programs\cvsnt). Since the installer will have put this into the system path variable it will work if you restart the server.
You can check this by going to a command window and typing the command:
cvs --ver
If this results in an eror message then you should restart the server PC before continuing.

Adding and managing CVS users for pserver and sserver access

This is a step that is only needed if you plan on using the sserver or pserver protocols with this CVS server. If your users are all on Windows PC:s pserver is not recommended since it has inherent security flaws. Instead use SSPI because that protocols integrate much better with Windows. If you decide to go with sspi (recommended) then you can skip the discussion on how to add and manage users in this section.

1. Creating CVS accounts on the server
In order for pserver and sserver to work you have to define CVS users, but before you can do this you need to create two real accounts on the server. These accounts will be used by the CVS users as the working accounts.
You need one account which will be a CVS administrative account and one which will be a normal user account. Note that the CVS administrator need not be a server administrator!



The two accounts are added through the Users dialog in Computer Management.
I have used the account names cvsadmin and cvsuser as shown above.

2. Adding CVS users
Open a command window and do the following (replace items <text> with the real values from your system).

set cvsroot=:sspi:<computername>:/TEST
cvs passwd -a <account name>

You will now be asked to enter a password for this user. This password is only for CVS use so it should not be the real system password! Enter the password twice.
Now the CVSROOT/passwd file will be created and the user you entered will be added to the list in this file.
This step is necessary if you are going to use the pserver or sserver protocol in the future since there is no way to log in with pserver/sserver unless there is a passwd file present with the user listed.

Important note:
Any user entered like this MUST be an NT user on the local system! CVS will not accept any user login that is not connected to a "real" account.

3. Aliasing CVS users to real accounts
In order to have many CVS user logins you don't need to create masses of system accounts! Instead you can "alias" a CVS login to a "real" account using this command:

cvs passwd -r <real accountname> -a <cvs login name>

What will happen now is that to CVS the user will be known and registered as the CVS login given in the command, but for file operations that will encounter permission issues the commands will be executed in the context of the real system account that was aliased. This makes it possible to use NTFS file system permissions to limit access to certain parts of the repository to some users. You simply create a system account for which you set limited permissions and then you alias the CVS login to this user.

Note that this command will fail if there is a space embedded in the real account name! DON'T ever use spaces in these contexts!!!!! (But using quotes may solve the problem like this:
cvs passwd -r "system admin" -a "new user"
Since I don't have a valid user with embedded space I could not check the quotes trick with the valid user name parameter, but adding a CVS login with space embedded *can* be done with quotes.)

Examples:
cvs passwd -r cvsuser -a charlie

or if you want the new user to be a CVS administrator:

cvs passwd -r cvsadmin -a rogerh

Note about Domain users:
You can add domain users with the following command:
cvs passwd -r <real accountname> -D <domain name> -a <cvs login name>
This command is reported by a user to have worked for him. I cannot check it because I don't have a domain. But based on information from the mail list I think that it will only work if there is a trust between the CVSNT server PC and the domain controller. If the CVSNT server PC is a member of the domain then this is the case.

The server is now ready to be used and you can check the pserver functionality by doing this:

4. Testing the CVS connection with sserver
Open another command window and type:
set cvsroot=:sserver:<user>@<computername>:/TEST
Replace <user> and <computername> with valid entries like:
set cvsroot=:sserver:charlie@cvsserver:/TEST

Then:
cvs login (enter password on prompt)
cvs ls -l -R
(this should give you a list of the files in TEST/CVSROOT)

5. Testing the CVS connection with pserver
Open another command window and type:
set cvsroot=:pserver:<user>@<computername>:/TEST
Replace <user> and <computername> with valid entries like:
set cvsroot=:pserver:charlie@cvsserver:/TEST

Then:
cvs login (enter password on prompt)
cvs ls -l -R
(this should give you a list of the files in TEST/CVSROOT)

6. Testing the CVS connection from another PC
Open a command window on another PC where you have installed the CVSNT in client only mode and type:
set cvsroot=:sserver:<user>@<computername>:/TEST
Replace <user> and <computername> with valid entries like:
set cvsroot=:pserver:charlie@cvsserver:/TEST

Then:
cvs login (enter password on prompt)
cvs ls -l -R
(this should give you a list of the files in TEST/CVSROOT)

If you cannot get this far, for example if the login fails, then you should check the Windows Firewall settings on the CVSNT server:

7. Modifying Windows Firewall to allow CVS calls

• Go to Control Panel
• Open the Windows Firewall item.
• Select the Exceptions tab
• Click the "Add port" button
• Enter the name CVSNT and port number 2401 as a TCP port
• Accept back to the main screen
• Make sure Windows Firewall is set to ON

 

Administrating the repository, users with admin rights

There have been a number of reports that people have not been able to add users or execute the cvs admin command even though they were members of the Administartors group or even of Domain Admins. In order to avoid this there is a simple way to manage who will have admin rights on the CVSNT server. It is done through the CVSROOT/admin file.
Here is how to:

• Create a text file called admin (no extension) inside the CVSROOT directory of the repository.
• Edit this file by adding on separate lines the login names of the users you want to give administrative priviliges on the CVS server.

The file could look like this:
cvsadmin
charlie
jennifer
john

Now each of these users are able to add new users, change their passwords and use the cvs admin command.

 

Disabling the pserver protocol

If you are exposing your CVSNT server to the Internet you should disable the :pserver: protocol because it uses too low security levels. Only the password for login is 'encrypted' and this is only barely so. All other traffic is in cleartext...
To protect your data you should use the :sspi: protocol instead (and set its encryption flag of course).
As an alternative with the same basic functionality as pserver you can use sserver instead. This uses encrypted connections by default and is probably better if you want to add cvs logins that do not correspond to real accounts (see above).
Disabling any protocol on the CVSNT server is done through the CVSNT Control Panel Plugins tab.
Select the :pserver: protocol line and click Configure. This will bring up a dialogue where you can just uncheck the checkbox to disable the protocol:

Adding new pserver users using the cvs passwd command

As soon as you have logged on using pserver or sserver with a cvs login name that is the same as a local system admin or is aliased to an admin account or is listed in the CVSROOT/admin file then you can add and delete CVS user logins with the passwd command. Here is the full syntax for this command:

Usage:
cvs passwd [-a] [-x] [-X] [-r real_user] [-R] [-D domain] [username]
-a Add user
-x Disable user
-X Delete user
-r Alias username to real system user
-R Remove alias to real system user
-D Use domain password

Example:
cvs passwd -r charlie -a john
This adds a CVS login john with a system alias to account charlie. When the command is executed there will be a password dialogue that asks for the password of john twice for confirmation. Note that this is NOT the actual system password of account john, it is the CVS login password only used by CVSNT.
After the command completes there will be a new line in the CVSROOT/passwd file looking somewhat like this:
john:KacIT8t1F/SKU:charlie
The part between the :: is the DES encrypted password you typed in and will be used by the CVSNT service during login to validate john. Once accepted the account charlie will instead be used so the password is no longer used. The CVSNT service has full priviliges to act on charlie's behalf and this is what it does too.

Managing pserver and sserver users

If you plan on using pserver or sserver with a fairly large number of different user logins then you might want to do as follows (also described above):

• Create a local user on the CVSNT server by the name of "cvsuser".
• Login to the cvs server using an admin account.
• Add the logins with the following command to alias to the cvsuser:
  cvs passwd -r cvsuser -a <login user name>
  You will be asked twice for the login password.

You may add as many pserver users this way as you like. They will all be individually identified by the login name even though the operations on the repository will be done in the cvsuser account context. Mail systems will recognize these user names as well (see below).

 

Using the SSPI protocol for CVSNT access

A few years ago the SSPI protocol was added to CVSNT. It works over TCP/IP so it can more easily traverse firewalls. Like :ntserver:, which is now depreciated, the :sspi: protocol does not need a login, instead the login you did when you started your workstation is used with this protocol.

Limiting user access with sspi
When used normally sspi will accept connections from all system users that authenticate against the system (local or domain). Often this is not really what we want, instead we want to use the same mechansism as is used with :pserver:. Here the CVSROOT/passwd file limits the logins accepted by CVSNT to those mentioned in the file.
With :sspi: this is quite possible, you only have to list the account login names that you want to give CVS access in the passwd file. You also have to set the parameter
SystemAuth = No
in the CVSROOT/config file.
Note that in this case there is no need for entering passwords into the passwd file, sspi uses the system login and the passwd file is only used as a list of accepted users. So simply issuing this command when logged in as a CVS administrator will work:
cvs passwd -a newuser
(press enter twice to tell CVSNT that no password is used)

Fine-tuning user access of CVS

The NTFS file system permissions can be used to tune the access to the CVS repository with more granularity than the passwd file allows. Here is how it is done:

1. Create a number of NT user groups where members can be added and removed easily.
2. Don't use aliases in the login scheme, let each user login as himself, for example using :sspi:.
3. Set permissions (read/write, read only, no access) on the module level in the repository using the CVS groups as tokens.
4. Give membership to the CVS user groups as needed to individual NT accounts

 

Using spaces with CVSNT

CVSNT tries its best to handle spaces embedded in file and directory names. But there still are instances where the use of spaces breaks the CVS functionality badly. So my recommendations are:

1. Install CVSNT to a path that does not contain spaces.
2. Place the repository on a path not containing spaces.
3. If you install additional software like PERL or RCS, don't use spaces!
4. Instruct your users not to use spaces in directory names that are to be handled by CVS.

People may argue that CVSNT handles these issues for them, but in my experience this is only partly true. For example the loginfo and notify script parsing breaks fully when handling files with embedded spaces. There are other places as well...
Also by allowing spaces you will make it impossible to later move the repository to a *nix system (Unix, Linux etc).
So you are much better off prohibiting spaces up front!

Afterwords

This tutorial is written 2005-11-16 and is based on CVSNT version 2.5.03.2148.
The test system is Windows Enterprise Server 2003 with SP1 installed running in Virtual PC 2004 SP1 on my development PC. The server is not member of a domain.

Comments? Send me a message: Bo Berglund