Table of Contents:
TWIG (The Web Information Gateway) is a groupware enabling package with integrated e-mail client, Contact Manager, Scheduling, Usenet News Client, To Do Lists, and Bookmarks.
From the Documentation: ./twig/docs
WARNING*WARNING*WARNING*WARNING*WARNING*WARNING*WARNING*WARNING*
Building a server with a database on it that is publicly accessible to the Internet can be a LARGE security hole. This document takes no consideration of this and assumes that you know what your doing about the security on the server and database.
WARNING*WARNING*WARNING*WARNING*WARNING*WARNING*WARNING*WARNING*
There are a number of Web hosted Mail programs available on the Internet. This guide in no way implies TWIG as better than the rest. If you are interested in other Web Hosted Mail services for your users, then take a look at some of those listed below:
Since the writing of this guide, OpenBSD has gradually included some webmail client pieces into the ports tree. Two in particular are Horde/IMP and OpenWebmail. Please review these if they meet your needs.
The following are programs necessary for the operation of TWIG. Each of the listed required component is linked to pages on this site with instructions on installation. Systems that can function with the below software will perform similarly with the additional load of TWIG.
PHP 4.0 or PHP
3.0.16
Apache
MySQL and PostgreSQL
UW Imap or Cyrus, Courier
IMAP
Source File: twig-2.3.2.tar.gz (available from http://twig.screwdriver.net)
[ref: twig-2.3.2/docs/Setup-Apache-PHP-IMAP-TWIG-MySQL.txt]
Note: I have recently downloaded 2.6.1 and it looks great, the same instructions below still work well with the update.
Extract the twig source files to a directory on your machine, create the directory of the final destination for TWIG and run the configuration script to copy the TWIG files to their final destination.
| # cd /usr/src # tar -zxf /[path-to-file]/twig-2.3.2.tar.gz # cd twig-2.3.2 # mkdir /var/www/twig # sh ./twig-install /var/www/twig |
[ ... Installation will display the following ... ]
TWIG Install Script =================== Installing feature modules... Installing images... Installing configuration files... Installing library modules... Installing root files... Done! |
We have used /var/www/twig as the destination directory, but of course you could have selected another directory location.
I like the documentation, so we'll copy that into our live tree as well.
| # cp -R docs /var/www/twig/ |
The necessary files for TWIG have been copied and we now just need to modify them.
Modify the Apache configuration file (normally in /var/www/conf/httpd.conf) to reference the TWIG location.
| Alias /twig/ "/var/www/twig/" <directory "/var/www/twig"> Options Indexes Multiviews AllowOverride All Order allow,deny Allow from all </directory> |
We also need to ensure that index.php3 is part of the Apache Directory Index directive.
| # Add to the Directory Index the index.php3 DirectoryIndex index.html index.htm index.php3 index.php index.phtml |
Restart Apache to re-read the configuration file.
# apachectl restart
Save the following mysql script to a file to help you configure the MySQL database. For security reasons, you should change the following settings used in the example.
Username : twig_user
Password : twig_password
Database : twig_db
# mysql_create.sql
# derived from the horde/scripts/database/mysql_create.sql
#
# You can simply direct this file to mysql as STDIN:
# > mysql (user/pass/host args) < mysql_create.sql
CONNECT mysql;
INSERT INTO user ( host, user, password )
VALUES (
'localhost',
'twig_user',
password('twig_password')
);
INSERT INTO db (
host, db, user,
Select_priv, Insert_priv, Update_priv, Delete_priv,
Create_priv, Drop_priv )
VALUES (
'localhost',
'twig_db',
'twig_user',
'Y', 'Y', 'Y', 'Y',
'Y', 'Y'
);
CREATE DATABASE twig_db;
FLUSH PRIVILEGES;
# done!
|
Configure MySQL with the database that we will use with TWIG. This may require starting MySQL if we have not yet started it.
| # /usr/local/bin/safe_mysqld
--user=mysql --log & # cd /var/www/twig # /usr/local/bin/mysql -u root -p < mysql_create.sql # /usr/local/bin/mysql -u root |
If you do not want to setup the above script, then you can manually configure your TWIG information with the following procedures. Warning, the instructions that ships with twig version 2.3.2 gives complete control of mysql to the twig_user (this is an insecure approach.)
1. Start MySQL daemon if it has not already started and login as root
| # /usr/local/bin/safe_mysqld
--user=mysql --log & # /usr/local/bin/mysql -u root -p |
2. Create the database for TWIG. If you have logged in correctly above you should now be at the mysql> prompt
| mysql> CREATE DATABASE twig_db; |
| Query OK, 1 row affected (0.03 sec) |
| mysql> quit |
3. Create the Tables by using the script supplied with the distribution source.
| # mysql -u root |
4. Create and specify (grant) the rights for the TWIG user account, and quit mysql.
| # mysql -u root -p mysql> USE mysql; mysql> INSERT INTO USER (host, user, password) values ('localhost', 'twig_user', password('twig_password') ); mysql> GRANT Select_priv, Insert_priv, Update_priv, Delete_priv, Create_priv, Drop_priv ON twig_db.* TO twig_user@localhost IDENTIFIED BY 'twig_password'; mysql> quit |
The major configuration files for TWIG are located in the ./config directory.
From the documentation: (./INSTALL)
| There are ten files that you should examine (and possibly edit) they can be found in the config directory: | |
| config.inc.php3 | Configure certain global settings. |
| header.inc.php3 | Goes at the top of every page. |
| footer.inc.php3 | Goes at the bottom of every page. |
| announcements.inc.php3 | Announcements for the Main screen. |
| dbconfig.inc.php3 | Certain database settings. |
| defaults.inc.php3 | Default settings to use for the site. |
| images.inc.php3 | Images to use in TWIG. |
| login.footer.inc.php3 | The footer of the forms based login. |
| login.form.inc.php3 | The body of the forms based login. |
| loging.header.inc.php3 | The header of the forms based login. |
| mainmenu.inc.php3 | Menu items to be displayed on the main menu. |
| newusergroups.inc.ph3 | If using advanced security this is the default list of groups to add a new user to. |
| mailfooter.inc.php3 | Footer to include on all outgoing mail messages. |
For our sample configuration (to get things up and running until we know how
it works) we can begin with modifying config.inc.php3, and dbconfig.inc.php3
File: config/config.inc.php3
|
$config["fromdomain"] = "foo.com"; // This
is where mail will be sent from $config["auth_logout_redirect"] = ""; // Complete
URL to redirect browsers to after they have been logged out $config["auth"] = "forms"; // Authorization Type (basic|forms) |
Change foo.com to your domain
Change /twig to whatever you specified for you Alias in the Apache httpd.conf
file
Change forms to basic if twig keeps dropping back to the login screen.
Change aspell to ispell which is available as a binary package.
File: config/dbconfig.inc.php3
|
$dbconfig["sqlusername"] = "twig_user";
// username |
Change twig_user to the User You specified above (note the default
is nobody)
Change twig_password to the password you specified above (note the default
is "" a blank password)
Change twig_db to the database you specified above (note the default
is twig)
You should now be able to test twig by pointing your browser to the site http://mywebsite.com/twig/test.php3
You should be presented with a screen to let you test 3 different component modules of TWIG (accessing the IMAP server, accessing an account on the IMAP server, accessing the MySQL database server, and the result of PHP Information <?php phpinfo() ?>.)
# lynx http://localhost/twig/test.php3
| [TWIG] ________________________________________________________________________________ General Back to top. Welcome to the TWIG test page! If you've executed a test that has failed and can no longer see the complete form click here to get back to a clean form. This page is divied in to several sections: * This section * An IMAP test * A SQL test * PHP Version Information |
Customising the look of your TWIG environment is readily completed through the various configuration files, especially the footer, header and announcements. TWIG does a great job of separating the 'business' logic of providing the groupware from the 'display' features, putting the web-page on the screen.
I list here a few things of interest to me in modifying the 'look-n-feel' of TWIG.
| mailfooter.inc.php3 | This is the text sent with each e-mail message (similar to hotmail, yahoo.) We prefer something about our organisation here. |
| login.footer.inc.php3, login.header.inc.php3, login.form.inc.php3 |
These files determine the look of the login page. I prefer to place our usage policy on the page to ensure people are aware of their responsibility when using our services. |
| announcements.inc.php3 | Announcements that are displayed after you have logged into the system. |
| header.inc.php3 | This contains the 1st part of the <body> section of the html page. |
| footer.inc.php3 |
Personalising, Corporatising the look of TWIG is an easy to implement feature, please remember to reference the project somewhere within this customisation.
If you get a lot of include error messages this problem manifested (was noticed) on a system where I had installed horde/PHPLib. Note: A fresh (machine) install without horde/PHPLib, did not show the same problems.
PHPLib requires changing the php3.ini file to specify an auto_prepend file. The changes made to the auto_prepend file (/var/www/conf/horde/phplib/prepend.inc) cause a pathing problem for twig.
Two solutions to the problem exist:
Solution 1: Disable the auto_prepend (in file /var/www/conf/php3.ini). Simply commenting out the line solves the problem on my system.
A more complete solution is to fix the reason why prepend.inc causes the problem.
Solution 2: References to directories config/ and lib/ and features/ are not resolving correctly on my setup. To cater for this problem I have to replace config/ with ./config/ and lib/ with ./lib/ and features/ with ./features/
A number of files are effected so I perfom a global search and replace. Unfortunately I don't have a Unix script for it as I'm hoping this is not a proper solution and it will be resolved with further review.
| Change this | To This |
| "config/ | "./config/ |
| "lib/ | "./lib/ |
| "features/ | "./features/ |
| "config" | "./config" |
Related References
Leafnode Netnews Server (distfiles leafnode-1.9.2.tar.gz)
Remember that what we've discussed above shows you configuring a Web hosted Groupware application. It does not in any way implement one that is 'secure.' To be minimally secure, you should review the security features of TWIG and tighten up the 'basic' configuration.
Features you should consider reviewing, include (in version 2.6.2) auth_provider, login_handler and other mechanisms for tightening up security on your database server. Obviously you should also be looking at implementing SSL on your website.
Once you have mod_ssl working correctly on your server, then we can require https to be used by using the SSLRequireSSL directive, as shown below:
|
Alias /twig/ "/var/www/twig/" |
|
SSLRequireSSL |
|
</directory> |
Copyright (c) 2000/1/2 Samiuela LV Taufa. All Rights Reserved.
I reserve the right to be totally incorrect even at the best advice of betters. In other words, I'm probably wrong in enough places for you to call me an idiot, but don't 'cause you'll hurt my sensibilities, just tell me where I went wrong and I'll try again.
You are permitted and encouraged to use this guide for fun or for profit as you see fit. If you republish this work in what-ever form, it would be nice (though not enforceable) to be credited.
|
TWIG - Group Ware through the Web |
Copyright © 2000/1/2 NoMoa Publishers All rights reserved. Caveat Emptor