Frequently Asked Questions

FAQ INDEX

Setup Problems
Startup Problems
Customising WebCollab
Performance Tuning
Uploading Files
RSS Feeds
iCalendar
Email
Security
Internationalisation
Unicode
Remote Databases
Database Types
Database Transactions
Database Backups
Translations

SETUP PROBLEMS

1. Setup program says that database can be created, but cannot write to the config file.

The web server does not/cannot have permissions to write to the config file. You need to make the config file world-writable. The config file is [webcollab]/config/config.php.

#chmod 666 config.php

For security, reinstate afterwards with:

#chmod 664 config.php

2. How to upgrade from an earlier version of WebCollab?

Refer to the INSTALLATION file. Briefly, all versions are upgradable by adding the new files. Versions pre-1.40, pre-1.60, pre-1.70, pre-2.00, pre-2.20, pre-2.50 and pre-3.00 need to have the database upgraded with the by pointing your web browser at [webcollab]/update.php.

3. All the documentation mentions the Apache web server. Can we use Microsoft IIS instead?

WebCollab is not tested nor supported on Microsoft IIS. That said, we have had successful reports of WebCollab running on Microsoft IIS (Windows Server 2003 and Windows Server 2000).

Here is how one Windows user got it working:

1. PHP and Mysql were previously installed and working for other apps.
2. Used Internet Services Manager to create website with Frontpage extensions.
3. Unzipped Webcollab to website folder.
4. Gave the default anonymous IUSR_servername write rights to config.php.
5. Completed the setup page ignoring the invalid url error. I used the root user to create the database and also the user for setup.
6. Since for some reason I couldn't get it to work for the root user I created a new user with full rights to the database. I then edited the config.php file to reflect the change of user and password.
7. Removed the default anonymous IUSR_servername write rights to config.php.
8. Using the Internet Services Manager I restarted IIS.
9. Logged in and it was working.

4. How do you install the mb_string library on Windows?

1. If you have only downloaded the "short" version of PHP (Named like 'php-4.3.10-installer.exe'), then download the full version (Named like 'php-4.3.10-Win32.zip').
2. Unzip the full version into a directory
3. Find php_mbstring.dll in your unzipped full version directory (For example: c:\php-4.3.10-Win32\extensions).
4. Copy php_mbstring.dll across to your working php\extensions directory
5. Use Notepad (or similar text editor) to open your php.ini file.
6. Change the extension_dir line to read:
   

   extension_dir = "c:\php\extensions\"

   
   (or whatever your extensions directory is called)
7. Remove the semi-colon on line:

    ; extension=php_mbstring.dll
   

8. Save the file, and restart Apache.

4. How do you install the mb_string library (for the Unicode version of WebCollab) on Linux?

• Some Linux distributions, such as Debian and derivatives, already have mb_strings compiled into PHP.
• Some Linux distributions, notably Suse, Mandriva & Fedora have a separate RPM package for mb_strings that needs to be installed.
• For compiling from source, you need to ensure that PHP has been compiled with the '--enable-mbstring=all' option set, and that the module enabling lines (see previous question) have been set in php.ini.

START UP PROBLEMS

1. "Initial installation works, but logging in gives a error message about undefined ctype_space function.

The ctype function is built into PHP, but some Linux distributions - notably Mandriva & Suse - have a separate RPM package for 'php-ctype'. It is a small package of about 10 kb, and needs to be installed.

For FreeBSD you have to install the textproc/php4-ctype port.

(The requirement for ctype functions was removed with WebCollab 2.00, and later versions).

2. "Initial installation works, but logging in as admin gives a blank screen."

Check that PHP has your database extensions compiled in. From the command line type 'php -m':

# php -m
Running PHP 4.2.2
Zend Engine v1.2.0, Copyright (c) 1998-2002 Zend Technologies

[PHP Modules]
pdo_mysql
pdo_pgsql

[Zend Modules]

#

Look for pdo_mysql and/or pdo_pgsql as required in the modules listing that follows.

Most likely cause is that the default file for php.ini has the mysql or pgsql module line commented out.

For UNIX based systems add this to php.ini

extension=pdo.so

Restart Apache to enable the extension.

>

For Windows based systems with PHP less than 5.3.0, add this to php.ini

extension=php_pdo.dll

Then for all versions of PHP on Windows add the appropriate extension:

extension=php_pdo_mysql.so
extension=php_pdo_pgsql.so

Restart Apache to enable the extension.

Also - many Linux distributions have separate packages (*.rpm, *.deb, etc) for the main PHP files and the MySQL/PostgreSQL PHP support. You need to install the relevant module package as well.

3. Setup says "Your version of PHP does not have support for MySQL..." or "Your version of PHP does not have support for PostgreSQL..." and then dies.

This is the same as the problem above.

4. "Can login, but the main page is not found (404 error)."

Check that the the defined parameter BASE_URL is correctly stated in config.php. Did you remember to add the trailing slash "/" as the config file says?

5. In Suse Linux 10 (and above) attempting to run setup gives an error about direct access not allowed.

Note: This is fixed in Webcollab 2.00 and later.

For some reason Suse have changed the default php.ini file. This causes problems for WebCollab because the include_path parameter is changed.

Edit the [webcollab]/path.php file to look like this:

<?php

ini_set('include_path', '.' );

define('BASE', '' );

?>

The line starting 'ini_set' is new and has been added to the file. Nothing else is changed.

The fix will be immediate; no need to restart, or reboot any services.

5. "Does WebCollab use cookies?"

Yes, if possible. Cookies are preferred for session management, but aren't reliable with all browsers.

Webcollab attempts to set a session cookie at the login. Additionally it uses encoded URI's at this stage, also for session management. If the session cookie is found to be successful (i.e. the user's browser accepts the cookie), the encoded URI's are dropped. Otherwise session management with encoded URI is continued.

The session cookie lasts only as long as the current session. The cookie is automatically deleted when either the browser is closed, or the user logs out.

5. "Does Magic Quotes need to be set 'on' or 'off' in php.ini?"

WebCollab does not use the Magic Quotes function in PHP. If magic quotes is enabled, WebCollab will override it. After input data is validated and normalised, the data is properly escaped before submission to the database.

6. "Does Register Globals need to be 'on' in php.ini?"

Software written for early versions of PHP (prior to version 4.1.0) often required Register Globals to properly receive input data. However for important security reasons Register Globals has defaulted to 'off' since PHP 4.2.0. WebCollab does not require Register Globals. You should always leave Register Globals 'off', unless it is specifically required to be 'on' for other scripts.

CUSTOMISING WEBCOLLAB

1. Can the 'Done', 'Active', 'On Hold' etc, labels be changed?

Yes, all the parameters are defined in the language files in [webcollab]/lang/ directory.

They can be easily changed to suit.

Alternatively, a new customised language file can be set up and defined in the redirection files [webcollab]/lang/lang.php, [webcollab]/lang/lang_long.php and [webcollab]/lang/lang_email.php

2. Can the splash screen image be changed?

Yes, add the new image to [webcollab]/images/ directory and set the SITE_IMG parameter in [webcollab]/config/config.php

3. Can background colours and text styles be changed?

Yes, see the style sheets the directory [webcollab]/css/. The default style sheet is default.css with the other style sheets calendar.css and print.css being for additional styles calendar and printing options respectively. The names of style sheets can be defined in [webcollab]/config/config.php

4. Can external web server authorisation be used instead of the login screen.

Yes, set the WEB_AUTH parameter to "Y" in [webcollab]/config/config.php. Username is taken from the REMOTE_USER environment variable set by Apache.

5. What web browsers is WebCollab compatible with?

WebCollab is valid XHTML 1.0 (Strict) and uses CSS1 cascading style sheets. Some Javascript is used, but this is not essential. This means WebCollab is compatible with most contemporary web browsers.

6. My ISP only gives me one database with my account. Can WebCollab share a database with another application, or applications?

Yes, the easiest way is to manually add a unique prefix to the all the table names SQL in [webcollab]/db directory. A suitable prefix might be 'webcollab_'. After that the tables can be created by running setup, or by doing a manual SQL creation (see the INSTALL file). Finally, the line in [webcollab]/config/config.php that reads 'define("PRE", "" )' needs to be altered accordingly. For the example above, this would become 'define("PRE", "webcollab_" )'.

PERFORMANCE TUNING

1. Can output buffering be used to speed up WebCollab?

WebCollab is normally very fast. Most bottlenecks are caused by database performance rather than PHP throughput.

