InstallationTips - The CVSNT Wiki

CVSNT Installation Tips

Reference Books
CVSNT Installation Background
1. Backup Strategy
How to get CVSNT up and usable
Configuring CVSNT now that it has been installed
Adding new modules to CVS
1. cvs import
2. cvs add
Migrating from 1.11.3.x to 2.0.x
Afterwords

1. Reference Books

If you are completely new to CVS, you may want to start with this book, Essential CVS by Jennifer Vesperman and publsihed by O'Reilly; ISBN 0-596-00459-1; http://www.oreilly.com/catalog/cvs/.

Once you get more into CVS, and/or want something more compact to read, there is CVS Pocket Reference, 2nd Edition by Gregor N Purdy, and also published by O'Reilly; ISBN 0-596-00567-9; http://www.oreilly.com/catalog/cvspr2/

Please note that both these books deal with traditional CVS rather than CVSNT, so don't expect to see details of the CVSNT specific features within.

2. CVSNT Installation Background

Original Author: Bo Berglund

I have received numerous emails privately and seen a number of 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: This guide was rewritten on 23-Dec-2002 to describe the new way of installing CVSNT that has been introduced recently, because many users had problems getting it up and running. The guide is substantially the same as before.

Notice: This guide is being extended again in mid-Jul-2004 to bring it up to date for the most recent stable release of CVSNT (currently 2.0.46).

2.1. Backup Strategy

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 run this from the schedule):

net stop cvsnt
xcopy c:\cvsrepo \\server\cvsbackup /Q /S /C /H /R /O /Y
net start cvsnt

If you have http://cygwin.com/ installed you may also use something like this :

net stop cvsnt
TODAY=`date +%Y-%m-%d`
tar c /cygdrive/c/cvsrepo | bzip2 -9 > /cygdrive/shared-drive-lettre/cvsbackup-${TODAY}.tar.bz2
net start cvsnt

The account you use must have permissions on the server share the files are copied to.

3. How to get CVSNT up and usable

3.1. Plan to Install to a Local NTFS Disk

Essential: The repository and temporary directory must be on a LOCAL (not networked) disk on the CVSNT server.

CVSNT will 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 drive is still considered to be on the network where SYSTEM cannot operate.

So don't even try to create such a configuration!

NTFS is strongly recommended, for the sake of security and disk integrity. Although FAT will work, running FAT on any server for any purpose probably isn't a good idea.

3.2. Know your binary file extensions

If you plan to put any binary files into your repository, make sure you know the file extensions for those types of files, and enumerate them in the cvswrappers file after you have installed and started your repository. There is a good starter list on the devguy web page http://www.devguy.com/fp/cfgmgmt/cvs/cvs_admin_nt.htm but you may need to add more. Just one example of an extension someone might need to add: Borland Delphi Form files, *.dfm, need to be added to the list so they are treated as binary.

3.3. Get the latest release of CVSNT

Download the latest CVSNT installation from http://www.cvsnt.org/,

3.4. Create CVS directories

Create directories on the target machine,

c:\cvsrepo (for the repository, which will contain modules, which will contain your files)

and

c:\cvstemp (for temporary scratch files used by CVSNT internally). If you have a separate disk partition to spare for CVS then use them instead, e.g. f:\cvsrepo and f:\cvstemp.

It is okay to use subdirectories for these key locations, example:

d:\AppsData\cvsrepo
e:\temp\cvstemp

Avoid spaces in the path leading to your repository.

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!

By the way, the CVSNT programs can reside on FAT32, NTFS or whatever. The default will be "c:\Program files\cvsnt\".

In the discussion below I assume that C: has been used.

3.5. Temporary directory security

Give c:\cvstemp security settings that allows full control for all accounts including SYSTEM (remember: SYSTEM is not included in Everyone).

3.6. Install CVSNT

Run the downloaded CVSNT setup file.

Note: CVSNT has changed the installation system recently so you will see slightly different screens than you are used to with InstallShield. I have included a set of screens here for your reference.

Windows XP and 2003 Note: On some machines the WMI service may cause an access denied error. To prevent this you must stop the WMI service before the install and then restart the service after the install completes.

Start Screen:

License Agreement:

Install Directory Selection:

Install Component Selection Screen:

Shortcut Folder Selection Screen:

Task Selection Screen:

Ready To Install!:

Install Progress:

Installation Done!:

Be careful that you don't have some old cvs.exe client in your path, because it might not recognize the sspi method.

NOTE: If you get a error about genkey.exe, your installation is okay, but your ssl key was not generated, hence your :sserver protocol will not work correctly. -RC

3.7. Reboot

You must reboot after installing CVSNT for the first time for all NT/Win2000/XP installations. If you do not restart, you will get a "Repository initialization failed" error when you try to create a repository.

