ApacheCon 2001
Santa Clara, California
9am - Thursday April 5th

Apache and FrontPage

By Suso Banderas
(suso@suso.org)

http://suso.suso.org/presentations/apache_and_frontpage/

-= Introduction =-

A little background.

  Allow me to take a moment to tell you who I am and what I do.  I work as a system administrator for an ISP that has been serving several thousand customers since 1996.  When FrontPage extensions came out back in 1997 many
customers requested that we install the FrontPage extensions so that they could just hit publish on their client and not deal with FTP at all.  However, we did not see the value in spending the time to implement them and  over the next few years we had to wave those extensions off as too much of a security risk to be able to install them.

  In early 2000 I was assigned the project of redesigning our web server setup in order to "Better meet the needs of our customers".  One of the primary objectives was to get FrontPage extensions working, no matter what.  Many of us felt that if we did not present our customers with a new web server solution that included FrontPage capabilities that we would end up losing a substantial amount of business.

  Upon initially looking into FrontPage extensions I noticed that it would require a recompile of the Apache server.  I thought this was rather limiting since all of our production machines are RedHat Linux based and we would like to have RPMs for all major software installations.  Also, we needed to have SSL capabilities for our current SSL customers.  We would have liked to use RedHat Secure Web Server, but RedHat claimed on their website that using
FrontPage with their server was impossible since it would require a compilation of the httpd binary. Covalent Technologies' Raven SSL was the only option at the time for doing FrontPage extensions with SSL.  However, Raven SSL did not come in RPM form.  So we took it upon ourselves to do a little work and make things work the way we wanted them to.

Systems and versions used

  All of the research and testing for this presentation was done on RedHat Linux systems either running version 6.2 or 7.0.  RedHat's Secure Web Server (versions 3.2 - 3.2.2) is the web server that we used for our virtual domain web server.  Secure Web Server is basically Apache coupled with mod_ssl and BSafe(a product by RSA that you can not easily get the source code for).  Plain Apache 1.3.12 through 1.3.17 have also been used.

Disclaimer

  Due to the lack of official information on the FrontPage protocol and historical information,  I may be slightly incorrect in some of these explanations.  But I'm mostly right. ;-)    Also, if anything that I say here happens destroy your web server, damage equipment or anything like that, I can’t be held responsible for it.
  
Opinion: Don't use FrontPage

  The main purpose for this presentation is to help prevent people like you from pulling your hair out while trying to integrate FrontPage into your web server setup.  If at all possible, DON'T USE FRONTPAGE AT ALL.  That may sound a little like I'm giving a presentation on the wrong topic, but I'm trying to help guide people who are probably going to use this technology anyways.  Most likely because it is being demanded of them by the populous at large or the management of your company.  This might be you.

  I think that the time you spend trying to get the FrontPage extensions to work on your web setup could be far better spent writing very nice and convincing documentation and presentations about HTML, CGI and how to incorporate them into a website.  All most people want is something easy and to most people FrontPage is easier than learning about all of this "code".  But if you can make writing the code easier for the user, they are likely to meet you half way.  In the long run, it will be better for both of you.  Ok, I've made my rant, now I'll move along.

-= Part 1: Introduction to FrontPage and FrontPage Extensions. =-

What is FrontPage?

  FrontPage was Microsoft's answer to the lack at the time of a professional WYSIWYG web content creation and management program.  But they didn't just stop there.  They also wanted to solve the problem many non-technical people face with including simple forms, counters and such on their site.  "Now Joe Consumer could have all the functionality that those geeky college folks do, without all the work of learning how to program in this archaic and complicated CGI thing."  People adopted this technology relatively fast because it did exactly what they wanted. Users began to demand that their ISPs load FrontPage extensions on their Unix web servers, and if they didn't they would go someplace that did.  Many system administrators at the time wrote this technology off as too much of a security risk, claiming that there was no reason for the extensions to require root privileges and that the protocol was proprietary, etc..  But poor old Joe Consumer didn't understand what the big deal was.  He just wanted his hit counter.

  Now with more recent releases of the extensions, Microsoft and others claim that those security problems have been fixed.  This is in part due to the additional checks that the fpexec program (a program like suexec) does to make sure that the environment that the FrontPage client is interacting with is safe.

FrontPage on IIS.

  The FrontPage extensions were developed for and made to run on the IIS web server under Windows NT or 2000. Under that platform, all you need to do to enable the extensions is select a few options in a tabbed page.

  Some of the programs are the same, such as the use of a _vti_bin directory with programs called author.exe, admin.exe, fpcount.exe and shtml.exe inside of it.  But many of the features controlling access and configuration are hidden away in registry settings and controlled from contextual properties dialogs.

