Hotway Daemon, the POP3 gateway to Hotmail, MSN & lycos.co.uk!
--------------------------------------------------------------
This document last modified 01-November-2003

NOTE: for the most up-to-date information please check the web site which
      can be found at http://hotwayd.sourceforge.net/ and for installation
      instructions check http://hotwayd.sourceforge.net/install/ also check
      the man page "man hotwayd" after "make install" for details of various
      flags which can be specified to alter the behaviour of hotwayd.

Latest news: 
------------
    * 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:
---------------------------------
Please note: these instructions are provided as a generic guide to
help people who may not have experience with inetd or xinetd with
their first installation of hotwayd. 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. This may be security and
other issues specific to your system that need to be addressed and
cannot be listed here. For more information read the documentation for
inetd or xinetd (depending on which you are using) and your mail
reader.  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.  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 source RPMs then refer to "man rpmbuild" or the 
RPM HOWTO for futher instructions. There are also some instructions
on the hotwayd web site: http://hotwayd.sourceforge.net/rpmbuild/

Now you need to set hotwayd up as a service on your computer. Run 
"ps -e | grep inetd" to see if you are using inetd or xinetd. You should
only make changes to the configuration files of the daemon which is
running. If nothing shows up then I recommend you install xinetd (available
from http://xinetd.org/) and setup your startup scripts so that it loads
automatically upon sytem startup. 

Now follow either one of the following instructions depending on if
you are using xinetd or inetd:

Adding hotwayd to the xinetd configuration files
------------------------------------------------

   1. Next step is to add the following to your xinetd configuration.

      Either copy the following to /etc/xinetd.conf or to a file
      called hotwayd in your /etc/xinetd.d directory (this depends on
      the way your distributino handles the xinetd setup files)

      service hotwayd
      {
      disable = no
      type = unlisted
      socket_type = stream
      protocol = tcp
      wait = no
      user = nobody
      groups = yes
      #server = /usr/local/sbin/hotwayd (use this for source install)
      server = /usr/sbin/hotwayd
      #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.

   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

      You need to ensure that connections to the pop3 server are not
      blocked. To do this add the following line to your
      /etc/hosts.allow file

      hotwayd : 127.0.0.1

      (or if you are setting up hotwayd to run on another computer
      than your mail client, replace 127.0.0.1 with the address of the
      computer which you will use your mail client from). 127.0.0.1
      always refers to your computer.

      You should now be able to telnet into your hotwayd service. Type
      the command

      telnet addr port_number

      e.g. telnet 127.0.0.1 110 if you setup hotwayd on your own
      machine using port 110. If you can't connect then go back and
      review your steps. You can also check if anything is listening
      on the port using the command netstat. An example is:

      $ netstat -lp

      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 /etc/services
      file. Use the username (with @hotmail.com, @lycos.co.uk or 
      @msn.com for the latest version of hotwayd) and password that 
      you normally use when accessing your email via the respective
      web interface.

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



Adding hotwayd to the inetd configuration files
-----------------------------------------------

   1. Next step is to add the following line to the file called
   /etc/inetd.conf

      pop3 stream tcp nowait root /usr/sbin/tcpd hotwayd

      or if you prefer to have hotwayd listen on a different port then
      add the following line to /etc/inetd.conf

      hotwayd stream tcp nowait root /usr/sbin/tcpd hotwayd

      This tells inetd what to load when it receives a connection to
      either the port "pop3" or "hotwayd". The paths to the files may
      differ on your system so modify them accordingly. Now we need to
      define what ports "pop3" or "hotwayd" are mapped to as described
      in step 4. If you use a proxy server you will need to add extra
      arguments. Run hotwayd -h to find out more about these arguments.

   2. Make sure you have the following line in /etc/services, if it's
   missing you need to add it.

      pop3 110/tcp

      or the following line, if you prefer make hotwayd listen to
      another port than standard POP3 (i.e. you chose to add the
      "hotwayd stream tcp..." line to your /etc/inetd.conf):

      hotwayd nnnn/tcp

      (where nnnn is the port-number, say 110 for example)

   3. Now you need to tell inetd to reload the configuration file

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

      $ killall -HUP inetd

      Otherwise you need to get the pid number by typing the following
      command (on linux):

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

      If it doesn't report any process inetd then you need to start up
      inetd. 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, issue the command:

      $ kill -HUP pidnumber

      This will load the new config file into inetd.

   4. Check your security settings

      You need to ensure that connections to the pop3 server are not
      blocked. To do this add the following line to your
      /etc/hosts.allow file

      hotwayd : 127.0.0.1

      (or if you are setting up hotwayd to run on another computer
      than your mail client, replace 127.0.0.1 with the address of the
      computer which you will use your mail client from). 127.0.0.1
      always refers to your computer.

      You should now be able to telnet into your hotwayd service. Type
      the command

      $ telnet address port_number

      e.g. telnet 127.0.0.1 110 if you setup hotwayd on your own
      machine using port 110. If you can't connect then go back and
      review the instruction steps. You can also check if anything is
      listening on the port using the command netstat. An example is:

      $ netstat -lp

      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/inetd". If you don't
      see this when you run netstat then there is a problem with your
      inetd setup.

   5. 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 /etc/services
      file. Use the username (with @hotmail.com, @lycos.co.uk or 
      @msn.com for the latest version of hotwayd) and password that 
      you normally use when accessing your email via the respective
      web interface.

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



COMMENTS/QUESTIONS/SUGGESTIONS/IMPROVEMENTS?
-----------------------------------------------
The original author is no longer working on this project and hotwayd
is now being maintained by a series of developers.  David Smith is
taking care of the general coordination of patches, writing the
documentation and packaging of hotwayd.  You can contact me at the
following address: 

   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

And if you feel like doing some hacking, perhaps implementing some of
the optional POP functionality that your favourity mail reader uses,
or any minor improvements you may have made to the code then feel free
to send in or post up your patch and we will incorporate it into the
next release. 

If you want to help with the addition of IMAP functionality then
please send us a message!

