Chapter 3 Administering an AnswerBook2 Server

Administering AnswerBook2 software consists of performing the following functions, each of which includes specific tasks:

• "Administering the Documentation Server"

• "Starting and Stopping the Documentation Server"

• "Turning On or Off Document Source Debugging"

• "Controlling Administrative Access"

• "Working with Document Collections"

• "Viewing Documentation Server Configuration"

• "Working with Other Documentation Servers"

• "Working With Server Reports"

• "Administration Page Icons"

Administering the Documentation Server

The AnswerBook2 software provides a web-browser interface (the Admin GUI) and a command-line interface (ab2admin) that you can use to administer the documentation server. Most functions are available in either interface.

To access the main page of the Admin GUI, select AnswerBook2 Administration from the Options Page of the AnswerBook2 browser, or, if you are running CDE, select AnswerBook2 Admin from the System_Admin applications window. All pages in the Admin GUI include a standard set of icons across the top of the screen.

To access the command-line interface, use the command: /usr/lib/ab2/bin/ab2admin. For detailed information about the command-line interface, see the ab2admin(1m) man page.

Only authorized administrative users can access the administrative functions. For more information, see "Controlling Administrative Access".

Starting and Stopping the Documentation Server

When you boot the system on which the documentation server is running, the server is started automatically (through the /etc/init.d/ab2mgr script). You can also manually start, stop, and restart the documentation server when needed. For example, you must restart the documentation server after you install a new document collection.

To perform these functions, log in as root on the documentation server machine and use the ab2admin command-line interface.

• To start the documentation server, use the following command:

  # /usr/lib/ab2/bin/ab2admin -o start

• To stop the documentation server, use the following command:

  # /usr/lib/ab2/bin/ab2admin -o stop

• To restart the documentation server, use the following command:

  # /usr/lib/ab2/bin/ab2admin -o restart

  If restarting the server does not supply the expected behavior, stop and start the server.

• To start the documentation server with debugging enabled, use the following form of the start-up command:

  # /usr/lib/ab2/bin/ab2admin -o start -D

Turning On or Off Document Source Debugging

The AnswerBook2 server has a debugging option that, when enabled, displays unrecognized markup in the book source in red with the word "BUG" in the viewer. This function helps to identify problems if a book does not display as expected.

To turn on debugging, log in as root to the documentation server's system and set the environment variable AB2_DEBUG to 1. For example:

% su -
# setenv AB2_DEBUG 1

To turn off debugging, log in as root to the documentation server's system and set the environment variable AB2_DEBUG to 0. For example:

% su -
# setenv AB2_DEBUG 0

After you change the debugging parameter, you must restart the documentation server. To restart the documentation server, type:

# /usr/lib/ab2/bin/ab2admin -o restart

To control debugging when you start up the server, use the following form of the start-up command:

# /usr/lib/ab2/bin/ab2admin -o start -D

Controlling Administrative Access

An administrative user is a user specifically defined for performing document administrative functions. The AnswerBook2 product uses passwords to verify that a given administrator is allowed to perform administrative functions on the server.

Setting Up Initial Administrative Access

The AnswerBook2 software comes with access control turned on for performing administrative functions, but with no default administrative user defined. The first time you attempt to access the AnswerBook2 administrative functions, the software informs you that access control is turned on but no user is defined. You can do one of two things at this point:

• Turn off access control.

  To turn off access control, log in as root on the documentation server machine and type the following:

  # /usr/lib/ab2/bin/ab2admin -o auth_off

  ---

  Caution -

  If you turn off access control, any user who can get to your documentation server can modify your documentation server.

  ---

• Define an administrative user and password.

  To define an administrative user, log in as root on the documentation server machine and type the following:

  # /usr/lib/ab2/bin/ab2admin -o add_admin -u admin-id

  Where admin-id is the login ID for administering this documentation server. The admin-id does not have to match the user's system login ID; it is solely a login ID for performing document-related administrative functions on a specific server.

  The software prompts you to enter a password for this user, then re-enter it for verification.

Adding Access for AnswerBook2 Administrators

To add an administrative user, select Add Administrator from the Admin GUI. To add the administrative user:

1. Type the administrator's login ID in the Administrator ID field.

   The login ID does not have to match the user's system login ID; it is solely a login ID for performing document-related administrative functions on a specific server.

2. Type in a password for the administrator.

   This password is stored in an AnswerBook2 password database. It does not have to match the user's system password.

You need to enter the password twice for verification.

You can also use the following command to perform this function:

