This document covers how to use an SSH client on the Windows operating system. If you use Linux, Mac OS X or another unix based OS, please read the document SSH Tutorial for Linux.

What Is SSH?

Windows users may not be as familiar with the concept of logging into a remote computer to run programs for checking e-mail, editing files and to run commands. It used to be that nearly all the activity on the Internet was conducted through remote login sessions to large servers running at universities and large enterprises. These login sessions were text only and people could run programs to do things like check their e-mail, download files, read newsgroup posts and even visit websites.

When you login to these sessions, you are running what is called a shell, and so people now call these login sessions shell accounts.

There are a couple of ways that you can access a shell (command line) remotely from Windows. One of the older ways is to use the telnet program, which is available on most network capable operating systems. Accessing a shell account through the telnet method though poses a danger though in that everything that you send or receive over that telnet session is visible in plain text on your local network, and the local network of the machine you are connecting to. So anyone who can "sniff" the connection in between can see your username, password, email that you read, commands that you run and their output. Actually, quite a few internet protocols have this issue, such as FTP, SMTP (sending mail) and checking mail via plain POP3 or IMAP. For these reasons you need a more sophisticated program than telnet to connect to a remote host. One such program is PuTTY, which uses the SSH protocol.

An unencrypted telnet session

SSH, which is an acronym for Secure SHell, was designed and created to provide the best security when accessing another computer remotely. Not only does it encrypt the remote session, it also provides better authentication facilities, as well as features like secure file transfer and network port forwarding so that you can increase the security of other network protocols. It can use different forms of encryption ranging anywhere from 512 bits on up to as high as 32768 bits and includes ciphers like AES (Advanced Encryption Scheme), Triple DES, Blowfish, CAST128 or Arcfour. The higher the bits, the better the security, but also the longer it will take to generate and use keys as well as the longer it will take to pass data over the connection.

An encrypted ssh session

These two diagrams on the left show how a telnet session can be viewed by anyone on the network by using a sniffing program, such as Wireshark. It is really rather trivial to do this and so anyone on the network can steal your passwords and other information. The first diagram shows user jsmith logging in to a remote server through a telnet connection. He types his username jsmith and password C0lts06!, which are viewable by anyone who is using the same networks that he is using.

The second diagram shows how an encrypted connection like SSH is not viewable on the network. The server still can read the information, but only after negotiating the encrypted session with the client.

Getting Started

PuTTY icon

To use SSH on Windows, you have to download an SSH client. One of the best and freely available clients is called PuTTY. PuTTY can be downloaded from this website. One nice feature of putty is that it does not need to be installed like other programs. This allows you to easily use PuTTY while at a computer that doesn't give you administrative rights, like an Internet cafe or computer lab.

To get started, double click on the PuTTY icon on your desktop. Windows may ask you if you want to allow the execution of the program you just downloaded.

Windows Security Warning

So long as you are sure this was the file you downloaded from the PuTTY website, go ahead and click on 'Run'. It might not seem like it, but it would actually be a good idea to uncheck the option 'Always ask before opening this file', because it ties that choice specifically to the instance of that executable. If someone overwrites that executable with another program with the same filename, Windows will detect that and prompt you again. So if after unchecking that option, you are prompted again, you should delete the program and download it again or do a thorough check of your computer. Because imagine what could happen if a virus, spyware or the like replaced the putty executable with another program that logged your password.

When the program starts, the first thing that you will see is a configuration window. This is the standard way that PuTTY starts. From here you can setup a new session, including the hostname to connect to and options for SSH port, what protocol to use and then on the left are several categories for other settings that we'll cover later.

The initial PuTTY configuration window

What you will need to use this program is a shell account on a remote unix based server such as the one you receive with a Suso account. Go ahead and type in the hostname you want to connect to in the "Host Name" field. Suso users would use yourusername.suso.org or www.yourwebsitedomainname.com as their hostname. Here is an example:

For now go ahead and click on the 'Open' button once you've entered a hostname.

PuTTY will now initiate a connection to the remote server. This is where SSH kicks in. Part of the SSH protocol is to verify that you are connecting to the server that you think you are connecting to, this involves a cryptographic key exchange. The first time you connect to a host, you will see this window:

Alert window showing that this is a new host key

STOP! Please read the following.

