NOCC Documentation
------------------

Copyright 2000 Nicolas Chalanset <nicocha@free.fr>
Copyright 2000 Olivier Cahagne <cahagn_o@epita.fr>

Summary
*******

This file contains the following sections:
	* Overview of Nocc
	  - License
	  - Getting Nocc
	* Requirements for NOCC
	* Installing NOCC
	* Additional notes for NOCC
	  - History

Overview of Nocc
****************

   Nocc is a Web-based e-mail reader. It uses PHP and a Web server to access
a mail server (POP3, IMAP) and send e-mail (SMTP or plain sendmail).

   Nocc can be used as an e-mail reader and allows you to view, send messages,
manage your mail account. It can view and send MIME attachments (files, HTML,
etc.).

   Nocc has low requirements on browser, it uses JavaScript as less as possible,
nearly no frames and even works with Lynx without cookies; low requirements on
Web servers too: you don't need any superuser privileges to install Nocc and it
can work with suEXEC (see Apache documentation) for increased security.

   Nocc was earlier known as Epimail, written in Perl, but was rewritten with
PHP, hence the new name. See later for a bit of history.

   Anybody is encouraged to contribute.

  License
  -------

   The full application (source code, icons) is distributed under the terms of
the GNU General Public License. See the file COPYING for details.

  Getting Nocc
  ------------

   Nocc development is powered by the free services offered by SourceForge to
the Open Source community. The Web page of Nocc is http://nocc.sourceforge.net/

   The latest release can always be found on SourceForge and is available from
'http://sourceforge.net/projects/nocc/'. Announces are sent to the
'nocc_announce' mailing lists
(http://lists.sourceforge.net/mailman/listsinfo/nocc-announce).

   A public CVS server is also accessible. See
'http://sourceforge.net/cvs/?group_id=12177'.

  Reporting bugs, sending suggestions or contributions
  ----------------------------------------------------

   We welcome bug reports or suggestions for Nocc (both program or
documentation). Please email them to <nocc-discuss@lists.sourceforge.net>.

   You can also use the Web-based bug tracker from SourceForge available at
'http://sourceforge.net/bugs/?group_id=12177'.

Requirements
************

  Mandatory Items
  ---------------

   * PHP 4.0.0 or later with IMAP support (--with-imap) -- SEE NEXT SECTION
  
   * A Web server supported by PHP (i.e. Apache for most people)
  
   * An IMAP or POP3 server to connect to.

  Optional Items
  --------------

   * An SSL Web server to allow encrypted connections.
     (Apache+mod_ssl+OpenSSL is popular)

  Notes on PHP
  ------------

   * PHP needs to be compiled with IMAP support. (--with-imap at the configure
     stage).
     You'll find information on IMAP support for PHP at
     'http://www.php.net/manual/ref.imap.php'.

Installing NOCC
***************

  Installation of NOCC
  --------------------
       
       1) Download nocc-x.y.tar.gz (where x and y are version numbers)
	  (or nocc-x.y.zip for Windows' users).
	  http://nocc.sourceforge.net/

       2) untar/unzip nocc into the directory you want.
	  Default directory is nocc.
      
       3) Change into the 'nocc' directory, make changes to the 
          config file (conf.php.dist) and save the new one to conf.php
	  (remove .dist in the file name)

           'conf.php.dist' contains a large number of default values
           that you'll need to configure for your system, such as
           the default IMAP/POP3 server, whether or not users can pick a
           different server, etc...
	   The file is fairly well documented, so you should be able to pick
	   out what you need to change fairly easily.

       4) (Optional step)
	  if you run with suEXEC, you'll need to run './addcgipath path' to add
	  the parser line at the beginning of PHP files.

       5) Remove ./addcgipath.sh. For security reasons, it might be run by
          external users although "sh" files are never interpreted by Web
          servers with default configuration.

Theme tips
**********

You can customize the look and feel of NOCC very easily, using a combination of
conf.php options, and themes. There are a few default themes you can choose
from, or you can copy an existing theme (to a new subdirectory of themes), and
customize it to your own requirements.

You can customize the leading and trailing HTML generated by NOCC by altering
the header.php and footer.php files in the themes' directory.

Security
********

 - NOCC was initially coded with security in mind as it had to run via suEXEC.
Therefore, there were security holes discovered by white-hat hackers which
are now fixed by 0.9.5.

 - How to setup proper Profile directory for Preferences ?
