Hotway Daemon, the POP3 gateway to Hotmail, MSN & lycos.co.uk!
--------------------------------------------------------------
This document last modified 12-December-2004

NOTE: For the most up-to-date information please check the web site which
      can be found at: 
      * http://hotwayd.sourceforge.net/ 
      The most up-to-date installation instructions are availble at:
      * http://hotwayd.sourceforge.net/e107_plugins/custompages/Install.php
      The man page "man hotwayd" after "make install" details the various
      flags which can be specified to alter the behaviour of hotwayd.

Latest news: 
------------
    * Fixed problem with 64-bit architectures. Should now work on all
    *nix 64-bit machines.

    * hotsmtpd now works with lycos/spray.

    * Improved configure scripts to correctly detect the required
    libraries.

    * Improved RPM packages, some of the xinetd config scripts were
    not being installed properly.

    * New flag -r added which marks messages as read on the HTTPMail server
    after downloading (old behaviour was never to mark message as read)

    * New flag -a added which allows the set of users which can login to a 
    HTTPMail server via hotwayd to be restricted. Check the man page for
    further information.

    * Incompatability with libxml2 >= 2.6.1 fixed

    * Now possible to get any folder you choose. Check the hotwayd man
    file "man hotwayd" or "man ./hotwayd.1" or the web page for 
    more details.
   
    * It is also now possbile to use lycos.co.uk, lycos.ch, lycos.de,
    lycos.es, lycos.it, lycos.at, lycos.nl, and spray.se mail accounts
    via HTTPMail using hotwayd! :-)  Just put in your full email address
    and hey presto!

    * Proxy support now works. Use -p proxy:port on the command line
    or via server_args in your hotwayd setup file for xinetd.

    * Choose your logging level (0-2) where 0 is nothing and 2 is 
    everything via the command line option -l


--------------------------------
Installation Instructions Follow
--------------------------------
A much nicer (and up-to-date) version of this guide is available online:
* http://hotwayd.sourceforge.net/e107_plugins/custompages/Install.php

Please note: these instructions are provided as a generic guide. As
with all generic guides, some sections will differ depending on which
variant of operating system you are using. This guide explains how to
set up hotwayd to listen for requests to a particular port on your
system. There may be security and other issues specific to your system
that need to be addressed and cannot be listed here. The way we get
hotwayd to listen on a particular port is by using the xinetd (or
inetd) daemons.

Almost all distributions come with xinetd now. If you are using inetd
then look at the inetd installation guide available online:

* http://hotwayd.sourceforge.net/e107_plugins/custompages/Install_inetd.php

-----------------
Compiling hotwayd
-----------------
You'll need libxml2 and libxml2-devel with iconv support in order to
compile this program. We use this library to parse the HTTPMail
requests. You may also need to install libiconv and zlib along with
cyrus-sasl (version 2.x.x, not version 1.x.x) for hotsmtpd (to send
mail via HTTPMail servers).

If you are using the source distribution, uncompress tarball and
compile with:

$ tar xvzf hotwayd-x.tar.gz 
$ cd hotwayd-x 
$ ./configure 
$ make 
$ su 
$ make install

Now you should be able to load up hotwayd by typing:
/usr/local/sbin/hotwayd

If you are using the RPM distribution, install with:

$ rpm -Uvh hotwayd-x.i386.rpm

This should install into /usr/sbin/hotwayd. Note that if you have used
previous versions of hotwayd, they may have installed to
/usr/local/sbin/ and you should delete those older binaries.  

If you are using the SRPM package:

If you are unsure how to build binary RPMs from the source RPM then
check the FAQ:
* http://hotwayd.sourceforge.net/e107_plugins/faq/faq.php


------------------------------
Setting up hotwayd as a server
------------------------------
If you use the RPM package you may not even have to do any more. Try
running "telnet 127.0.0.1 110". If you see the hotwayd greeting then
you just need to setup your mail client as described below, otherwise
continue with all of the following steps:

Now you need to set hotwayd up as a service on your computer. Run:
"ps -e | grep inetd" to see if xinetd is running. If you see only "inetd"
then refer to the inetd installation guide instead:
* http://hotwayd.sourceforge.net/e107_plugins/custompages/Install_inetd.php

If neither xinetd or inetd are running then you need to see if you
have one of them installed. Look in the /etc/rc.d/init.d/ directory
(depends on your distro) and see if there is a file xinetd or inetd. If
xinetd is not there then you must install it first:
* http://xinetd.org/    (or RPM via rpmfind.net)

You need to follow the same steps to install hotsmtpd. Details are
given in README.hotsmtpd included in the source packages.

