Tunneling with SSH

• About this Guide
• About SSH
• Concepts
• Choosing the Desktop Terminal
• Using the Desktop Terminal
• Macintosh
• Windows
• Tunneling Using Cygwin: The Desktop Unix Emulator
• Further Documentation

About this Guide

What this guide discusses. The purpose of this discussion is to provide a guide for users to tunnel to the desired server using SSH (Secure Shell).

What this guide does not discuss. This guide does not explain how to use CVS, only how to set up the tunnel so that you can use CVS. However,a brief description of the command to begin using CVS, once the tunnel has been established, is appended at the end of this document.

About SSH

SSH is a flexible and more secure replacement for telnet and rlogin. It is widely used in development projects to provide access control and data-transport security. SSH can be used to create an unobtrusive, transparent "port tunnel" to the CVS (concurrent versions system) server. Data sent through the tunnel is encrypted, but the process is invisible to you or to the client software you are using to access the CVS repository.

Because it is easy to use and very secure, we recommend SSH for developers accessing the CVS repository.

• Accessing the CVS repository without SSH runs the very real risk of having a third-party thief snoop your CVS password. And, with your CVS password, the thief can wreak serious mischief. For instance, he or she might quite plausibly compromise the CVS repository by inserting a virus in the source code.

Concepts

• Using the right software
• Establishing an SSH tunnel

Before you can establish an SSH connection, you have to find the right software,i.e., a client that places a terminal on your desktop, if you are using Windows or Mac OS 9 (Mac OS X has SSH built in). Fortunately, there are several excellent clients (both free and not) that offer Windows and Mac OS users desktop terminals. The section below discusses them in detail. Of course, if you are using Linux (or some other Unix variant), then you can skip that section and go right to the section, "Tunneling Using Cygwin," that describes the key elements in establishing an SSH tunnel in a Unix-like environment.

Once you have obtained a client terminal, the process of establishing a tunnel to the server housing the CVS repository is fairly simple. The crucial element is making sure you connect to the right server and that you use the right port numbers in establishing your tunnel. Fortunately, that number has been standardized: 2401.

Choosing the Desktop Terminal

Platforms

Linux, Unix, Solaris. Linux supports SSH. To connect using SSH, see the "Tunneling Using Cygwin" section below.

Macintosh.In important regards, procedures for tunneling with a Mac client terminal resemble those for Windows clients. Mac users can download and install any number of free or for-fee terminals, the most popular being MacSSH, which is characteristically easy to use, is free, and offers superior performance for SSH1 connections.

NiftyTelnet 1.1 SSH, a fast and easy-to-use telnet and SSH1 client is also free. It supports effortless scp (secure copying), as well.

Mac OS X, based on FreeBSD and the Mach 3 kernel, has SSH built in and is constantly updated. You can also obtain and use Data Fellows' F-Secure SSH, a for-fee (see below) client create a desktop terminal allowing you to tunnel to the CVS server. F-Secure SSH can be obtained at: http://www.DataFellows.com. For SSH1, you will want F-Secure SSH v.1.02; v.2.1 is for SSH2 connections only--i.e., those requiring encrypted certificates, or keys.

Windows. If you are using Windows (NT or 9x or 2K), then you can use SecureCRT, F-Secure SSH, or Cygwin. Cygwin, from Cygnus Solutions, provides a nearly full Unix environment on your desktop.

In contrast, SecureCRT and F-Secure SSH only provide user-friendly terminals, i.e., they don't pretend to emulate a Unix environment. Both F-Secure SSH and SecureCRT cost money ($100 for SecureCRT, $150 for F-Secure SSH), although a free, 30-day trial version is available for each. Of all, Cygwin has the added value of not just being free and very powerful, but also open source and constantly improved upon.

Using the Desktop Terminals

Necessities

Hostname: enter the name of this site

Local port: 2401

Remote port: 2401

Username: tunnel

User password: tunnel

• MacSSH
• NiftyTelnet SSH

Both Mac clients offer intuitive interfaces; both also are well-documented. For that reason, this discussion of the Mac clients is very brief. However, for both clients, the important information is the same as for the Windows clients: the hostname and ports must be correctly specified.

Windows

Two free clients for Windows provide SSH tunneling:

• TTSSH, an open-source add-on to Tera Term Pro
• PuTTY, a free implementation of Telnet and SSH for Win32 platforms. It also provides an XTerm terminal emulator.

As with the Mac clients, the important things to keep in mind are the hostname and the port numbers. For both terminals, the configuration process is straightforward. Because TTSH is an add-on to Tera Term, it means you have to go through that one extra step before SSH functionality is possible. [A fuller description of tunneling with TTSH is being drafted and will be posted when finished. For now, please see TTSH's website.]

PuTTY, on the other hand, does not allow you to easily configure the client to handle port forwarding. As a result, it is not recommended for tunneling.

SecureCRT and F-Secure SSH

Both these clients are fairly easy to use and configure for SSH1 tunneling. The information you will need--doubtless familiar by now--is listed below.

The following illustrates the procedure; we will use SecureCRT (version 3.1.2):

1. Open a new session, specifying "SSH1" in the pull-down menu.
2. For "Hostname," enter the name of this site.
3. Click on the "Advanced" button by "Hostname."
4. Once in the Advanced section, click on the "Port Forwarding" tab.
5. For "Local port," enter "2401."
6. For "Remote port" enter "2401."
7. For Username, enter "tunnel."
8. For User password, enter "tunnel."
9. For "Remote hostname," enter "localhost."
10. Enter "Save" and "OK" to exit the dialog box.
11. Back in the main connection page. . . .
12. Leave the defaults for "Cipher" and "Authentication" as they are.
13. Click on "Connect."
14. The server should then prompt for your password. It is "tunnel."
15. If this is your first time, the client will tell you that no "host key" for the server has been found and ask if you want to continue. You want to continue.
16. You are now tunneling.
17. The terminal screen does not show a prompt. That's how it should be. The tunnel has been established. You are now ready to begin using CVS securely.

Cygwin

The most important consideration for installing Cygwin is creating the appropriate Unix folders. Cygwin's website offers complete and detailed instructions; the below is an abbreviated version.

• Download and install Cygwin. Cygnus gives you the option of installing from the Web, but it is faster (and ultimately more efficient) to install from a local disk. So just download and save the file somewhere you can easily find it.
• Click on Cygwin's "setup.exe" icon and follow the instructions, accepting the defaults. At some point, you will be asked for text format and whether you want Cygwin to be for yourself alone or to be shared. It doesn't matter whether you choose DOS or Unix, but for the sake of ease of use, choose Unix and "All." Cygwin will then install, and should create icons in your start file as well as on your desktop. If it doesn't, run setup again. Nothing will be installed if nothing needs to be, but it will take you to the end, where you can check the boxes indicating you want the icons installed. Check them.
• At this point, you need to create the Unix folders. You can create the standard directories from within Cygwin, as Cygwin's configuration instructions suggest (http://www.cygwin.com/cygwin-ug-net/setup-dir.html), or you can set them up from within Windows. Using the Windows method has some advantages, especially for people who are not entirely familiar with Unix commands and protocols. Since Cygwin is able to read both Win32 (Windows) file paths as well as Unix ones (POSIX), it doesn't much matter how you do it.
• Very clear instructions for creating the Unix directories can be found at http://www.woodsoup.org/projs/ORKiD/basic.htm. Although the instructions are specifically for a slightly earlier version of the program, they still obtain: the typical Unix directories must still be created.
• As well, the cygwin.bat file needs to be modified. Cygnus suggests that other files, too, need modification; but of these, the .bat file, which specifies the commands and their sequence that bash must go through, needs immediate modification.
• Configure your cygwin.bat file using Windows' Notepad utility or other text editor (not Microsoft Word or anything that imparts formatting) so that it looks something like this:

@ECHO OFF
SET MAKE_MODE=Unix
SET CYGWIN=notty
SET HOME=C:\unix\HOME\[your home directory name]
SET TERM=VT100
CHDIR C:\Unix\HOME\[your home directory name]
SET PATH=C:\Unix\BIN;C:\Unix\USR\LOCAL\BIN;C:\CYGWIN\BIN;%PATH%
BASH

• Where the "unix" directory on the "C" drive contains the traditional Unix directories. You can name it anything you want, as long a you do not use anything that confuses Unix, e.g., hyphens, spaces, etc.
• You should now have the C:\Cygwin directories, and your own C:\unix directories, which include your crucial home directory.
• There is still one more, optional, step. For Cygwin to run efficiently, you might want to configure the shortcut icon on your desktop so that it starts the program in the right directory. This is not necessary, if you have stipulated the HOME directory in the .bat file.
• Cygwin offers some further refinements, and, to be sure, there will doubtless be some tweaking you will have to do to make have the program running efficiently. Again, if you are familiar with Unix commands and file structures, you will find this easy; if you are not, Cygwin is quite forgiving, and you can get started with a minimum of fuss.

• First, begin the program.
• At the prompt, enter "ssh -x -L 2401:localhost:2401 tunnel@DOMAINNAME"
• Where DOMAINNAME is the name of this site. The server should ask you for your password. Enter it. It is "tunnel"
• If this is your first time, the server will send you a message along these lines:
  • Host key not found from the list of known hosts.
  • Are you sure you want to continue connecting (yes/no)?
• Enter "Yes." You can't just enter "y"; you have to spell it out.
• The server will then respond with: "Host "DOMAINNAME" added to the list of known hosts."
• The screen does not show a prompt. That's how it should be. The tunnel has been established. You are now ready to begin using CVS.
• You can, at this point, minimize the terminal, but do not close it or enter Ctrl-C (^C). Doing so will kill the terminal tunnel.

Terminating the Tunnel

The easiest way to terminate the tunnel is to Ctrl-C (^C) it out of existence. In both the Mac OS and Windows environment, you can also close the client window, thereby shutting the tunnel down.

CVS