Last updated 2003-07
Contents
What this guide discusses. The purpose of this guide is to enable users to tunnel to OpenOffice.org 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 OpenOffice.org administrator. It will also then explain how to create a secure "tunnel" between your machine and OpenOffice.org 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 OpenOffice.org, 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.
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, OpenOffice.org uses SSH2 for developers accessing the CVS repository.
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
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 ssh2key@openoffice.org in the www.component.
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.
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 OpenOffice.org. We recommend Cygwin and do not recommend any other client.
Regardless of the way the public key has been created, it needs to be sent to OpenOffice.org and accepted by OpenOffice.org administrators.
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.
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 OpenOffice.org user password. Thus, the process is:
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.