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
   <[email protected]>, see

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

   Vincent in turn was inspired by a Perl script from Frederik Vermeulen
   <[email protected]>, 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 the
           Apache::Roaming::LiPrefs(3) manpage 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 the INSTALLATION
           manpage 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 the
           Apache::Constants(3) manpage. 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: [email protected]

   All rights reserved.

   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.

SEE ALSO
   the Apache(3) manpage, the mod_perl(3) manpage

   An example subclass is Apache::Roaming::LiPrefs. See the
   Apache::Roaming::LiPrefs(3) manpage.

   A C module for Apache is mod_roaming, by Vincent Partington
   <[email protected]>, see

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

   Frederic Vermeulen <[email protected]> has written a CGI binary
   for roaming profiles. It's missing a MOVE method, though.

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.