DIFFERENCES FROM PREVIOUS VERSIONS TWIG 2 is a significant departure from it's predecessors in how it is built, this subsequently means that the configuration and requirements have changed a bit as well. Unlike previous versions of TWIG, version 2 no longer has a truly database free installation, instead it has a file based db for small installation that do not have a proper SQL server. TWIG 2 also has a whole host of new options for user authentication and session storage systems. For a more complete outline of some of TWIG's features take a look at the administration manual found in docs/AdminManual. For details on installing TWIG in a specific configuration you can go to the docs directory and find several Setup-....txt files that will help out. For details on upgrading from one revision of TWIG to another please see the UPGRADE file. REQUIREMENTS For TWIG to function you need the following: A web server (Apache is recommended) A supported database server (see below for details) PHP 3.0.12 or greater with support for IMAP and your database software TWIG requires a database system of some sort. This can be as simple as a flat file based dbase system, but for performance reasons a true SQL server is highly recommented. TWIG currently supports Interbase, MSSQL, MySQL, Oracle, PostgreSQL, and Sybase database servers. You can take a look at the Setup-Apache-PHP-IMAP-TWIG.txt file for details on how to setup a basic TWIG system (without SQL support). The file Setup-Apache-PHP-IMAP-MySQL.txt gives detailed instructions on how to setup TWIG with MySQL. CONFIGURATION There are ten files that you should examine (and possibly edit), they can be found in the config directory: config.inc.php3 - This is where you configure certain global settings. header.inc.php3 - Stuff in here goes at the top of every page. footer.inc.php3 - Stuff in here goes at the bottom of every page. announcements.inc.php3 - Announcements for the Main screen. dbconfig.inc.php3 - This is where you configure certain database settings. defaults.inc.php3 - this is the default settings to use for the site. images.inc.php3 - This is a list of 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 - The 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 - A site wide footer to include on all outgoing mail messages. Once all of the above is setup, you may need to create the database tables on your server if you are going to use a database backend. You can find the table definitions in the twig.table.[server type] in TWIG's setup/ directory. CONFIG.INC.PHP3 This file contains all of the primary configuration items for TWIG. Here is a list of what they are and what they do: Primary Configuration Settings: $config["fromdomain"] This is where mail will be sent from $config["basedir"] The path of the URL to your TWIG installation (usually /twig) $config["imgdir"] The path to graphics files (usually /twig/images) $config["index"] This is what you name the index file (usually index.php3) $config["auth"] Authorization Type (basic|forms) $config["auth_timeout"] Set the auth cookie timeout value (in sec., 1800 = 30min) $config["auth_provider"] Authorization Method (imap-new|imap|sqltable|mysql|pgsql|ldap|sqlimap|sqlopen|nntp) $config["security"] Type of security to use (basic/advanced) $config["groups"] Type of groups support to use (none|standard|personal) $config["session_handler"] Session handler (get|sqltable|get2) $config["session_expiry"] How long session records are retained (in seconds) $config["login_handler"] Login handler (cookie|sqltable(experimental)) $config["language"] language file to use (english is the default). $config["spellcheck"] Command, including full path and flags, to run a spellcheck (via pipe) Color Configuration: $config["cellcolor"] Background color of certain cells $config["cellcoloralt"] Alternate background color of mail list cells $config["celltext"] Text color inside those cells $config["cellheadcolor"] Background color of header cells $config["cellheadtext"] Text color inside those cells $config["cellfont"] Font of text inside those cells $config["tabcolorlight"] The light (main body) color of tabs $config["tabcolordark"] The light (highlight) color of tabs Date Display Configuration: $config["timeformat"] Format to display time in $config["longdateformat"] Format to display long dates in $config["shortdateformat"] Format to display dates in IMAP Server Configuration: $config["imap_server"] IMAP Server Host (defaults to localhost) $config["imap_port"] IMAP Server Port (defaults to 143) $config["imap_path"] IMAP Mail Path (defaults to home dir) SMTP Server Configuration: $config["smtp_relay"] Do we use a SMTP relay server? $config["smtp_server"] SMTP Relay server to send mail through $config["smtp_port"] SMTP Relay server port to send mail through NEWS Configuration: $config["news_server"] News Server Host (defaults to localhost) $config["news_port"] News Server Port (defaults to 119) VHosts Configuration: $vhosts[<server_name>] Setup support for virtual hosts, see the VHOSTS section for details Disabled features Configuration: $disabled["compose"] Turns of the mail composing feature (see FAQ for complete list of features that can be disabled) DBCONFIG.INC.PHP3 This file contains all of the database configuration items for TWIG. Here is a list of what they are and what they do: SQL Server Configuration: $dbconfig["sqlserver"] SQL server hostname $dbconfig["sqlport"] SQL server port $dbconfig["sqlusername"] username $dbconfig["sqlpassword"] password $dbconfig["defaultdb"] database $dbconfig["sqltype"] mysql, pgsql, pgsql-new, dbasesql, mssql or oracle. Database Table Name Configuration: $dbconfig["groups_table"] SQL table name for group info $dbconfig["members_table"] SQL table name for group member info $dbconfig["prefs_table"] SQL table name for mail preferences $dbconfig["schedule_table"] SQL table name for schedule info $dbconfig["todo_table"] SQL table name for todo list $dbconfig["bookmarks_table"] SQL table name for bookmarks $dbconfig["contact_table"] SQL table name for contact list $dbconfig["folders_table"] SQL table name for news group list $dbconfig["news_prefs_table"] SQL table name for news preferences $dbconfig["accounts_table"] SQL table name for user accounts $dbconfig["acl_table"] SQL table name for ACL lists $dbconfig["aclgroups_table"] SQL table name for ACL Groups lists $dbconfig["main_prefs_table"] SQL table name for main prefs $dbconfig["global_prefs_table"] SQL table name for main prefs $dbconfig["todo_prefs_table"] SQL table name for contact prefs $dbconfig["contacts_prefs_table"] SQL table name for contact prefs $dbconfig["schedule_prefs_table"] SQL table name for contact prefs $dbconfig["bookmarks_prefs_table"] SQL table name for bookmarks prefs $dbconfig["context_table"] SQL table name for context info $dbconfig["session_table"] SQL table name for session info $dbconfig["sqlloginhandler_table"] SQL table name for sqltable login handler storage DEFAULTS.INC.PHP3 This file contains settings to use as defaults for the site, these include things like the default number of items to display on a page. HEADER.INC.PHP3 This file controls what is displayed at the top of the TWIG pages. You can customize this file for your site. FOOTER.INC.PHP3 This file controls what is displayed at the bottom of the TWIG pages. You can customize this file for your site. ANNOUNCEMENTS.INC.PHP3 This file controls what is displayed in the message of the day section of the main twig page. You can customize this file for your site. If this file does not exist, then nothing is displayed. IMAGES.INC.PHP3 This file contains references to each image that TWIG uses. LOGIN.FOOTER.INC.PHP3 This file contains the closing information required for forms based login. LOGIN.FORM.INC.PHP3 This file contains the information that is displayed during forms based login. LOGING.HEADER.INC.PHP3 This file contains the opening information required for forms based login. MAINMENU.INC.PHP3 This file contains a list of all the 'features' that will be contained on the main menu bar for TWIG. NEWUSERGROUPS.INC.PHP3 If using advanced security this is the default list of groups to add a new user to. If you are using basic security you can completely ignore this file. MAILFOOTER.INC.PHP3 A site wide footer to include on all outgoing mail messages. $config["auth_provider"] Authorization Method to use during login: imap This provider mirrors TWIG 1's login process, an IMAP server is connected to and a mailbox is opened each time a page is loaded. imap-new This provider differs from the original TWIG system by not opening the mailbox on the initial page load, but waits until the mailbox is required to open in. sqltable This provider uses a sqltable (twig_accounts) to store users and passwords in, users must first be created in this table before they will be allowed to log in. This provider does not require an IMAP server to function. mysql This provider connects to a MySQL server as then given username and password, if successful it allows the user on, otherwise they are rejected. pgsql This provider connects to a pgsql server as then given username and password, if successful it allows the user on, otherwise they are rejected. sqlimap This is a combination of imap-new and sqltable, it first checks the sqltable for the user, if found it allows the user to log on. If not found then the imap server is contacted and checked. If the user is validated by the imap server then they are added to the sqltable so that next time the IMAP server will not be connected to untill need to by the mail module. sqlopen This provider is based on sqltable but if the user is not found in the table, then the user is added to the table automaticly, effectively giving open access to the server. ldap This provider connects to an ldap server as the given username and password, if successful it allows the user on, otherwise they are rejected. nntp This provider connects to a news server as the given username and password, if successful it allows the user on, otherwise they are rejected. $config["security"] Type of security to use. Security is only implemented in the admin module at this time. basic This basically gives access to everything. advanced This is a full blown ACL based security system that in future versions of TWIG will be used to control much of the functionality of TWIG on an administrative level. Unlike basic, this defaults to denying access to a feature. $config["groups"] Type of group support to use, TWIG Supports three different types of groups: none No groups will be supported and the user will not be able to 'file' their items in anything but a single group that only they can see. personal This groups system allows for items to be filed into groups for purposes of organization, but does not allow for sharing of information. standard This is the traditional TWIG group support. Like 'personal', it allows for items to be filed into groups for purposes of organization. However, standard groups can also be shared with other users allowing them to view an modify that information. userperms Like 'standard', this group type allows items to be placed into groups for purposes of organization and allows those groups to be shared among multiple users. However, the userperms groups system allows different users to be given different levels of access to the information filed under those groups. $config["language"] The default language to use, TWIG supports the following languages at this time (though some items may not yet be translated): catalan chinesebig5 chinesegb czech danish dutch english estonian finnish french german hebrew italian jpeuc korean polish portuguese russian russianwin spanish swedish test (only used for testing) $config["session_handler"] Session handler, this determines how session data is stored between page loads. get This is the traditional TWIG storage system of this information, in forms hidden fields are used, in links additional variables are added. sqltable This is a method that uses sqltables to store the session information and only uses a reference pointer on the url or in the forms. get2 This is an upcoming replacement to get but is still considered experimental at this time. $config["login_handler"] Login handler, this determines how login data is stored between page loads. cookie This is the traditional TWIG storage system of this information, username and passwords are stored as a cookie. sqltable This is a method that uses sqltables to store the login information and only uses a reference pointer in a cookie. DATE DISPLAY The date display configuration strings are used by TWIG to call the php date() function, as such these string should follow the guidelines that can be found here: http://www.php3.org/manual/function.date.php3. MAIL RELAYING TWIG 2 uses the mail relaying functions by default. This is primarily due to the limitations of the built in PHP functions for mail sending that are dependent on the OS that is being used for what functionality is available. To use mail relaying you must have a server that will accept mail for relaying. This is often considered a large security hole if this server is also publicly available on the net. Make sure you understand the security implications before you enable mail relaying. VHOSTS TWIG can support vhosts configuration, if you don't know what a vhost is, you can skip this section. TWIG's vhost support allows you to use a central config.inc file and then override various values on a host by host basis. To configure vhost support, go in to the main config.inc.php3 and add a line like the following: $vhosts["quick.net"] = "config/qnet"; This will tell TWIG to load a config file called "config/qnet/config.inc.php3" after config/config.inc.php3 has been read. This will allow you to change any of the config.inc settings (fromdomain, etc.) to tailor TWIG to the vhost. SECURITY There are several issues with security, and this is only a brief overview of the issues. Before implementing a TWIG server (or any Internet based server) you should have a good working knowledge of Internet related security. To keep your configuration settings secure you need to make sure that your web server pay's attention to .htaccess files. To check to make sure your configuration is secured, try accessing your config.inc.php3 file using the following URL: http://<your server name>/<twig home directory>/config/config.inc.php3 You should get an access denied message after a security dialog box pop's up. If you don't, please refer to your web server's documentation to enable .htaccess files. Another concern is connectivity between TWIG and the mail/database server. The most secure system is to have everything on the same server, otherwise passwords may be transmitted across the net. This is nothing specific to TWIG, but instead is depended on the other servers. The most obvious security concern in the transmitting of username/passwords using basic or forms based authentication. One possible solution to this is to use an SSL capably browsers/server. If you are allowing shell access for users to the servers that you have TWIG installed on you need to make sure that the various files are secured from being access by anyone but the admins (and the web server of course). These include things like the TWIG config files, the .htaccess files, the web server log files, the sql databases, the web server config files, etc. If a user could read or alter these files they could retrieve information or impersonate a user that could breach the security of the data. By default, may files are installed on servers as world readable and need to have their security reset to be secure. If possible, do not allow shell access to these servers so that these kinds of attacks can be limited.