The Free and Open Productivity Suite
Apache OpenOffice 4.1.6 released

About this Guide

What this guide discusses. The purpose of this guide is to enable users to tunnel to using SSH2 (Secure Shell 2). This guide provides instructions for the creating the certificate (also called the public key) used by SSH2 servers and for sending that certificate to the administrator. It will also then explain how to create a secure "tunnel" between your machine and using this certificate. (Throughout this discussion, the term "public key" and "certificate" will be used interchangeably.) This guide only seems long. Much of the material is repeated and tailored to suit the needs of particular clients.

What this guide does not discuss. This guide does not explain in detail how to use CVS, only how to set up the tunnel so that you can use CVS. See the brief account of using CVS with a tunnel below.

Note: In order to tunnel to, you must first submit a public key (certificate); it must then be accepted; it will only be accepted if you have the authorization of your project lead and have submitted either a Joint Copyright Assignment or Public Document License and your name is on the "Copyright Approved" list. For more information, see the Contributing page.

About SSH2

SSH2 is a flexible and more secure replacement for telnet and rlogin, and SSH1. It is widely used in development projects to provide access control and data-transport security. SSH2 can be used to create an unobtrusive, transparent "port tunnel" to the CVS (concurrent versions system) server. SSH2 uses encrypted certificates (a public/private key pair) to verify the user's identity and to transmit data. 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, uses SSH2 for developers accessing the CVS repository.


  1. Using the right software
  2. Creating the certificate
  3. Establishing the SSH2 tunnel

Before you can establish an SSH2 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 SSH2 capability built in). Fortunately, there are excellent clients 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" that describes the key elements in establishing an SSH2 tunnel in a Unix-like environment. And if you already are familiar with the these clients, then you can skip ahead to "Using the Desktop Terminal."

Once you have obtained and configured a client terminal, you must

  1. Generate a public/private key pair (the certificate); and
  2. File an issue and attach the public key to the issue. Assign it to in the "www" component

Generating the key is simple, and there are both commercially available and free clients that do the job for you. Sending the key then is only a matter of attaching it to an issue in which you explain which module you wish to access and assigning it to in the www.component.

The SSH2 Client


Command Line: Linux, Mac OS X, Unix, Solaris. Linux supports SSH. To connect using SSH, see the "Tunneling" section below. As well, Mac OS X, via the "Terminal" application, allows you to generate a key pair, and establish a tunnel. This is no surprise, as it is using tried-and-true software. To establish the tunnel, follow the instructions as for Linux, with the exception being that the command for generating the DSA key in BSD is different: ssh-keygen -t dsa (though I have found that ssh-keygen -d also works).

MacOS 9.x. Hardly surprising, isn't it, that tunneling using Mac OS 9 is trivially easy? The concepts are the same as for Windows, Linux, or Mac OS X, as are the numbers, etc. But, in a nutshell, here's what you do. It's a two-step process. First, you must configure MacSSH, then configure the CVS client.

Configuring MacSSH

  1. Download the latest version of MacSSH, which is characteristically easy to use, is free, Open Source, and offers superior performance.
  2. Configure it by clicking on the "Favorites" pull-down menu in the top-navbar.
  3. Click on the "New" button.
  4. Enter a name for this favorite. If it is going to be your default, don't bother.
  5. Host Name:
  6. Port: 22
  7. Terminal: default
  8. Go now to "SSH2" tab.
  9. Encryption: 3DES
  10. Authentication: MD5
  11. Compression: zlib
  12. Method: Local TCP port forward
  13. Local port: 2401
  14. Remote host: localhost
  15. Remote port: 2401
  16. You now must initialize (create) your SSH2 key pair. Click on the "Initialize SSH" button. Follow instructions.
  17. Export your key (that is, put it elsewhere) by clicking on the "Export" button.
  18. Once your key has been loaded by the helpful and friendly staff at, you will be notified; and then you will be able to establish a tunnel.
  19. And, as is the case with tunnels: once established, there is no shell. At most you will receive a message in a window saying that you are connected. That is all. Leave this open, though you may minimize the window.

Configuring Mac CVS Clients

There are several free and easy-to-use CVS clients for the Mac. Each has its shortcoming (among them being the inane similarity of names) but I prefer two: MacCVSPro, and MacCVSClient. Both allow port forwarding (so you can use the tunnel) and both are easily configured. The data is the same for both. As well, for both you must create a folder for he CVS files. This can be done within the client or outside. I suggest you do it first, and that you clearly identify your folder.

Note: I am providing all the information you may need. Not all this information is required by the clients.

