Chapter 18. Documentation Search Service

AIX Version 4.3 System Management Guide: Operating System and Devices

Installation and Configuration

This section provides information about installing and configuring the documentation search server, as well as the documentation search service.

The following main topics are covered:

Introduction

For the documentation search service to function, the following is required: the documentation search service software, a web browser, web server software, the documents to be searched, and the document's indexes. The browser must be a forms-capable browser and the web server must be CGI-compliant.

A computer can be set up as either a documentation server or as a documentation client system. When users on a client computer request a search form or an html document, the request is sent to the web server on a documentation server which then sends back the requested object. When searches are done, they are done on the server computer and the results are then sent back to the user on the client computer.

A documentation server computer has installed on it the documentation search service, all the documents, the document indexes, and web server software. You only need to install the documentation search service client software and a web browser on a client computer.

If you have a standalone (non-networked) computer, both the server and client software are installed on the same standalone computer. Instead of going to a remote computer, requests from users on the standalone computer go to the web server software on their own computer. A documentation server on a network can also be made standalone in the sense that you can configure its web server software to only accept requests from users logged onto the documentation server computer.

Server Installation

Use this procedure if you want to set up a computer to be a documentation server. This is the computer where you want to install your online documentation. A server can be a networked computer that serves remote clients, or it can be a standalone computer that just serves its own users.

The next section covers the following procedures:

1. Install the Web Server Software

If the following software is not already installed on your system, please install it. If you aren't sure what is already installed, enter smit list_installed .

Install a web browser that can display forms (the Netscape browser is on the AIX 4.3 Netscape Products CD)
Install web server software that can run CGI programs (the Lotus Domino Go Webserver is on one of the AIX 4.3 Bonus Pack CDs)

2. Configure and Start your Web Server Software

Consult the documentation that came with your web server software and configure and start your web server software. Write down the full pathnames of the webserver directories where the server starts looking for a) HTML documents, and b) CGI programs (if you are using the Domino Go webserver and you installed it in its default location, you can skip this step.). Also, some webservers may not automatically create these directories. If not, you must created them before you continue.

You must also configure your web server software to allow access from the users and remote computers that will be using this computer as their documentation search server.

3. Install the AIX Documentation Search Service

Install the documentation search service (bos.docsearch, which is on the second AIX 4.3 CD). Install ALL parts of the package, except that if you are not using the CDE Desktop, you do not have to install the Docsearch Client - CDE Desktop Icons and Actions component.

4. Configure the Documentation Search Service

You can configure the documentation search service by using either of the AIX System Management Tools, Web-based System Manager or SMIT.

Using Web-based System Manager:

Change to root user. On a command line enter wsm system . This opens the System Environments container.
When the System Environments window appears, double-click on the Internet Environments icon to open it.
When the notebook appears, click on the Default Browser tab if it isn't already the front page.
Type into the field the command that launches the browser that you want to be the default browser for all users on this computer. Include any flags that are required when a URL is included in the command.
For example, if you would type on a command line wonderbrowser -u http://www.ibm.com to open your wonderbrowser with the www.ibm.com page open inside, you would type wonderbrowser -u into the field. Many browsers (for example, netscape) do not require a flag.

Click on the OK

When the System Environments window appears, double-click on the Internet Environments icon to reopen it.
Click on the Documentation Server tab. The Documentation Server configuration page will appear.
Select the Local server radio button.
Under the heading Location of documents and CGI programs on local server, select the web server software you installed on this computer. If the name of your webserver software isn't listed, select Other.
Note: If you have installed Lotus Domino Go or ICSS in a non-default location on your system, or you set up the servers to use non-standard locations for their cgi-bin or HTML directories, you must select Other.
If you selected Other, type in the full pathnames of the two directories into the fields below Other. If you selected one of the default webserver packages, skip to the next step.
In the Server port field at the bottom, type in the port number the web server software is using. The most common default port is 80 .
Click the OK button. Your documentation server will then be configured.
The configuration for the new webserver software is now complete. Any users who were logged in when configuration was done must log out, and then log back in to activate the search service. You can now close the administration tool.

Next, Install or register your documentation.

Using SMIT:

