!!!  For the latest version of this document see in:
!!!		  http://www.ncbi.nlm.nih.gov/cpp/network/firewall.html


Dear Colleague,

Problems connecting NCBI databases may be due to the 
presence of a firewall at your site, especially if you 
receive error messages about the inability to connect to a 
dispatcher.  This document details how to connect to the 
NCBI dispatcher through a firewall.


===============================================
Connecting to Network Entrez through a firewall
===============================================
[Instructions were last modified in June, 1999]

NCBI databases are accessed via the hyper text transfer 
protocol (http).  Because of this, most users who are not 
behind a security firewall or use a web browser do not have 
to do anything special to access our databases and do not 
have to read this document.  However, users who are behind 
firewalls may have to configure their clients (i.e. 
programs) and ask their network administrations to 
reconfigure the firewalls to use NCBI services.  This 
configuration procedure is complicated by the fact that 
NCBI has recently switched to use http instead of an older, 
specialized protocol in order to make NCBI services more 
reliable (although we will not shut down the older protocol 
until it is no longer of use).  This document will list the 
procedures necessary to configure your clients and 
firewalls to use NCBI database services. If you do not know 
if you are behind a security firewall or proxy, please 
consult your network administrator. 


====================
Configuring clients:
====================

There are 3 types of clients: older clients (those built 
using NCBI code released before September, 1998), 
intermediate clients (those released between September, 
1998, and November, 1998) and new clients (released after 
December 1998). 


Configuring older clients
-------------------------
These include versions of Cn3D earlier than 2.0, Oxford 
Molecular's MacVector 6.5 and earlier, versions of Sequin 
earlier than 2.70, and Nentrez versions earlier than 6.4.
We recommend updating Cn3D, Sequin, and Nentrez to newer 
versions, although all of these programs can be used 
with the old network configuration, which is detailed at 
the end of the document.  MacVector should be used with the 
old network configuration, please see the old network configuration 
at the end of the document or contact your manufacturer for 
instructions.


Configuring intermediate clients
--------------------------------
These include Cn3D 2.0x, Sequin 2.70, and Nentrez 6.4.

To turn on firewall operation, you must edit your NCBI 
configuration file.  On Windows, this is found in your 
windows or winnt directory with the name Ncbi.ini.  On the 
Macintosh, this is found in the System:Preferences 
directory with the name ncbi.cnf.  On Unix, it is the file 
.ncbirc in your home directory.  

The next step depends on what kind of firewall you use --- 
if you don't know, ask your network administrator.  If you 
have a transparent firewall, that is, a firewall that your 
program can connect through without having to know the 
network address of the firewall, use the first set of 
directions, otherwise, use the second set of directions.


1. Intermediate clients with a transparent firewall
------------------------------------------------
After opening the NCBI configuration file in a text editor, 
find the section entitled [ENTREZ_NET].  In this section 
add or edit an entry to read SRV_CONN_MODE=FIREWALL.  If 
you use an http proxy, set SRV_PROXY_HOST to the name of 
your proxy server and SRV_PROXY_PORT to the port used by 
your http proxy.  Set SRV_PROXY_TRANSPARENT=yes to indicate 
that your firewall is transparent.  For more information on 
these settings, contact your network administrator.  A 
sample configuration is then:

[ENTREZ_NET]
SRV_CONN_MODE=FIREWALL
SRV_PROXY_HOST=your.proxy.com
SRV_PROXY_PORT=80
SRV_PROXY_TRANSPARENT=yes

2. Intermediate clients with a non-transparent firewall
-------------------------------------------------------

Edit your NCBI configuration file to include the line 
SRV_CONN_MODE=DISPATCHER underneath the [ENTREZ_NET] entry:

[ENTREZ_NET]
SRV_CONN_MODE=DISPATCHER

This uses the old connection protocol.  See the 
configuration information at the end of the document.


Configuring newer clients
-------------------------

All of these clients (except blastcl3) include easy-to-use 
configuration dialogs that allow you to set firewall operation 
from the programs themselves.  These clients also deal with correctly 
with non-transparent firewalls.  Blastcl3 can be configured by installing
Sequin or Entrez, or by editing the configuration file directly.

If you wish to edit your configuration file directly, use 
the same instructions for intermediate clients behind 
transparent firewalls, except edit the [NET_SERV] section 
instead of the [ENTREZ_NET] section.  If your firewall is 
not transparent, set SRV_PROXY_TRANSPARENT=no, otherwise 
set it to yes.



Detailed description of client configuration settings:
======================================================

