Frequently Asked Questions
The following is a collection of frequently asked and
anticipated questions of PunBB.
Table of Contents
- Why can't I login?
- Does PunBB support BBCode and if so,
how do I use it?
- I keep seeing messages like "Bad
HTTP_REFERER.". How can I get rid of them?
- How do I grant a user moderator
access to a certain forum?
- Avatar uploads don't work. What could
- I get a message saying "Unable to
write configuration cache file to cache directory.". What's
- People using Internet Explorer 6 are
unable to login. Why?
- I've set the forum into maintenance
mode and I'm logged out. How do I turn it off?
- What's this "DEBUG mode" and
how do I enable it?
- Is it possible to have more than one
- I've updated the database manually,
but the changes have no effect. What's up?
Modifications and site integration
- How do I add more smilies to my
- How can I use smilies of different
sizes than 15x15 pixels?
- How do I add my own footer/header so
that I can integrate my forums into design of the rest of
- Is it possible to include my own PHP
scripts in the templates?
- I want to display information from
the forums on my website's front page. How can I do
- Does PunBB provide RSS feeds for
- I've developed a modification for
PunBB and I want to release it to the public. What do I do
License and copyright
- What license is PunBB released
- May I remove the copyright from the
- May I add my own copyright to the
- May I remove the copyright from the
1. General usage
- 1.1 - Why can't I login?
- There are many possible reasons. The most common reason is
that you have simply entered the wrong username or password.
Please double-check that you have entered the correct
information and try again. If it still doesn't work, you can
request a new password by clicking the link "Forgotten your
password?" on the login page.
- When you enter the correct username and password, you will
be redirected to the page on which you clicked the
"Login" link. If you find that after being redirected
you are still not logged in, the problem is almost certainly
related to cookies. PunBB relies on cookies to determine if you
are logged in or not. Make sure that your browser it setup to
accept cookies. If you are still unable to login, you should
contact an administrator of the forums you are having problems
- 1.2 - Does PunBB support BBCode and if so, how do I use it?
- Yes, PunBB supports BBCode. It supports a subset of the
tags that are present in many other bulletin boards. The tags
supported by PunBB are bold, underline, italic, color, url,
email, img, quote and code. Usage instructions can be found in
the script help.php. Links to this script can be found next to
text areas that allow BBCode (e.g. when posting a
- 2.1 - I keep seeing messages like "Bad
HTTP_REFERER.". How can I get rid of them?
- When a script in PunBB receives form data, it checks the
CGI variable HTTP_REFERER (misspelled in the HTTP standard) to
make sure that the form was submitted from the correct script.
The check is only made for administrators and moderators. The
referrer check is a security mechanism that prevents malicious
users from deceiving administrators and moderators by silently
and invisibly submitting a form from an external page to one of
the scripts in PunBB.
- The referrer check can fail for a number of reasons. The
check relies on the variable "Base URL" from the
options page in the admin interface. If "Base URL" is
not correctly set, the referrer check will fail. It is also
vital that you visit the forums by entering the exact URL found
in "Base URL" into your browsers address bar. If
"Base URL" is set to http://somehost.com and you visit
the forums by going to http://www.somehost.com (note the www
part), the check will fail.
- Another common reason for the check to fail is that you are
browsing the forum through a proxy or firewall of some sort
that is stripping HTTP_REFERER from all requests. Norton
Internet Security and Norton Personal Firewall are known to
strip HTTP_REFERER in its default setup. Some popup/ad stoppers
are also known to do this (most of them don't though).
- Note: You can find information on how to setup Norton
Internet Security and Norton Personal Firewall to not strip
referrer information at the following addresses:
2002 and earlier and
2003 and 2004.
- 2.2 - How do I grant a user moderator access to a certain
- The first step is to move the user user to the moderators
group. This can be done in the user's profile under
- The next step is to give the new moderator access rights to
one or more forums. This is also done in the user's profile.
Just below the drop-down menu we just used, you will find a
list of forums together with a checkbox. Select the forums you
want to grant the user moderator access to and click
"Update forums". The user is now a moderator and can
edit and delete posts and topics in the forums you
- 2.3 - Avatar uploads don't work. What could be wrong?
- In order for avatar uploads to work, the user account under
which the webserver runs must have write permissions to the
avatar directory. In UNIX (or UNIX-like) operating systems,
this is usually done via the command "chmod". Most FTP
clients have support for this and it is usually done by
right-clicking the directory and selecting something along the
lines of "Attributes" or "Permissions". If
you don't know what values to enter, try 0777 (or just 777 if
you can only enter three digits).
- 2.4 - I get a message saying "Unable to write configuration
cache file to cache directory.". What's wrong?
- Similar to avatar upload, where PunBB needs to be able to
write to the avatar directory, PunBB needs to be able to write
to the cache directory. See the above question for
- 2.5 - People using Internet Explorer 6 are unable to login.
- The problem is related to how Internet Explorer 6 handles
third party cookies. A first party cookie is a cookie that
originates from the host domain, whereas a third party cookie
originates from another domain. The problem arises when a
website utilizes some form of domain redirect or frame-based
redirect service. I.e. a service that redirects the user to the
real location instead of pointing directly at it. The best
solution to the problem is to not use such a domain redirect
service and use a "real" domain instead. However, a quick fix
that seems to work most of the time can be found in the script
include/functions.php. Search for P3P and follow the
- 2.6 - I've set the forum into maintenance mode and I'm
logged out. How do I turn it off?
- Copy/upload the script turn_off_maintenance_mode.php from
the directory extras/ into the forum root directory and run it
through your browser. A message will appear when the operation
has completed. Don't forget to remove the script from the forum
root directory when finished.
- 2.7 - What's this "DEBUG mode" and how do I enable
- "DEBUG mode" can be used to display more detailed
error messages in case of failure. These error messages can be
helpful when tracking down the cause of the failure. When
"DEBUG mode" is enabled, PunBB will also display the
script generation time and the number of SQL queries executed
for every page. This information will be displayed in the page
- To enable "DEBUG mode", open up the file
include/common.php in a text editor and locate the line that
starts with "//define('PUN_DEBUG', 1);". It it located
at the very top of the file below the software license
preamble. Then remove the two slashes in the beginning of the
line and save/upload the script. Once you've solved the
problem, it is recommended that "DEBUG mode" be turned
off again (just add the two slashes again).
- 2.8 - Is it possible to have more than one "Base
- No, it's not. However, there is extremely seldom a need to
have more than one. The need often arises when you access your
forums through one URL externally and one URL internally. The
internal URL is often the IP address or the name of the
computer that runs the webserver. The problem is easily solved
by editing your hosts file. The hosts file contains a list of
IP addresses and host names. If you haven't made any changes to
it earlier, it unsually only contains the IP address 127.0.0.1
and the hostname localhost. If you enter http://localhost/ into
your browsers adress field, your operating system will first
check the hosts file to see if localhost can be found in there.
If it finds it, it will navigate to the IP address 127.0.0.1
instead of trying to look up the host name localhost with
traditional DNS. So, what you want to do is to add a line to
this file with the IP address of the webserver and the hostname
that you use to access your server externally. If the host name
for your forums is www.mycoolforums.com and the IP address of
the webserver is 192.168.100.15, you would add the line:
- The hosts file is located in different locations depending
on what operating system you run. Here's a list of where the
file can usually be found in a few operating systems:
- Windows 95/98/ME: c:\windows\hosts
- Windows NT/2000/XP:
- Linux/UNIX: /etc/hosts
- Once you've added the line to your hosts file, you can set
your "Base URL" to www.mycoolforums.com and use that
URL to access your forums externally as well as
- 2.9 - I've updated the database manually, but the changes
have no effect. What's up?
- In order to decrease the load on the database server, PunBB
caches parts of the database to PHP scripts in the cache/
directory. If you've made manual changes to any of the tables
bans, config, categories, forums or ranks, the cached data
might have to be updated. To do this, simply delete all PHP
scripts in the cache/ directory. PunBB will regenerate them
when it needs them.
3. Modifications and site integration
- 3.1 - How do I add more smilies to my forums?
- Adding more smilies to your forums is not difficult, but it
involves editing one of the scripts that comes with PunBB.
Here's a step-by-step instruction. Having very basic knowledge
of PHP or programming in general is recommended.
- Copy the smilies you want to add/change to into the
- Open up the file include/parser.php in a text editor
and locate the line that starts with "// Here you can
add additional smilies if you like" (it's almost at
the top of the file). There you will find two PHP arrays -
$smiley_text and $smiley_img. $smiley_text contains the
character combinations for the smileys (e.g. :D or
:rolleyes:) and $smiley_img contains the filenames of the
smiley images (e.g. big_smile.png or roll.png).
- For every new smiley that you want to add, add a
character combination to $smiley_text and a filename to
$smiley_img. Please note that you must escape the character
' (singlequote) with a backslash if you use it in any of
your smilies (e.g. ':rock\'n\'roll:'). Singlequote must be
escaped so that PHP can understand that it is not the end
of the string, but a character in the string. The same goes
for backslash. If your smiley contains a backslash, just
must escape that backslash with another backslash (e.g.
- Once you've added your smileys above, you should pay
attention to the row below the smiley arrays. It says that
if any of your smilies contain any of the characters &,
", ', < or >, you must uncomment the row
- Finally save/upload the file and try it out. A list of
all installed smilies can be found at the bottom of the
help text in help.php.
- If you get a PHP error message stating that it encountered
a "Parse error", you probably forgot to escape a
singlequote or backslash character in the $smiley_text
- 3.2 - How can I use smilies of different sizes than 15x15
- To use non-15x15 pixel smilies, you must prevent PunBB from
adding the width="15" and height="15" attributes to img tags.
This can be done by editing include/parser.php in a text
editor. Open up the file and search for:
- The text should be somewhere around line 260. Then replace
the values with a width and height of your choice. If you want
to use smilies of varying sizes, remove the attributes
- 3.3 - How do I add my own footer/header so that I can
integrate my forums into design of the rest of my
- For this purpose, PunBB has a simple template system. The
template files are located in include/template/. There are five
templates - main.tpl, admin.tpl, help.tpl, maintenance.tpl and
redirect.tpl. The file main.tpl contains the template for
almost all pages that are displayed in the forum, admin.tpl is
the template for the admin interface, help.php is for the help
screen, maintenance.tpl is the template for the message page
that is displayed when the forum is put in maintenance mode,
and finally the file redirect.tpl is used to display the
redirect pages e.g. when logging in or when posting a
- The templates contain variables that are replaced with
actual content when a page is displayed. All variables in PunBB
are enclosed in less-than and more-than signs (< and >).
For example, the variable for the title of the forums is called
<pun_title>. When PunBB displays the index page, it reads
the file main.tpl and replaces <pun_title> with the title
of the forums. There are 11 replacement variables in
- If you want to customize the look of PunBB so that it fits
the design of other pages on your website, it is primarily the
template files you should edit. For example, if you wanted to
add your own logo at the top of all forum pages, you would edit
main.tpl and add markup for displaying your logo at the
appropriate position in the file. It is possible to include PHP
scripts from the templates. See the next FAQ entry for more
info on that.
- 3.4 - Is it possible to include my own PHP scripts in the
- Yes. PunBB has a special replacement variable called
pun_include for including scripts in the templates. For
example, if you wanted to include a script called banner.php
at the bottom of all forum pages, you would place the script
in include/user/ and add the following to your template
- The script banner.php must be located in the user include
directory mentioned above and its file extension must be .php,
.php4, .php5, .inc, .htm, .html or .txt. PunBB will execute the
script and the pun_include variable will be replaced by any
output that the script produces. Please note that all included
scripts have access to the PunBB variables, so if you e.g.
wanted to access the database, you could use the $db object just
like the rest of PunBB does. Be careful when dealing with global
variables in included scripts so that they don't collide with
PunBB's global variables.
- 3.5 - I want to display information from the forums on my
website's front page. How can I do this?
- The script extern.php found in the forum root directory can
output various bits of information from the forums. See
Developer Information for
- 3.6 - Does PunBB provide RSS feeds for recent discussions?
- Yes. The script extern.php found in the forum root
directory can produce RSS 0.91 feeds on recent discussions. See
Developer Information for
- 3.7 - I've developed a modification for PunBB and I want to
release it to the public. What do I do now?
- Visit the PunBB.org downloads page and
download the Mod SDK. It contains a text file with instructions,
a template for the readme file (all mods have a readme.txt) and
a template for a mod installation script (if needed).
- For more information about PunBB modding, visit the
4. License and copyright
- 4.1 - What license is PunBB released under?
- PunBB is released under The GNU
General Public License. In short terms this means that
PunBB is free to download, use, distribute, modify and even
charge for. However, if any of these modifications are released
to the public, that code must also be released under the same
license as PunBB.
- 4.2 - May I remove the copyright from the page footer?
- Yes, but please don't. If you must, please try to keep at
least "Powered by PunBB"
with the link to www.punbb.org intact.
- 4.3 - May I add my own copyright to the page footer?
- Yes, but you may not alter the original copyright in such a
way that it loses it's original "meaning". It must, in other
words, be absolutely clear who is the copyright holder of
PunBB. Adding an additional line with your copyright notice is
- 4.4 - May I remove the copyright from the source code?
- No. The copyright notice in all the source files must be
left intact. Any modification or removal of this copyright is
illegal under the terms of the GNU
General Public Licence.