Now I know that using Windows is like playing Whack-a-mole for some people (Click on the Ok and Yes buttons as quick as you can!) I'm guilty of it to some degree too. But this is important. These alerts are here for a reason and you should always stop and read and think about what they are telling you. One of the security features of the SSH protocol is to help you determine that the machine you are connecting to is the machine you think it is. That way your session won't be vulnerable to what is called a man-in-the-middle attack where someone could steal your username and password and other data.

Once you've read the alert, then if this is the first time you are connecting to this machine from this computer, go ahead and click 'Yes' to accept the key and cache it for the future. From then on, when you try to connect to that server, it should present the same host key and your PuTTY client will check if the key you receive is the same as the one in the host key cache on your computer. If its not, you will receive a message like this:

The cached host key does not match the key the server presented.

You can think of this process as being similar to dropping a child off at day care. A lot of these things are unconscious but you do a visual check to make sure that the building is the correct one and that the teacher that you hand your child off to is the correct one and that they acknowledge that they know who your child is and your child knows who they are. The first time you drop your child off, they have to get accustomed to that process and if the process ever changes, it raises a warning flag in your mind telling you that something might not be right. Just like the first time you connect to a server you have to accept the host key and if the host key changes, it raises a warning flag.

If and when you receive this error message, the best thing to do is press 'Cancel' and contact the administrator of the server by phone. Ask them if they have recently changed the host key on the server, which might happen if they upgrade the server or replace it, but leave the hostname the same. If they haven't done this, let them know that you received this warning message and they should be able to help you. It could mean that someone is trying to hijack your connection.

Ok, now that explanation is over, we can get back to your initial connection. Once you've accepted the host key, you will see the window with a black background. The server should eventually send a signal for PuTTY to generate a 'login:' prompt. At this prompt you should type in the username of the account you are trying to access on the server. After pressing return, it will give you a password prompt.

The password prompts generated by PuTTY.

Enter the password for the account and press enter. If you typed in the right password, it should continue with the login and eventually take you to a shell prompt or perhaps a menu system, depending on the server. If it re-prompts you for the password, keep trying and if it still doesn't work, check with the system administrator.

You should now see something like this:

PuTTY, after successfully logging in to an account.

At this point, you are logged into the remote account. What you do here will depend on what you are trying to accomplish of course. For a quick primer on how to use a unix shell, see the document "What Is a Shell? What Can I Do In It?". It covers some common programs you can run and how to use the BASH shell.

Here is a screenshot showing the user running a few commands to see a list of files in the home directory and also the www directory below that:

Running a few common commands.

The colors that you may see as well as the output from commands may be different depending on the server you are connecting to.

Try running a few commands so you can get a feel for it. Make sure you press enter after typing in each command.

ls

cd www

ls -l

That last command uses something called a command option. In this case, the -l tells the ls command to list the files and directories in long format, so that you can see other information like file size and ownership.

For now, we'll leave the rest for you to explore and go through the tutorial mentioned above. Lets move on to using WinSCP for transfering files to and from the server. Go ahead and type logout to exit your SSH session and close PuTTY.

logout

Using WinSCP to transfer files

A common usage of SSH is for transfering files. You may be used to using an FTP program for transferring files to and from a server. SSH has a set of solutions for this. One is SCP (Secure CoPy) and one is SFTP (SSH File Transfer Protocol). Under Windows, the best program to use for these is another program based on the implementation of PuTTY, called WinSCP. You can download WinSCP from http://www.winscp.net/. It comes in two flavors, an installable version, which puts an icon in the start menu and on the desktop, and the standalone version. The standalone version is nice when you are at a computer where you don't have the access rights to install software, but you can place it on your desktop.

Go ahead and download the version that suits your needs, install if necessary and startup WinSCP. You should have the following configuration window in front of you.

WinSCP configuration window with example data

Put in the hostname of the server you are connecting to for the 'Host name' field, leave the port number set to 22, enter your username and password in the provided fields. You can leave 'File protocol' alone generally. The only reason you might need to change that is if the server doesn't have SFTP setup. But that's what the SCP fallback checkbox is there for anyways. Go ahead and press the 'Login' button. On the first connection to a server, you will be presented with a window like the following, asking you to accept the host key for the server.

Host key accept window

Go ahead and click 'Yes' if this is a new connection or you were expecting the key change. If you were not expecting this window, then you should click 'No' and talk to the server administrator about the issue. See the discussion above about host keys if you haven't read it yet.

