Setting up multiple boards on one server
========================================
[for issues with multiboard see "Multiboard Issues" below]

The phpbb3 package allows for easily setting up different boards on
the same host (we also call that "multisite"). The advantage is that
the boards share the same code base and upgrades of the package are
instantly available to all boards.

In this file we assume you're using the Apache web server, although
this feature does not depend on the webserver used.

Using multiple boards is not compatible with Debian's dbconfig-common,
i.e. you will have to cope yourself with upgrading the databases of
the additional boards that you create. To that end we provide
upstream's install folder with a random suffix in
/usr/share/phpbb3/www/, e.g. /usr/share/phpbb3/www/install-xi8hgDjmRX.

You can use this installer to populate alternative databases. Just
configure the board(s) as shown below and go to their install-XXX
folder. The installer will complain that it cannot write to
config.php, which is not important, since you need to have it
configured beforehand anyway to get here.

To add a second (or third, ...) board to your install, you need to take the
following steps:
- Create a new database and a new database user for your new board.
- Copy /usr/share/doc/phpbb3/examples/config.php to a new file in /etc/phpbb3/
  (e.g. /etc/phpbb3/board2.inc.php) and put the the new database credentials
  in it.
- Eventually configure $url_forum in each configuration file, in order to
  distinguish the different boards. By default, the database name will be used.
- Edit /etc/phpbb3/apache2.conf and add:

	Alias /board2 /usr/share/phpbb3/www
	<Location /board2>
	        php_value auto_prepend_file /etc/phpbb3/board2.inc.php
	</Location>

- Restart Apache.
- Populate the database for the new board by browsing to the install folder
  mentioned above, i.e. http://yourhostname.example.org/board2/install-XXX.

Your second board is now reachable at http://yourhostname.example.org/board2

If you do not want to create a separate database for each board but
rather want to concentrate them all in one, you only need to give each
board a distinct $table_prefix; they can easily share a single
database.  
Note that in this case, usually everyone will then however have access
to all the forums' databases, unless you set table-specific privileges
in your database server.

Multiple boards across virtual hosts is also possible; continue reading.

---------------------------------------------------------------------------

We've had reports that the above doesn't work reliably in some situations. The
forums will then just sometimes have the wrong settings. We believe that
this is not phpBB at fault (esp. because of the "sometimes"), but we did
receive this workaround from Rob Bos:

	I've worked around this bug as follows, at Ian Pushee's advice, and
	having a single config.php file that is called from all the forum
	virtualhost blocks via auto_prepend_file:

	<?php
	$dbhost = 'localhost';
	$dbname = 'example';
	$dbuser = 'example';
	$dbpasswd = '3x@mpl3';

	if ($_SERVER["HTTP_HOST"] == "forum.example.com") {
		$table_prefix = 'excom_';
	} else if ($_SERVER["HTTP_HOST"] == "forum.example.net") {
		$table_prefix = 'exnet_';
	} else if ($_SERVER["HTTP_HOST"] == "forum.example.org") {
		$table_prefix = 'exorg_';
	} else {
		$table_prefix = 'ERR_NOT_EXIST_';
	}

	define('PHPBB_INSTALLED', true);
	?>

---------------------------------------------------------------------------

If you want to have multiple boards using virtual hosts, and have each board
use a separate database, then instead of the above, do the following:

1. Edit /etc/phpbb3/virtualhost_config.php as follows:

<?php
if ($_SERVER["HTTP_HOST"] == "forum.example.com")
{
   $dbms = 'mysql';

   $dbhost = 'mysql.example.com';
   $dbname = 'phpbb_sites';
   $dbuser = 'mylogin';
   $dbpasswd = 'mypassword';

   $table_prefix = 'phpbb_';
}
else if ($_SERVER["HTTP_HOST"] == "forum.example.net")
{
   $dbms = 'postgres';

   $dbhost = 'postgres.example.net';
   $dbname = 'phpbb_sites';
   $dbuser = 'mylogin';
   $dbpasswd = 'mypassword';

   $table_prefix = 'phpbb_';
}
else if ($_SERVER["HTTP_HOST"] == "forum.example.org")
{
   $dbms = 'mysql';

   $dbhost = 'mysql.example.org';
   $dbname = 'phpbb_sites';
   $dbuser = 'mylogin';
   $dbpasswd = 'mypassword';

   $table_prefix = 'phpbb_';
}
else {
   $table_prefix = 'ERR_NOT_EXIST_';
}

