raven ioctl

CVS client configuration.

ioctl.org : unix bits and pieces : CVS stuff : CVS and SSH (Win32 client)

Setting up a Win32 client for using CVS via ssh

These days I reckon a good pairing is to use PuTTY as an SSH client and WinCVS as the CVS client.

Configuring PuTTY

Installation

PuTTY comes as a .zip archive; this should be extracted to an appropriate directory, for instance, c:\program files\putty\.

Key generation

Run c:\program files\putty\puttygen.exe. You should select the option to generate an SSH2 DSA keypair. Hit the "Generate" button (and wiggle the mouse as asked). A keypair will be generated for you.

You can (if you wish) use a passphrase to protect your private key; this is not necessary and a discussion of this is beyond the scope of these instructions. If you choose to do so, you may find it convenient to use the pageant program that comes as part of the PuTTY distribution to hold your passphrase. If you don't use a passphrase, then PuTTY won't need pageant to be running.

Save your public key (just call it "public" and save it in the default PuTTY directory). Similarly, save your private key (call it "private"). At this point, you may be asked to confirm that you wish to save the private key without a passphrase.)

At this point you can exit puttygen. You can now mail your public key to your CVS administrator; this will enable them to complete the configuration of your account on the CVS server.

Setting PuTTY's defaults

Run c:\program files\putty\putty.exe. In the session tab, choose the SSH protocol. In the connection/ssh tab, set the protocol preference to SSH 2. In the connection/ssh/auth tab, browse to your saved private key file - this will probably be c:\program files\putty\private. Finally, you should return to the session tab and save these choices as the default settings.

PuTTY will now default to using your keypair for authentication; you can close the dialog box at this stage.

First connection

The first time that PuTTY (or plink) tries to connect to the remote CVS server, you will probably find that it prompts you to accept a host key fingerprint that identifies the remote machine. If this first connection occurs from within WinCVS, that prompt will confuse it, so you need to run plink on its own first to deal with the fingerprint. The CVS administrator will have let you know what this fingerprint should be. If the value matches the one you're expecting, you should accept the host key and continue to connect. If the value does not match, you should contact the CVS server administrator for advice.

Once you have heard from the CVS server administrator, you should try connecting to the remote machine using plink. Run

c:\program files\putty\plink.exe jbloggs@cvs.server.name

and confirm your acceptance of the host key (if it matches the value you're expecting). If all goes well, you'll be connected to the remote machine - however, you won't get a prompt (since you're talking directly to a CVS server at that point). You can simply close down the plink window to close the connection at this stage.

Configuring WinCVS

Installation

WinCVS comes as a .zip archive containing a setup program; you should extract this to a temporary directory and run the setup. You should be able to accept all the defaults.

Configuration

When you run WinCVS, you'll be asked to configure it. You can access the configuration dialog in the future from the admin menu.

Under the general tab, set the CVSROOT to

jbloggs@cvs.server.name:/abs/path/to/cvs/cvsrep

and choose "SSH server" as the authentication method.

Under the globals tab, uncheck "checkout read-only" and "prune empty directories".

Under the ports tab, check the "alterate rsh name" and enter the path to PuTTY's plink program: probably

c:\program files\putty\plink

(assuming you installed PuTTY in the recommended directory).

Under the WinCVS tab: choose a HOME folder (generally the location of your "My Documents" will suffice) - this simply prevents WinCVS from bothering you for this in the future.

In the instructions above, you should replace jbloggs with the remote username that you've been provided with by the CVS administrator. Similarly, cvs.server.name and /abs/path/to/cvs/cvsrep should be replaced with the names of the remote CVS server and the repository path. The CVS administrator should have provided you with those values.

Initial check-out

Right-click on the "C:" icon in the left-hand pane of WinCVS and choose "Checkout module..." from the context menu.

You will need to enter the project name in the module, for example:

project1

and the local folder that will contain your working copy.

When you click on "OK" you should get a copy of the project on the local drive. (The project directory may be fairly sparse to begin with.)

The CVS administrator will provide you with a list of the projects you have access to.

Further reading

At this point, reading the WinCVS documentation will augment the understanding you have from reading the CVS book and documentation at cvshome.org. WinCVS itself is pretty straightforward if you understand the rudiments of CVS operation.

Alternative method

  1. Install Cygwin, the POSIX emulation layer. By default, this includes an OpenSSH client and a copy of the CVS software.
  2. Follow the instructions for setting up a Unix client using the Cygwin shell.

This currently requires the user to be familiar with the command-line operation of CVS. We do not consider this to be too onerous a requirement.

Caveat: Unix/MSDOS lineends

There is one upshot of this system: since Cygwin's cvs thinks it is running on a Unixalike, it uses the Unix newline character. And so does the CVS server. So no newline translation is performed; thus, the wise will use a Windows text editor that can save files in Unix newline format - and turn that behaviour on by default.

If you've anything to comment on this (perhaps a better Win32 solution?), drop me a line.