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 to Install
• Server Installation
• Client Installation
• Changing configuration
• Change the Documentation Language

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:

• Install the web server software
• Configure and start your web server software
• Install the Documentation Search Service
• Configure the Documentation Search Service
• Install or register your documentation
• Using the Documentation Search Service

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. You may also consult Installing Optional Software and Server Updates in the AIX Installation Guide.

• 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)

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.

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.

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:

1. Change to root user. On a command line enter wsm system. This opens the System Environments container. Double-click on the Internet Environments icon to open it.
2. When the notebook appears, click on the Default Browser tab if it isn't already the front page.
3. Enter the command that launches the default browser for all users on this computer. Include any flags that are required when a URL is included in the command. From the System Environments window, double-click on the Internet Environments icon to reopen it.
4. Click on the Documentation Server tab and select the Local server radio button.
5. 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.

6. If you selected Other, type in the full pathnames of the two directories. Enter the appropriate port number--default port is 80. Your documentation server will now 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:

1. 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.
2. Select the Change/Show Default Browser choice.
3. Return to the web configure main menu. Select the Change Documentation and Search Server choice. Click the List button and select local - this computer for server location. When the Web Server Software screen appears, select the web server software you are using.
4. Type in the full pathnames of the two directories, and the appropriate port number. SMIT will configure your system.

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.

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:

• Install the Client Software
• Configure the Documentation Search Service
• Using the Documentation Search Service

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.

1. Install a web browser that can display forms (the Netscape browser is on the AIX 4.3 Netscape Products CD)
2. 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, or the Docsearch Client - CDE Desktop Icons and Actionsfileset if you are using the CDE Desktop.

You do not need to install the Docsearch Server fileset.

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:

1. Change to root user on the client computer. On a command line enter wsm system. This opens the System Environments container. Double-click on the Internet Environments icon to open it.
2. When the notebook appears, click on the Default Browser tab if it isn't already the front page. Enter the default browser that you want for all users on this computer. Include any flags that are required when a URL is included in the command.
3. In the System Environments window, double-click on the Internet Environments icon to open it. In the Documentation Server page, click on the Remote server radio button and enter name of the documentation server computer in the Computer name field.
4. In the Server port, enter the port number the web server software is using. The most commonly used port is 80. Your client computer will now be configured.

   Remember to Install or register your documentation.

Using SMIT:

1. Change to root on the client computer. Enter the smit web_configure command to open the web configuration screen. This menu is stored under the System Environments menu in SMIT.
2. 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.
3. Return to the SMIT web configure main menu. Select the Change Documentation and Search Server choice. Click the List button and select Remote computer for server location. On the next screen, type in the name and the appropriate port number of the remote documentation search server computer that you want this client computer to send its search requests to. 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.

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:

• View the Current Configuration
• Change a client's computer's default remote Documentation Search Service
• Select the documentation search server for a single user
• Convert a Client System to a Server System
• Disable or Uninstall the documentation Search Service
• Convert between a Standalone Server and a Public Remote Server
• Change the Default Browser
• Change the Web Server Software on a Documentation Server
• Change the Documentation Language

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:

1. Change to root user. On a command line type wsm system
2. In the System Environments window, double-click on the Internet Environments.
3. 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.
4. The Documentation Server configuration page shows the current settings for the documentation server for this computer.

Using SMIT:

1. Change to root user. On a command line type smit web_configure. From the web configuration menu, select Show Documentation and Search Server. The current configuration information will appear.

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:

1. Change to root user. On the command line type the command wsm system. This opens the System Environments container.
2. In the System Environments window, double-click on the Internet Environments icon to open it and click on the Documentation Server tab.
3. Click on the Remote server radio button, and enter the name of the documentation server computer in the Computer name field. This is the server computer that contains the documents that you want this client computer to be able to search.
4. In the Server port field at the bottom, Enter the port number the web server software is using. The most commonly used port is 80. Your client computer will now be reconfigured to use the new server.

Using SMIT:

1. Change to root user. On a command line enter smit web_configure. From the web configuration screen, select Change Documentation and Search Server. From the List, select Remote computer.
2. Enter the NAME of remote documentation server field the name or IP address of the new server and the appropriate port number.When the output pane shows the message Documentation server onfiguration completed. the reconfiguration is finished.

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
• Search all documents on another server

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:

          export DOCUMENT_SERVER_MACHINE_NAME=<servername>
     	  export 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.

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.

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 names ds_form, ds_form2, ds_rslt, and ds_rslt2. 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.

