Installing isearch The _i_s_e_a_r_c_h facility is a pair of shell scripts that allow users to search the Tru64 UNIX documentation set using a Web browser. The usual place for installation of scripts and other executable Web programs is in a directory named _c_g_i-_b_i_n. These programs are often referred to as "cgi-bin", or CGI, programs. This document explains how to install _i_s_e_a_r_c_h. Optionally, the _i_s_e_a_r_c_h facility can log queries and report them at intervals to Compaq. This logging helps us to improve our documentation by telling us what information we can make more visible. If you want to enable logging, see the section titled LLLLooooggggggggiiiinnnngggg QQQQuuuueeeerrrriiiieeeessss. PPPPrrrreeeerrrreeeeqqqquuuuiiiissssiiiitttteeeessss To use _i_s_e_a_r_c_h, your system must satisfy the following prerequisites: +o Configuration as a Web server For security reasons, Web browsers do not permit a user to call for the execution of programs on the user's local system. Calls for CGI programs, including _i_s_e_a_r_c_h, can be handled only through a Web server. Tru64 UNIX includes a copy of the Compaq Secure Server. You can obtain other server software and configuration instructions from third parties such as Netscape Communications Corporation. When your system is configured as a Web server, it can serve the _i_s_e_a_r_c_h utility to any number of client systems, including itself. +o A browser that supports HTML tables, forms, and JavaScript 1.1 (for example, Netscape Navigator or Communicator Version 4.0 or higher, or Microsoft Internet Explorer Version 4.0 or higher) The Netscape browser provided with Tru64 UNIX includes the required support. Other browsers, especially very old ones, might not work properly with _i_s_e_a_r_c_h. IIIInnnnssssttttaaaallllllllaaaattttiiiioooonnnn This section describes how to install the _i_s_e_a_r_c_h utility. _N_o_t_e The following instructions specify directories into which you must place the files making up the _i_s_e_a_r_c_h utility. Do not attempt to place any of the files in other locations; there are interlocking HTML links between the _i_s_e_a_r_c_h utility and the documentation set, and neither will work correctly if any of the files are not where they are expected to be. Similarly, you must not change the names of any of the files. The _i_s_e_a_r_c_h installation requires the following files, all of which are provided in the /_u_s_r/_s_h_a_r_e/_d_o_c_l_i_b/_o_n_l_i_n_e/_D_O_C_S/_H_T_M_L/_i_s_e_a_r_c_h directory when the Tru64 UNIX documentation CD-ROM is correctly mounted: +o _i_s_e_a_r_c_h and _i_s_e_a_r_c_h__a - the actual CGI scripts for basic and advanced searches, respectively The _i_s_e_a_r_c_h and _i_s_e_a_r_c_h__a scripts must be installed in the server-level _c_g_i-_b_i_n directory. If you have not configured a _c_g_i-_b_i_n directory, configure it and then place the script files there. The directory must be named _c_g_i-_b_i_n, and it must be at the top of the site so that its Web location is as follows: _h_t_t_p://your.server.domain/_c_g_i-_b_i_n/ Check that the permissions on both scripts are 755 and that their ownership is _r_o_o_t:_s_y_s_t_e_m. (Do not confuse the _i_s_e_a_r_c_h script with the _I_s_e_a_r_c_h binary search-engine program.) +o _i_s_e_a_r_c_h._c_a_t - the localized message catalog used by the _i_s_e_a_r_c_h facility This file must be placed in the _c_g_i-_b_i_n directory along with _i_s_e_a_r_c_h and _i_s_e_a_r_c_h__a. Check that its permissions are 644 and that its ownership is 2 Installing isearch _r_o_o_t:_s_y_s_t_e_m. +o _i_s_e_a_r_c_h._m_s_g - the localizable source file from which _i_s_e_a_r_c_h._c_a_t is generated This file is provided so that versions other than English can be made. It is not necessary to install this file on the system in order to run _i_s_e_a_r_c_h. (To generate a new _i_s_e_a_r_c_h._c_a_t file, edit a copy of _i_s_e_a_r_c_h._m_s_g and compile a new _i_s_e_a_r_c_h._c_a_t by following the instructions in _i_s_e_a_r_c_h._m_s_g.) +o The _i_s_e_a_r_c_h-_c_o_n_t_e_n_t directory - the help files and image files used by _i_s_e_a_r_c_h: - _h_e_l_p._h_t_m_l and _h_e_l_p__a._h_t_m_l - online instructions for using _i_s_e_a_r_c_h and _i_s_e_a_r_c_h__a, respectively These files provide easily available online information for _i_s_e_a_r_c_h users. They can also be translated for versions other than English. - _i_m_a_g_e_s - image file directory This directory contains several image files used by the _i_s_e_a_r_c_h facility. The _i_s_e_a_r_c_h-_c_o_n_t_e_n_t directory must be installed in the server's primary content directory in order for _i_s_e_a_r_c_h to access it; for example, if you have specified /_d_a_t_a/_w_e_b/_p_u_b_l_i_c as the primary content directory, then you must copy _i_s_e_a_r_c_h-_c_o_n_t_e_n_t to that directory. Use the _c_p command's -_r and -_p options. Check that the ownership of the copied area is _r_o_o_t:_s_y_s_t_e_m. +o _I_s_e_a_r_c_h - the search engine binary The _I_s_e_a_r_c_h engine is a compiled binary program that will work only on a Tru64 UNIX Version 4.0 or higher system. Copy this program to the /_u_s_r/_l_o_c_a_l/_b_i_n directory. If no /_u_s_r/_l_o_c_a_l/_b_i_n directory exists, create it and then place _I_s_e_a_r_c_h there. Check that the permissions on _I_s_e_a_r_c_h are 755 and that its ownership is _r_o_o_t:_s_y_s_t_e_m. After you have installed the _i_s_e_a_r_c_h software, you must establish /_u_s_r/_s_h_a_r_e/_d_o_c_l_i_b/_o_n_l_i_n_e as a public content directory for your Web server. If you are using the Compaq Secure Server, for example, you establish this configuration by creating a directory alias, setting access control for the new directory, Installing isearch 3 and reloading the server. The easiest way to perform these tasks is to use the Tru64 UNIX Open Software Internet Solutions server management tools. For maximum performance, Compaq recommends that you copy the Tru64 UNIX HTML documentation and the _i_s_e_a_r_c_h database from the CD-ROM onto your system's hard disk. Instructions for copying the documentation are contained in the chapter titled "Using Online Documentation" in the Tru64 UNIX _I_n_s_t_a_l_l_a_t_i_o_n _G_u_i_d_e. To copy the database, locate the _I_S_E_A_R_C_H directory at the top level of the CD-ROM and copy it together with its entire contents to the /_u_s_r/_s_h_a_r_e/_d_o_c_l_i_b/_o_n_l_i_n_e directory on your hard disk. For example, if you have mounted the CD-ROM on /_m_n_t, you would use this command: # _c_p -_r_p /_m_n_t/_I_S_E_A_R_C_H /_u_s_r/_s_h_a_r_e/_d_o_c_l_i_b/_o_n_l_i_n_e Do _n_o_t attempt to copy the _I_S_E_A_R_C_H directory to the hard disk unless you also copy the documentation. LLLLooooggggggggiiiinnnngggg QQQQuuuueeeerrrriiiieeeessss To enable query logging, you must create an _i_s_e_a_r_c_h._d_a_t file in the _c_g_i-_b_i_n directory that contains the _i_s_e_a_r_c_h and _i_s_e_a_r_c_h__a scripts. Change to that directory and enter the following command: # _e_c_h_o "_l_o_g_g_i_n_g=_e_n_a_b_l_e_d" > _i_s_e_a_r_c_h._d_a_t When you have enabled logging, each of the scripts will create its own log file in the /_v_a_r/_t_m_p directory and will log each query on a single line in that file. Log entries contain only the exact text of the query that is submitted to the search engine; no user or system information is included. When a script detects that its file has reached 500 lines in length, it renames the file (giving it a name that is guaranteed to be unique), mails it to _r_e_a_d_e_r_s__c_o_m_m_e_n_t@_z_k_3._d_e_c._c_o_m, and then deletes it. Renaming the file allows another user's simultaneous query to be logged into a new copy of the file without the loss of any data. MMMMaaaakkkkiiiinnnngggg iiiisssseeeeaaaarrrrcccchhhh AAAAvvvvaaaaiiiillllaaaabbbblllleeee ttttoooo UUUUsssseeeerrrrssss After installing the _i_s_e_a_r_c_h software, you must enable a hot link for _i_s_e_a_r_c_h in the Tru64 UNIX home page. The home page is contained in the following file: 4 Installing isearch /_u_s_r/_d_o_c/_n_e_t_s_c_a_p_e/_T_r_u_6_4__U_N_I_X._h_t_m_l Enable the hot link for _i_s_e_a_r_c_h by following this procedure: 1. Edit the /_u_s_r/_d_o_c/_n_e_t_s_c_a_p_e/_T_r_u_6_4__U_N_I_X._h_t_m_l file using your favorite text editor. 2. Find the list of hot links. This list is coded as a table, with each hot link contained in a single cell. For appearance, the table is laid out so that each table row appears as one item in the list. 3. The entry for _i_s_e_a_r_c_h is already in the table, but it is commented out. To enable it, remove the following two lines: - This line is immediately after the end of the table row for _i_s_e_a_r_c_h. Remove these two lines completely to enable the table entry for _i_s_e_a_r_c_h to appear. 4. In the hot link you have just enabled, replace the word _S_E_R_V_E_R with the name you have assigned to your Web server (for example, _w_w_w._g_u_n_t_h_e_r._c_o_m). 5. Save the edited file and test it. When it works properly, quit from the editor. Installing isearch 5