------------------------------------------------
Adding hotwayd to the xinetd configuration files
------------------------------------------------
   1. Next step is to add the following to your xinetd configuration:

      Copy the following to a file called "hotwayd" in /etc/xinetd.d/ 
      or add it to /etc/xinetd.conf (may change depending on your
      distro) [remove spaces at front!]:

        service hotwayd
        {
        #only_from=192.168.0.0/24 #for gentoo security?
        disable = no
        type = unlisted
        socket_type = stream
        protocol = tcp
        wait = no
        user = nobody
        groups = yes
        server = /usr/sbin/hotwayd #must be full path!
        #server_args = -p http://proxy:8080 -u proxy_user -q
        proxy_password
        port = 110
        }

      Note 1: If you prefer to have hotwayd listen on a different port
      then replace the 110 with whichever port you would like to use.
      Note 2: The directory where hotwayd was installed may be
      different (e.g. /usr/local/sbin/hotwayd) in which case you will
      need to specify the correct directory for the "server" option.
      Note 3: For those who security is of a major concern, it may be
      better to create a specific hotwayd account and use "user =
      hotwayd".
      Refer to your xinetd instructions for further information.
      Note 4: If you have a proxy server that you must use to access
      the internet then you must enter it in the server_args field and
      remove the # symbol at the front. The username and password
      fields are optional. If you don't use a proxy server then simply
      leave the # in front of server_args and
      hotwayd will connect directly to the internet. If you enter a
      username and password you may want to remove world readable
      flags.
      Note 5: You can also set the logging level via -l in
      server_args.
      Note 6: only_from is used to restrict the IP address available
      to connect to the service. See man xinetd.conf

   2. Now you need to tell xinetd to reload the configuration file

      If you have the killall program, issue the following command:

      $ killall -HUP xinetd

      Otherwise you need to get the PID number of the running xinetd
      process.
      This can be done on linux by issuing the following command:

      $ ps -eo "%p %c" | grep xinetd

      If it doesn't report any process xinetd then you need to start
      up xinetd. Optimally it should be started during bootup in your
      rc.d scripts. Refer to your operating system notes for further
      details.

      Now that you have the PID number, you need to load in the new
      configuration file. This is done by issuing the following
      command:

      $ kill -HUP pidnumber

   3. Check your security settings

      First try to telnet to port 110 of your machine with "telnet
      127.0.0.1 110". If you see the hotwayd greeting then you can
      skip to setting up your mail reader. Otherwise try the steps
      following and check the Installation FAQs at:
      * http://hotwayd.sourceforge.net/e107_plugins/faq/faq.php?cat.6

      You can also check if anything is listening on the port using
      the command netstat. An example is:

      $ netstat -lp            [or "netstat -a" on cygwin]

      You should see in the column "Local Address" either *:pop3 or
      *:port_number if you used a different port to 110 (standard for
      pop3). The program name should show "xxxx/xinetd". If you don't
      see this when you run netstat then there is a problem with your
      xinetd setup.

   4. Setup your favourite mail client to use your newly installed
   server.

      You should give the POP-3 server address as either "127.0.0.1",
      "localhost.localdomain" or the name of your machine. The port
      number depends on what you entered in the xinetd setup (110 as
      default) Use your full username (e.g. hotmailuser@hotmail.com or
      msnuser@msn.com) and password that you normally use when
      accessing hotmail/msn/lycos/spray.

      If you use hotsmtpd then you need to setup the SMTP mail
      preferences with the username like specificed above and use port
      2500 (unless you picked a different one in the xinetd
      configuration above).

   5. Done! Now enjoy your newly installed POP3-HTTPMail gateway

--------------------------------------------
COMMENTS/QUESTIONS/SUGGESTIONS/IMPROVEMENTS?
--------------------------------------------
Many people have contributed to the code of hotwayd/hotsmtpd/hotimapd
over time. David Smith is taking care of maintaining and most of the
development for this proejct. You can contact me at:

   courierdavid@users.sourceforge.net

Please don't email me with support request, we have a forum for that
where you will get a faster response:

   http://sourceforge.net/forum/?group_id=25479 or
   http://www.sourceforge.net/projects/hotwayd

If you fix any bugs yourself or add extra functionality please post it
to the patches tracker on sourceforge:
* http://sourceforge.net/tracker/?group_id=25479&atid=384446
and it will be added to the next release.

Of course you are more than welcome to submit to me any patches to the
source that you have made or ideas that you may have to improve the
hotwayd suit of packages that we can incorporate into future releases.

Open source software starts with you :-)