% /usr/lib/ab2/bin/ab2admin -o add_admin -u admin-id [-m server_name] [-p server_port]

Changing the Password for an Administrator

To change an administrator's password, select Change Password from the Admin GUI. To modify the password:

1. Select the administrative user from the Administrator ID pop-up list.

2. Type the administrator's existing password in the Old Password field.

3. Type the administrator's new password in the New Password field.

4. Type the administrator's new password a second time in the Re-enter New Password field.

5. Click Change Password to apply this change.

When you click Change Password, the AnswerBook2 software checks to see that the data entered in the New Password and Re-enter New Password fields agree. If they do, the new password is stored in the database. If they do not, the software displays an error.

You can also use the following command to perform this function:

% /usr/lib/ab2/bin/ab2admin -o change_password -u admin-id [-m server_name] [-p server_port]

Removing Access for an Administrator

To remove a user from the list of administrative users:

1. Click on the checkbox next to the administrator's login ID that you want to remove from the List of Administrators.

   This is the administrator's ID, not necessarily the person's system or user ID.

2. Click on Delete Administrator.

   ---

   Note -

   This has no effect on the person's ability to access AnswerBook2 documents as a user. It only removes the person's ability to perform administrative functions.

   ---

You can also use the following command to perform this function:

% /usr/lib/ab2/bin/ab2admin -o del_admin -u admin-id [-m server_name] [-p server_port]

Working with Document Collections

An AnswerBook2 collection is a logical grouping of books. For example, you might have a collection that contains all Solaris^TM developer-oriented books. This collection can be an AnswerBook2 (SGML) collection or an AnswerBook1 (Display PostScript^TM) collection.

Listing Collections

To see a list of all collections installed on your server, select View List of Available Collections from the Admin GUI. This list includes AnswerBook1 collections and AnswerBook2 collections.

You can also use the following command to perform this function:

% /usr/lib/ab2/bin/ab2admin -o list [-m server_name] [-p server_port]

Adding New Collections

To add a collection to the server's database, select Add Collection to List from the Admin GUI. This function assumes the collection already exists as an installed package on the server's system or some other system to which the server has access. If the collection is not yet installed, use pkgadd to add the collection first, then use this function. For new collections (those that are on the Solaris 7 Documentation CD, for example), if you run the pkgadd command on the server, it adds the collections to the server's list automatically.

Perform the following steps to install the collection:

1. Enter a valid path to the collection file in the Path to Collection field.

   For example, /opt/answerbooks/english/solaris_2.7/SUNWababe/collinfo. The path must point to a directory that contains either a collinfo file for an AnswerBook2 collection or an ab_cardcatalog file for an AnswerBook1 collection.

2. Click on Add Collection.

You can also use the following command to perform this function:

% /usr/lib/ab2/bin/ab2admin -o add_coll -d path_to_collection

After you install a collection, you must restart the documentation server. To restart the documentation server, click Restart on the Admin GUI's status page or type the following from the command line:

# /usr/lib/ab2/bin/ab2admin -o restart

Adding Existing Collections

The AnswerBook2 server can scan your current system to find locally installed AnswerBook1 and AnswerBook2 collections and add them to the server's database. To have the server perform this function for you, select Scan for Locally Installed Collections from the Admin GUI. This function creates and displays a list of all valid document collections it finds on the local system.

To add a collection to the server's database:

1. Click on the checkbox next to the collection you want to add.

2. When you have selected all the collections you want, click on Add Selected Collections.

Collections that do not have a checkbox next to them are already in the database.

If the list does not include document collections that are installed on a local mount point, verify that the directory into which the collections were installed has read access set for others.

You can also use the following command to perform this function:

% /usr/lib/ab2/bin/ab2admin -o scan

The command line scanning function adds all the collections it finds; it does not allow you to choose which collections to add.

After you install a collection, you must restart the documentation server. To restart the documentation server, click Restart on the Admin GUI's status page or type the following from the command line:

# /usr/lib/ab2/bin/ab2admin -o restart

Removing AnswerBook2 Collections

To remove an AnswerBook2 or AnswerBook1 collection from the server's database, select Delete Collection from List from the Admin GUI. To remove the collection:

1. Select the checkbox next to the title(s) of the collection(s) you want to remove from the Collection List. To deselect a selected item, click the checkbox again.

2. After you have selected all the collections you want removed, click on Delete Collection.

You can also use the following command to perform this function:

% /usr/lib/ab2/bin/ab2admin -o del_coll -t collection_title

