INSTALL

        MRBS Installation Instructions



REQUIREMENTS
---------------------------------------------------------------------------
MRBS works with both MySQL and PostgreSQL 6.5 to 7.2 database systems. You must
have PHP with support for your chosen database system installed and working
for this application. See the PHP (www.php.net), MySQL (www.mysql.com), and
PostgreSQL (www.postgresql.org) sites for more info on setting these up.
You need to know how to install, secure, run, maintain, and back up your
chosen database system.

No optional PHP packages (other than the database system) are required for
this application. This version of MRBS was tested with PHP 4.3.2 and
somewhat with PHP 5.1.2. Older versions of PHP 4 may work, but PHP 3 is
unsupported.

You can run PHP either as a CGI or with a direct module interface (also called 
SAPI). These servers include Apache, Microsoft Internet Information Server, 
Netscape and iPlanet servers. Many other servers have support for ISAPI, the 
Microsoft module interface.
You'll get better performance with PHP setup as a module.  Not only will you 
not have to deal with the CGI performance hit, but you'll be able to use PHP's
database connection pooling. However, be careful that you don't exceed
the maximum number of connections allowed to your database; with connection
pooling PHP/Apache can potentially create a connection from each Apache
child server to the database. 
Also many mrbs authentication schemes use basic http authentication. These 
don't work if you run PHP as a CGI.

If you are using PHP as an Apache module, you probably want to ensure that
the Apache MaxRequestsPerChild is not set to 0, in case of undetected memory
leaks in PHP or MRBS.

If you use MySQL, versions 3.22.32, 3.23.23, 3.23.53, 4.0.13, 4.0.14 and
5.0.18 have been tested and reported to work.

If you use PostgreSQL, you will need at least version 7.0, versions 7.0.3
and 8.1.4 has been tested and reported to work.

FILE UNPACKING
---------------------------------------------------------------------------
To install MRBS, just unpack the distribution into a temporary directory,
then copy the files in the "web" subdirectory into a new directory somewhere
your web server can find them.

For example:

Unpack the software into a new temporary directory, something like this:
    $ tar -xvzf ~/download/mrbs-1.0.tgz       (or whatever version)
    $ cd mrbs-1.0                             (or whatever version)

If you are upgrading from a previous version of MRBS, you should save your
"config.inc.php" file so you can compare and update the new file with your
site-specific changes. Then rename your existing MRBS web server directory.
For example:
    $ cp /var/lib/apache/htdocs/mrbs/config.inc.php config.site.inc
    $ mv /var/lib/apache/htdocs/mrbs /var/lib/apache/htdocs/mrbs.old

Now install MRBS by copying the contents of the "web" subdirectory of the
distribution somewhere your web server can find it.  For example:
    $ cp -r web /var/lib/apache/htdocs/mrbs

DATABASE SETUP
---------------------------------------------------------------------------
If you are upgrading from MRBS version 0.7 or later, and continuing to
use MySQL, your database is already set up, so you can skip to the
Application Setup section.

For a new install:

You can place the MRBS database tables in an existing database or
create a new database with the following:

[MySQL]         $ mysqladmin create mrbs
[PostgreSQL]    $ createdb mrbs

(This will create a database named "mrbs", but you can use any name.)

Create the MRBS tables using the supplied tables.*.sql file:

[MySQL]         $ mysql mrbs < tables.my.sql
[PostgreSQL]    $ psql -a -f tables.pg.sql mrbs

where "mrbs" is the name of your database (mentioned above).
This will create all the needed tables.
You may need to set rights on the tables; for PostgreSQL see "grant.pg.sql".
If you use a PHP version less than 4.2, you will also need to replace the pgsql
driver file pgsql.inc with pgsql.before_php42.inc, and rename it to pgsql.inc.
If you need to delete the tables, for PostgreSQL see "destroy.pg.sql".

The tables are now empty and ready for use. If you want to add a few sample
areas and rooms without going through the Admin function, use this script:

[MySQL]         $ mysql mrbs < sample-data.sql
[PostgreSQL]    $ psql -a -f sample-data.sql mrbs

