ch49.htm

linux-unix130.linux.and.unix.ebooks130 linux and unix ebookslinuxLearning Linux - Collection of 12 E

		<TD WIDTH="15%" VALIGN="TOP"><TT>doc</TT></TD>

		<TD WIDTH="76%" VALIGN="TOP">Doc files, help files, and FAQs</TD>

	</TR>

	<TR>

		<TD WIDTH="9%" VALIGN="TOP">

			<UL>

				<LI>&#160;

			</UL>

		</TD>

		<TD WIDTH="15%" VALIGN="TOP"><TT>include</TT></TD>

		<TD WIDTH="76%" VALIGN="TOP">Header files used by the compiler</TD>

	</TR>

	<TR>

		<TD WIDTH="9%">

			<UL>

				<LI>&#160;

			</UL>

		</TD>

		<TD WIDTH="15%"><TT>lib</TT></TD>

		<TD WIDTH="76%">Library files</TD>

	</TR>

	<TR>

		<TD WIDTH="9%">

			<UL>

				<LI>&#160;

			</UL>

		</TD>

		<TD WIDTH="15%"><TT>man</TT></TD>

		<TD WIDTH="76%">Man pages</TD>

	</TR>

	<TR>

		<TD WIDTH="9%">

			<UL>

				<LI>&#160;

			</UL>

		</TD>

		<TD WIDTH="15%"><TT>Src</TT></TD>

		<TD WIDTH="76%">WAIS source code</TD>

	</TR>

	<TR>

		<TD WIDTH="9%">

			<UL>

				<LI>&#160;

			</UL>

		</TD>

		<TD WIDTH="15%"><TT>Wais-Sources</TT></TD>

		<TD WIDTH="76%">Directory of Internet servers</TD>

	</TR>

	<TR>

		<TD WIDTH="9%">

			<UL>

				<LI>&#160;

			</UL>

		</TD>

		<TD WIDTH="15%"><TT>Wais-Test</TT></TD>

		<TD WIDTH="76%">Sample indexer and service scripts</TD>

	</TR>

</TABLE>

<BR>

Once you have fine-tuned the configuration file information, you can compile the

freeWAIS source with the <TT>make</TT> command:</P>

<PRE><FONT COLOR="#0066FF">make linux

</FONT></PRE>

<P>By default, the <TT>make</TT> utility compiles two clients called <TT>swais</TT>

and <TT>waisq</TT>. If you want to compile an X version of WAIS called <TT>xwais</TT>

(useful if you want to allow access from X terminals or consoles), uncomment the

line in the <TT>Makefile</TT> that ends with <TT>makex</TT>.

<CENTER>

<H3><A NAME="Heading8<FONT COLOR="#000077">Setting Up freeWAIS</FONT></H3>

</CENTER>

<P>When you have the compiled freeWAIS components installed and configured properly,

you can begin setting up the WAIS index files to documents available on your system.

This is usually done by creating an index directory with the default name of <TT>wsindex</TT>.

The directory usually resides just under the root of the file system (<TT>/wsindex</TT>)

but many administrators like to keep it in a reserved area for the WAIS software

(such as <TT>/usr/wais/wsindex</TT>). If the index files are difficult to locate,

users may have problems when they try to find them.</P>

<P>The <TT>wais-test</TT> directory created when you installed freeWAIS contains

a script called <TT>test.waisindex</TT> that creates four WAIS index files automatically

for you. These are used to test the WAIS installation for proper functionality, as

well as to show you how you can use the different search and index capabilities of

freeWAIS. The following are the four index files:<BR>



<TABLE BORDER="0" WIDTH="100%">

	<TR>

		<TD WIDTH="9%" VALIGN="TOP">

			<UL>

				<LI>&#160;

			</UL>

		</TD>

		<TD WIDTH="15%" VALIGN="TOP"><TT>test-BOOL</TT></TD>

		<TD WIDTH="76%" VALIGN="TOP">Index of three example documents using the Boolean capabilities and synonyms</TD>

	</TR>

	<TR>

		<TD WIDTH="9%" VALIGN="TOP">

			<UL>

				<LI>&#160;

			</UL>

		</TD>

		<TD WIDTH="15%" VALIGN="TOP"><TT>test-Comp</TT></TD>

		<TD WIDTH="76%" VALIGN="TOP">Index demonstrating compressed source file handling</TD>

	</TR>

	<TR>

		<TD WIDTH="9%" VALIGN="TOP">

			<UL>

				<LI>&#160;

			</UL>

		</TD>

		<TD WIDTH="15%" VALIGN="TOP"><TT>test-Docs</TT></TD>

		<TD WIDTH="76%" VALIGN="TOP">Index of files in the <TT>doc</TT> directory showing recursive directory search</TD>

	</TR>

	<TR>

		<TD WIDTH="9%" VALIGN="TOP">

			<UL>

				<LI>&#160;

			</UL>

		</TD>

		<TD WIDTH="15%" VALIGN="TOP"><TT>test-Multi</TT></TD>

		<TD WIDTH="76%" VALIGN="TOP">Index of GIF images and multi-document capabilities</TD>

	</TR>

