CVS/SSH instructions for courses on ITU

By Lars Thorup

Why bother?

You may think that it looks terribly complicated to setup CVS and SSH. But what you get out of the trouble is a

Secure Distributed Multiplatform Multiuser Version-controlled Document-management System

And that is a good thing; let me explain:
Document-management
The system manages documents by keeping them in a central location on a server from where they can easily be backed up.
Secure
Using SSH makes the system secure: no one can eavesdrop on the communication going over the network
Distributed
The system is accessible from any machine connected to the server via a network
Multiplatform
There are graphical and command line CVS clients for Windows, Linux, Macintosh, etc.
Multiuser
Several users can work on documents simultaneously and the system normally merges changes with no trouble.
Version-controlled
All versions of documents are kept, which makes it easy to go back to a previous version, or to a previous base line of the entire repository.

Overview

  1. SSH client, for every user
  2. CVS server, once per group
  3. CVS client, for every user

General instructions

In the entire document, substitute "user1" with the username you normally use to log into the IT-C network.

SSH setup on the Linux server

  1. Assume that a useable host name for the server on the internet is "ssh.it-c.dk".
  2. Assume that the server can accept incomming SSH requests.
  3. Assume that you have a user account on the server under the user name "user1".
  4. Then nothing else needs to be setup.

SSH setup on a Linux client

  1. Assume that you have SSH installed already. Test it by typing ssh -V. Otherwise install a version from http://www.openssh.org/.
  2. Assume that you have a working connection to server. Test it by doing a remote login like this:
    $ ssh user1@ssh.it-c.dk # invoke the program
    The authenticity of host 'ssh.it-c.dk ([ip-number])' can't be established.
    DSA key fingerprint is xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx.
    Are you sure you want to continue connecting (yes/no)? yes         		# this step is only needed if this is the first time you run ssh against ssh.it-c.dk, or when ssh.it-c.dk changes its key fingerprint. By answering yes you add the fingerprint to ~/.ssh/known_hosts2.
    user1@ssh.it-c.dk's password: # you type the password
    $ hostname
    ssh.it-c.dk         		# check that you is now on the server
    $ exit # end the remote login
  3. Create a unique key pair without passphrase on the client
    $ ssh-keygen -d
    Generating public/private dsa key pair.     		# invoke the key generation program asking for dsa type encryption
    Enter file in which to save the key (/home/user1/.ssh/id_dsa): # accept default location
    Enter passphrase (empty for no passphrase): # just press return
    Enter same passphrase again:
    Your identification has been saved in /home/user1/.ssh/id_dsa.
    Your public key has been saved in /home/user1/.ssh/id_dsa.pub.
    The key fingerprint is:
    xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx user1@[your client]     		# press return again, now the key is created
  4. Install the public key of the client on the server:
    $ scp .ssh/id_dsa.pub user1@ssh.it-c.dk:
    user1@ssh.it-c.dk's password:         		# copy the public key to the server, you must still enter your password
    $ ssh user1@ssh.it-c.dk
    user1@ssh.it-c.dk's password:         		# login to the server, you must still enter your password
    $ mkdir -p .ssh # create the .ssh directory if missing
    $ chmod go-rwx .ssh # make sure the directory is for your eyes only
    $ cat id_dsa.pub >> .ssh/authorized_keys2 # append the clients public key to the authorized list. Note the underscore in the file name authorized_keys2.
    $ rm id_dsa.pub # remove the copy of the public key
    $ chmod go-rwx .ssh/authorized_keys2 # make sure the authorized list is for your eyes only
    $ exit # leave the remote login
  5. Test that you can now do a remote login without typing a password
    $ ssh user1@ssh.it-c.dk # invoke the program
    $ hostname
    ssh.it-c.dk         		# check that you is now on the server
    $ exit # end the remote login

