Changing the Configuration of the Documentation Library Service

This article provides information about changing the configuration of the Documentation Library Service after it has been initially installed and configured. For instructions on how to set up the library service for the first time on a computer, see Installing and Configuring the Documentation Library Service and Installing AIX Documentation in AIX Version 4.3 Installation Guide.

Note: In AIX Versions 4.3.0 to 4.3.2 the service was called the Documentation Search Service. In AIX Version 4.3.3, it was renamed to the Documentation Library Service to reflect its broader functionality.

The following main topics are covered in this chapter:

• Viewing the Current Configuration
• Changing a Client Computer's Default Remote Documentation Server
• Selecting the Documentation Server for a Single user
• Converting a Client System to a Documentation Server System
• Disabling or Uninstalling the Documentation Library Service
• Converting a Standalone Documentation Server into a Public Documentation Server
• Changing the Default Browser
• Changing the Web Server Software on a Documentation Server
• Changing the Documentation Language

Viewing the Current Configuration

This process shows the default system documentation server settings. If users have specified different settings in the .profile file in their home directories, they will not be affected by the default settings.

You can view the configuration of the documentation library service by using either of the AIX system management tools:

Using Web-based System Manager :

1. Change to the root user.

2. At the command line, type:

   wsm system

   then press Enter.

3. In the System Environments window, double-click on Internet Environments.

4. 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 that displays the library application.

   The Documentation Server configuration page shows the current settings for the documentation server for this computer.

Using SMIT:

1. Change to the root user.

2. At the command line, type:

   smit web_configure
   

   then press Enter.

3. From the web configuration menu, select Show Documentation and Search Server to display the current configuration information.

Changing a Client Computer's Default Remote Documentation Library Service

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

You can view the configuration of the documentation library service by using either of the AIX system management tools:

Using Web-based System Manager :

1. Change to the root user.

2. At the command line, type:

   wsm system
   

   then press Enter. This opens the System Environments container.

3. In the System Environments window, double-click on the Internet Environments icon to open it, then click on the Documentation Server tab.

4. Click on the Remote server radio button, then type the name of the documentation server computer in Computer name. This is the server computer that contains the documents that you want this client computer to be able to access and search.

5. In Server port, at the bottom, type the port number the web server software is using. The most commonly used port is 80,. An exception is the Lite NetQuestion web server, which must use port 49213. Your client computer will now be reconfigured to use the new server.

Using SMIT:

1. Change to the root user.

2. On a command line, type:

   smit web_configure
   

   then press Enter.

3. From the web configuration screen, select Change Documentation and Search Server. From the List, select Remote computer.

4. In NAME of remote documentation server, type the name or IP address of the new server and the appropriate port number. When the output pane shows the message Documentation server configuration completed., the reconfiguration is finished.

Selecting the Documentation Search Server for a Single User

All users on a computer do not have to use the same documentation 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 specify the documentation server they want to use:

• Changing the personal default documentation server
• Manually going to a documentation server

Changing the Personal Default Documentation Server:

A user's default documentation server is the documentation server that will be used when he or she starts the Documentation Library Service. System administrators set up a default server for all users logged into a system. A user who does not want to use the default documentation server can specify a different personal default documentation server.

To specify their own personal default documentation server, users can do the following:

1. Insert the following two lines in the .profile file in their home directory:

             export 
   
   DOCUMENT_SERVER_MACHINE_NAME=<servername>
   
             export 
   
   DOCUMENT_SERVER_PORT=<portnumber>
   

2. Replace <servername>with the name of the documentation search server computer they want to use.

3. Replace <portnumber> with the number of the port that the web server on the server uses. In most cases this will be 80. An exception is the Lite NetQuestion web server, which must use port 49213.

4. Log out, then log back in to activate the changes.

Once these two lines are placed in the .profile file in their home directory, changes that the system administrator makes to the system-wide default settings will not affect these users. If these users want to resume using the system-wide default server, they can remove the above two lines from their profile, log out, then log back in.

Manually Going to a Documentation Server:

When users don't want to change their default documentation server, but want to use the documents on another documentation server, they can type the following into the URL location field of his browser:

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

This opens into their browser the library application from the document server with the server_name given in the URL. The <port_number> only needs to be entered if the port is different from 80. (80 is the standard port number for most webservers; an exception is the Lite NetQuestion web server which uses port 49213).

For example, if a user wants to search the documents on a document server named hinson, and the web server on hinson uses the standard port 80, the user can enter this URL:

http://hinson/cgi-bin/ds_form

A library application would open in the user's browser to display the documents registered on the server hinson. Once the library application from a document server appears in the user's browser, the user can create a bookmark that goes 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.