If all goes well, the server will accept your authentication details and log you in. WinSCP will then take you to a window with your local files on the left side and the remote files on the right.

The WinSCP file browser window

To use this interface, you can drag and drop files from one side to the other or back the other way. For more information on using WinSCP's interface, please see the interface section of the WinSCP documentation. Next we'll move on to generating an SSH key for use with the different SSH based programs.

Generating a key

Generating an SSH key is an optional thing. You can continue to use your server side password and be fine. However, it is more secure to use a private/public key pair with a passphrase and more options will be available to you by doing so.

PuTTYgen icon

Now that you are connected and excited about being able to login to a shell account and also transfer files, go ahead and logout. ;-) What we are going to do is generate an SSH key. This key will be used to authenticate us with the server in a different way than is done when typing in a password.

You can think of a key as being similar to a key in the real world. Instead of having to speak the password through a hole at a speakeasy, you can just use your key to get through the door.

Using PuTTYgen

To generate a key in Windows you'll need to download another program from the PuTTY website called PuTTYgen. PuTTYgen is a program that generates a pair of cryptographic keys used to encrypt the data that you send to and from the server.

Once you've downloaded PuTTYgen, click on the icon. Windows will probably prompt you that the program is not an officially signed program. Again, make sure you have the right program before clicking on run.

You should now see a window like this:

PuTTYgen opening window

The only field that you might ever feel like changing here is the field at the bottom labeled 'Number of bits in a generated key'. The most you can set this to in an RSA type key is 4096, go ahead and set it to that value now. Since we want to create a new key, go ahead and click on the 'Generate' button.

You will see the top half of the window change to a progress bar and it will tell you to 'Please generate some randomness by moving the mouse over the blank area'. This may seem like a strange thing to do but it is important for the security of encryption. The random movements that you generate are very unlikely to be exactly reproduced by someone else. The program counts how long you take in-between individual movements and which way and how far you move the mouse. Even you are very unlikely to produce the same sequence twice.

Moving the mouse to generate randomness

Randomness is very important in cryptography, which is the study of obscuring information using mathematical algorithms. Imagine a mathematical equation where the answer to two numbers added together is 42, but you don't know what numbers are added together to make 42, because it is supposed to be a secret. However, you do know that the algorithm used to generate the two numbers to add together tends to generate one number to be 23 after being run for 10 seconds. By knowing this, you can figure out that the other number would be 19. However, by adding good random information to the algorithm, you can make sure that the algorithm doesn't generate repeatable results and thus prevents crackers from figuring out what your private key or passphrase is.

Once you are done generating the randomness, PuTTYgen will start creating the private and public key pair. This may take a minute or two. Once it is done you will see two additional fields appear for entering a passphrase twice. Also, the buttons for saving the public and private key will be enabled.

PuTTYgen, after the key pair has been generated

At this point we should talk about the difference between a passphrase and a password. Unlike a system password, when you use an SSH key and a passphrase, your passphrase is never sent over the network to the remote computer and so nobody can ever try to sniff it or see what you typed by logging it on the remote side. The idea behind what you should use for a passphrase is also different from that of a password. Ideally, you should choose something unique and unguessable, just like your password, but it should probably be something much longer, like a whole sentence. Here are some examples of passphrases I've used in the past:

now is the time for me to shine

Someday I'm going to come up with a really nice passphrase

I don't know why that special death is there.

They're not going to guess this passphrase!

The RIAA can just suck my big ass