Substitute the database name you used for "mrbs".
This script is only for use in a newly initialized database! (It will not
work properly in a database where the ID counters are greater than 0.)
Also see the description of testdata.php in the README file.

For an upgrade:

The database format changed slightly between 0.6 and 0.7. To change the
format of your data do:

[MySQL]         $ mysql mrbs < upgrade.my.sql

(This does not apply to PostgreSQL, which was not supported then.)
Also see the file UPGRADE in the distribution.

For a second installation or to use different table names:

If you have table name conflicts or want to do a second installation
and only have access to one database, then you can modify the 'mrbs_'
prefix for the table names.

In tables.*.sql you will need to change the table names and then follow
the instructions above for creating the tables in your database.

When editting config.inc.php, you need to change the table name prefix
from "mrbs_" to the value you chose using the variable $db_tbl_prefix.

WARNING: All of the .sql files are setup to use the 'mrbs_' prefix
         therefore you will have to edit them before you use them if you
         change the prefix for your tables.


Maintenance:

Be sure to back up your database regularly.
For PostgreSQL, be sure to run the "vacuum" command regularly.
You can clean out old entries from your database using the supplied SQL
scripts purge.my.sql (for MySQL) and purge.pg.sql (for PostgreSQL). Read
the comments at the top of the scripts before using them.

APPLICATION SETUP
---------------------------------------------------------------------------
Next, you will need to customize the file "config.inc.php"...

If you are upgrading from a previous version of MRBS, use your saved
copy of "config.inc.php" as a reference. Do not just use your old config.inc.php
file, however, because there changes and new settings.

Refer to the comments in the supplied config.inc.php file for more details.
The following sections can be configured:


1. Database Settings:

First, select your database system. Define one of the following:

    $dbsys = "mysql";
    $dbsys = "mysqli";
    $dbsys = "pgsql";

Then define your database connection parameters. Set the values for:

    $db_host =      The hostname that the database server is running on.
    $db_database =  The name of the database containing the MRBS tables.
    $db_login =     The database login username
    $db_password =  The database login password for the above login username

If the database server and web server are the same machine, use 
$db_host="localhost". Or, with PostgreSQL only, you can use $db_host="" to
use Unix Domain Sockets to connect to the database server on the same machine.

By default, MRBS will use PHP persistent (pooled) database connections,
for better performance. Depending on your web server and database server
configuration, it is possible that this will cause MRBS to reach the maximum
number of connections allowed to your database, since each Apache child
process may keep a connection open. Then, users will randomly get errors
when trying connecting to MRBS.  If you would rather use non-persistent
database connections, uncomment the line in "config.inc.php" which sets the
$db_nopersist variable.

If you want to install multiple sets of mrbs tables when only one
SQL database is available, or resolve table name conflicts, you have
to change the prefix of "mrbs_" for the tables in your database,
then you will need to set the value of:

    $db_tbl_prefix = The table name prefix


2. Site Identification:

Specify your company or site name, and contact information. The company name
is displayed at the top of each page, and the contact information is
displayed in the help file.

    $mrbs_admin = "Your Administrator";
    $mrbs_admin_email = "admin_email@your.org";
    $mrbs_company = "Your Company";

Alternately, if you want to display your organization logo, replace the 
$mrbs_company line like this :

$mrbs_company = "<a href=http://www.your_organization.com/><img src=your_logo.gif border=0></a>";

$url_base = "";

This is to fix URL problems when using a proxy in the environment
If links inside MRBS appear broken, then specify here the URL of
your MRBS root directory, as seen by the users. For example:

$url_base =  "http://webtools.uab.ericsson.se/oam";

It is also recommended that you set this if you intend to use email
notifications, to ensure that the correct URL is displayed in the
notification.


3. Calendar Settings:

There are two options here:
- regular consecutive booking periods (default)
  for example: every half hour period from 7 AM to 7 PM can be booked
- user-defined periods
  for example: school periods where periods are of different lengths
  and are not consecutive because of change-over time or breaks.

It is not possible to swap between these two options once bookings have
been created and to have meaningful entries.  This is due to differences
in the way that the data is stored.

