How to set up SSH (for the beginner)

Last modified $Date: 2013/01/30 05:18:43 $, $Revision: 1.19 $.

Some folks have offered links to translations; these may be useful, but note that I have not verified them.

This is a minimal set of instructions to get a beginner going with ssh2, in particular the client version of OpenSSH which comes on Linux distributions or on Windows viaCygwin. I’ve included a section to help you connect to machines which are not running OpenSSH but some commercial ssh. Since it covers both Linux and Windows it reflects the author’s bias and takes a command line approach: it assumes some knowledge of typing things at a command prompt (e.g., the “cd” command). If you are not familiar with that sort of thing you will need to seek help.
If you want to enable ssh clients to connect to your computer (i.e., make it an ssh server, then on Linux this is usually just a matter of installing the ssh server package, which may be called “sshd” or “ssh-server”. On Cygwin it is a little more involved and you should consult the web.
Note that these explanations make reference to your “home” directory (written “HOME” or “~”). On UNIX machines (including Linux) this is the directory you land in when you login, and where you keep your files; this location is stored in the environment variable “HOME”. Note that “HOME” is the name of the variable, and that $HOME is the value, e.g. HOME’s value may be “C:nifty”. The natural HOME for the Windows user Nifty is the existing folder “Documents and SettingsNifty” but Cygwin and other UNIX related applications are not necessarily happy with pathnames that include blanks, so you may want to create your own HOME directory for Cygwin as described below.

Windows only

SSH can give you authenticated and encrypted connections to remote computers. If you set up keys you can make these connections without passwords. Installing Cygwin is pretty easy but the home directory and public/private key business, on Cygwin, is something of a pain; it’s going to push the “beginner” envelope but is doable. If you don’t mind typing passwords with every connection, you can skip all the Windows HOME business below after installing and running Cygwin. If for some reason you do not wish to install Cygwin on Windows you may want to consider putty. I do not cover how to use putty here.
Installing Cygwin on Windows: This is pretty straightforward. Download the Cygwin installation wizard setup.exe from the Cygwin site and double-click on it. Most of the default selections in the wizard are fine. Select a place to install Cygwin (recommended: C:cygwin, although on Windows 7 it seems to work fine in C:, despite the warning) and select a place to put the installation files (I use C:cygwininstallation-files). Choose an ftp or http site from the list and then review the additional packages you want installed. You must select at least the openssh package from the Net section. You do not need the sources.
Running Cygwin on Windows: You start a Cygwin console (which I may call a “terminal” as well) from the Start menu, and type the commands in that window. (If the shell does not open in the HOME directory, see below). The ls command lists files and folders (“directories” in UNIX lingo). The cd command enables you to change directories, “cd ..” moves you up a directory. The Cygwin console is much like a regular UNIX terminal and may be customized on startup with .bash_profile and .bashrc files in your HOME directory. Search the web for more about UNIX for beginners. You can see the (terse) documentation for any command by using the “man” command, for example, “man ls” or “man ssh-keygen“.
By the way, Cygwin comes with a small program to set up ssh for you. The command is ssh-user-config, which will create keys and a .ssh directory in your HOME directory. However, it will not create a non-default HOME directory, nor fix your /etc/passwd/file, nor put the public key on the remote computer, all of which may be necessary and are described below. I’ve never used it.
A proper Cygwin installation will have, in the installation directory, a folder “home” with a subfolder with the same name as your user name, but in the past this has sometimes not happened for me. If one of these folders is missing see the Troubleshooting section below. Note that your home directory does not have to be in Cygwin’s “/home” (mine is not), you can put it anywhere, e.g., C:nifty. (I do this so that my home directory C:nifty is at the top the C: drive tree instead of in C:cygwinhomenifty). To do this, rename the existing C:cygwinhomenifty directory to niftyTMP, create the C:nifty directory, open a Cygwin console, and run

        $ cd /home
$ ln -s /cygdrive/c/nifty nifty
$ mv niftyTMP/*.* nifty
$ rmdir niftyTMP

The “ln” command is making a symbolic link, like a Windows shortcut, from Cygwin’s /home/nifty to your C:nifty. Note that “/cygdrive/c/nifty” is Cygwin’s way of saying “C:nifty”. If your HOME is on another drive, say D:, use the cygwin prefix /cygdrive/d. The next two commands will move all the files from niftyTMP to C:nifty and delete niftyTMP.

Setting the HOME environment variable on Windows: For Win2K/XP right click on “My Computer”, click on “Advanced” and “Environment variables”. Add a personal environment variable HOME with value, e.g., C:cygwinhomenifty (or if you did the linking business above, C:nifty). You shouldn’t need to reboot, buy you may need to login again for the changes to take affect.
For Win9x/Me, you must put a line in your autoexec.bat file (usually C:autoexec.bat) which sets it, e.g.,

      set HOME=C:cygwinhomenifty     

or, if you have the link as described above,

      set HOME=C:nifty    

and reboot. Be sure to edit the autoexec.bat with a text editor (like Notepad) and not a word processor (like Word). You can see the value of the environment variable from the command line with the command “echo $HOME” in Cygwin, or “echo %HOME%” in DOS. Your Linux environment variables are set in your ~/.bashrc and ~/.bash_profile files.

By the way, environment variables are useful for a variety of programs; this is how you would set CVS_RSH, ANT_HOME, JAVA_HOME, and JIKESPATH if you were a Java programmer using CVS with SSH. If you wanted Cygwin commands available from DOS prompts you would append “;C:cygwinbin” to your PATH variable.
Troubleshooting: Creating a missing Cygwin home directory: The Cygwin installation folder contains folders “usr” and “bin”. If it is missing, add a folder called “home” and in that folder add a folder with some name, typically your user name, e.g., “nifty”. This will be the folder where ssh.exe will look for the .ssh folder containing your keys. (Cygwin thinks your home is where the line in /etc/passwd says it is, see below).
Troubleshooting: Checking the home in the /etc/passwd file on Windows: In your Cygwin root install folder (C:cygwin) there is a directory etc/ containing a file “passwd” (if this file is missing it can be created with the cygwin command “makepasswd”). The lines in this file contain fields separated by colons (:). In a new Cygwin installation the last line will be for your Cygwin user name. The last field will be “/bin/bash”. Make sure the next-to-last field in the line for your user name is “/home/nifty”, (it’s OK if “nifty” is a link, as above). Do not use Windows “C:” notation. Be sure to edit the /etc/passwd file with a text editor (like Notepad or Wordpad) and not a word processor (like Word).
Troubleshooting: If the Cygwin shell doesn’t open in $HOME: On some some of my installations the Cygwin Bash shell did not open in $HOME but in /usr/bin (the prompt was “/usr/bin $”, not, e.g., “nifty/ $”). See the troubleshooting note above.

Linux and Windows

OpenSSH to OpenSSH (ssh2)

Check that ssh functions at all: SSH can replace telnet even without keys. Suppose you are connecting to the remote computer as user “dude”. Run

 $ ssh [email protected] 

and ssh will ask if you want to keep connecting, type “yes”, and then it should ask for your password and open a shell in dude’s home directory on, just like telnet. If this fails, there is a problem somewhere. Make sure ssh is installed on your end, and also make sure that is accepting ssh connections. If it’s not, you’re wasting your time.

Once ssh is functioning we will set up the keys so that it will no longer be necessary to send passwords. If you are curious about the theory of this then read up on “public key cryptography”.
Create your keys: You need to create private and public ssh keys and put them in the proper place with the proper permissions. In your home directory create a folder .ssh ($ mkdir .ssh), if there is none. Note that Windows may make it difficult for you to create a file starting with “.” if you try to do it with their tools; e.g. Windows Explorer. Next, create the keys with the command

 $ ssh-keygen -t dsa  

The ssh-keygen program will ask for a passphrase, just hit the “Enter” key unless for some reason you know you want a passphrase. This creates the keys id_dsa and and puts them in .ssh/. The private key id_dsa must be readable only by you; change its permissions with

 $ chmod 600 .ssh/id_dsa 

Put the public key on the remote computer: In this section we are assuming the remote computer is also running OpenSSH. Somehow, you must get the .ssh/ key onto the remote computer, whether by email, ftp, carrying it over on a floppy (sneakernet), etc.; the cool way to do it is to use scp, which was installed along with ssh. Suppose the remote computer is named, and your account there is “dude”. To copy the file to remote, run

 $ scp .ssh/ [email protected]:  

Don’t forget the trailing colon (:). You will be asked for dude’s password on remote before the copying commences. The file will be copied to dude’s home directory on remote.

Install the public key on the remote computer: (We assume the remote computer is running OpenSSH on Linux or UNIX!) Once is on the remote computer, login into the remote computer (you can use ssh to login with your password as described above). From your home directory (where you should see your newly arrived create a .ssh folder if none exists. Then append your to a file in .ssh with

 $ cat >> .ssh/authorized_keys 

This will create the file authorized_keys if none exists. The key may be removed from the remote computer’s home directory, if you like. The .ssh folder on the remote computer must have the correct permissions, you may set them with

 $ chmod 700 .ssh     

Checking the password-less connection: Now the command

 $ ssh [email protected] 

should give you a password-less connection to Likewise, scp should be password-free.

By the way, all the commands you do by first logging into the remote computer can be done remotely, one at a time, using ssh. For example, you can run run “$ ssh [email protected] ls” and get a listing of your home directory files on the remote computer. See the documentation for details.

OpenSSH to Commercial SSH

This is very similar to the connection described above and only some differences are described here. If you don’t mind using passwords you can use ssh and scp as described above. For password-less connections read on.
Changes to the keys: OpenSSH’s ssh-keygen command has the options “-i” to import commercial keys and “-e” to export them. If you have created your keys using OpenSSH, then you should be able to export the key to a commercial version, and put that on the remote machine instead of the OpenSSH version.
If “-e” does not work for you (and it did not for me), you can generate commercial keys on the remote machine using ssh-keygen2, and then on your local machine use OpenSSH’s ssh-keygen with the “-i” flag to create a new private key id_dsa (This worked for me, or was it vice-versa?).
Installing the commercial public key: This is like the OpenSSH installation above except for minor differences. The directory on the remote machine is called .ssh2, and the public key file’s name (not the file itself) is appended to .ssh2/authorization. The public key file itself can be stored in .ssh2/. From the home directory:

        $ mv .ssh2
$ echo "" | cat - >> .ssh2/authorization

SSH Tunnelling

We’ll move right out of beginner stuff into ssh tunnelling now. The idea here is to connect to a remote computer via an intermediate computer, all with ssh. This situation arises at organizations that have one computer facing the internet, but you want to connect to another computer behind the internet-facing computer. Of course the intermediate computer and the remote computer must accept ssh connections. I’ll assume that you are “dude” sitting at “localhost”, with account “intdude” on the intermediate computer “”, and account “remotedude” on the remote computer “”. I’ll assume further that you have set up ssh keys for access to

Basic SSH Tunnelling

On localhost, in a terminal, run

 $ ssh -L [email protected] 

This creates an “ssh tunnel” starting at localhost:2022 through (which has the default ssh port of 22) to As a byproduct it gives you a shell on The idea is that you can use ssh to connect to from localhost through the tunnel.

Leave this terminal open, and in another terminal run

 $ ssh -l remotedude -p 2022 localhost 

If you do not have your key in’s .ssh/authorized_keys, then you will get:

 [email protected]'s password:  

Enter the remotedude password at this prompt and you will have a shell on Of course if you have set up ssh keys for connecting from to, then you will need no passwords at all.
You can use the same key pair for both ssh connections, but maybe you don’t want to; for example you may want to use one private/public pair for your computers at work and another pair for your computers at home. In this case the work computer only needs the public key from your home pair.
Remark: It is not quite intuitive to use “localhost” in your commands and mean “”. You can change this so that “ssh [email protected]” works by adding a HostKeyAlias to your config file, as described below.

CVS Tunnel to

Assume you want to check out the module mycvsmodule on which has CVS root “/cvsroot”. Create with or add to your localhost ~/.ssh/config file the following stanza (note the optional wildcard “*”, too):

      Host remote*
HostName localhost
Port 2022
User remotedude
HostKeyAlias remote
CheckHostIP no
ForwardAgent yes

Then (after you set up the tunnel in another terminal with the “ssh -L” command as described above) run something like

 $ cvs co mycvsmodule 

which will check out the “mycvsmodule” module. You can now cd into the mycvsmodule/ directory where CVS commands will work as expected (as long as the tunnel is open).

Browser Tunnel to

Tunnelling may help in situations where you want to access web pages from a site behind a firewall. If is running a web server then it can be accessed via ssh through Suppose there is a page which you can access from inside the firewall at Assuming you have set up ssh as described above, from outside the firewall you can set up a tunnel:

 $ ssh -L [email protected] 

and then browse to http://localhost:2022/mypage.html.

Copyright 2006 by Glenn Murray

Leave a Comment

Your email address will not be published. Required fields are marked *