/////////////////////////////////////////////////////////////////////////////
// Improved mod_frontpage                                                  //
// for Apache 1.3.12 & 1.3.11                                              //
// v1.3.1 - March 2, 2000                                                  //
// Copyright (C) 2000 Christof Pohl <chripo+frontpage@edo.uni-dortmund.de> //
/////////////////////////////////////////////////////////////////////////////
// WorldWideWeb: http://home.edo.uni-dortmund.de/~chripo                   //
// FTP: ftp://ftp.edo.uni-dortmund.de/pub/mod_frontpage                    //
/////////////////////////////////////////////////////////////////////////////

This product includes software developed by the Apache Group for use in the
Apache HTTP server project (http://www.apache.org/).



WHAT YOU NEED
=============


The Apache HTTP Server sources
------------------------------

Of course. ;-) The Apache 1.3.12 sources are available via FTP at
<ftp://ftp.apache.org/dist/apache_1.3.12.tar.gz> or HTTP
<http://www.apache.org/dist/apache_1.3.12.tar.gz>.


Microsoft FrontPage Server Extensions
-------------------------------------

You can download the Microsoft FrontPage Server Extensions for UNIX platforms
at <ftp://ftp.microsoft.com/products/frontpage/>.

Get the compressed tar file named fp40.platform.tar.Z, where platform is the
UNIX platform to which the FrontPage Server Extensions are being installed.
For example, fp40.linux.tar.Z is the compressed tar file for Linux servers.

You will not need to download Microsoft's installation scripts
("fp_install.sh" or "change_server.sh").


Root access
-----------

To install the Apache HTTP Server with Improved mod_frontpage you must have
root access on the UNIX system!



USERS AND RIGHTS
================


Later in this Installation Guide you will come across several different
"users" and "groups" and their UID/GID (user/group id). I will try to prevent
any confusion and explain the different users/groups in this chapter. Please
read it carefully!


UNIX users, UNIX groups and FrontPage users
-------------------------------------------

UNIX users are valid user accounts on your UNIX system (e.g. they can login to
your system). Each UNIX user has a login name and a numerical user ID (UID).

When installing the Apache HTTP Server with Improved mod_frontpage, you will
have to differenciate between privileged users (like the superuser "root") and
unprivileged users (like "nobody"). All user accounts with a UID below a
certain number are privileged users; all other accounts are unprivileged.
Typical values to separate privileged from unprivileged users are 100 or 500
(I will use 500 later in this document).

The same is true for UNIX groups: each group has a group name and a numerical
group ID (GID). Again, all GIDs below a certain number are privileged, all
other groups are unprivileged. A typical value to separate privileged and
unprivileged groups is 100 (I will use 100 later in this document).

On most UNIX systems, typical privileged users are "root", "bin", "wheel",
etc. Privileged groups are "root", "bin", "daemon", etc. Unprivileged users
are "nobody" or your user account. Unprivileged groups are "nogroup" (or
"nobody" on some systems).

In contrast to the UNIX users, FrontPage users are no "real" users. They are
created by the FrontPage client or the "fpsrvadm.exe"-utility inside Apache's
access control files (normally ".htaccess"). These accounts are used to
authenticate an internet client to the Apache HTTP Server (for example, if you
want to open a web in the FrontPage client). They do not have any "direct"
rights on your UNIX system.


Special users/groups mentioned in this Installation Guide
---------------------------------------------------------

FrontPage Server Extensions User/group (see Step 1):
    This is the UNIX user/group owning the FrontPage Server Extensions
    installation  directory (normally "/usr/local/frontpage") and all files
    and subdirectories below. Since you do not want any of your unprivileged
    UNIX users to replace any of the FrontPage Server Extension files with the
    newest cracker tool, you will want the FrontPage Server Extensions to be
    owned by a privileged user and group (default is user "bin" and group
    "bin", which should be fine for most systems).

Apache HTTP Server User/Group (see Step 4):
    This is the UNIX user/group the Apache HTTP Server runs as. Both are set
    in Apaches configuration file "httpd.conf" with the "User" and "Group"
    directive. Improved mod_frontpage will not work if the Apache HTTP Server
    user/group is a privileged UNIX user or group. If you get strange errors
    when connecting to your Apache server using a FrontPage client, make sure
    that an unprivileged user and group is set in the "httpd.conf" file (e.g.
    "nobody" and "nogroup").