</TABLE>

<BR>

Only graphically based (usually X-based) browsers can handle the <TT>Multi</TT> document

formats, although any type of browser should be able to handle the other three index

formats.</P>

<P>Once you have verified that the indexing system works properly and all the components

of freeWAIS are properly installed, you need to build an index file for the documents

available on your system. Do this with the <TT>waisindex</TT> command. The <TT>waisindex</TT>

command enables you to index files two ways using the <TT>-t</TT> option, followed

by one of these keywords:<BR>



<TABLE BORDER="0">

	<TR>

		<TD WIDTH="9%" VALIGN="TOP">

			<UL>

				<LI>&#160;

			</UL>

		</TD>

		<TD WIDTH="15%" VALIGN="TOP"><TT>one_line</TT></TD>

		<TD WIDTH="76%" VALIGN="TOP">Index each line of a document so a match can show the exact line the match occurred

			in.</TD>

	</TR>

	<TR>

		<TD WIDTH="9%" VALIGN="TOP">

			<UL>

				<LI>&#160;

			</UL>

		</TD>

		<TD WIDTH="15%" VALIGN="TOP"><TT>text</TT></TD>

		<TD WIDTH="76%" VALIGN="TOP">Index so a match shows the entire document with no indication of the exact line the

			match occurred in. This is the default option.</TD>

	</TR>

</TABLE>

<BR>

The <TT>waisindex</TT> command takes arguments for the name of the destination index

file (<TT>-d</TT> followed by the filename), and the directory or files to be indexed.

For example, to index a directory called <TT>/usr/sales/sales_lit</TT> into a destination

index file called <TT>sales</TT>, using the <TT>one_line</TT> indexing approach,

you would issue this command:</P>

<PRE><FONT COLOR="#0066FF">waisindex -d sales -t one_line /usr/sales/sales_lit

</FONT></PRE>

<P>Because there is no path provided for the <TT>sales</TT> index file in this example,

it would be stored in the current directory.</P>

<P>Once your WAIS server is running (see the section entitled &quot;Starting freeWAIS&quot;),

you can test the indexes by using the <TT>waissearch</TT> command. For example, to

look for the word &quot;WAIS&quot; in the index files, issue the command</P>

<PRE><FONT COLOR="#0066FF">waissearch -p 210 -d index_file WAIS

</FONT></PRE>

<P>where <TT>-p</TT> gives the port number (default value is 210), and <TT>-d</TT>

is the path to the index file. If the search is successful (and you have something

that matches) you will see messages about the number of records returned and the

scores of each match. If you see error messages or nothing, check the configuration

information and the index files.</P>

<P>A final step you can take if you want your freeWAIS system to be accessible by

Internet users is to issue the command</P>

<PRE><FONT COLOR="#0066FF">waisindex -export -register Filenames

</FONT></PRE>

<P>where Filenames is the name of the index. This will be registered with the Directory

of Servers at <TT>cnidr.org</TT> and <TT>quake.think.com</TT>. These addresses are

reached automatically with the <TT>-register</TT> option. Only do this step if you

want all Internet users to access your WAIS service. (We will look at the <TT>waisindex</TT>

command in much more detail shortly.)</P>

<P>If you want to enable clients to connect to your freeWAIS system with a WWW browser

(such as Mosaic or Netscape), you must issue the following command:</P>