Either create it outside of the Web tree or, if you only have choice to
create it within the Web tree, setup a .htaccess to restrict access to
the files created.

 .htaccess would contain:

 Order Deny,Allow
 Deny from all

It won't be a security hole but anyone knowing Nocc could download users's
signature files (useful ? privacy issue ?) and perhaps use them for spam...
Note: due to this fact and that it might not be easy/possible for everyone,
depending on provider, Web server, etc., this is disabled by default.

Additional notes
****************

  Known working setups
  --------------------

   NOCC has been tested with (unfortunately, we don't have enough manpower
to test every setup at each release, we have just sometimes tested this with
some version of NOCC and it worked, we'd like to have a matrix of what works
for every release and be able to update it with users' setups):

	* servers: (Nocc should work with any server, however, these have been
specifically tested and are known to work)
	  - Apache with PHP compiled as module or CGI.
	  - Apache 1.3.12, 1.3.14, 1.3.17, 1.3.19, 2.0.14 (Win32).
	  - Microsoft IIS 4.0, IIS 5.0 w/CGI, IIS 5.0 w/ISAPI.
	  - O'Reilly WebSite Pro 2.x & 3.
	  - Xitami.
	  - PHP 4.0.0, 4.0.1, 4.0.1pl1, 4.0.2, 4.0.3pl1, 4.0.4, 4.0.4pl1, 4.0.5.
	  - PHP running through a wrapper: suEXEC.
	  - various OS including GNU/Linux, FreeBSD, NetBSD, OpenBSD and Win2k.
	  - PHP 4.0.4-dev compiled as module for Apache Win32.
	  - warning: due to a sessions bug, only PHP 4.0.4 or higher will run
	    correctly on Win32 platforms.

	* browsers: (256 colors setups are ok)
	  - Netscape 4.x, 6.x for Unix and Windows.
	  - IE 4.x, 5.x for Windows.
	  - Lynx 2.8.3, Konqueror, Opera, WebTV 3.0.
	  - Mozilla 0.x for Linux and Windows.
	  - with or without cookies.

	* mail servers: (Nocc should work with any IMAP/POP3 server, however,
these have been tested and work)
	  - UCB POP3 1.831beta.
	  - MS Exchange 5.5 Build 2650-24 Service Pack 3.
	  - Default RedHat 6.1 IMAP daemon v.12.250 (perhaps Cyrus IMAPd ?).

        * MTA: (Nocc should work with any MTA, however, these have been tested
and work)
	 - Sendmail.
	 - Postfix.

   NOCC has been used for many months at:

	* a company with approx. 150 unique users/day,
	* a school with also 150 unique users/day,
	* several other, see http://nocc.sf.net/ .

  Tips
  ----

   Enhance randomization with PHP by uncommenting the entropy lines if your OS
has this feature (known to work with NetBSD and Linux for e.g.).
   See PHP manual, this is used for session numbers, creating temporary files,
etc.

  Brief history
  -------------

   NOCC started as Epimail, a Webmail for our school as a free project.
   The first version was written in Perl because it was powerful, has
object-oriented features, adapted to the Web and available in our school. It
also didn't require any superuser privileges.

   Webmail clients we found either required database support, superuser
privileges or an IMAP server. We had neither of these and we wanted to have
something quite simple to access a POP server and an SMTP server.

   The Perl version was nice and is now released for your pleasure in GPL (some
people actually already committed patches) but it won't work out-of-the-box, we
don't have time to write documentation neither maintain it anymore).

   We started working on Epimail in May 1999 and had it working in July 1999,
it's been working for more than 1 year with approx. 150 unique users per day.
The projects has also been used by two companies through some friends who came
to know it.

   The problem was that it was our first big software written in Perl, and we
didn't write it very well, mixing code and HTML, so it was hardly maintainable.
Meanwhile, I discovered PHP and started rewritting it with PHP but lacked SMTP
support so sendmail was required. Then submitted my work to Nicolas Chalanset
who made a working version by adding proper session feature, etc. and actually
used it for a company.

   We decided to make a maintainable and public version under GPL so that it
can be simple to setup, have POP and SMTP features, MIME decoding features.


----------------------------------------------------------------------
We hope you find NOCC useful and easy to use.  We thank you for taking
the time to try it and if you ever have any questions, just drop a note on
<nocc-discuss@lists.sourceforge.net>

Enjoy,

The NOCC team
----------------------------------------------------------------------
