WING - Web IMAP/NNTP Gateway, version 0.6 Copyright (C) 1998, 1999 by Malcolm Beattie This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License or the Artistic License for more details. You should have received a copy of the GNU General Public License in the file named "Copying". If not, you can get one by writing to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. DESCRIPTION WING provides a gateway so that users can access email held on an IMAP server via any web browser. Some features of WING are: * The browser does not need to support Java, JavaScript or frames but table and cookie support are preferable. * Users can create a hierarchy of multiple mailboxes and browse and move messages between them. * Messages with MIME attachments can be displayed nicely. * Per user defaults (such as screen size and mail signature) can be set and saved between sessions. * Files local to the client browser can be included in composed messages or MIME attached to them. * Arbitrary headers can be added to composed messages except that the "From:" header cannot be changed or forged for outgoing messages from WING. * WING is scalable up to thousands and tens of thousands of users. When integrated with a mail cluster similar to the one we have here at Oxford University, WING also has these features: * Users can manage their account via the WING interface. This includes changing passwords, querying disk usage of mailboxes and disk quota an setting mail forwarding and "vacation" messages. * Users can create address books which can be browsed, searched and shared in an ACL controlled manner with chosen lists of other users and groups. * WING server nodes can be added or removed transparently and can be taken down for upgrades without affecting user service. * There are a few web-based admin tools for querying the status of the WING cluster and its users. REQUIREMENTS In its current state, WING requires many other pieces of software to function. Future versions may be easier to install, configure and maintain but this one requires the attention of an experienced system administrator familiar with Apache/mod_perl, Perl and SQL databases. It was also developed primarily for Linux. Although almost all of it is portable, if you're running it on something other than Linux you'll at least need to edit Wing/Login.pm and write a new version of make_session_id() that gets cryptographically strongly random numbers by some other means than simply reading /dev/urandom. For configuring a mail cluster and its associated features, the administrator will also need to know about network configuration, firewalling, NFS, automount, named and exim. You have been warned. AVAILABILITY Wing is available from your favourite CPAN site as a tar ball or from its home site in tar.gz form ftp://ftp.ox.ac.uk/pub/perl/Wing-0.6.tar.gz or source RPM form ftp://ftp.ox.ac.uk/pub/linux/SRPMS/wing-0.6-1.src.rpm or "binary" (noarch) RPM form for Red Hat 5.x Linux ftp://ftp.ox.ac.uk/pub/linux/RPMS/noarch/wing-0.6-1.noarch.rpm INSTALLATION These instructions are probably woefully incomplete and inaccurate. I'll assume there are three logically separate hosts: a frontend, an IMAP server and a WING server. If necessary, those can all be the same physical host (or there can be multiple hosts in each class). If they are all the same host then WING will, in the current configuration, still access user mailboxes by using loopback IMAP connection to itself. It is possible to make WING access mail files directly in this case but it needs changes to WING which I won't go into here. Now start installing things: On the frontend and the WING server install Apache, mod_perl, Perl 5.004_04 (or later) and the following Perl modules: DBD-Pg DBI Data-Dumper Net-Telnet Apache-DBI MD5 MIME-Base64 Term-ReadKey HTML-Parser Term-ReadLine-Perl libnet IO-stringy CrackLib Mail-Cclient libwww MailTools MIME-tools Net-DNS SQL Most of these are standard CPAN modules, a couple are modules I've written but not officially released yet (CrakLib and SQL). All are available in RPM form at ftp://ftp.ox.ac.uk/pub/linux/SRPMS/ for the source RPMs and ftp://ftp.ox.ac.uk/pub/linux/RPMS/i386 for binary RPMs built on Red Hat 5.x for x86. Those who can't cope directly with RPMs will, for the moment, have to get rpm2cpio and build them themselves. I will get around to releasing these modules to CPAN sometime. SQL has bugs involving string/number quoting but should work OK the way WING uses it. On the frontend, install PostgreSQL. You may be able to use another SQL database, but (1) it must support transactions (this rules out MySQL) (2) it must support using ident lookups for authentication (or else you will have to alter the security model and associated code.) Create a database for wing. I'll assume that Apache runs under the username "httpd". Create database users "httpd" and "root". Note that PostgreSQL user root really is root (uid 0) and *not* the PostgreSQL "superuser" username (often "postgres"). Initialise the necessary database tables with the SQL from wing-init.sql (run as username httpd) abook-init.sql (run as username httpd) users-init.sql (run as username root) Each user who wants to use wing should have a row in the users table which includes their username, uid, gid and sender. The "sender" field is what WING will put in the "From: " header of outgoing messages that the user sends with WING. If using PostgreSQL, after adding a number of users to the users table don't forget to "vacuum analyze users" so that it realises it should make use of index lookups. Also, give each user a personal address book insert into abook_ids (username, tag) values ('fred', 'personal'); Start up the maild daemon under the httpd username. An appropriate init.d boot time script is wing.init which can be copied to /etc/rc.d/init.d/maild (or wherever you keep boot time scripts). If you don't have a SysV flavoured boot configuration, tweak it yourself. Install Wing. If you use the RPM, fine. If you're not you'll have to: * copy Wing.pm Wing/*.pm to your Perl site_perl directory * copy wing-icons/* to the wing-icons subdirectory of your Apache root directory * copy help/* to the wing-help subdirectory of your Apache root * install maild in /usr/sbin (or wherever your boot time script wants to find it) * create directories /var/lib/maild and /var/lib/maild/sessions, owned by httpd and mode 700. Now the difficult part: edit .../site_perl/Wing/Shared.pm and go through changing things to refer to your own hostnames, domains and environment. Some things will need changing, most won't. The various variables are reasonably well commented. Edit your Apache httpd.conf and check you're running under user httpd and group httpd. On the WING server only edit access.conf and add PerlModule Wing SetHandler perl-script PerlHandler Wing SetHandler perl-script PerlHandler Wing::Login Alias /wing-icons/ /home/httpd/wing-icons/ On the frontend, edit access.conf and add PerlModule Wing::Balance # # Using below means the root directory of this web # server (or, typically, virtual host) brings up a login screen # for wing. This means users can just type a simple hostname into # their browser for wing access. If you don't want this and can't # spare a virtual host, change it to something like # so that they have to type # http://foo.bar.baz/wing-login into their browsers to get at WING. # SetHandler perl-script PerlHandler Wing::Balance # # *** Add auth restrictions here to limit the people who can # *** use the admin interface to query wing. # SetHandler perl-script PerlHandler Wing::Admin Now create a file called /etc/wing.live on the frontend and put in it, one per line, the hostnames of each WING server. You can comment out lines by putting "#" at the beginning of the line. Restart Apache on the frontend and WING server(s). Right, that might just about be it. Try using a browser to connect to http://yourfrontend.example.org/ (or .../wing-login if you chose that Location above) and see what happens. If something goes wrong, investigate and try to fix it. Don't mail me directly. Some of the features (those above that I mentioned required the extra cluster configuration) may not work. I don't yet have instructions yet for how to set all that up but you can always look at the source and figure it out for yourself if you're adventurous. SUPPORT There isn't any official support. Don't mail me directly. However, I have set up a mailing list called "wing-admin" where I anticipate those who want to set up WING can discuss things. I will monitor that mailing list and help where I can but I'm not going to answer every single little question, I'm not going to respond quickly (necessarily) and I'm going to assume a good deal of sysadmin knowledge on the part of participants. The list is a majordomo list. To subscribe, send the following message *body* (the subject line is irrelevant and ignored) subscribe wing-admin to majordomo@maillist.ox.ac.uk. To unsubscribe again send the message body "unsubscribe wing-admin" to the same address. To send messages to the list, mail to wing-admin@maillist.ox.ac.uk. Good luck. You'll need it. It is rather good when it all works though. BUGS Address books haven't been thoroughly tested yet. A few (untested) minor changes have been made to turn some site-specific parts of Wing into generic configurable items. There may be bugs floating somewhere. AUTHOR Malcolm Beattie mbeattie@sable.ox.ac.uk Version 0.6, first public release 5 February 1999