Website Content User/Group (see Step 4):
    This is the UNIX user/group owning your website's content directory
    (normally the "htdocs" directory below your Apache HTTP Server
    installation directory). Improved mod_frontpage will not work if the
    Website Content User/Group is a privileged UNIX user or group.  If you get
    strange errors when connecting to your Apache server using a FrontPage
    client, make sure that an unprivileged user and group (e.g. "nobody" and
    "nogroup") own your website's content directory. This is also true for the
    content directories of any virtual hosts you might want to extend with the
    FrontPage Server Extensions!

FrontPage Administrator (see Step 7):
    This is the FrontPage user that is created when installing the FrontPage
    Server Extensions to a web by running the "fpsrvadm.exe"-utility.



STEP-BY-STEP INSTALLATION GUIDE
===============================


Step 1: Install the FrontPage Server Extensions
-----------------------------------------------

Be sure you have the latest version of the FrontPage Server Extensions at hand
(download at <ftp://ftp.microsoft.com/products/frontpage/>). You will not need
"fp_install.sh" or "change_server.sh". After downloading, do a:
    # cd /usr/local
and untar the FrontPage Server Extensions there by hand:
    # tar zxf /path/to/downloaded/fp40.platform.tar.Z

Notice: If you have tried to install the FrontPage Server Extensions before,
        it is a good idea to remove the old "/usr/local/frontpage" directory
        completely BEFORE untarring the "fp40.platform.tar.Z" file:
            # cd /usr/local
            # rm frontpage -Rf

After that you will have a "/usr/local/frontpage" directory which contains the
FrontPage Server Extensions. The owning user and group should both be "bin".
This is the default FrontPage Server Extensions Unix user/group, which I will
use later in this document.

When using the FrontPage client for administring or authoring a web on your
server later, the Apache HTTP Server will execute the FrontPage CGI programs
which are right now located in the "/usr/local/frontpage/version4.0/exes"
directory.

Notice: It is possible to copy the whole "/usr/local/frontpage" directory tree
        to another location:
            # mv /usr/local/frontpage /some/other/path
        In this case, you have two options:
        - either you can create a symbolic link in "/usr/local", which points
          to the new position of the "frontpage" directory (recommended):
              # cd /usr/local
              # ln -s /some/other/path/frontpage frontpage
        - or you use the "--fpexec-fpdir" configure switch later in step 4 to
          tell Improved mod_frontpage where to look for the FrontPage CGI
          programs:
              --fpexec-fpdir=/some/other/path/frontpage/version4.0/exes

Notice: If for some strange reasons ;-) you want another UNIX user or UNIX
        group to own the FrontPage Server Extensions directory (e.g. user
        "root" and group "root"), do a chown:
            # chown root.root /usr/local/frontpage -R
        You must use the "--fpexec-fpuser" and/or "--fpexec-fpgroup"
        switches later when configuring the Apache HTTP Server to set your
        new FrontPage Server Extensions UNIX user and group:
            --fpexec-fpuser=root --fpexec-fpgroup=root


Step 2: Set up your building environment
----------------------------------------

You will have to untar this package and a fresh copy of the Apache sources
somewhere ("/usr/src" is usually a good choice). Using a fresh copy of the
Apache sources is highly recommended; you avoid side effects from previous
builds of Apache or from incompatible 3rd party patches or modules. To remove
an existing Apache source tree, do:

    # cd /usr/src
    # rm -Rf apache_1.3.12

Then untar this package and the Apache sources in "/usr/src/":

    # cd /usr/src
    # tar zxf /path/to/downloaded/apache_1.3.12.tar.gz
    # tar zxf /path/to/downloaded/mod_frontpage-apache_1.3.12-v1.3.1.tar.gz


Step 3: Patch the Apache HTTP Server sources
--------------------------------------------

With this document you got a file called "mod_frontpage-apache_1.3.12-v1.3.1".
This is a patch to the original Apache 1.3.12 distribution and includes
everything you need to compile Apache with Improved mod_frontpage. To apply
it, first change the working directory to the Apache sources:

    # cd /usr/src/apache_1.3.12