Change to root user. On a command line type smit web_configure to open the web configuration screen. This menu is stored under the System Environments menu in SMIT.
Select the Change/Show Default Browser choice. Type into the field the command that launches the browser that you want to be the default browser for all users on this computer. Include any flags that are required when a URL is included in the command.
For example, if you would type on a command line wonderbrowser -u http://www.ibm.com to open your wonderbrowser with the www.ibm.com page open inside, you would type wonderbrowser -u into the field. Many browsers (for example, netscape) do not require a flag.

Press OK.
Return to the web configure main menu. Select the Change Documentation and Search Server choice.
1. When Documentation and Search Server screen appears, click the List button and select local - this computer for server location. Press OK.
2. When the Web Server Software screen appears, click list button. Select the web server software you are using.
  Note: If you have installed Lotus Domino Go or ICSS in some non-default location on your system, or you set up the servers to use non-standard locations for their cgi-bin or HTML directories, you must select Other. Press OK.
3. When the next screen appears, type in the full pathnames of the two directories. If you selected one of the two default servers, the pathnames should already be entered automatically. If you set up your webserver to use some port other than the standard port 80 , type in the port number. Press OK. SMIT will then configure your system. When it is done, you should see a Documentation server configuration completed! message at the bottom of the results pane.
4. You can now close SMIT. The documentation search service installation and configuration is now complete. Any users who were logged in when configuration was done must log out, and then log back in to activate the search service.
If you have not yet installed or registered your documents, continue with the next section - Install or register your documentation.

5. Install or Register your Documentation

Remember that before any document can be searched using the documentation search service, it must have an index created and the index must be registered with the search service.

Some applications will ship pre-built document indexes inside their install packages. When the application is installed the indexes will be automatically registered. The AIX Version 4.3 documentation libraries and the Web-based System Manager ship pre-built indexes for their documents.

You can also create indexes for your own HTML documents and register them with the search engine so that they can be searched online. For more details, see the chapter Documentation Search Service in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs for more information.

6. Using the Documentation Search Service

Users can access the global search form by entering docsearch on the command line or by clicking on the search service icon in the CDE Desktop front panel Help subpanel. Search forms may also be launched from Search links inside the document pages of applications such as Web-based System Manager.

Client Installation

Use this procedure if you want to set up a computer to be a client of a remote documentation search server computer. When users on this computer want to search online documentation, the request will be sent to a remote documentation search server where the search will be conducted and the results then sent back to a web browser on this client computer. A documentation search server computer must be created before you create a client.

This next section covers the following procedures:

1. Install the Client Software

If the following software is not already installed on your client system, please install it. If you aren't sure what is already installed, enter smit list_installed .

Install a web browser that can display forms (the Netscape browser is on the AIX 4.3 Netscape Products CD)
Find the documentation search service package (the bos.docsearch package which is on the second AIX 4.3 CD). From this package install:
- the Docsearch Client fileset
- the Docsearch Client - CDE Desktop Icons and Actions fileset if you are using the CDE Desktop.
You do not need to install the Docsearch Server fileset.

2. Configure the Documentation Search Service

You can configure the documentation search service by using either of the AIX system management tools, Web-based System Manager or SMIT.

Using Web-based System Manager:

Change to root user on the client computer. On a command line enter wsm system . This opens the System Environments container.
When the System Environments window appears, double-click on the Internet Environments icon to open it.
When the notebook appears, click on the Default Browser tab if it isn't already the front page.
Type into the field the command that launches the browser that you want to be the default browser for all users on this computer. Include any flags that are required when a URL is included in the command.
For example, if you would type on a command line wonderbrowser -u http://www.ibm.com to open your wonderbrowser with the www.ibm.com page open inside, you would type wonderbrowser -u into the field. Many browsers (for example, netscape) do not require a flag.

Click on the OK button.

When the System Environments window appears, double-click on the Internet Environments icon to open it.
Click on the Documentation Server tab. The Documentation Server configuration page will appear.
Click on the Remote server radio button.
Under the Remote server button, type into the Computer name field the name of the documentation server computer. This is the server computer that contains the documents that you want this client computer to be able to search.
In the Server port field at the bottom, type in the port number the web server software is using. The most commonly used port is 80 .
Click the OK button. Your client computer will then be configured.
The configuration for the new webserver software is now complete. Any users who were logged in when configuration was done must log out, and then log back in to activate the search service. You can now close the administration tool.

