Installation instructions

Copyright (C) 1999 Jukka Zitting <jukka.zitting@iki.fi>
Copyright (C) 2000 The Midgard Project ry
See the end for copying conditions.

These are the installation instructions of the Midgard address
translation and user authentication module. The module is used by
Apache to map URLs to Midgard database records.

This module uses the GNU configure system for configuration and
installation. The configure script locates the Apache apxs tool and
uses it to compile and install the module. You can configure, build,
install and setup mod_midgard by running:

 $ ./configure
 $ make
 # make install

The module needs midgard-lib, and for that midgard-config (as supplied
by midgard-lib) needs to be in your path.

The module needs to find the apxs tool in order to compile and install
properly. If the configure script is unable to find them, then you can
specify the following options to aid the script:

  --with-apache=DIR    Apache source directory.

  --with-apxs=APXS     Full path to apxs

Run "./configure --help" for more information.

For mod_midgard-preparser to work you'll need midgard-lib and
midgard-php4 1.4.2 or later. You'll also need database-upgrade from
the 1.4.2 data package. In order to start using mod_midgard-preparser:

1. Make a backup of your database. Not strictly required, but always a
good idea before running database-upgrade

2. install this module

3. run database-upgrade. This will add the cache tables to your
database. The default data package does not yet include the cache
tables, so even if you do a new install you will still need to run
database-upgrade

4. Add the MidgardPageCacheDir directive to your apache configuration
(see below).

5. Reconfigure midgard-php4 using the --enable-mgd-preparser switch,
recompile and reinstall

6. Stop and start apache (restart is _not_ the same).

You should now be able to access your midgard sites. As you do so, the
cache directory will start filling up with the pages you access. You
can remove these at any time, and they'll be regenerated. Note that if
you upgrade midgard-lib for changes to the preparser, you will want to
clear the cache directory. The preparser implementation is compatible
with APC and ZendCache, which should add another bit of performance,
although the preparser was mainly created to simplify Midgard
internally. You'll want APC or ZendCache to detect changes to the
source files (e.g. apc.check_mtime = on) or the cached files may
change without the compiled files being updated. If you have very few
changes to your site (excluding topic/article content), that may be
acceptable.

** CONFIGURATION DIRECTIVES **

  Syntax:  MidgardEngine [On|Off]
  Example: MidgardEngine On
The MidgardEngine directive turns the Midgard processing on or off
(default). You can selectively enable or disable Midgard processing
in VirtualHost and Location sections.

  Syntax:  MidgardRootfile [full path to rootfile]
  Example: MidgardRootfile /usr/lib/apache/midgard-root.php4
You can use the MidgardRootfile to specify the location of the Midgard
root file (absolute or relative to Apache server root). The default is
libexec/midgard-root.php3, where the default installation puts it.
There should be no need to change this location. The root file does
some initialization and invokes the root template that starts the page
generation process.

  Syntax:  MidgardDatabase [database] [username] [password]
  Example: MidgardDatabase midgard midgard secretpass
You can also use the MidgardDatabase to override the default database
connection attributes defined in the Midgard library (all set to
"midgard"). You can set different databases for different VirtualHosts. If
no databases are defined but MidgardEngine is on, then the default
database defined by the Midgard library is used.

  Syntax:  MidgardBlobDir [directory where the blobs reside]
  Example: MidgardBlobDir /var/www/blobs
Location where the blobs (aka attachments) are stored.

  Syntax:  MidgardDefaultRealm [string]
  Example: MidgardDefaultRealm "my Midgard machine"
Realm string that will be used for user authentication requests for
SG0.

  Syntax:  MidgardParser [encoding]
  Example: MidgardParser russian
The MidgardParser directive sets text formating engine used for internal
text formating and mail message handling. You may select between 'latin1'
and 'russian' values. 'latin1' does conversion of chars using ISO-8859-1 
encoding and converts symbols higher 160 to corresponding HTML entities.
Selecting 'russian' you switch off the conversion described above and
set encoding of mail messages to KOI8-R. Note that Midgard doesn't convert
symbols in mail messages to KOI8-R but expects it from client program.

  Syntax:  MidgardPageCacheDir [directory]
  Example: MidgardPageCacheDir /var/cache/midgard/page
The MidgardPageCacheDir directive tells mod_midgard where to store the
cached pages. This directory needs to be writeable for the apache
process. If this directive is not set, the directory does not exist,
or is not writeable, you'll get consistent failures for Midgard :)

  Syntax:  MidgardFavorFiles [On|Off]
  Example: MidgardFavorFiles On
The MidgardFavorFiles directive gives you the ability to choose what
to serve when both a file-based and a Midgard-based resource match an
URL. The default behaviour (MidgardFavorFiles Off) serves Midgard
URLs. Setting it to On will allow you to serve file- (or directory-)
based URLs under active pages without having to create static dummy
pages to fool Midgard.