The [webcollab]/config/config.php file contains code for compressed output buffering with zlib. When this is enabled the output to the browser will be compressed before transmission, providing the browser is capable of accepting compression - and most are.

To enable, set the parameter below:

//Use external webserver authorisation to login (values are "N", or "Y")
define('WEB_AUTH', "N" );

Refer to PHP Manual for more information.

2. Is caching worthwhile?

WebCollab uses a modular codebase with a high reuse factor. Compiler caches will work well with WebCollab.

UPLOADING FILES

1. Error message about directory not writable when uploading files with the file upload feature.

Make sure the [webcollab]/files/filebase directory is writable by the web server. This means the directory should be either owned by the web server user (usually apache, www or www-data) or the directory must be world-writable.

For Linux: Use 'chmod 666 filebase' from the files directory, and preferably move the directory outside the web server root - see item 3 below.

2. File upload gives message about server configuration not allowing uploads.

Check that the PHP configuration file, php.ini, is set to allow file uploads. Check that 'file_uploads = On', or file uploads cannot work.

3. Increasing the file upload limit for bigger files.

There are three configuration files that the control the upload file size:

1. The FILE_MAXSIZE parameter in [webcollab]/config/config.php. This can be changed by the setup program, or by manual edit of the file.

   //max uploaded file size in bytes (2 Mb is the default)
   define('FILE_MAXSIZE', 2000000 );

   The default file size limit is 2 Mb.
2. There are settings in Apache which you may need to change. In particular this affects large file uploads. On Red Hat Linux this setting is very low by default, you can change the limit by adding or editing a lines in Apache's httpd.conf with the upload size in bytes (different operating systems may have these files in different locations):

   <Files *.php>
    SetOutputFilter PHP
    SetInputFilter PHP
    LimitRequestBody 10485760
   </Files> 
   

   The size limit in this example is 10 Mb (10,485,760 bytes)
3. PHP also has two more byte limits, which you can set in php.ini, and sometimes in a .htaccess file:

   php_value upload_max_filesize 20000000
   php_value post_max_size 20000000
   

   The default size limit is 2 Mb.

4. Certain types of downloaded files are corrupted, or an error message occurs about 'Unrecognised file type'. WebCollab may give an error message of 'Files action handler: No request given'

This is caused by the uploaded file type not having an appropriate entry in the webservers Mime Type file (In Linux this file is normally /etc/mime.types).

The list of registered mime types is available at IANA. If in doubt choose 'application/octet-stream', which is the mime type for generic binary data.

If you do not have access to the mime types file, a .htaccess file can be used with AddType (See Apache documentation for detail).

5. File upload security.

If you use the default [webcollab]/files/filebase directory, it is possible for users to navigate to the directory with their browsers and view the files present. WebCollab has the [webcollab]/files/filebase directory protected by a index.html file and .htaccess file. For this to be effective, .htaccess files do need to be enabled in the Apache configuration.

Ideally, for good security move the file upload directory to outside the web server root directory. WebCollab can accommodate an upload directory in any location of the local file system - not just the web server root directory. Make sure the chosen directory is writable by the user that normally runs the web server.

RSS Feeds

1. How do you enable RSS feeds in WebCollab?

Because WebCollab has access control for each user the RSS feed also has to be password protected. This is unlike normal RSS feeds that are essentially free access.

The password access for the RSS feeds is controlled using the .htaccess (hypertext access) function provided by the Apache webserver. This function is enabled by providing an .htaccess file in the [webcollab]/rss/ directory. Here is a sample .htaccess file:

AuthType Basic
AuthName "WebCollab"
AuthUserFile /etc/apache/passwd/passwords
AuthGroupFile /etc/apache/passwd/groups
Require group GroupName

The usernames and passwords need to be setup in the named file, which in this example is /etc/apache/passwd/passwords. The usernames in this file also need to match the existing usernames in the WebCollab database. More information on setting up this file is given in the Apache website documentation

Once this is set up correctly, users can connect a RSS feeder withauthentication to the following WebCollab feeds:

• [webcollab]/rss/rss_forum.php
• [webcollab]/rss/rss_tasks.php
• [webcollab]/rss/rss_files.php

For RSS readers that do not support password authentication, the username and password can be given with the URL. The syntax for this is given in RFC 1738:

http://<user>:<password>@<host>:<port>/<url-path>

For a typical Webcollab setup at mysite.webcollab.com with this might be:

http://username:password@http://mysite.webcollab.com:80/rss/rss_projects.php

Once RSS has been set up, you may wish to enable RSS autodiscovery in the configuration file, [webcollab]/config/config.php.

iCalendar

1. What is iCalendar?

iCalendar is a standard (RFC 2445) for calendar data exchange. In WebCollab 'iCalendar' icons are provided on the top right of most task pages. Clicking on this icon will create a downloadable file in the iCalendar format. This file can then be loaded into other compatible calendar software.

2. WebCollab iCalendar won't work with some other third party applications.

WebCollab uses To-do (VTODO) element to describe tasks and projects. Some calendar projects only recognise the Events (VEVENT) element.

Changing the VEVENT parameter in [webcollab]/config/config.php the file to 'Y' will force WebCollab to produce files with VEVENT instead of VTODO.

EMAIL SETUP

1. How does email work in WebCollab?

WebCollab preferably uses the standard SMTP protocol over TCP/IP to 'talk' to a mail server. The mail server can be remote or local. WebCollab handles the mail interaction by a purpose written SMTP mailer that is compliant to RFC 821 (RFC 2821), RFC 822 (RFC2822), et al.

In [webcollab]/config/config.php:

SMTP_HOST = DNS name or IP address of the SMTP server

2. My SMTP server needs me to use SMTP AUTH before accepting mail!

If SMTP AUTH is enabled in the config file, WebCollab will automatically login with 'plain', 'login' or 'CRAM-MD5' authorisation. The required auth format is automatically detected.

You need to set your login name and password in the [webcollab]/config/config.php file.

WebCollab complies to RFC 2195 (CRAM-MD5), RFC 2554 (SMTP AUTH) and RFC 2595 (auth plain).

3. Can WebCollab handle non US-ASCII characters (i.e.Languages other than US English)?

For languages with more than "US-ASCII" characters (e.g.: French, German, Spanish etc), WebCollab attempts to send emails in 8 bit format. This is accepted by almost all mail servers. Sendmail, for instance, has had 8 bit support since 1993.

If the upstream SMTP server does not advertise support for 8 bit mail, WebCollab reverts to 'quoted-printable' encoding. This follows the requirements of RFC 1652 (8BITMIME), RFC 1869 (Extended EHLO), RFC 2045 (quoted-printable), and RFC 2047 (8 bit extensions).

4. Can the PHP mail() function be used instead?

Some servers, notably Windows servers, do not have access to a SMTP mail server. These sites will generally allow mail access with the PHP mail() function.

To enable the PHP mail() function in WebCollab change the mail transport definintion in the [webcollab]/config/config.php file:

 //mail transport (SMTP for standard mailserver, or PHPMAIL for PHP mail() )
define('MAIL_TRANSPORT', "PHPMAIL" );

The PHP mail() function is not as fully featured as the WebCollab SMTP built-in, and may not work reliably with all systems.

5. Common problems getting email to work.

• Check the mailserver set in config is the correct address and can be accessed by the web server. This is a particularly common problem. If during setup configuration the setup program gives a warning error, you do not have the right mailserver address.
• As an Admin go into 'Admin config' menu and make sure the return addresses are set for email. These must be valid return addresses for the email server you are using. Incorrect or lack of any address in Admin config, will usually cause the server to reject emails from WebCollab
• For SMTP AUTH the return address must be valid for for the username / password combination.

5. What is the mailing list (mentioned in Admin Email), and how does it work?

The mailing list is set up in Admin Config, which can only be accessed by an admin.

Every email sent by WebCollab (except user details) is also sent to the mailing list. Users on the mailing list will then get a lot of mail, but they will be fully abreast of the site workings.

SECURITY

1. What are practical measures to increase site security?

WebCollab has been coded with strong security measures. In practical use WebCollab security has proven to be very robust.

Practical measures to enhance security include:

• Shift the uploaded file directory to outside the web server root. WebCollab can write to anywhere in the file system. Check that the web server has write permissions for the chosen directory. This prevents uses uploading files, then navigating to the upload directory with a browser and executing the file.
• Shift the config file out of the webserver directories. You will need to alter the file [webcollab]/path_config.php and add the new path to the include_path directive in php.ini.
• Shift the program files out of the webserver directories. You will need to alter the file [webcollab]/path.php and add the new path to the include_path directive in php.ini.
• Use a non-root user for the database. The database user should have minimal privileges, and not be able to create and/or delete tables.
• Make sure that Apache configuration allows .htaccess files to set <Limit> in WebCollab directory. WebCollab uses .htaccess files extensively to protect subdirectories.
• Make sure the file [webcollab]/config/config.php is not world writable and not owned by the web server user.
• Use an SSL layer for access with WebCollab.
• Delete unnecessary files. For instance the [webcollab]/setup directory and [webcollab]/update.php.

INTERNATIONALISATION

1. What character encoding does WebCollab use? Or, what characters can be used with WebCollab?

The character encoding is UTF-8, (also know as Unicode). WebCollab is fully internationalised and language files can be set up with any language encodings.

UNICODE

1. What is the Unicode version, and why is it relevant?

The standard character sets use a single byte character set specific to the language being used.

This method has two major disadvantages: Because it is single byte, only 255 different characters are possible (this is a problem with Chinese, Japanese for instance). Secondly, differing character sets cannot be mixed in a single application.

This Unicode version of WebCollab converts the localisation to Unicode (UTF-8), which natively supports over 650 languages. Chinese, Japanese and European languages, for instance, can be displayed simulataneously on the same screen.

REMOTE DATABASE

1. Why can't remote databases be used with PostgreSQL?

PostgreSQL uses UNIX domain sockets by default. TCP port will NOT be opened by default. The TCP option can be enabled with the '-i' flag to postmaster and it's meaning is: "listen on TCP/ IP sockets as well as Unix domain sockets".

Usually the pg_hba.conf (PostgreSQL config file) also needs to be edited to allow TCP/IP connections.

Changing DATABASE_HOST in config.php from "localhost" to anything else (including 127.0.0.1) without reconfiguring PostgreSQL will always prevent WebCollab from connecting to the database.

DATABASE TYPES

1. What are the database types in the config file?

postgresql_pdo	=> PostgreSQL abstraction layer
mysql_pdo	=> standard MySQL abstraction layer

2. PHP 5 is bundled with SQLite. Why doesn't WebCollab support this too?

SQLite does not have sufficient date/time functions to work with the WebCollab code.

TRANSACTIONS

1. Are database transactions used?

The PostgreSQL and MySQL abstraction layer always uses transactions because:

• They provide better data security in the event of power failure or hardware/software crashes during database write operations. Incomplete data is not written to the database, and data corruption or loss is avoided.
• Without transactions it is possible for two users to alter the same data simultaneously, leading to data corruption. With transactions this is prevented by design.

DATABASE BACKUP

1. Can the database be backed up?

Two UNIX based shell scripts are provided in [webcollab]/db directory for backing up WebCollab databases.

MySQL:

# dump_mysql.sh
   Usage: dump_mysql.sh
 <database user> <database
name> <database password>

PostgreSQL:

# dump_postgresql.sh
   Usage: dump_postgresql.sh
 <database name>

Both dump into a plain text file. They can be automated with a cron job and emailed to a back up machine at regular intervals.

TRANSLATIONS

1. Can I translate WebCollab text messages to my language? And how do I do it?

The message translation files are in the [webcollab]/lang directory. Using English as an example, there are three main files:

1. en_message.php - message strings used in the program.
2. en_long_message.php - long text descriptions used in a few screens.
3. en_email.php - text used in the automated emails.

Each file contains a single string per line, with an id on the left hand side. For example:

"planned" => "Planned (not active)"

Translate the right hand side to your language. Save the file (replacing 'en' with your language).

The 'help' files are similar, but are mostly written in HTML text. They are found in the [webcollab]/help directory.

Please send a copy of your translation for inclusion in the main program.

2. How do I install the translation files that I've written?

Either:

• Manually add the new files to the switch statements in [webcollab]/lang.php, [webcollab]/lang_long.php & [webcollab]/lang_email.php. If you have some PHP programming experience, the correct format in the files will be obvious; or;
• Send the translated files to the author (email address in files). I am happy to check files and updatethe other program files to match.

Final step is to alter the locale in the [webcollab]/config/config file.

3. The translation file for my language still has some English phrases, or is out of date!

Some translations have been offered by translators who do not wish to maintain them, or often I have been unable to contact the maintainer by email for updating.

For these reasons, updates from others are welcomed.