FrontPage under Apache.

  When Microsoft designed the FrontPage extensions for use on the Apache server, they had to work with some differences between Apache and the IIS server.  First of all, the server extensions (as they are commonly referred to from the help documents for IIS) are an integrated part of the IIS server.  Many of the settings are kept in the registry and use components that are integrated into Windows.  This makes it difficult to separate this functionality out and work it into much more open servers like Apache, where modules are key and the source code is free.

  This is where the mod_frontpage module for Apache comes in.  It replicates the functionality of integrating the FrontPage extensions with the server.  When any request comes in that is FrontPage related, this module will catch the request and know what FrontPage extension program to run to handle the request.

  When executing any of those FrontPage extension programs, a program called fpexec is used to run the extension program.  The functionality of fpexec is very simular to the functionality of suexec.  The fpexec program can just be thought of as a more specialized version of suexec, that will only be used to run the FrontPage extension programs.  This helps with the security because the extension programs are then run as the user who owns the website, instead of user nobody or whatever user your web server runs as.

  Authentication is done by the use of .htaccess files that use a ‘require’ directive in some directories.  The .htaccess files look for flat authentication files (just like .htpasswd) in the _vti_pvt directory of a FrontPage extended web to determine if the user can authenticate or not.  Since the authentication is separated out this way, it allows you to change the way authentication is done so that you can use digest, Radius or LDAP for authentication instead.

  When you download the FrontPage extensions tarball from Microsoft, it includes a patch against the Apache source tree for creating the mod_frontpage module. A few precompiled httpd binaries with pre-built mod_frontpage support come with the tarball in case you don't want to build your own.  Also, a pre-built binary of the fpexec program along with it's source code are in the tarball.  Unfortunately, the source code to the extension binaries that are run within a FrontPage extended web are not available at the time of this writing.

  Improved mod_frontpage by Christof Pohl comes with both the mod_frontpage module and the fpexec suid program.  The mod_frontpage module by Christof however, is a rewritten version of the Microsoft module to fix some security issues and provide more features.  Such as, being able to enable or disable the extensions through the use of a directive in each domain's virtual container.  The fpexec program is also a re-written version of the Microsoft program to make
more security checks before allowing any of the extension programs to run.

  Recent developments with improved mod_frontpage have enabled it to be a true DSO loadable module that only needs the apxs program for compilation.  Probably by the time you read this, improved mod_frontpage should also no longer need to be patched against the Apache source tree for installation.  Thus, it will be a separately compilable module.  This will make it more viable for being built into packages like RPM and Debian packages and making it much easier to install.

-= Part 2: How the FrontPage extensions are setup on Unix. =-

Global installation directory.

  Wait, I thought that we were already talking about FrontPage extensions. 

  Well, in a way we were, but like all popular technologies that have limited technical documentation and catch on too quickly, people are confused and there is a gray line.  The original FrontPage extensions for Apache came with a patch to the Apache source code that added the mod_frontpage module.  At that time I guess you could say that the whole tarball and everything it contained where the "FrontPage extensions".  The module itself started to become a little more separated when companies began integrating just the module into their own Apache setups, but still required you to download the rest of the extensions.

  With the release of Improved mod_frontpage, the module and fpexec program where completely separate of the extensions kept in /usr/local/frontpage.  In this instance, the extensions now refer to the programs that are installed in the document root on your web server and also in /usr/local/frontpage.  This is where the server side FrontPage configuration files and installation programs are kept.

  After untarring the tarball from Microsoft into /usr/local/frontpage, we wind up with the following hierarchy:

/usr/local/frontpage/
`-- version4.0/
    |-- _vti_bin/
    |   |-- _vti_adm/
    |   `-- _vti_aut/
    |-- admin/
    |   `-- scripts/
    |-- apache-fp/
    |   `-- _vti_bin/
    |-- bin/
    |-- exes/
    |   `-- _vti_bin/
    |       |-- _vti_adm/
    |       `-- _vti_aut/
    |-- nls/
    |-- serk/
    `-- srcs/

  Let's briefly go through what is kept in each of these directories.

/usr/local/frontpage/

  This is the main FrontPage extension installation directory.  If you run the fp_install.sh script that you can download with the tarball, it untars the tarball into this directory.  Besides having the version directory, it also can contain configuration files for each virtual host on your server.  After installing a root web there should be a file named we80.cnf in here that specifies the defaults for virtual servers.  You can also create additional config files named 'domainname:port.cnf' in this directory that give more fine grained control over specific virtual domains.

frontpage/version4.0/

 This directory holds the specified version of the extensions.

version4.0/_vti_bin/

 This directory contains the precompiled stub executable programs that will be installed in a root web or sub web if you use the fpsrvadm.exe program.  These executables are statically linked however, so it would be wise to recompile
your own fpstub executable by compiling the source code found in the version4.0/srcs directory.

version4.0/admin/

   This directory can be copied to someplace within your web space so that you can remotely administer your FrontPage extensions using a web browser.   I would not advise you to administer your server in this fashion because of the extra
security risks involved.  If you do use these scripts, make sure that you have setup authentication for this site when you put it in your server’s web accessible space.  It would also probably be wise to setup an SSL certificate so that passwords aren't transmitted over your network in the clear.

version4.0/apache-fp/

   Here lie the binary distributions of Apache that have been compiled with built-in mod_frontpage support.  The two files 'httpd' and 'httpd.Compat' are both compiled versions of Apache with the mod_frontpage module built-in.  The latter binary file uses different path names than the first one.  Mainly, it uses paths relative to the server root instead of absolute pathnames.  Both binaries have been compiled so that the suexec binary must be at /usr/local/apache/sbin/suexec.  You can run the programs with the -l option to see what other compiled in modules they use.

  The file fpexe.c is the source code to the fpexec executable.  There is also a compiled version of fpexec in the _vti_bin directory of this directory.  The file called 'fp-patch-apache_<version>', is the mod_frontpage source code patch against to specified version of Apache.

version4.0/bin/

   This directory contains three files.  The binary file called 'fpsrvadm.exe' is the program that you can run to install/manage/delete the FrontPage extensions on the root webs and sub webs of the server.  Upon running it without any options, it will give you a menu system that will ask you questions, determining what you want the program to do.

  The other two files (postinfo.html and _vti_inf.html) are copied when creating a new root web.  I don't really know much about them except that they are used by the client and extensions to determine what the hostname is and where
certain programs can be located.

version4.0/exes/

  The _vti_bin directory in this directory contains the actual binary executable files that get executed when the fpstub.exe files are run from a web.

 The shtml.exe program deals with all the bots that can run on a FrontPage extended web.  This includes functionality such as including headers and footers, echoing out the current date or modified date of a file, managing a user forum or dealing with form processing.

The fpcount.exe program is just a web counter bot that is run when a visitor comes to your site.  I suppose that this program was separated from the shtml.exe program to provide better speed upon execution.

In the _vti_aut and _vti_adm are the admin.exe and author.exe programs that the FrontPage client deals with when publishing or managing a FrontPage extended web.  These programs are put in separate directories that use .htaccess files to restrict their access based on a user or group.

version4.0/nls/

  'nls' stands for national language support in this instance.  This directory holds code page files for different languages.  All you need to know about this directory is that it should exist.

version4.0/serk/

   This directory contains the html documentation that can also be found on the web at:

                 http://officeupdate.microsoft.com/frontpage/wpp/serk/

The fonts used in this documentation seem to be easier to read than what is on Microsoft's website.  Also, you can be sure that you'll always have the documentation that goes with your version of the extensions in case Microsoft changes information to their site.

version4.0/srcs/

   In this directory is a source code file called fp.suid.c. This is a stub executable that will be installed in multiple places of each web's _vti_bin directory.  You should be able to compile this program by running:

    $ cc fp.suid.c -o fpstub.exe

Upon execution, this stub file will run one of the files in the frontpage/version4.0/exes/_vti_bin directory, according to what the stub executable is named after.  So, if the stub executable is named shtml.exe, it will run the shtml.exe program in the /usr/local/frontpage/version4.0/exes directory.  This saves quite a lot of space in each web since the stub executable is usually only 15KB, where as the actual programs these stub files will run total over 10MB.

version4.0/change_server.sh

  This script is supposed to help you upgrade your *currently running* server so that you will be able to use FrontPage extensions.   Note, it's not a good idea to run this script because it will replace your current Apache executable with the one kept in the frontpage/version4.0/apache-fp.  It gives you a chance to opt out of the upgrade once you run this program.  But just to be safe, you should keep away from it.

version4.0/fp_install.sh

  This script can be downloaded from the website that you get the FrontPage extensions tarball from.  It also comes in the tarball itself.  You should use this script to actually install the global FrontPage extensions setup in /usr/local/frontpage.  The script will ask you a series of questions about your server and where things are located.   There is more information about how to use this script later in this document.

version4.0/frontpage.cnf

  This file has some configuration information for how the server extensions work globally.  It also has some configuration information on how the extensions are installed on a per web basis.

version4.0/set_default_perms.sh

  If there is anything that would make me think that Microsoft intended that the FrontPage extensions are for dummies, it would be this script right here.   This script is supposed to change the permissions on the files and directories in the /usr/local/frontpage/version4.0 directory back to their defaults.  Chances are that if you’ve messed up your global directory so much that you need to use this script, it would just be better to re-install the extensions.

/usr/local/frontpage/we80.cnf

   This file sets global defaults for the root or sub web extensions.  Settings such as the outgoing SMTP server can be set in this file.  A list of possible configuration variables and values for this and other .cnf files in the FrontPage directory can be found at this website:

      http://officeupdate.microsoft.com/frontpage/wpp/serk/apndx03.htm

/usr/local/frontpage/<servername><port>.cnf

  If you want to give specific configuration values for any virtual domain host, you should create a file in this directory called <servername><port>.cnf where <servername> is the name of the virtual server and <port> is the port that it runs on (usually port 80).  This is formatted in the same fashion as the we80.cnf file.

Root web.

  Upon installation of the FrontPage extensions using the fp_install.sh script, you will be prompted to install what is called a 'root web':

Do you want to install a root web (y/n) [Y]?

  The root web refers to the top level website that has FrontPage extensions installed.  This is usually someplace like /home/httpd/html or /usr/local/apache/htdocs.  A root web has the following directory and file structure:

   docroot/
        |-- _private/
        |-- _vti_bin/
        |   |-- _vti_adm/
        |   |   `-- admin.exe
        |   |-- _vti_aut/
        |   |   `-- author.exe
        |   |-- fpcount.exe
        |   `-- shtml.exe
        |
        |-- _vti_cnf/
        |   `-- index.html
        |
        |-- _vti_inf.html
        |-- _vti_log/
        |-- _vti_pvt/
        |   |-- access.cnf
        |   |-- botinfs.cnf
        |   |-- bots.cnf
        |   |-- deptodoc.btr
        |   |-- doctodep.btr
        |   |-- frontpg.lck
        |   |-- linkinfo.cnf
        |   |-- service.cnf
        |   |-- service.grp
        |   |-- service.lck
        |   |-- service.pwd
        |   |-- services.cnf
        |   |-- svcacl.cnf
        |   `-- writeto.cnf
        |
        |-- _vti_txt/
        |-- images/
        |-- index.html
        `-- postinfo.html

.htaccess and */.htaccess

  Throughout these directories you will notice that there are .htaccess files that have all the authentication directives setup except for a require user or require group directive.  The exception to this is the _vti_adm and _vti_aut directories under the _vti_bin directory where by default there are require group directives.

_private/

   This directory will hold files that are not meant to be viewed from a web browser.

_vti_bin/
| _vti_adm/
` _vti_aut/

  This is the primary extensions directory.  The stub executable files go in this directory and in the _vti_aut and _vti_adm directories within it.  The fpcount.exe and shtml.exe executables are programs that are run like CGIs when someone visits the FrontPage enabled website.  The fpcount.exe program is used for FrontPage web counters.  The shtml.exe handles all other browser based FrontPage extension requests.

  The _vti_aut directory contains the author.exe program, which is what the FrontPage client interacts with when it publishes a website, calculates hyperlinks and so on.  This directory is password protected with a .htaccess file that requires a user from the htaccess group 'authors' to authenticate.

  The _vti_adm directory contains the admin.exe program, which is used when the client needs to create a sub web of the current web or to add/remove user privileges from the web.  This directory is also password protected and requires a user in the administrators group to authenticate.