define('PHPBB_INSTALLED', true);
?>

2. Uncomment the <VirtualHost *:80> section found in
/etc/phpbb3/apache2.conf and make an appropriate change to ServerName
-- i.e. forum.example.com. Make sure the line:

    php_value auto_prepend_file /etc/phpbb3/virtualhost_config.php

points towards the file which you just edited above in step #1.  Each
VirtualHost section should include this same line and all should point
to the same config file.

3. Add additional <VirtualHost *:80> sections to apache2.conf as necessary
for each of your intended phpbb3 boards.  Each VirtualHost section
must have a different ServerName that obviously corresponds to each
individual board -- i.e.  forum.example.com, forum.example.net,
forum.example.org, etc.

4. Make sure you have proper DNS resolution on your DNS server for
each of the different boards of your set up in each of the VirtualHost
sections.

5. After making all changes, reload apache - service apache2 force-reload.

---------------------------------------------------------------------------
Multiboard Issues
---------------------------------------------------------------------------

Preliminary Notes
=================
First, multiboard support itself is not an official feature from upstream.

The source has been modified in this package such that caching will
not break when running multiple boards from the same codebase. The
"store" directory (database backups) will also contain subdirectories
for the individual boards that you configure; creation of those
directories happens when needed - there is nothing you have to do.

This is what the store directory will look like for a forum at the URL
http://10.8.0.1:8800/phpbb/:

# ls -al /var/lib/phpbb3/store
drwx-wx-wt 3 root     www-data 4096 Mar 10 18:23 .
drwxr-xr-x 5 root     root     4096 Mar 10 16:06 ..
drwxr-x--- 2 www-data www-data 4096 Mar 10 18:23 10.8.0.1.8800.phpbb

For the rest, we provide some workarounds for other features where
patching the source is too intrusive. We leave that to upstream, if
those features are desired. Ask them.

Avatar Upload
=============

Avatar uploads go to the /var/lib/phpbb3/images/avatars/upload/
folder. Since this folder is common to all boards, there would be
conflicts as the uploads are stored by userid, which can be the same
in different forum instances.

You may of course simply create another avatar uploads folder and
use that one in ACP -> Avatar settings.

However, you can also change the avatar_salt value in the config table
of the respective boards' databases and make sure it is unique for
each board. phpBB uses this value to prepend the avatar's name in the
filesystem. No conflicts will then occur. Unfortunately this value
cannot be set in the ACP.

Make sure to empty the caches of the respective board after the
change.

Furthermore, the upload directory has permissions 1733, i.e. avatars
cannot be listed either, except by the superuser, so this is secure.

Note that if several forum instances run under the same (unix) userid
and the avatar_salt is not changed, avatars might get overwritten.

Avatar Galleries
================

You can make avatar galleries available to specific forums only when
running each forum under a different user ID (e.g. using suexec). You
can leave avatar galleries that should be available to every forum
simply with permissions 0755. Avatar galleries that should only be
available to specific forums should belong to the user running the
forum and have no permissions for other users; phpbb will silently
ignore those galleries if it cannot access them.

In the following example, the 'avatars' gallery is available to
everyone, the 'avatars2' gallery is however only available to the
forum run by user "web15_admin" and/or group "web15".

/var/lib/phpbb3/images/avatars/gallery# ls -l
drwxr-xr-x 2 root        root  4096 Mar 10 16:06 avatars
drwxr-x--- 2 web15_admin web15 4096 Mar 10 16:17 avatars2

Again: in this case, accessing the forum via a different DNS name or
such does not change anything. Which galleries are visible solely
depends on the server-side instance of phpBB you are accessing.

Attachments
===========
Attachments to posts are stored in /var/lib/phpbb3/files/.

Since these filenames are generated by md5() and microtime(), there is
not much need to worry about collisions.

As far as security is concerned, the files have permissions -rw-rw-rw-
but the directory has only drwx-wx-wt, so noone can list them. The
forum a specific file belongs to knows its exact name (in the
'attachments' table), and thus can access it.

Styles
======
All styles (from /etc/phpbb3/styles) are available for every board.