1. Uninstall the documentation search service component of the documentation search service 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.
2. Uninstall the web server software if it is not being used for some other purpose.
3. Uninstall the documentation and indexes. You can leave documentation installed, but any Search links within the documents will generate error messages when clicked.
4. 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.

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.

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:

1. Change to root user on the client computer. On a command line type wsm system. This opens the System Environments container.
2. When the System Environments window appears, double-click on the Internet Environments icon to open it.
3. When the notebook appears, click on the Default Browser tab if it isn't already the front page.
4. 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.
5. Click the OK button. You can now close Web-based System Manager.

Using SMIT:

1. Change to root user. Install the new browser. On a command line enter smit web_configure. From the web configuration screen, select the Change/Show Default Browser choice, and type in the field the command that launches your new web browser. The change will take effect the next time users log back into the computer.

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.

1. Uninstall the current web server.
2. Install the new web server. You may consult section Install the Web Server Software in the AIX Installation Guide.
3. 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.

4. 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:

1. Change to root user. On the command line, enter wsm system to open the System Environments container.
2. In the System Environments window appears, double-click on the Internet Environments icon to open it.
3. When the notebook appears, click on the Documentation Server tab. On this page, the Local server radio button should already be selected.
4. 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 is not 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.

5. 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.
6. In the Server port field at the bottom, Enter the port number the web server software is using. The most common default port is 80. Your server will now be reconfigured to use the new webserver software.

Using SMIT:

1. Change to root user. On the command line, enter smit web_configure. From the web configuration screen, select the Change Documentation and Search Server choice.
2. When the Documentation and Search Server screen appears, select local - this computer for server location. From the Web Server Software screen, select List and then choose the web server software you are using.
3. Enter the full pathnames of the directories and choose the appropriate port number. SMIT will now configure your system. Any users who were logged in when configuration was done must log out, and then log back in to activate the search service.

Change the Documentation Language

However, there may be reasons that users want to see the documentation in some language other than the computer's current default locale.

The documentation language can be changed for all users on a computer, or it can be changed for a single user.

Note: These techniques will not affect the language that is used if you are opening a document or search form from an HTML link inside a document. These techniques only affect what language is used when you use the desktop icons or the docsearch command.

To Change Documentation Language for All Users

	/usr/bin/chdoclang <locale>

The chdoclang command adds the following line to the /etc/environment file:

	DOC_LANG=<locale>

Note If the users are using a remote documentation server, the chdoclang command should be run on the user's client computer, not the remote server. Also, the language change will not take effect until the next time a user logs out and back into the computer.

For example, suppose that a computer's default locale is English. The users would normally see English documentation if they use the AIX Documentation Search Service or if they open the AIX Base Documentation.

If the system administrator now wants all the users to see Japanese documents instead of English documents, the administrator would run (as root) the following command:

	/usr/bin/chdoclang Ja_JP

After users log out and then log back in, they will now see Japanese versions of the documentation instead of English versions.

Note: Before a computer can serve documents in a language, the AIX locale (language environment) for that language, and the translated versions of the documents must also be installed on the documentation server.

To Change Documentation Language for a Single User

	 /usr/bin/chdoclang [-u UID|username] <locale>

where <locale> is replaced by the locale that will be the new language and <username> is replaced with the user's username. Locale names can be found in the AIX Language Support Table.

Running the command as described above will add the following line to the user's $HOME/.profile file:

        export DOC_LANG=<locale>

where <locale> is the locale that will be the new default documentation viewing and searching language.

For example, if an administrator wanted to change the documentation language of user <fred> to be Spanish(es_ES), they would type the following command:

	 /usr/bin/chdoclang -u fred es_ES

Note: Defining the DOC_LANG environment variable in a user's .profile will take precedence over any global DOC_LANG setting in their computer's /etc/environment file. Also, for CDE Desktop you must uncomment the DTSOURCEPROFILE=true line in the $HOME/.dtprofile file, which causes the $HOME/.profile file to be read during CDE login. The change to user's documentation language will then take effect the next time the user logs out and then logs back in.

To Remove a Documentation Language Setting

To delete the global system default documentation language setting, run (as root) the following command:

	 /usr/bin/chdoclang -d 

To delete a single user's language setting, run (as root) the following commmand:

	 /usr/bin/chdoclang -d [UID|username]

For example, to remove the user <fred>'s personal language setting so that he will again use the system default language, run the following command:

	 /usr/bin/chdoclang -d fred