Installing and using mod_roaming
--------------------------------

Installing and using mod_roaming compromises three steps:
1. Linking the mod_roaming module with Apache.
2. Configuring the mod_roaming module.
3. Configuring Netscape Communicator

The following requirements exists for installing and using mod_roaming:
* Apache 1.3.2 or higher. The default directory layout (Apache) of
  Apache 1.3.4 is assumed in this guide. Change the filenames at will.
* A C compiler.
* Netscape Communicator or Navigator 4.5 or higher.

If you run into problems, check the Known Problems section at the end.

Linking the mod_roaming module with Apache
==========================================
Depending upon the way your Apache is configured, choose one of the
following methods:
1. Build a DSO module, if you built Apache with DSO support
   (recommended).
2. Build a static module by calling the configure script, if you used
   APACI to configure Apache.
3. Build a static module by editing the Configuration file, if you used
   the old-style way to configure Apache.

Bulding a DSO module
--------------------
1. Change the current directory to the directory that contains
mod_roaming.c

2. Execute the following command:
> apxs -i -a -c mod_roaming.c
   The module will be compiled, installed in the libexec directory of
   your configuration and the httpd.conf file will be updated. The
   apxs command can be found in the directory that also contains
   apachectl, typically PREFIX/sbin.

Building a static module by calling the configure script
--------------------------------------------------------
1. Change the current directory to the directory containing your apache
   source distribution.

2. Call the configure script as you normally would and add the switch
--add-module=<path-to-mod_roaming-directory>/mod_roaming.c

3. Make sure the build environment is clean by issuing the following
   command:
> make clean

4. Build the new httpd binary with:
> make

5. Install the new httpd binary with:
> make install

Building a static module by editing the Configuration file
----------------------------------------------------------
1. Change the current directory to the src subdirectory of your apache
   source distribution.

2. Copy mod_roaming.c to the subdirectory modules/extra.

3. Add the following line to the file Configuration:
AddModule modules/extra/mod_roaming.o

4. Build new Makefiles etc. by issuing the following command:
> ./Configure

5. Make sure the build environment is clean by issuing the following
   command:
> make clean

6. Build the new httpd binary with:
> make

7. Install the new httpd binary with:
> make install


Configuring mod_roaming
=======================
1. Edit your httpd.conf file and add a line like the following:
RoamingAlias /roaming /usr/local/apache/roaming

   The first argument is the uri prefix that mod_roaming will respond
   to, the second argument is the directory where the roaming access
   files will be stored. Make sure the webserver has write permissions
   to this directory. Preferrably, no other user should have read or
   write permissions to this directory to protect the privacy of the
   users.

   A subdirectory is automatically created for each user, e.g. the
   roaming access files for user vinny will be stored under
/usr/local/apache/roaming/vinny
   and can be accessed via
http://<host>/roaming/vinny/...

   Multiple mod_roaming directives may be used to set up multiple
   roaming uri's. You do not have to set up directories for the
   individual users. These are automatically created the first
   time someone uses Roaming Access.

2. Make sure that any requests made to the roaming directory are
   authorized. You can do this in a number of different ways:
   a. by putting a .htaccess file in the roaming directory (e.g.
      /usr/local/apache/roaming). If you do this, make sure
      Apache is reading the .htaccess file and the directives in it
      are allowed (AllowOverride AuthConfig),
   b. by putting a
      <Directory /usr/local/apache/roaming>
      block in httpd.conf, or
   c. by putting a
      <Location /roaming>
      block in httpd.conf.

   This file or block should contains something like this:
AuthUserFile /usr/local/apache/conf/roaming-htpasswd
AuthType Basic
AuthName "Roaming Access"
<Limit GET PUT MOVE DELETE>
	require valid-user
</Limit>

   The roaming-htpasswd can be created by using the htpasswd program
   that comes with the Apache distribution. Try accessing the URL
   http://<host>/roaming/<userid>/liprefs to check whether
   authentication has been configurated correctly.

   These steps make sure access to the roaming files is authenticated.
   However, basic authentication is very weak and passwords can be
   snooped from the connection. SSL would be even better, but Netscape
   Communicator 4.5 refuses to connect to https URL's when they are
   entered as the Roaming URL.

   If you want to use your regular Unix password for authentication
   you may want to look into Howard Fear's mod_auth_sys module:
   <URL:http://kw2.knightweb.com/~hsf/sources/mod_auth_sys/>

3. Stop Apache and start it again (restarting after rebuilding a DSO
   module sometimes causes Apache to hang or crash).

Configuring Netscape Communicator
=================================
There are two ways roaming access can be enabled with Netscape
Communicator:
1. You can change an existing user profile to use the Roaming Access
   server
2. You can create a new user profile that uses the settings on a Roaming
   Access server.

Enabling Roaming Access for an existing user profile
----------------------------------------------------
1. Start Netscape Communicator.

2. Open the Preferences dialog.

3. Go to the "Roaming Access" pane.

4. Check the "Enable Roaming Access for this profile" checkbox.

5. Enter your username below and optionally check the "Remember my
   roaming password" checkbox.

6. Go to the "Server Info" pane.

7. Select the "HTTP Server" radio button.

8. Enter the Roaming URL, e.g.
http://www.foo.com/roaming/vinny
   You can replace the userid with the string $USERID or %USERID% to
   let Netscape Communicator replace it with the userid entered in the
   previous pane.

9. Go to the "File Selection" pane.

10. Select the files you want to be stored on the Roaming Access server.
    Depending upon your trust of the network and the server you may or
    may not want to store the Java Security or Certificates and Private
    Keys file on the Roaming Access Server. Storing the History file on
    the server may not be very useful and may consume valuable bandwidth.

Known problems
==============
The following known and unresolved issues exist with mod_roaming
and Roaming Access:

* Loading mod_roaming as a DSO module on Debian GNU/Linux fails with an
  error message like:
Cannot load /usr/local/apache/libexec/mod_roaming.so into server:
/usr/local/apache/libexec/mod_roaming.so: undefined symbol: stat
  Luc Stepniewski reported he has managed to build a DSO module with:
> gcc -DLINUX=2 -DUSE_HSREGEX -fpic -DSHARED_MODULE
  -I/usr/local/apache/include -c mod_roaming.c
> ld -Bshareable -o mod_roaming.so mod_roaming.o -lc -lm -lcrypt

* There can be problems when you access the Roaming Access server
  through a proxy. Roaming Access uses the non-standard HTTP MOVE
  request method to atomically update the files. Some proxies
  (including Squid) do not pass these requests through to the
  server. If you cannot bypass by the proxy by putting the roaming
  server in the "Do not use proxies for domains beginning with"
  list, one way to get around this is to add the line
user_pref("li.server.http.useSimplePut", true);
  to your Preferences file. However, I have used before and it
  gives a lot of hassle (sometimes it disappears and reverts
  back to the old way of doing things).

* The MacOS versions of Netscape crash when accessing the roaming
  profile on Apache 1.3.12 w/ mod_roaming. It seems to be caused
  by the fact that Apache 1.3.12 adds an explicit "charset=iso-8859-1"
  to the authentication challenge page. Although this problem was
  introduced with Apache 1.3.12, it is really a bug in Netscape.
  But, until that bug is fixed, you can fix the problem by changing
  line 2588 in src/main/http_protocol.c from
    r->content_type = "text/html; charset=iso-8859-1";
  to
    r->content_type = "text/html";
  and recompiling Apache.