Converting a Client System to a Documentation Server System

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

See the Installing and Configuring the Documentation Library Service and Installing AIX Documentation in AIX Version 4.3 Installation Guide for instructions for installing and configuring a documentation service. Choose the procedures that configure a system as a documentation server.

Disabling or Uninstall the Documentation Library Service

You can disable a server temporarily, or uninstall it permanently.

Temporarily Disabling a Server:

There are several different techniques:

• On the documentation sever, turn off the web server software or turn off the web server access permissions for all or some users.

  Note: If you are using the Lite NetQuestion web server software, it is automatically restarted each time you reboot the computer. To turn off the Lite NetQuestion web server until the next reboot, kill the process named "httpdlite". To prevent the web server software from being automatically restarted each time the computer reboots, edit the file /etc/inittab and remove or comment out this line:

  httpdlite:2:once:/usr/IMNSearch/httpdlite -r  
  
  /etc/IMNSearch/httpdlite/httpdlite.conf>/dev/console 2>&1
  

  To restore automatic startup of the lite server, reinsert or uncomment the above line in /etc/inittab.

  To manually start the Lite NetQuestion server, type the following command (there is a single space before and after the "-r"):

  /usr/IMNSearch/httpdlite/httpdlite -r /etc/IMNSearch/httpdlite/httpdlite.conf
  

• To disable the library service, but leave the web server functioning, go to the CGI directory of the web server. Find the file names ds_form, ds_form2, ds_rslt, and ds_rslt2 (the last two files only exist in 4.3.0 to 4.3.2). Turn off these files' execution permissions. This turns off access to all the documentation library service functions. An error message will display whenever users try to access the library service on this documentation server.

• To disable just the searching of a specific index without removing the documents or index it from the documentation sever, unregister the index.

If you think you might ever want to re-register the index, you must record the index's registry information before you remove it. To delete an index:

1. Login as the root user or library administrator.

2. Type the following command at a command line:

   /usr/IMNSearch/cli/imndomap /var/docsearch/indexes -l <index_name>
   

   where <index_name> is replaced with the name of the index.

3. Write down the index name, document path, and title.

4. Type the following command to delete the index:

   /usr/IMNSearch/cli/imndomap /var/docsearch/indexes -d <index_name>
   

5. Type the following command to complete the deletion:

   cp /var/docsearch/indexes/imnmap.dat /usr/docsearch/indexes/imnmap.dat
   

If you ever want to re-register this same index:

1. Login as the root user or library administrator.

2. Type the following command at a command line:

   /usr/IMNSearch/cli/imndomap /var/docsearch/indexes -c <index_name>
   
   <document path> "<title>"
   

   where you insert the index name, document path, and title values you recorded above in step 2.

Permanently Uninstalling:

If you are sure you want to permanently remove the documentation library service 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 library service package (bos.docsearch). 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 documentation service search engine (IMNSearch package).  Uninstall both IMNSearch.bld (NetQuestion Index Buildtime ), and IMNSearch.rte (NetQuestion Search Runtime).

3. Uninstall the web server software if it is not being used for some other purpose.

   Note: If you are using the Lite NetQuestion web server software, you can remove it by uninstalling the fileset IMNSearch.rte.httpdlite (NetQuestion Local HTTP Daemon).

4. Uninstall the documentation and indexes.

   Note: The operating system documents can be read directly from the documentation CDs by opening the readme file in the top directory of the CDs. However, the search functions will not work.

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

1. Login as the root user or a search administrator.

2. At the command line, type 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 server functions should now be disabled. If the users of this computer were using this computer as their documentation server, you should go into SMIT and change the name of the default documentation server to another computer. See Changing a Client Computer's Default Remote Documentation Library Server.

Converting a Standalone Documentation Server into a Public Documentation Remote Server

The difference between a stand alone documentation 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 software'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.

Note: If you are using the Lite NetQuestion web server software for your standalone documentation server, you must replace the lite server with a more full-functioned web server software package that can serve remote users. The lite web server can only serve local users. After you install the new server you must reconfigure the documentation service to use the new server. For more instructions on reconfiguration, see the section Change the Web Server Software on A Documentation Server.

Changing the Default Browser

This procedure changes the default browser that is used by applications that use the defaultbrowser command to open a browser window. The default browser is the browser that is launched when users use the docsearch command or the Documentation Library icon on the Help subpanel in the CDE desktop. You can change 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 the root user on the client computer.

2. On a command line, type:

   wsm system

   to open the System Environments container.

3. In the System Environments window, double-click on the Internet Environments icon to open it.