Next, Install or register your documentation.

Using SMIT:

Change to root on the client computer. On a command line, enter the smit web_configure command to open the web configuration screen. This menu is stored under the System Environments menu in SMIT.
Select the Change/Show Default Browser choice. Type into the field the command that launches the browser that you want to be the default browser for all users on this computer. Include any flags that are required when a URL is included in the command.
For example, if you would type on a command line wonderbrowser -u http://www.ibm.com to open your wonderbrowser with the www.ibm.com page open inside, you would type wonderbrowser -u into the field. Many browsers (for example, netscape) do not require a flag.

Press OK.
Return to the SMIT web configure main menu. Select the Change Documentation and Search Server choice.
1. When Documentation Search Server LOCATION screen appears, click the List button and select Remote computer for server location. Press OK.
2. When the next screen appears, type into the NAME of remote documentation server field the name of the remote documentation search server computer that you want this client computer to send its search requests to. You can type in a name or an IP address. If the webserver on the remote server is set to use some port other than the standard port 80 , type in the port number. Click the OK button.
  SMIT will then configure your client system. When it is done, you should see a Documentation server configuration completed! message at the bottom of the results pane.
The documentation search functions on this client computer should now be ready to use. Any users that were logged on this client computer before configuration finished must log off, and then log back in to use the search functions.

3. Using the Documentation Search Service

Users on this client computer can access the global search form by typing docsearch on the command line or by clicking on the search service icon in the CDE Desktop front panel Help subpanel. Search forms may also be launched from Search links inside the document pages of applications such as Web-based System Manager.

Changing Configurations

This section contains instructions for changing the configuration of the documentation search service after it is initally installed and configured:

1. View the Current Configuration

This process shows the default system documentation server settings. If a user has specified different settings in the .profile file in their home directory, they will not be affected by the default settings.

You can configure the documentation search service by using either of the AIX system management tools, Web-based System Manager or SMIT.

Using Web-based System Manager:

Change to root user. On a command line type wsm system
When the System Environments window appears, double-click on the Internet Environments icon to open it.
When the notebook appears, click on the Default Browser tab if it isn't already the front page. This shows the current command that is used to launch the default browser.
Click on the Documentation Server tab. The Documentation Server configuration page will appear. This page shows the current settings for the documentation server for this computer.

Using SMIT:

Change to root user. On a command line type smit web_configure to open the web configuration screen. This menu is stored under the System Environments menu in SMIT.
Select Show Documentation and Search Server. The current configuration information will appear.

2. Change a Client Computer's Default Remote Documentation Search Server

This configuration process changes the default system documentation server. If a user has specified a different server in their own .profile file in their home directory, they will not be affected by the default settings.

You can change a client computer's default remote documentation search server by using either of the AIX system management tools, Web-based System Manager or SMIT.

Using Web-based System Manager:

Change to root user on the client computer. On a command line type the command wsm system . This opens the System Environments container.
When the System Environments window appears, double-click on the Internet Environments icon to open it.
Click on the Documentation Server tab. The Documentation Server configuration page will appear.
Click on the Remote server radio button.
Under the Remote server button, type into the Computer name field the name of the documentation server computer. This is the server computer that contains the documents that you want this client computer to be able to search.
In the Server port field at the bottom, type in the port number the web server software is using. The most commonly used port is 80 .
Click the OK button. Your client computer will then be reconfigured to use the new server.
The reconfiguration is now complete. Any users who were logged in when configuration was done must log out, and then log back in to activate the search service. You can now close the administration tool.

Using SMIT:

Change to root user. On a command line enter smit web_configure to open the web configuration screen. This menu is stored under the System Environments menu in SMIT.
Select Change Documentation and Search Server
Click List, select Remote computer, press OK.
Type into the NAME of remote documentation server field the name or IP address of the new server. If the web server on that server computer uses a port other than 80 , change the port number. Click the OK button.
When the output pane shows the message Documentation server onfiguration completed. the reconfiguration is finished. Any users who were logged into the client during the configuration process will need to log out and then log back in to have the changes take effect.

3. Select the Documentation Search Server for a Single User

All users on a computer do not have to use the same documentation search server. The system administrator sets the default server for users, but users can choose to use a different server.

