====== Configuring and using PuTTY/Pageant ======

PuTTY is a free and easy to use [[other:ssh|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 [[other:x_conf|X server]]

===== Installation =====

Official web site: [[https://www.chiark.greenend.org.uk/~sgtatham/putty/|PuTTY Web site]]

You can install the latest version of PuTTY directly from [[https://apps.microsoft.com/store/detail/XPFNZKSKLBP7RJ|Microsoft Store]], or download the latest [[https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html|64-bit msi installer]]

==== Updating PuTTY ====

Download the latest version, or just type ''winget upgrade %%--%%id XPFNZKSKLBP7RJ'' in a [[other:win10apps#windows_terminal|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 [[other:ssh#using_an_ssh_agent|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. [[other:win10apps#winscp|WinSCP]]) will automatically try to use ''Pageant'' as an //ssh-agent//, instead of asking you to type your [[other:putty_conf#using_ssh_keys|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.\\ {{ :other:putty_01_notes_v2.png?direct |}}

  * 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\\ {{ :other:putty_02.png?direct |}}

===== Configuring PuTTY =====

Launch the PuTTY Configuration manager: (Right click on) ''Pageant'' => ''New Session''\\ {{ :other:putty_03.png?direct&300 |}}

  * 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.

  * <wrap hi>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''!**
</wrap>
==== 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)\\ {{ :other:putty_04.png?direct |}}

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 [[#creating_a_new_session|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**\\ {{ :other:putty_05.png?direct |}}
  * 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 [[other:win10apps#windows_terminal|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 **[[https://en.wikipedia.org/wiki/Consolas|Consolas]]** font in the list of available fonts
    * 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), or ''Consolas'' and ''Regular'' or ''Bold''\\ {{ :other:putty_cascadia_font.png?direct |}} {{ :other:putty_cascadia_styles.png?direct |}}
  * 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!\\ {{ :other:putty_06_v2.png?direct |}}
    * You should also specify ''xterm-256color'' instead of the default ''xterm'' terminal type in the ''Terminal-type string'' field. This will allow you to display nicer colors in the terminals (for the applications that use fancy colors)
      * You can later open a terminal and type ''msgcat %%--%%color=test'', and check if you get something like\\ {{ :other:putty_256colors.png?direct&200 |}}
  * In the ''Connection'' => ''SSH'' => ''Kex'' category:
    * **<wrap hi>Unselect Attempt GSSAPI key exchange</wrap>**!\\ If you forget to do this, connecting to a server will seem to take forever (if it works at all)...\\ {{ :other:putty_gssapi.png?direct |}}
  * In the ''Connection'' => ''SSH'' => ''Auth'' category:
    * Select **Allow agent forwarding**. This is the same as [[/other:ssh#standard_usage|using ssh with the -A option]]\\ {{ :other:putty_07.png?direct |}}
  * In the ''Connection'' => ''SSH'' => ''X11'' category:
    * Select **Enable X11 forwarding**. This is the same as [[/other:ssh#standard_usage|using ssh with the -X option]]\\ Note: remember that you will also need an [[other:x_conf|X server running]] in order to display graphics!\\ {{ :other:putty_08.png?direct |}}

  * When you have finished updating the settings, **do not forget to go back to ''Category'' => ''Session'' and Save the session**!\\ {{ :other:putty_09.png?direct |}}

  * 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\\ {{ :other:putty_new_host.png?direct |}}

==== Adding more connection profiles ====

[[other:putty_conf#launching_putty_pageant|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 [[#creating_a_new_session|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 [[https://documentations.ipsl.fr/spirit/spirit_clusters/head_nodes.html|spirit]]:
      * ''Host Name'' => ''spirit1.ipsl.fr''
        * <wrap em>WARNING!</wrap> You can only connect to spirit using a pair of //ssh keys//. Be sure to read the [[other:putty_conf#using_ssh_keys_with_putty_pageant|Using ssh keys with PuTTY/Pageant]] section below
        * You can also use ''spirit2'', ''spiritx1'' or ''spiritx2'' depending on [[https://documentations.ipsl.fr/spirit/spirit_clusters/head_nodes.html|which IPSL server you want to access]]
      * ''Saved Session'' => ''spirit1''
      * do not forget to **specify your IPSL login** in: ''Connection'' => ''Data'' => ''Auto-login username''
  * Go back to ''Category'' => ''Session'' and <wrap em>**Save** the session</wrap>

=== 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 [[#creating_a_new_session|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:
    * ''ssh -X -A obelix'' (check the [[other:ssh#standard_usage|useful ssh options]] for more details on the options)\\ {{ :other:putty_10b.png?direct |}}
  * Go back to ''Category'' => ''Session'', <wrap hi>specify a new profile name</wrap> in **Saved Sessions** (e.g. ''obelix via ssh1'') and <wrap em>**Save** the session</wrap>\\ {{ :other:putty_11.png?direct |}}
 
===== Daily usage of PuTTY/Pageant =====

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

==== Starting a session from Pageant ====


Once you have [[#launching_putty_pageant|started pageant]], and [[#using_putty_pageant|configured sessions]], you can easily open terminals on the remote servers by right-clicking on the pageant icon, and selecting a **Saved Session**. \\ {{ :other:putty_12.png?direct |}}

==== Starting a session from a desktop shortcut ====

It is possible to [[https://the.earth.li/~sgtatham/putty/0.77/htmldoc/AppendixA.html#QA.6.4|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 =====

<WRAP center round alert 60%>
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 [[other:win10config#displaying_hidden_folders_and_files_and_the_files_extension|see hidden folders, and files' extensions]]** before you go further!
</WRAP>


Read the [[other:ssh#using_ssh_keys|Using ssh keys]] section if you don't already know what //ssh keys// are
<WRAP center round important 80%>
  * **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 [[other:ssh#some_common_sense_advice|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 [[other:ssh#configuration_files|ssh configuration directory]]** of each desktop/laptop/servers you use!
</WRAP>
==== 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 [[other:ssh#configuration_files|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\\ {{ :other:putty_21b.png?direct&300 |}}

  * 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 [[other:ssh#configuration_files|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 [[https://the.earth.li/~sgtatham/putty/0.78/htmldoc/Chapter8.html#pubkey-puttygen|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
    * {{:other:putty_23b.png?direct&500|}}
    * You could also use ''RSA'' and ''4096'' bits, but ''ed25519'' keys are now recommended to access the [[https://documentations.ipsl.fr/spirit/spirit_clusters/head_nodes.html|IPSL servers]]

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

  * Type your ''Key passphrase'' and confirm it
    * Read [[other:ssh#some_common_sense_advice|Do not forget your passphrase!]] if you need some advice about passphrases

  * Click on the ''Save private key'' button, and create the ''id_ed25519**.ppk**'' **Pageant //private// key file**
    * We recommend that you save this file in the the Windows [[other:ssh#configuration_files|ssh configuration directory]]\\ => ''C:\Users\your_windows_login\.ssh\id_ed25519.ppk''
    * 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 the ''id_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 the ''id_ed25519**.pub**'' file\\ Something looking like\\ <code>ssh-ed25519 AAAAC3NzaC1lZDI[... lots of characters ...]vwjLNmY eddsa-key-20230310</code>
    * This is the **//public// key** that you will need to [[other:ssh#installing_ssh_keys|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 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\\ {{ :other:putty_private.png?direct&300 |}}
  * 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 [[other:ssh#installing_ssh_keys|installed correctly]]

/* standard page footer */

\\ \\ \\ 
----
[ [[pmip3:|PMIP3 Wiki Home]] ] -
[ [[pmip3:wiki_help|Help!]] ] -
[ [[wiki:syntax|Wiki syntax]] ]