Table of Contents

towerdevelopmentΔιαχείριση Δεδομένων

16 Δεκ 2012 (πριν από 4 χρόνια και 7 μέρες)

183 εμφανίσεις



Table of Contents


000

Requirements

................................
................................
................................
...........

000

Software License Agreement

................................
................................
...............

000

In
stallation

................................
................................
................................
..............

000

Installation process

................................
................................
......................

000

Using MySQL to store user preferences

................................
...................

000

Using PostgreSQL to store user preferences

................................
...........

000

Upgrading from versions previous to 1.3

................................
.................

000

Upgrading from version 1.3.0 to 1.3.1 or 1.3.2

................................
..........

000

Upgrading from version 1.3.x to 1.4.0

................................
.......................

000

Customisation

................................
................................
................................
.........

000

Templates

................................
................................
................................
.......

000

Hooks

................................
................................
................................
..............

000

Security

................................
................................
................................
....................

000

Directory Structure

................................
................................
.......................

000

Permissions

................................
................................
................................
....

000

Register Globals

................................
................................
...........................

000

Session Files

................................
................................
................................
..

000

FAQs

................................
................................
................................
.........................

000

Installation

................................
................................
................................
.....

000

Administration

................................
................................
..............................

000

V
-
webmail Admin Documentation

Richard Heyes

Table of Contents

Requirements

................................
................................
................................
...................

000

Software License Agreement

................................
................................
.........................

000

Installation

................................
................................
................................
........................

000

Customisation

................................
................................
................................
..................

000

Security

................................
................................
................................
..............................

000

FAQs

................................
................................
................................
................................
..

000

Requirements

PHP





PHP version 4.0.4pl1 minimum



IMAP Extension



Session support




Supported browsers



Windows



Internet Explorer 4 or higher



Netscape 6.1 or higher



Mozilla
0.9.8 or higher



Opera 6.0 or higher


Linux



Netscape 6.2 or higher



Other browsers (in particular those based on the Gecko engine) may be fine, but are
untested.



Software License Agreement


SOFTWARE LICENSE AGREEMENT


NOTICE: This License Agreement
("the License") is a legal agreement

between you (either as an individual or as any other legal entity) and