_vti_cnf/

  The root web and all of the sub webs and subdirectories of any web that you access with the FrontPage client will have one of these directories.  Inside of it is configuration information for each file in the directory that the _vti_cnf directories resides in.  So if you have a few files called index.html, pictures.html and links.html in your www/ directory, then inside the _vti_cnf directory in the www directory would be files called index.html, pictures.html and links.html.  Those files contain configuration and attribute information such as what version of the file it is, when it was
last modified, what character set it uses and so on.

_vti_log/

  This directory can contain an author.log file in it that keeps track of publishes to the root web.  I have never seen this file used or anything logged to it when interacting with the client.  So don't worry if you don't see anything logged to it either.

_vti_pvt/

  This directory contains all the configuration and authentication information for the root web.  The service.pwd and service.grp files are basically normal Apache password and group flat authentication files (usually these are named .htpasswd and .htgroup).  If you want to change the password for a user or add or delete a user, you can modify these files and use the htpasswd program to change the encrypted passwords in service.pwd.  The service.lck file is used as a lock on all operations while a FrontPage client is accessing the extensions.  This keeps two clients from modifying the web simultaneously.

   Other access control files include the access.cnf file, which contains a list of settings for the Realm Name and password directory.  You can also use the svcacl.cnf file to control what IP addresses have access to the extended
web.

  The other files in this directory rarely will need to be changed or cared about.  They are just files that keep track of the extended web and control what the FrontPage client is doing.

_vti_txt/

   This is the description of this directory on Microsoft’s website:
   "This folder contains text indexes for the WAIS search engine only. It is not used by Index Server on IIS."    
   Well that's no help.  So what does it do?

_vti_inf.html and postinfo.html

   When the client first connects to the server that it is publishing to, it looks for these files at the base URL of the server to determine some global settings for the root web.  As an example, If you were publishing to a sub web at http://www.yourdomain.com/~username/, then it would look for these files at http://www.yourdomain.com/_vti_inf.html or http://www.yourdomain.com/postinfo.html.

  These files contain some information about where the extension binary programs are and what URL should be used for references.