The above information should be all you need. If you receive error messages (a "1" in CVS), you may not have correctly set up your tunnel or have a bad password. As well, be sure to put the preceding slash "/" before the cvs (lowercase) root. If it's not there, you won't be able to checkout material.

Windows. If you are using Windows (NT or 9x or 2K), then please use Cygwin. Cygwin, from Cygnus Solutions, provides a nearly full Unix environment on your desktop. Cygwin has been updated to load quickly and easily. It also generates the keys in the proper format for We recommend Cygwin and do not recommend any other client.

Using Cygwin: Free and Open Source Unix Terminal Emulator

Generating the Key with Cygwin: Unix Commands

  1. Open Cygwin. If properly configured, Cygwin should start in your home directory. To check that it does, type in "pwd" at the prompt. (The command requests bash to respond with the working directory.) If the answer does not correspond to your home directory, type in "cd." This relocates the working directory to your home directory.
  2. Enter "ssh-keygen -d." This commands the program to generate an SSH2 key (the -d extension specifies a DSA or SSH2 key). Depending on the speed of your processor, it could take anywhere from several seconds to several minutes. When finished, it will prompt you for a file in which to save the key. You should accept the default; or, you can specify a file and directory in which to save the key, but doing so can be a pain, unless you are familiar (or wish to be become familiar) with Unix file structures.
  3. You will then be asked to enter a passphrase. You must enter a passphrase. Your key will not work unless you enter one. Remember this passphrase: you will be asked for it every time you log into the SSH2 server to which you have connected using this public key.
  4. If you have entered a passphrase correctly (and you will be asked twice to be sure you aren't typo-ing your way into a mistake), you will then be told that the "identification" has been saved in the file you stipulated, and that the "public key" has been saved in a file bearing that same name but with a .pub suffix. The .pub signifies that it is the public key.
  5. For details on submitting the key, see the section below, "Submitting Your Certificate (Public Key).
  6. Note: you are going to use CVS via the tunnel. Your CVSROOT needs therefore to point to your localhost to use the tunnel.

Tunneling with the Cygwin: Unix commands

Submitting Your Certificate (Public Key)

Regardless of the way the public key has been created, it needs to be sent to and accepted by administrators.

  1. To submit the key, attach the .pub file as an attachment to an IssueZilla issue. (To use IssueZilla you must be registered; but, then, to actually use the key you have to be a registered user.) Assign it to "" in the "www" component. Explain in the issue what modules you wish access to. (The key takes up one very long line; it cannot be broken into more than one line, and anything that does that violates the integrity of the key. That's why you need to attach the file to the issue.)
  2. We will then send you an acknowledgment alerting you of your ability to use the certificate to tunnel to Should you run into difficulties, do not hesitate to contact
  3. Note: Your CVSROOT needs to point at your localhost to use the tunnel

What to do after you have a tunnel

Okay, you've come this far. If you've done everything right, you will have a tunnel on your desktop to the server housing the CVS repository. This tunnel is not a shell, i.e., you will not see any of the more or less familiar Unix elements, just a perplexingly blank screen, and a message indicating when you last logged in.. And this is the way it should be.

What you must do now: Log on to CVS. As mentioned before, this document does not touch upon CVS protocols, only how to establish an SSH tunnel. But, to emphasize the issue, the establishment of the tunnel is distinct from loggin into the CVS repository. The tunnel only enables you to log in. For documentation on how to use CVS, please see the Help on CVS.

See below, How to use CVS with a tunnel.

See also the new document generated by Miljenko Williams of Website that does a fine job of explaining not only tunneling and Cygwin, but also CVS.

How to use CVS with a tunnel

The tunnel is a conduit for cvs data. When you initiate a tunnel following the instructions above, you are connecting to the CVS server. The tunnel, which is more a window into the server, becomes your designated CVS host. You need only supply the correct password for the CVS server; it is the same as your user password. Thus, the process is:

  1. Establish a tunnel. If it works, you will be asked for your passphrase (not password, a sign of failure)
  2. Initiate the CVS connection. You use :pserver; the server is "localhost" (the tunnel), and you use your regular username.
    • E.g., cvs -d :pserver:[username]@localhost:/cvs login
  3. The regular set of CVS commands obtains. Just keep in mind you are going through the localhost tunnel, that you are not connecting to the CVS server outside of the 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.

Further Documentation

Top | Help index

Apache Software Foundation

Copyright & License | Privacy | Contact Us | Donate | Thanks

Apache and the Apache feather logo are trademarks of The Apache Software Foundation. OpenOffice, and the seagull logo are registered trademarks of The Apache Software Foundation. Other names appearing on the site may be trademarks of their respective owners.