Table of Contents
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
Updating PuTTY
Download the latest version, or just type winget upgrade --id XPFNZKSKLBP7RJ
in a Windows Terminal
Launching PuTTY/Pageant
You could directly launch PuTTY (Start
⇒ PuTTY
⇒ PuTTY
), but it is actually more efficient to use Pageant
for opening terminals, 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
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, justLoad
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
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
- 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)
IF Windows Terminal is not installed yet, you can select the modern Consolas font in the list of available fonts
- In the
Connection
⇒Data
category:- You should also specify
xterm-256color
instead of the defaultxterm
terminal type in theTerminal-type string
field. This will allow you to display nicer colors in the terminals (for the applications that use fancy colors)
- In the
Connection
⇒SSH
⇒Kex
category: - In the
Connection
⇒SSH
⇒Auth
category: - 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!
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 (and correctly configured) 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 spirit:
Host Name
⇒spirit1.ipsl.fr
- WARNING! You can only connect to spirit using a pair of ssh keys. Be sure to read the Using ssh keys with PuTTY/Pageant section below
Saved Session
⇒spirit1
- do not forget to specify your IPSL login in:
Connection
⇒Data
⇒Auto-login username
- 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 from the gateway, in the Remote command field
e.g. for LSCE, use:
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 clickNext
:
"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 key files that have the same base name, and different extensions: e.g. id_ed25519
, id_ed25519.pub
and id_ed25519.ppk
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 already 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 store the key files in the standard ssh configuration directory of each desktop/laptop/servers you use!
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
- 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 anid_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) isEdDSA
(short for Edwards-curve DSA), with the default255
bits.
This will generate ed25519 keys that are now recommended on the IPSL servers- You could also use
RSA
and4096
bits, buted25519
keys are now recommended to access 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 theid_ed25519.ppk
Pageant private key file- We recommend that you save this file in the the Windows ssh configuration directory
⇒C:\Users\your_windows_login\.ssh\id_ed25519.ppk
- Note: files with a
.ppk
extension can only be used byPuTTY
/pageant
. That's why you also need to export the private key, as shown below
- Important! Click
Conversions
⇒Export OpenSSH Key
and create theid_ed25519
standard private key file (a text file with no.ppk
extension)- ⇒
C:\Users\your_windows_login\.ssh\id_ed25519
- 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 the
id_ed25519.pub
standard public key file- ⇒
C:\Users\your_windows_login\.ssh\id_ed25519.pub
- Save the content of the
Public key for pasting into OpenSSH authorized_keys file
field in theid_ed25519.pub
file
Something looking like
ssh-ed25519 AAAAC3NzaC1lZDI[... lots of characters ...]vwjLNmY eddsa-key-20230310
- This is the public key that you will need to install on all the remote Linux server that you want to connect to using the ssh agent, instead of typing your password
- WARNING! Do not use the
Save public key
button to create the public key file, because the resulting file will not be standard enough to be used directly on Linux computers
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 thePageant Key List
window by:- Double-clicking (left mouse button) on
Pageant
- Or right-clicking on
Pageant
and choosingView keys
- 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 inPageant
was installed correctly
[ PMIP3 Wiki Home ] - [ Help! ] - [ Wiki syntax ]