WinCVS CVS Client Installation Instructions

WinCVS CVS Client Installation Instructions

This document provides instructions for installing and configuring the WinCVS CVS client software in conjunction with the PuTTY SSH client suite. These instructions are designed for SourceForge.net project developers who are using 32-bit Microsoft Windows platforms.


What is CVS?

SourceForge.net provides free hosting for Open Source software development projects. Among the services offered by SourceForge.net are tools, used by development teams, to manage the collaborative development process; CVS is one such tool. CVS provides the ability to coordinate changes to a centralized source code base which is managed and developed by a project team; and track and manage historical changes to your source code.

One of the best resources available, regarding basic operation of CVS as well as advanced CVS functionality, is http://cvsbook.red-bean.com (commonly referred to as, "The CVS Book"). The chapters from this book related to the operation of CVS are available freely under an Open Source license; several translated versions of this book content are also available. The SourceForge.net team generally recommends that every new CVS user read at least the first chapter of this book -- it provides key and fundamental background information; while CVS has a learning curve, the first chapter in this book is among the fastest ways to ready yourself to use CVS.

SourceForge.net provides a significant amount of information about the specifics of the SourceForge.net project CVS services within its 'Introduction to SourceForge.net Project CVS Services'. The SourceForge.net team strongly recommends that all developers of SourceForge.net-hosted projects review this document before proceeding to use project CVS services.


These instructions are for developers

SourceForge.net provides CVS services to two groups of people: developers and end-users. Developers are active members of SourceForge.net-hosted projects, and have the permissions required to write to the CVS repository for their project. End-users are typically users of the software provided from one of those hosted projects, and have only anonymous, read-only access to project CVS repositories (i.e. they cannot commit changes). This document applies only to developers (who are members of an active project hosted on SourceForge.net) and does not apply to end-users.

This document covers the process required for a developer to set up WinCVS to access their project CVS repository so as that they will be able to commit changes to that repository. Non-developers (end-users) do not need to go through this process, nor will it work for them, as they will only need to download WinCVS and configure it to access the repository anonymously, by following the configuration details on the CVS page for the project in question. Please proceed with these instructions only if you are a developer on a SourceForge.net-hosted project.


Overview of basic operation

Each project hosted on SourceForge.net is automatically provided a CVS repository, which they may use to store source code, documentation, and web site content (or other product-related materials) and track historical changes to these files. In order to access a CVS repository, you need a special piece of client software which is capable of communicating to the CVS server; WinCVS is one such client software package, available for 32-bit Windows workstations. You will run a client like WinCVS from your workstation to communicate with the SourceForge.net project CVS server; this will allow you to download a working copy of your data to your local machine, where you may change that data and commit the changed data back to the server.

To ensure security over this communication, all developer CVS traffic must be wrapped using the SSH protocol (the same protocol used to communicate to the project shell servers; not to be confused with SSL, which is the protocol used to secure web traffic). SSH serves three key functions, in this case. First, SSH allows the SourceForge.net site to validate your identity in a manner more secure than CVS normally uses. Second, SSH encrypts, and further secures, all data transmitted between your workstation and the CVS server. Finally, SSH provides the means to authenticate to the CVS server using public key encryption mechanisms, thus eliminating the need to frequently enter your password.


Steps in this process

Total user time for install: approximately 40 minutes; plus a 6 hour delay during SSH key upload. We do advise that you proceed to the CVS Book at this time, and read the first chapter, as to gain background information about the basic operation of CVS.


Downloading the required materials

To implement CVS write access for a SourceForge.net project developer, as described in this document, you will need to obtain three pieces of software: a SSH (Secure SHell) suite, a CVS client, and a utility for use in installing the SSH suite and CVS client. At time of this writing, the latest versions of these applications total a little more than 5 megabytes of data which must be downloaded to proceed.

7-Zip is an Open Source utility which may be used to extract the contents of compressed archives in a number of formats (including tar, gzip, bzip2, and zip). 7-Zip is similar in basic feature set to WinZip. If you already have WinZip installed on your machine, you need not also install 7-Zip.

The SSH client suite and CVS client used in these instructions are each distributed in the form of a zip archive; zip archives, as other archival formats, provide an easy means to transport many files at once, compressing them to reduce download times. In order to perform the installation of the SSH client suite and CVS client covered by these instructions, you will first need to extract the files from those archives using a tool like 7-Zip.