Sub webs

  A sub web is structured pretty much the same was as a root web, except that it is below a root web and is missing a few files such as the postinfo.html and _vti_inf.html . To illustrate exactly the relationship between a root web and a sub web, I'll use a real world example.

  Let's say that we have a root web at the website http://www.frontpage.com/. On the server, that root web is at /home/httpd/html on the server's file system. If we create a sub web of this root web called manual, then that sub web will exist at /home/httpd/html/manual on the file system and will be accessed at http://www.frontpage.com/manual/ from the FrontPage client or a web browser. This does not mean that any directory under /home/httpd/html is a sub web.  To be a sub web, the directory has to have the full array of extension directories (_vti_* and the like).  This is somewhat useful from a client point of view in that it allows the user to open up a separate project when managing the sub web.

  When you setup the FrontPage extensions in a user's web space, such as at http://www.frontpage.com/~jimbob/, you are creating a sub web as well.  This is also called a per-user sub web.

-= Part 3: Improved mod_frontpage =-

Changes and improvements made.

  Christof Pohl's Improved mod_frontpage has a goal of providing features and security fixes for Apache servers that are not provided by the Microsoft mod_frontpage module.  One of those improvements most sought after was it's ability to work with and be compiled on the latest versions of Apache.  Also, it fixed the problem of suexec not functioning in some cases with Microsoft's fpexec.  On top of that, it properly works with most other popular Apache modules like PHP and mod_ssl.

  Improved mod_frontpage also adds two directives called FrontpageDisable and FrontpageEnable that allow you to disable or enable specific virtual hosts in your main Apache configuration file.  This way you can globally disable FrontPage and then enable it for specific hosts.

  One other thing that I like about improved mod_frontpage is that it follows the source tree layout that the Apache source tarball sets up.  It patches the files it needs in rest of the tree, but when setting up the actual module code and fpexec source file, it puts it in src/modules/frontpage.  The Microsoft module on the other hand puts itself right in the base directory as if it was the most important module in the world.

  Recently Adrian Hosey and I worked on making the module a true DSO module that could be compiled on it's own using the apxs program.  This means that now it can be compiled for SSL based web servers like RedHat's Secure Web Server, where recompilation of the httpd binary is impossible.  RedHat even said on their website that it was impossible to use FrontPage extensions with their Secure Web Server product.

  One of the most important things about improved mod_frontpage though is that it's being developed openly by many people around the world making contributions and suggestions.  Security and bug fixes get fixed in a matter of days instead of waiting months for Microsoft to release a "complete" update.

  Christof Pohl told me recently that the next release of the distribution will probably be completely independent and compilable on it's own through the use of it's own configure script and Makefile.  So probably by the time you read
this that new version will be available (current version is 1.5.1).   I think that these features will help to give improved mod_frontpage the acceptance it needs to be bundled with other third party distributions of Apache.

 Installing improved mod_frontpage and FrontPage extensions.

   Currently, the method for installing improved mod_frontpage involves patching the source tree for Apache and enabling some configure flags while running the configure script for Apache.  Basically it's done in these steps:

   1.  Untar the Improved mod_frontpage source into /usr/local/src
   2.  Untar the Apache source into /usr/local/src
   3.  cd into the Apache source tree and run:
	 patch -p1 < ../improved_mod_frontpage-tree/patchfilename
   4.  Run configure on the Apache source tree, setting the following options:

	--enable-module=frontpage       This will enable the module to be built.

 You will probably need to change these options below to a setting that reflects how your server is setup.  The default values are in brackets, I've put the values that I usually use on the right in parenthesis:
	
	--fpexec-caller=[www]				   	 (nobody)
	--fpexec-docroot=[/usr/local/apache/htdocs]        	 (/home)
	--fpexec-logfile=[/usr/local/apache/logs/cgi.log]  	 (/var/log/httpd/fpexec.log)
	--fpexec-userdir=[public_html]			 (www)
	--fpexec-uidmin=[100]				   	 (99)
	--fpexec-gidmin=[100]				   	 (99)
	--fpexec-safepath=[/usr/local/bin:/usr/bin:/bin]   	  (same)
	--fpexec-fpdir=[/usr/local/frontpage/version4.0/exes]  (same)
	--fpexec-fpuser=[bin]					  (same)
	--fpexec-fpgroup=[bin]				     	  (same)
	--fpexec-htaccess=[.htaccess]			   	  (same)
	--fpexec-umask=[022]				   	  (same)

  * The settings that are shown in parenthesis are what RedHat Linux users should probably use.

   5.  Run 'make'             
   6.  Run 'make install'  

   7.  Add these lines to your httpd.conf file if necessary:

       LoadModule frontpage_module  <modulepath>/mod_frontpage.so
       AddModule mod_frontpage.c

Now after you have mod_frontpage an fpexec installed you will want to make sure that you have the FrontPage extensions installed.

Change to the /tmp directory first just to be safe.

   8. Download the tarball file from Microsoft's site:

	ftp://ftp.microsoft.com/products/frontpage/fp40.<os>.tar.z   

   9. Download the install script from their website as well:

               ftp://ftp.microsoft.com/products/frontpage/fp_install.sh

  10. Run the fp_install.sh script.  You will be prompted with several questions  including where you would like to        install the extensions and where programs like zcat are (which is usually /bin/zcat).  

  Here are some questions the script may ask you and the answers I usually use:

  - Are you satisfied with your backup of the system (y/n) [N]?  y
  - FrontPage Extensions directory [/usr/local/frontpage/]: /usr/local/frontpage