Then patch the sources with the following command:

    # patch -p0 < ../mod_frontpage/mod_frontpage-apache_1.3.12-v1.3.1

This will modify some files of the Apache distribution and create a new
subdirectory "/usr/src/apache_1.3.12/src/modules/frontpage", which contains
the Improved mod_frontpage files.

Notice: Any reports about succeeded hunks with fuzz and/or offset can safely
        be ignored. If you get other errors (e.g. failed hunks), check the
        version of your "patch" program:

            # patch --version

        This will print a small text including the version number. You need a
        reasonable up to date version of the "patch" program to apply the
        Improved mod_frontpage patch (version 2.5.3 or later is known to work,
        earlier versions might work as well).

Notice: You may want to add other modules now. Please have a look at the
        documentation of the 3rd party modules for further information. If you
        get any errors when applying other modules, please mail me!

        This module is compatible with mod_ssl version 2.6.0 for Apache 1.3.12
        by Ralf S. Engelschall, available at http://www.modssl.org.


Step 4: Configure Apache
------------------------

After you applied the patch successfully, there will be a number of new
configure switches you can give on the command line to activate Improved
mod_frontpage and set some values for its "wrapper", fpEXEC (see "ABOUT:
Security enhancements of Improved mod_frontpage" in the file "README" for more
information about fpEXEC).

Before configuring, make sure the Apache source directory is your working
directory:

    # cd /usr/src/apache_1.3.12

In this directory, you have to run the "configure" script with several so
called "configure switches". These are special parameters that influence
Apache's following build process. A sample call of the "configure" script with
detailed explanations is given below, but please read through the following
text first!

The "configure" script is called with several switches by executing:

    # ./configure --this-is-a-dummy-switch --this-switch=has-a-value

To activate the build of Improved mod_frontpage with your Apache HTTP Server,
add the following switch to the "configure" command:

    --activate-module=src/modules/frontpage/mod_frontpage.o

Using this configure switch will automatically enable the build of fpEXEC
also.

Notice: Yes, I mean "mod_frontpage.o", even if it is not there at the moment.
        Don't worry about that. :-)

You should add some more configure switches, but before, you have to make some
decisions (write them down on a piece of paper or so for later reference):

* Who should be your Apache HTTP Server User?
  This must be an unprivileged user, recommended is "nobody". Other reasonable
  choices (besides others) might be "www", "daemon", "demon", "http" or
  "httpd". I will use user "nobody" as Apache HTTP Server User in this
  Step-By_Step Installation Guide from now on.

* Who should be your Apache HTTP Server group?
  This must be an unprivileged group, recommended is "nobody" or "nogroup" (it
  dependes on your system which group is available). Other reasonable choices
  (besides others) might be "www", "daemon", "demon", "http" or "httpd". I
  will use group "nogroup" as Apache HTTP Server group in this Step-By_Step
  Installation Guide from now on.

* Who should be your Website Content User/Group? This must also be an
  unprivileged user and group. The user/group must be different from your
  Apache HTTP Server User/Group; the only exception to this rule is user
  "nobody" and group "nobody" (or "nogroup", respectivley): this user/group
  may be owner of your website's content directory as well as Apache HTTP
  Server user/group. Note that both user and group must exist on your UNIX
  system; if not, you should add them now. I will use user "customer" and
  group "firm" in this Step-By_Step Installation Guide from now on.


For configuring Improved mod_frontpage, you should set at least the following
configure switches, if their default values do not suit your needs:

  --fpexec-caller=nobody    set this to your Apache HTTP Server User.
  --fpexec-uidmin=500       set this to the lowest UID an unprivileged user
                            can have on your UNIX system.
  --fpexec-gidmin=100       set this to the lowest GID an unprivileged group
                            can have on your UNIX system.

Notice: If you have adjusted the owning user and/or group of the FrontPage
        Server Extensions Directory in Step 1, you will additionally need to
        use:

          --fpexec-fpuser=bin   set this to your FrontPage Server Extensions
                                user.
          --fpexec-fpgroup=bin  set this to your FrontPage Server Extensions
                                group.