SourceForge.net recommends that most Windows-based developers make use of the WinCVS CVS client software in conjunction with the PuTTY SSH suite. This pairing is relatively simple to install (compared with many solutions) and provides a stable platform for development.

These instructions (and accompanying screenshots) assume that you have created a directory, C:\DOWNLOAD, to house the files needed for this installation procedure. Filenames specified within these instructions reflect the most recent stable version of the software that was available when these instructions were initially written; you should obtain and use the latest stable versions of these software packages that their development teams provide. It is always a good idea to test downloaded materials using an anti-virus software package; this step is omitted from these instructions, but is strongly recommended, for your protection. The following materials should be downloaded:

  • 7-Zip, a .zip archive decompresser for 32-bit Windows platforms. (filename: 7z230b18.exe)
  • WinCVS, a CVS client package for 32-bit Windows platforms. (filename: WinCvs120.zip)
  • PuTTY, a SSH client suite for 32-bit Windows platforms. (filename: putty.zip)

View of C:\DOWNLOAD folder contents


Installing 7-Zip

7-Zip is used within these instructions to decompress the .zip archives used to distribute the WinCVS and PuTTY client packages. In order to install 7-Zip, we must first download this software from the 7-Zip project.

  1. To proceed with the installation of 7-Zip, use Start -> Run to execute the downloaded copy of the 7-Zip executable, C:\DOWNLOAD\7z230b18.exe
  2. Upon executing the 7-Zip Installer, we are prompted to confirm that we want to install 7-Zip; select 'Yes'.
  3. Next, you are prompted to specify the path to which 7-Zip will be installed; change this path as necessary (or leave it at its default value of 'C:\Program Files\7-ZIP'), then select 'Ok'.
  4. The installation of 7-Zip will proceed and you should be notified that the installation has completed successfully.
  5. Upon completion of the 7-Zip installation, you will be prompted to restart your computer; select 'Yes'.

7-Zip install, do you wish to proceed? 7-Zip install, select a path 7-Zip install, install complete 7-Zip install, restart computer


Installing the PuTTY SSH suite

SourceForge.net recommends the use of the PuTTY SSH client suite in conjunction with WinCVS as to access project CVS repositories in a more secure fashion. To proceed in installing PuTTY, you must first download a copy of the PuTTY software.

  1. Start the 7-Zip software (via its icon under your Start menu).
  2. Use the File->Open menu option of 7-Zip to open the putty.zip archive you downloaded.
  3. Right click in the file listing box, then select the 'Extract' option from the pop-up menu.
  4. On the file extraction page, specify a path of 'C:\PUTTY' (or similar) to which the files will be extracted. Ensure that the 'All Files' radio button has been selected, then click 'Ok'.
  5. 7-Zip will proceed to extract the files from this .zip archive to the path specified.
  6. Using Start->Run, execute 'C:\PUTTY\PUTTY.EXE'.
  7. Enter 'cvs.sourceforge.net' as the host name you wish to connect to, and select 'SSH' as the desired Protocol. For clarity, select the 'Never' radio button within the 'Close window on exit' option, then click 'Ok'.
  8. The connection to cvs.sourceforge.net will be initiated and you will be promThe connection to cvs.sourceforge.net will be initiated and you will be prompted to verify the host fingerprint for the cvs.sourceforge.net host.
  9. Access the SSH Host Key Fingerprints listing using your web browser.
  10. Verify that the host fingerprint in the PuTTY window matches the specified fingerprint for this host, as found in our Site Documentation. Once you are satisfied that the fingerprint matches the expected value, click 'Yes' within the PuTTY window.
  11. PuTTY will prompt you to enter your SourceForge.net user account username and password.
  12. Upon successful authentication, cvs.sourceforge.net will create your home directory, then log you out automatically. This is normal; there is no other reason to interactively sign-in to cvs.sourceforge.net than to have your home directory created.
  13. You have successfully installed and tested PuTTY; if you encountered difficulties in this process contact the SourceForge.net team for further assistance.

View of PuTTY .zip archive Accessing the Extract option in the 7-Zip pull-down Preparing to extract files from the PuTTY .zip archive View of the C:\PUTTY folder

Configuring your PuTTY session Prompt for host key fingerprint verification Site documentation about host key fingerprints Username and password prompt in PuTTY