SSH setup on a Windows client

  1. Download putty.exe, pscp.exe, plink.exe and puttygen.exe from http://www.chiark.greenend.org.uk/~sgtatham/putty/. Solutions to some common installation problems (like missing WS2_32.DLL on Windows 95) can be found in the FAQ at http://www.chiark.greenend.org.uk/~sgtatham/putty/faq.html.
  2. Copy the files to the folder "H:\Putty".
  3. Assume that you have a working connection to the server. Test it by doing a remote login like this:
    4. Run putty.exe
    Enter Hostname: ssh.it-c.dk
    Select Protocol: SSH
    Click Open
    You will probably first get a PuTTY Security Alert Window where you are asked to confirm that you trust the server's host key with the given key fingerprint. Click Yes.
    Then you should get a terminal window in which you are asked to login with user name and password.
    After that you can type hostname and you should get ssh back.
    Close the terminal window by typing exit, which also exits PuTTY.
  4. Create a unique key pair without passphrase on the client:
    Run puttygen.exe
    Click Generate
    Move the mouse around as long as the progress bar indicates to generate some entropy.
    Copy the Public Key into Notepad. Important:Make sure to add a trailing linebreak after the key. Otherwise concatenating several keys will not put them each on their own line. Finally save it in H:\Putty\identity.pub.
    Click Save to save the private key in H:\Putty\identity. Accept the warning about no passphrase.
    Exit the PuTTY Key Generator.
  5. Create a Saved Session in PuTTY
    Run putty.exe
    Session tab, Hostname: ssh.it-c.dk
    Session tab, Protocol: SSH
    Session tab, Saved Sessions - text box: ssh.it-c.dk
    Connection tab, Auto-login username: user1
    SSH tab, Private key file: H:\Putty\identity
    Session tab, Click Save.
    Test the new session by double clicking it on the list of saved sessions. You should get a terminal window and be asked for a password. Type exit to close the terminal window again.
  6. Install the public key of the client on the server
    H:\>cd Putty # Using a Command Prompt Window, go to the location of the key files
    H:\Putty>pscp identity.pub user1@ssh.it-c.dk:
    user1@ssh.it-c.dk's password:         		# Copy the public key to the server, you must still enter your password
    H:\Putty>putty
    Double-click on ssh.it-c.dk
    Sent username "user1"
    Server refused our public key.
    user1@ssh.it-c.dk's password:         		# Login to the server. You must still enter your password.
    $ mkdir -p .ssh # create the .ssh directory if missing
    $ chmod go-rwx .ssh # make sure the directory is for your eyes only
    $ cat identity.pub >> .ssh/authorized_keys # append the client's public key to the authorized list
    $ rm identity.pub # remove the copy of the public key
    $ chmod go-rwx .ssh/authorized_keys # make sure the authorized list is for your eyes only
    $ exit # leave the remote login
  7. Test that you can now do a remote login without typing a password:
    H:\Putty>plink ssh.it-c.dk
    Sent username "user1"     		# Login to the server.
    $ hostname
    ssh.it-c.dk         		# check that you is now on the server
    $ exit # end the remote login

CVS setup on the Linux server

  1. Assume that the name of the users are "user1" and "user2" and that these users are in the group "group1".
  2. Assume that you choose to put the CVS repository in the directory "cvsroot" located in "~user1", i.e. the home directory of "user1".
  3. Assume that your project is named "pacman".
  4. As "user1": Create the CVS repository:
    $ cd ~user1 # begin at a well-defined place
    $ mkdir cvsroot # create the directory
    $ chgrp group1 cvsroot # make sure the directory belongs to the common group
    $ chmod g+s cvsroot # make sure everything below will belong to the common group
    $ cvs -d ~user1/cvsroot init # let CVS create its own files
    $ chmod -R g+w cvsroot # give group permission to write. Only neccessary because IT-C's filesystem is xfs.
    $ cat ~user1/cvsroot/CVSROOT/modules # verify that CVS has created its files
  5. As "user1": Create an empty CVS module, and import it into the repository:
    $ cd ~user1 # begin at a well-defined place
    $ mkdir pacman # create a temporary folder for the initial files
    $ cd pacman # go there
    $ touch readme.txt # create an initial file
    $ cvs -d ~user1/cvsroot import -m "" pacman v r # import the files into the repository under the name "pacman"
    $ chmod -R g+w cvsroot/pacman # give group permission to write. Only neccessary because IT-C's filesystem is xfs.
    $ cd ~user1 # back out
    $ rm -rf pacman # remove the temporary folder
    $ cat cvsroot/pacman/readme.txt,v # verify that the new file was created in the repository
    $ pwd
    /import/home/user1         		# verify the absolute path to the repository