The settings for each option are described below:

    a) Regular Consecutive periods
    Specify the resolution in minutes. MRBS will display blocks of this size,
    and will round up all entries to an even multiple of this many minutes.
    Specify a number which divides evenly into hours, for example one of:

        $resolution =  900;   # 15 minutes
        $resolution = 1800;   # Half hour
        $resolution = 3600;   # Whole hours

    Specify the start and end of the day in 24 hour notation, using whole
    hours.

        $morningstarts = 7;   # First block is 7 AM.
        $eveningends = 19;    # Last block starts at 7 PM.

    For additional control there are $morningstarts_minutes and
    $eveningends_minutes.

    $morningstarts_minutes gives you more control over the starting block
    displayed for each day.  For example, to start a day at
    8:30 am:

        $morningstarts = 8;
        $morningstarts_minutes = 30;

    $eveningends_minutes gives you more control over the last block displayed
    for each day. For example, to display full 24 hour days with 30 minute
    intervals:

        $resolution = 1800;
        $morningstarts = 0;
        $eveningends = 23;
        $eveningends_minutes = 30;

    Note: Be careful to avoid specifying options that display blocks
    overlaping the next day, since it is not properly handled.

    b) User-defined periods
    To enable this option set
        $enable_periods = TRUE;

    Then define the names of the periods that you wish to use in chronological
    order.  This is a free-form field and can contain anything, such as a
    descriptive name for the period or the start and end time.

    For example:
        $periods[] = "Period&nbsp;1";
        $periods[] = "Period&nbsp;2";
        ...
    or
        $periods[] = "09:15&nbsp;-&nbsp;09:50";
        $periods[] = "09:55&nbsp;-&nbsp;10:35";
        ...

    &nbsp; is used to ensure that the name or description is not wrapped
    when the browser determines the column widths to use in day and week
    views.

    A maximum of 60 periods may be defined.

    Note:
    1) Changing the number of periods after bookings have been entered may
    lead to incorrect reservations being displayed where the booking does not
    end on the day that it starts.
    2) The periods bear no relation to clock time during a day.


To control international preferences for the calendar displays, 

- use $weekstarts to change the first day of the week from the default of
Sunday; 
- use $dateformat to show dates as "Month Day" or "Day Month"
in the page footers;
- use $twentyfourhour_format to show dates in 12 or 24 hour
format.


4. Miscellaneous Settings:

These settings control:

- the maximum number of repeat entries which can be created at once (a safety
  feature),
- the default report time period,
- the number of search results to return per page,
- the page refresh rate,
- the way area/rooms are selected (html list or a drop-down select box),
- the way entries are displayed in monthly view (start/end slot, brief
  description or both),
- the way weeks are displayed in the bottom of the page (as week numbers (ie.
  42) instead of 'first day of the week' (13 Oct)),
- display of times on right and left side in day and week view,
- display of horizontal stripes on the day view,
- cells highlighting options,
- the default starting view (month, week or day),
- the default room to start with.


5. Authentication:

Read the file AUTHENTICATION for information about this section. By default, 
config.inc.php uses "php" session management and "config" authentication 
method, allowing only demo users to book rooms, and "administrator" is defined 
to administer the system. Demo users are "alice" and "bob" (passwords "a" and 
"b") and "administrator" (password 'secret') is administrator.


6. Email support:

MRBS can send emails to various recipients and in accordance with events.

There are four recipients types:

- MRBS administrator
- Area administrators
- Room administrators
- Bookers

With settings described below, you can decide that MRBS sends emails to all
these recipients, or any combination of them. Each one can be selected
individually. Note that the word 'administrator' is used here only for mail
purposes, it is not related to any approval workflow.

There are three events types:

- entry creation
- entry change
- entry deletion

As for recipients, you can choose to send mails for any of these three events.

There are many other settings, including mail transport agent (php mail, smtp
server, unix sendmail), content of the mail subject and body, either a link to
the entries or full description (with changes between edited entry and its
previous state). Read the following parameters for detailed informations:

MAIL_ADMIN_ON_BOOKINGS

Set to TRUE if you want to be notified when entries are booked. Default is
FALSE

MAIL_AREA_ADMIN_ON_BOOKINGS

Set to TRUE if you want AREA ADMIN to be notified when entries are booked.
Default is FALSE. Area admin emails are set in room_area admin page.

