This is an introduction to ssh (secure shell) and cvs (concurrent version system), as used by the SEUL project. It is meant to help get developers started with using cvs quickly, and point them in the right directions for more info that will be necessary to fully utilize the power of this development system. This document assumes some knowledge of the general layout of the SEUL project servers (see the general FAQ for more info), and focuses on describing how to actually get ssh/cvs set up and running, to access and operate on SEUL source code and other documents.

The first things covered are general overviews of: "What is CVS?" and "What is ssh?", followed by instructions for How to set up ssh/cvs to access SEUL sources.

What is this?

CVS is the version control system used by the SEUL project. RCS and SCCS are other common version control systems that you may be familiar with. These are all systems that allow a development team to keep a central repository of sources, which may then be checked out by various developers, modified, and checked back in to the main repository.

Version control systems also allow operations which help keep track of source modifications over time, such as listing differences between revisions of files, and tagging sets of files that constitute a complete software release. They also resolve issues (to some degree) that arise when multiple developers want to work on the same file simultaneously. RCS forces locking of files, so that only one person can work on a file at once. CVS, however, recognizes that with proper planning and communication there is no reason multiple people can't work on one file at once. So CVS allow any number of copies of the same file to be worked on at once, and implements methods for merging changes, as well as some support for watching who is editing what, to avoid surprise conflicts. However, it is important to keep in mind that CVS will not do everything for you, and most notably is not a replacement for communicating with other developers working on your project.

More information on CVS can be found in the official CVS documentation. This may be found in /usr/doc/cvs-*/cvs.ps on a system with cvs installed, in the ftp pub dir on cran (eventually), and a slightly outdated html version is on the web at http://hill.ucs.ualberta.ca/Documentation/cvs-1.8.1/cvs_toc.html. If you plan on working on the SEUL project extensively, you should probably read through that document eventually, or at least refer to it when you're not sure how some part of CVS works.

For now, a quick intro for getting started with CVS as related to SEUL may be found below. However, it is not meant to replace the full documentation, but merely to offer a quick-start for using CVS for SEUL development.

What is CVS?

CVS automatically supports remote access to a repository, so you can check out files on the the SEUL CVS server directly from your own development machine. By default, it uses the rsh program to do this, though that can easily be overridden. SEUL replaces the rsh connection with ssh.

Ssh (secure shell) is a secure replacement for rsh/rlogin (remote shell/login). Like rsh/rlogin, it allows a user on a remote machine to start a login shell on a server machine, or to just execute a single command on the remote machine. In addition, ssh provides authentication to make sure the machines connecting to each other really are who they claim, and RSA-like encryption of all communication. These are important to the SEUL project, since developers get direct access to the CVS repository, and unlike common most companies/projects that use CVS, we can't simply put all our developers behind a firewall to prevent random people from getting in and messing things up, while pretending to be legitimate developers (this is trivial to do with rsh, since rsh is notoriously insecure).

The price we pay for ssh is that it takes more than one simple line of text editing to make it work, but the rest this document should help you get things set up pretty easily nevertheless. And it is worth the larger benefits gained. Rsh is actually disabled on the cvs server, and if you ever need to login directly to the machine, we recommend you use ssh, not telnet. Telnet will probably also be disabled soon.

This document is merely a quick introduction to get ssh running, so you can use SEUL cvs services. You will probably want to do some additional reading to get a better idea of how ssh actually works. The places to look for more documentation are:

• The documentation in /usr/doc/ssh-*/README on a system with ssh installed. (Will also be available for ftp from cran eventually)
• The ssh manpage, on a system with it installed.
  
• The official ssh web site at http://www.cs.hut.fi/ssh/

What is ssh?

Here are the basic steps for setting up ssh/cvs to access the SEUL repository. They assume you are using a Linux machine. If not, some of these instructions may be a bit inaccurate. So far, we have successfully set up cvs access on Redhat Linux machines. If you have particular good or bad experiences with other platforms, let us know.

(These instructions are not the greatest. But they will be improved as soon as someone has time for it.)

1. Access. You will need a cvs account. Currently, send email to seul@seul.org to request one. In the near future there will be a request form. You will also need access to the cvs server via the internet. If you are behind a firewall that blocks connections on port 22 (the ssh port), then you will need to figure out a workaround.
2. SSH. First, install ssh on your machine. (You will need to do this as root.) If you are running Redhat Linux, there is an ssh RPM available from ftp.replay.com. They have a US and International versions of the software. You are responsible for checking if there are any local regulations on whether you must use one or the other. If you are not using Redhat, you can always get the sources and compile them. There is probably also a dpkg distribution of ssh.
   Note that you can install the full sshd server, or just the ssh client. To have full functionality, you will need to install the server, since it is what authenticates your machine to the cvs server.
3. Start the sshd server, configuring it first if necessary. The sshd RPM will automatically create a server configuration and key information for you in /etc/ssh... If this is not done automatically for you, you will have to manually run the commands to initialize your server configuration/keys.
4. Before doing the next step, you will also need to generate keys for yourself. Log into your machine as the user you will be when connecting to cran. Run ssh-keygen and follow the instructions.
5. Now, with everything installed and sshd running, execute the following from the shell prompt: ssh cranleigh.mit.edu
6. Ssh is now trying to connect to cran. The next thing you should see is a paranoid message, asking if you really want to connect. (This is because you have never connected before, so ssh does not recognize cran yet.) You answer yes. Then you get a passwd prompt, enter the passwd you were assigned, and you should find yourself sitting at a shell prompt.
7. Congrats! You've logged into cran. Ssh has now stored away host info about cran in $HOME/.ssh/... on your machine, so it will recognize cran next time you connect. Now you have to tell cran about your machine. You need to know you're machines canonical host name, or its IP. If in doubt, you can get the IP by running "ifconfig" on your machine. Then run: ssh (your machine) from cran. If sshd is running correctly, you will connect back to your machine just like you did to cran, and now cran will stash info about your machine. When this is done, log out from your machine to find your self back at cran's prompt.
8. The last thing you will need to do is set up your account on cran to allow automatic authentication, so you can use cvs without providing a password every time you run a command. We will provide a script to do this for you... It should just be something like "shosts_config (your ip)" And there's also that dynamic hosts script, if you're using a ppp link or whatever... (omega: can you get this stuff setup, and fill in this section. remember that rbash'ers will not be able to chmod, so the shosts_config needs to do all that for them...)
9. Now log out of cran. You should be able to ssh to cran again and get logged in without a password (as long as you are connecting from the same machine as the same user, or update your ip with the dynamic_known_hosts script). You are ready to configure CVS.
10. CVS. Step 1: Install CVS on your machine. Please use CVS version 1.9 or higher. CVS is available as an RPM from ftp.redhat.com, and probably as a dpkg, and in other formats, including source for you to compile. This should not be too tricky.
11. Now set two important environment variables: CVSROOT to (your cran username)@cranleigh.mit.edu:/usr/local/cvsroot, and CVS_RSH to ssh. (We should provide details on how to do this under bash and csh here.)

Now you are ready to use CVS. Here are a few basic operations and tips. To really learn CVS, however, you should look at the CVS reference docuementation cited above.

How to set up ssh/cvs to access SEUL repository