CVS setup on a Linux client

  1. Assume that SSH has been setup on the client
  2. Assume that CVS has been setup on the Linux server
  3. Tell CVS to use SSH
    $ echo -e "\nexport CVS_RSH=ssh\n" >> ~/.bash_profile # tell CVS to use SSH.
    $ exit # logout, then login again
    $ echo $CVS_RSH
    ssh         		# test that the setting has been made permanent
  4. Verify that CVS works by doing a checkout of the pacman module
    $ cvs -d :ext:user1@ssh.it-c.dk:/import/home/user1/cvsroot co pacman
    cvs server: Updating pacman
    U pacman/readme.txt         		# checkout the module. You specify the CVS root, which is the login method, username, host and repository location. And then you specify an action

CVS setup on a Windows client

  1. Assume that SSH has been setup on the client
  2. Assume that CVS has been setup on the Linux server
  3. Install WinCVS from http://www.wincvs.org/. Choose version 1.2. Note that this requires administrator rights which most users on the IT-C network do not have, but WinCVS should already be installed on several machines. You should be able to do this at home though.
  4. Start WinCVS and configure it using the Admin | Preferences dialog:
    General tab, Authentication: SSH server
    General tab, CVSROOT: :ext:ssh.it-c.dk:/import/home/user1/cvsroot
    Ports tab, Check for an alternate rsh name: H:\putty\plink.exe
    Globals tab, Checkout readonly: unchecked
    Close the dialog by clicking OK, and exit the program to save the new preferences.
  5. Verify that CVS is working by doing a checkout of the pacman module
    In the Left Pane on the Modules tab, select the directory to hold the pacman directory, e.g. H:\.
    Invoke the Admin | Command Line dialog.
    Enter cvs -d :ext:ssh.it-c.dk:/import/home/user1/cvsroot co pacman and click OK.
    Click on pacman\readme.txt in the right pane to verify that it was indeed checked out.

CVS usage on a Linux client

What is out-of-date?
cvs -nq update
U or P
Update or Patch. A newer version exists on the server.
M
Modified. A newer version exists locally.
C
Conflict. Newer versions exists both locally and on the server. Might need manual resolving.
?
New. The file exists only locally.
Make up-to-date
cvs -q update -P

The "-P" option ensures that you will also get newly created directories

Files still marked with "C" needs manual resolving. Search for text between "<<<<", "----" and ">>>>". The first segment is the local version, the second segment is the server version. Remove the segment you don't want plus the markup inserted by CVS.

Add new directories
cvs add [directories]
After this you will need to login to the Linux server (using ssh) and issue this command for each directory:
$ chmod g+w cvsroot/[directory].
Add new text files
cvs add [files]
Add new binary files
cvs add -kb [files]
Delete a file
cvs rm -f [files]
Rename a file
Copy the file, add it the new place, remove it the old place
Commit changes after add, delete or edit
cvs commit -m "good explanation"

CVS usage on a Windows client

What is out-of-date?
Red icons are modified locally. ?-icons are files that only exists locally.

Alternatively, use Query | Query Update:

U or P
Update or Patch. A newer version exists on the server.
M
Modified. A newer version exists locally.
C
Conflict. Newer versions exists both locally and on the server. Might need manual resolving.
?
New. The file exists only locally.

Make up-to-date
Select module directory, then select Modify | Update selection. Check the option "Create Missing Directories..." to ensure that you will also get newly created directories.

Files still marked with a "C"-icon needs manual resolving. Search for text between "<<<<", "----" and ">>>>". The first segment is the local version, the second segment is the server version. Remove the segment you don't want plus the markup inserted by CVS.

Add new directory
Select files, then select Modify | Add selection.
After this you will need to login to the Linux server (using putty) and issue this command for each directory:
$ chmod g+w cvsroot/[directory].
Add new text files
Select files, then select Modify | Add selection.
Add new binary files
Select files, then select Modify | Add selection binary.
Delete a file
Select files, then select Modify | Remove selection.
Rename a file
Copy the file, add it the new place, remove it the old place
Commit changes after add, delete or edit
Select the module directory, then select Modify | Commit selection. Then enter a good explanation in the dialog before clicking OK.

Troubleshooting

Document version: $Header: /home/cvs/projects/voop-itu/web/cvs-setup.html,v 1.8 2002/02/24 13:42:18 lth Exp $