Some passphrases that I've used have been as many as 60 characters long with punctuation and numbers. This makes the passphrase next to impossible to guess, provided you don't tell someone or say it in your sleep (maybe your spouse is a spy and you didn't know it).

To give you an idea of how much more secure a passphrase is than a password. Consider this. Even if you narrowed down the number of words someone could use in a passphrase to 2000 potential words, if that person used 5 words in a sentence from that 2000 word set, it would mean there are 32,000,000,000,000,000 different combinations. Compare this with 6,095,689,385,410,816, which is the total possible combinations in an 8 character password using upper and lower case characters, numbers and punctuation (about 94 potential characters). So an 8 character password has 5.25 times less combinations than a 5 word passphrase. In actuality, most people choose words from a set of 10,000 or more words, bringing the complexity of a 5 word passphrase to 16,405 or more times greater than that of a 8 character password. So on average, the difficulty of cracking a passphrase is much greater than any password that could be used. Interestingly, the potential number of combinations of 8 word passphrase of someone with an adult vocabulary (8000 words or more) is almost equal to the number of 8 character password combinations multiplied by itself or about 16,777,216,000,000,000,000,000,000,000,000 combinations.

Don't use any famous quotes or phrases for your passphrase, they may be easily guessed by another person or by a brute force cracking program.

So think for a moment about what you want to use for a passphrase and then type it into the given field, and again to make sure that you typed what you thought you typed. The program will mask out the characters that you have typed so no one else can see.

I'd also recommend filling in the field called 'Key comment', this can be anything but usually you would put your <username>@<yourmachinename> so that you know where the key is from. This comment ends up at the end of the public key line that you will put on the server.

Showing the Key comment and passphrase fields filled in.

Once all this is done, you can save the private key and the public key. The private key is the key that you keep on your local machine. Do not ever let anyone see this key. If you think that the key has been viewed or accessed by someone, you should generate a new key.

Click on the 'Save private key' button and a file window will appear, which will probably default to your 'My Documents' folder. Call the key file something like ssh_private_key and then click on the 'Save' button.

If your My Documents folder is on a remote network drive or if your machine is shared by other people, you should consult with your local computer administrator to find a safe place to put this key file.

Next, instead of saving the public key file, all you need to do is copy the text in the top field that says 'Public key for pasting into OpenSSH authorized_keys file'. Make sure that you select the entire key as it will probably extend beyond what can be seen in the box. Press Ctrl-C to copy it.

Selecting the public key

Putting the public key on the server

So now we are assuming that the server that you are going to login to is using OpenSSH. Most likely it is, but you may ask the system administrator or support desk what type of SSH server they are using. At Suso, we use OpenSSH.

You should now have the public key copied into your copy/paste buffer, what you will do now is log back into the server and create an authorized_keys file. Go ahead and log back into the server as you did in the first section. Once you get to a command prompt, run the following commands:

mkdir .ssh

chmod 700 .ssh

cd .ssh

Now you will need to run an editing program in order to create the authorized_keys file. If you don't already know how to use vi or emacs, then we'd recommend nano, which is a basic editor. To start nano and edit a new file called authorized_keys, run the following command:

nano -w authorized_keys

The -w part is an option telling nano not to wrap long lines. It is important that the line that you will be pasting into the file not be broken up at the spaces. So we need to use this option. The last argument to nano tells it that we want to edit a file called authorized_keys, if it doesn't exist, then it creates a new one. You should now see something like this:

The nano editor

Now that you have nano open, all you have to do is paste in what is in your copy buffer into the putty window (Make sure you still have the public key in your paste buffer instead of something else). You can do this by pressing your right mouse button in the window (The Ctrl-v hotkey will not work for pasting inside Putty because it has a different meaning there).

Because the line you are pasting in is so long and because you have line wrapping turned off (remember the -w), nano will abbreviate the line that you have pasted in. The dollar sign that you should now see on the left end of the line is nano's way of telling you that there is more to the line to the left of this character. If there is a dollar sign on the right end of the line, it means that there are more characters to the right of that character. You can use the arrow keys or home and end to move around the line. Here are two screenshots showing what it looks like from the end of the line and the beginning of the line.

End of the line

Beginning of the line

Once that has been pasted into the file you need to save and exit the file. Nano uses control sequences (The use of the Ctrl key and another key) to perform these functions. They are somewhat like hotkeys in Windows. To save the file, press the Ctrl key and the 'x' key at the same time. At the bottom of the screen it will ask you "Save modified buffer". Press 'y' for yes. It may then prompt you for the filename to write to. If it says authorized_keys, just press enter, otherwise type in that filename and press enter. After doing this, nano will exit and you should be back at the command line. Now run this command:

chmod 600 authorized_keys

The 'chmod' program is a program that changes the access permissions on files. The reason why you need to run the above command is because a lot of servers have a setting that requires your authorized_keys file and your '.ssh' directory to be readable only by yourself instead of being "world readable". This command and the one you ran previously on the '.ssh' directory take care of that.

Configuring Putty to use the key

Now you can open PuTTY back up and configure it to use the private key. This time we are going to save the configuration into a session so that we can quickly retrieve it for later use. We'll save the session after configuring PuTTY to use the key.

Open PuTTY and click on the + symbol next to the 'SSH' category on the left hand side. A sublist will drop down, click on the 'Auth' category under there. You should now see this:

The SSH Auth configuration screen.

The key is set down at the bottom under 'Private key file for authentication'. Click on the 'Browse' button next to that field and locate your private key file on the file system. It is probably in your My Documents folder. Select the file and press 'Ok'.

Now, back in the configuration window, scroll to the top of the categories box and click on the 'Session'. On this page enter the hostname of the server you want to connect to and then in the box below under the words 'Saved sessions', enter a descriptive name for this session. I'd recommend using the hostname of the server or just the first part of the hostname.

Now click on the 'Save' button. It will move the session name down into the list of saved sessions. To test this, close Putty, then reopen it. When it comes back up, you should see your saved session in the list below. Go ahead and click on that session to select it and click on 'Load'. Now click on the 'Open' button at the bottom. This will open a connection to the hostname you specified for the session and use the SSH private key you specified.

It is possible to setup shortcuts to PuTTY that open up specific sessions when you click on them. This is done by creating a session, then making a shortcut to Putty and changing the target program to include '-load <sessionname>' at the end. So you would wind up with a target like this:
"C:\Documents and Settings\Yourusername\Desktop\putty.exe" -load bambino

Now it will start out the same, prompting you for your username. But instead of asking you for a password, it will prompt for your local passphrase for your SSH private key.

Prompting for the passphrase

Now you can enter your passphrase and it should log you in the rest of the way.

If it didn't prompt you for the passphrase and instead prompted you for your password, then either the permissions are wrong on the server side 'authorized_keys' file, the '.ssh' directory or the home directory. Or you didn't load the public key correctly into the 'authorized_keys' file. Or you didn't use the private key file.

Optional: Configure server to disallow password authentication

This step is optional, but recommended for better security. Now that you are using public key authentication to authenticate with your server account, your password becomes a weaker point in the security of your account and its security will only be as strong as the unguessability of your password. You can however completely disable the ability to use server side password authentication with your account to drastically increase the security of your account.

While this is a recommended configuration, it may become inconvenient if you wish to access your account from other computers where your SSH private key will not be available. You will want to consider this before disabling password authentication. There are techniques to make your key more portable however. You must also consider other users who use the server before disabling password authentication because these other users may not be using or may not wish to use public key authentication.

Login using administrative privileges to your server. If your server and your server account are both configured to use sudo for super user privileges, then you should be able to edit the sshd_config file using this command:

sudo vi /etc/ssh/sshd_config

If you do not have sudo privileges, but have the password for the root account, you should be able to login directly as root and then run the edit command:

su -

vi /etc/ssh/sshd_config

In the sshd_config file you make the following change:

PasswordAuthentication no

You may need to remove the commend character (#) from the beginning of the line. Then restart the ssh server with this command:

service sshd restart

You may need to consult with your server documentation for the proper command to restart sshd.

Now you will only be able to authenticate to any system account using public key authentication. This prevents an attacker from gaining access to your account through SSH via guessing your password, regardless of its complexity.

Using Pageant for auto-login

Pageant icon

This section will only make sense if you have created a private/public key pair in the previous section.

One of the great features of SSH and having a private key is that you can type in your passphrase once at the beginning of your Windows session and then login as many times as you want without having to type it again. This is accomplished using the Pageant program.

Go back to the PuTTY website (Tired of going there yet?) and download the Pageant program.

System tray

Pageant doesn't have any window when you start it, instead it puts itself in the Windows system tray down in the lower right next to the clock. You can right mouse click on the icon and show its menu. Go ahead and select 'Add Key'. This will bring up a file dialog, where you can select your SSH private key file. After you select it and press 'Open', a new window will appear asking for the passphrase to the key. Go ahead and enter your passphrase and click on 'Ok'.

Passphrase dialog

Once you've entered the passphrase, all SSH based sessions using PuTTY or WinSCP, will use the agent to decrypt the private key for authentication. This means that you will not have to enter your password or passphrase anymore until you logout of your machine, close Pageant or tell Pageant to forget about the passphrase for the key.

Please be careful! Once you've entered your passphrase into Pageant, anyone who has access to your machine or who can compromise your machine can also compromise any other machine that you have access to through your public/private key pairs. This includes things like spyware, viruses and the link too. You must be responsible and make sure your machine is properly protected. Most Windows machines aren't. I'd highly recommend also enabling password logins for your windows account and pressing Windows-L when you walk away to lock your screen.

If you want to remove your cached key from Pageant, you just need to right click on the tray icon, select 'View Keys' from the menu and then in the window that appears select the key and click on the 'Remove Key' button.

Now you're probably wondering, isn't there a way to make this automatically start when I login to Windows. Why yes, yes there is. You can create a shortcut to pageant, change it so that it takes your key file as an argument and put that shortcut in your 'Startup' folder.

Creating a shortcut

First, create a shortcut of the Pageant program on your desktop.

Now right click on the shortcut and select 'Properties'. In the window that appears, examine the 'Target' field. Here it sets what program to run from the shortcut, select this field and press the 'End' key to go to the end of the line. Now add the path to your private key here in double quotes. Above we created a private key in your 'My Documents' folder, so we would put the following path after the program path:

"C:\Documents and Settings\YourUsername\My Documents\ssh_private_key.ppk"

Of course, you would replace 'YourUsername' with your actual Windows username. Click 'Ok' to accept the change.

Next we will put this shortcut in the startup folder. Open an explorer window and navigate to

"C:\Documents and Settings\YourUsername\Start Menu\Programs\Startup"

Now just drag and drop the shortcut to pageant from your desktop into this Startup folder. You might rename the shortcut to something like 'pageant autostart with key' just to be clear.

Showing the location of the Pageant autostart shortcut.

Now go ahead and log out of your user in Windows or restart the computer. When you log back in, you should be prompted for your passphrase. You will probably also get the warning about the program you are trying to run is unsigned.

TCP Port Forwarding

Primer on TCP ports

Port forwarding will take a bit of explaining. You may not think you need it until you realize that it can help you get around firewalls, make it look like you are coming from somewhere else.

To understand what port forwarding is you first have to understand a bit about computer networking. The majority of network protocols on the Internet use a protocol called TCP, which is part of the Internet Protocol (IP) suite. When you make a connection to a resource like web server or an e-mail server or even an SSH server like in this document, you are connecting to a specific port number. You can think of it as part of a street address on the Internet. Actually, its more like an apartment number.

Each connection you make has a from port number and a to port number as well as a from and to IP address. The from port number is usually just randomized by your computer's operating system for safety, but the to port number determines what protocol you are going to use. Each type of application that you use on your computer has a set port number that it connects to. Below are some examples of programs that you may use, what the protocol is called and what port number the program would connect to in order to transmit and receive data.

Common Windows Network Applications and Their Standard Network Port
Example Application	Protocol	Standard TCP Port
Internet Explorer, Firefox, Opera	HTTP	80
Internet Explorer, Firefox, Opera	HTTP over SSL (https)	443
Outlook (sending mail), Thunderbird (sending mail)	SMTP	25 (465 for SMTP over SSL)
Outlook (downloading mail), Thunderbird (downloading mail)	POP3	110 (995 for POP3 over SSL)
Outlook (viewing mail), Thunderbird (viewing mail)	IMAP	143 (993 for IMAP over SSL)
PuTTY, WinSCP	SSH (also SCP and SFTP)	22
CuteFTP	FTP	21, 20 and 1024 through 65535 (One reason why FTP sucks)
mIRC, X-Chat	IRC	6667

These are the standard port numbers for the protocols. It is possible for the administrator of a server to use an arbitrary port number and most client programs are capable of configuring the port number that it uses.

Port forwarding in Putty

Because modern networks use firewalls and other access controls to restrict access, you might find yourself in a situation where connecting directly to a service from your computer can't be done. This is where port forwarding can help.

The port forwarding interface in PuTTY is accessed from the initial configuration window when you open the program. Under the 'Connection' category on the left click on 'SSH' then on 'Tunnels'

SSH Tunnels configuration

MySQL forward

For database users, such as MySQL, one of the most useful port forwards you can do is to forward port 3306 from your local machine, over your SSH connection and then to the server side's port 3306. 3306 is the default server port for MySQL. At Suso, we've firewalled out all outside access to port 3306 for security. The only way to connect to MySQL is from a machine on the Suso network. For some people, this can be a problem because they would like to use GUI applications like the MySQL administrator or query browser applications from mysql.com. These programs have to work directly with the server. So what do you do? Use an SSH tunnel.

All you need to do to create the tunnel for MySQL is put the port number 3306 in the 'Source port' and 'hostname:3306' in the 'Destination' field and then click on the 'Add' button. The Source port field sets what port the tunnel will listen on on your local machine. You will connect to this end of the tunnel by going to port 3306 on the localhost interface on your machine. The destination sets where packets will go once they reach the other end of the tunnel. Its the target if you will. In the example below, we use mysql2.suso.com:3306 as the detination. The MySQL host that you connect to might be different.

Setting the source port and destination

SMTP forward

Another useful SSH tunnel or port forward is to send SMTP (sending mail) traffic through your SSH connection. A lot of Internet Service Providers these days don't allow users to send mail to mail servers off of the ISP's network. For example, you might not be able to establish a port 25 SMTP connection to mail.suso.com, even though we would allow it. One way around this is to create a SSH tunnel for port 25. Simply put 25 in the 'Source port' and mail.suso.com:25 in the 'Destination' and click on 'Add'.

One other useful thing that can be done before clicking on Add is to check the box above that is labeled 'Local ports accept connections from other hosts'. What this does is makes your SSH tunnel available to anyone who can connect to your machine. So you can share the tunnel with people in your office, they would just need to connect to your machine's IP on port 25 with their e-mail client.

Other types of tunnels

The radio buttons below the destination field can generally be left alone. If you want the tunnel to be reversed so that it listens on a remote port on the server and sends network packets back to your computer, you can select 'Remote'.

Selecting 'Dynamic' will give you what is called a SOCKS5 tunnel. The tunnels we have talked about so far all have a static hostname on the remote or local end that can't be changed. A SOCKS5 "Dynamic" tunnel allows you to use any SOCKS5 capable program (there are more available than you might think) over the SSH dynamic tunnel. A lot of programs support this type of proxy including most web browsers, File transfer programs, Instant messaging clients, IRC clients and so on.

Remember, in the words of Benjamin "Uncle Ben" Parker, with great power comes great responsibility. Just because you can get around firewalls and use other hosts for sending network traffic, doesn't mean that some system administrator isn't going to notice you.

How To Use The Tunnels In Programs

Once you've established an SSH tunnel, you will need to do some minor configuration within the program that you want to use the tunnel.

Outlook Express

In Microsoft Outlook Express, if you have setup a tunnel to forward your outgoing mail connection, then you configure Outlook to use localhost as the outgoing mail server. This is done by going to 'Tools -> Accounts', then selecting your e-mail account, clicking on 'Properties'. Then click on the 'Servers' tab.

The Servers tab in account configuration

Depending on what port you told PuTTY to listen on on your local machine, you might need to adjust the port to use for SMTP. This is done on the 'Advanced' tab.

Setting the outgoing port is done via the Advanced tab.

Keep in mind that you must keep your SSH session going for whenever you want to send outgoing mail.

MySQL Administrator

Configuring MySQL to use your SSH tunnel is very easy. If you setup a port forward like you did above, then all you need to do is put in 'localhost' in the 'Server Name' field and leave the port at 3306.

MySQL administrator config window

Use your MySQL username and password that where provided as appropriate. Note that these are not necessarily the same as your SSH login username and password. It depends on the practices of the host. On Suso, you can find your database username and password in the mysqlinfo file.

Keeping Your SSH Session Alive

Sometimes you may have trouble keeping your SSH session up and idle. For whatever reason, the connection just dies after X minutes of inactivity. Usually this happens because there is a firewall between you and the internet that is configured to only keep stateful connections in its memory for 15 or so minutes.

PuTTY has some settings to help you control this problem. From the opening config window in PuTTY, click on the 'Connection' category on the left.

Connection config including TCP Keepalive

This screen offers two differen types of keep alives. You only need to concern yourself with the field at the top with the label 'Seconds between keepalives (0 to turn off)'. Go ahead and set this value to 300, which is 5 minutes between keep alive packets. These keep alive packets, tell the router or firewall that your session is still active. If your session still dies after setting this to 300, try 60. If that still doesn't work, then this might not be the problem. It might be that your network connection is dropping out. Talk to your network administrator. Also, reading this document will give you more insight into session drops.

Ending Your SSH Session

All good things come to an end. And there are many common ways to end your SSH session.

You might be tempted to end your session by closing the window using the standard 'X' close window button in Windows, but its not recommended. If you do this, you might confuse the server and the session might stay running. This all depends on the server environment. Its generally not a good thing to do.

Here are a few common ways that you can properly end your SSH session.

exit