!!! 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 NOTE: SRV_PROXY_TRANSPARENT is an obsolete setting and should not be used. 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. NOTE: DISPATCHER is no longer an available method of connecting. Please consider to upgrade your client. 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: SERVICE -- use the new dispatcher [default] WWW -- use the old dispatcher via persistent http FIREWALL -- use the old dispatcher through a firewall DISPATCHER -- very old dispatcher interface, phased out and no longer available SRV_ENGINE_HOST -- the name of the new dispatcher. Value: www.ncbi.nlm.nih.gov -- default 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/dispd.cgi -- default /Service/nph-dispd.cgi -- this is the default if old dispatcher is used 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 whether it is connecting to the firewall. Values: no -- default yes -- transparent NOTE: This setting is obsolete and should not be used anymore. ============================== 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 RETIRED - DO NOT USE! firewall port 5859 ------> 130.14.22.2 RETIRED - DO NOT USE! firewall port 5840 ------> 130.14.22.8 RETIRED - DO NOT USE! firewall port 5845 ------> 130.14.22.12 (can be accessed only from NCBI!) firewall port 5810 ------> 130.14.22.30 RETIRED - DO NOT USE! 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.31 5812 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.31 5812 | Trying 130.14.22.31... | Connected to 130.14.22.31. | Escape character is '^]'. | test | NCBI Firewall Daemon: Invalid ticket. Connection closed. | Connection closed by foreign host. Configuring Old Clients and Firewalls ===================================== OLD DISPATCHER HAS BEEN COMPLETELY RETIRED AND IS NO LONGER AVAILABLE THUS MAKING THIS SECTION IS TOTALLY OBSOLETE 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