MAIL_ROOM_ADMIN_ON_BOOKINGS

Set to TRUE if you want ROOM ADMIN to be notified when entries are booked.
Default is FALSE. Room admin emails are set in room_area admin page.

MAIL_ADMIN_ON_DELETE

Set to TRUE if you want ADMIN to be notified when entries are deleted. Email
will be sent to mrbs admin, area admin and room admin as per above settings,
as well as to booker if MAIL_BOOKER is TRUE (see below).

MAIL_ADMIN_ALL

Set to TRUE if you want to be notified on every change (i.e, on new entries)
but also each time they are edited. Edited entries will display the modified
fields in brackets after the new value if MAIL_DETAILS is set to TRUE
(see below). Default is FALSE (only new entries).

MAIL_DETAILS

Set to TRUE is you want to show entry details in email, otherwise only a
link to view_entry is provided. Irrelevant for deleted entries, as email body
will always have entry details, since there is no possibility to provide a
link. Default is FALSE.

MAIL_BOOKER

Set to TRUE if you want the entry booker to receive a copy of his entry as
well as any future changes (depends of MAIL_ADMIN_ALL, see below). Default
is FALSE. MRBS can turn some of your user databases to advantage, as there
are several authentication schemes where the username is the same as
the email address username .For example, if your mrbs users come from an
ldap directory and mrbs use this authentication scheme, it is likely your
organisation emails addresses will use this username with '@domain'. If
this is the case, you just have to set MAIL_BOOKER to TRUE and provide your
domain below. This setting is available too if you use MRBS own user
database (auth_db).

MAIL_DOMAIN

If MAIL_BOOKER is set to TRUE (see above) and you use an authentication
scheme other than 'auth_db', you need to provide the mail domain that will
be appended to the username to produce a valid email address (ie.
"@domain.com").

MAIL_USERNAME_SUFFIX

If you use MAIL_DOMAIN above and username returned by mrbs contains extra
strings appended like domain name ('username.domain'), you need to provide
this extra string here so that it will be removed from the username.

MAIL_ADMIN_BACKEND

Set the name of the backend to use to transport your mails. Either "mail",
"smtp" or "sendmail":

·   mail
Sends a mail using PHPs build-in mail()-function. This means this function
must not be disabled and you have a minimal control over your server and
settings in php.ini :
    'SMTP' and 'smtp_port' for Windows and 'sendmail_from' and 'sendmail_path'
    for Unix

·   sendmail
Sends a mail using a sendmail unix program.

·   smtp
Sends a mail connecting directly to an smtp server.

# Sendmail settings

SENDMAIL_PATH

Set the path of the Sendmail program (only used with "sendmail" backend).
Default is "/usr/bin/sendmail"

SENDMAIL_ARGS

Set additional Sendmail parameters (only used with "sendmail" backend).
(example "-t -i"). Default is ""

# SMTP settings

SMTP_HOST

Set smtp server to connect. Default is 'localhost' (only used with "smtp"
backend).

SMTP_PORT

Set smtp port to connect. Default is '25' (only used with "smtp" backend).

SMTP_AUTH

Set whether or not to use SMTP authentication. Default is 'FALSE'

SMTP_USERNAME

Set the username to use for SMTP authentication. Use only if SMTP_AUTH is
set to TRUE. Default is ''

SMTP_PASSWORD

Set the password to use for SMTP authentication. Use only if SMTP_AUTH is
set to TRUE. Default is ''

# Miscellaneous settings

MAIL_ADMIN_LANG

Set the language used for emails (chooses from an available lang.* file).
Default is 'en'.

MAIL_FROM

Set the email address of the From field. Default is the $mrbs_admin_email
variable.

MAIL_RECIPIENTS

Set the recipient email. Default is $mrbs_admin_email. You can define
more than one recipient like this "john@doe.com,scott@tiger.com"

MAIL_CC

Set email address of the Carbon Copy field. Default is ''. You can define
more than one recipient (see MAIL_RECIPIENTS)

$mail["subject"]

Set the content of the Subject field. Default is
"Entry added/changed for $mrbs_company MRBS"

