PMIP3 wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Understanding and using ssh correctly ======

<WRAP center round tip 60%>
Everything you always wanted to know about //ssh//, //ssh keys//, the //passphrase// and //ssh agent//, but were afraid to ask

At least everything you need to know in order to work efficiently, without getting bored to death
</WRAP>


===== A quick introduction =====

  * ''ssh'' is a program for connecting securely to a remote server and for executing commands on this server
    * More precisely ''ssh'' is an //SSH client// using the //SSH protocol//

  * We assume below that you have a ''my_login'' account on the remote ''remote_server'' computer, and that you know your password
    * This page will also show some examples using the [[https://intranet.lsce.ipsl.fr/informatique/fr/inter.php|LSCE]], [[https://mesocentre.ipsl.fr/|IPSL Mésocentre ESPRI]] and [[https://intranet.lsce.ipsl.fr/informatique/en/tgcc.php|TGCC]] servers

  * Instead of a password, you can also [[other:ssh#using_ssh_keys|use a set of private and public keys and a passphrase]]
    * This is the only kind of authentication that will work if you need to use the [[https://mesocentre.ipsl.fr/|IPSL Mésocentre ESPRI]] (aka //**ciclad** and **climserv**//)!

  * Many programs are said to //work over ssh// when they implicitly use the //ssh protocol// to securely transfer data from one server to another: ''scp'' (copy remote directories and files), ''rsync'' (synchronize remote directories and files), ...

  * Some history: before you were born, and the world and internet were a safer place, people used less secure programs like ''telnet'', ''rlogin'', ''rsh'', ''ftp'', ...

===== Using ssh =====

==== Standard usage ====

<WRAP center round tip 60%>
  * The following will work in a **Linux** terminal, but can also work in a //terminal// on a **Mac** or on a **Windows 10** computer

  * On **Windows 10**, ''ssh'' is directly available in a ''Windows Powershell'', a [[other:win10apps#windows_terminal|Windows Terminal]] or the old ''cmd'', but the most user-friendly way to use ''ssh'' is to use [[other:putty_conf|PuTTY]]

  * On a **Mac**, ''ssh'' is directly available in the built-in Apple [[other:ssh#a_recommended_terminal_for_mac|Terminal application]]

</WRAP>

  * **''ssh [options] [my_login@]remote_server''**
    * If your login is the same on the local and remote computer, you can omit the optional ''my_login@'' part:\\ e.g. simply use ''ssh ssh1.lsce.ipsl.fr'' instead of ''ssh my_login@ssh1.lsce.ipsl.fr''
    * The **first time** you connect to a **new server**, ''ssh'' will ask if you are sure of what you are doing, and then store some unique information about the remote server in the ''known_hosts'' file ([[#configuration_files|details]]).\\ <code>PS C:\Users\my_login> ssh ciclad.ipsl.jussieu.fr
The authenticity of host 'ciclad.ipsl.jussieu.fr (134.157.176.129)' can't be established.
RSA key fingerprint is SHA256:n6wFvMaJuyInd0LNhp78dfMd04Dr751lEekcU7X2UfU.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'ciclad.ipsl.jussieu.fr,134.157.176.129' (RSA) to the list of known hosts.
my_login@ciclad.ipsl.jussieu.fr: Permission denied (publickey,hostbased).</code>\\ ''ssh'' will automatically check this security information each time you connect to the same server, and warn you if something seems wrong.

==== Most common options ====

  * ''-X'' or ''-Y'' options if you will need to **use graphical programs on the remote server**
    * All the Details in the [[other:ssh#using_an_x_server_to_display_graphics|Using an X server to display graphics]] section

  * ''-A'': **enable //agent forwarding//**. This is useful when you use [[other:ssh#using_ssh_keys|ssh keys and an ssh agent]]

  * ''-t command'': this option allows you to **execute a specific command on the remote server** (without displaying the output of the initial ''ssh''). We use this mostly to //chain ssh connections//, when we want to automatically go through a specific //gateway// server to access another server\\ e.g. ''ssh -A -X my_login@ssh1.lsce.ipsl.fr -t ssh -A -X obelix''

  * ''-v'': **verbose mode**. Use this option only when you can't connect, or things don't seem to work correctly. Analyzing the verbose output when you start ''ssh'' should allow you, or the [[other:newppl:starting#getting_help_from_the_lsce_system_administrators|system administrators]], to find out what is wrong

==== Connecting to servers commonly used by LSCE users ====

=== LSCE servers ===

There are several ways to use ''ssh'' to connect to the LSCE ''obelixNN'' servers (more details about the [[other:newppl:starting#which_linux_servers_should_you_use)|available LSCE servers]])

  * If your computer is **on the LSCE ethernet/wired network**:
    * Go to the server with the smallest [[other:newppl:starting#determining_the_load_of_a_linux_server|load]]:\\ ''ssh -A -X my_LSCE_login@obelix''\\ or ''ssh -A -X my_LSCE_login@obelix.lsce.ipsl.fr''
    * Go to a specific ''obelixNN'' (possibly because you have some running processes on this server that you want to monitor with [[other:newppl:starting#determining_the_load_of_a_linux_server|top]], or terminate with ''kill'')\\ e.g. ''ssh -A -X my_LSCE_login@obelix4''
  * If your computer is **outside LSCE**, or **on the LSCE WiFi network**, you have to:
    * Ask your advisor to send a mail to [[other:newppl:starting#getting_help_from_the_lsce_system_administrators|help-lsce]], and request an access to the ''ssh1'' server
    * Connect through the ''ssh1'' gateway server, i.e you first use ''ssh'' to connect to the ''ssh1'' gateway, and then use ''ssh'' to go to an ''obelix'' server\\ These two ''ssh'' commands can be [[other:ssh#most_common_options|conveniently chained with the '-t' option]]!\\ ''ssh -A -X my_LSCE_login@ssh1.lsce.ipsl.fr -t ssh -A -X obelix''

=== IPSL servers ===

If you want to connect to the [[https://documentations.ipsl.fr/spirit/spirit_clusters/head_nodes.html|IPSL servers]] (only possible with [[other:ssh#using_ssh_keys|ssh keys]]!):
  * [[https://mesocentre.ipsl.fr/account-opening/|Requesting an account at IPSL]]
  * Connecting to ''spirit1'':
    * ''ssh -A -X my_meso_login@spirit1.ipsl.fr''
    * Depending on what you need to do, you can also use ''spirit2'', ''spiritx1'' or ''spiritx2''
  * [[https://documentations.ipsl.fr/spirit/spirit_clusters/head_nodes.html|More details]]
  * Note: the ''ciclad'' server may still be accessible when you read this page, but its usage has been deprecated in favor of the ''spirit'' servers

=== TGCC (super)computers ===

If you want to use the [[https://www-hpc.cea.fr/tgcc-public/en/html/tgcc-public.html|TGCC computers]] (e.g. ''irene''):

  * Note: you have to go //trough// the ''ssh1'' LSCE gateway to access the TGCC, even if you are on the LSCE wired network!
  * ''ssh -A -X my_LSCE_login@ssh1.lsce.ipsl.fr -t ssh -A -X my_TGCC_login@some_tgcc_login_node''
    * Once you are on a TGCC login node (e.g. ''irene''), you can get lots of information by typing ''<node>.info'' (e.g. ''irene.info'')
  * [[https://intranet.lsce.ipsl.fr/informatique/en/tgcc.php|more TGCC connection details]]

=== IDRIS (super)computers ===

FIXME


==== Using shell aliases shortcuts to connect to the servers ====

If you have to use ''ssh'' regularly (with the appropriate options), you should define convenient //shell aliases//, or [[other:putty_conf#adding_more_connection_profiles|add PuTTY connection profiles]] on Windows

=== bash shell users ===

Define the following aliases in the ''~/.bashrc'' configuration file of your local Linux account

<code>
# Connecting to LSCE from a computer on the LSCE network
alias obelix='ssh -A -X my_LSCE_login@obelix'

# Connecting to LSCE from outside the LSCE network
alias sobelix='ssh -A -X my_LSCE_login@ssh1.lsce.ipsl.fr -t ssh -A -X obelix'

# Connecting to ciclad @ IPSL
alias ciclad='ssh -A -X my_ciclad_login@ciclad.ipsl.jussieu.fr'

# Connnecting to irene @ TGCC
alias sirene='ssh -A -X my_LSCE_login@ssh1.lsce.ipsl.fr -t ssh -A -X my_TGCC_login@irene-ccrt.ccc.cea.fr' 
</code>

=== tcsh shell users ===

If your connection shell is ''tcsh'' instead of ''bash'', use the appropriate alias syntax in your ''~/.cshrc'' configuration file,\\ e.g. ''alias obelix 'ssh -A -X my_LSCE_login@obelix' ''

==== Using an X server to display graphics ====

A terminal can be used to display text information\\ e.g. the output of ''ls'' and ''top'', the ''vi'' editor, etc...\\ but also to start programs that will open new (graphical) windows outside of the initial terminal\\ e.g. ''evince'' to display pdf files, ''eog'' to display png/jpg images, the ''emacs'' editor, ''ferret'', etc...

If you want to **use ''ssh'' to start graphical programs on a remote server**, you need to:

  * **Use ''ssh -X''** (or ''ssh -Y'' if ''-X'' does not work) to connect to the remote server
    * ''-X'': **enable //X11 forwarding//**
    * ''-Y'': enable //trusted// X11 forwarding (low security, but you //trust// the remote server)
    * Using the ''-X''/''-Y'' option will **automatically** define the ''DISPLAY'' environment variable that is required by graphical programs on the remote server to determine where to display the graphical windows.\\ ''DISPLAY'' will **not** be defined if you forget to use ''-X''/''-Y''\\ 
    * Example:\\ <code>my_login@my_local_computer:~$ echo $DISPLAY
localhost:0.0

my_login@my_local_computer:~$ ssh ssh1.lsce.ipsl.fr
Last login: Wed Jul  8 14:45:31 2020 from [...some address...]
[my_login@ssh1 ~]$ echo $DISPLAY
DISPLAY: Undefined variable.
[my_login@ssh1 ~]$ logout
Connection to ssh1.lsce.ipsl.fr closed.

my_login@my_local_computer:~$ ssh -X ssh1.lsce.ipsl.fr
[my_login@ssh1 ~]$ echo $DISPLAY
localhost:43.0</code>
  * **And** [[other:x_conf|have a local X server running]]!

==== Configuration files ====

''ssh'' will store all its **configuration files** in a ''.ssh'' sub-directory of your //home// directory. The configuration files are in a //text// format.

  * **Linux**: ''~/.ssh/'' directory
  * **Windows**: ''C:\Users\your_windows_login\.ssh'' directory
  * **Mac**: ''/Users/your_mac_login/.ssh'' directory (should be the same path as ''~/.ssh/'')

You will find (some of) the following text files:
  * ''known_hosts'': the text file were ''ssh'' stores one line of security information about each server you have connected to from this computer\\ e.g. ''ciclad.ipsl.jussieu.fr,134.157.176.253 ssh-rsa AAAAB3NzaC1y[a long identifier...]''

  * ''config'': an optional configuration text file, e.g.\\ <code># Empty lines and lines starting with '#' are "comments"
# More details => man ssh_config

ServerAliveInterval=120
ServerAliveCountMax=90</code>

  * [[#using_ssh_keys|ssh keys]] related information:
    * ''authorized_keys'': the //public key(s)// of the account(s) authorized to connect to //this// account.
    * the **//private// (and probably the //public//) //ssh key(s)//** used on this account
      * e.g. ''id_ed25519'' and ''id_ed25519.pub'' files

==== A recommended ssh client for Windows ====

[[other:putty_conf|PuTTY]] is a convenient and user-friendly //ssh client// for Windows


==== A recommended terminal for Mac====

A ''Terminal'' window will open a local Linux-like shell session on the Mac, where you can use ''ssh'' to connect to another server, or other standard Linux commands

  * Built-in: ''Terminal'' application (available in ''/Applications/Utilities'')
    * [[https://support.apple.com/guide/terminal/welcome/mac|Terminal User Guide]]
  * Recommended: the [[https://iterm2.com|iTerm2]] application
    * Improved //Favorite Sessions// settings

==== Solving common problems ====

  * [[other:x_conf#troubleshooting|X server related errors]]

  * Other types of errors: remember that you can run ''ssh'' in **verbose** mode to help you determine what is wrong (''-v'' option)

===== Copying files between servers/computers =====

Sometimes you need to copy files from one remote server (or your desktop) to the other. The files can be securely copied //over ssh// with the ''scp'' command

Note: you should **keep the big data files were their original version is** instead of duplicating them, and move the data processing (your scripts, etc...) to the server where the original files are located (e.g. the ''ciclad'' server at IPSL)

==== Copying files with scp ====

<WRAP center round tip 60%>
Note: the following will work in a **Linux** terminal, but can also work in a //terminal// on a **Mac** or on a **Windows 10** computer (''scp'' is directly available in ''Windows Powershell'', [[https://www.microsoft.com/store/productId/9N0DX20HK701|Windows Terminal]] or the old ''cmd'', but it is not the most user-friendly way to use ''scp'' on Windows)

If you have a Windows computer, it is much easier to use [[other:win10apps#winscp|WinSCP]] for copying files
</WRAP>

  * **''scp [options] local_path_or_file(s) [my_login@]remote_server:remote_path''**\\ or **''scp [options]  [my_login@]remote_server:remote_path_or_file(s) local_path''**
    * If your login is the same on the local and remote computer, you can omit the optional ''my_login@'' part
    * If you are copying files from a remote server to the current local directory, you can use ''.'' instead of the full path of the local directory:\\ <code>$ cd /some/path
$ scp -p ssh1.lsce.ipsl.fr:/some/remote/path/scatter_regress_example.py .
scatter_regress_example.py                    100% 4988   134.6KB/s   00:00</code>
    * if you need to use [[https://www.tecmint.com/use-wildcards-to-match-filenames-in-linux/|wildcards]] to specify the files you want to copy, you can use quotes around the path specification:\\ <code>$ scp -p ssh1.lsce.ipsl.fr:'/some/remote/path/matplotlib/plot_lat_test.*' .
plot_lat_test.eps                             100%   43KB   1.0MB/s   00:00
plot_lat_test.pdf                             100%   20KB 853.8KB/s   00:00
plot_lat_test.png                             100%   77KB   1.5MB/s   00:00</code>

  * Most common options:
    * ''-p'': **preserves modification times**, access times, and modes from the original file.\\ This option is **very useful** if you want the copied file(s) to have the same date/time as the original file(s). Otherwise, the time will be the time when you copy the file(s)...
    * ''-r'': **recursively** copy entire directories.\\ **You have to use this option if the source location is a directory**. ''scp -r'' will copy the complete content of the directory (including sub-directories)

==== A recommended graphical scp client for Windows ====

[[other:win10apps#winscp|WinSCP]] is a convenient and user-friendly //scp client// for Windows

==== A recommended graphical scp client for Mac ====

FIXME

==== Mirroring directories with rsync ====

In some cases, you may want to **mirror the content of directories**:
  * because you are creating a backup
  * because you have lots of files, possibly (very) big, and you don't want to start copying everything again if the copy fails for some reason (e.g. temporary network problems if you transfer data between servers)
  * //mirroring// means that, after running ''rsync'', the ''SRC'' (//Source//) and ''DST'' (//Destination//) directories will have the exact same content (**files in ''DST'' and not in ''SRC'' will be deleted**)

''rsync'' is a convenient **Linux** command that can be used for //mirroring// a directory hierarchy to another location on the same computer (e.g. a removable disk), or a remote Linux machine, //over ssh//.

//Mirroring// means, in the ''rsync'' case, that we will **only copy new or changed files**. The first //copy// may take some time, but will be much faster afterwards, when only a few files have been created/changed and have to be copied. Or, if a copy is interrupted, the files already copied will not be copied a second time.

<WRAP center round important 60%>
**Warning!** <wrap em>It is easy to lose files with ''rsync'' if you use the wrong syntax or options!</wrap>

Mirroring //no files// by mistake, to a place where there are files, when using the ''%%--%%delete'' option, means that existing files or whole directory hierarchies will be deleted!

  * Be sure to understand the basic options, and use ''%%--%%dry-run'' (simulate what would be done) and ''-v'' (verbose) before performing the actual mirroring
  * <wrap em>Having a trailing ''/'' or not behind a directory name makes a difference!</wrap>
</WRAP>

=== Basic rsync syntax ===

Note: use ''man rync'' to get all the details and options

Local usage: ''rsync [OPTIONS] SRC DEST''

Remote usage (i.e. the ''SRC'' and ''DEST'' directories are on different Linux machines):

<code>         Pull: rsync [OPTIONS] [USER@]HOST:SRC... DEST
         Push: rsync [OPTIONS] SRC... [USER@]HOST:DEST</code>

<code>
-a, --archive               archive mode; equals -rlptgoD (no -H,-A,-X)
        -r, --recursive             recurse into directories
        -l, --links                 copy symlinks as symlinks
        -p, --perms                 preserve permissions
        -t, --times                 preserve modification times
        -g, --group                 preserve group
        -o, --owner                 preserve owner (super-user only)
            --devices               preserve device files (super-user only)
            --specials              preserve special files
        -D                          same as --devices --specials


-v, --verbose               increase verbosity
-z, --compress              compress file data during the transfer
-W, --whole-file            copy files whole (w/o delta-xfer algorithm)
-C, --cvs-exclude           auto-ignore files in the same way CVS does
             RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state .nse_depinfo *~ #* .#* ,*  _$*
             *$  *.old  *.bak  *.BAK *.orig *.rej .del-* *.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln
             core .svn/ .git/ .hg/ .bzr/

--delete                delete extraneous files from dest dirs

-n, --dry-run               perform a trial run with no changes made
-c, --checksum              skip based on checksum, not mod-time & size
</code>

=== Examples ===

  * We have an existing //source// ''/mnt/h/test/'' directory that we would like to //mirror// to another disk or //destination//, as ''/mnt/i/test/''.\\ i.e we want to recursively copy the content of ''test/'' to a ''test/'' directory //somewhere else//\\ \\ The examples below are on the same machine, but we could do a copy/mirror //over ssh// by just adding ''[USER@]HOST:'' in front of the //Source// or //Destination// directory\\ \\ 
    * Show what would be done, but do not do it (yet)\\ <wrap em>Note that we have a trailing ''/'' after the source directory, and NO ''/'' after the destination directory</wrap>\\ ''rsync %%--%%dry-run -avW -C /mnt/h/test/ /mnt/i/test''
      * Note: using ''-C'' makes sure  that files and directories considered as temporary will not be copied.\\ Do NOT use the ''-C'' option if you really want to copy all the files!
    * Same as above, without the //verbose// mode. Probably nothing will be displayed on the screen\\ ''rsync %%--%%dry-run -aW -C /mnt/h/test/ /mnt/i/test''
    * Actually **copy** the files, without displaying anything\\ ''rsync -aW -C /mnt/h/test/ /mnt/i/test''
    * Actually **mirror** the content of the //source// directory.\\ **Warning! Warning!** the ''%%--%%delete'' option will make sure that files present in the destination directory, but not in the source directory will be deleted! Be careful, make some tests and use the ''%%--%%dry-run'' option before using this\\ ''rsync -aW -C %%--%%delete /mnt/h/test/ /mnt/i/test''
===== Using ssh keys =====

==== What are ssh keys and why use them? ====

//ssh keys// are a combination of two specific (and unique) **text files**, **the //private// key** file and **the //public// key** file, linked by a special kind of password called **the passphrase**, that can be used instead of a standard password to connect securely from one server to another server

ssh keys have to be configured properly (a few easy steps), and are **very convenient** because:

  * Contrary to passwords, **they usually don't expire!**\\ You don't have to change ssh keys (except in some extra secure computing centers like TGCC) and you can keep them for years

  * **They don't depend on the accounts and the passwords of the servers where you use them**
    * You can (and should!) use the same set of ssh keys on several servers: you can then use the **same** passphrase to access all these servers, rather than having to memorize different passwords\\ e.g. if you have your //private// key on ''account_A'' of ''server_A'' and install the matching //public// key on ''account_B'' of ''server_B'', etc... you can then use ''ssh'' on ''account_A@server_A'' to access ''account_B@server_B'', ''account_C@server_C'', ... with the **same** passphrase !
    * **You can give your public key** to somebody and then access their account using your own passphrase (no need to know the password of the other person)

  * The [[https://mesocentre.ipsl.fr/|IPSL Mésocentre ESPRI]] servers can **only** be accessed with a public key and passphrase (the password is not used)

  * By default, ''ssh'' will ask you to type your passphrase each time you connect to a server, but **you can [[other:ssh#using_an_ssh_agent|use an ssh agent]] to securely store your passphrase for you**\\ Once you have typed your passphrase in the //ssh agent//, you can connect to all the servers that have your public key without having to type your passphrase!
    * ''scp'' (and [[other:win10apps#winscp|WinSCP]] on Windows) and the tools using ''ssh'' on your local computer will not ask your passphrase, if they find the passphrase in a running //ssh agent// on the local computer
      * if you use the ''-A'' option ([[other:ssh#most_common_options|agent forwarding]]), the remote server will also //know// (securely) your passphrase, and you will not have to type the passphrase when using ''ssh'', ''scp'' and tools running //over ssh// on the remote server(s)
    * the local //ssh agent// is terminated when you log out of your local computer (or reboot the computer)
==== Generating ssh keys ====

=== Some common sense advice ===

  * **Generate only one pair of private/public keys and use the same pair of keys everywhere!**\\ Put differently, do not generate a different pair of key on each computer/server you use (even if you always use the same passphrase)!

  * <wrap em>Do not use an empty passphrase!</wrap>\\ If you do that, somebody gaining access to your private key will be able to access all the accounts where you have installed your public key... You obviously do not want that, right?

  * **Keep a backup of your your keys outside of the computer where they were generated**
    * Useful if you erase or overwrite the keys by mistake, or if you move to another lab and use a new computer/account, but still need to access the accounts where you have installed your public key...
    * If you have not used an empty passphrase, and have not saved the passphrase in the same directory as the keys, the keys can't be used (easily) by somebody else to gain access to your accounts 

  * **Do not forget your passphrase!**
    * Do not write your passphrase on a post-it taped to your computer
    * When you create your keys and type your passphrase, choose something that you will be able to easily remember during several years. It can even be a long (but easy to remember!) sentence!
      * Easy to remember passphrase example: "//I love working at LSCE!//"

=== Generating keys in a terminal (Linux and Mac) ===

If you already have a pair of ssh keys, you probably don't want to generate a new pair, unless you have been asked to (e.g. because an old encryption type like //DSA// has been deprecated), or you have lost one of the keys, or forgotten your passphrase. If you generate a new pair of keys, you will have to replace the old keys that you were using on all your desktops/laptops, and all the remote servers

There are several ways to generate pairs of ssh keys with ''ssh-keygen''. The following one is the one recommended for opening an account on [[https://mesocentre.ipsl.fr/account-opening/|IPSL Mésocentre ESPRI]]. If you open an account on ''spirit'', but already have a public key, just **send your existing public key**!

  * Type ''ssh-keygen  -t ed25519''
    * Accept the default path and key name
    * <wrap em>Do not specify an empty passphrase!</wrap>
    * Note: ''ssh-keygen -t ed25519'' will also work on Windows! But then you will still have to [[other:putty_conf#converting_existing_ssh_keys_with_puttygen|convert the generated private key with PuTTYgen]]
  * This will generate two text //key// files in the [[other:ssh#configuration_files|ssh configuration directory]]:
    * The **//private// key**: ''id_ed25519''
      * Note: on a Linux computer, the private key has to be readable only by you, otherwise ''ssh'' will not work
      * <code> > cd ~/.ssh
 > ls -l id_ed25519
-rw------- 1 my_login my_group some_date id_ed25519
 > cat id_ed25519
-----BEGIN OPENSSH PRIVATE KEY-----
b3BlbnNzaC1rZXktdjEAAAAACmFlczI1Ni1jdHIAAAAGYmNyeXB0AAAAGAAAABC7W9+Eu7
[ lots of literally cryptic lines ]
cG7sHta/m1cOGM8ej7yD8ejCRMKGX1pEqGx/8=
-----END OPENSSH PRIVATE KEY-----</code>
    * The **//public// key**: ''id_ed25519**.pub**''
      * This is the //key// that **you can share**, or that you have to send when opening an account on [[https://mesocentre.ipsl.fr/account-opening/|IPSL Mésocentre ESPRI]].
        * Note that the ''my_login@my_machine'' string at the end of the line is just some information about who generated the keys, and where, and can be removed or replaced by something more informative
      * <code> > cat id_ed25519.pub
ssh-ed25519 AAAAC3NzaC1lZDI1NT [ lots of cryptic characters ] Frx8rRFKthpmqRdkXl my_login@my_machine</code>

=== Generating or importing keys with PuTTY (Windows) ===

Read [[other:putty_conf#converting_existing_ssh_keys_with_puttygen|Converting existing ssh keys with PuTTYgen]], or [[other:putty_conf#creating_ssh_keys_with_puttygen|Creating ssh keys with PuTTYgen]]

==== Installing ssh keys ====

<note tip>**Special case**:

  *  ''spirit[x]'' servers: if you need to use the [[other:ssh#ipsl_servers|IPSL spirit[x] servers]], you have to send your //public// key when you request your account, and the IT people will take care of putting your //public// key in the correct place when they create your account

</note>

The **required //ssh key// files have to be present in the ''.ssh'' [[other:ssh#configuration_files|directory where ssh stores its configuration files]]**, on the //source// **and** //target// computers. You do not need the same key files on the //source// **and** //target// computers, but it is easier to have all the key files in all the ''.ssh'' directories. This will also act as a backup of the key files in different locations.


We assume below that you have copied the required key files in the ''.ssh'' directory of both //source// and //target// computers. We also assume that we are dealing with ''ed25519'' keys, so the //key// files will are named: ''id_ed25519'' (and ''id_ed25519**.ppk**'' on a Windows computer, if you use [[other:putty_conf#using_ssh_keys_with_putty_pageant|PuTTY/Pageant]]), and ''id_ed25519**.pub**''.


  * on the **//source// computer**\\ (your local desktop/laptop, or a remote Linux server if you will use ''ssh''/''scp'' from this remote server to another remote server)\\ \\
    * you need **the //private// key**: e.g. ''id_ed25519''
      * remember that **the private key has to be readable only by the file owner (you!)** on a linux (or Mac) computer\\ <code>$ chmod 600 ~/.ssh/id_ed25519

$ ls -l ~/.ssh/id_ed25519
-rw------- [...] /some_path/your_login/.ssh/id_ed25519</code>


  * and the **//target// computer**\\ (a remote Linux server)\\ \\
    * you need **the //public// key**: e.g. ''id_ed25519.pub''
    * you need a copy of the //public// key in the ''authorized_keys'' file
      * **if the ''authorized_keys'' file does not exist yet**, just copy the //public// key file\\ <code>$ cd ~/.ssh

$ ls -l authorized_keys
ls: cannot access authorized_keys: No such file or directory

$ cp -p id_ed25519.pub authorized_keys</code>
      * **if there is already an ''authorized_keys'' file** (possibly with older public keys), just create a backup of the existing file, and **add the new public key at the end of the file**\\ <code>$ cd ~/.ssh

$ cat authorized_keys
ssh-dss AAAAB3NzaC1kc3MAAACBAM9w0bY604COfD5yLwlBLaSDSbi2eKfhPJBl/
[...]
OUZ8jrQrhDbq2P7GNTTaEEdy+JvtDvZSZLG4+DwhWSkxqPZ35yD8wfOi5WInpG3Cms some_login

$ mv authorized_keys authorized_keys.save

$ cat authorized_keys.save id_ed25519.pub > authorized_keys

$ cat authorized_keys
ssh-dss AAAAB3NzaC1kc3MAAACBAM9w0bY604COfD5yLwlBLaSDSbi2eKfhPJBl/
[...]
OUZ8jrQrhDbq2P7GNTTaEEdy+JvtDvZSZLG4+DwhWSkxqPZ35yD8wfOi5WInpG3Cms some_login
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIICD35IUxzgjlslHsrOZQ2ARZsXN1RuDcJ+ncyBKLwHr another_login
</code>
==== Using the keys ====


===== Using an ssh agent =====

An //ssh agent// running on your computer will securely store your passphrase and supply it to applications that use ''ssh'' on your computer to connect to remote Linux servers

  * start the //agent// when you open a new session on your computer
  * enter your //ssh passphrase//(s). An agent can store multiple passphrases associating multiple pairs of private and public ssh keys, but you can also use the same public key on different remote Linux servers
  * the //ssh agent// will store your passphrase until you exit your session, or restart your computer 

==== Linux ssh agent ====

FIXME

==== Windows ssh agent ====

  * On Windows, we recommend using [[other:putty_conf#using_the_private_key_in_pageant|Pageant/PuTTY]] as an //ssh agent//, because:
    * [[other:putty_conf#launching_putty_pageant|Pageant/PuTTY]] also offers a very easy and convenient way to define profiles to connect to your favorite servers
    * Some programs that use ''ssh'' to transfer files will automatically use the keys stored in ''Pageant'': [[other:win10apps#winscp|WinSCP]], [[other:emacs_doc|emacs]], ...

  * It is also possible (but less convenient) to use the Windows built-in ''ssh-agent'' and ''ssh'' commands!
    * Note that the //agent service// is not activated by default and you will get the following error when you try to use ''ssh-add''
      * <code>C: > ssh-add
Error connecting to agent: No such file or directory</code>
    * It is necessary to first **activate the agent Windows //service//** (in an **//elevated// PowerShell**, i.e with //Administrator// privileges) as explained in the [[https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_keymanagement#user-key-generation|User key generation]] section
      * <code>C: > Get-Service ssh-agent
Status   Name               DisplayName
------   ----               -----------
Stopped  ssh-agent          OpenSSH Authentication Agent

C: > Get-Service ssh-agent | Set-Service -StartupType Automatic

C: > Start-Service ssh-agent

C: > Get-Service ssh-agent
Status   Name               DisplayName
------   ----               -----------
Running  ssh-agent          OpenSSH Authentication Agent

C: > ssh-add
Enter passphrase for C:\Users\your_login/.ssh/id_dsa: XXXX_Type_Your_Passphrase_Here_XXXX
Identity added: C:\Users\your_login/.ssh/id_dsa
Identity added: C:\Users\your_login/.ssh/id_ed25519

C: > ssh-add -l
1024 SHA256:/vC3Ma6s9Wj[Some_Summary_Info_About_The_Key]c1Q4 (DSA)
256 SHA256:8BGKU+zBnJXH[Some_Summary_Info_About_The_Key]2Al8 jypeter@obelix5 (ED25519)</code>

==== Mac ssh agent ====

<WRAP center round tip 60%>
Nothing to configure!
</WRAP>

The ''ssh-agent'' process will be automatically started, if a user runs ''ssh'' or ''ssh-add''!

Check the [[https://support.apple.com/guide/terminal/script-management-with-launchd-apdc6c1077b-5d5d-4d35-9c19-60f2397b2369/mac|launchd documentation]] if you need more details
<code>$ launchctl list | grep ssh
      7240	0	com.openssh.ssh-agent</code>
      
It seems that, once used, the passphrase will be automatically stored in the [[https://support.apple.com/guide/keychain-access/what-is-keychain-access-kyca1083/mac|Keychain]] for future sessions
===== More... =====

  * If you want to **know more** (options, etc...), check the //man(ual) page// on Linux: ''man ssh''
  * Editing **remote text files** with emacs (and automatic ''scp''): check the ''emacs'' section of the [[other:newppl:starting#text_editors|Text editors]]
  * Digging **ssh tunnels** when using //ipython notebooks//

/* standard page footer */

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