CVSNT Installation Background

Author: Bo Berglund
Notice 1:
This guide is not maintained and is only made accessible as-is. It was once written for installation help when the main obstacle was using the Windows NT4 operating system. Since that time much has happened that makes the guide obsolete or simply outdated and I don't have time to maintain it. The basic info is still OK, but details vary.

I have received numerous emails privately and seen a number of mail list postings complaining about the difficulty of getting the CVSNT system up and running. So to help out I have actually stepped through the process on a "naked" NT4 WorkStation and noted the different steps needed.
Apart from minor operating system details (like where the path variable is set), these steps work the same way on Win NT4, Win 2000 and Win XP-Pro (I have tested all).

Notice 2: This guide is rewritten on Dec 23rd 2002 to describe the new way of installing CVSNT that has been introduced recently. The reason I have done this is that many users have had problems getting it up and running. The guide is substantially the same as before, but it contains new screenshots from the setup sequence and tips on how to set it up correctly.

IMPORTANT - use a local disk!
CVSNT does not work properly unless the repository files are located on a disk on the local PC. Don't try to use a network drive or a mapped disk (not even a mapped disk aimed at the local PC)!
It will not work and there are numerous reasons, here is one:
CVSNT runs as a service and thus acts as the SYSTEM user account. This account has no permissions on the network and so cannot access the files if they are on a remote server. In fact if the files are on the same PC does not help either if they are accessed using the network via an UNC path. The dive is still considered to be on the network where SYSTEM cannot operate.
So don't even try to create such a configuration!

If you are worried about backup of the repository and you don't have a backup system running on the CVSNT server itself, then use a scheduled task that runs under a known account (like your own) and does this (put this into a batch file and sun this from the schedule):
net stop cvs
xcopy d:\cvsrepo \\server\cvsbackup /Q /S /C /H /R /O /Y
net start cvs
The account you use must have permissions on the server share the files are copied to.

Table of contents
CVSNT Installation steps
Adding CVS users
Adding CVS administrators
Disabling pserver as security measure
The cvs passwd command for adding users
Managing pserver users
Connection problem over named pipe with :ntserver:
Using the SSPI protocol
Fine-tuning user access of CVS
Automatic email on commits and other events
Using spaces with CVSNT
Adding new modules to CVS

This procedure works to get CVSNT up and usable:

Note: I don't have a domain, so the workstation used is belonging to a workgroup in a home LAN environment with 5 other machines of various systems (W98, NT4 WS, Win2000Pro, XP-Pro).

Steps to take:

0. File system type
Make sure your system is only using NTFS file system! If not then convert using the NT tool for conversion. 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!

1. Get the latest release of CVSNT
Download the latest CVSNT installation from http://www.cvsnt.org/, currently 1.11.1.3 build 63. (2002-12-23): CVSNT Latest version

2. Create CVS directories
Create two directories on the target machine, c:\cvsrepo and c:\cvstemp. If you have a separate disk partition to spare for CVS then use that instead, replace the paths with these, example:
f:\cvsrepo
f:\cvstemp
The important point here is that the disk where the repository is located on is NTFS.
Where CVSNT itself is installed in not important, it can be on FAT32 or NTFS or whatever.
In the discussion below I assume that C: has been used.
3. Directory security and permissions
Give c:\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 in Win2000 and Win-XP!

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!)
Note: CVSNT has changed the installation system recently so you will see slightly different sceens than you are used to with InstallShield. I have included a set of screens here for your reference.
Start screen:


License agreement:


Install directory selection:


Anti-virus software warning:


Installation component selection screen:


Note that the CVSNT server itself may not be checked here!
Make sure to check all components like this:


Shortcut folder selection screen:


Task selection screen:


Ready to install!


Install progress


Installation done!



5. Path to CVSNT
Note that the installer probably complains about being unable to set the path environment variable at the end. If so:

6. Open Control Panel/System and go to the Environment tab so you can set the *system* variable path. (Location of this setting page varies between NT4, W2000 and XP, you will have to look around a bit). Add ;c:\programs\cvsnt to the end of path and save it (Apply).

7. CVSNT Control Panel configuration
Open Control Panel and look for the CVSNT applet (the green fish):


Start the applet with this icon:

Note:
If you have problems locating the CVSNT Control Panel applet it might be because one or several of a few system dll:s are missing. These are supposed to be installed by CVSNT Installer but sometimes this does not happen. The files you need can be exctracted from the binary download of CVSNT:
Precompiled binaries for CVSNT
These are the files that might be missing:
mfc70.dll (needs registration)
mfc70u.dll (needs registration)
msvcp70.dll
msvcr70.dll
Copy them to the %windows%\system32 folder.
Now open the CVSNT control panel applet and do the following:
7a. Check that the service is not running (Start button is enabled). If it has started then stop it. This is the initial screen:



7b.Go to the tab "Repositories". It will initially look like this:


Now check the check the box for prefix and browse to the directory c:/cvsrepo using the ellipsis button.


The dialogue will look like this when you have navigated to c:/cvsrepo:

Note that when you navigate to the root of your CVS repositories to set the prefix, you cannot use the drive itself - you must go down at least one level in the directory tree (like to c:/cvsrepo). This is because the control panel GUI adds an erroneous extra slash to the prefix for drive roots and then the prefix stops working....
So don't stop with the dialogue looking like this:


7c. Use the Add button to add a repository. Enter TEST after the prefix in the box that appears. Accept the offer to create the repository. You can have several separate repositories on the same server, in that case you will use the Add button once for each repository you need. Once the list of repositories contain those you want you are done here.
Note: If you use Repository prefix and have more than one repository they must all be located at the same top directory (= the prefix). There is only one setting for Repository Prefix on CVSNT.
This is how it will look like after you have created the first repository "test":


Later when you return to the Control panel applet this screen will instead look like this. Note that the repository has now been stripped of the prefix.


7d. Go to the Advanced tab and view the checkboxes. (Note that from build 57i the TCP/IP checkbox has been removed.)

Here you have three options to set/clear:
- Support ntserver protocol. This is what CVSNT has been using for NT connectivity, but it is being phased out in favor of the SSPI protocol, which works over TCP/IP.
- Impersonation enabled. This setting allows CVSNT to operate in the guise of the user actually doing the command. So with this flag on you can use file system permissions.
- Use local users instead of domain. Use this if you don't have a domain to authenticate against. Note that in this mode your users must have valid accounts on the server PC itself.
For these tests check all checkboxes. You can later go back and change these settings.




7e. Also set the temp dir using the ellipsis button. It should be set to c:\cvstemp

7f. 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:



8. 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!):


You might have trouble here (I did not check this) with the path variable change needing a reboot to register. (Check this by opening a command window and type path (enter). Look for c:\programs\cvsnt in the list that appears. If it is there you don't have to reboot...)



9. Adding CVS users
This is a step that is only needed if you plan on using the pserver protocol with this CVS server. If your users are all on Windows PC:s this is not recommended since it has inherent security flaws. Instead use SSPI or ntserver (but ntserver is being phased out now) because these protocols integrate much better with Windows NT. If you decide to go with sspi (recommended) then you can skip the discussion on how to add and manage users in this section.
But if you really must use pserver then:
Open a command window and do the following (replace items <text> with the real values from your system).
Note: for ntserver the computername cannot be entered as 'localhost', it must be the real name of the PC.:
set cvsroot=:ntserver:<computername>:/TEST
cvs passwd -a <your NT username>
You will now be asked to enter a password for this user. If you intend this system to be used both with ntserver and pserver then add a password for CVS that is different from the real login password for this user (security reasons). Enter the same 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 even if you are going to only use the pserver protocol in the future since there is no way to log in with pserver 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. But you can "alias" a CVS login to a "real" user by this command:
cvs passwd -a -r <real accountname> <cvs account name>
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 -a -r "system admin" "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.)

Note 2 (Domain users):
You can add domain users with the following command:
cvs passwd -a -r <real accountname> -D <domain name> <cvs account 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.

Note 3:
A user has reported that before a login that has been added like this can be used the CVSNT service needs to be restarted. This applies to Windows XP.
I have not tested this myself, so if someone having problems with user logins can test this and report back to me I would be grateful.

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

10. 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)

Using WinCvs (ver 1.3):
Step 10 can be performed from another computer using WinCvs by setting the WinCvs preferences like this:
Admin/Preferences/General:
Authentication: pserver
Path: /TEST
Host address: <computername of server>
User name: <the user name you entered above>



then:
Admin/Login (enter CVS password for this user)

then in the command window in WinCvs:
cvs ls -l -R
should give you the same result as above:

Example:
cvs -z9 login
Logging in to :pserver:bosse@castor:2401/test

*****CVS exited normally with code 0*****
cvs ls -l -R

*****CVS exited normally with code 0*****

Listing modules on server

Directory CVSROOT

checkoutlist 1.1 Sat Mar 16 23:22:16 2002
commitinfo 1.1 Sat Mar 16 23:22:16 2002
config 1.1 Sat Mar 16 23:22:16 2002
cvswrappers 1.1 Sat Mar 16 23:22:16 2002
editinfo 1.1 Sat Mar 16 23:22:16 2002
loginfo 1.1 Sat Mar 16 23:22:16 2002
modules 1.1 Sat Mar 16 23:22:16 2002
notify 1.1 Sat Mar 16 23:22:16 2002
rcsinfo 1.1 Sat Mar 16 23:22:16 2002
taginfo 1.1 Sat Mar 16 23:22:16 2002
verifymsg 1.1 Sat Mar 16 23:22:16 2002



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.

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).
Disabling any protocol on the CVSNT server is done by physically deleting the corresponding xxx_protocol.dll file from the CVSNT programs directory. There is no registry or other switch for this purpose.
In this case erase the pserver_protocol.dll and then restart the service as a safety measure.

Adding new pserver users using the cvs passwd command