These functions do not remove the collection packages from the system; they only remove the entry for the collection from the server's database. To remove the packages from the system use the pkgrm utility.

After you remove a collection, you must restart the documentation server. To restart the documentation server, click Restart on the Admin GUI's status page or type the following from the command line:

# /usr/lib/ab2/bin/ab2admin -o restart

Configuring the Documentation Server

To view the current server configuration, select View Current Configuration from the Admin GUI. To change these settings, select Modify Server Configuration from the Admin GUI.

Viewing Documentation Server Configuration

The View Current Configuration page lists the settings shown in Table 3-1 and Table 3-2. These settings are stored in the server_config_path/dwhttpd.cfg file (which defaults to /usr/lib/ab2/dweb/data/config/dwhttpd.cfg).

If you are running a CGI-based server rather than the default NSAPI-based server, only some server configuration options are visible in the Admin GUI's interface. For more information, see "Configuration Issues when Running the Server as a CGI Process".

The document administrator should not manually change the settings shown in Table 3-2. The system configures these settings when you install the server software.

You can also use the following command to view the current server configuration:

% /usr/lib/ab2/bin/ab2admin -o view_config [-m server_name] [-p server_port]

Changing Documentation Server Configuration

When you install the AnswerBook2 server software, certain variables are set to default values. Use the fields on the Modify Server Configuration page to change these values. You can change the following server settings:

• Server name -- When you install the documentation server, AnswerBook2 automatically sets this variable to the current host name (for example, cats). If you want anyone outside of your domain to access documents on this server, change the name to a fully qualified name (for example, cats.house.pets.com ).

• Server port number -- To use a port other than 8888 for the AnswerBook2 server, enter the port number in this field. To use a port number below 1024, you need to perform some additional steps. For more information, see "Using a Port Number Less Than 1024".

• Maximum threads -- This is the maximum number of concurrent AnswerBook1 searches the server will perform. If you have lots of AnswerBook1 collections and people search them frequently, you might want to increase this number. If you increase this number, however, it might slow your server's response time.

• Maximum server requests -- This tells the server how often to perform "housekeeping" activities and restart itself. The number indicates the number of http requests to the server.

• Access log file -- Click the appropriate item to turn on or turn off access logging. If you anticipate many users accessing your documentation server, you might want to periodically save and restart this log file. For more information about rotating the access log file, see "Rotating Log Files".

• Error log file -- Click the appropriate item to turn on or turn off error logging. If you experience large numbers of server errors, you might need to periodically save and restart this log file. For more information about rotating the error log file, see "Rotating Log Files".

• Administration access control -- Click the appropriate item to turn on or turn off administrative access control. When access control is turned on, only those users who have administrative access defined can perform administrative functions for this server.

These functions are also available through the administration command-line interface (ab2admin). For detailed information about the command-line interface, see the ab2admin(1m) man page. You can also edit the server_config_path/dwhttpd.cfg file (which defaults to /usr/lib/ab2/dweb/data/config/dwhttpd.cfg) to change these values.

If you change any of these values, you must stop and start the documentation server. Log in as root on the server machine and type the following commands:

# /usr/lib/ab2/bin/ab2admin -o stop
# /usr/lib/ab2/bin/ab2admin -o start

Using a Port Number Less Than 1024

Port numbers below 1024 are reserved for system use. To use one of these numbers (for example, port number 80) for the AnswerBook2 server, perform the following steps:

1. Either use the Modify Configuration Settings function in the Admin GUI or edit the /usr/lib/ab2/dweb/data/config/dwhttpd.cfg file and change the following line:

   set ServerPort 8888

   To this:

   set ServerPort 80

2. Edit the /usr/lib/ab2/dweb/data/config/nsapi.cfg file and change the following line:

   set ServerPort 8888

   To this:

   set ServerPort 80

3. Edit the /etc/init.d/ab2mgr file and change the following line:

   su daemon -c "LD_PRELOAD=$pre_load;LANG=$LNG;AB2_ORIG_LANG=$ORGLNG;LD_LIBRARY_PATH=$LD_LIBP;EBT_REGISTRY=$ER;export LD_PRELOAD LD_LIBRARY_PATH LANG AB2_ORIG_LANG LC_ALL EBT_REGISTRY; $AB2BIN/dwhttpd $AB2CFG > /dev/null"

   To this:

   su root -c "LD_PRELOAD=$pre_load;LANG=$LNG;AB2_ORIG_LANG=$ORGLNG;LD_LIBRARY_PATH=$LD_LIBP;EBT_REGISTRY=$ER;export LD_PRELOAD LD_LIBRARY_PATH LANG AB2_ORIG_LANG LC_ALL EBT_REGISTRY; $AB2BIN/dwhttpd $AB2CFG > /dev/null"

   This allows the parent dwhttpd process to run as root, which can then use port 80. Note that the child dwhttpd process still runs as daemon.

