[ Last Modified June 14, 1999] [ ALSO SEE THE README_2 FILE IN THIS DIRECTORY ] INTRODUCTION The Network Entrez client program described in this document is currently available for general release. Entrez is the first network service to be supported by the NCBI and the first which utilizes a general "service discovery and request" facility called Dispatcher. General inquiries about the availability of NCBI Network Services may be sent to: net-info@ncbi.nlm.nih.gov. Technical inquiries may be sent to the same address. Users are also encouraged to subscribe to the "NCBI News". Free subscriptions to "NCBI News" can be obtained by sending one's name and postal mailing address to: info@ncbi.nlm.nih.gov. For the support of Network Entrez, the NCBI asks that a local administrator at each institution or department be designated to install the software and assist users. The administrator is expected to be the first point of contact for user support. NCBI staff will not be able to provide extensive end-user support but will be available to assist local administrators. However, if there are questions about configuration and operation of the software, they may be sent to the address net-info@ncbi.nlm.nih.gov The Network Entrez application provides functionality similar to the Entrez application which is distributed on the NCBI Entrez CD-ROMs. No CD-ROM drive is required to use Network Entrez. What is required is a direct Internet connection to your computer. Electronic mail access to the Internet, e.g. via BITNET, is insufficient. Check with your system administrator if you are uncertain as to whether you have direct Internet connectivity. To use Network Entrez, your computer must access the Internet using one of the following supported mechanisms: * UNIX - Any Berkeley-style socket implementation which supports TCP/IP. This includes most modern versions of UNIX. * Macintosh - System 7.x with MacTCP version 1.1 or 1.1.1. Use of a SLIP module is also feasible in conjunction with MacTCP if you have a high-speed modem. MacTCP 1.1.1 is required by System 7.1. MacTCP is available through the Apple Programmers and Developers Association (APDA), 1-800-282-APDA, and is included in some commercial software packages, e.g. VersaTerm. * PC - Microsoft Windows in conjunction with WinSock 1.1 compliant TCP/IP packages. The following WinSock 1.1 compliant stacks have been tested with Network Entrez. If you test it with another WinSock 1.1 package, or have experiences which contradict what is written below, please send a description of your results to net-info@ncbi.nlm.nih.gov. - PC-NFS 5.0 (SEE NOTE) - NetManage 3.10 - Lanera 2.2 - Wollongong Pathway Runtime 1.2.0.1 (SEE NOTE) - PC/TCP 2.11 (SEE NOTE) - Microsoft TCP/IP for Windows for Workgroups (pre-release) - Trumpet WinSock (Alpha version #15 or higher) - Novell LAN WorkPlace for DOS v4.1 (plus WinSock Beta-test) - Beame & Whiteside 3.0c - Frontiertech's SuperTCP version 4.0 - TwinSock 1.2 (for dial-up users with Internet access from a UNIX host) NOTE: PC-NFS 5.0 operates better if you obtain the latest wshelper.exe. PC/TCP 2.11 and Pathway 1.2.0.1 will only operate if you obtain the latest winsock.dll. Contact the vendor to learn how to obtain these updates. [ Old executables for PC-NFS 4.0 and NetManage Chameleon NFS 3.05 are available on-line, but are not being updated, and are not longer supported as of February 1994 ] * VMS - A VMS implementation courtesy of Will Gilbert of the University of New Hampshire is available on the ncbi.wi.mit.edu archive. The Multinet/TGV, Wollongong Pathway, and UCX TCP/IP stacks are currently supported. Read the files ENTREZ/111README.VMS_TGV ENTREZ/111README.VMS_TWG, and ENTREZ/111README.VMS_UCX, respectively, for downloading and usage information. This file contains instructions for downloading versions of Entrez for the SGI Iris workstation, Macintosh, or IBM-PC with Microsoft Windows platforms. Additional UNIX executables are available for DEC Alpha OSF1 workstations and Solaris workstations, by performing operations which are analogous to what is described SGIs. Also, executables for ULTRIX are available on the ncbi.wi.mit.edu archive. The NCBI is dropping support for SunoOS. Please email toolbox@ncbi.nlm.nih.gov if you have concerns about this. It may also be possible for you to build your own version of Network Entrez by downloading the NCBI toolkit, available on ncbi.nlm.nih.gov in the /toolbox/ncbi_tools directory. Contact toolbox@ncbi.nlm.nih.gov for details. CONFIGURATION Entrez can only function if the computer on which it resides has a direct Internet connection. Electronic mail access to the Internet is insufficient. In general, if you can install and use a WWW-browser on your system, you should be able to install and use Entrez. Check with your system administrator or Internet provider if you are uncertain as to whether you have direct Internet connectivity. If you are not behind a firewall, and have a Domain Name Server (DNS) available, no additional configuration is necessary, and Entrez should come up with its initial Query window. Otherwise, a configuration form will be displayed. If DNS is not available, uncheck the Domain Name Server button. If you are behind a firewall, set the Connection control to Firewall. The Proxy box then becomes active. If you also use a proxy server, type in its address. (If you have DNS, it will be of the form www.myproxy.myuniversity.edu. If you do not have DNS, you should use the numerical IP address of the form 127.45.23.6.) Once you type something in the Proxy box, the Port box and Transparent Proxy button become active and can be filled in or changed as appropriate. (By default the Transparent Proxy button is off, indicating a CERN-like proxy.) Ask your network administrator for advice on the proper settings to use. If you are in the United States, the default Timeout of 30 seconds should suffice. From foreign countries with poor Internet connection to the U.S., you can select up to 5 minutes as the timeout. Once you press Accept, Entrez will save the settings to a configuration file and quit. You must restart Entrez in order for the network-aware settings to take effect. If you are behind a firewall, it must be configured correctly to access NCBI services. Your network administrator may have done this already. If not, please have them contact NCBI for further instructions on setting up firewalls to work with NCBI services. OLD CONFIGURATION PROGRAM (SOFTWARE RELEASED PRIOR TO JANUARY 1995) All of the versions of Network Entrez should be configured using a configuration program, 'netentcf', which is an extention of the 'entrezcf' configuration program that appears on the Entrez: Sequences CD-ROM, as well as in the entrez archives on the ftp server ncbi.nlm.nih.gov. If you are a subscriber to the Entrez CD-ROM series, refer to the documentation which arrived with the Entrez: Sequences disc, for information about 'entrezcf'. The 'netentcf' program will create a configuration file which is compatible with both the Entrez executable and the Network Entrez program. With the exception listed in the note below, it should be possible to only run the 'netentcf' once, and be ready for both Entrez and Network Entrez usage. When you launch 'netentcf', the 'netentcf' program should be located in the same folder/directory structure in which you unpacked it from the anonymous ftp server. If not, 'netentcf' will post a dialog box where you must provide the name of the folder/directory which contains the DATA folder/directory, and for some platforms, the ASNLOAD folder/directory. This is the same behavior as that exhibited by the 'entrezcf' program. The main 'netentcf' window is the same as the 'entrezcf' window, except that there is an additional checkbox near the top of the screen marked 'Entrez Network Service'. Select this checkbox, and make any other selections from this window which are compatible with your usage of the non-network version of Entrez. If you are not a user of the non-network Entrez program, then make sure that the "Entrez: Sequences" and "Entrez: References" boxes are deselected. Press the Accept button when you are through with this window. Note that the Network Entrez program only uses the information associated with the the 'Entrez Network Service', and the non-Network Entrez program only uses the information associated with 'Entrez: Sequences' and 'Entrez: References'. After passing through any relevant dialog boxes associated with Entrez: Sequences and Entrez: References, you will reach the Network Entrez Configuration dialog box. In order to obtain a reliable configuration, you should Connect to the dispatcher and successfully use the Attempt Connection button to test your ability to use the Network Entrez service. Note that you can specify the Dispatcher configuration and Service specification through this window. Overall, the recommended order of operations is: * Press the Dispatcher-Specify button and make certain that your user-name is correct. At present, there is no restriction upon user-name, but it is suggested that you use either your system login name, if you have one, or some other name which uniquely identifies you, like "Jane Smith". Use of the numeric IP addresses is recommended for the dispatcher name, since this will make it easier for your machine to reliably reach the dispatcher. However, if you experience problems, you can try the corresponding Fully Qualified Domain Name instead. [ NOTE: Some versions of the Network Entrez software point by default to ncbi.nlm.nih.gov (130.14.25.1). This machine no longer runs a dispatcher. Be sure that you configure the program to use gold.nlm.nih.gov (130.14.25.47) or dispatch1.nlm.nih.gov (130.14.25.211). ] * Connect to the dispatcher. * Press the Service-Specify button. Press the Catalog button (this is only possible if you have successfully connected to the dispatcher), and select the desired service name from the list of options by double-clicking on the name. Then double-click one of the resource names. The services and resources named 'Entrez' are recommended. Read the on-line catalog descriptions for more details. * Accept the service configuration (push the Accept button in the Service Selection window), and then push the Attempt Service Request button. If you are not a registered user, this is where you will find out. Follow the directions provided. If you successfully connect to the requested service, then accept the configuration and save the configuration file. An explanation of the resource minimum and maximum numbers is in order here. The resource-min and resource-max fields indicate the minimum and maximum versions of the dataset which are acceptable to you. A maximum value of "0" is interpreted as infinity. The network services dispatcher will always provide the highest numbered dataset which is also consistent with the user's stated [resource-min,resource-max] requirements. The following [minimum,maximum] values have the following interpretations: [1,0] Give me the highest numbered version available. [40,0] Give me the highest numbered version available which is >= 40 (i.e., at least Entrez 4.0), or an error if only lower-numbered datasets are available. [40,40] I will only accept version 40 (Entrez 4.0), perhaps because I don't want the dataset to change without my realizing it. I accept the consequences of an error when the Entrez 4.0 dataset is taken off-line. Note to users of the non-Network Entrez: While it is possible to select nearly every familiar combination of Entrez: Sequences and Entrez: References, it is not possible to de-select Disc Swapping when you have all three data sources selected (Network+Sequences+References), both Entrez media are CD-ROMs, and you only have one CD-ROM drive. If you must have this configuration, then either save a copy of the configuration file (specific to your platform; see the Entrez documentation for details) or re-run the 'netentcf' program between alternate invocations of Entrez or Network Entrez. HOW DOES NETWORK ENTREZ WORK? The Network Entrez client starts out by connecting to a central Dispatcher and issuing a Service Request for one of the Entrez services. The dispatcher routes the service request to a server machine which establishes communication with the client. Subsequent communication between between server and client takes place using ASN.1 encoded messages. Most complex processing is performed by the server and, of course, the data-set resides exclusively at the server. FIREWALL WARNING Some institutions surround their network with a 'firewall', which restricts contact with outside networks to varying degrees. Note that your firewall may impede your ability to use Network Entrez. In some cases, it is possible to work around the firewall, with the cooperation of your local network managers. Please contact NCBI at net-info@ncbi.nlm.nih.gov to discuss the matter, if this is an issue for you. For many users, the "SOCKSIFIED UNIX NETWORK ENTREZ CLIENTS" section below will satisfy your needs. As of early December 1995, all Network Entrez clients are capable of reversing the connection of the client<->server connection, making it more palatable for many firewalls. To use this new functionality, check the "Outgoing Connections Only" checkbox on the second screen of the configuration window. 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". DOCUMENTATION If you are unfamiliar with Entrez, you should obtain a copy of the Entrez CD-ROM documentation; note that the CD-ROM and network products are nearly identical. The Entrez documentation is available by anonymous ftp, and is contained in the /entrez/docs directory on ncbi.nlm.nih.gov. Users with access to a Macintosh should take entrzdoc.hqx, which is a self-extracting-archive containing a Microsoft Word document. When printing this document, be certain to select the Grayscale option from the "Print ..." dialog box. Users without access to a Macintosh should take entrzdoc.txt, which is a text-only version of the same document. MACINTOSH UPDATE DOWNLOADING AND INSTALLATION INSTRUCTIONS The latest version of Network Entrez may be downloaded via anonymous ftp from the NCBI file server in the entrez/network directory. The Network Entrez update for the Macintosh is supplied as a Compact Pro (TM) self-extracting archive. The following instructions are an example of downloading using the HyperFTP (c) package. DOWNLOADING * Remove any old files from your hard disk. For example, remove any old Nentrez applications, or "data" or "asnload" folders. * Create an ENTREZ folder on your hard disk, if one does not already exist. * Launch HyperFTP. * Connect to "ncbi.nlm.nih.gov". * Enter "anonymous" as the user name. * Enter your Internet e-mail address as the password. * Set the BinHex file Transfer Mode. * Double click on the "entrez" directory. * Double click on the "network" directory. * Receive the "entrez.hqx" file, saving as "entrez.sea" in the ENTREZ directory. * Disconnect from the NCBI file server. * Quit HyperFTP. * Double click on the "entrez.sea" application. This will self-extract into "Network Entrez", files the "asnload", "data", "seq" and "ref" folders. INSTALLATION * Double click on the "Network Entrez" icon to start the application. NOTE: If you attempt to view very large sequences, Network Entrez may report out-of-memory errors, in which case it will be necessary to increase the "preferred size" for the Network Entrez application in the "Get Info" box accessed from the Finder's File menu. It is recommended that the default memory size be used unless a memory related problem is encountered with the program. The amount of memory to assign to Network Entrez must be determined empirically, but will be limited by the memory capacity of your computer. If your Macintosh supports virtual memory and is configured to do so (see the Memory control panel), it may be possible to assign more memory to a program than otherwise possible. When assigning a preferred size to Network Entrez, one should also consider the memory requirements of any other applications that will need to be run alongside Network Entrez. MICROSOFT WINDOWS UPDATE DOWNLOADING AND INSTALLATION INSTRUCTIONS The latest version of Network Entrez may be downloaded via anonymous ftp from the NCBI file server in the entrez/network/mswin directory. The Network Entrez update for the the PC under Microsoft Windows is supplied as a PKZIP (R) self-extracting archive. DOWNLOADING * Remove any old files from your hard disk. For example, remove any old Nentrez.exe applications, or "data" or "asnload" directories. * Change directory (cd) into the C:\ENTREZ directory, creating one if necessary. This directory may be created anywhere, not necessarily on the C: drive, and not necessarily at the disk root (\). * Type "ftp ncbi.nlm.nih.gov". * Enter "anonymous" as the user name. * Enter your Internet e-mail address as the password. * Type "bin" to set the binary transfer mode. * Type "cd entrez". * Type "cd mswin". * Type "cd winsock1.1". * Type "get entrezz.exe". * Type "quit". * Type "entrezz". This will self-extract into "NENTREZ.EXE" and "NETENTCF.EXE" executables and the "ASNLOAD", "DATA", "SEQ" and "REF" directories. INSTALLATION * Type "win" to run Microsoft Windows, and use the Program Manager's "New" command to set up icons for the NETENTCF and NENTREZ applications. See the Windows User's Guide for further instructions. * Launch the NETENTCF application, and follow the instructions provided in the Configuration section, above. * Launch the NENTREZ application to start Network Entrez. UNIX UPDATE DOWNLOADING AND INSTALLATION INSTRUCTIONS The latest version of Network Entrez may be downloaded via anonymous ftp from the NCBI file server in the entrez/network directory. The Network Entrez update for the SUN and SGI is supplied as a compressed tar archive. The SGI version runs under X11R4. DOWNLOADING * Remove any old files from your hard disk. For example, remove any old Nentrez applications, or "data" directory. * Type "ftp ncbi.nlm.nih.gov". * Enter "anonymous" as the user name. * Enter your Internet e-mail address as the password. * Type "bin" to set the binary transfer mode. * Type "cd entrez". * Type "get sgi.tar.Z". * Type "quit". * Type "uncompress sgi.tar.Z". * Type "tar xvf sgi.tar". This will extract into the "data" directory and the 'Nentrez' executables. INSTALLATION * Run an X window manager. Note that your system must be configured for the appropriate version of the X Window System (X11R4 or X11R5). * Type "Nentrez" to run Network Entrez. You can specify foreground and background colors, and the maximum number of milliseconds that indicates a double click, as follows: Nentrez -fg plum -bg "pale green" -xrm '*multiClickTime: 1000' * Nentrez relies on the .ncbirc file to find the Network Services Dispatcher address, the details for the Entrez services which you would like to obtain, the paths to the CD-ROM(s) (if used) and to find the paths to the data directory (as will any other programs that use the NCBI data access library.) Nentrez will look for .ncbirc first in the current directory, then in your home directory, and finally in the directory whose path is specified by the NCBI environment variable. You can put the active .ncbirc file wherever it is most convenient, as long as you make sure that the first .ncbirc file found is correctly edited. NOTE ON SUN KEYMAPS Network Entrez for UNIX machines uses the X11 windowing system and the OSF/Motif toolkit. Motif provides virtual keysyms, which map particular key presses to classes of actions. The symbolic mappings must reside in the XKeysymDB file, which should be in the list of paths specified by the XFILESEARCHPATH environment variable. Many Sun systems don't have the proper osf-specific lines in XKeysymDB. This results in a long list of error messages of the form: Warning: translation table syntax error: Unknown keysym name: osfHelp Warning: ... found while parsing 'osfHelp: Help()' The quick and dirty solution has been to send stderr to the null device: Nentrez >&! /dev/null Unfortunately, lack of appropriate keysym mappings prevents the backspace or delete keys from working in Network Entrez. A better solution is to provide the proper keyboard mappings. To do so, find the XKeysymDB file, which must be in your machine's XFILESEARCHPATH environment variable's list of paths, or pointed to by the XKEYSYMDB environment variable. (Create the file if it does not exist anywhere in these paths.) Cat (append) the following file to it: ---------------------------begin included file------------------------------ ! ! OSF Keysyms ! osfBackSpace :1004FF08 osfInsert :1004FF63 osfDelete :1004FFFF osfCopy :1004FF02 osfCut :1004FF03 osfPaste :1004FF04 osfAddMode :1004FF31 osfPrimaryPaste :1004FF32 osfQuickPaste :1004FF33 osfPageUp :1004FF41 osfPageDown :1004FF42 osfEndLine :1004FF57 osfBeginLine :1004FF58 osfActivate :1004FF44 osfMenuBar :1004FF45 osfClear :1004FF0B osfCancel :1004FF69 osfHelp :1004FF6A osfMenu :1004FF67 osfSelect :1004FF60 osfUndo :1004FF65 osfLeft :1004FF51 osfUp :1004FF52 osfRight :1004FF53 osfDown :1004FF54 ! DEC specific keysyms ! DRemove :1000FF00 ---------------------------end included file------------------------------ SOCKSIFIED UNIX NETWORK ENTREZ CLIENTS At present, all of the posted UNIX Network Entrez clients are SOCKSified. This means that they can run successfully behind a firewall, where a SOCKS daemon exists at the edge of the firewall. The Network Entrez software determines at runtime whether or not to use a SOCKSified method of communicating with NCBI's Dispatcher, based upon the presence or absence of the file /etc/socks.conf. On systems without this file, the Network Entrez software should run as it has in the past. On systems where /etc/socks.conf is present, it should be configured to permit access to the appropriate NCBI computers. At present, this means that the following line should be added to /etc/socks.conf: sockd 130.14.25.211 255.255.255.0 Also note that the SOCKS_SERVER environment variable must be set to point to the hostname of your SOCKS daemon. If these constraints are incompatible with your SOCKS environment, you can build Network Entrez from its source code in the NCBI toolbox, in ncbi.nlm.nih.gov:/toolbox/ncbi_tools. We hope to make SOCKSified clients for other platforms available in the not-too-distant future, subject to time availability and technical constraints. Many thanks to Rick Blevins of Merck for his help in testing this out in a real firewall environment, and to Don Holt of Glaxo for confirming this correct operation. If you have trouble running SOCKSified Network Entrez, please verify the proper operation of your SOCKS environment using other SOCKSified applications prior to contacting NCBI. DATA ENCRYPTION AVAILABLE FOR U.S. AND CANADIAN USERS For U.S. and Canadian users who might be concerned about the security of their Network Entrez data which traverses the Internet, it is now possible to build Network Entrez in a manner which causes all communications to be encrypted. The encryption uses DES cypher-block-chaining, where the DES key is pseudorandomly selected by the Network Entrez client software, and is securely transmitted to the Network Entrez server using public key encryption. The private key for the public key encryption only exists on NCBI's Dispatcher computers. The public key appears in the Network Entrez software releases in the "data" directory, as well as in the NCBI toolbox and on the Entrez CD-ROMs, release 11.0 and higher. The public key file is named "pubkey.enc". Due to U.S. export regulations, NCBI cannot post encryption-capable software for anonymous FTP. U.S. and Canadian users who wish to use encryption-capable Network Entrez will need to build Network Entrez from source code in the NCBI toolbox, and follow the instructions in the toolbox's network/encrypt/README file to obtain the RIPEM/RSAREF source code. Since Network Entrez consists of keyword searches of public data, it is unlikely that users will need to use data encryption. There may, however, be concerns about transmitting private sequence data over the network for BLAST searches. Since the same encryption scheme will be used in the forthcoming Dispatcher-based network BLAST client/server software, interested users and developers may wish to preview the encryption methods now. We would like to thank James Bidzos, President of RSA Data Security, Inc., for granting permission to use the software from the RSAREF encryption libraries for this application and to Mark Riordan for maintaining the RIPEM/RSAREF distribution site. DOCUMENT REVISION HISTORY: Date | Change =============================================================================== 04-21-93| Add revision history, fix directory names for all platforms to | indicate correct directories (entrez/current/network and | entrez/current/network/mswin), and announce availability of VMS | Multinet/TGV version. ------------------------------------------------------------------------------- 05-05-93| Clarify that only System 7 is currently supported for Macs, | and insert note regarding Sun keymaps. ------------------------------------------------------------------------------- 06-15-93| Announce availability of WinSock 1.1, unpost End User disk for | PC-NFS 4.0 upgrade, announce forthcoming Wollongong and UCX. ------------------------------------------------------------------------------- 06-18-93| Add description of resource-min and resource-max, announce | availability of Wollongong. ------------------------------------------------------------------------------- 09-01-93| Announce compatability with the following WinSock 1.1 stacks: | Lanera, PC/TCP, Wollongong Pathway, Microsoft WfWG. ------------------------------------------------------------------------------- 09-13-93| Cleanup document to eliminate references to beta-test, add Trumpet | WinSock to list of supported stacks, add firewall notice, add note | regarding use of 'gold' dispatcher. ------------------------------------------------------------------------------- 09-15-93| Change Will Gilbert's affiliation from Whitehead to UNH, add | pointer to Entrez documentation. ------------------------------------------------------------------------------- 09-17-93| Add registration details. ------------------------------------------------------------------------------- 09-21-93| Add note regarding Macintosh memory errors, clarify that Network | Entrez only uses the 'Entrez Network Service' configuration | information, and clarify use of usernames. ------------------------------------------------------------------------------- 09-30-93| Add Novell lwp4dos to list of tested WinSock stacks ------------------------------------------------------------------------------- 10-08-93| Move PC-NFS 4.0 and NetManage 3.05 executables to directories | containing the version number, to reduce future confusion with | (for example) PC-NFS 5.0 users downloading the "pcnfs" version. ------------------------------------------------------------------------------- 02-10-94| End support for PC-NFS 4.0 and NetManage 3.05, announce UCX, Ultrix, | DEC Alpha, and Solaris versions. Move entrez/current/network | to entrez/network. Add B&W to list of tested WinSock stacks. ------------------------------------------------------------------------------- 01-04-95| Changed Dispatcher addresses to 130.14.25.47 and 130.14.25.211. ------------------------------------------------------------------------------- 01-30-95| Encourage users to try Network Entrez before attempting registration, | add TwinSock to list of tested WinSock stacks, add new configuration | section and new SOCKS and encryption sections. ------------------------------------------------------------------------------- 02-02-95| Add SuperTCP and correct TwinSock's version number ------------------------------------------------------------------------------- 08-23-95| Remove references to Network Entrez registration prior to use. | Registration was discontinued effective August 1, 1995. ------------------------------------------------------------------------------- 11-08-95| Add reference to README_2 ------------------------------------------------------------------------------- 11-30-95| Added discussion of "Outgoing Connections Only" flag in firewall | section ------------------------------------------------------------------------------- 06-27-97| Removed reference to -d option when extracting PC archive, since | this is no longer necessary thanks to a different archiving | technology. ------------------------------------------------------------------------------- 06-14-99| Removed references to netentcf program which is obsolete now.