Note that it is not necessary to reboot the server if you are merely upgrading CVSNT. This is necessary because services will not see the updated system path until after the system is restarted.

3.7.1. Reboot?

I tested 2 installations with CVSNT 2.0.46 and did not need to reboot.

4. Configuring CVSNT now that it has been installed

4.1. Start CVSNT Control Panel applet

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

Start the applet with this icon:

4.2. Define your repository

Open the CVSNT control panel applet and do the following:

Check that the service is not running (Start button is enabled). If it has started then stop it. This is the initial screen:

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

Use the Add button to add a repository. You might use values like this:

Name: /AppsData/CVSRepo
Root: d:/AppsData/CVSRepo

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 (however it is noted (June 2004) that you probably only need 1 repository because it can contain multiple modules). Once the list of repositories contain those you want you are done here.
Go to the Advanced tab and view the checkboxes:

Here you have two options you can set/clear (leaving them at the default setting should be OK for most users):
- 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. There are security issues with disabling this option, so you would normally leave it enabled.
- Use local users instead of domain. Use this if your machine is a member of a domain but you don't want CVSNT to use domain accounts to authenticate.
- Set your temporary directory on the advanced tab, e.g. c:\cvstemp.
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:

4.3. Starting CVSNT

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!)

4.4. Updating your list of binary files

This subsection of instructions were tested on Win2000, on a machine where the logged-in Windows user was Administrator. Start from a DOS cmd window, in an empty folder such as c:\temp\sandbox\.

SET CVSROOT=d:\AppsData\CVSRepo
cvs co CVSROOT
cd CVSROOT
notepad cvswrappers

Make changes to cvswrappers, perhaps pasting in the default list from the devguy web page.

cvs commit

What did you just do? You checked out all the files from the CVSROOT folder, which would have been d:\AppsData\CVSRepo\CVSROOT in this example. You switched into the directory that you just checked out (CVSROOT). You modified one file, cvswrappers. You used the commit command to post the changed file back to the repository. You are now free to delete the c:\temp\sandbox\*.* files.

Of course, CVS works remotely, and is usually used from a remote machine. Nonetheless you may find that for some of the initial housekeeping tasks, it is handy to learn a few commands such as co (checkout) and update.

4.5. Users, groups and permission settings

Many of the instructions assume that you will use the Windows user groups and user accounts as the basis for your CVSNT logins. This is not the only option, and if it is not what you want to do, keep reading as you will discover an option that suits you. Many variations are possible, depending on which protocol is selected, and which configuration.

The reminders that pserver is an insecure protocol are to be heeded!

To use Windows users as the basis for CVSNT login, create a group called CVSUsers on the server and add all the CVS users as members of this group. Now login as administrator and right click on c:\cvsrepo and select properties. Click on the the 3rd tab for permissions, and give full control permissions for CVSUsers and SYSTEM accounts.

As an alternative, create just 2 or 3 user accounts (CVSADMIN, CVSWRITER and maybe CVSREADER), to which you will map pserver accounts using the admin, reader and writer files. (More on that below.)

4.5.1. Select your protocol(s) now!

The bottom line is that you will waste a lot of time if you do not select your protocol and login strategy early in the game. You will need to read about those choices elsewhere, but do it, otherwise you are not ready to benefit from the numerous tips below.

4.6. Adding CVS users

This is a step that is only needed if you plan on using the pserver or sserver protocol with this CVS server, and you want to add usernames who are not part of the standard NT user list. If your users are all on Windows PCs it is recommended that you use SSPI instead because it integrates much better with Windows NT. If you decide to go with SSPI then you can skip the discussion on how to add and manage users in this section. All :sspi: users must be valid user accounts and cannot be aliased.

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

th - removed a section about adding your own username - this would be better handled by setting SystemAuth=Yes (which I think is the default?)

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

You will now be asked to enter a password for this user. 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.

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 (only works if users connect with pserver):

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

If there are spaces in the account name you must use quotes otherwise the command will fail:

cvs passwd -a -r "system admin" "new user"

Note 2 (Domain users):

You can add domain users with the following command:

cvs passwd -a -D <domain name> <real account name>

This adds a user (who must be a real user on the domain) to the passwd file and tells CVSNT to verify the pserver/sserver password against the domain password for that user. Note that for this to work the CVS server PC must be a member of that domain!

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

4.7. Testing the CVS connection

Open another command window and type:

==== pserver, sserver or ssh ====
```
 set cvsroot=:<protocol>:<user>@<computername>:/TEST
 
```
Replace <user> and <computername> with valid entries like:
```
 set cvsroot=:pserver:charlie@cvsserver:/TEST
 
```
Then:
```
 cvs login(enter password on prompt)
 
```
==== sspi ====
```
 set cvsroot=:sspi:<computername>:/TEST
 
```
Replace <computername> with valid entries like:
```
 set cvsroot=:sspi:cvsserver:/TEST
 
```
==== ext ====

