Configuring and using PuTTY/Pageant

PuTTY is a free and easy to use ssh client for Windows. You can use it to connect to your favorite remote Linux servers in text mode, and start remote graphical applications if you also have a running X server

Installation

Official web site: PuTTY Web site

You can install the latest version of PuTTY directly from Microsoft Store, or download the latest 64-bit msi installer

Launching PuTTY/Pageant

You could directly launch PuTTY (Start => PuTTY => PuTTY), but it is actually more efficient to launch Pageant, especially if you are often going to connect to the same server(s)

Starting Pageant: Start => PuTTY => Pageant

Pageant is an ssh agent for Windows, but this page also explains how to use it for easily creating and using connection profiles (aka Sessions) to connect to remote Linux servers

Some applications (e.g. WinSCP) will automatically try to use Pageant as an ssh-agent, instead of asking you to type your ssh passphrase

It will seem that nothing happens when you start Pageant, but you should get the Pageant icon at the bottom right of your screen.

If you right click on the Pageant icon, you can manage sessions with the New Session option, use Saved Sessions profiles and manage ssh keys (View Keys, Add Key).
You can also view/add ssh keys by double clicking on the pageant icon

Configuring PuTTY

Launch the PuTTY Configuration manager: (Right click on) Pageant => New Session

You can keep most PuTTY's default settings. This section will show you how to create your first session profile, with some highly recommended options.
If you want to add another session later, just Load an existing (and properly configured) session, Save it under a new name, change the session details, and then save the session again.

When changing a setting, select a (sub-)Category in the left part of the PuTTY Configuration window, and change the displayed settings in the right part of the window.

After changing the settings of an existing Session, do not forget to go back to the Session category (at the top left of the Putty Configuration window) and click Save!

Creating a new session

In the Session Category:

Specify a Host Name: e.g. ssh1.lsce.ipsl.fr for the LSCE access server (also called LSCE gateway)

Specify a matching session name in Saved Sessions: e.g. ssh1

Click on Save to save the new session (that will only have default settings for now)

If you are in a hurry, you can connect to the Linux server specified in the Host Name field by clicking on Open

Changing some useful settings

Load an existing session (e.g. the ssh1 profile defined above), that will serve as a template (with the recommended settings) for the future sessions

In the Window => Selection category:

Select xterm in the Actions of mouse buttons section.
This will allow you to use the mouse buttons in the PuTTY terminal the same way you would use them in an standard Linux xterm terminal:

Select and Copy text (at the same time) with the left button

Paste text with the middle button

In the Window => Appearance category:

You can choose a font more readable than the default one!
We recommend the Cascadia Code font that comes with the Windows Terminal application (which means that you first have to install Windows Terminal first, but you will probably need it anyway)

Use the Change... button in the Font settings section, and select Cascadia Code and Regular (you can also experiment with styles different from Regular, and different font sizes)

In the Connection => Data category:

Specify your login name (on the LSCE servers) in Auto-login username. This way you won't have to type it when you connect to the Linux server!

In the Connection => SSH => Kex category:

Unselect Attempt GSSAPI key exchange!
If you forget to do this, connecting to a server will seem to take forever (if it works at all)...

In the Connection => SSH => Auth category:

Select Allow agent forwarding. This is the same as using ssh with the -A option

In the Connection => SSH => X11 category:

Select Enable X11 forwarding. This is the same as using ssh with the -X option
Note: remember that you will also need an X server running in order to display graphics!

When you have finished updating the settings, do not forget to go back to Category => Session and Save the session!

Click on Open to connect to the specified host with the updated settings, and check that things are working properly
The first time you connect to a server, you will get a PuTTY Security Alert window, where you have to click on Accept to tell PuTTY that you trust the connection to this new server

Adding more connection profiles

Start Pageant, and then the PuTTY Configuration manager: (Right click on) Pageant => New Session

New profile for a direct connection to a remote server

Select an existing session (e.g. the ssh1 profile defined above) and click on Load

Update the values of the Host Name and Saved Session (the name of the new profile you want) text fields, and settings

Example: connecting to LSCE from INSIDE LSCE
(inside <=> computer connected to the wired network):

Host Name => obelix

Saved Session => obelix (direct connection)

Example: connecting to ciclad:

Host Name => ciclad.ipsl.upmc.fr

Saved Session => ciclad

do not forget to specify your ciclad login in: Connection => Data => Auto-login username

you will also need an ssh key if you want to connect to ciclad !!

Go back to Category => Session and Save the session

New profile with a connection through a gateway

Select an existing gateway session (e.g. ssh1) and click on Load.
For connecting to LSCE from OUTSIDE LSCE, select the ssh1 profile
If you are at LSCE, but use the eduroam or the guest WiFi network, you are considered as being outside LSCE!

In the Connection => SSH category, specify the command used to connect to the target server in the Remote command field
e.g. for LSCE, use:

ssh -X -A obelix (check the useful ssh options for more details on the options)

Go back to Category => Session, specify a new profile name in Saved Sessions (e.g. obelix via ssh1) and Save the session

Daily usage of PuTTY/Pageant

