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.