todo - needs explanation of external programs, how to set CVS_EXT (or CVS_RSH if we want legacy support)

Now you can type:

cvs ls -l -R

(this should give you a list of the files in TEST/CVSROOT

Using WinCvs (ver 1.3):

This step can be performed from another computer using WinCvs by setting the WinCvs preferences like this: Admin/Preferences/General:
Authentication: sspi (change this to whatever you prefer to use)
Path: /TEST
Host address: <computername of server>
User name: <your username>

then (if using pserver):
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

4.8. Administrating the repository, users with admin rights

Depending on the SystemAuth setting, CVS administrator rights are normally given to all users with administration rights on the machine the cvs server is running on. However, there is an alternate way to specify administrator rights which overrides this should it not work in your particular setup. 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:

charlie
jennifer
john

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

4.9. Disabling unwanted protocols

If you are exposing your CVSNT server to the Internet you may want to disable the :pserver:protocol because of its low level of security (The encryption used for the password is so poor as to be effectively plain text).

Disabling any protocol on the CVSNT server is normally done by physically deleting the corresponding xxx_protocol.dll file from the CVSNT programs directory.

In this case erase the pserver_protocol.dll.

Note that the setting 'Require Encryption' in the CVSNT control panel effectively disables pserver as it doesn't support any level of encryption. It also ensures that clients are using an encrypted protocol to communicate with the server. th - probably need a note here about Unix CVS clients, but the only encrypted protocol that they support really is gserver, which we've avoided mentioning

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

4.11. Using the SSPI protocol for CVSNT access

SSPI works over TCP/IP so it can more easily traverse firewalls. 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

System''Auth = 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)

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

Create a number of NT user groups where members can be added and removed easily.
Don't use aliases in the login scheme, let each user login as himself.
Set permissions (read/write/modify, read only, no access) on the module level in the repository using the CVS groups as tokens. If a group should have the privilege to make changes (commit files), then give read/write/modify permissions. If a group should not have commit privilege, then give only read permission.
Give all groups (including SYSTEM) read access on the CVSROOT folder, located under the repository folder. Only administrators should have write/modify access to this folder, with the exception of two files, as follows.
Give all groups read/write access to the file CVSROOT/history. This will enable everyone to find out who is doing what.
Give read/write access to the file CVSROOT/val-tags for all groups that should have the privilege to branch files or folders.
Give all groups read/write/modify access to the CVSTEMP folder, as described above.
Give membership to the CVS user groups as needed to individual NT accounts
Checkout CVSROOT of your repository and edit the config file so that it contains the line

LockServer=localhost:2402

Commit your change and restart the CVSNT service using the Control Panel applet. The reason you need to create the LockServer is that you cannot set a repository directory to read only because CVS needs to be able to create lock files for each operation even if the operation is not going to modify the repository. These lockfiles are normally stored in the repository itself and if it is read only then the operation fails.

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

Place the repository on a path not containing spaces.
If you install additional software like PERL or RCS, don't use spaces!
Instruct your users not to use spaces in filenames that are to be handled by CVS.

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!

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

5.1. 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!

need mention of import -C somewhere, which removes the need to checkout the module again. I don't think WinCVS supports it though

The pro with this solution is that all of the files and directories in the source are imported at once. Very convenient.

The con is that this creates a vendor branch. This is useful for importing third-party sources but disturbing for your own.

5.2. cvs add

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

...but it can be as comfortable as the above solution when using the "Recursive Add (auto-commit)" macro!

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.Pros of this solution:
Every single folder and file must be individually selected and added. This can be rather tedious work if you have many files and subfolders.

The pro with this solution is that all of the files are added to the baseline without vendor-branch. By using the WinCVS "Recursive Add" macro (pretty self-explaining) it is as comfortable as the import solution.

The con is clearly the amount of work it takes if you don't have macro-support available.

See also: Chapter 7. Project Management in the Essential CVS book.

6. Migrating from 1.11.3.x to 2.0.x

There is no change in the repository structure and it should be problem free to move a complete repository to a new CVSNT server. I have done so many times and no problems happened. Note that in order to be compatible across operating systems one should define a Repository Alias so that the connection string becomes something like this: :pserver:user@host:/cvsrepo Notice the absence of any drive letter and backslashes, these are Windows specific and should be avoided. Also notice the name of the repository, it is generally a bad idea to use cvsroot as the name of a repository because this name is used for many differing items in CVS lingo and in fact CVS creates a folder by this name in every repository. If you read my installation tips you will find that the names I recommend are cvsrepo for the repository and cvstemp for the temp dir....

7. Afterwords

The above is based on the original document by Bo Berglund, converted to Wiki from the original source sometime around 2003-03-26.

I hope this helps those of you who could not get CVSNT to work.

CategoryDocumentation