** HOST CONFIGURATION **
To access the Midgard sites you'll need to set up virtual hosts
for them. You can use either name-, ip- or port-based virtual hosts.
See the Midgard FAQ and Apache documentation for details.

To activate the Midgard admin in the address 'localhost/admin' you
should set up a virtual host like this one:

  # httpd.conf
  <VirtualHost 127.0.0.1>
  ServerName localhost
  # Configure text parser:
  # Change to 'russian' for Russian Midgard
  MidgardParser latin1 
  # Configuration for Russian Midgard - we use mod_charset to automate 
  # re-encoding of page and query's data in respect of client's browser
  <IfModule mod_charset.c>
   # default charset for real or virtual server (selected if all other charset-
   # selections methods fails)
   CharsetDefault koi8-r
   # Default source (on-disk) charset (we keep all content in DB in KOI8-R 
   # encoding). If you want different charset, please re-encode midgard-ru.sql
   # before inserting it into DB too.
   CharsetSourceEnc koi8-r
   # Force mod_charset to do its work
   CharsetDisable Off
  </IfModule>
  </VirtualHost>

Then run the following SQL command to map the Midgard admin site to
the virtual host you just created.

  UPDATE host SET name='localhost',prefix='/admin' WHERE id=1

NOTE: The default administrator username is "admin" and
the password is "password".

Note that you'll need to use the Midgardized PHP module to correctly
parse the Midgard template codes. You shouldn't directly fetch the
Midgard root file as it should be read only by mod_midgard module. 
Do not place the root file inside the Apache document root.

** ADVANCED FEATURES **

  Syntax:  MidgardPageDatabase [database] [username] [password]
  Example: MidgardPageDatabase midgardadmin midgard midgard
The database to fetch page and style information from. You can use
this to partially emulate sitegroups. Pages will be served from this
database but the pages will run accessing data from the database
specified with the 'MidgardDatabase' directive. You can put shared
sites in such a database, and these sites will be available while
access to the data in them is totally prohibited.

  Syntax:  MidgardAuthDatabase [database] [username] [password]
  Example: MidgardAuthDatabase midgardadmin midgard midgard
The database to authenticate from. You can use this to arrange access
to sites served from databases where you have no Midgard user account.
Used in combination with MidgardPageDatabase and MidgardDatabase.
Users authenticated from this database will be granted full
(root-level) access no matter what.

  Syntax:  MidgardAuth [On|Off]
  Example: MidgardAuth On
Allow authentication against the midgard database for regular apache
'require' protection.

  Syntax:  MidgardLog [LogSpec] <[logfile]>
  Example: MidgardLog Error|Warning /var/log/midgard.log
  Example: MidgardLog Debug+ /var/log/midgard.log
Enables midgard-specific logging. You specify what type of information to
log by adding with '|' signs one or more of the following identifiers: 
Error, Critical, Warning, Message, Info, Debug. Appending '+' to a
loglevel selects that loglevel and those above it. The logfile is optional and
when omitted logging information will go to the apache error log. Currently
only the midgard-lib messages will go to this log; mod_midgard still logs to
the apache log. Setting this to Debug will cause midgard-lib to log all it's
queries and the mysql error message if the query fails. This directive
is global to all midgard sites; setting it in a VHost is not illegal
but will also affect all other midgard sites. The last appearance of
this directive overrules all others.

** NTLMSSP authentication support **

  Syntax:  MidgardAuthNTLM <path to Samba's ntlm_auth>
  Example: MidgardAuthNTLM "/usr/bin/ntlm_auth"
Enables authentication of users with NTLMSSP over HTTP. It allows seamless
login in into corporate Intranet sites with user's password in CIFS domain.
The only parameter for this option is path to Samba 3.0's ntlm_auth utility.
Please note that the user Apache is running under should have access to Winbind's 
priviledged pipe and, of course, Winbind itself should be properly configured 
before using this option.

  Syntax:  MidgardNTLMDomainMap <domain> <sitegroup>
  Example: MidgardNTLMDomainMap "FOO" "BAR"
Maps domain of user from CIFS networks to specific sitegroup in Midgard.
Can be specified multiple times for different domains. This option is
virtual server-wide and the whole map between domains and sitegroups
is empty by default for every virtual host.
----------------------------------------------------------------------
Copyright information:

Copyright (C) 1999 Jukka Zitting <jukka.zitting@iki.fi>
Copyright (C) 2000 The Midgard Project ry

   Permission is granted to anyone to make or distribute verbatim copies
   of this document as received, in any medium, provided that the
   copyright notice and this permission notice are preserved,
   thus giving the recipient permission to redistribute in turn.

   Permission is granted to distribute modified versions
   of this document, or of portions of it,
   under the above conditions, provided also that they
   carry prominent notices stating who last changed them.
^L
Local variables:
version-control: never
mode: indented-text
end:
