Documents and Indexes

This section covers system management operations on documents and indexes for the documentation search service:

• Registering Documents for Online Searching
• Deleting or Uninstalling Documents
• Updating Documents
• Moving Documents
• Security

Registering Documents for Online Searching

Not all documents on a documentation server can be searched. Two things must occur before a document can be searched using the Documentation Search Service:

• An index of the document must be created on the server, and

• The index must be registered with the search service.

Documents are registered in two ways:

• If an application ships pre-built indexes for its documents, the indexes may be automatically registered when they are installed on your system, or

• A system administrator may manually create indexes for documents that are already on the server and then manually register the indexes.

To create an index, you will complete the following steps. When you are ready to create the index, see the chapter Documentation Search Service in the AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs book for more information.

1. Write your document in HTML.

2. Create the index.

3. If you are an application developer who is creating this index for inclusion in an installp package, your next step is to go to the Documentation Search Service section in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs. Follow the steps to include the index in your installation package and do automatic registration of your indexes during your package's post-installation process.

   If you are the system administrator of a documentation server, the next step is to register the new indexes on the server.

4. Register the index.

   After your indexes are registered, they will appear for searching in the global Documentation Search Service search form that is launched by typing the docsearch command or by opening the Documentation Search Service icon in the CDE Desktop. You can also create your own custom search form that only shows a subset of all registered indexes. For instructions, read the section on creating your own search forms in the Documentation Search Service chapter in the AIX 4.3 General Programming Concepts book.

   For detailed instructions on creating and registering an index, see the chapter Documentation Search Service in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs for more information.

Deleting or Uninstalling Documents

If a document and its index were automatically registered when an application was installed on the server, you must use the uninstall process to remove the document. If you simply delete a registered document or its index, it will still be registered with the search service. This will generate error messages during searches since the search service will still try to search the missing index.

If you want to delete a document that was manually registered by the system administrator, you must first unregister it with the search service.

To unregister an index:

1. Change to root or to a user who is a member of the imnadm group.
2. At the command line, type the following lines, pressing Enter after each. Replace <index_name> with the name of the index you want to unregister.

      /usr/IMNSearch/cli/imnixdel <index_name>
   
      
      /usr/IMNSearch/cli/imndomap /var/docsearch/indexes -d <index_name>
   
      
      cp /var/docsearch/indexes/imnmap.dat /usr/docsearch/indexes

3. Now you can safely delete the document and its index.

Updating Documents

If a document's contents change, the index of the document must be updated to reflect the changes to the contents of the document.

If you are installing an updated application and it automatically registers its documents, it should automatically update the old indexes with the new ones.

If you are updating a document that another user created, you will have to manually update the index for the document.

1. Unregister the index. Type:
   

   /usr/IMNSearch/cli/imndomap /var/docsearch/indexes -d <index name>
   cp /var/docsearch/indexes/imnmap.dat /usr/docsearch/indexes

2. Delete the index. Type:
   

   /usr/IMNSearch/cli/imnixdel <index name>

3. Re-build the index. See Building an Index in the chapter Documentation Search Service in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs for more information.

Moving Documents

You should not move application documents that were automatically installed with an application. For example, you should not move AIX documentation after it is installed. If you move automatically registered documents, the search service will not be able to find the documents and error messages will occur.

However, you can move documents that you manually indexed and registered. To move a document that is already registered, change to root, or a user who is a member of the imnadm group. Then do the following:

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 and title.

3. Now update the index with a new document location, type:

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

   where you insert the values found in step 2 and replace <document path> with the new location of the document.

Security

You should follow your normal security procedures for the documents on the documentation server.In addition, a documentation server also has the added security elements of the document indexes and the webserver software.

Indexes should be treated as files that include a list of all the words in the original documents. If the documents contain confidential information, then the indexes themselves should be treated with the same care as the documents.

There are three levels of security you can set up for indexes:

1. No Restrictions.

   By default, the permissions on the indexes directory are set so that all webserver users can both search and read all index files.

2. Search, but not read.

   All webserver users can search inside indexes for key words, but cannot open an index file to directly read its contents. This makes it more difficult for users to obtain confidential data, but a person can sometimes still gain a lot of information just by knowing if certain key words are inside a document. Assuming you store all your indexes in the standard location, this state is set up by setting the permissions of the /usr/docsearch/indexes directory. It is set to the user:group imnadm:imnadm with all permissions for others disabled so that only members of the imnadm search administration group can read the index files. To set these permissions type the following two commands:

   chown -R imnadm:imnadm /usr/docsearch/indexes
   chmod -R o-rwx /usr/docsearch/indexes

   Note: The user imnadm must always be able to read and execute the directory where you store indexes. This is because the search engine runs as user imnadm when it searches inside indexes.

3. No search, no read.

   This is done by setting the permissions as in level two above (this prevents reading of index files). In addition, a user's permission to use the search service webserver is disabled (this prevents searches). The user will be unable to search indexes because the webserver will not let them open the search form. This security level is set up using the administration functions in your webserver software to turn off a user's permission to use the webserver. Consult the documentation that came with your webserver to determine how to configure your webserver software to prevent access by specific users.