There are two ways users can change documentation search servers

Change Personal Default Server:

If the users wants to change their personal default documentation server they should use this technique.

The user should insert the following two lines in the .profile file in their home directory:

     DOCUMENT_SERVER_MACHINE_NAME = <servername>

     DOCUMENT_SERVER_PORT = <portnumber>

<servername> should be replaced with the name of the documentation search server computer they want to use.
<portnumber> is replaced with the number of the port that the web server on the server uses. In most cases this will be 80 .

The user must them log out and then log back in to see the changes take effect.

Once an individual users places these two lines in their .profile file in their home directory, changes that their system administrator makes to the system-wide default settings will not affect them. If they want to resume using the system default, they should remove the above two lines from their profile and then log out and log back in again.

Search all Documents on Another Server:

In this case, a user doesn't want to change their default search server, they just want to do a single search of all the documents registered on another server. They should type the following into the URL location field of their browser:

http://<server_name>
:[<port_number>
]/cgi-bin/ds_form

This will open into their browser the global search form of the document server with the name of the remote server given in <server_name> . <port_number> only needs to be entered if the port is different from 80 .

For example, if a user wanted to search the documents on a document server named "einstein", and the web server on "einstein" uses the standard port 80, they would enter this URL:

http://einstein/cgi-bin/ds_form

Once the search form for a server appears in their browser, the user can create a bookmark that will take them back to the server. The system administrator of a web server can also create a web page that contains links to all the different documentation servers in an organization.

4. Convert a Client System to a Server System

In this case you have a client computer that is using a remote documentation server to search documents. You want to convert this client computer to be a search server so that the documents stored on this computer can be searched by the users on this computer or by remote users.

Go to the Server Installation section and follow the instructions there. Complete all of the tasks in that procedure. There is only one modification you need to make to the steps in that section. When you come to the task where you are instructed to install all of the documentation search service software, you only need to install the Docsearch Server component since you have already installed the client software onto this computer.

5. Disable or Uninstall the Documentation Search Service

You can disable a server temporarily, or uninstall it permanently

Temporarily Disabling:

There are several different techniques:

Turn off the web server software or turn off the web server access permissions for all, or some users.
To disable all searches, but leave the web server functioning, go to the CGI directory of the web server. Find the files named ds_form and ds_rslt. Turn off these file's execution permissions. This will turn off all the documentation search service searches. An error message will appear each time users click on a Search link that goes to this server.
To disable just the searching of a specific index without removing it from the computer, unregister the index.

If you think you might ever want to re-register the index,you need to record the index's registry information before you remove it. To do this, type (as root or a search administrator) the following commands on a command line:
1. /usr/IMNSearch/cli/imndomap /var/docsearch/indexes -l <index_name>
  where <index_name> is replaced with the name of the index.
2. Write down the index name, document path, and title.
3. /usr/IMNSearch/cli/imndomap /var/docsearch/indexes -d <index_name>
4. cp /var/docsearch/indexes/imnmap.dat /usr/docsearch/indexes/imnmap.dat
If you ever want to re-register this same index, type (as root or a search administrator) the following:
1. /usr/IMNSearch/cli/imndomap /var/docsearch/indexes -c <index_name> <document path> "<title>"
  where you insert the values you recorded above in step 2.

Permanently Uninstalling:

If you are sure you want to permanently remove the search server functions, do the following:

Note: In each of the following steps make sure you do uninstalls using SMIT instead of just deleting software. Deletes will not clean up the system properly.

Uninstall the documentation search service component of the documentation search service docsearch package. If you want this computer to be a client of another search server, leave the Docsearch Client software installed and just uninstall the Docsearch Server component.
Uninstall the web server software if it is not being used for some other purpose.
Uninstall the documentation and indexes. You can leave documentation installed, but any Search links within the documents will generate error messages when clicked.
Unregister any indexes that were not automatically unregistered during the uninstall process. This will included any indexes that you manually registered.
To unregister an index type (as root or a search administrator) the following:

rm -r /usr/docsearch/indexes/<index name>

where <index name> is the name of the index you want to remove.

All of the documentation serve functions should now be disabled. If the users of this computer were using this computer as their search server, you should go into SMIT and change the name of the default search server to another computer. See Changing a Client Computer's Default Remote Documentation Search Server.

