<CHAPTER ID="SSH-CHAPTER">
  <TITLE>Secure Shell (SSH) Plugin To &prog</TITLE>

  <SECT1 ID="SSH-OVERVIEW">
    <TITLE>Overview of the SSH Plugin</TITLE>
    <PARA>
This is a plug-in to &prog that enables you to view and transfer
files from a local machine (e.g. PC/MacOSX/UNIX) to another remote
file system (i.e. any other file system that you have ssh access to).
The main areas where this is useful are:
   </PARA>
   <ITEMIZEDLIST SPACING="compact">
   <LISTITEM>
   <PARA>
file management for both local and remote files. Files can be transferred
by dragging and droping between file systems. Multiple files can be
selected and transferred in this way.
   </PARA>
   </LISTITEM>

   <LISTITEM>
   <PARA>
launching Artemis and ACT with sequences and tab files from files
on the remote machines.
   </PARA>
   </LISTITEM>

   <LISTITEM>
   <PARA>
running BLAST and Fasta searches can be sent from the local machine that
is running &prog and run on the remote machine. To do this the software
(BLAST and Fasta) need to be set up on the remote side (see 
<XREF LINKEND="SSH-CONFIG-SSH-SEARCHES">).
   </PARA>
   </LISTITEM>
   </ITEMIZEDLIST>

   </SECT1>

   <SECT1 ID="SSH-LOGIN">
    <TITLE>Login In</TITLE>
    <PARA>
From the &prog launch window go to the 'File' menu and select
'Open SSH File Manager'. A file manager window will then open with a
local file manager at the top. Underneath this is a remote file manager
with a section to enter login details.

<MEDIAOBJECT>
<IMAGEOBJECT>
   <IMAGEDATA FORMAT="gif" FILEREF="fm_login.gif">
            </IMAGEOBJECT>
</MEDIAOBJECT>

   </PARA>

   <PARA>
If you can connect directly to the remote machine give the hostname, username
and password. Alternatively if you are using a SSH tunnel (see <XREF
LINKEND="SSH-TUNNEL-LOGIN">) then use localhost and the appropriate
port number.
   </PARA>

  </SECT1>

  <SECT1 ID="SSH-TUNNEL-LOGIN">
    <TITLE>Setting up a SSH tunnel</TITLE>
    <PARA>
The tunneling capability of SSH Secure Shell allows people to access
their email, intraweb pages and files securely even when working away
from the office. This can be used with &prog and this section provides
some examples of setting up tunnelling. It may be necessary to consult your
friendly system administrator about the details on how best to do this.
    </PARA>

    <PARA>
On <EMPHASIS>UNIX</EMPHASIS> the ssh configuration can be set in the file 
<ComputerOutput>~/.ssh/config</ComputerOutput>. This
contains the information to set up a tunnel that looks like this:
    </PARA>

    <PARA>
    <SCREEN>
Host *.sanger.ac.uk
   LocalForward 2222 machine.sanger.ac.uk:22
   User tjc
    </SCREEN>
    </PARA>

    <PARA>
Once this configuration file is in place you can login from a UNIX 
window to set up a tunnel.
    </PARA>

    <PARA>
On <EMPHASIS>Windows</EMPHASIS> you can use Putty, see <XREF LINKEND="PUTTY">.
    </PARA>

    <PARA>
When the tunnel has been established you can start artemis and enter
'localhost' into the Hostname field in the login window and the port
number (e.g. 2222 in the above example).
    </PARA>

<MEDIAOBJECT>
<IMAGEOBJECT>
   <IMAGEDATA FORMAT="gif" FILEREF="fm.gif">
            </IMAGEOBJECT>
</MEDIAOBJECT>

  <PARA>
The file manager can be used to drag and drop files between each file system.
If you right click on a selected file this will provide you with a pop-up menu (see below)
enabling you to delete, rename and open files.
    </PARA>

<MEDIAOBJECT>
<IMAGEOBJECT>
   <IMAGEDATA FORMAT="gif" FILEREF="fm_popup.gif">
            </IMAGEOBJECT>
</MEDIAOBJECT>

    <PARA>
Files on the remote file system can be double clicked on and opened
in Artemis (in the same way they can be opened from the local file
manager). Tab files can be read in by dragging them from the remote
file manager and dropping them into the Artemis window.
    </PARA>

    <PARA>
Note for ACT the sequence filename can be dragged from the file manager into
the file selection box (if the files are not found locally the are then
located on the server). The tab files in ACT can be dragged from the
file manager and dropped on the relevant sequence display.
    </PARA>

    <PARA>
When files are saved, if the entry orginated from the remote file system
then this is saved locally in the current working directory and to the 
remote file as well.
    </PARA>
  </SECT1>

  <SECT1 ID="PUTTY">
    <TITLE>Using Putty to Set Up A Tunnel</TITLE>
    <PARA>
On <EMPHASIS>Windows</EMPHASIS> you can use  
<ULINK
URL="http://www.chiark.greenend.org.uk/~sgtatham/putty/" TYPE="external">
Putty</ULINK> to set up a ssh tunnel. Below are settings that can be used 
in Putty to set up a SSH tunnel.
    </PARA>

<MEDIAOBJECT>
<IMAGEOBJECT>
   <IMAGEDATA FORMAT="gif" FILEREF="putty1.gif">
            </IMAGEOBJECT>
</MEDIAOBJECT>

    <PARA>
    </PARA>

<MEDIAOBJECT>
<IMAGEOBJECT>
   <IMAGEDATA FORMAT="gif" FILEREF="putty2.gif">
            </IMAGEOBJECT>
</MEDIAOBJECT>

    <PARA>
