NAME

Apache::Roaming - A mod_perl handler for Roaming Profiles

SYNOPSIS

    # Configuration in httpd.conf or srm.conf
    # Assuming DocumentRoot /home/httpd/html

    PerlModule Apache::Roaming
    <Location /roaming>
      PerlHandler Apache::Roaming->handler
      PerlTypeHandler Apache::Roaming->handler_type
      AuthType Basic
      AuthName "Roaming User"
      AuthUserFile /home/httpd/.htusers
      require valid-user
      PerlSetVar BaseDir /home/httpd/html/roaming
    </Location>

In theory any AuthType and require statement should be possible
as long as the $r->connection()->user() method returns something
non trivial.

DESCRIPTION

With Apache::Roaming you can use your Apache webserver as a Netscape Roaming Access server. This allows you to store you Netscape Communicator 4.5 preferences, bookmarks, address books, cookies etc. on the server so that you can use (and update) the same settings from any Netscape Communicator 4.5 that can access the server.

The source is based on mod_roaming by Vincent Partington <vincentp@xs4all.nl>, see

http://www.xs4all.nl/~vincentp/software/mod_roaming.html

Vincent in turn was inspired by a Perl script from Frederik Vermeulen <Frederik.Vermeulen@imec.be>, see

http://www.esat.kuleuven.ac.be/~vermeule/roam/put

Compared to Apache::Roaming, this script doesn't need mod_perl. On the other hand it doesn't support the MOVE method, thus you need to set the li.prefs.http.useSimplePut attribute in your Netscape preferences. Due to the missing MOVE method, it may be even slower than Apache::Roaming and perhaps a little bit less stable.

The modules features are:

GET, HEAD, PUT, DELETE and MOVE are handled by the module. In particular the Non-standard MOVE method is implemented, although Apache doesn't know it by default. Thus you need no set the li.prefs.http.useSimplePut attribute to true.
Directories are created automatically.
The module is subclassable, so that you can create profiles on the fly or parse and modify the user preferences. See Apache::Roaming::LiPrefs(3) for an example subclass.

INSTALLATION

First of all you need an Apache Web server with mod_perl support. The TypeHandler must be enabled, so you need to set PERL_TYPE=1 when running Makefile.PL. For example, I use the following statements to build Apache:

    cd mod_perl-1.16
    perl Makefile.PL APACHE_SRC=../apache_1.3.X/src DO_HTTPD=1 \
        USE_APACI=1 PERL_METHOD_HANDLERS=1 PERL_AUTHEN=1 \
        PERL_CLEANUP=1 PREP_HTTPD=1 PERL_STACKED_HANDLERS=1 \
	PERL_FILE_API=1
    cd ../apache-1.3.3
    ./configure --activate-module=src/modules/perl/libperl.a
    make
    make install
    cd ../mod_perl-1.16
    make
    make install

See the mod_perl docs for details.

Once the web server is installed, you need to create a directory for roaming profiles, I assume /home/httpd/html/roaming in what follows, with /home/httpd/html being the servers root directory. Be sure, that this directory is writable for the web server, better for the web server only. For example I do

mkdir /home/httpd/html/roaming
chown nobody /home/httpd/html/roaming
chgrp nobody /home/httpd/html/roaming
chmod 700 /home/httpd/html/roaming

with nobody being the web server user.

Access to the roaming directory must be restricted and enabled via password only. Finally tell the web server, that Apache::Roaming is handling requests to this directory by adding something like this to your srm.conf or access.conf:

PerlModule Apache::Roaming
<Location /roaming>
  PerlHandler Apache::Roaming->handler
  PerlTypeHandler Apache::Roaming->handler_type
  AuthType Basic
  AuthName "Roaming User"
  AuthUserFile /home/httpd/.htusers
  require valid-user
  PerlSetVar BaseDir /home/httpd/html/roaming
</Location>

That's it!

NETSCAPE COMMUNICATOR CONFIGURATION

Assuming your document root directory is /home/httpd/html and you want your profile files being located under http://your.host/roaming, do the following:

1.)

