Installing and Administering an AnswerBook2 Server

Chapter 2 Installing Documentation Server Software

This section explains the requirements you must meet and decisions you should make before you install the AnswerBook2 server software.

Note -

To view online documentation as an AnswerBook2 client, no installation is required; you need to know the URL for a documentation server or, if you have Internet access, you can view released Solaris documentation at http://docs.sun.com.

Note -

There is no client-level access control for this product. If a client machine can access the URL for a documentation server, it can view the documents on that server.

This section contains the following information:

Before Installing Server Software

Before you start the installation process, verify that your system meets the requirements listed in "Hardware and Software Requirements" and decide where you want to install the software as explained in "Installation Choices".

Hardware and Software Requirements

Before you start the installation process, verify that the system(s) on which you plan to install AnswerBook2 server software meet the hardware and software requirements listed in Table 2-1 and Table 2-2.

Table 2-1 Hardware and Software Requirements


Component	Requirement
Documentation server system hardware	SPARCstation 2 or higher (SPARCstation 5 recommended) Intel-based personal computer
Operating environment	Solaris 7 (for SPARC or x86, as appropriate)
Admin GUI and AnswerBook2 client viewer	Any HTML 3.2-compliant browser, such as HotJava^TM, Netscape Navigator^TM, or Lynx

Table 2-2 Disk Space Requirements Table


Directory Path	Description	Space
`/usr/lib/ab2/`	Contains executable files, server processing files, library files, and graphics and document source files for the product interface	26.0 Megabytes
`/var/log/ab2/`	Contains catalog files and log files, if logging functions are enabled	5.0 Megabytes (recommended -- grows as server is used)
`/etc/init.d/ab2mgr`	Server start-up file	0.01 Megabytes

In addition, you need to set aside some amount of disk space (600 Megabytes recommended) for the actual book files. The exact amount of space depends on the specific collections. For a list of collections available on the Solaris 7 Documentation CD, see the README file located on that CD.

Installation Choices

Before you install the AnswerBook2 server software, you should consider your installation choices:

Install everything on one system

The AnswerBook2 server software and Solaris 7 documentation collections are on the Solaris 7 Documentation CD. If you install both parts of the server product on a single system, when you finish the installation process and start the server, it will be ready to serve documentation to all clients. See "Installing the Server Software" for more information.
Install server and document collections on separate systems

You can install the documentation server software on one system and point to document collections that are located on a different system. You might want to do this if you have minimal space available on your server's system or if you have existing collections on another system. To do this, you need to add each collection manually to the server's database and the Scan for Locally Installed Collections function will not find these collections. See "Installing the Server Software" for more information.
Run a server from the CD

If you are operating in a non-networked environment (stand-alone) or you only occasionally view the online documentation, you can run the AnswerBook2 server directly from the Solaris 7 Documentation CD. A documentation server run from the CD tends to be slower than a documentation server installed on your system. Thus, it is not recommended that you use this approach if you expect other users to access this documentation server. For more information, see "Running a Documentation Server from the CD".

Installing the Server Software

To install documentation server software, you can use the point-and-click interface available from the Solaris Web Start^TM utility, or you can use standard installation utilities, such as pkgadd. Appendix A, Sample AnswerBook2 Installation provides a complete sample installation of the documentation server software using the pkgadd utility.

To install the AnswerBook2 server software, perform the following steps:

Log in as super-user on the documentation server machine.

To use the Web Start utility, you must log in as root from the Desktop Login screen. To use a standard installation utility, such as pkgadd, you can log in as root from the Desktop Login screen or enter the following at the command line:
% su -

Insert the Solaris 7 Documentation CD into your CD-ROM drive.

The Volume Manager should automatically mount the CD.

If you choose to use the Solaris Web Start utility to install your products, double-click on the installer icon, follow the instructions on the Web Start screens, and go to Step 6.

The Web Start utility provides pre-selected groups of packages for you to install. Follow the instructions on the Web Start screens to continue.

If you choose to use the pkgadd utility or the swmtool utility, change directory to the location of the documentation server packages.

For example, you might enter a command similar to the following to go to the location of the server software packages for a SPARC server:
# cd cdrom/Solaris_2.7_Doc/sparc/Product/
Where cdrom is the mount-point for the CD-ROM device and defaults to /cdrom/sol_2_7_doc.

Launch the installation utility and select the server software packages.