As soon as you are logged on using pserver with a cvs login that either is the same as a local system admin or is aliased to an admin then you can also 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 users

If you plan on using pserver with a fairly large number of different user logins then you might want to do as follows:

• 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.

Connection problems using the :ntserver: protocol

There are some reported problems that can occur when connecting to a CVSNT server using the :ntserver: protocol.
The most common one is a report that the 'named pipe' could not be connected.
If the client and server are on different sides of a firewall then this is quite normal since the named pipe method uses network communications that are not normally open through a firewall because they are too insecure from intrusion. If this is the case for you then consider switching to the :sspi: protocol and ask the firewall maintainers to open port 2401 through the firewall. The :sspi: protocol uses encryption for its communication and is considered fairly safe.
If you are on the same network and still see the named pipe error message then this is often an indication that there is insufficient trust between the client computer and the server. If the two are members of the same domain and you have logged on to the client PC using domain login rather than local login, then this problem should not appear.
But in these circumstances the named pipe error may occur (there may be more cases):

• Client is NT4WS and is not connected to the server domain. The server does not trust the workstation.
• Client is NT4WS and is member of the server domain, but the user logged on to a local account. The server does trust the workstation, but has no knowledge of the user account trying to connect.
• Client is NT4WS and the server is not connected to a domain. In this case the server does not trust the client PC and the named pipe cannot be connected.

Using the SSPI protocol for CVSNT access

Recently the SSPI protocol was added to CVSNT. It works over TCP/IP so it can more easily traverse firewalls. Like :ntserver: the :sspi: protocol does not need a login, instead the login you did when you started your workstation is used with this protocol.
I don't have personal experience using this protocol, but I have collected a few tips on its properties and use. So here goes:

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.
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
5. Important: Create a directory outside the repository where CVS can store the lock files and make this directory read/write for all CVS usergroups. For example you can use c:\cvstemp\locks, provided you created the temp dir as instructed above.
6. Checkout CVSROOT of your repository and edit the config file so that it contains the line
   LockDir=c:/cvstemp/locks
   Commit your change and restart the CVSNT service using the Control Panel applet.

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 firm 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 filenames 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!

Adding new modules to CVS

There are two ways to set up a new module in a cvs repository, the cvs add and the cvs import methods. They have some pros and cons to each as follows:

cvs import
This is the method mostly talked about in CVS tutorials and it works like this from WinCvs:

• Activate the Create/Import menu command
• Navigate to the source of the module files on your hard drive
• Check the state of all types of files in the list and change it to suit
• Specify module name on the CVS server and the release and vendor tags (Import settings tab)
• On the General tab specify the server and repository where the module should go
• When you hit OK your source files will be imported into the CVS repository
• Now you have to check out the module to your working files area (=sandbox). You cannot use the source directory as your checkout target, it must be non-existing.
• Done!

• The imported files per default wind up on a branch and get the revision 1.1.1.1
• There is no security for this command! If there already exists a module on the server with the name you are giving the new module then the command happily adds your files to the existing module and even adds new revisions to those files that may already exist! This most probably will destroy the existing module's structure!

cvs add
This method is seldom mentioned for main module additions, basically because it is a bit labor intensive...

• Create/Checkout Module from WinCvs menu
• Enter a single . (period) as the module name to check out in the 'Checkout settings' tab
• Browse to the folder on your working files disk where you have the source files and set the 'Local folder to check out to' to the folder where this folder is stored (one level up).
• Check the 'Do not recurse' checkbox. This is important!
• On the General tab make sure the server data are correct
• After you give the OK command there will be one single folder (CVS) created in your sandbox
• Now change location in WinCvs to the folder containing your sources folder. There will be a black checkmark on the parent folder.
• Select the module folder in the right hand panel and click the Add button. A checkmark will appear.
• Move into this folder and select all text files inside that need to be part of the module and click the Add button. They turn red.
• Also do the same for the binary files, except click the 'Add binary' button instead.
• Now select the module folder in the left hand pane and commit.
• This adds the new module folder and its files to the CVS server.

• All files are starting out on the TRUNK with revision 1.1
• If the module is already existing on the server there will be an error message
• You can continue working with your sources from the location they were in, no need for a checkout to create the working file set (sandbox). You have effectively converted your existing source files to a versioned checkout.

• Every single folder and file must be individually selected and added. This can be rather tedious work if you have many files and subfolders.

As usual the method selected for module creation will depend on preferences. If you really don't want initial revisions to be on the branch and you want to be sure an existing module is not overwritten then use the cvs add method.
If on the other hand you don't have the time needed then use the cvs import, which is inherently faster. But be aware of the security risk you may encounter....

Afterwords

The above is revised 2002-12-23 and is based on using the CVSNT version I have current access to (1.11.1.3 build 63).

I hope this helps those of you who could not get CVSNT to work.
Also note that build 51 has a serious bug in the passwd command that actually mangles the file contents so it will be unusable. Therefore you MUST use the most recent version from CVSNT for the instructions above to work.

Comments? Send me a message: Bo Berglund

Unique visit counter started 2002-12-08: