==================
NOCC Documentation
==================
Nicolas Chalanset <nicocha at free.fr>
Olivier Cahagne <wolruf at free.fr>
Arnaud Boudou <skuld at goddess-gate.com>
Oliver Heil <oheil at users.sf.net>
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
support ESMTP AUTH via LOGIN and PLAIN methods.
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; low requirements on Web
server 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.
Some files are distributed under the terms of the GNU Lesser General Public
License. See the the LGPL 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://sf.net/projects/nocc/'. Announces are sent to the
'nocc-announce' mailing lists: http://sf.net/mail/?group_id=12177
A public SVN server is also accessible:
http://sf.net/scm/?type=svn&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 at lists.sourceforge.net>.
You can also use the Web-based bug tracker from SourceForge available at
'http://sourceforge.net/p/nocc/bugs/'.
Requirements
============
Mandatory Items
---------------
* PHP 5.0.0 or later with IMAP (--with-imap) or Horde/Imap_Client,
iconv (enabled by default) and mbstring (--enable-mbstring)
support. -- SEE NEXT SECTION
register_globals directive must be set to 'Off'.
* A Web server supported by PHP (i.e. Apache for most people)
* An IMAP or POP3 server to connect to.
Optional Items
--------------
* SSL Web server to allow encrypted connections.
Notes on PHP
------------
* PHP needs to be compiled with IMAP, iconv and mbstring support
(--with-imap and --enable-mbstring at the configure stage).
Instead of php imap the Horde/Imap_Client can be used.
* register_globals directive must be set to 'Off'.
* You'll find information on IMAP support for PHP at
'http://www.php.net/manual/ref.imap.php'.
Installing NOCC
===============
If you upgrade from a previous installation, you should read UPGRADE file.
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.sf.net/
2) untar/unzip nocc into the directory you want.
Default directory is nocc.
3) Change into the 'nocc/webmail/config' 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.
How to use NOCC with PHP safe mode?
In order to add attachments to mails you send, you'll have to create a tmp
directory ($conf->tmpdir in configuration file), belonging to NOCC's php
scripts files, and with a 777 access mode.
In order to use preferences, IMAP filters and contacts manager, you'll have
to create a preference directory ($conf->prefs_dir in configuration file),
belonging to NOCC's php scripts. You can let the standard access mode (i.e.
755).
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.
- PHP 5.2.3, 5.6, 5.7, 7.0, 7.2, 7.4, 8.1, 8.2
- FreeBSD.
- MacOS X.
- Debian.
* browsers: (NOCC should work with any browser which support CSS and XHTML,
however, these have been tested and work)
- Internet Explorer.
- Safari.
- Firefox.
- Chrome.
- cookies needed as of 0.9.5.
* mail servers: (NOCC should work with any IMAP/POP3 server, however,
these have been tested and work)
- Courier-IMAP.
- Dovecot.
* MTA: (NOCC should work with any MTA, however, these have been tested
and work)
- Postfix.
- Exim.
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.
Thanks
------
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 at lists.sourceforge.net>
Enjoy,
The NOCC team