$mail["subject_delete"]

Set the content of the Subject field for deleted fields. Default is
"Entry deleted for $mrbs_company MRBS";

$mail["new_entry"]

Set the content of the message when a new entry is booked. What you type
here will be added at the top of the message body. Default is:
"A new entry has been booked, here are the details:"

$mail["changed_entry"]

Set the content of the message when an entry is modified. What you type
here will be added at the top of the message body. Default is:
"An entry has been modified, here are the details:"

$mail["deleted_entry"]

Set the content of the message when an entry is deleted. What you type
here will be added at the top of the message body. Default is
"An entry has been deleted, here are the details:"


7. Language:

MRBS supports multiple languages, which can be used at the same time, based on 
what the client is using. Users can configure their web browsers to prefer
one language over another, and MRBS will attempt to serve the MRBS pages in
the user's preferred language. You can specify the default language in
config.inc.php. See the file called LANGUAGE for more info.

MRBS also uses your server's OS locale support to localise date/time strings.
MRBS attempts to figure out what locale should be used based on your
preferred language and the server OS. Use "locale -a" on your unix system to
find out what locale support is installed. On Windows any language supported
by Windows should work.

From mrbs-1.2-pre2, MRBS is internationalised as long as the config
variable $unicode_encoding is set to 1 (which is the default setting). 
If this is set, then MRBS serves all of its pages in UTF-8 and stores
everything in the database in UTF-8. This means that all languages work
together.

IF THIS DOES NOT WORK for you (your server may not have unicode support),
just set $unicode_encoding to 0. MRBS will run the old way, with pages
being served in an encoding based on the language, and the encoding of data
in the database being a mess of different encodings based on the users'
preferred language.

To use Unicode, php should be built with 'iconv' support ('--with-iconv'
directive), or have the iconv extension installed and enabled. On Windows,
if you are using PHP 5, iconv support is built-in.

For PHP 4 on Windows, three things are needed :

- iconv.dll file in in the system path. Either copy it from your
  \%phpdir%\dlls\ directory into \%windir%\system32\ directory,
  or add your \%phpdir%\dlls\ directory to your PATH environment variable.
  (Note: for Microsoft IIS, you HAVE to copy iconv.dll into \%windir%\system32\)
- uncomment php_iconv.dll in php.ini.
- extension directory in php.ini have to be properly set to your actual
  \%phpdir%\extensions\


Note: Upgrading mysql database from previous charsets to Unicode :

  You can use convert_db_to_utf8.php script to convert text in the
  database to UTF8, to use MRBS with $unicode_encoding set to 1. The
  administrator should copy it into the web directory, run it (choosing
  the encoding to convert from) ONCE, and then move it back out of the
  web directory. We recommend you backup your database before running
  this script if you are at all worried.


8. Entry Types:

By default, MRBS defines two "meeting types" - internal and external. There
are a total of 10 types ready to be used, if you assign names to them in
your config.inc.php file. Each type has a color, defined in the style sheet.


HELP/FAQ File:

Customize site_faq.html if desired.  It contains help that can be tailored
to your environment. Currently this help is available in a number of
languages.


SECURITY NOTES!
---------------------------------------------------------------------------
You can configure your web server so that users can not obtain the ".inc"
files but this is not essential, since critical files containing your
database login and password use a ".php" extension like config.inc.php.
See your web server documentation on how to do this.

There is an Apache .htaccess file included, but Apache might ignore it because
of the "AllowOverride None" in your httpd.conf. Either change "AllowOverride
None" to "AllowOverride Limit", create a new <Directory> entry with the
contents of the .htaccess file in it, or add the contents of the .htaccess
to httpd.conf where it says "<Files ~ "^\.ht">". And then read the Apache
docs five or six times, until you know what you just did.

You may protect "config.inc.php" to only allow the web server to read it.
For example:   # chown httpd config.inc.php; chmod 400 config.inc.php

The script "testdata.php" is for testing only.  Do not leave it in a
directory accessible to your web server. Anyone running this will add a
large number of test entries to your database, regardless of
authentication, and book all your rooms to people you've never heard of.

$Id: INSTALL 798 2008-04-13 19:59:24Z jberanek $