Use all other configure switches starting with "--fpexec" with care! Be sure
you know what you are doing... ;-)

To avoid any later confusion, you should use the following two switches to
initially configure the Apache HTTP Server User and group:

  --server-uid=nobody   set this to your Apache HTTP Server User.
  --server-gid=nogroup  set this to your Apache HTTP Server group.

Apart from the above switches, configure your Apache HTTP Server as normal
(e.g. use other switches like "--prefix").

Here is a simple exsample on how to use the Apache configure script using only
the switches described above (a more complex example follows below):

    # ./configure --prefix=/install/path/of/apache \
    # --activate-module=src/modules/frontpage/mod_frontpage.o \
    # --fpexec-caller=nobody \
    # --fpexec-uidmin=500 \
    # --fpexec-gidmin=100 \
    # --fpexec-fpuser=bin \
    # --fpexec-fpgroup=bin \
    # --server-uid=nobody \
    # --server-gid=nogroup

This command will configure the Apache HTTP Server to install itself to
"/install/path/of/apache". Improved mod_frontpage is activated. The fpEXEC
caller is set to the Apache HTTP Server User "nobody", and the lowest
unprivileged UID/GID is set to 500/100. The FrontPage Server Extensions User
and group are both "bin". The server will initially be configured to run as
Apache HTTP Server User/Group "nobody" and "nogroup".

Because of the default values of some of the above used configure switches,
the following "configure" command is equivalent:

    # ./configure --prefix=/install/path/of/apache \
    # --activate-module=src/modules/frontpage/mod_frontpage.o \
    # --fpexec-caller=nobody \
    # --fpexec-uidmin=500 \
    # --server-uid=nobody \
    # --server-gid=nogroup

Notice: Normally, all transactions and errors of Improved mod_frontpage's
        wrapper fpEXEC are logged in a file called "fpexec_log" residing in
        the "logs" directory of your Apache HTTP Server. If you want to use
        "wrapper_log" as your logfile, add the following switch to your
        "configure" command:

          --fpexec-logfile=/usr/local/apache/logs/wrapper_log

Maybe you will want to add other 3rd party modules (such as mod_ssl or PHP)
before running configure.

Notice: You may have to add other configure switches to enable or configure
        3rd party modules for Apache.

Notice: You can compile Improved mod_frontpage as a shared module (DSO) with
        the switch "--enable-shared=frontpage". Explicit compilation as static
        module (which might be necessary if you use "--enable-shared=max") may
        be done with "--disable-shared=frontpage".

Here is a more complex exsample on how to use the Apache configure script:

    # ./configure --prefix=/path/where/to/install/apache \
    # --sbindir=/path/where/to/install/apache/sbin \
    # --infodir=/usr/local/info \
    # --mandir=/usr/local/man \
    # --enable-module=most \
    # --activate-module=src/modules/frontpage/mod_frontpage.o \
    # --enable-shared=max
    # --server-uid=nobody \
    # --enable-suexec \
    # --suexec-caller=nobody \
    # --fpexec-caller=nobody \
    # --fpexec-fpuser=root \
    # --fpexec-fpgroup=root

This command will configure the Apache HTTP Server to install itself to
"/path/where/to/install/apache", with the sysadmin executables in a "sbin"
directory. Info and manual pages will be installed into "/usr/local/info" or
"/usr/local/man". "Most" modules of Apache are enabled, and Improved
mod_frontpage is activated. All possible modules (including Improved
mod_frontpage) will be build as shared modules. The server will run as user
"nobody", which is also expected by the enabled suEXEC feature and Improved
mod_frontpage's wrapper fpEXEC. Furthermore, the "/usr/local/frontpage/"
directory (and files/subdirectories) are owned by user "root" and group
"root".

Here is a complete list of all fpEXEC configure switches including their
default values. All of these configure switches have no influence on Apache's
build process if the "--activate-module=src/modules/frontpage/mod_frontpage.o"
switch is not present (this means Apache will be build without Improved
mod_frontpage).