Note: PuTTY will ask your password each time you open a session, unless you have ssh keys, and you use Pageant to store your passphrase

Starting a session from Pageant

Once you have started pageant, and configured sessions, you can easily open terminals on the remote servers by right-clicking on the pageant icon, and selecting a Saved Session.

Starting a session from a desktop shortcut

It is possible to create a shortcut on the desktop to start a specific session!

Right-click on the desktop and select New => Shortcut

Specify the location of putty.exe in the path field, and click Next:
"C:\Program Files\PuTTY\putty.exe" (with the quotes!)

Specify the name of the shortcut (as it will appear on the desktop), and save the shortcut
e.g. obelix via ssh1

Right-click on the shortcut and select Properties, then add the name of the desired profile to the content of the Target field

Warning:

you have to use an existing session name (as it appears in Pageant => Session => Saved Sessions)

you have to use quotes correctly, otherwise you will get an error message!

Examples:

"C:\Program Files\PuTTY\putty.exe" -load "obelix via ssh1"

"C:\Program Files\PuTTY\putty.exe" -load "obelix (direct)"

Click OK to save the changes

You can now connect to the remote server just by clicking on the desktop shortcut, instead of right-clicking on the Pageant icon!

Using ssh keys with PuTTY/Pageant

In this section, we will use files that have the same base name, and different extensions. You should make sure that you can see hidden folders, and files' extensions before you go further!
Read the Using ssh keys section if you don't know what ssh keys are

Do not lose the (existing) ssh keys files you have, or the keys that you will create It is recommended to keep a copy of these files on another computer! Do not forget the passphrase that will be used to unlock the private key If you save the passphrase in a file, do not put this file in the same place as the ssh keys Read Do not forget your passphrase! if you need some advice about passphrases The best thing to do is probably to keep the keys in the standard ssh configuration directory!

Converting existing ssh keys with PuTTYgen

If you already have a private ssh key generated on another computer (e.g. an id_ed25519 text file), you just have to use PuTTYgen to import the existing private key, and then export it to a converted id_ed25519.ppk file that Pageant can use

Move the id_ed25519 key file to the Windows ssh configuration directory

=> C:\Users\your_windows_login\.ssh\id_ed25519

Launch the PuTTY Key Generator: Start => PuTTY => PuTTYgen

Open the Conversions=>Import key menu

Select the existing id_ed25519 private key file (or another valid private key) and type the passphrase to unlock and import it

Click on the Save private key button, and create an id_ed25519.ppk file in the Windows ssh configuration directory

=> C:\Users\your_windows_login\.ssh\id_ed25519.ppk

Creating ssh keys with PuTTYgen

If you don't already have an existing set of recent-enough ssh keys, follow the steps below to create a set of private and public keys.

Notes:

by recent-enough, we mean ssh keys of type rsa and preferably ed25519 (dsa is deprecated)

extra technical details (that you can probably safely ignore) are available in the official Using PuTTYgen, the PuTTY key generator documentation

Steps:

Launch the PuTTY Key Generator: Start => PuTTY => PuTTYgen

Make sure that the selected Type of key to generate (at the bottom of the PuTTYgen window) is EdDSA (short for Edwards-curve DSA), with the default 255 bits.
This will generate ed25519 keys that are now recommended on the IPSL servers

You could also use RSA and 4096 bits, but ed25519 keys are now recommended on the IPSL servers

Click on the Generate button and move your mouse to generate some random information

Type your Key passphrase and confirm it

Read Do not forget your passphrase! if you need some advice about passphrases

Click on the Save private key button, and create an id_ed25519.ppk file

Note: files with a .ppk extension can only be used by PuTTY/pageant. That's why you also need to export the private key, as shown below

Important! Click Conversions=>Export OpenSSH Key and create an id_ed25519 file (a text file with no .ppk extension)

You will not need this file when you use PuTTY, but you may need to use this private key in a standard text format later, on Linux computers/servers

Open a text editor and create an id_ed25519.pub file

Save the content of the Public key for pasting into OpenSSH authorized_keys file field in the file
Something looking like

ssh-ed25519 AAAAC3NzaC1lZDI[... lots of characters ...]vwjLNmY eddsa-key-20230310

Click on the Save public key button, and create a id_ed25519.pub file

You will need to install the public key on all the remote Linux server that you want to connect to using the ssh agent, instead of typing your password

Using the private key in Pageant

We assume that the private key file is available locally in <some_disk_different_from_c>:\Users\<your_login>\ssh\

Start Pageant and open the Pageant Key List window by:

Double-clicking (left mouse button) on Pageant

Or right-clicking on Pageant and choosing View keys

Click on Add Key, navigate to the directory where you have stored the .ppk converted private key file (e.g. \Users\<your_login>\ssh\), open it and type your passphrase. You can Close the Pageant Key List once the key appears there

If everything was done correctly, you should now be able to open the Sessions defined in Pageant, on remote servers where the public key matching the private key used in Pageant was installed correctly

[ PMIP3 Wiki Home ] - [ Help! ] - [ Wiki syntax ]