Configuration Issues when Running the Server as a CGI Process

Because the AnswerBook2 server follows standard web protocols, you can run the AnswerBook2 server as a CGI process on an existing server, rather than as the default NSAPI server. For information on how to configure your server to run this way, see "Running the AnswerBook2 Documentation Server as a CGI Process".

If you run your documentation server as a CGI process, the following configuration settings will not display on the View Configuration Settings page of the Admin GUI:

• Maximum Threads

• Maximum Server Request

• Server Configuration Path

• Server User

• Plug-in File

• Mime File

• Doc Root

• Log Directory

The only option available on the Modify Server Configuration page will be turning on or turning off access control. All other functions will not display.

The following options for the ab2admin command will not work:

• -o access_on

• -o access_off

• -o error_off

• -o error_on

• -o modify_server_name

• -o modify_server_port

Working with Other Documentation Servers

When a user clicks on a link in a book, the AnswerBook2 server can follow that link to another AnswerBook2 server. If the book exists on the current documentation server, the link goes there. If, however, the book being linked to is not located on the current server, the AnswerBook2 server "falls through" to any alternate documentation servers defined for it to access. You can use this capability to distribute documents across various servers or to create a backup of the documents.

Identifying Alternate Documentation Servers

To see what alternate servers are defined, select View List of Alternate Servers from the Admin GUI. This displays a list of servers currently identified as "fall-through" servers. If a user clicks on a link in a book and that book is not located on the current server, the AnswerBook2 product examines the servers in this list to find the target for the link. The AnswerBook2 server comes with a pre-defined alternate server of http://docs.sun.com, which is Sun's master documentation server and contains released Sun documentation.

For each alternate server defined for the current server, this page shows the name of the server, its port number, and a link to the list of collections installed on that server. When you click on show list of collections, you are prompted for administrative ID and password for the alternate server (if administrative access control is defined for the alternate server). In other words, you can add an alternate server without having administrative access to it, but you can only view the list of collections on the alternate server if you have administrative access to it.

There is no command line option to perform this function.

Adding Alternate Documentation Servers

To enable your current server to access books located on another server (for the purpose of following links between books), select Add Alternate Server from the Admin GUI.

1. Enter the alternate server's name in the AnswerBook2 Server Name field.

2. Enter the alternate server's AnswerBook2 port number in the Server Port Number field. If you are unsure of the port number, try 8888 (the AnswerBook2 default port number).

3. Click on Add Server.

You can also use the following command to perform this function:

% /usr/lib/ab2/bin/ab2admin -o add_server -M add_server_name -P add_server_port 
[-m server_name] [-p server_port]

Removing Additional Documentation Servers

To remove a server from your server's list of alternate servers, select Delete Alternate Server from the Admin GUI.

1. Select the server from the Server List.

2. Click on Delete Server.

This removes the server from the list of alternate servers for the local documentation server. This does not stop the removed server from functioning as a documentation server.

You can also use the following command to perform this function:

% /usr/lib/ab2/bin/ab2admin -o del_server -M del_server_name -P del_server_port 
[-m server_name] [-p server_port]

Modifying Alternate Server Order

When you add an alternate server to the list of servers your server can use, the alternate server is added to the bottom of the server order. This order determines the sequence in which your server accesses alternate servers to follow document links. If a user requests a given document from the library and that document is not available from the default server, the server goes through the alternate server list in the defined sequence to find the document.

To change the order of the servers available to your system, select Modify Server Order from the Admin GUI.

1. Select a server from the List of Servers.

2. Click on Move Up in List or Move Down in List.

There is no command line option to perform this function.

Working With Server Reports

The AnswerBook2 server software maintains logs that show server errors and server access. In addition, it provides a summary report that displays how often document collections are being accessed and how many errors occur.

Book Access Summary Report

To see a summary of access to the books on the server, select View Book Access Summary from the Admin GUI. The book access report summarizes how often each book on the server has been accessed. For each book on the server, it displays the following:

• Book title -- The book's title as it appears on the Library Page

• Book short name -- The short name for the book as identified in the book's configuration file

• Collection name -- The short name of the collection to which the book belongs, as identified in the collinfo file

• Hits -- Number of times the book has been accessed

• Errors -- Number of errors associated with the book