PuTTY SSH session output and disconnect


Installing WinCVS

CVS repositories reside on a central server and are accessed using a special CVS protocol, which requires a client software package. The WinCVS software will be used to access the CVS repository for your projects.

  1. Start the 7-Zip software (via its icon under your Start menu).
  2. Use the File->Open menu option of 7-Zip to open the WinCvs120.zip archive you downloaded.
  3. Right click in the file listing box, then select the 'Extract' option from the pop-up menu.
  4. On the file extraction page, specify a path of 'C:\DOWNLOAD\WinCvs120' (or similar) to which the files will be extracted. Ensure that the 'All Files' radio button has been selected, then click 'Ok'.
  5. 7-Zip will proceed to extract the files from this .zip archive to the path specified.
  6. Make use of Start->Run to execute 'C:\DOWNLOAD\WinCvs120\WinCvs120\SETUP.EXE'
  7. At the WinCVS installer welcome screen, click on the 'Next' button.
  8. At the WinCVS software license screen, review the license terms for the WinCVS software, then click on the 'Yes' button to proceed.
  9. At the WinCVS information screen, click on the 'Next' button.
  10. At the WinCVS path selection screen, modify the installation path as needed (or leave the default of 'C:\Program Files\WinCvs 1.2'), then click on the 'Next' button.
  11. At the WinCVS setup type selection screen, select the 'Typical' radio button, then click on the 'Next' button.
  12. At the WinCVS program folder selection screen, specify the folder name you wish to use for this application under the Program Files menu, then click on the 'Next' button.
  13. When prompted to proceed with the installation, click on the 'Next' button to start copying files.
  14. Once the installation has been completed, click on the 'Finish' button to exit the installer.

Accessing the Extract option in the 7-Zip pull-down Preparing to extract files from the WinCVS .zip archive View of extracted WinCVS .zip archive contents WinCVS installer welcome screen

WinCVS installer license agreement screen WinCVS installer information screen WinCVS installer path selection screen WinCVS installer setup type selection screen

WinCVS installer Program Folder selection screen WinCVS installer start confirmation screen WinCVS installer completion screen


Generating a SSH key pair

When authenticating to a host via SSH, you will either need to enter your user account password for each connection, or to establish your identity using a SSH public key pair. This document covers the process of setting up WinCVS and PuTTY to use a SSH key pair, as this is most desirable to developers who use CVS services on a regular basis. Information about SSH may be found in our "Introduction to SSH on SourceForge.net". Information about SSH key handling may be found in our "Guide to generating, posting and using SSH keys".

To generate a SSH public key pair, we will make use of the PuTTYGEN utility, included with the PuTTY SSH client suite.

  1. Make use of Start->Run to execute 'C:\PUTTY\PUTTYGEN.EXE'
  2. Set the 'Number of bits in a generated key' to 1024, then click on the 'Generate' button.
  3. Move your mouse within the provided window as to help PuTTY to generate random bits for use in key creation. When sufficient random bits have been collected, your key generation will proceed.
  4. Enter 'username@users.sourceforge.net' within the Key comment field.
  5. Enter a secure (unique) password in the Key passphrase and Confirm passphrase fields. If this password is lost, there will be no means to recover it (you will need to create a new key pair). The use of a passphrase helps to prevent the possibility of someone stealing your identity; they need both the private key file and your password to prove identity.
  6. Click on the 'Save' button. Save your new key to 'C:\PUTTY\SOURCEFORGE.NET.KEY'
  7. You have completed the generation of your SSH public key pair. Please leave the PUTTYGEN application running, then proceed to the next step.

unstated


Uploading your SSH public key

In order for SourceForge.net hosts (the project shell and CVS servers) to validate your identity, they must be provided a copy of your public key. The public key is half of the key pair generated in the previous step. It is important that you keep your private key in a secure location and protect it from access by others. Your private key should never be given out; SourceForge.net staff will never ask for your SSH private key or key passphrase.

  1. Access the Edit Keys page from the User Account Maintenance page.
  2. Within the PUTTYGEN window (left open from the previous step of these instructions), highlight all of the text within the 'Public key for pasting into authorized_keys file' field.
  3. Press the Control + C key combination to copy this data to the clipboard.
  4. Within your web browser, paste the data in to the provided text box, then click the 'Update' button.
  5. Returning to the 'Account Options' page, you will note that your 'CVS/SSH Shared Authorized Keys' count is now 1.
  6. Key data will be synchronized from the SourceForge.net web site to the project shell and project CVS servers every six hours. Please wait six hours, then proceed to the next step of this installation.