Configure switches for Improved mod_frontpage:

  --fpexec-caller=NAME
    Set this to the Apache HTTP Server User. The default value is "www".

    Notice: The Apache HTTP Server User should additionally be set with
            "--server-uid".

  --fpexec-logfile=FILE
    This defines the filename to which all fpEXEC transactions and errors are
    logged (useful for auditing and debugging purposes). By default the
    logfile is named "fpexec_log" and located in your standard logfile
    directory (can be set with "--logfiledir").

    Notice: If you also want to use both suEXEC and fpEXEC, they can share the
            same logfile if "--fpexec-logfile" and "--suexec-logfile" point to
            the same file (e.g. "/usr/local/apache/logs/wrappers_log").

  --fpexec-uidmin=UID
    Define this as the LOWEST unprivileged UID allowed to be a target user for
    fpEXEC. The target user is your Website Content User. For most systems,
    500 or 100 is common. Default value is 100.

  --fpexec-gidmin=GID
    Define this as the LOWEST unprivileged GID allowed to be a target group
    for fpEXEC. The target group is your Website Content Group. For most
    systems, 100 is common and therefore used as default value.

  --fpexec-fpuser=NAME
    Set this to the FrontPage Server Extensions User. If you have not chowned
    the FrontPage Server Extensions directory to a different user in Step 1,
    the default value of "bin" should be alright for you.

  --fpexec-fpgroup=NAME
    Set this to the FrontPage Server Extensions Group. If you have not chowned
    the FrontPage Server Extensions directory to a different group in Step 1,
    the default value of "bin" should be alright for you.

  --fpexec-safepath=PATH
    Define a safe PATH environment to pass to the FrontPage CGI programs.
    Default value is "/usr/local/bin:/usr/bin:/bin".

  --fpexec-fpdir=PATH
    This defines the path where the FrontPage CGI programs are located.
    Default value is "/usr/local/frontpage/version4.0/exes", which should be
    fine if you have untarred the FrontPage Server Extensions in the
    "/usr/local" directory or have a symbolic link there (see Step 1 of this
    Installation Guide for more details).

  --fpexec-htaccess=FILE
    Define the name of the access control file your Apache will use. Default
    value is ".htaccess".

  --fpexec-umask=UMASK
    Set this to the umask for the FrontPage CGI programs run by fpEXEC. The
    default value of "022" should be fine for most systems.

Notice: Before you apply your "configure" command to the Apache HTTP Server,
        you can check your current configuration by adding the "--layout"
        configure switch.

Notice: If you get a configure error stating that you have enabled both suEXEC
        and Improved mod_frontpage, your settings for "--fpexec-caller" and
        "--suexec-caller" are not equivalent. Use both switches in your
        configure command and set them to the same value.

Notice: If you get warning messages concerning any of your "--fpexec-..."
        switches, read them carefully (they might contain a hint on what you
        should change) and re-read this step of the Installation Guide again.
        Please note that the warning is no error and that compiling apache
        should nevertheless succeed without errors.


Step 5: Compile and install Apache
----------------------------------

After configuration is done, compile the Apache HTTP Server. Usually, you will
do a simple:
    # make
and after compilation has finished:
    # make install

Notice: Maybe you will have to issue other commands between "make" and "make
        install" to get other modules working properly. See the 3rd party
        modules' documentation for further details.

Edit Apache's configuration file "httpd.conf" in your favourite text editor:

    # vi /install/path/of/apache/conf/httpd.conf

Find the "<Directory>" directive for the path specified in the "DocumentRoot"
directive:

    <Directory "/install/path/of/apache/htdocs">

You will have to change the "AllowOverride" directive a few lines below from
"None" to "All". Otherwise, when trying to open your FrontPage Web in the
FrontPage client later, everybody is able to open it without using a login and
password, or you will get a strange error message like "No authentication
required".

Notice: You must set the "AllowOverride All" directive for ALL webs you plan
        to install the FrontPage Server Extensions for. This is also true for
        any virtual hosts and user specific webs ("~username"-webs with
        content in "/home/username/public_html").

Make sure that the "User"/"Group" directive states the name of your Apache
HTTP Server User/Group.

On some systems, you might have to make additional changes in "httpd.conf"
before you can successfully install a FrontPage Web in Step 7 (not needed on
my Linux box):