When you first access NCBI databases, the connection is
received by a server called a dispatcher.  The purpose of
the dispatcher is to connect your software to the
appropriate database server.  For example, if you are
looking for article abstracts using Sequin, the dispatcher
will connect Sequin to the PubMed server.  This dispatcher
has been recently rewritten to use http instead of a custom
communications protocol.  The following settings affect the 
use of the new dispatcher.


Configuration Parameters
------------------------

SRV_CONN_MODE -- specifies whether to use the old or new
dispatcher and if this is a firewall connection.

Values:
DISPATCHER -- use the old dispatcher
WWW        -- use the new dispatcher via persistent http
FIREWALL   -- use the new dispatcher through a firewall


SRV_ENGINE_HOST -- the name of the new dispatcher.

Value:
www.ncbi.nlm.nih.gov  -- default (new dispatcher)


SRV_ENGINE_PORT -- which port on the new dispatcher to use.

Value:
80 -- default


SRV_ENGINE_URL -- the url used to access the new 
dispatcher, minus the server name.

Value:
/Service/nph-dispd.cgi -- default


SRV_PROXY_HOST -- If you are using the new http dispatcher
through a proxy or firewall, set this to the name of the
proxy or firewall.  This will only work with a CERN-type
proxy.  If you do not know if you have a CERN-type proxy or
firewall, please contact your network administrator.

Value:
not set -- default


SRV_PROXY_PORT:  The port to use on the proxy or firewall

Value:
80 -- default


SRV_PROXY_TRANSPARENT: Indicates the firewall is 
transparent, i.e. client does not know it is connecting to 
the firewall.

Values:
no -- default
yes -- transparent 



==============================
Network Firewall Configuration
==============================

This section is intended for network administrators.  Using 
NCBI services from behind a security firewall requires 
opening ports in your firewall.

The ports you need to open depend upon the clients used 
behind the firewall and how they are configured.  If you 
have only older clients (as defined in the sections above), 
you can either upgrade your clients or use the old firewall 
directions at the end of the document.  If you have a 
mixture of old, intermediate and new clients, you will have 
to open up the ports described in this section AND the 
ports listed in the old firewall directions at the end of 
the document.  Be aware that Oxford Molecular's MacVector 
versions 6.5 and earlier use the old form of firewall 
connection.  If all clients are configured to use 
SRV_CONN_MODE=FIREWALL and you:

1. have only intermediate and new clients and your firewall 
is transparent, or

2. have only new clients and your firewall is either 
transparent or not transparent,

then the ports to open are:

Ports to open
-------------
firewall port 5853      ------> 130.14.22.1
firewall port 5859      ------> 130.14.22.2
firewall port 5840      ------> 130.14.22.8
firewall port 5845      ------> 130.14.22.12  (can be accessed only from NCBI!)
firewall port 5810      ------> 130.14.22.30
firewall port 5812      ------> 130.14.22.31
firewall port 5811      ------> 130.14.22.32

The firewall port number should be mapped to the same port 
number on the external host.


TROUBLESHOOTING:  You can test if these ports are accessible from
your host by just running, for example (see the "Ports to open" list
above):
  telnet 130.14.22.1 5853
and entering a line of arbitrary text in the telnet session.
If everything is fine, your TELNET session will look as follows:

| > telnet 130.14.22.1 5853
| Trying 130.14.22.1...
| Connected to 130.14.22.1.
| Escape character is '^]'.
| test
| NCBI Firewall Daemon:  Invalid ticket. Connection closed.
| Connection closed by foreign host.



Configuring Old Clients and Firewalls
=====================================


The default mode of the old NCBI network clients is that 
the NCBI server will need to contact the client.  This 
often causes problems for sites with firewalls. All clients 
are capable of reversing the direction of the client<-
>server connection, making it more palatable for many 
firewalls.  This is the first thing that should be tried if 
firewall problems exist.  If this does not work, then it is
recommended that the directions given in the rest of this 
document be followed.

To reverse the direction, check the "Outgoing Connections 
Only" checkbox on the second  screen of the netentcf 
configuration program.  You can see whether this 
functionality is in-use when running Network Entrez by 
selecting "About Entrez..."'s More button, and looking for 
the string "Using outgoing connection when communicating
with server".
     
The method used for connecting to Network Entrez through a 
firewall depends upon whether your firewall can allow you 
to use our IP addresses and have them be properly detected 
and mapped on the firewall, or whether you must explicitly 
connect to a port on the firewall which is then mapped
to the real IP address.  If the former (much simpler and 
more reliable), then you should omit the steps related to 
"PROXY_SERV_OVERRIDE" below.  

Some firewalls only allow a single host (the firewall 
machine) to be connected-to en route to the Internet.  In 
this scenario, it is possible but somewhat challenging) to 
map (TCP) ports in a manner which allows Network
Entrez to operate properly.  It is necessary to map all of 
the ports given below, as the NCBI server decides which 
port will be used.