SSH 2 only is probably recommended here.
    </PARA>
<MEDIAOBJECT>
<IMAGEOBJECT>
   <IMAGEDATA FORMAT="gif" FILEREF="putty3.gif">
            </IMAGEOBJECT>
</MEDIAOBJECT>

    <PARA>
X11 forwarding is not necessary.
    </PARA>
<MEDIAOBJECT>
<IMAGEOBJECT>
   <IMAGEDATA FORMAT="gif" FILEREF="putty4.gif">
            </IMAGEOBJECT>
</MEDIAOBJECT>

    <PARA>
Set the source port to 2222 and set the destination to
hostname:port (e.g. pcs2.internal.sanger.ac.uk:22).
    </PARA>
<MEDIAOBJECT>
<IMAGEOBJECT>
   <IMAGEDATA FORMAT="gif" FILEREF="putty5.gif">
            </IMAGEOBJECT>
</MEDIAOBJECT>

    <PARA>
Click 'Add' to add this to the list of forwarded ports.
    </PARA>

<MEDIAOBJECT>
<IMAGEOBJECT>
   <IMAGEDATA FORMAT="gif" FILEREF="putty6.gif">
            </IMAGEOBJECT>
</MEDIAOBJECT>

    <PARA>
Run Artemis and select the 'SSH File Manager' from the 'File'
menu. At the bottom fill in login details and click on the
'Connect' button.
Loging in may take a minute (depending on the connection).
    </PARA>

<MEDIAOBJECT>
<IMAGEOBJECT>
   <IMAGEDATA FORMAT="gif" FILEREF="putty7.gif">
            </IMAGEOBJECT>
</MEDIAOBJECT>

  </SECT1>

  <SECT1 ID="SSH-RUNNING-DB-SEARCHES">
    <TITLE>Using the SSH connection to run Fasta and BLAST</TITLE>
    <PARA>
Using the SSH connection you can send Fasta and BLAST searches to be run 
on the remote machine. If you have not already be prompted to login
(i.e. when opening up the SSH file manager), you will then be asked
for your login details. The sequence files that are to be searched against the
database are then sent to the remote machine.
Once the search has finished the results are transferred back afterwards.
If &prog detects that you have opened up an entry from the remote file system
the analysis will be run in the directory you open the entry from. The results
in this case are stored on both the local and remote machines.
    </PARA>

    <PARA>
To keep Fasta and BLAST searches on your local machine and the remote file system
<EMPHASIS>in-sync</EMPHASIS>:
    </PARA>

   <ITEMIZEDLIST SPACING="compact">
   <LISTITEM>
   <PARA>
copy any previously run fasta and blast directories from the remote machine to your
local file system. This can be done by making a tar ball of the directory:
e.g. creating a tar file of a 'fasta' directory
   </PARA>
   <PARA>
<SCREEN>
tar cvf tar_ball_name.tar fasta
</SCREEN>
   </PARA>
   </LISTITEM>
   <LISTITEM>
   <PARA>
Then transfer this file to the local project directory and extract with:
   </PARA>
   <PARA>
<SCREEN>
tar xvf tar_ball_name.tar
</SCREEN>
   </PARA>
   </LISTITEM>
   <LISTITEM>
   <PARA>
when launching Artemis, make sure you first change directory to the directory above
the 'fasta' directory that has been unpacked.
   </PARA>
   </LISTITEM>
   <LISTITEM>
   <PARA>
open the files from the remote file system in the file manager. It then knows where 
to save it back to.
   </PARA>
   </LISTITEM>
   </ITEMIZEDLIST>
  </SECT1>

  <SECT1 ID="SSH-CONFIG-SSH-SEARCHES">
    <TITLE>Configuring Searches to be run via SSH</TITLE>
    <PARA>
This would most likely be done by a systems administrator. The databases and
fasta and BLAST software need to be set up on the remote machine. Once this is
done the commands that are sent from the Artemis/ACT client to the remote
machine are controlled by a 'j2ssh.properties' file, see below for example of
this file. This needs to be put in the CLASSPATH for Artemis/ACT or the one in
the distribution (lib/j2ssh/j2ssh.properties) modified.
   </PARA>

    <PARA>
The j2ssh.properties file also hold default information. For example default
parameters can be set for the login prompt, the working directory (for searches
when sequences are opened on the local side) and any extra directories (other
than the users home directory) to display in the file manager.
   </PARA>

   <PARA>
   <SCREEN>
#
#
# Configuration file for using SSH file management and
# database searches. 
#
#
# default login options
port=2222
host=localhost
#
#
# Generic default options
#
blastp=blastall -p blastp
blastx=blastall -p blastx
tblastx=blastall -p tblastx
blastn=blastall -p blastn
fasta=fasta33_t -B -S -q -b 100 -H -l /data/fasta/pubseqgbs
fastx=fastx33_t -B -S -q -b 40 -H -l /data/fasta/pubseqgbs
#
#
# default working directory
wdir=/scratch
#
#
# aliases used for fasta
%uniprot=%U
%uniprot_archaea=%A
%uniprot_bacteria=%B
%uniprot_eukaryota=%E
%uniprot_viruses=%V
%uniprot_rest=%R
%malaria=%M
%kineto_aa=%K
default_db=%uniprot_bacteria
#
#
# remote directories to use as roots in the file manager
remotedir.PD=/nfs/pathdata
remotedir.YP=/nfs/disk222/yeastpub
# local directories to use as roots in the file manager
localdir.PD=/nfs/pathdata
localdir.YP=/nfs/disk222/yeastpub
   </SCREEN>
   </PARA>

  </SECT1>

</CHAPTER>