* remove all quotation marks that enclose paths (e.g. in the "ServerRoot"
  directive)

* set the directives "ResourceConfig" and "AccessConfig" to a value of
  "/dev/null":

      ResourceConfig /dev/null
      AccessConfig /dev/null


Step 6: Start the Apache HTTP Server
------------------------------------

Simply do a:

    # /install/path/of/apache/(s)bin/apachectl start

Or, with mod_ssl installed:

    # /install/path/of/apache/(s)bin/apachectl sslstart

Have a look at the "error_log" file:

    # tail /path/to/installed/apache/logs/error_log

You should find something like:

    [Wed Feb  6 20:16:52 2000] [notice] Apache/1.3.12 (Unix)
    FrontPage/4.0.4.3 configured -- resuming normal operations

Please note that the term "FrontPage/4.X.X.X" is included. This means
Improved mod_frontpage was loaded correctly.


Step 7: Install the FrontPage Server Extensions to your server's root web
-------------------------------------------------------------------------

Before you install the FrontPage Server Extensions, you should think about the
login name and password of your FrontPage Administrator, which will be created
in the process. This user will have full administration rights in the web you
install the FrontPage Server Extensions to, if (and only if) he is using the
FrontPage client. I will use the login name "fpadm" and password "test" in
the example below.

Now use the "fpsrvadm.exe" utility, which is part of the FrontPage Server
Extensions, to install the FrontPage Server Extensions to the root web on your
new Apache HTTP Server:

    # /usr/local/frontpage/version4.0/bin/fpsrvadm.exe

Notice: If you get an error like "Floating point exeption" and fpsrvadm.exe
        dosn't start at all, please make sure you have the shared C-libraries
        of the "old" libc5 libraries installed!

Notice: The UNIX username "fpsrvadm.exe" will ask you for is your Website
Content User. The UNIX group is your Website Content Group, accordingly.

Choose the following options when prompted:

  Please enter command:            1) install

  Please enter server type:        1) apache-fp

  Enter server config filename:    /path/to/installed/apache/conf/httpd.conf

  Enter host name for multi-hosting []: <ENTER>

  Enter UNIX username []:          nobody

  Enter UNIX group []:             nogroup

  User name to add to FrontPage group "administrators" [administrator]: fpadm

  Password for user "test":        test (you will see nothing)

  Confirm password:                test (you will see nothing)

Note that the "htdocs" directory containing your server's content will be
chowned by the "fpsrvadm.exe" utility to the UNIX username/groupname of your
Website Content User/Group. As already stated at the beginning of this
Installation Guide, this user/group must NOT be privileged, else you will be
unable to open your new FrontPage Web with the FrontPage client and Improved
mod_frontpage will report errors in your Apache's error logfile or in
"fpexec_log".

Notice: You can use command line switches with the "fpsrvadm.exe" utility. Try
        running it with "-help" to get some help.


Step 8: Try to open the FrontPage web with the FrontPage client
---------------------------------------------------------------

When prompted, use the FrontPage Administrator account that was created during
the last step (in the example this was user "fpadm" with password "test"). You
should be able to:
    - open your FrontPage Web
    - create and delete new FrontPage extended subwebs (e.g. discussion webs)
    - create/modify/delete FrontPage users
with the FrontPage client now.


Step 9: Sekt oder Selters
-------------------------

If everything works now, you might want to give a party or drink some beer or
something. ;-)

If not, recheck all the steps before, maybe you have missed something. Try to
get to work Improved mod_frontpage without any other patches or modules first.
You may also want to check out "http://home.edo.uni-dortmund.de/~chripo/" for
the FAQ, bugfixes or new versions of Improved mod_frontpage.

If all of the above doesn't help you, please send me a mail:
    <chripo+frontpage@edo.uni-dortmund.de>
Include as much information as possible: hardware, your system (Linux, Sparc,
FreeBSD, etc.), configure switches, 3rd party modules, logfiles, etc. I will
help you, if I can.

If you have any suggestions concerning Improved mod_frontpage, this
documentation or the Improved mod_frontpage website, please drop me a line
<chripo+frontpage@edo.uni-dortmund.de>.

Thank you,

Christof Pohl
