System Management Guide:
Operating System and Devices

Changing the Configuration of the Documentation Library Service

This section 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 the Online Documentation in AIX 5L Version 5.2 Installation Guide and Reference.

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 are not affected by the default settings.

You can view the configuration of the documentation library service by using either of the system management tools (Web-based System Manager or SMIT).

Using Web-based System Manager

1. Change to the root user.
2. At the command line, type: wsm, then double-click on System Environment.
3. In the System Environments window, double-click on Settings.
4. When the contents are displayed, double-click on the Default Browser icon. This shows the current command that is used to launch the default browser that displays the library application.

   Double-click on the Documentation Server icon to view 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
3. From the Web Configuration menu, select Show Documentation and Search Server to display the current configuration information.

Changing the Default Remote Documentation Library Service of a Client Computer

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 system management tools (Web-based System Manager or SMIT).

Using Web-based System Manager

1. Change to the root user.
2. At the command line, type: wsm, then double-click on System Environment.

   This opens the System Environments container.

3. In the System Environments window, double-click on the Settings icon to open it, then double-click on Documentation Server.
4. Click on the Remote server host name radio button, then type the name of the documentation server computer in the field to the right. This is the server computer that contains the documents that you want this client computer to be able to access and search.
5. In the Server port field, type 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 the root user.
2. On a command line, type:  smit web_configure
3. From the web configuration screen, select Change Documentation and Search Server. From the List menu, 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. The reconfiguration is complete when the output window shows the message Documentation server configuration completed.

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 is 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 do not affect these users. If these users want to resume using the system-wide default server, they can remove the two lines inserted in step 1 from their profile, log out, then log back in.

Manually Going to a Documentation Server

When users do not 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 their 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 must use port 49213.)

In the following 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 the following 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 is displayed 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 Documentation in AIX 5L Version 5.2 Installation Guide and Reference for instructions for installing and configuring a documentation service. Choose the procedures that configure a system as a documentation server.

Disabling or Uninstalling the Documentation Library Service

Use one of the following procedures:

• Temporarily Disabling a Server
• Permanently Uninstalling a Server

Temporarily Disabling a Server

There are several different techniques:

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

  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 httpdlite process. To prevent the web server software from being automatically restarted each time the computer reboots, edit the /etc/inittab file and remove or comment out the following 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 same 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 flag):

  /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_rslt, and ds_print. Turn off these files' execution permissions. This turns off access to all the documentation library service functions. An error message is displayed whenever users try to access the library service on this documentation server.
• To disable the searching of a specific index without removing the documents or index from the documentation sever, unregister the index.
  Note
  To re-register the index, you must record the index 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/bin/itedomap -p /var/docsearch/indexes -l -x index_name

     where index_name is replaced with the name of the index.

  3. Write the index name, document path, and title.
  4. Type the following command to delete the index:

     /usr/IMNSearch/bin/itedomap -p /var/docsearch/indexes -d -x index_name

  If you ever want to re-register this same index, you must complete the following steps:

  1. Login as the root user or library administrator.
  2. Type the following command at a command line:

     /usr/IMNSearch/bin/itedomap -p /var/docsearch/indexes -c -x index_name -sp \
     	document path -ti "title"

     where you insert the index name, document path, and title values you recorded previously.

Permanently Uninstalling a Server

If you are sure you want to permanently remove the documentation library service functions, do the following:

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:

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, start SMIT and change the name of the default documentation server to another computer. See Changing the Default Remote Documentation Library Service of a Client Computer.

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.

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 system management tools, Web-based System Manager (see Using Web-based System Manager) or SMIT (see Using SMIT).

Using Web-based System Manager

1. Change to the root user on the client computer.
2. On a command line, type: wsm, then double-click on System Environment.

   to open the System Environments container.

3. In the System Environments window, double-click on the Settings icon to open it.
4. In Settings, double-click on the Default Browser icon.
5. In the Browser command 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, type wonderbrowser -u in 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 computer.

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 type:

   wonderbrowser -u http://www.ibm.com

   to open your wonderbrowser with the www.ibm.com page open inside, you would type wonderbrowser -u in 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 the following 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 5L Version 5.2 Installation Guide and Reference.
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 web server 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 web servers might 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 are 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 because the lite server can only be used for standalone documents services. 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 system management tools, Web-based System Manager (see Using Web-based System Manager) or SMIT (see Using SMIT).

Using Web-based System Manager

1. Change to the root user.
2. On the command line, type: wsm, then double-click on System Environments.
3. In the System Environments window, double-click on the Settings icon to open it.
4. Next, double-click on the Documentation Server icon. In this dialog, the This computer server radio button is already selected.
5. To the right of the heading Location of documents and CGI programs, 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 CGI and Documents directories. If you selected one of the default web server packages, skip to the next step.
7. In the Server port field, 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 is now reconfigured to use the new webserver software. Any users who were logged in when configuration was completed 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

3. From the Web Configuration screen, select Change Documentation and Search Server.
4. 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.
5. 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 now configures 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 Common Desktop Environment, or the 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 current default locale of the computer. The documentation language can be changed for all users on a computer, or it can be changed for a single user.

1. 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.
2. Before a computer can serve documents in a language, the locale (language environment) for that language and the library service messages for the language must be installed on the documentation server. For instructions, see Chapter 7. Installing and Configuring Documentation Library Service and Online Documentation in AIX 5L Version 5.2 Installation Guide and Reference.

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 (see Using Web-based System Manager:) or SMIT (see Using SMIT:).

Using Web-based System Manager:

1. Change to the root user.
2. On the command line, type: wsm, then double-click on System Environment.
3. In the System Environments window, double-click on the Settings icon to open it.
4. In the next view, double-click on the Documentation Server icon.
5. Scroll down until you see the Start Up Web Page language field, then select your new language.
6. Click OK. The documentation service on this computer is now 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

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 the computer is now 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 might assign a single user a documentation language that is different than the default language of the user's computer. This is done by running the following command as root:

/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 Language Support Table.

Running the command as described adds 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), type the following command:

/usr/bin/chdoclang -u fred es_ES

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 the following command as root:

/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