Access Log Files

To turn on or turn off access logging, select Modify Server Configuration from the Admin GUI.

• To have information about who is accessing information on the documentation server written into the access log file, click on the button next to on, then click Apply. The default location for this file is /var/log/ab2/logs/access-8888.log.

• To stop having information written into the access log file, click on the button next to off, then click Apply.

You can also use the following commands to perform these functions:

% /usr/lib/ab2/bin/ab2admin -o access_on [-m server_name] [-p server_port]
 

% /usr/lib/ab2/bin/ab2admin -o access_off [-m server_name] [-p server_port]
 

After you change the logging function, you must stop and start the documentation server. Log in as root on the server machine and type the following commands:

# /usr/lib/ab2/bin/ab2admin -o stop
# /usr/lib/ab2/bin/ab2admin -o start

Viewing the Access Log

To view the access log file, select View Log Files from the Admin GUI, then click on View Access Log File. The access log file is a text file that lists every access made to the documentation server. Each line in the access log looks similar to the following:

129.146.83.55 - - [04/Nov/1996:15:07:05 -0800]
"GET /icons/ab2_curr_home.gif HTTP/1.0" 200 1938

Where:

• The first set of numbers is the IP (Internet Protocol) address of the client. For example, 129.146.83.55.

• The information between the square brackets is the date and time of the access. For example, [04/Nov/1996:15:07:05 -0800] .

• The information between the double quotes tells you what access occurred. This typically identifies a URL or file name as well as the protocol used to respond to the access request. For example, "GET /icons/ab2_curr_home.gif HTTP/1.0" tells you that the access was to get the file /icons/ab2_curr_home.gif using the HTTP 1.0 protocol.

• The next-to-last number indicates whether the access was successful (200) or not (anything else).

• The last number indicates the size (in Kilobytes) of any information returned to the requestor. For example, 1938 is the size of the .gif file retrieved.

You can also use the following command to perform this function:

% /usr/lib/ab2/bin/ab2admin -o view_access [-m server_name] [-p server_port]

Error Log Files

To turn on or turn off error logging, select Modify Server Configuration from the Admin GUI.

• To have information about any errors that occur on the documentation server written into the error log file, click on the button next to on, then click on Apply. The default location for this file is /var/log/ab2/logs/errors-8888.log.

• To stop having information written into the error log file, click on the button next to off, then click on Apply.

You can also use the following commands to perform these functions:

% /usr/lib/ab2/bin/ab2admin -o error_on [-m server_name] [-p server_port]
 

% /usr/lib/ab2/bin/ab2admin -o error_off [-m server_name] [-p server_port]

After you change the logging function, you must stop and start the documentation server. Log in as root on the server machine and type the following commands:

# /usr/lib/ab2/bin/ab2admin -o stop
# /usr/lib/ab2/bin/ab2admin -o start

Viewing the Error Log

To view the error log file, select View Log Files from the Admin GUI, then click on View Error Log File. The error log file lists every error that occurred on this documentation server. You can use this information to determine the cause of server problems or unusual behaviors. These errors usually identify the server and port with which the error is associated, as well as some text that describes the error.

You can also use the following command to perform this function:

% /usr/lib/ab2/bin/ab2admin -o view_error [-m server_name] [-p server_port]

Rotating Log Files

The AnswerBook2 product allows you to save the current access or error log to a file and start logging information into an empty file.

• To rotate the error log, select Rotate Error Log File from the Admin GUI.

• To rotate the access log, select Rotate Access Log File from the Admin GUI.

When the Rotate Access (Error) Log File page appears:

1. Enter the file name to save to in the Save Log File field.

   The default value is current_date.current_log_file_name. Where current_date is of the form YearYearYearYear_MonthMonth_DayDay_HourHour and current_log_file_name defaults to access-8888 or error-8888 (for example, 1997_02_26_14.access-8888.log).

   Note that the Log file location field shows you the path to where the file is saved. You cannot change this information on this page.

2. Click on Apply.

After you change the logging function, you must stop and start the documentation server. Log in as root on the server machine and type the following commands:

# /usr/lib/ab2/bin/ab2admin -o stop
# /usr/lib/ab2/bin/ab2admin -o start

You can also use the following commands to perform these functions:

% /usr/lib/ab2/bin/ab2admin -o rotate_error [-m server_name] [-p server_port]
 

% /usr/lib/ab2/bin/ab2admin -o rotate_access [-m server_name] [-p server_port]

Administration Page Icons

The following table identifies the icons displayed on administration pages.