For example, use the following command to launch the pkgadd utility:
# pkgadd -d .
Select these server software packages:
- SUNWab2r (0.25 Megabytes) -- Installs in root partition and provides configuration and start-up files.
- SUNWab2s (1.00 Megabytes) -- Provides shared files for performing document processing.
- SUNWab2u (26.00 Megabytes) -- Provides executable and back-end processing files for server and administration functions.

Start up the server, if needed.

Installing the packages should cause the server to start up on the default port of 8888. If it does not start, use the following command to start it:
# /usr/lib/ab2/bin/ab2admin -o start

Install the book collections.

Your documentation server cannot do its job if no document collections are installed for it to serve. You can install collections from the Solaris 7 Documentation CD or from other locations, such as existing document collections or collections that come on other CDs. For more information about installing document collections, see "Installing Document Collections onto the Server".

(Optional) Change configuration files and create links to run the documentation server as a CGI process on an existing httpd server.

If you already run an httpd server on your system, you can run the documentation server as a CGI process on that server. You must install the standard documentation server software, then change several configuration files and create links to run the documentation server as a CGI process. For more information, see "Running the AnswerBook2 Documentation Server as a CGI Process".

(Optional) Register the server.

If you want other users to automatically find your documentation server through Federated Naming Service (FNS), you need to register the server. To register your server, use the following command:
# /usr/lib/ab2/bin/ab2regsvr server_url
Where server_url is the fully qualified URL to get to this server (for example: http://imaserver.eng.sun.com:8888/). See "Registering Your Documentation Server" for more information.

Installing Document Collections onto the Server

Your documentation server cannot do its job if no documents are installed for it to serve. You can install collections from the Solaris 7 Documentation CD or from other locations, such as existing document collections or collections that come on other CDs.

To install document collection packages from the Solaris 7 Documentation CD, you can use the point-and-click interface available from the Solaris Web Start^TM utility, or you can use standard installation utilities, such as pkgadd. To install document collections, follow these steps:

Log in as super-user on the documentation server machine.

To use the Web Start utility, you must log in as root from the Desktop Login screen. To use a standard installation utility, such as pkgadd, you can log in as root from the Desktop Login screen or enter the following at the command line:
% su -

Insert the Solaris 7 Documentation CD into your CD-ROM drive.

The Volume Manager should automatically mount the CD.

If you choose to use the Solaris Web Start utility to install your products, double-click on the installer icon, follow the instructions on the Web Start screens, and go to Step 6.

The Web Start utility provides pre-selected groups of packages for you to install. Follow the instructions on the Web Start screens to continue.

If you choose to use the pkgadd utility or the swmtool utility, change directory to the location of the documentation collection packages.

For example:
# cd cdrom/Solaris_2.7_Doc/common/Product/
Where cdrom is the mount-point for the CD-ROM device and defaults to /cdrom/sol_2_7_doc.

Launch the installation utility and select document collection packages to install.

For example, to launch the pkgadd utility:
# pkgadd -d .
For a detailed list of document collections included on the Solaris 7 Documentation CD, see the README file located on that CD.

The document collection packages included on the Solaris 7 Documentation CD include a post-install script that add the collections to the server's database and restart the server.

If you install collection packages from any other location besides the Solaris 7 Documentation CD, you might need to use either the Admin GUI's Add Collection to List function or the ab2admin -o add_coll command to add these collections to the documentation server's database.

If you have document collections already installed on your system, you can use either the Admin GUI's Scan for Locally Installed Collections function or the ab2admin -o scan command to have them found and added to the documentation server's database. This function only works for locally-installed packages.

To serve document collections located on some other system, use the Add Collection to List function or the ab2admin -o add_coll command and provide the full path name to the ab_cardcatalog or collinfo file. For example, if the documentation server is imaserver and you want it to serve document collections located on the system elsewhere, you might use the following command:
# ab2admin -o add_coll -d /net/elsewhere/books/SUNWdtad/collinfo

Registering Your Documentation Server

To give users the ability to locate your documentation server without knowing the URL, you can register the name of your server with the FNS system. Users can still access unregistered documentation servers if they know the URL.

How you register your server depends on two things:

Your familiarity with FNS commands

If you are familiar with standard FNS commands, such as fnbind, you can use those commands to register the server. However, to simplify the registration process, the /usr/lib/ab2/bin/ab2regsvr command can take care of registering your server for you. For more information , see "Registering your Server Using the ab2regsvr Command" and "Registering your Server Using Standard FNS Commands".
What name service you are using

NIS+ (Network Information Service Plus) is the primary name service used for Solaris 2.6 and later operating environments. If your system is using NIS+ and you have administrative privileges, you can register the server while logged in on either the NIS+ master or NIS+ client system.

NIS (Network Information Service) was the standard name service provided in SunOS 4.x (Solaris 1.x) environments. If your system is using NIS, you must be logged in as root on the NIS master system to register the documentation server.

The AnswerBook2 product also works with a file-system defined naming system (files) in which all names are manually entered into data files. These files are stored in the directory /var/fn/. In this case, to be able to register the server, you must have root access to the system and registration applies only on the machine on which it is registered. Other machines cannot see a server registered under a file system mechanism.

Registering your Server Using the `ab2regsvr` Command

To register your server, use the ab2regsvr command. The ab2regsvr command looks at your system's configuration and sets up the appropriate name space for your server.

To register your server, use the following command:

# /usr/lib/ab2/bin/ab2regsvr server_url

Where server_url is the fully qualified URL to get to this server (for example: http://imaserver.eng.sun.com:8888/).

The ab2regsvr command also provides some other options you might find useful:

To view a list of registered AnswerBook2 server URLs:
# /usr/lib/ab2/bin/ab2regsvr -l
To remove a registered server from the list:
# /usr/lib/ab2/bin/ab2regsvr -d
To change the URL for the currently registered AnswerBook2 server:
# /usr/lib/ab2/bin/ab2regsvr -r server_url
Where server_url is the new URL to get to this server (for example: http://aserver.eng.sun.com:8888/). This replaces any existing URLs with the specified URL.

For more information about the ab2regsvr command, see the ab2regsvr(1m) man page.

Registering your Server Using Standard FNS Commands

If you want to use FNS commands to register your server and you already have FNS installed at your location, use the following command to register the specified URL as a documentation server for your organization (domain):

# fnbind -r thisorgunit/server/answerbook2 onc_answerbook2 \
onc_addr_answerbook2 server_url

Where server_url is the fully qualified URL to get to this server (for example: http://imaserver.eng.sun.com:8888/).

To find out what servers are currently registered, use the following command:

% fnlookup -v thisorgunit/service/answerbook2

This returns a list of registered servers that looks similar to the following:

Reference type: onc_answerbook2
Address type: onc_addr_answerbook2
  length: 19
  data: 0x68 0x74 0x74 0x70 0x3a 0x2f 0x2f 0x61 0x6e 0x73  http://ans
        0x77 0x65 0x72 0x73 0x3a 0x38 0x38 0x38 0x38       wers:8888

In this example, the registered server is http://answers:8888/.

If you get a response similar to the following, then no documentation servers are registered with FNS:

Lookup of 'thisorgunit/service/answerbook2' failed: \
Name Not Found: 'answerbook2'

For more information about FNS, including how to install it, see the FNS documentation.

Name Services and AnswerBook2 Users

Rather than using the described name services to find a documentation server, the user can define a default AnswerBook2 server using the environment variable AB2_DEFAULTSERVER. For example, the user could have the following line in the .cshrc file:

setenv AB2_DEFAULTSERVER http://imaserver.eng.sun.com:8888

If the user has not defined an environment variable, when the user launches the AnswerBook2 product from the desktop, the product looks to see if the system from which it was launched is running a documentation server. If so, it launches using the URL: http://localhost:port, where port defaults to 8888.

If the user has not defined an environment variable and the current system is not a documentation server, when the user launches AnswerBook2 from the desktop, the system performs an fnlookup thisorgunit/service/answerbook2 command to find out what documentation servers are available. It then chooses one of those servers and launches the AnswerBook2 browser using that server name for the URL.

Running a Documentation Server from the CD

To run a documentation server directly from the Solaris 7 Documentation CD:

Insert the Solaris 7 Documentation CD into your CD-ROM drive.

Make sure you are logged in as super-user.
% su -

Change directory to (or bring up and go to) the top level of the CD-ROM volume.

This should look similar to the following location:
/cdrom/sol_2_7_doc/
This directory contains one directory, a README file, the installer utility, and the ab2cd script. Use the ab2cd script to run the documentation server directly from the CD.

Run the following command:
# ./ab2cd

Access the documentation server using the following URL:
http://server:8888/
Where server is the name of the machine to which the CD-ROM drive is attached.

Note that a documentation server run from the CD always runs on port 8888.

(Optional) If document collections are installed already on your server machine and you want the CD-driven server software to recognize those collections, use this command:
# ab2cd -s
This form of the command causes the CD-driven server software to look for other collections installed on this system and add them to its database.

To stop running the server from the CD, enter the following command:
# /cdrom/sol_2_7_doc/ab2cd stop

Caution -

Running the documentation server directly from the CD tends to be slow. Do not use this approach if you expect other users to access this documentation server.

Important Notes

Keep these things in mind when you run the server from the CD:

The AnswerBook2 server always runs on port 8888 when run from the CD. If you already have an AnswerBook2 server running on your system using the default port (8888), the ab2cd script will display the following message:
```
A document server is already running on this system as server:8888.





Please shut down the current server before running the ab2cd command.
```
Use the following command to shut down the existing server:
# /usr/lib/ab2/bin/ab2admin -o stop
Always use ab2cd stop to stop the server running from the CD. Do not use /etc/init.d/ab2mgr stop to stop the CD-based server.

The ab2cd stop command stops the AnswerBook2 server process and cleans up all files in the /tmp/ab2 and /tmp/ab2cd_config directories. The /etc/init.d/ab2mgr stop command stops all server processes, but does not clean up the files in the /tmp/ab2 and /tmp/ab2cd_config directories.

Running a Server from the CD and a Server on your System

To run two AnswerBook2 servers (one on your system, one from the CD), keep these rules in mind:

Starting up the server
- The /etc/init.d/ab2mgr start command always starts the server on your system.
- The ab2cd command always starts the server from the CD.
Shutting down the server
- Always use the ab2cd stop command to stop the server running from the CD.
- To stop both servers, first use the ab2cd stop command to stop the server running from the CD, then use either /etc/init.d/ab2mgr stop or /usr/lib/ab2/bin/ab2admin -o stop to stop the server running on your system.

Running the AnswerBook2 Documentation Server as a CGI Process

By default, the AnswerBook2 documentation server runs as an NSAPI plug-in on top of the httpd server that is included in the SUNWab2u package. Because the AnswerBook2 server complies with standard web protocols, you can choose to run the documentation server as a CGI (Common Gateway Interface) process on top of some other web server already on your system (for example, Netscape Server or Sun Web Server).

Be aware that the following functions will not work if you change from the default AnswerBook2 web server:

/usr/lib/ab2/bin/ab2admin -o start
/usr/lib/ab2/bin/ab2admin -o stop
/etc/init.d/ab2mgr start
/etc/init.d/ab2mgr stop
restart from the Admin GUI

You will need to use your server's start and stop functions instead.

Changing to CGI-based Server

Because specific details differ by web server, this procedure describes the general steps you need to follow to use a CGI-based web server rather than the default (NSAPI plug-in) server. Specific examples are included below for Sun Web Server and Netscape Server.

Shut down the AnswerBook2 server if it is running.

Use one of the following commands:
# /usr/lib/ab2/bin/ab2admin -o stop # /etc/init.d/ab2mgr stop

Edit your web server's configuration file and make icons available.

Your web server's documentation should explain specific details, such as where to find the configuration file. The entry /icons/ should point to /usr/lib/ab2/data/docs/icons/.

If /icons/ is already being used, link all files in /usr/lib/ab2/data/docs/icons/ to the existing /icons/ directory.

Link AnswerBook2 Help documents to the current documentation root.

Go to your web server's documentation root directory and create a soft link to /usr/lib/ab2/data/docs/.

Make AnswerBook2 cgi-bin files available to your server.

Go to your web server's cgi-bin directory and create soft links to the following:

/usr/lib/ab2/bin/cgi/admin
/usr/lib/ab2/bin/cgi/nph-dweb
/usr/lib/ab2/bin/cgi/gettransbitmap
/usr/lib/ab2/bin/cgi/getepsf
/usr/lib/ab2/bin/cgi/getframe
/usr/lib/ab2/bin/cgi/ab2srwrap

Edit your server's configuration file and map /ab2/ to call AnswerBook2 cgi.

Your web server's documentation should explain specific details, such as where to find the configuration file. You need to change the entry for /ab2/ to /usr/lib/ab2/bin/cgi/nph-dweb/ab2/.

Edit the AnswerBook2 administration configuration file.

You need to edit the /usr/lib/ab2/bin/cgi/nph-dweb file and change the entries for servertype, errorlog, and accesslog.

Changing to Sun Web Server using CGI

By default, the Sun Web Server configuration file is /etc/http/httpd.conf and files are in /var/http/demo/. If you did not install SUNWab2u in the default location (/usr/), all paths that begin /usr/lib/ab2/ should be the path where you installed the files (for example, /usr2/lib/ab2/).

Edit the /etc/http/httpd.conf file and put the following line in the server section of the file:
map /icons /usr/lib/ab2/data/docs/icons
When you have made this change, use the following command to restart the SWS server:
# /etc/init.d/httpd start
To verify your changes, enter the following URL in your web browser to see a Help icon :
http://localhost:port/icons/ab2_help.gif
Where port is the port number on which your documentation server is running and defaults to 8888.

Go to the /var/http/demo/public/ directory and put in the following soft link:
# ln -s /usr/lib/ab2/data/docs/Help Help
To verify your changes, enter the following URL in your web browser to see a Help icon :
http://localhost:port/Help/C/Help/books/Help/figures/ab2_help.gif
Where port is the port number on which your documentation server is running and defaults to 8888.

Go to the /var/http/demo/cgi-bin/ directory and create the following soft links:

# ln -s /usr/lib/ab2/bin/cgi/admin
# ln -s /usr/lib/ab2/bin/cgi/nph-dweb
# ln -s /usr/lib/ab2/bin/cgi/gettransbitmap
# ln -s /usr/lib/ab2/bin/cgi/getepsf
# ln -s /usr/lib/ab2/bin/cgi/getframe
# ln -s /usr/lib/ab2/bin/cgi/ab2srwrap

To verify your changes, enter the following URL in your web browser to see the AnswerBook2 library page:

http://localhost:port/cgi-bin/nph-dweb/ab2

Where port is the port number on which your documentation server is running and defaults to 8888.

Edit the /etc/http/httpd.conf file and add the following entry in the host section of the file:
map /ab2 /var/http/demo/cgi-bin/nph-dweb/ab2 cgi
Restart the SWS server using the following command:
# /etc/init.d/httpd start
To verify your changes, enter the following URL in your web browser to see the AnswerBook2 library page:
http://localhost:port/ab2
Where port is the port number on which your documentation server is running and defaults to 8888.

Edit the /usr/lib/ab2/bin/cgi/nph-dweb file and change the following entries:

setenv servertype sws
setenv errorlog
setenv accesslog /var/http/logs/http.elf.1

Changing to Netscape Server using CGI

For this example, the Netscape Server configuration file is /ul/netscape/suitespot/httpd-threads1/config/obj.conf and files are in /ul/netscape/suitespot/docs/. If you did not install SUNWab2u in the default location (/usr/), all paths that begin /usr/lib/ab2/ should be the path where you installed the files (for example, /usr2/lib/ab2/).

Edit the /ul/netscape/suitespot/httpd-threads1/config/obj.conf file and add the following line:
NameTrans fn="pfx2dir" from="/icons" dir="/usr/lib/ab2/data/docs/icons"
To verify your changes, restart the Netscape Server. Then, enter the following URL in your web browser to see a Help icon :
http://localhost:port/icons/ab2_help.gif

Go to the /ul/netscape/suitespot/docs/ directory and put in the following soft link:
# ln -s /usr/lib/ab2/data/docs/Help Help
To verify your changes, enter the following URL in your web browser to see a Help icon :
http://localhost:port/Help/C/Help/books/Help/figures/ab2_help.gif
Where port is the port number on which your documentation server is running and defaults to 8888.

Go to the /ul/netscape/suitespot/cgi-bin/ directory and create the following soft links:

# ln -s /usr/lib/ab2/bin/cgi/admin
# ln -s /usr/lib/ab2/bin/cgi/nph-dweb
# ln -s /usr/lib/ab2/bin/cgi/gettransbitmap
# ln -s /usr/lib/ab2/bin/cgi/getepsf
# ln -s /usr/lib/ab2/bin/cgi/getframe
# ln -s /usr/lib/ab2/bin/cgi/ab2srwrap