<PRE><FONT COLOR="#0066FF">waisindex -d WWW -T HTML -contents -export /usr/resources/*html

</FONT></PRE>

<P>Replace the <TT>/usr/resources</TT> path with the path to your HTML files. This

line allows WAIS clients to perform keyword searches on HTML documents, as well.</P>

<P>If you want, you can set WAIS to allow only certain domains to connect to it.

This is done in the <TT>ir.h</TT> file, which has a line like this:</P>

<PRE><FONT COLOR="#0066FF">#define SERVSECURITYFILE   &quot;SERV_SEC&quot;

</FONT></PRE>

<P>You have to place a copy of an existing <TT>SERV_SEC</TT> file or one you create

yourself in the same directory as the WAIS index files. If there is no <TT>SERV_SEC</TT>

file accessible to WAIS, all domains are allowed access. (You can change the name

of the file, of course, as long as the entry in <TT>ir.h</TT> matches the filename

with quotation marks around it.)</P>

<P>Each ASCII entry in the <TT>SERV_SEC</TT> file follows a strict format for defining

the domains that are granted access to WAIS. This is the format of each line:</P>

<PRE><FONT COLOR="#0066FF">domain   [IP address]

</FONT></PRE>

<P>Each line has the domain name of the host that you want to grant access to with

its IP address as an optional add-on to the line. If the domain name and IP address

do not match, it doesn't matter because WAIS allows access to a match either of name

or of address. A sample <TT>SERV_SEC</TT> file looks likes this:</P>

<PRE><FONT COLOR="#0066FF">chatton.com

roy.sailing.org

bighost.bignet.com

</FONT></PRE>

<P>Each of these three domain names can access WAIS, while any connection from a

host without these domain names is refused.</P>

<P>The <TT>SERV_SEC</TT> file should be owned and accessible only by the user that

the freeWAIS system is running as (it should not be run as root to avoid security

problems), and the file should be modifiable only by root.</P>

<P>Similar to the <TT>SERVSECURITYFILE</TT> variable is <TT>DATASECURITYFILE</TT>,

which controls access to the databases. There is a line in the <TT>ir.h</TT> file

that looks like this:</P>

<PRE><FONT COLOR="#0066FF">#define DATASECURITYFILE   &quot;DATA_SEC&quot;

</FONT></PRE>

<P>where <TT>DATA_SEC</TT> is a file listing each database file and the domains that

have access to it. The file should reside in the same directory as the index files.

The format of the <TT>DATA_SEC</TT> file is</P>

<PRE><FONT COLOR="#0066FF">database   domain   [IP address]

</FONT></PRE>

<P>where database is the name of the database the permissions refer to, and domain

and the optional <TT>I</TT>P address are the same as the <TT>SERV_SEC</TT> file.

A sample <TT>DATA_SEC</TT> file looks like this:</P>

<PRE><FONT COLOR="#0066FF">primary   chatton.com

primary   bignet.org

primary   roy.sailing.org

sailing   roy.sailing.org 

</FONT></PRE>

<P>In this example, three domains are granted access to a database called <TT>primary</TT>

(note that <TT>primary</TT> is just a filename and has no special meaning), while

one domain has specific access to the database called <TT>sailing</TT> as well as

<TT>primary</TT>. If you want to allow all hosts with access to the system (controlled

by <TT>SERV_SEC</TT>) to access a particular database, you can use asterisks in the

domain name and IP address fields. For example, the entries</P>

<PRE><FONT COLOR="#0066FF">primary   *   *

sailing   roy.sailing.org

</FONT></PRE>

<P>allow anyone with access to WAIS to use the <TT>primary</TT> database, with only

one domain allowed access to the <TT>sailing</TT> database.</P>

<P>In both the <TT>SERV_SEC</TT> and <TT>DATA_SEC</TT> files, you have to be careful

with the IP addresses to avoid inadvertently granting access to hosts you really

don't want on your system. For example, if you specify the IP address 150.12 in your

file, then any IP addresses from 150.12 through 150.120, 151.121, and so on, are

also granted access because they match the IP components. Specify IP addresses explicitly

to avoid this problem.

<CENTER>

<H3><A NAME="Heading9<FONT COLOR="#000077">Starting freeWAIS</FONT></H3>

</CENTER>

<P>As with the FTP services, you can set freeWAIS to start up when the system boots,

by using the <TT>rc</TT> files from the command line at any time, or you can have

the processes started by <TT>inetd</TT> when a service request arrives. If you want

to start freeWAIS from the command line, you need to specify a number of options.

A sample startup command line looks like this:</P>

<PRE><FONT COLOR="#0066FF">waisserver -u username -p 210 -l 10 -d /usr/wais/wais_index

</FONT></PRE>

<P>The <TT>-u</TT> option tells <TT>waisserver</TT> to run as the user <TT>username</TT>

(which has to be a valid user in <TT>/etc/passwd</TT>, of course), the <TT>-p</TT>

option tells <TT>waisserver</TT> what port to use (the default is 210, as shown in

the <TT>/etc/services</TT> file), and the <TT>-d</TT> option shows the default location

of WAIS indexes. If you want to invoke logging of sessions to a file, use the <TT>-e</TT>

option followed by the name of the logfile.</P>

<P>You should run <TT>waisserver</TT> as another user instead of root to prevent

holes in the WAIS system from being exploited by a hacker. If the service is run

as a standard user (such as <TT>wais</TT>), only the files that the user would have

access to would be in jeopardy.</P>

<P>If the port for <TT>waisserver</TT> is set to 210, the service corresponds to

the Internet standards for access. If you set the value to another port, you can

configure the system for local area access only. If the port number is less than

1023, the WAIS service must be started and managed by root, but any port over 1023