Create a directory /home/httpd/html/roaming. Make it writable by the web server and noone else, for example by doing a

    mkdir /home/httpd/html/roaming
    chown nobody /home/httpd/html/roaming
	# Insert your web servers UID here
    chmod 700 /home/httpd/html/roaming

2.)

Start your communicator and open Preferences/Roaming User. Click the "Enable Roaming Access for this profile" checkbox.

3.)

Open Preferences/Roaming User/Server Information. Click the "HTTP Server" checkbox and enter the Base URL "http://your.host/roaming/$USERID".

That's all. Now hit the Ok button. A directory with the name of your user id should automatically be generated under /roaming and files should be stored there.

METHOD INTERFACE

As already said, the Apache::Roaming module is subclassable. You can well use it by itself, but IMO the most important possibility is overwriting the GET method for complete control over the users settings.

handler

$result = Apache::Roaming->handler($r);

(Class Method) The handler method is called by the Apache server for any request. It receives an Apache request $r. The methods main task is creating an instance of Apache::Roaming by calling the new method and then passing control to the Authenticate, CheckDir and GET, PUT, DELETE or MOVE, respectively, methods.

handler_type

$status = Apache::Roaming->handler_type($r)

(Class Method) This method is required only, because the Apache server would refuse other methods than GET otherwise. It checks whether the requested method is GET, PUT, HEAD, DELETE or MOVE, in which case it returns the value OK. Otherwise the value DECLINED is returned.

new

$ar_req = Apache::Roaming->new(%attr);

(Class Method) This is the modules constructor, called by the handler method. Instances of Apache::Request have the following attributes:

basedir: The roaming servers base directory, as an absolute path. You set this using a PerlSetVar instruction, see INSTALLATION above for an example.
file: This is the path of the file being created (PUT), read (GET), deleted (DELETE) or moved (MOVE). It's an absolute path.
method: The requested method, one of HEAD, GET, PUT, MOVE or DELETE.
request: This is the Apache request object.
status: If a method dies, it should set this value to a return code like SERVER_ERROR (default), FORBIDDEN, METHOD_NOT_ALLOWED, or something similar from Apache::Constants. See Apache::Constants(3). The handler method will catch Perl exceptions for you and generate an error page.
user: Name the user authenticated as.

Authenticate

$ar_req->Authenticate();

(Instance Method) This method is checking whether the user has authorized himself. The current implementation is checking only whether user name is given via $r->connection()->user(), in other words you can use simple basic authentication or something similar.

The method should throw an exception in case of problems.

CheckDir

$ar_req->CheckDir();

(Instance method) Once the user is authenticated, this method should determine whether the user is permitted to access the requested URI. The current implementation verifies whether the user is accessing a file in the directory $basedir/$user. If not, a Perl exception is thrown with $ar_req->{'status'} set to FORBIDDEN.

GET, PUT, MOVE, DELETE

$ar_req->GET();
$ar_req->PUT();
$ar_req->MOVE();
$ar_req->DELETE();

(Instance Methods) These methods are called finally for performing the real action. With the exception of GET, they call Success finally for reporting Ok.

Alternative method names are possible, depending on the name of the requested file. For example, if you request the file liprefs via GET, then it is checked whether your sublass has a method GET_liprefs. If so, this method is called rather than the default method GET. The alternative method names are obtained by removing all non-alpha- numeric characters from the files base name. That is, if you request a file pab.na2, then the alternative name is pabna2. Note, these method names are case sensitive!

MkDir

$ar_req->MkDir($file);

(Instance Method) Helper function of PUT, creates the directory where $file is located, if it doesn't yet exist. Works recursively, if more than one directory must be created.

Success

$ar_req->Success($status, $text);

(Instance Method) Creates an HTML document with status $status, containing $text as success messages.

AUTHOR AND COPYRIGHT

This module is

Copyright (C) 1998    Jochen Wiedmann
                      Am Eisteich 9
                      72555 Metzingen
                      Germany

                      Phone: +49 7123 14887
                      Email: joe@ispsoft.de

You may distribute this module under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)