6. Convert Between a Standalone Server and a Public Remote Server

The difference between a stand alone server and a public remote server is that the remote server allows people on other machines to access and search the documents stored on the remote server. After a standalone server is connected to a network, modify the web server's security configuration controls to allow users on other computers to access the documents on this computer. Consult the web server documentation for instructions on how to alter these access permissions.

7. Change the Default Browser

This procedure changes the default browser that is used by applications that use the defaultbrowser command to open a browser window. You can changes the default browser by using either of the AIX system management tools, Web-based System Manager or SMIT.

Using Web-based System Manager:

Change to root user on the client computer. On a command line type wsm system . This opens the System Environments container.
When the System Environments window appears, double-click on the Internet Environments icon to open it.
When the notebook appears, click on the Default Browser tab if it isn't already the front page.
Type into the field the command that launches the browser that you want to be the default browser for all users on this computer. Include any flags that are required when a URL is included in the command.
For example, if you would enter on a command line wonderbrowser -u http://www.ibm.com to open your wonderbrowser with the www.ibm.com page open inside, you would type wonderbrowser -u into the field. Many browsers (for example, netscape) do not require a flag.
Click the OK button. You can now close Web-based System Manager.

Using SMIT:

Change to root user. Install the new browser. On a command line enter smit web_configure to open the web configuration screen. This menu is stored under the System Environments menu in SMIT.
Select the Change/Show Default Browser choice.
Type in the field the command that launches your new web browser.
Press OK. Close SMIT.
The change will take effect the next time users log back into the computer.

8. Change the Web Server Software on A Documentation Server

Use this procedure if you have already configured a documentation server and you now want to change the web server software that it is using.

Uninstall the current web server.
Install the new web server.
Configure and start your new web server software. Consult the documentation that came with your web server software and configure and start your web server software. Write down the full pathnames of the webserver directories where the server starts looking for HTML documents, and CGI programs (if you are using the Domino Go webserver and you installed it in its default location, you can skip this step). Also, some webservers may not automatically create these directories. If not, you must create them before you continue.
You must also configure your web server software to allow access from the users and remote computers that will be using this computer as their documentation search server.
Reconfigure the documentation search service by using either of the AIX system management tools, Web-based System Manager or SMIT.

Using Web-based System Manager:

Change to root user.
On a command line enter wsm system . This opens the System Environments container.
When the System Environments window appears, double-click on the Internet Environments icon to open it.
When the notebook appears, click on the Documentation Server tab.
The Documentation Server configuration page will appear.
The Local server radio button should already be selected.
Under the heading Location of documents and CGI programs on local server, select your new web server software. If the name of your webserver software isn't listed, select Other.
Note: If you have installed Lotus Domino Go or ICSS in a non-default location on your system, or if you set up the web servers to use non-standard locations for their cgi-bin or HTML directories, you must select Other.
If you selected Other, type in the full pathname of the two directories into the fields below Other. If you selected one of the default webserver packages, skip to the next step.
In the Server port field at the bottom, type in the port number the web server software is using. The most common default port is 80 .
Press OK. Your server will then be reconfigured to use the new webserver software.
The configuration for the new webserver software is now complete. Any users who were logged in when configuration was done must log out, and then log back in to activate the search service. You can now close the administration tool.

Using SMIT:

Change to root user.
On a command line enter smit web_configure to open the web configuration screen. This menu is stored under the System Environments menu in SMIT.
Select the Change Documentation and Search Server choice.
When the Documentation and Search Server screen appears, click the List button and select local - this computer for server location. Press OK.
When the Web Server Software screen appears, click the List button. Select the web server software you are using.
Note: If you have installed Lotus Domino Go or ICSS in some non-default location on your system, or you set up the servers to use non-standard locations for their cgi-bin or HTML directories, you must select Other.
Press OK.
When the next screen appears, type in the full pathnames of the two directories. If you selected one of the two default servers, the pathnames should already be entered automatically. If you set up your webserver to use some port other than the standard port 80 , type in the port number. Press OK. SMIT will then configure your system. When it is done, you should see a Documentation server configuration completed! message at the bottom of the results pane.
You can now close SMIT.
The configuration for the new webserver is now complete. Any users who were logged in when configuration was done must log out, and then log back in to activate the search service.