unstated unstated


Configuring Pageant

The PuTTY SSH client suite includes an application to help reduce the frequency that you need to enter your password. Upon starting your workstation, you may execute 'C:\PUTTY\PAGEANT.EXE' and configure it to have knowledge of your current SSH keys. By adding your key data to Pageant, you will need to enter your SSH key password only once, no matter how many SSH sessions you initiate while Pageant remains running. This step will need to be repeated each time you restart your workstation or Pageant.

  1. Make use of Start->Run to execute 'C:\PUTTY\PAGEANT.EXE'
  2. Double-click on the Pageant (computer with hat) icon in your system tray.
  3. Click on the 'Add Key' button.
  4. Select the key file we saved during the key generation process (C:\PUTTY\SOURCEFORGE.NET.KEY).
  5. When prompted, enter the password you specified during the key generation process, then click 'Ok'.
  6. The key in question will now appear within Pageant's active key list. While Pageant is running, Pageant will respond to any requests from other PuTTY applications (such as PuTTY.EXE and PLINK.EXE) that you enter your SSH key password.

unstated


Testing automated authentication

Since we have waited six hours since uploading our SSH key data, and we have configured Pageant to answer requests for our SSH key password, we can now proceed to test passwordless authentication to the project CVS server.

  1. Open a Command Prompt (Start->Run, CMD.EXE)
  2. At the command prompt, enter: c:\putty\plink.exe username@shell.sourceforge.net echo "SSH public key is in place."
  3. Upon executing this command, we should receive a line back, stating: SSH public key is in place.
  4. At the command prompt, enter: c:\putty\plink.exe username@cvs.sourceforge.net echo "SSH public key is in place."
  5. Upon executing this command, we should receive a line back, stating: SSH public key is in place.
  6. If both of these commands worked correctly, without prompting you for your password, and without error, you have successfully posted your SSH key data and have properly configured Pageant. If no issues were encountered, proceed to the next step in these instructions.

unstated


Configuring WinCVS

It is now time to configure the WinCVS client software to use access your project CVS repository, and to use the PuTTY SSH client in order to use the SSH protocol for authentication.

  1. Execute the WinCVS client using its icon within the Start Menu.
  2. Use the Admin->Preferences menu option of WinCVS to access the Preferences dialog. Select the 'General' tab.
  3. Enter the proper CVS for your username and project name within the 'Enter the CVSROOT' field, as: username@cvs.sourceforge.net:/cvsroot/projectname
  4. Specify 'SSH server' as your authentication method.
  5. Select the 'Ports' tab. Ensure that the 'Check for an alternate rsh name' box is checked. Enter 'C:\PUTTY\PLINK.EXE' in the adjacent text field.
  6. Click on the 'Ok' button. WinCVS is now configured to access your project CVS repository (and you will be able to commit files to this repository).

unstated unstated


Using WinCVS

Now that you have completed the installation of WinCVS, and have configured WinCVS to use PuTTY for authentication, you may proceed to use CVS within your actual development process. We recommend that you review three sets of documentation if this is your first time using CVS.

First, though you are using version 1.2.x of the WinCVS software, the documentation for WinCVS 1.3.x will likely prove quite useful. You may also find benefit in the Online Help provided with the WinCVS application.

Second, the SourceForge.net team has prepared an introduction to SourceForge.net project CVS services, which includes key information about operation of your project CVS repository and the various CVS-related services provided by SourceForge.net. This document should prove to be a good reference should you encounter any difficulties in using project CVS services, or if you want to make the most of CVS.

Finally, the CVS book by Karl Fogel provides an easy-to-understand walk-through of basic CVS operation. The first chapter of this document should provide enough background information for you to start using project CVS services immediately.


Where can I obtain support for using these instructions?

The SourceForge.net support team is happy to assist with any issues related to the services we offer, including the use of WinCVS to access SourceForge.net-hosted CVS repositories. To contact the SourceForge.net support team, submit a support request.

Return to the top of this page.

© Copyright 2002 Open Source Development Network. All rights reserved.

posted @ 2004-04-17 18:11  dudu  阅读(4962)  评论(0)  编辑  收藏  举报