Table of Contents
Understanding and using ssh correctly
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
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 remoteremote_server
computer, and that you know your password
- Instead of a password, you can also 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 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
- 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 aWindows Powershell
, a Windows Terminal or the oldcmd
, but the most user-friendly way to usessh
is to use PuTTY
- On a Mac,
ssh
is directly available in the built-in Apple Terminal application
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 usessh ssh1.lsce.ipsl.fr
instead ofssh 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 theknown_hosts
file (details).
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).
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 Using an X server to display graphics section
-A
: enable agent forwarding. This is useful when you use 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 initialssh
). 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 startssh
should allow you, or the 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 available LSCE servers)
- If your computer is on the LSCE ethernet/wired network:
- Go to the server with the smallest load:
ssh -A -X my_LSCE_login@obelix
orssh -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 top, or terminate withkill
)
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 help-lsce, and request an access to the
ssh1
server - Connect through the
ssh1
gateway server, i.e you first usessh
to connect to thessh1
gateway, and then usessh
to go to anobelix
server
These twossh
commands can be 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 IPSL servers (only possible with ssh keys!):
- 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
orspiritx2
- Note: the
ciclad
server may still be accessible when you read this page, but its usage has been deprecated in favor of thespirit
servers
TGCC (super)computers
If you want to use the 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
)
IDRIS (super)computers
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 add PuTTY connection profiles on Windows
bash shell users
Define the following aliases in the ~/.bashrc
configuration file of your local Linux account
# 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'
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
(orssh -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 theDISPLAY
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:
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
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 weressh
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.
# Empty lines and lines starting with '#' are "comments" # More details => man ssh_config ServerAliveInterval=120 ServerAliveCountMax=90
- 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
andid_ed25519.pub
files
A recommended ssh client for Windows
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
) - Recommended: the iTerm2 application
- Improved Favorite Sessions settings
Solving common problems
- 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
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
, 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 WinSCP for copying files
scp [options] local_path_or_file(s) [my_login@]remote_server:remote_path
orscp [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:
$ 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
- if you need to use wildcards to specify the files you want to copy, you can use quotes around the path specification:
$ 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
- 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
WinSCP is a convenient and user-friendly scp client for Windows
A recommended graphical scp client for Mac
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
, theSRC
(Source) andDST
(Destination) directories will have the exact same content (files inDST
and not inSRC
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.
Warning! It is easy to lose files with rsync
if you use the wrong syntax or options!
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 - Having a trailing
/
or not behind a directory name makes a difference!
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):
Pull: rsync [OPTIONS] [USER@]HOST:SRC... DEST Push: rsync [OPTIONS] SRC... [USER@]HOST:DEST
-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
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 oftest/
to atest/
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)
Note that we have a trailing/
after the source directory, and NO/
after the destination directory
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 onaccount_A
ofserver_A
and install the matching public key onaccount_B
ofserver_B
, etc… you can then usessh
onaccount_A@server_A
to accessaccount_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 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 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 WinSCP on Windows) and the tools usingssh
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 (agent forwarding), the remote server will also know (securely) your passphrase, and you will not have to type the passphrase when usingssh
,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)!
- Do not use an empty passphrase!
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 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
- Do not specify an empty passphrase!
- Note:
ssh-keygen -t ed25519
will also work on Windows! But then you will still have to convert the generated private key with PuTTYgen
- This will generate two text key files in the 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 > 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-----
- 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 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
> cat id_ed25519.pub ssh-ed25519 AAAAC3NzaC1lZDI1NT [ lots of cryptic characters ] Frx8rRFKthpmqRdkXl my_login@my_machine
Generating or importing keys with PuTTY (Windows)
Installing ssh keys
spirit[x]
servers: if you need to use the 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
The required ssh key files have to be present in the .ssh
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 PuTTY/Pageant), and id_ed25519.pub
.
- on the source computer
(your local desktop/laptop, or a remote Linux server if you will usessh
/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
$ chmod 600 ~/.ssh/id_ed25519 $ ls -l ~/.ssh/id_ed25519 -rw------- [...] /some_path/your_login/.ssh/id_ed25519
- 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
$ cd ~/.ssh $ ls -l authorized_keys ls: cannot access authorized_keys: No such file or directory $ cp -p id_ed25519.pub authorized_keys
- 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
$ 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
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
Windows ssh agent
- On Windows, we recommend using Pageant/PuTTY as an ssh agent, because:
- Pageant/PuTTY also offers a very easy and convenient way to define profiles to connect to your favorite servers
- It is also possible (but less convenient) to use the Windows built-in
ssh-agent
andssh
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
C: > ssh-add Error connecting to agent: No such file or directory
- It is necessary to first activate the agent Windows service (in an elevated PowerShell, i.e with Administrator privileges) as explained in the User key generation section
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)
Mac ssh agent
Nothing to configure!
The ssh-agent
process will be automatically started, if a user runs ssh
or ssh-add
!
Check the launchd documentation if you need more details
$ launchctl list | grep ssh 7240 0 com.openssh.ssh-agent
It seems that, once used, the passphrase will be automatically stored in the 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 theemacs
section of the Text editors - Digging ssh tunnels when using ipython notebooks
[ PMIP3 Wiki Home ] - [ Help! ] - [ Wiki syntax ]