Setting Up an AnswerBook Server and AnswerBook Clients

Table 22-1 Task Map: AnswerBook Network Setup

Activity........Description

For Instructions, Go To

Install AnswerBook

Install AnswerBook from a product CD image or from an

Chapter 21, "Installing page

AnswerBook CD image...............AnswerBook"

345

Set Up an

Set up a central ab_cardcatalog file. Modify it to point

· How to Set Up an page

AnswerBook

to all installed AnswerBook packages on the AnswerBook

AnswerBook Server

363

Server

server.

on the Network

Set Up

Set the AB_CARDCATALOG environment variable and

· How to Enable..page

AnswerBook

make it available to all users wanting to access the

Clients to Access an

369

Clients

AnswerBook server.

AnswerBook Server

Manage the

Convert old-style bookinfo files to ab_cardcatalog

· How to Convert a page

ab_cardcatalog File

files, add entries and maintain the ab_cardcatalog file.

bookfinfo File To an

371

ab_cardcatalog File

· How to Manage the ab_cardcatalog File

page 372

Manage the

Verify that Display PostScript is available for displaying

· How to Determine If page

AnswerBook

AnswerBook documentation.

Display PostScript Is

374

Display

Available

Prerequisites

To set up an AnswerBook server on the network, you need:

• A system or server running Solaris system software.
• Disk space to hold numerous AnswerBooks. (The disk space required for any given AnswerBook varies, so there's no sure recommendation.)
• The automounter running. (There are setup files on the server that the answerbook startup script expects to access via the automounter.)

Once you've installed the AnswerBook package, network clients should have the following system setup to view the AnswerBook documentation:

• A system or server running Solaris system software and a black-and-white or color bitmap graphics monitor.
• OpenWindows^(TM) Version 3.2 or later.
• For printing pages from AnswerBook: a laser printer with Palatino^(TM) style fonts resident (such as the Sun LaserWriter^(TM) or Sun SPARCprinter^(TM)).
• The automounter running. (There are setup files on the server that the answerbook startup script expects to access via the automounter.)

Setting Up an AnswerBook Server

For networked sites, it makes sense to install all AnswerBook packages on a single system and create an AnswerBook server. This centralizes AnswerBook installation and administration, and frees disk space and the CD-ROM drive on desktop systems. The remainder of this section shows the procedure to set up an AnswerBook server.

· How to Set Up an AnswerBook Server on the Network

This procedure assumes the AnswerBook package is already installed on a system. For details on how to install an AnswerBook package, see Chapter 21, "Installing AnswerBook."

1. Choose a system to be an AnswerBook server for other clients on the network.

2. Log in to the AnswerBook server as root.

3. Create or update the master ab_cardcatalog file with information about the new AnswerBook.

# /usr/openwin/bin/ab_admin -file AB-net-path -merge AB-install-dir/ab_cardcatalog

In this command,

AB-net-path	Is the path to the ab_cardcatalog file that will be shared with clients on the network, for example:
/export/share/ab_cardcatalog
AB-install-dir	Is the path to the installed AnswerBook. The /opt directory is typically the default AnswerBook installation directory: for example,

/opt/SUNWaadm

Clients accessing the AnswerBook server will reference this ab_cardcatalog file to determine the AnswerBooks that are available for viewing.

The ab_admin command copies information from the ab_cardcatalog in the AnswerBook installation directory into the master ab_cardcatalog file.

4. Edit the master ab_cardcatalog file so that the tocpath, pspath, and indexpath entries use automounter path names. (Automounter path names typically begin with /net/hostname.)

By default, ab_admin sets the tocpath, pspath, and indexpath to the location of the installed AnswerBook packages on the AnswerBook server. For example, if the SUNWAxg AnswerBook were installed in /opt, the ab_cardcatalog file would look like this:

id=SUNWAxg_10_6 title=... tocpath=/opt/SUNWAxg/toc pspath=/opt/SUNWAxg/ps indexpath=/opt/SUNWAxg/index

These paths must have automounter paths (for example, tocpath=/net/hostname/opt/SUNWAxg/toc) so that clients can access the AnswerBook server's AnswerBook packages successfully. Manually edit the master ab_cardcatalog file according to the following conventions.

id=SUNWAxg_10_6 title=... tocpath=/net/hostname/AB-install-dir/AB-name/toc pspath=/net/hostname/AB-install-dir/AB-name/ps indexpath=/net/hostname/AB-install-dir/AB-name/index

---

Note - This assumes your site uses the default automounter mount point, which is /net. If your site uses a different automounter mount point, substitute that mount point for /net.

---

In this ab_cardcatalog file,

/net	Is the default mount point for the automounter. If your site uses another automounter mount point, use that mount point instead of /net.
hostname	Is the name of the AnswerBook server.
AB-install-dir	Is the path to the installed AnswerBook. The /opt directory is typically the default AnswerBook installation directory.

AB-name.......Is the name of the installed AnswerBook package, for example: SUNWAxg.

5. Repeat Step 3 and Step 4 for all AnswerBooks you want to be accessed from the AnswerBook server.

6. Edit the /etc/dfs/dfstab file and add these lines.

share -F nfs -o ro AB-net-path share -F nfs -o ro AB-install-dir

In this file,

AB-net-path	Is the directory with the master ab_cardcatalog file, for example: /export.
AB-install-dir	Is the directory with the installed AnswerBook. The /opt directory is typically the default. For example, for the SUNWAxg AnswerBook installed in /opt/SUNWAxg, share /opt.

7. Share the file systems with the AB-net-path and AB-install-dir file systems.

   This makes the master ab_cardcatalog and related files available when clients on the network start the AnswerBook software.

# shareall

When you are done setting up the AnswerBook server, verify that the master ab_cardcatalog is correct and that the ab_cardcatalog and AnswerBook installation directories are shared.

Verification--Setting Up an AnswerBook Server on the Network

To verify that the paths in the master ab_cardcatalog file can be mounted by other clients on the network, examine the master ab_cardcatalog file. In this case, assume the master ab_cardcatalog file is on a system named mars

and in the /export/share directory. The tocpath, pspath, and indexpath are correctly set to a path for clients running the automounter (a path that begins with /net/hostname/).

mars# more /export/share/ab_cardcatalog :::::::::::::: ab_cardcatalog :::::::::::::: #<Card Catalog> version 1 # # This file was generated by cardcatadmin. # DO NOT EDIT THIS FILE BY HAND. :id=SUNWab_10_4: \ :version=: \ :title=Solaris XGL 3.1 AnswerBook: \ :tocpath=/net/mars/opt/SUNWAxg/toc: :pspath=/net/mars/opt/SUNWAxg/ps: :indexpath=/net/mars/opt/SUNWAxg/index: :id=SUNWab_8_22: :version=: \ :title=Solaris 2.4 User AnswerBook: \ :tocpath=/net/mars/opt/SUNWabe/toc: :pspath=/net/mars/opt/SUNWabe/ps: :indexpath=/net/mars/opt/SUNWabe/index:

To verify that the tocpath, pspath, and indexpath are set correctly and are readable, use the ab_admin command. If there is an error, the ab_admin command will report it. Otherwise, the command will return the prompt.

To verify a single AnswerBook entry, use this ab_admin command.

# ab_admin -file /net/mars/export/share/ab_cardcatalog -verify SUNWab_10_4 #

To verify all AnswerBooks in the ab_cardcatalog file, use these commands.

# /bin/sh $ for AB in 'ab_admin -list -file $AB_CARDCATALOG' > do > echo Verifying $AB > ab_admin -verify $AB -file $AB_CARDCATALOG > done Verifying SUNWab_10_4 Verifying SUNWab_8_22 . . .

To verify that the AB-net-path and AB-install-path are shared so that client's trying to access the AnswerBook server can mount them, use the share command. For example, assume an AnswerBook server named mars has AnswerBooks installed in /opt and has a master ab_cardcatalog file in /export/share. /opt and /export need to be shared.

mars# share - /export ro "" - /opt ro ""

Where to Go Next

After setting up the AnswerBook server, there is still some work required before clients on the network can access AnswerBook from the server. For details, see "Enabling Clients to Access the AnswerBook Server" on page 368.

Enabling Clients to Access the AnswerBook Server

To access a central AnswerBook server, each client on the network must set a local environment variable named AB_CARDCATALOG. This environment must be set to the path the master ab_cardcatalog file on the AnswerBook server. Then, when a user types the answerbook command, the AnswerBook startup software knows where to find all the AnswerBooks available on the network.

There are several ways to set this environment variable for users. Three are described in detail in "The AB_CARDCATALOG Environment Variable" on page 340. This section describes only the recommended way to distribute the AB_CARDCATALOG environment variable. This method involves creating a site-specific initialization file and sourcing it from the users's initialization file.

· How to Enable Clients to Access an AnswerBook Server

Enabling clients to access an AnswerBook server involves making a special AnswerBook environment variable to all clients. This section shows one model for distributing that environment variable. However, this model for distributing the environment variable has implications beyond AnswerBook administration. It is discussed in detail in the section titled "Use Site Initialization Files" on page 24.

1. Make sure your site has site-specific initialization files that are somehow available to all users.

   For detailed information on setting up site-specific initialization files and making information in those files available to users, see the section titled "Use Site Initialization Files" on page 24.

2. Modify the site-specific csh and sh initialization files. For csh users, add the following line:

setenv AB_CARDCATALOG AB-net-path

For sh users, add the following line:

AB_CARDCATALOG=AB-net-path:${AB_CARDCATALOG} export AB_CARDCATALOG

In these site-specific initialization files,

AB-net-path.....Is the path to the ab_cardcatalog file that will be shared with clients on the network, for example:

/net/moon/export/share/ab_cardcatalog

Note: You must use the automounter path for clients to be able to access the server's ab_cardcatalog correctly. (An automounter path begins with /net/hostname/).

Verification--Enabling Clients to Access an AnswerBook Server

Verify the setup with a trial run. Log in to a system on the network and start the AnswerBook application. Either double-click on its icon in File Manager or enter:

$ /usr/openwin/bin/answerbook &

If OpenWindows has been installed somewhere other than /usr/openwin (which is the default installation directory), then use the command:

$ /openwin-install-path/openwin/bin/answerbook &

The answerbook command will search for a local ab_cardcatalog file and then for a remote ab_cardcatalog file (which it finds according to the AB_CARDCATALOG environment variable).

When the AnswerBook Navigator opens, click the Modify Library button and select AnswerBook titles from the scrolling list so they are included in the Navigator Contents.

Converting a bookinfo File to an ab_cardcatalog File

If an old (pre-Solaris 2.2) bookinfo file is on your network, convert it to ab_cardcatalog file. You can do this with the ab_admin command, as described in the next procedure.

· How to Convert a bookfinfo File To an ab_cardcatalog File

To convert an older bookinfo file to card-catalog format, use this ab_admin command:

# ab_admin -file $AB_CARDCATALOG -convert /opt/AB-name/bookinfo

In this command,

AB-name.......Is the name of the installed AnswerBook package.

Using ab_admin to Manage the ab_cardcatalog File

One way to view and manage the ab_cardcatalog file is simply to view it with the cat command and edit it. However, the $AB_CARDCATALOG/ab_cardcatalog file can grow to be quite large, possibly making it unwieldy to manage in this way. For this reason, the ab_admin command is the recommended interface for managing the ab_cardcatalog file.

· How to Manage the ab_cardcatalog File

Following is the syntax for using the ab_admin command. For more details, see the ab_admin(1) man page.

ab_admin [-verify AB-ID ] [-listpaths] [-match AB-ID] [-remove AB-ID] [-merge AB-install-dir] [-file $AB_CARDCATALOG]

In this command,

AB-ID	Is the AnswerBook ID number as listed in the ab_cardcatalog file.
AB-install-dir	Is the AnswerBook installation directory. AnswerBook packages are typically installed in /opt.

$AB_CARDCATALOG          Is the environment variable that is set to a master 
                         ab_cardcatalog file that is shared on an 
                         AnswerBook server.

Example--Validating ab_cardcatalog Entries

This ab_admin command verifies the AnswerBook entries are valid in an ab_cardcatalog file.

% /bin/sh $ for AB in 'ab_admin -list -file $AB_CARDCATALOG' > do > echo Verifying $AB > ab_admin -verify $AB -file $AB_CARDCATALOG > done Verifying SUNWab_8_6 Verifying SUNWab_2_6

The ab_admin command will report any invalid entries.

Example--Finding an AnswerBook ID Number

The ab_admin command often takes the AnswerBook ID as an argument. If the ab_cardcatalog file has a lot of AnswerBook entries, you can use ab_admin with an AnswerBook ID to view information specific to that AnswerBook.

This ab_admin command shows the AnswerBook ID number for the SUNWabe AnswerBook installed in /opt.

% ab_admin -list -file /opt/SUNWabe/ab_cardcatalog SUNWab_2_6

Example--Listing Card Catalogs

This ab_admin command list card catalogs and packages in the current environment:

# ab_admin -listpaths /net/AB-server/export/ab_cardcatalog /home/mickey/.ab_cardcatalog

Example--Listing AnswerBook Title and Paths

This ab_admin command lists a specific AnswerBook title and paths as listed in ab_cardcatalog file. In this example, ab_admin displays information about the AnswerBook corresponding to ID SUNWab_10_4:

% ab_admin -match SUNWab_10_4 -file $AB_CARDCATALOG id=SUNWab_10_4 title= Solaris XGL 3.1 AnswerBook tocpath=/net/AB-server/export/share/ab_cardcatalog pspath=/net/AB-server/export/share/ab_cardcatalog indexpath=/net/AB-server/export/share/ab_cardcatalog

Example--Merging New Card Catalog Data with the Master

This ab_admin command merges a specific AnswerBook ab_cardcatalog file with the site's master ab_cardcatalog file. (You would do this after installing a new AnswerBook. Before users on the network can access it, you need to merge its ab_cardcatalog with the site's master ab_cardcatalog).

# ab_admin -file $AB_CARDCATALOG -merge \ /opt/AB-name/ab_cardcatalog

Example--Removing Entries From ab_cardcatalog

This ab_admin command removes a specific AnswerBook entry (in this case, the AnswerBook with an ID of SUNWab_2_6) from the ab_cardcatalog file.

# ab_admin -file $AB_CARDCATALOG -remove SUNWab_2_6

· How to Determine If Display PostScript Is Available

To determine if your system or terminal is running Display PostScript, set the DISPLAY environment variable to the appropriate display and then use the xdpyinfo(1) command.

At the command line, enter:

$ xdpyinfo | grep -i dps

If Display PostScript is running you will see:

Adobe-DPS-Extension DPSExtension

If Display PostScript is not running, no information will be displayed.