= SSH Setup on Monsoon =	

In order to submit UM jobs to Monsoon from the UMUI on PUMA you need to have set up ssh-agent and ssh-forwarding correctly.

This page attempts to describe what you need to do to setup ssh-agent. Since instructions will differ depending on your current setup; whether you already have an ssh-agent running on PUMA and if so, where it is initiated from, be that PUMA or forwarded from a localhost, we cannot cover all scenarios and offer this information as advice only.

 
== Determining if you already have an ssh-agent running on PUMA ==

First we need to determine if you already have an ssh-agent running on PUMA. Login to PUMA and run the command `ssh-add -l`

=== Scenario A: ===
{{{
puma$ ssh-add -l
1024 7e:c9:c1:a6:f5:71:e3:bd:d9:84:23:4c:e4:fc:f7:ea /home/ros/.ssh/id_dsa (DSA)
}}}
If the result is similar to the above then you already have an ssh-agent running on PUMA. Please go to the setup instructions entitled [wiki:MonsoonSshAgent#Settingupyourpublickey "Setting up your public key PUMA"].

=== Scenario B: ===
{{{
puma$ ssh-add -l
Could not open a connection to your authentication agent.
}}}
Output similar to the above indicates that you do not have an ssh-agent running on PUMA. Please follow the instructions entitled [wiki:MonsoonSshAgent#Settingupssh-agentonPUMA "Setting up ssh-agent on PUMA"].

== Setting up ssh-agent on PUMA ==

[[box(Note: The following instructions assume that you haven't already got ssh-agent setup on PUMA., type=note)]]

 1. Generate the authentication key on PUMA:
{{{
    puma$ ssh-keygen -f ~/.ssh/id_rsa -C "‹userid›@puma.nerc.ac.uk"
    Generating public/private rsa key pair.
    Enter passphrase(empty for no passphrase): [TYPE_YOUR_PASSPHRASE]
    Enter same passphrase again: [TYPE_YOUR_PASSPHRASE]
    Your identification has been saved in ~/.ssh/id_rsa.
    Your public key has been saved in ~/.ssh/id_rsa.pub.
    The key fingerprint is:
    md5 1024 [String of characters] ‹userid›@puma.nerc.ac.uk
}}}
    [TYPE-YOUR-PASSPHRASE] is a fairly complicated and unguessable passphrase. You can use spaces in the pass phrase if it helps you to remember it more readily. It is recommended that you don't use your password just in case this is hacked.

 2. Add the public key to the ~/.ssh/authorized_keys file on PUMA:
{{{
    puma$ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
}}}

 3. Run ssh-agent on PUMA:

 Make the ssh-agent automatically start-up when your session runs.

 Copy [htdocs:downloads/ssh-setup my setup script] to `$HOME/.ssh/setup`, and ensure it has execute permission:
{{{
    puma$ chmod u+x $HOME/.ssh/setup
}}}
 Call this script from your `.kshrc` (if you don't have a `.kshrc` file call it from your `.profile`) by adding the following line:
{{{
    . $HOME/.ssh/setup
}}}

 4. Run the following command and type your passphrase (you may need to do this every time a new ssh-agent is started - ie. every time you re-start your local session):
{{{
    puma$ ssh-add
    Enter passphrase for ~/.ssh/id_rsa (‹userid›@puma.nerc.ac.uk): [Type Passphrase]
}}}

 5. Now complete the section entitled [wiki:MonsoonSshAgent#Settingupssh-forwarding "Setting up ssh-forwarding"]


== Setting up your public key ==

The following instructions assume that you already have an ssh-agent running on PUMA

The purpose of this section is to set up your public keys so that you don't need to supply your PUMA password during the job submission process. You need to copy your public key to the `~/.ssh/authorized_keys` file on PUMA, but which key this is, depends on how you setup the ssh-agent.

Is the agent running on PUMA or has it been forwarded from a localhost (ie. the machine you logged into PUMA from)?

The easiest way to determine this is to search the processes you have running on PUMA, by issuing the command:
{{{
ps -flu <username> | grep ssh-agent
}}}

If the search is successful, then you are running the agent on PUMA and you need to run the following command to add your PUMA public key to the `~/.ssh/authorized_keys` file on PUMA:
{{{
puma$ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
}}}

Otherwise the ssh-agent is being forwarded from another machine. You now need to determine which machine that is, most likely to be the one you logged into PUMA from and copy the public key from that machine to the `~/.ssh/authorized_keys` file on PUMA. This can be achieved in a secure manner by running the following command:
{{{
puma$ cat ~/.ssh/id_rsa.pub | ssh ‹userid›@puma.nerc.ac.uk 'mkdir -p .ssh ; cat - >> ~/.ssh/authorized_keys'
}}}

{{{#!box type=note
Note: Depending on the type of public key you have previously generated, you may find it is in a file called `~/.ssh/id_dsa.pub` rather than `id_rsa.pub`
}}}

Now complete the section entitled [wiki:MonsoonSshAgent#Settingupssh-forwarding "Setting up ssh-forwarding"].

== Setting up ssh-forwarding ==

'''On PUMA:'''

If you already have the file `$HOME/.ssh/config` add the following lines to it, otherwise first create the file `$HOME/.ssh/config` and add the following lines.
{{{
Host monsoon lander.monsoon-metoffice.co.uk
ForwardAgent yes

Host *
ForwardAgent no
ForwardX11 yes
ForwardX11Trusted yes
}}}
 
'''On lander.monsoon-metoffice.co.uk:'''
('''Note:''' This is on the lander '''NOT''' the XCS)

Create, or append to, the file `$HOME/.ssh/config` the following lines.
{{{
Host *.*
ForwardAgent no

Host *
ForwardAgent yes
ForwardX11 yes
}}}

If all has worked correctly, you should only be required to enter your Monsoon passcode once for each job you submit.