Note that these mappings changed in March, 1998.

The basics of these mappings are:
    firewall port 5557      ------> 130.14.25.211
    firewall port 5848      ------> 130.14.22.1
    firewall port 5849      ------> 130.14.22.1
    firewall port 5850      ------> 130.14.22.1
    firewall port 5851      ------> 130.14.22.1
    firewall port 5852      ------> 130.14.22.1
    firewall port 5853      ------> 130.14.22.1
    firewall port 5854      ------> 130.14.22.2
    firewall port 5855      ------> 130.14.22.2
    firewall port 5856      ------> 130.14.22.2
    firewall port 5857      ------> 130.14.22.2
    firewall port 5858      ------> 130.14.22.2
    firewall port 5859      ------> 130.14.22.2

At present, in all cases the firewall port number should be 
mapped to the same port number on the external host.

After the firewall has been properly setup, it is possible 
to configure the Network Entrez clients using a combination 
of the netentcf program and manual-editing of the NCBI 
configuration file (named ncbi.ini, .ncbirc, or ncbi.cnf, 
depending upon your platform).

In netentcf, follow the instructions for each screen:
   (a) On the second screen ("Entrez for Internet setup") 
check the "Outgoing connections only" checkbox and select 
the "Give up" radio button setting.
   (b) On the third screen ("Dispatcher Internet Address") 
enter your firewall's IP address as the Dispatcher FQDN or 
Address, and check the "Test connection during 
configuration" checkbox.
   (c) On the fourth screen ("Entrez Service Selection"), 
_de-check_ the "Test connection during configuration" 
checkbox.

Manually edit the NCBI configuration file's [NET_SERV] 
section.  Be sure that the "DISPATCHER" address is set to 
your firewall's IP address (netentcf may have modified this 
to be the real Dispatcher's address), and add a new line to 
set the PROXY_SERV_OVERRIDE field to also be set to
your firewall's IP address.  The resulting [NET_SERV] 
section should look something like this (the order of the 
lines within the section is not significant), where 1.2.3.4 
should be replaced by the IP address of your firewall 
machine.

[NET_SERV]
PROXY_SERV_OVERRIDE=1.2.3.4
DISPATCHER=1.2.3.4
DISP_ALT_1=dispatch1.nlm.nih.gov
DISPSERIALNO=6
DISP_ALT_2=130.14.25.47
DISP_ALT_3=dispatch2.nlm.nih.gov
DISP_ALT_4=dispatch3.nlm.nih.gov
DISP_ALT_5=130.14.25.1
DISP_RECONN_ACTION=QUIT
DIRECT_SVC_CON=TRUE

If this file is setup correctly and so is the firewall, 
then in principle "Nentrez" will now operate correctly when 
you run it.


In principle it is possible for NCBI to setup a similar 
mechanism to contact the backup Entrez server and other 
services like BLAST.  It will be difficult, however, to 
support backup Dispatchers via this mechanism.

Here are the port numbers for the BLAST server; they are 
independent of the Entrez port numbers above, but require 
the same Dispatcher configuration.
    firewall port 5400      ------> 130.14.25.175
    firewall port 5401      ------> 130.14.25.175
    firewall port 5402      ------> 130.14.25.175
    firewall port 5403      ------> 130.14.25.175
    firewall port 5404      ------> 130.14.25.175
    firewall port 5405      ------> 130.14.25.175
    firewall port 5406      ------> 130.14.25.175
    firewall port 5407      ------> 130.14.25.175
    firewall port 5408      ------> 130.14.25.175
    firewall port 5409      ------> 130.14.25.175
    firewall port 5410      ------> 130.14.25.28
    firewall port 5411      ------> 130.14.25.28
    firewall port 5412      ------> 130.14.25.28
    firewall port 5413      ------> 130.14.25.28
    firewall port 5414      ------> 130.14.25.28
    firewall port 5415      ------> 130.14.25.28
    firewall port 5416      ------> 130.14.25.28
    firewall port 5417      ------> 130.14.25.28
    firewall port 5418      ------> 130.14.25.28
    firewall port 5419      ------> 130.14.25.28
    firewall port 5420      ------> 130.14.25.59
    firewall port 5421      ------> 130.14.25.59
    firewall port 5422      ------> 130.14.25.59
    firewall port 5423      ------> 130.14.25.59
    firewall port 5424      ------> 130.14.25.59
    firewall port 5425      ------> 130.14.25.59
    firewall port 5426      ------> 130.14.25.59
    firewall port 5427      ------> 130.14.25.59
    firewall port 5428      ------> 130.14.25.59
    firewall port 5429      ------> 130.14.25.59