- Where is the zcat which can uncompress gz files? /bin/zcat
  - Do you want to install a root web (y/n) [Y]? y
  - Server config filename:  /etc/httpd/conf/httpd.conf
  - FrontPage Administrator's user name:  fpadmin
  - Enter the new servers port number: 80
  - Unix user name of the owner of this new web:[nobody]  nobody
  - Unix group of this new web:[nobody] nobody
  - What type of Server is this: 3                   (This is apache-fp)
  - Password for user "fpadmin":                     (it will prompt you twice.)

  - Which local character encoding does your system support: [1] 1
  - What should the default language be: [1] 1
  - Install new sub/per-user webs now (y/n) [Y]? n      
  - Install virtual webs now (y/n) [Y]? n               

 Note that it might not ask you every question shown above because the script tries to detect certain settings.  Also, if you have multiple virtual host containers setup in your httpd.conf file, it may prompt you for which host to use.  You will want to use the main server name.

  11. Now you will need to tweak some settings that the fp_install.sh script might not have got right.

-  The fp_install.sh script doesn't always install the _vti_bin binaries in the root web or sub webs.  You will want to copy the stub executable file from /usr/local/frontpage/version4.0/srcs/fpstub.exe to the proper locations in the root or sub web's _vti_bin directory.

- The fp_install.sh script is supposed to add some ScriptAlias directives to your Apache httpd.conf file to allow the   programs in _vti_bin to run correctly.  If they weren't added, put something like the following in the global section of your httpd.conf file:

	ScriptAlias /_vti_bin/_vti_adm/ <docroot>/_vti_bin/_vti_adm/ 
	ScriptAlias /_vti_bin/_vti_aut/ <docroot>/_vti_bin/_vti_aut/ 
	ScriptAlias /_vti_bin/ <docroot>/_vti_bin/

where <docroot> is the document root of the server.

-= Part 4: Using FrontPage extensions at an ISP =-

  In an Internet Service Provider setting, installing and maintaining FrontPage extensions and the mod_frontpage module can be quite tricky.  In this section I will provide some methods for working around some of the limitations of the stock/standard FrontPage setup.  Not all situations will be covered, but you should be able to pick up ideas off of what I provide here.  Simply adjust those techniques to your own setup.

Setting up the FrontPage extensions on shared servers.

 The most common situation that will probably come up at most ISPs is how to  install the extensions for a user, whose web space is at http://www.isp.com/~username.  Using the fpsrvadm.exe program as the root user you can do the following.

   umask 022 
   cd /usr/local/frontpage/version4.0/bin
   ./fpsrvadm.exe -o install -p 80 -w '~<username>' -s \
       /etc/httpd/conf/httpd.conf -xu <username> -xg <primarygroup> -u <username>

  <primarygroup> is the user's main group id.  This is usually either the same name as the username, 'users' or some value indicating what level of service the user has like 'business' or 'vhttp'.

 The -xu and -xg options are for specifying what operating system level user and group should be used for owning the files.  The -u option specifies what Apache user (through .htaccess) will be the initial author and administrator for the site.

 I think that it's probably best to give the .htaccess user the same name as the OS level user so that there is no confusion to the end user (or the system administrator) as to who has access to publish to the site.   

 Many ISPs have expanded their system of user management beyond the use of the simple adduser program bundled with most Unices.  Where I work, we have written modules to handle the management of users in an object oriented way. On top of that we use a program we wrote called mcfeely to handle running commands unattended on multiple servers from a task initiated on another server.  Unfortunately this kind of setup doesn't work well with the fpsrvadm.exe program because you can't have fine grained control over how and what is installed.  Also, if you are counting on processing return codes from install programs you will have troubles working with fpsrvadm.exe.

 What you should try doing instead is installing all of the files using your own install program. Fortunately, this isn't too difficult.  As shown in Part 2 of this documentation there are some standard directories that all FrontPage extended webs use.

 The first part of writing your own script is to install all the necessary files that make up a sub web using the fpsrvadm.exe program.  Then copy those files that were created into /etc/skel, which is usually the place where standardized files for per-user installs are kept.  The FrontPage files that you just copied also have some values in some of the files that should be generalized by replacing them with a string like %{username} or %{password}.  These files include:

    web/.htaccess
    web/_vti_bin/.htaccess
    web/_vti_bin/_vti_aut/.htaccess
    web/_vti_bin/_vti_adm/.htaccess
    web/_vti_pvt/access.cnf
    web/_vti_pvt/service.pwd
    web/_vti_pvt/service.grp 
    web/postinfo.html

   Then when you install script runs, it can replace those strings with their actual value for the user you are installing.

   All the files installed as FrontPage extensions can be world readable without to much worry.  Some of them have to be world readable anyways for the  web server to be able to use them before it uses fpexec.

