<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE>HOWTO Use Catacomb with Apache</TITLE>
</HEAD>
<BODY>
<H1>HOWTO Use Catacomb with Apache</H1>
<H2>GRASE Lab at UCSC <CODE>grase (at) cse.ucsc.edu</CODE> </H2>0.01, 2002-8-30
<P><HR>
<EM>
<!--
(your index root)
-->
This is a brief explanation about Catacomb. This explains what is Catacomb, howto install it and how to use it. The enables the SEARCH method which is specified in the DASL protocol. The Catacomb is a module for
<A HREF="http://httpd.apache.org">Apache</A> and repository interface of
<A HREF="http://www.webdav.org/mod_dav">mod_dav</A>.</EM>
<HR>
<H2><A NAME="s1">1. Introduction</A></H2>
<P>
<!--
(your index root)!introduction
-->
There are many web servers. Suppose you have one web server which has millions of documents.
How would you find find particular documents whose author is Jim and which contain a key word such as <EM>java</EM>.
A Catacomb is a perfect solution for that.
<P>
<P>The Web-DAV protocol is an extension of HTTP and it enables the user to write to the HTTP server, give properties for resources and other functions.
DASL is extension of Web-DAV and it enables the user to search resources in the Web server.
Catacomb is a DASL implementation for Apache and mod_dav.
<P>This document explains how to install the Catacomb module and use it.
<P>
<H2>1.1 Copyright</H2>
<P>
<BLOCKQUOTE><CODE>
<PRE>
Copyright (c) 2002, The Regents of the University of California.
The Regents of the University of California MAKE NO REPRESENTATIONS OR
WARRANTIES ABOUT THE SUITABILITY OF THE SOFTWARE, EITHER EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR
NON-INFRINGEMENT. The Regents of the University of California SHALL
NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF
USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H2><A NAME="s2">2. What is Catacomb?</A></H2>
<P>Briefly, it is :
<UL>
<LI>DASL implementation for mod_dav and Apache.</LI>
<LI>MYSQL Back-ended storage system.</LI>
</UL>
DASL specifies the SEARCH method for searching and locating resources.
In other words, it enables the user to search resources in the web server using the DASL protocol.
Catacomb is the implementation of DASL which allows web server to support a search function.
<P>
To implement the search function,
Catacomb uses MySQL. That means if you are saving some resources using PUT or MKCOL which are Web-DAV methods,
all of the resources and their information are saved in not a file system, but in DBMS.
<P>
<H2><A NAME="s3">3. Installation</A></H2>
<P>
<H2>3.1 What do I need?</H2>
<P>You need :
<UL>
<LI>Linux or Unix system which can be installed Apache.</LI>
<LI>Apache 2.0.36 or higher version.</LI>
<LI>MySQL 3.2.33 or higher version.</LI>
<LI>mod_dav_respo latest version.</LI>
</UL>
<P>
<H2>3.2 Quick Tour</H2>
<P>We assume that your MySQL is installed in the /usr/local directory.
<BLOCKQUOTE><CODE>
<PRE>
<shell> tar xvfz httpd-2.0.36.tar.gz
<shell> cd http-2.0.36
<shell> ./configure --enable-dav --enable-so
<shell> make; make install
<shell> cd ..
<shell> tar xvfz catacomb-x.x.x.tar.gz
<shell> cd catacomb-x.x.x
<shell> ./configure --with-apache=/usr/local/apache2 --with-mysql=/usr/local
<shell> make; make install
<shell> add this in /usr/local/apache2/conf/httpd.conf
___________________________________________________________
|# This is server configure now |
|DavDBMSHost localhost |
|DavDBMSDbName repos |
|DavDBMSId root |
|DavDBMSPass root |
|DavDBMSTmpDir /tmp/ |
| |
|<Location /repos> |
|DAV repos |
|<//Location> |
-----------------------------------------------------------
<shell> mysqladmin create repos
<shell> mysql repos < table.sql
<shell> mysql repos < data.sql
<shell> /usr/local/apache2/bin/apachectl start
</PRE>
</CODE></BLOCKQUOTE>
Enjoy DASLed Apache server!
<P>
<H2>3.3 Installation</H2>
<P>You need MySQL, and you can download it from the
<A HREF="http://www.mysql.org">MySQL Web Site</A>.
I assume that MySQL is already installed on your machine. There is no special MySQL option for mod_dav_dasl,
so you don't need to reinstall MySQL for Catacomb, if MySQL is already installed.
If you have some difficulties to install MySQL, please visit the MySQL homepage.
The default MySQL installation directory is /usr/local.
<P>You need Apache 2.0.36 or later version for Catacomb.
You can download the latest Apache server from the
<A HREF="http://www.apache.org">Apache Web Site</A>.
When you install Apache, we need two options, --enable-dav and --enable-so.
Catacomb is a mod_dav interface, so we need to enable mod_dav.
The Catacomb object is a shared style object, so your Apache must support shared objects.
The default Apache installation directory is /usr/local/apache2.
You can enable two option by configuring with this command:
<BLOCKQUOTE><CODE>
<PRE>
<shell> ./configure --enable-dav --enable-so
</PRE>
</CODE></BLOCKQUOTE>
<P>
Now, it is time to install Catacomb.
You can download the latest version from the
<A HREF="http://www.webdav.org/catacomb">Catacomb project Web Site</A>.
Untar the source.
When you configure the Catacomb, you need to select two options, --with-apache and --with-mysql.
Using --with-mysql option, you need to specify the mysql C client library directory,
and using --with-apache, you will specify the apache directory.
The default directory is the /usr/local directory for MySQL and the /usr/local/apach2 directory for Apache.
<P>After finishing the configuration, you can do make and make install.
<P>
<H2>3.4 Configuration</H2>
<P>We need two configurations such as:
<UL>
<LI>Apache configuration.</LI>
<LI>DBMS initialization.</LI>
</UL>
<P>You want to add these lines into the /usr/local/apache2/conf/httpd.conf file.
<P>
<BLOCKQUOTE><CODE>
<PRE>
___________________________________________________________
|# This is server configure now |
|DavDBMSHost localhost |
|DavDBMSDbName repos |
|DavDBMSId root |
|DavDBMSPass root |
|DavDBMSTmpDir /tmp/ |
| |
|<Location /repos> |
|DAV repos |
|<//Location> |
-----------------------------------------------------------
</PRE>
</CODE></BLOCKQUOTE>
Here are the directive explanations:
<UL>
<LI>DavDBMSHost: specify your MySQL server.</LI>
<LI>DavDBMSDbName: Your DB name. To make new DB for Catacomb is recommended.</LI>
<LI>DavDBMSId: User id for the DB. Make sure the user has proper permission for the DB.</LI>
<LI>DavDBMSPass: User password for the id. If your id doesn't have a password, just omit DavDBMSPass directive. </LI>
<LI>DavDBMSTmpDir: Catacomb needs a temporary directory to manipulate the files. Make sure your HTTP daemon has writing permission in the directory.</LI>
<LI> Location specifies the URI information. You need to specify DAV provider as "repos".</LI>
</UL>
<P>Second configuration job is creating DB and tables for mod_dav_dasl.
DB which is already exist for other usage is reusable for Catacomb,
but creating a new DB for Catacomb is strongly recommend.
You can create new DB using the mysqladmin command:
<BLOCKQUOTE><CODE>
<PRE>
<shell>mysqladmin create repos
</PRE>
</CODE></BLOCKQUOTE>
This command will create DB named repos.
There are several tables used by Catacomb.
You can create tables by importing table.sql in the Catacomb source directory using this command:
<BLOCKQUOTE><CODE>
<PRE>
<shell>mysql repos < table.sql
</PRE>
</CODE></BLOCKQUOTE>
You might need -u and -p options for MySQL, if you specified a database user for the DB.
Finally, you need to import data for your root information of the Catacomb enabled directory.
In our example, the directory name is /repos.
If you specified different directory name, you need to edit data.sql in the Catacomb source directory.
Also, if you have more than two directory directives for Catacomb,
you need to import data.sql several times with different directory data.
This is the example of data.sql.
<BLOCKQUOTE><CODE>
<PRE>
INSERT INTO dasl_resource VALUES
(1,'','/repos',651165539,'(null)','(null)',0,'httpd/unix-directory',
'(null)',1014759103979654,'(null)',1,0,'(null)',1,2,NULL,'1234567890');
</PRE>
</CODE></BLOCKQUOTE>
Make sure the third arguments in the example (/repos) is same as your Location in httpd.conf.
You want to import the data.sql using this command:
<BLOCKQUOTE><CODE>
<PRE>
<shell>mysql repos < data.sql
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H2>3.5 Fire your Apache.</H2>
<P>
<BLOCKQUOTE><CODE>
<PRE>
<shell>/usr/local/apache2/bin/apachectl start
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H2><A NAME="s4">4. DASL Clients</A></H2>
<P>If you want to test your DASLed server very quickly, the simplest and best way is using telnet.
Do telnet to your server and the port.
Let's suppose our DASLed server is ocean.cse.ucsc.edu and port is 7777. We can test by typing the OPTION method:
<BLOCKQUOTE><CODE>
<PRE>
ocean 10> telnet ocean.cse.ucsc.edu 7777
Trying 128.114.51.104...
Connected to ocean.cse.ucsc.edu.
Escape character is '^]'.
OPTIONS /dasl/ HTTP/1.1
Host: ocean.cse.ucsc.edu
HTTP/1.1 200 OK
Date: Wed, 08 May 2002 09:16:13 GMT
Server: Apache/2.0.36-dev (Unix) DAV/2 DASL/0.1
DAV: 1
DAV: <http://apache.org/dav/propset/fs/1>
MS-Author-Via: DAV
Allow: OPTIONS,GET,HEAD,POST,DELETE,TRACE,PROPFIND,PROPPATCH,COPY,MOVE,SEARCH
DASL: <DAV:basicsearch>
Content-Length: 0
Content-Type: text/plain; charset=ISO-8859-1
</PRE>
</CODE></BLOCKQUOTE>
If you can see SEARCH method in Allow field in the response, your DASLed server is working properly.
<P>
<P>
<P>
<H2>4.1 Read/Write resources</H2>
<P>Unfortunately, you can not copy resources or make directory directly like usual Apache file system directories,
since Catacomb use MySQL to save all resources and their data.
So you need to use Web-DAV client to read/write your resources in the DASLed server.
There are many WebDAV client programs. You can use one of these client and read/write your resources.
If you want to only read your resources, a web browser are a good tool.
For more information about WebDAV software, visit the
<A HREF="http://www.webdav.org/">WebDAV resource site</A>.
<P>
<H2>4.2 Search</H2>
<P>So far, there is not many DASL clients. When we write this HOWTO, cadaver DASL patch is on developing.
The cadaver client will support DASL, when you read this HOWTO.
Hopefully there will be lots of DASL clients very soon.
<P>
<H2><A NAME="s5">5. Trouble shooting.</A></H2>
<P>If your DASLed server doesn't work properly, reading error_log in the Apache's log directory is good idea.
Here are simple check lists:
<UL>
<LI>Did you configure Apache with --enable-so and --enable-dav option?</LI>
<LI>MySQL demon is running before Apache server is running?</LI>
<LI>Did you specify the right DB information in httpd.conf?</LI>
<LI>Temporary directory which is specified httpd.conf is readable and writable?</LI>
<LI>...</LI>
</UL>
<P>
<H2><A NAME="s6">6. Conclusion</A></H2>
<P>Catacomb project is just started, so we have lots of thing to do and to improve though. I hope Catacomb and this HOWTO could help your Internet environment.
<P>
<H2>6.1 Call for participation</H2>
<P>Catacomb is open source project under Apache License. So anybody is welcome to the project.
Please content to
<A HREF="mailto:catacomb(at)webdav.org">catacomb(at)webdav.org</A>, if you have interest.
<P>
<P>
</BODY>
</HTML>