4. In the notebook dialog, click on the Default Browser tab if it isn't already the front page.

5. In the field, type 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 type wonderbrowser -u http://www.ibm.com at a command line to open your wonderbrowser with the www.ibm.com page open inside, you would type wonderbrowser -u into this field. Many browsers (for example, Netscape) do not require a flag.

6. Click OK. You can now close Web-based System Manager. The browser change will take effect the next time users log back into the compute

Using SMIT:

1. Change to root user.

2. On a command line, type:

   smit web_configure

3. From the web configuration screen, select Change/Show Default Browser. On the next screen, type in the field the command that launches your new web browser. 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. The browser change will take effect the next time users log back into the computer.

Changing 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. For instructions see Install the Web Server Software in the AIX Version 4.3 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 going to use the Lite NetQuestion web server or the IBM HTTP Webserver, and you installed them in their 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.

   If your computer is going to serve documents to remote users, 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. Note: If you are using the Lite NetQuestion web server software you do not need to do this step since the lite server can only be used for standalone documents serves. It does not support access by remote users.

4. Reconfigure the documentation library service to use the new web server by using either of the AIX system management tools, Web-based System Manager or SMIT.

Using Web-based System Manager:

1. Change to the root user.

2. On the command line, type:

   wsm system

   to open the System Environments container.

3. In the System Environments window, double-click on the Internet Environments icon to open it.

4. In the notebook dialog, click on the Documentation Server tab. On this page, the Local server radio button should already be selected.

5. 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 your web server software is listed by name, but you installed it 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.

6. 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.

7. In the Server port field at the bottom, type the port number the web server software is using. The standard default port is 80, ; an exception is the Lite NetQuestion server which must use port 49213.

8. Click OK. The documentation service on this computer will now be reconfigured to use the new webserver software. Any users who were logged in when configuration was done must log out, and then log back in to reactivate the library service.

Using SMIT:

1. Change to the root user.

2. On the command line, type:

   smit web_configure

4. From the web configuration screen, select Change Documentation and Search Server.

5. In the Documentation and Search Server dialog, select local - this computer for server location. From the Web Server Software screen, select List, then choose the web server software you are using.

6. Enter the full pathnames of the directories and choose the appropriate port number. The standard default port is 80; an exception is the Lite NetQuestion server which must use port 49213. 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 reactivate the library service.

Changing the Documentation Language

By default, if a user opens the library using the docsearch command, the Documentation Library icon in the CDE desktop, or the AIX Base Library icon, the library application displays in the same language as the current locale of the user's client computer. However, there may be reasons that users want to see the documentation in a language other than their 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 do 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.

Note: Before a computer can serve documents in a language, the AIX locale (language environment) for that language, and the library service messages for the language must be installed on the documentation server. For instructions on installing languages, see the section on installing languages in the Documentation Library Service chapter in the operating system Installation Guide.

Changing the Default Documentation Language for All Users

To change the default documentation language for all users on a computer, the system administrator (as root) can use the Web-based System Manager or SMIT.

Using Web-based System Manager:

1. Change to the root user.

2. On the command line, type:

   wsm system

   to open the System Environments container.

3. In the System Environments window, double-click on the Internet Environments icon to open it.

4. In the notebook dialog, click on the Documentation Server tab.

5. Scroll down until you see the Default Documentation Language field, then select your new language.

6. Click OK. The documentation service on this computer will now be reconfigured to use the new language default. Any users who were logged in when configuration was done must log out, and then log back in to reactivate the library service with the new default language.

Using SMIT:

1. Change to root user.

2. At the command line, type:

   smit web_configure

   then press Enter.

3. From the web configuration screen, select the Change/Show Documentation Language choice.

4. In the Language dialog, select the new language. The documentation service on this computer will now be reconfigured to use the new language default. Any users who were logged in when configuration was done must log out, and then log back in to reactivate the library service with the new default language.

To Change Documentation Language for a Single User

A system administrator may assign a single user a documentation language that is different than the default language of the user's computer. This is done by running (as root) the following command:

/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, to change the documentation language of user <fred> to be Spanish(es_ES), you can type the following command:

/usr/bin/chdoclang -u fred es_ES

Note: If the DOC_LANG environment variable is defined in a user's .profile, it takes precedence over any global DOC_LANG setting in the /etc/environment file on the user's computer. Also, for the 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 a user's documentation language takes effect the next time the user logs out and then logs back in.

To Remove a Documentation Language Setting

If the documentation language has been set, you can delete the 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 the following command:

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

For example, to remove the user fred's personal language setting to use the system default language, run the following command:

/usr/bin/chdoclang -d fred