====== README-multiboard - phpBB3 v. 3.0.7-PL1-4 ======

===== 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.
  * Edit ''/etc/phpbb3/apache.conf'' and add:
<code html>
	Alias /board2 /usr/share/phpbb3/www
	<Location /board2>
	        php_value auto_prepend_file /etc/phpbb3/board2.inc.php
	</Location>
</code>
  * 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//:

<code php>
<?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);
?>
</code>

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:

==== /etc/phpbb3/virtualhost_config.php ====

Edit /etc/phpbb3/virtualhost_config.php as follows

<code php>
<?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);
?>
</code>

==== <VirtualHost *:80> section in Apache ====

Uncomment the ''<VirtualHost *:80>'' section in Apache configuration file ''/etc/phpbb3/apache.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.

Add additional ''<VirtualHost *:80>'' sections to ''apache.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.

==== DNS resolution ====

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.

==== Reload Apache ====

After making all changes, reload apache - ''/etc/init.d/apache2 force-reload''.

===== Multiboard Issues =====

==== Preliminary Notes ====

First, <color black/yellow>multiboard support itself is not an official feature from upstream.</color>

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/%%'': 

<code>
# 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
</code>

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".
<code>
/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
</code>

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.