This chapter provides procedures for performing DynaWeb server administrative tasks. The major sections of this chapter are:
DynaWeb can run either as a Common Gateway Interface (CGI) script or as a process. Since DynaWeb currently supports only non-secure basic HTTP authentication, a security-conscious administrator may wish to run DynaWeb as a CGI script piggybacked on another server, utilizing the SGML-to-HTML and organizational capabilities of DynaWeb while retaining the extra security provided by the front-end server.
The first subsection, “Running DynaWeb as a Process,” explains how to run a single DynaWeb server as a process. The next subsection, “Running DynaWeb as a Process with Multiple Configurations,” explains how to set up and run a DynaWeb server with multiple configurations, each associated with a port number. With different configurations, the server can serve English books on one port and serve Japanese books on another port. The last subsection, “Running DynaWeb as a CGI Script,” explains how to have another server, such as a Mindshare Out Box server or a Netscape server, run DynaWeb as a CGI script.
The dynaweb program starts the DynaWeb server as a process. It isn't usually started from the command line. Instead, it is started automatically when the system boots up if the dynaweb configuration flag is on, or by running the /etc/init.d/dynaweb script with the dynaweb configuration flag on.
To check the value of the dynaweb configuration flag, enter this command:
# chkconfig | grep dynaweb |
To set the dynaweb configuration flag on, enter this command as superuser:
# chkconfig dynaweb on |
When the dynaweb configuration flag is on, the Dynaweb server starts automatically each time the system is rebooted.
To start dynaweb manually, enter this command as superuser:
# /etc/init.d/dynaweb start |
By default, DynaWeb utilizes port number 88. To use this port or any other port less than 1024, DynaWeb must be run by a superuser.
To restart dynaweb, perhaps because you have changed values in the configuration file /usr/lib/Insight/dweb/data/config/dynaweb.cfg.tmpl, enter these commands:
# /etc/init.d/dynaweb stop # /etc/init.d/dynaweb start |
To stop dynaweb, enter this command as superuser:
# /etc/init.d/dynaweb stop |
A DynaWeb process can be set up so that it appears to users as multiple servers. Each “server” can have a different configuration, for example, different collections of books or server pages in different languages. Each configuration is described by a configuration file and is associated with a port number. Users select the configuration they want using hypertext links or by specifying a port number in a URL (see the section “Accessing InSight Books” in this chapter).
Follow this procedure to set up a DynaWeb server with multiple configurations and start it:
Make a copy of the DynaWeb configuration file:
# cd /usr/lib/Insight/dweb/data/config # cp dynaweb.cfg.tmpl dynaweb_port.cfg.tmpl
port is the port number for the additional DynaWeb server. Do not use 80, 88, or any other port number listed in /etc/services for the value of port.
Open the new configuration file, dynaweb_port.cfg.tmpl, for editing, for example:
# vi dynaweb_port.cfg.tmpl
Change configuration parameters in dynaweb_port.cfg.tmpl as necessary to achieve the configuration you want. See Chapter 3, “Configuration Parameters,” for information on configuration parameters. To simplify maintenance of configuration files, parameters whose values are the same in dynaweb_port.cfg.tmpl and dynaweb.cfg.tmpl need not be included in dynaweb_port.cfg.tmpl.
Change the value of the configuration parameter DWEB_PORT in dynaweb_port.cfg.tmpl to port:
DWEB_PORT = port
Write the file dynaweb_port.cfg.tmpl and exit the editor.
Open the file /etc/init.d/dynaweb for editing, for example:
# vi /etc/init.d/dynaweb
Find the comment labeled EDIT LOCATION 1 OF 3 and this line following it (shown wrapped here and in the file):
sed “s/%%LOCALHOST%%/$HOSTNAME/” $WWWD_DIR/data/config/dynaweb.cfg.tmpl | sed “s/%%BOOKSHELVES%%/$X/” > $WWWD_DIR/data/config/dynaweb.cfg
Put a copy of the sed line from step 7 immediately after it.
In the second copy of the line, replace dynaweb.cfg.tmpl with dynaweb_port.cfg.tmpl.
Also in the second copy of the line, replace dynaweb.cfg at the end of the line with dynaweb_port.cfg. The second copy of the line now looks like this:
sed “s/%%LOCALHOST%%/$HOSTNAME/” $WWWD_DIR/data/config/dynaweb_port.cfg.tmpl | sed “s/%%BOOKSHELVES%%/$X/” > $WWWD_DIR/data/config/dynaweb_port.cfg
If each server is to display the same collections of books, skip to step 14. Continue with the next step if the servers are to display different collections, for example English books on one server and Japanese books on another server.
In both of the copies of the line shown in step 7, remove this portion of the line:
| sed “s/%%BOOKSHELVES%%/$X/”
Edit each of the configuration files, /usr/lib/Insight/dweb/data/config/dynaweb.cfg.tmpl and /usr/lib/Insight/dweb/data/config/dynaweb_port.cfg.tmpl, and modify the definitions of the DWEB_COLLECTIONS configuration parameter so that they specify the collections that are to be displayed by each of the servers.
Find the comment labeled EDIT LOCATION 2 of 3 in /etc/init.d/dynaweb and this line following it:
CONFIG_FILES=”dynaweb.cfg”
Add the name dynaweb_port.cfg to the quoted string so that it looks like this:
CONFIG_FILES=”dynaweb.cfg dynaweb_port.cfg”
port is the port number you chose in step 1.
Find the comment labeled EDIT LOCATION 3 OF 3 and this line following it:
exec ./$WWWD - p 88
Add a comma and the port number that you chose in step 1 to the end of the exec line. It now looks like this:
exec ./$WWWD -p 88,port
Write the file /etc/init.d/dynaweb and exit the editor.
Follow the directions in the section “Running DynaWeb as a Process” to set the dynaweb configuration flag on, if necessary, and start or restart the DynaWeb server.
The procedure for running DynaWeb as a CGI script under another server (for example, the Mindshare Out Box Web Server, the Netscape Commerce Server, or the Netscape Communications Server) is described in this section. It assumes that dynaweb is not already running as a process.
Perform these steps as superuser:
Start and stop the DynaWeb server by giving these commands:
# /etc/init.d/dynaweb start # /etc/init.d/dynaweb stop
Starting the DynaWeb server creates the file /usr/lib/Insight/dweb/data/config/dynaweb.cfg and links InSight book collections to the DynaWeb root directory.
Create a link named nph-dynaweb to the dwsgml2html program:
# cd cgibindir # ln -s /usr/lib/Insight/dweb/bin/dwsgml2html nph-dynaweb
cgibindir is the cgi-bin directory of the server that receives requests (not the DynaWeb cgi-bin directory). Normally it is /var/www/cgi-bin.
Create data and data/config directories:
# cd .. # mkdir data data/config
If you get one or more “File exists” error messages from mkdir, ignore them; they mean that the directories already exist.
Create a link to the file /usr/lib/Insight/dweb/data/config/dynaweb.cfg:
# cd data/config # ln -s /usr/lib/Insight/dweb/data/config/dynaweb.cfg .
Check to see if icons and images directories exist already:
# cd ../.. # ls -d icons images
If you get an error message for either directory, it doesn't exist.
For each directory that already exists, copy the contents of the corresponding DynaWeb directory:
# cp - r /usr/lib/Insight/dweb/servroot/icons/* icons # cp /usr/lib/Insight/dweb/servroot/images/* images
For each directory that doesn't exist, create links to the /usr/lib/Insight/dweb/servroot/icons and /usr/lib/Insight/dweb/servroot/images directories:
# ln -s /usr/lib/Insight/dweb/servroot/icons . # ln -s /usr/lib/Insight/dweb/servroot/images .
The server (for example, the Mindshare Out Box Web Server, the Netscape Commerce Server, or the Netscape Communications Server) can now serve out InSight books.
The DynaWeb home page and the DynaWeb collections page provide convenient access to IRIS InSight books. The following methods can be used to access collections from a Web browser:
Create a hypertext link from your home page to the DynaWeb home page.
The DynaWeb home page (in the file /usr/lib/Insight/dweb/servroot/docs/homepage.html) gives clients access to the DynaWeb collections page and the home pages of Silicon Graphics and Electronic Book Technologies, Inc. Using a Web authoring tool, create a hypertext link from your home page to the DynaWeb home page by including this URL:
<a href=http://server:port/>DynaWewb</a>
server is the hostname of the DynaWeb server. port is the port number of the server configuration you want. The default is 88. A configuration's port number is included in the name of its configuration file (except for the default configuration file, /usr/lib/Insight/dweb/data/config/dynaweb.cfg.tmpl), specified by the configuration parameter DWEB_PORT within that file, and included in the file /etc/init.d/dynaweb. See the section “Running DynaWeb as a Process with Multiple Configurations” in this chapter for more information.
Specify the URL of the DynaWeb home page or the DynaWeb collections page to your Web browser.
The URL of the DynaWeb home page is:
http://server:port/
The URL of the DynaWeb collections page is:
http://server:port/DWEB-COLLECTIONS
See the description of the values of server and port in the previous bullet.
Install the Silicon Graphics What's New product.
Installing What's New provides easy access to a DynaWeb server running on your system.
If DynaWeb is running as a CGI script, specify the URL of the parent server to your Web browser.
IRIS InSight book collections in the standard locations, /usr/share/Insight/library/*/*, are automatically made available to the DynaWeb server when it starts up. InSight book collections in non-standard locations and collections of DynaText books can be made available as well, by following the procedures in either of the following two subsections. The first subsection, “Setting Up a Collection as a Symbolic Link,” describes how to create symbolic links to other collections. The second subsection, “Setting Up a Collection as a Directory,” describes how to add collections to the DynaWeb root directory.
Installed InSight book collections are automatically linked to the DynaWeb root directory (see the section “Collections” in Chapter 1). The procedure below describes how to manually link other InSight book collections, for example, books that have been prepared with IRIS InSight Professional Publisher, and DynaText books to the DynaWeb root directory.
 | Note: Use symbolic links cautiously. For a discussion of the risks associated with allowing Web clients to access symbolically linked directories, see the section “Collections” in Chapter 1. |
Follow these steps:
Create a symbolic link to your collection in the /usr/lib/Insight/dweb/servroot directory:
# cd /usr/lib/Insight/dweb/servroot # ln -s coll_dir .
coll_dir is a directory that contains one or more InSight or DynaText books—a collection.
Note: Remember that if you allow access to a directory, the user is allowed to access all of the directories beneath it. Edit the file /usr/lib/Insight/dweb/data/config/dynaweb.cfg.tmpl and expand the definition of the DWEB_COLLECTIONS parameter to encompass each of your proprietary collections. For example,
DWEB_COLLECTIONS = %%BOOKSHELVES%%;@lit_books=Literature Collection
Restart the DynaWeb server:
# /etc/init.d/dynaweb stop # /etc/init.d/dynaweb start
One way to set up a collection is to place your own publishing files inside the DynaWeb root directory. Follow these steps:
Create a directory in /usr/lib/Insight/dweb/servroot to hold your collection, for example:
# cd /usr/lib/Insight/dweb/servroot # mkdir coll_dir
coll_dir is a directory name of your choice.
Copy your collection of published books to your new directory.
Edit the file /usr/lib/Insight/dweb/data/config/dynaweb.cfg.tmpl and modify the definition of the DWEB_COLLECTIONS parameter to include the new collection. For example, to specify the default collections and the new collection, use this definition:
DWEB_COLLECTIONS = %%BOOKSHELVES%%;@coll_dir=short title
short title is the name of the collection. It can include space characters and isn't quoted.
Restart the DynaWeb server:
# /etc/init.d/dynaweb stop # /etc/init.d/dynaweb start
The DynaWeb server has been structured to make it easy to provide different language versions of the server. All of the files containing English text are contained in the /usr/lib/Insight/dweb/servroot/C directory and in the configuration file /usr/lib/Insight/dweb/data/config/dynaweb.cfg.tmpl.
Follow this procedure as superuser to replace English with another language:
Copy the C directory to another directory. For example:
# cd /usr/lib/Insight/dweb/servroot # mkdir locale # cp -r C locale
locale is a locale name from /usr/lib/locale.
Save a copy of the original configuration file, for example:
# cd ../data/config # cp dynaweb.cfg.tmpl dynaweb.cfg.tmpl.C
Edit each of the files in the directory /usr/lib/Insight/dweb/servroot/C and replace the English text (not the HTML structure information within angle brackets, <>) with the language you want to provide on the server.
Open the file /usr/lib/Insight/dweb/data/config/dynaweb.cfg.tmpl for editing, for example:
# vi /usr/lib/Insight/dweb/data/config/dynaweb.cfg.tmpl
Change the values of all of the configuration parameters whose names end in LABEL. Substitute text in the language of your choice for each of these icon labels.
For more information about configuration parameters in /usr/lib/Insight/dweb/data/config/dynaweb.cfg.tmpl, see Chapter 3, “Configuration Parameters.”
Change the value of the DWEB_LOCALE configuration parameter to the name of the directory that is the new copy of the C directory:
DWEB_LOCALE = locale
Restart the DynaWeb server:
# /etc/init.d/dynaweb stop # /etc/init.d/dynaweb start
By using multiple ports and port-specific configuration files, you can set up a server to provide books and server pages in one language on one port and books and server pages in another language on another port. See the section “Running DynaWeb as a Process with Multiple Configurations” in this chapter for more information.
DynaWeb provides the ability to authenticate any requests it receives from a client against a password file. Authentication is achieved through the HTTP protocol, where the user name and password are included in the request for information and then checked against a master list of approved users. Enabling HTTP authentication is described in the subsection “Enabling HTTP Authentication.” The following subsections, “Adding a User,” “Verifying a User,” and “Deleting a User,” describe how to maintain the access list.
When the DynaWeb server is installed, authentication is inactive. To enable user name and password checking, follow these steps as superuser:
Open the configuration file /usr/lib/Insight/dweb/data/config/dynaweb.cfg.tmpl in a text editor.
Uncomment the line that starts DWEB_PASSWD_FILE = by removing the pound sign (#) from the beginning of the line.
Decide the pathname of the file that will contain the password information. Add the absolute pathname of the file as the value of DWEB_PASSWD_FILE.
Note: Remember to place the password file above dynaweb/servroot, to prevent browsers from accessing it. Restart the DynaWeb server:
# /etc/init.d/dynaweb stop # /etc/init.d/dynaweb start
Add a user to the access list with dwpasswd by giving this command:
# /usr/lib/Insight/dweb/bin/dwpasswd passwdfile -a [user [password [' name']]] |
passwdfile is the name of the password file you specified in step 3 in the section “Enabling HTTP Authentication.”
If you omit the information after the -a, dwpasswd prompts you to enter it. When entering the real name of the user at the prompt, you do not need to put quotations around the name. Once you have entered all the information, dwpasswd prompts you to repeat the process. To exit the program, press the <Enter> key without entering a user name.
Verify that a user has access to the DynaWeb server with this dwpasswd command:
# /usr/lib/Insight/dweb/bin/dwpasswd passwdfile -v [user [password]] |
passwdfile is the name of the password file you specified in step 3 in the section “Enabling HTTP Authentication.” The program reports whether that name and password are valid.
If you do not specify a user name, dwpasswd prompts you to do so. You are asked to enter the password for that user twice.
To delete a user from the password file, follow this procedure:
Open the password file for editing. The location of the password file is specified in the file /usr/lib/Insight/dweb/data/config/dynaweb.cfg.tmpl by the DWEB_PASSWD_FILE parameter. The password file is an NCSA-style password file.
Remove the line containing the user's information.
Write the file and exit the editor. That user is no longer able to access the server.