Richard Heyes ("the Author") for use of the software package ("the
Software")

provided with the License. By installing or otherwise using the

Softwa
re you agree to be bound by the terms of the License. If you do
not

agree to the terms of the License, do not install or use the Software.



1. GRANT OF RIGHTS



1.1 On condition that you conform with the terms and conditions of
this


License, the A
uthor grants to you the non
-
exclusive, non
-
transferable right


throughout the World to:



1.1.1 You may install and run a single copy of the Software. This
installation may


serve an unlimited number of virtual hosts. This installation
ca
n be on


multiple web servers which form a cluster. This installation
may serve:



1.1.1.1 A maximum of five (5) users if you have purchased the
five user license



1.1.1.2 An unlimited number of users if you have purchased the
unlimited

user


license



1.1.2 You may alter or update the source code as and when you need.
The source code


may or may not be provided in future versions.



1.1.3 You MUST NOT redistribute or make available to others, either
in full o
r part,


the source code of the Software.



1.1.4 The author reserves the right to terminate your license if
these clauses


are broken. No refund will be made.



2. COPYRIGHT


You acknowledge that no title to the intellectual property
in the

Software is transferred to you. You further acknowledge that title and

full ownership rights to the Software shall remain the exclusive

property of the Author and you will not acquire any rights except as
are

expressly set out in this License.



3.
NO WARRANTY


The Software is supplied "as is" without warranty of any kind, either

expressed or implied, including, but not limited to, the implied

warranties of merchantability and fitness for a particular purpose.



4. NO LIABILITY



4.1 The entire risk

as to the quality and performance of the Software
is


with you. Should the Software prove defective, you assume the
cost of


all necessary bug
-
fixing and correction;



4.2 In no event will the Author be liable to you for damages,
including any


general, special, incidental or consequential damages arising out
of the


use or inability to use the Software (including but not limited
to loss


of data or data being rendered inaccurate or losses sustained by
you or


third parties
or a failure of the Software to operate with any
other


software or systems).



5. SEVERABILITY


In the event of invalidity of any provisions of this License, you shall

agree that such invalidity shall not affect the validity of the other

provisions
of this License.



6. ENTIRE AGREEMENT


This License is the entire agreement between you and the Author and

supersedes any prior agreement or understanding relating to the subject

matter of this License.



7. GOVERNING LAW


This License shall be
governed by the laws of England and Wales and is

subject to the exclusive jurisdiction of the English courts.



8. NOTICES


All correspondence regarding any matter relating to this License should

be addressed to Richard Heyes, 4 Huntley Close, Mansfield,
Nottinghamshire,

NG18 5HP.





Installation

Installation process


1.

Extract the files. Make sure the htdocs directory is accessible via your web
server. If you extract the entire archive into a sub
-
directory (eg.
http://www.domain.com/v
-
we
bmail/) then this would make your url to V
-
webmail this: http://www.domain.com/v
-
webmail/htdocs/ Now this throws
up problems since it exposes the other directories, such as
includes

and
userdata
,
but this can be avoided by setting the document root of your

(virtual) server to
the htdocs directory. For example you could add this to your apache config (the
path will obviously need altering to suit your setup):


DocumentRoot /www/vhosts/v
-
webmail/htdocs/

DirectoryIndex index.php





2.

Permissions!

Ensure that the webserver can write to the userdata, logs and tmp
directories. Ideally only the webserver should be able to read/write these
directories. See the security section for more information on permissions.


3.

You n
ow need to edit the configuration files. First, make copies of servers.php,
vhosts.php and settings.php which are located in the config directory. The
copies should be called local.servers.php, local.vhosts.php and
local.settings.php. This copying is neces
sary for easier upgrading.


Now open up local.settings.php and follow the instructions in there; each
configuration option is documented.


Important:

Do not turn off config_checks until you are certain that V
-
webmail is
up and running. If there is a prob
lem with the configuration and this option is
off, you may experience unpredictable behaviour.


If you only want to allow access to one or a certain set of servers or you wish to
change the default options presented on the login page, you will need to edi
t
local.servers.php. Again, this file is fully documented. The most important
setting here is servers_strict. With this Off you can connect to any server you
specify with the default login page, however with it turned on you can only
connect to the servers

specified in this file. If you turn this on the default login
template will automatically change from presenting the server/port/folder
prefix options to instead presenting a single dropdown listing available servers
to connect to. The text visible in thi
s drop down is taken from the server
descriptions as marked by square brackets, eg [Default Server].


The local.vhosts.php file should be used to define any virtual hosts you wish to
use. If you only want to have a single vhosts, then this file simply ser
ves as a
further configuration file. Multiple virtual hosts should be used when you wish
for different domains to have different settings. eg mail.customer1.com and
mail.customer2.com could both have a different set of templates for branding
purposes. Each

option is documented in this file.


Very Important:

Unfortunately, bugs have been uncovered in the ini parsing
function in PHP. This means that it is not possible to use certain characters in
the config files. These illegal characters include (but may no
t be limited to): !
(exclamation mark) " (double quote) ~ (tilde). Some of these characters can be
used by enclosing the particular value in double quotes ("). Another possible
gotcha is having whitespace after a [...] line. This can cause the line to be
i
gnored.


Should you also wish to customise the default user and addressbook, you can
do so by making copies of the config/default.user.php and
config/default.addressbook.php files and prependingf their names with "local.",
so you end up with local.default
.user.php and local.default.addressbook.php.
You can then modify these files to suit your needs. These are not ini files, they
are actual PHP scripts, so be extra careful when modifying them, take backups,
and don't use single quotes. With regard to defaul
t special folders, you can enter
them here in the local.default.user.php file, but you must prefix the names with
the folder prefix that you're using. So if you're using INBOX. as the folder
prefix, and you want users' trash folder to be "Trash", you would

specify
"INBOX.Trash".


4.

You should now be able to login using a valid username/password for the
server details you supply.

Using MySQL to store user preferences


If you want to store your users' preferences and addressbook information in a MySQL
dat
abase (useful if you have a large number of users, and/or multiple webservers)
you need to perform the following steps.


1.
Follow the instructions in config/local.settings.php for changing the preferences
driver.


2.
Create table named "userprefs" in you
r database. The following table definition
can be used:


CREATE TABLE userprefs (


userprefs_id mediumint(8) unsigned NOT NULL auto_increment,


userprefs_host varchar(128) NOT NULL default '',


userprefs_user varchar(64) NOT NULL default '',


userprefs
_data text NOT NULL,


PRIMARY KEY (userprefs_id),


UNIQUE KEY host_user (userprefs_host,userprefs_user)

) TYPE=MyISAM;





3.

You will now be storing user preferences and addressbook information in the
database. I
t is important to not delete the config/default.user.php or
config/default.addressbook.php files however, as these are still used for the
default preferences and addressbook.

Using PostgreSQL to store user preferences


If you want to store your users' pre
ferences and addressbook information in a
PostgreSQL database (useful if you have a large number of users, and/or multiple
webservers) you need to perform the following steps.


1.
Follow the instructions in config/settings.php for changing the preferences

driver.


2.

Create a table in your database with the name specified in settings.php. The
following table definition can be used:


CREATE SEQUENCE userprefs__userprefs_id_seq;

CREATE TABLE userprefs (


userprefs_id smallint DEFAULT
nextval('userpr
efs_userprefs_id_seq') NOT NULL,


userprefs_host varchar(128) DEFAULT '' NOT NULL,


userprefs_user varchar(64) DEFAULT '' NOT NULL,


userprefs_data text DEFAULT '' NOT NULL,


PRIMARY KEY (userprefs_id)

);

CREATE UNIQUE INDEX hos
t_user ON userprefs (userprefs_host,
userprefs_user);




3.

You will now be storing user preferences and addressbook information in the
database. It is important to not delete the config/default.user.php or
config/de
fault.addressbook.php files however, as these are still used for the
default preferences and addressbook.

Upgrading from versions previous to 1.3


V
-
webmail 1.3 is significantly different from previous versions. Most if not all files
have been touched, wi
th many having been moved or removed. Most importantly is
the change in the way virtual hosts are defined
-

the admin section has been removed
with easier to maintain/administer configuration files located in the config/ directory.

As such the easiest way

to upgrade is:


1.
Install V
-
webmail 1.3 alongside your previous version


2.
Copy over your config/local.(settings|servers).php files


3.
Configure the local.vhosts.php file to your taste


4.
Copy over your userprefs data


5.

Run the convertprefs.php sc
ript (see the comments in the script for how to run
it). This script will convert prefs to the storage method you've set in
config/settings.php.

Upgrading from version 1.3.0 to 1.3.1 or 1.3.2


V
-
webmail 1.3.1 and 1.3.2 have only changed files, so upgradin
g is simply a matter of
backing up your current installation, and extracting the archive over the top. If you've
followed the procedure of making local. copies of configuration files, the config should
be unchanged. Some notable changes that you should be
made aware of are:


1.

The per virtual host "mail_send" option has now been removed. V
-
webmail will
by default send mail using the built in PHP functionality. If however you wish
to send via SMTP (reccommended for Windows installations), simply specify a
n
SMTP server in the appropriate place in the servers.php configuration file.


2.

You can now append text to all outgoing messages by using the per virtual host
setting "outgoing_append". This takes the name of a file in the config directory
and appends
all text in that file to outgoing messages. An example is provided
called v
-
webmail.txt.

Upgrading from version 1.3.x to 1.4.0


As with version 1.3.0, most if not all files have been touched with version 1.4.0.
Significantly though few have been removed.
This means that the normal procedure of
backing up your installation and extracting the archive out over the top should still
work just fine.


Important:

Due to the bug in 1.3.x which meant that the local.default.user.php file was
not honored, many people

will have modified the default.user.php file. You will need
to rename this file to local.default.user.php before upgrading to ensure your changes
are not lost.

Customisation

Templates


One of the areas where V
-
webmail really shines is the handling of tem
plates.
Templates are held in a sub
-
directory of the templates directory, with the name of the
sub
-
directory denoting the set. Each set can be specific to a virtual host, or available to
all virtual hosts, as defined in the vhosts.php configuration file (c
onfig directory). The
usual header/footer combinations are used, each being in it's own file
(header/footer.html).


The templates can be changed to suit your needs, though you should be careful to
avoid removing necessary parts which construct the program
s output. Most
installations will probably only ever need to change the header/footer combinations
and the stylesheets (htdocs/css/).


If you do need to alter one or more of the templates there are two ways. Method one
is to create a new template set by c
reating a new directory in templates/ and giving it
an appropriate name. Add this new set into your vhosts.php configuration file
(templates directive, see the comments above it for details), and then copy and modify
the templates you need changed. Don't w
orry about copying all the templates to the
new set, as V
-
webmail will automatically fall back to the v
-
webmail set if it can't find
one it needs in the new set. This method allows you to create a new set, and only
change the ones you need to.


Method two

involves copying the file you wish to change, to a new file with the same
name but prefixed with "local.", eg local.email.list.html. This file will be used instead
of the original. This method is advisable if the change you wish to make is minor, or
you d
on't need a new template set.


Important:

You should not delete or rename the v
-
webmail template set. This is used
in case any other sets do not have all the required templates.

Hooks


The purpose of the hooks.php file in the includes directory is for us
er defined
functions which are called at key points throughout the program. There follows a list
of these hook functions and their uses. More documentation for individual functions is
available in the hooks.php file. To use these functions, you should not
edit the file
directly. You should instead make a copy of the file, call it local.hooks.php, and edit
that instead.

hook_usernameLookup()


This function is called during login. It takes an argument of the username/password
and returns a two element array
of username and password eg: array('username,
'password') Amongst other things, it can be used in particular for doing username
aliasing. An example of this is given in the file. It's a basic example that could be
extended to LDAP/db lookups.

hook_emailLo
okup()


This function is called during login. It is however only called if the users email
address preference is blank, (it's therefore not called if the option
allow_changeable_email is Off (local.vhosts.php file)). It allows you to set a default
email ad
dress for the user, so they aren't confused when the system won't allow them
to send mail due to having no From address. The function should return a single
string, which is the intended email address. The default function uses the "domain"
option of the c
urrent server (from the local.servers.php config file) and combines it
with the username, to build the email address. You could, for example, use this
function to lookup the email address in a database, or perhaps an LDAP directory.


Futher hook functions

will be added as and when is necessary or appropriate,
suggestions for these are more than welcome.

Security


These security notes should be taken into consideration when installing and
configuring V
-
webmail. It is by no means a comprehensive guide to sy
stem
administration.

Directory Structure


The application was designed with virtual hosting firmly in mind. What this
translates to is that the directory structure is thus:


/v
-
webmail


|


+
-
/config


+
-
/help


+
-
/htdocs <
---

Point your DocumentR
oot here


+
-
/includes


+
-
/lang


+
-
/logs


+
-
/manual


+
-
/templates


+
-
/tmp


+
-
/userdata




As pointed out, the DocumentRoot (the root folder of your website) should be pointed
at the htdocs directory. This is so that the rest of

the directory structure is hidden
when accessing the website.


If you do not do this, or you don't have access to set up virtualhosts, then you can still
use V
-
webmail, but the directories will be traversable. This means people could in
theory gain acces
s to the userdata folder, or the tmp folder (file uploads reside here).


All is not lost however, since V
-
webmail can quite happily accommodate directory
name changes. So if you're forced to use this less secure method, then simply rename
the userdata/tmp
/logs /includes folders and update the config.php file (located in the
htdocs directory) to reflect the changes.


If you have to use the more open method of installation, you can rename the htdocs
directory, to something more friendly, eg webmail. No conf
ig.php changes are
necessary if you do this.

Permissions


The userdata and tmp directories have to be webserver writeable, so obviously all the
inherent issues with webserver writeable directories are present here. An example
command to set the necessary
permissions for these directories is:


chmod
-
R 777 userdata tmp




If you wanted to limit write access to the webserver only you could alternatively do
this (assuming the webserver runs as the user www and the group www):


chown
-
R www:www userdata tmp logs

chmod
-
R 700 userdata tmp logs



Register Globals


"register_globals" is a php option which makes all input variables available in the
"global scope". This is bad due to potential security risks, and hence

the reason why it
is off by default in recent versions of PHP (4.1.0+). Whilst there should be no risk in
this software (all variables set in this manner are unset), you are strongly
recommended to turn it off.

Session Files


It is important to make sure

your session data cannot be read by anyone except the
webserver. This is because sensitive information is stored in the session. If people can
read your session files, then they can read this data. On unix or linux with Apache, if it
runs as the user/grou
p www/www you could run the following commands:


mkdir
-
p /tmp/session
-
data

chown
-
R www:www /tmp/session
-
data

chmod
-
R 700 /tmp/session
-
data




You would of course have to set this ( /tmp/session
-
data ) to be the directory used
for

session data in your php.ini.

FAQs

Installation

Q:
I've installed V
-
webmail, however I get a blank screen when I try to login.

A:
One possible cause is that you have turned off the "config_checks" directive and
you don't have the PHP IMAP extension. Turn

"config_checks" back on to make sure.

Q:
I've set "servers_strict" to On however there's no dropdown box on the login form.

A:
If there is only one server specified, no dropdown box will be shown.

Administration

Q:
How do I change the default user prefer
ences?

A:
Edit the file config/default.user.php. This is a php script so you should avoid using
single quotes (') in strings and always take a backup.

Q:
How do I append some text to all outgoing messages?

A:
This can be achieved on a per virtual host bas
is. There is now a "outgoing_append"
option that can be used in your local.vhosts.php file which takes the name of a text file
in the config directory as it's argument. This text files' contents are appended to the
body of the email. An example text file i
s available in the config directory called v
-
webmail.txt, and should look at the vhosts.php config file to see the option in effect.

Q:
The folders page is very slow, is there a way to speed it up?

A:
Calculating the number of unseen/seen messages and in
particular the size of
mailboxes is an expensive operation for the IMAP/web server to perform. To alleviate
this problem there is an option in Preferences/Folder Prefs to enable or disable the
calculation of these stats.