Dealing with precompiled quirks and undocumented design.

  I heard someone ask the question once of some piece of software "Why did they hard code that value into the program?".  The posed answer to that question was "My only guess would be to maximize suckage."

 The FrontPage extensions have some values hard coded into the programs that really shouldn't be.  The one that I had the most trouble with was the user web directory suffix.  The FrontPage extension binaries are hard coded to use the web suffix 'public_html'.  For some reason recently, this whole 'public_html' user web directory suffix standard has been catching on, and I guess Microsoft decided that they would push it along even further.  I personally don't think that 'public_html' is a good name for the suffix.  The older convention of using 'www' makes more sense because it doesn't lend itself to any one document format that might be replaced someday.  Anyways, I won't ramble on about my opinions here anymore.

 If you need to change the web suffix that the binaries use you can accomplish this by editing the programs with a text editor that has a binary editing mode.  Both Emacs and Vi have binary editing modes.  See the documentation on those programs for details.

 In the binary program files you can search for the string public_html, which is in each file about three times.  Once you have located the relevant text, you can overwrite the word public_html with the suffix that you use followed by a null character.

WARNING:  It is very important that you do not change the length of the file.  Otherwise the binary program file will cease to work and will dump core every time you try to run it.  Therefore, you must replace the word public_html like this:

   original:      public_html
   replacement:   www^@ic_html

 The ^@ symbol is a two character sequence that represents the null character in most editors.  To give you an example using vi, you can open the file with 'vi -b <binaryfilename>' and then in command mode type '/public_html'.  This will take you to the first instance of the word public_html.  Right before the word public_html there should be a null character.  I wasn't able to figure out how to type in a null character in vi without copying one into the paste buffer so what you'll have to do is delete one of the null characters in the file with the cut command, reinsert the character back where it was using the P key, and then paste the null character still in your paste buffer overtop of the first l in public_html.  So here would be the exact sequence of keys (arrow keys, return and escape are specified in angle brackets):

  1.   vi -b shtml.exe <return>	  [Open the file in binary mode.]
  2.   /public_html <return>           [Search for the string.]
  3.   <left arrow>                    [Move over top of the null character.]
  4.   x                               [Cut the character under the cursor.]
  5.   P                               [Paste it back in the current position.]
  6.   4l                              [Move one position right 4 times.]
  7.   p                               [Paste the character after the cursor.]
  8.   4h                              [Move left 4 characters.]
  9.   4x                              [Cut 4 characters after the cursor.]
 10.   i                               [Insert mode.]
 11.   www                             [type in the www string.]
 12.   <escape>                        [Go back to command mode.]
 13.   n                               [find the next instance of public_html.]
 14.      <repeat steps 3-13 until all strings are replaced.>
 15.   ZZ			         [Exit vi, saving the file.] 

Now do the same thing for the other binary files.  The binaries that you will need to modify are located at:

     /usr/local/frontpage/version4.0/bin/fpsrvadm.exe
     /usr/local/frontpage/version4.0/exes/_vti_bin/shtml.exe
     /usr/local/frontpage/version4.0/exes/_vti_bin/_vti_adm/admin.exe
     /usr/local/frontpage/version4.0/exes/_vti_bin/_vti_aut/author.exe

 You will obviously need to adjust these instructions depending on what your web directory suffix is and how many characters the suffix is.

   What if you want to use a different method for authentication?  Using the standard .htpasswd flat files may be fine for small sites or small office servers.  But most ISPs and larger businesses probably use some other way of authenticating users with something like a radius server, which we'll use in this example. To approach this problem, it's wise to simplify as much as possible what you put in the .htaccess files in each FrontPage extended web.  Ideally, you only want to have a directive in the .htaccess files like 'require user <username>'.  Then you put the overhead radius directives inside a directory container in the httpd.conf file.  Like this:

      <Directory "/">
         AuthRadiusAuthoritative Off
         AuthAuthoritative On
         AuthRadiusActive Off
      </Directory>

      <Directory "/home/*/www/_vti_bin/*">
        Options ExecCGI
        AuthType Basic
        AuthRadiusActive On
        AuthRadiusAuthoritative Off
        AuthAuthoritative On
      </Directory>

 Make sure you have the mod_auth_radius module installed and setup before you use the AuthRadius directives though.  You'll need to put these directives for mod_auth_radius somewhere else in the global section of the file so that Apache knows what radius server to talk to:

      <IfModule mod_auth_radius.c>
        AddRadiusAuth <radiusservername>:<port> <sharedsecret> 5
        AddRadiusCookieValid 5
      </IfModule>

 By turning AuthRadiusAuthoritive off and AuthRadiusActive on, it will make the client fall back on radius authentication if the user's password doesn't match what is in the service.pwd file.  This makes it possible for the
