Imported from the SVN repository

http://svn.wolffelaar.nl/wsvn/phpbb/branches/jessie/

Signed-off-by: Olivier Gayot <duskcoder@gmail.com>

1 files changed, 245 insertions, 0 deletions

diff --git a/debian/README.multiboard b/debian/README.multiboard
new file mode 100644
index 0000000..e0f5048
--- /dev/null
+++ b/debian/README.multiboard
@@ -0,0 +1,245 @@
+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.