The purpose of this guide is to enable users to tunnel (connect) to OpenOffice.org using SSH2 (Secure Shell 2). This guide helps you create the certificate (also called the public key) used by SSH2 servers, and send that certificate to the OpenOffice.org administrator. Next it explains how to create a secure "tunnel" (or connection) between your machine and OpenOffice.org using this certificate. This guide only seems long. Much of the material is repeated and tailored to suit the needs of particular clients.
Tunneling is not hard. But it is more difficult using Windows than, say, Linux or Solaris or Mac OS X. If you don't get it the first time, don't hesitate to ask for enlightenment on the support@website.openoffice.org list or on the issue that holds your public key. Also, if you want to improve this guide, please do so by submitting your ideas to support@website.openoffice.org.
This guide also gives the basics on how to use CVS after set up of the SSH tunnel.
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 and to the client software you are using to access the CVS repository.
This is what you have to do:
Linux, Unix, Solaris | Cygwin for Windows | Putty for Windows | MacCVSPro for Macs
Linux (or some other Unix variant): Go to Tunneling, where you will learn the key elements of establishing an SSH2 tunnel in a Unix-like environment.
Windows clients: Find a client that places a terminal on your desktop to generate a public/private key file set and establish a tunnel. Use either Cygwin or PuTTY. Of the two, we recommend Cygwin, as it works well; although setup can sometimes be difficult. There is some concern that PuTTY, which is easy to use, creates a key that is not quite compatible with the OpenOffice.org SSH server; though, it can be fairly easily fixed. There are reported security risks in earlier versions, so use PuTTY version .57 or later.
Mac clients: Find a client that places a terminal on your desktop to generate a public/private key file set and establish a tunnel. MacCVSPro is the recommended GUI client for using CVS on Mac OS X; it is easy to use and robust.
Linux, Unix, Solaris | Cygwin for Windows | Putty for Windows | MacCVSPro for Macs
Cygwin, from Cygnus Solutions, provides a nearly full Unix environment on your Windows desktop. Cygwin can be found at http://www.cygwin.com/. To install and configure Cygwin, read our instructions. (These instructions also detail how to create a set of keys.)
PuTTY is easy to use, but the keys generated need some adjustment. You can download PuTTY from http://www.chiark.greenend.org.uk/~sgtatham/putty/. Instructions on setting it up, generating keys, and forming a tunnel with port forwarding can be found in the PuTTY User Manual. See also the very good, "How to make a tunnel from PuTTY." The key values are the same as for the Cygwin tunnel, so no repetition is needed. Willy Sudiarto Raharjo has succeeded in creating keys for OpenOffice.org using PuTTY plus Pageant (PuTTY Authentication Agent), downloaded from the same website as PuTTY.
MacCVSPro is the recommended GUI client for using CVS on Mac OS X; it is easy to use, robust, and allows for port forwarding, which is crucial. A hint: you must create a folder for the CVS files. This can be done within the client or outside. I suggest you do it first, and that you clearly identify your folder.
The above information should be all you need. If you receive error messages, 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.
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 cd
at the prompt. This relocates the working directory to your home directory.ssh-keygen -d
at the command prompt. This commands the system 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..pub
suffix. The .pub
signifies that it is the public key.ssh -2 -x -L 2401:localhost:2401 tunnel@openoffice.org
Host key not found from the list of known hosts.
Are you sure you want to continue connecting (yes/no)?
Yes
. You can't just enter y
; you have to spell it out.openoffice.org
added to the list of known hosts.localhost
to use the tunnel.Ctrl-C (^C)
. Doing so will kill the terminal tunnel. Let it run in the background, and close it after your work in CVS is finished.Regardless of the way the public key has been created, it needs to be sent to OpenOffice.org and accepted by OpenOffice.org administrators.
pub
file as an attachment to an Issue Tracker issue. (To use Issue Tracker you must be registered; but, then, to actually use the key you have to be a registered user.) Assign it to "ssh2key" in the "www" component, ""openoffice.org website general issues"" subcomponent. 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.)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 screen with the message, "Tunnel established. Type ctrl-c to exit".
What you must do now: Access the CVS repository. As mentioned before, this document does not focus on CVS but does give the elements. For more extensive documentation on how to use CVS, please see the Help on CVS or Miljenko Williams' excellent How-To. Both the documents discuss excellent and easy-to-use clients for Windows. The below is merely the basics plus a brief account on how to use SSH2/CVS with a Mac OS X client.
Problems with tunneling are distinct from those having to do with CVS. Most problems occur because the key submitted does not work with OpenSSH, which is what the OpenOffice.org server uses.
The easiest way to resolve your problem is to contact us. Reopen, if needed, the issue used to file the original key. Then, ask support for assistance, explaining the problems you are encountering.
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:
:pserver;
the server is "localhost" (the tunnel), and you use your regular OpenOffice.org username.
cvs -d :pserver:[username]@localhost:/cvs login
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.