FrontPage client to create author users that will still work like they did with the flat file authentication method.

  The FrontPage client doesn't like it when it can't write to files in it's web space.  This became a problem for us because we run a cronjob every night that processes a user's web log and puts the results in www/http-analyze.  The job
runs as root, so the output directory is owned as root, and therefore is not writable by the FrontPage client.  This was discovered after a user reported that whenever he published his site, he would get the error "Server error: Cannot change permissions on file: /home/user/www/http-analyze/index.html".  Uh, yeah, that's a server error isn't it. :-)

 The solution to this problem is kind of a hack, but it works.  We changed the permissions on the http-analyze directory to 751 so that normal users and the FrontPage clients could still enter the directory, but could not list the files. After making this change, the FrontPage client stopped complaining after making this change.  So I guess the baby logic behind that is that if the FrontPage client can't see it, then it doesn't bother with it.  The better solution for us would be to modify the stats output program to chown the files after writing them to disk, which is something we will probably do. But there may be cases where you can't do that.  So thus, I present this solution to you.

  If you are hosting virtual domains on a shared server you will need to put a file called postinfo.html in each virtual domain user's web directory.  This file has a variable line in it called BaseUrl= that holds the name of the domain to which the site is being published.  This value is the full hostname that the user should publish their site to.  Note that if that user tries to switch back and forth between publishing to their virtual domain and their ~username address, the FrontPage bots will not work for the address that they did not publish too.  This is a very lame "feature" of FrontPage
that should be fixed but probably won't be.  Sigh.

-= Part 5: Other considerations =-
User migration

  If you are migrating your web servers to include FrontPage extensions, you may wonder what will happen to users who have already been publishing their site using ftp or trying to install the extensions themselves.  Well, fear not because fortunately we didn't have any trouble with this at all when we migrated our setup (this is not to say that you won't, but generally it's going to be true).  What we actually did was remove any _vti_* directories in each user's account before installing the extensions we had setup in their account.  We did this for each user so that they would not have to request that their extensions be turned on.

What do you do when there is a problem?  

 First of all, I can't emphasize how much you should simulate the setup of your web servers using FrontPage on a test (non-production) machine, before actually setting them up on a production machine.  Things rarely ever go as planned and there are lots of potential gotchas that can creep up if you've been running a server for a while.  Especially if you have any "exception" users with special setups.  You have to cover all bases and make sure that you know what test cases to use.

 If the problem is only coming up for one user and they might have futzed with their extensions, it's best to just re-install their extensions.  I've actually written a program to do this.  You can use this script as an example and modify it for your setup.  You can download it at:

    http://suso.suso.org/presentations/apache_and_frontpage/initfrontpage.pl

 If the problem seems global and affects all of your users, then you probably didn't do enough testing. ;-)  The best place to go to find out what possible solutions to your problem may be is the Improved mod_frontpage forum at:

   http://home.edo.uni-dortmund.de/~chripo/

 There you can search through the posts to find people who have possibly had a simular problem.  If you can't find it there, then be creative and let others on the forum know of your solution.

What about a free version of the FrontPage extensions?

 There is a free FrontPage extensions clone being developed by Mrs. Brisby, which is just a single CGI script.  You can find it at:

    http://www.nimh.org/fpse.shtml

  This software is not complete at the time of this writing and may not implement all the features that the FrontPage client requires.

What about the future of FrontPage?  What about WebDAV?

 You might notice when you login to Microsoft's ftp server that in the FrontPage extension directory there is another directory containing the development 5.0 version of the extensions.

 WebDAV is a more standardized and open protocol that is looking to replace FrontPage.  WebDAV is something that was originally developed at Microsoft but has spun off a bit.  I think that most of the office products are somewhat WebDAV enabled.  Check out Greg Stein's WebDAV presentation at ApacheCon 2001 for more information.

-= Part 6: Conclusion and links to more info =-

Conclusion

   FrontPage is voodoo.  It’s not cool voodoo either like mod_rewrite is.  It’s just designed poorly and can be a real pain to install and manage.   I hope this documentation keeps you from screaming and yelling for weeks like I did while learning about FrontPage.  I think the key thing to remember is that there are usually creative ways to get around most of the problems that you'd face setting it up.  If possible, the best solution would be to skip FrontPage all together and train your users how to write their websites in HTML and upload them with FTP.   All your users need is some encouragement from you and enough documentation to get started.   You just need to make it look easy.  After all, that’s why FrontPage caught on so fast.

Links:

    - http://home.edo.uni-dortmund.de/~chripo/  (Improved mod_frontpage)
    - http://officeupdate.microsoft.com/frontpage/wpp/serk/
    - http://suso.suso.org/presentations/apache_and_frontpage/
    - http://www.nimh.org/fpse.shtml  (FPSE Clone)

Places to point users of the FrontPage client:

    - http://www.microsoft.com/frontpage/

To find the latest update to this document you can visit:  
 
http://suso.suso.org/presentations/apache_and_frontpage/