
  WebCollab Frequently Asked Questions (FAQ)
  =========================================



      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 //config/config.php/ below the root directory of
    WebCollab.

     #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 and pre-1.60 need to have
    the database upgraded with the by pointing your web browser at
    /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.


      START UP PROBLEMS
      -----------------
      
1. "Initial installation works, but logging in as admin has no effect
(no error message either)."
    
    This problem occurs with PHP 4.0.6 and lower. WebCollab will only
    run on PHP 4.1.0, or higher. Earlier versions of PHP do not support
    $_POST, $_GET or $_REQUEST global arrays, which are necessary for
    WebCollab to function.

    (The setup program now checks for early versions of PHP and will
    record an error).

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]
      mysql
      pgsql
      
      [Zend Modules]
      
      #


    Look for mysql and/or 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. Look for lines in php.ini like this:

      ;extension=mysql.so
      ;extension=pgsql.so
      

    Remove the semi-colon ';' from the module you want, and restart Apache.

    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 parameter $BASE_URL is correctly stated in
    config.php. Did you remember to add the trailing slash "/" as the
    config file says?

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. It
    will be automatically destroyed when the browser is closed, or the
    user logs out.

5. "Does Magic Quotes need to be set 'on' or 'off' in php.ini?"
    
    When magic_quotes set to 'on' in php.ini, input data is
    automatically feed through the addslashes() function for security.
    WebCollab reads the php.ini file, and applies addslashes() on input
    data if magic quotes is set to 'off'. The addslashes() function is
    important to prevent SQL injection attacks.


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 requires 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 leave Register Globals 'off' for better
    web site security, 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/ They can be easily changed to suit.

    Alternatively, a new customised language file can be set up and
    defined in /lang/language.php

2. Can the splash screen image be changed?
    
    Yes, add the new image to /images/ and set the $SITE_IMG parameter
    in /config/config.php

3. Can background colours and text styles be changed?
    
    Yes, see the style sheet /css/default.css.

4. Can external web server authorisation be used instead of the login
screen.
    
    Yes, set the $WEB_AUTH parameter to "Y" in /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 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 /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 /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 /includes/screen.php file contains 'commented out' code for
    compressed output buffering with ob_handler(). When this is enabled
    the output to the browser will be 'gzipped' before transmission,
    providing the browser is capable of accepting gzipped HTML - and
    most are. However, there is a downside to this form of output
    buffering: Compression does not start until _all_ the page is
    rendered by the web server. This creates a noticeably high latency
    in page loading; for this reason the code has been 'commented out'
    in WebCollab.

    The preferred method of output buffering is with
    zlib.output_compression set in php.ini. Refer to PHP Manual
    <http://www.php.net/manual/en/ref.zlib.php#ini.zlib.output-compression>
    for more information. The downside of this option is that
    zlib.output_compression is not available on all versions or flavours
    of PHP. 

2. Is caching worthwhile?
    
    WebCollab uses a modular codebase with a high reuse factor. Compiler
    caches will work well with WebCollab. Ioncube PHP Accelerator has
    proven very compatible with WebCollab; Turck MMCache and Zend
    products should also work well.


      UPLOADING FILES
      ---------------
      
1. Error message about directory not writable when uploading files with
the file upload feature.
    
    For Linux and *nix: Make sure the /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.

    Use 'chmod 777 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)
            $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. File upload security.
    
    If you use the default /files/filebase directory, it is possible for
    users to navigate to the directory with their browsers and view the
    files present. WebCollab has the /filebase directory protected by a
    index.html file and .htaccess file. Also, the filenames have a ID
    prefix added to them to prevent filename 'guessing' by attackers,
    but none of these measures are particularly foolproof.

    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. 


      EMAIL SETUP
      -----------
      
1. How does email work in WebCollab?
    
    Early versions of WebCollab used the mail() function call in PHP. In
    most cases it worked, but it proved troublesome with some SMTP servers.

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

    In /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
    /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. 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.
        * 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 //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 /setup directory
          and update.php.


      INTERNATIONALISATION
      ---------------------

1. What character encoding does WebCollab use? Or, what characters can
be used with WebCollab?
    
    The character encoding is set by the language file in use. For
    instance, English, French & German all use ISO-8859-1 encoding (this
    is also known as Latin 1 encoding). WebCollab is fully
    internationalised and language files should be able to be set up
    with most international character encodings. Multi-byte character
    encodings schemes will probably need the (optional) multi-byte
    strings library installed in PHP, and the related mb_function
    overloading to be enabled in php.ini.

    For better internationalisation capability, the Unicode version of
    WebCollab should be used. This natively supports over 650 languages.
    The database and PHP requirements, are however, much more stringent. 


      REMOTE DATABASE
      ---------------
      
1. Why can't remote databases be used with PostgreSQL?
    
    Since version 6.3 (March 1998) 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	=> PostgreSQL abstraction layer
    mysql	=> standard MySQL abstraction layer
    mysql_innodb	=> MySQL abstraction layer with innodb transaction support

2. PHP5 is bundled with SQLite. Why doesn't WebCollab support this too?
    
    At present SQLite does not have sufficient date/time functions to
    work with the WebCollab code. 


      TRANSACTIONS
      ------------
      
1. Are database transactions used?
    The PostgreSQL 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 witten 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.


    The mysql_innodb abstraction layer also uses transactions.

    For MySQL version 4.0, and above, innodb database support is enabled
    by default. For these versions (and configured 3.23.xx versions) it
    is recommended that the database be created with the mysql_innodb
    database creation script, and the mysql_innodb abstraction layer is
    used.

    For MySQL version 3.23.xx the database server _must_ first be
    correctly configured to allow innodb databases to be used. See the
    on line MySQL manual for more details:
    http://www.mysql.com/doc/en/InnoDB_in_MySQL_3.23.html 


      DATABASE BACKUP
      ---------------

1. Can the database be backed up?
    
    Two UNIX based shell scripts are provided in /db for backing up
    WebCollab databases.

    MySQL:

        dump_mysql.sh

       Usage: dump_mysql.sh  <database user> <database name> <databasepassword>

    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 /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 /help directory. 

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

        * Manually add the new files to the switch statements in
          /lang.php, lang_long.php & 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
          (andrewsimpson@users.sourceforge.net), they will be returned
          with updated files.

    Final step is obviously to alter the locale in the /config/config file.

