HoTTProxy Technical Article

 Running HoTTProxy on Linux, etc.

Since HoTTProxy is written in pure Perl, it should be able to be run on any platform for which a Perl interpreter is available (which is pretty much all of them). To tell if your computer has Perl on it, open a command console (how to do this varies by platform), and enter the command:

perl -v

This is perl, v5.8.4 built for MSWin32-x86-multi-thread
(with 3 registered patches, see perl -V for more detail)

Copyright 1987-2004, Larry Wall

Binary build 810 provided by ActiveState Corp. http://www.ActiveState.com
ActiveState is a division of Sophos.
Built Jun  1 2004 11:52:21

Perl may be copied only under the terms of either the Artistic License or the
GNU General Public License, which may be found in the Perl 5 source kit.

Complete documentation for Perl, including FAQ lists, should be found on
this system using 'man perl' or 'perldoc perl'.  If you have access to the
Internet, point your browser at http://www.perl.com/, the Perl Home Page.

If you don't have Perl on your computer you'll just get an error. If this is the case, not to worry. ActiveState offers a Perl interpreter for AIX, HP-UX, Linux, Mac OS, Solaris, and Windows. ActiveState is the de facto standard Perl interpreter for Windows - the only major desktop operating system which doesn't come with Perl interpreter these days.

The instructions that follow were worked out on Red Hat's "Fedora Core 4" version of Linux, installed using the "Server" option, along with choosing to install the optional "development tools" (which included Perl, gcc, and probably other stuff that is important. That said, the procedure should be nearly identical for any operating system - the main difference being simply how one goes about opening a command console (a.k.a. BASH, command prompt, cmd.exe, terminal window, etc., depending upon OS).

 Requirements

As stated above, you need to be running an Operating System that has a Perl interpreter installed.

You are also going to need an unzip program appropriate to your OS. If you're running anything but Windows, chances are you already have gzip on your machine which will be fine. If you're running a Win32 OS, you've probably got WinZip, WinRAR, or another GUI file compression utility.

A brief aside for Win32 users: You might should get the Win32 ports of some of the more common GNU tools (like gzip) if you are going to be building and installing Perl modules from CPAN (which we will be doing in this procedure). You can get most of them here. Get at least gzip, tar, and wget. You should put these in your C:\WINNT or C:\Windows directory (whichever directory your machine has). You will also need Microsoft's NMAKE utility which is the Microsoft version of what everyone else calls MAKE and is used to "build" the modules you download. You can get NMAKE directly from Microsoft by going here, and find and download NMAKE15.EXE. This is a self extracting archive that contains NMAKE.EXE, NMAKE.ERR, and README.TXT. NMAKE.EXE and NMAKE.ERR should be put in your C:\WINNT or C:\Windows directory (whichever your machine has). You should get all these files downloaded and in place before you proceed.

In addition to running a proper operating system with Perl installed, a few more things are needed:

• An Internet connection - preferably broadband (not dialup)
• Port 9201 (or other chosen port) forwarding to the computer you run HoTTProxy on (if you are using a broadband router or other hardware firewall)
• Port 9201 (or other chosen port) allowed to pass through your software firewall if you are using one (if you have Windows XP - you've got one whether you know it or not)
• An Internet browser on the machine which will run HoTTProxy (to use the new Administration Console)
• (Optional) DynDNS name pointing to your computer to make accessing your proxy easy

 Steps

The high level steps to running the HoTTProxy as a Perl script are:

• Install Perl if you don't have it
• Install all of the required Perl modules
• Download and Install HoTTProxy
• Run the HoTTProxy_Admin daemon
• Edit the HoTTProxy configuration file
• Create user files
• Run HoTTProxy
• Testing your HoTTProxy install
• Other Stuff

 Install Perl if you don't have it

Sorry, but you're on your own for this step since it will vary so much from platform to platform. See the discussion earlier for how to tell if you already have Perl or not and where to get it if you don't.

 Install all of the required Perl modules

HoTTProxy requires a variety of modules to run. Your machine may already have some of these, but for the purposes of this documentation, I'm going to assume that you don't have any of them (except the ones I know are part of the standard distribution).

1. Open whatever your OS uses for a command window. In Linux this is probably called "Terminal Window" or BASH, in Windows this is called the "command prompt" or cmd.exe.
2. At the command prompt, type: perl -MCPAN -e shell and press [ENTER].
3. If this is the first time you've run the CPAN interface, you'll be asked a lot of questions. You can take the default for everything except when it asks what country, download server, etc. -- you should choose sensible values for those.
4. Once it is done asking questions and is waiting for a command, type: install YAML and press [ENTER].
5. Let fetch and install Test::More if it asks.
6. Type: install Module::Build and press [ENTER].
7. Type: install Bundle::LWP and press [ENTER].
8. Type: install HTTP::Daemon and press [ENTER].
9. Type: install HTTP::Proxy and press [ENTER].
10. Type: install HTTP::Server::Simple and press [ENTER].
11. Type: install Date::Calc and press [ENTER].
12. Type: install CGI and press [ENTER].
13. Type: exit and press [ENTER] to exit the CPAN installer.
14. Leave this window open, you will need it later.

 Download and Install HoTTProxy

When you download the HoTTProxy program, we're going to have you save the compressed archive in the location where you will run HoTTProxy from. This will simplify the instructions. We're also going to make some assumptions about where you'll be running HoTTProxy from. If you're running on Win32, we're going to assume "C:\HoTTProxy", and if you're running Linux, etc., we're going to assume "/home/HoTTProxy". You can of course run HoTTProxy from wherever you like, with one important warning. Do not put your HoTTProxy code in a directory that is served by a web server. HoTTProxy is not a CGI application and is not used with a web server - it is a free standing Daemon of its own.

1. Open an Internet browser.
2. Go to the HoTTProxy official website download page (http://www.HoTTProxy.org/downloads.html), download HoTTProxy-Source-0.24.0.0.tar.gz and save it to the directory you will run HoTTProxy from (see the discussion above if you've forgotten it already).
3. Close your Internet browser and return to your command prompt window.
4. For Win32, type: cd c:\HoTTProxy and press [ENTER].
5. For Linux, etc., type: cd /home/HoTTProxy and press [ENTER].
6. Type: gzip -dc HoTTProxy-Source-0.24.0.0.tar.gz | tar -xof- and press [ENTER].

 Run the HoTTProxy_Admin daemon

As of version 0.24.0.0 of HoTTProxy, user maintenance and basic configuration may be accomplished using the Administration console instead of manually editing the text files. You may of course still manually edit the text files if you wish.

The Administration Console is web based and has its own built in daemon. Before you may use it you must first first start the daemon (HoTTProxy_Admin).

To run HoTTProxy you'll need to go back to the command prompt that you've been using. You should already be "in" whatever directory you installed HoTTProxy in. There are actually a number of different ways to start HoTTProxy_Admin.pl running depending upon your OS and configuration, but this command should work for all:

perl HoTTProxy_Admin.pl

Unless you get an error, you should get a screen that tells you the daemon is running and what port URL to use to access it (e.g. http://localhost:8085). If you need to change this port for some reason you'll need to edit HoTTProxy_Admin.conf with a text editor and change the port. Assuming the port is OK, open your Internet browser and enter the URL. You should receive the Administration Console main menu. Things should be intuitive from there. At a minimum you'll need to create at least one user account.

Legacy instructions for manually configuring user accounts and for editing the full range of configuration options appears in the sections which follow.

 Edit the HoTTProxy Configuration File

Note: You only need to do this if you want to change options that are not presented in the Administration console. The instructions below should be considered to be "for experts".

Now we get into some good stuff. While you can run HoTTProxy using the provided configuration file "as is", there wouldn't be much adventure in that.

Note that to edit any of the HoTTProxy files you'll need to use a text editor. For Linux this might be KEdit (or another editor), for Win32 this could be Notepad (but I'd recommend buying UltraEdit if you'll be doing much text editing on Windows). When you save the files, it is important that you ensure that the file is named the way I say to name it. Particularly on Windows, folks have a tendency to put .txt on the end of everything and that won't work.

The documentation that tells what each item in the configuration file does is in the supplied default configuration file, and I don't see much use in reproducing it here since it is bound to grow over time. Instead I'm going to cover the items that you'll probably want to change, and warn you about some items that I don't think you should change unless you have a good reason to.

It is important to note that the format of this file is fairly critical. If you mess it up you may get unpredicatable results. Things to be aware of:

• Lines that begin with a pound sign ('#') are comments and are ignored by HoTTproxy
• Blank lines are ignored by HoTTproxy

• All other lines consist of a configuration parameter name, followed by a space, followed by an equal sign ('=') followed by a space, followed by one or more values. You must put the spaces around the equal sign. Yes, I could have programmed HoTTProxy to be more tolerant of formatting deviations, but I didn't.

  Examples:

  Parameter with a single value:

       ProxyPort = 9201

  Parameter with a list of values:

       TrustedDomains = yourdomain.com;mydomain.com;otherdomain.com

  Note that with the parameter having a list of values, the values are separated by semicolons (';') and the semicolons don't have spaces before or after them. If you put a space before or after the semicolon, the space will actually become part of the value it appears with. For example, the above line translates into 3 parameters: "yourdomain.com", "mydomain.com", and "otherdomain.com". If you instead typed the line this way:

       TrustedDomains = yourdomain.com; mydomain.com; otherdomain.com

  your values would be: "yourdomain.com", " mydomain.com", and " otherdomain.com". (Note the leading space in the second and third value which would likely cause a problem.)

Some parameters that you might want to change (and why):

• DefaultHomePage - Requests for ".local" domains are redirected to work around cell phone carriers that lock the phone to a homepage like http://homepage. The redirect will be to either the user's personally configured home page, or to this default home page if they don't have a personal one configured.

  Whatever you set this to should be a page somewhat friendly to wireless devices. A good choice would be a page somewhere that has links to other wireless-friendly pages that you use a lot.

• RealmString - Not particularly important, but if a personal computer based browser tries to use your HoTTProxy gateway, this is the string that will show as the "name" of the gateway. You could set it to something spiffy or just leave it 'as is' if you want to be boring.

• ViaString - Similar in character to RealmString, ViaString is the name string that will show up in the HTTP "Via" header when someone using your gateway accesses a website. Most websites don't care about the Via header or do anything with it, but setting it to something spiffy is anti-boring.

• ProxyPort - The port is set to 9201 in the default configuration file and if you don't have a reason to change it, you might as well leave it alone. Reasons to change it might be if for instance your wireless device is locked to only use another port like 8080 (I've heard some carriers or phones do this).

• CookiePassthru - (Not yet implemented) This is set to zero by default and should probably stay that way. Changing this to a nonzero value would let cookies stored on the user's browser "pass through" the proxy server to the website being visited. If your device is a cell phone, this would probably be irrelevant as most phones don't support cookies on their own anyway and therefore won't have any cookies to send. However if the device is a personal computer then its browser probably does have stored cookies and if they are allowed to pass through, they may conflict with the cookies that HoTTProxy has stored or cause strange results. Basically, if you don't really understand how HoTTProxy's proxy cookies work, and how cookies in general work, leave this at zero.

• SetCookiePassthru - (Not yet implemented) Same thing as CookiePassthru except the other direction. Setting this to a nonzero would allow cookies sent to the browser by a website to pass through the proxy to the browser. If the device is a phone or other device that doesn't understand cookies, no harm will come, the cookie headers just get ignored. However you are wasting bandwidth receiving cookies that your phone is just going to ignore anyway. As with CookiePassthru, if you don't really understand how HoTTProxy's proxy cookies work, and how cookies in general work, leave this at zero.

• SessionCookieLife - A "session cookie" is one that is sent without an expiration date/time. Intuitively you'd think this means they never expire, but actually that's not correct. Cookies without an expiration date/time are supposed to be discarded when the "session" ends. On personal computers, this is when the user closes all instances of their browser. In the case of HoTTProxy and proxy cookie support, we don't have any idea when or if the user closes their browser -- we just see requests come through. Still, cookies are sent as session cookies for a reason, so we don't want them to last forever. As a compromise, the SessionCookieLife parameter is used to create an expiration date/time for cookies that don't have one. The value of SessionCookieLife is the number of minutes (from the time the session cookie was received) until the cookie should expire. The default value is 1440 which is 24 hours. You cannot set this value to zero (well you can, but if you do it will default to 1440). The shortest time you can set is 1 minute and I have no idea what the longest time is. If you wanted to go crazy and make session cookies last for a year, 525600 would be the approximate value (ignoring leap years). When messing with this value, remember that the website that sent you the session cookie is not expecting it to exist forever, so making it exist forever might be counterproductive unless you have a specific reason/purpose in mind.

Read the comments in the HoTTProxy.conf file to learn more about other parameters. Some would be of interest primarily only to developers who are messing with the code and need diagnostic information for debugging. As suggested in the comments at the top of the file, it is a good idea to keep a copy of the original file in case you mess it up.

 !!!LEGACY!!! - Deprecated - Creating User Files

Note: You really should not need nor want to do the below - these instructions are left in the documentation for purposes of reference, but the Administration Console is much preferred to doing it "by hand".

As written, HoTTProxy has no facility for running "open" and requires all users to authenticate. While it would be trivially simple to change this, it would be a bad idea since it would allow anyone who discovered that open port on your machine to use your proxy to do nefarious things semi-anonymously.

In order for a user to be able to authenticate, you have to create a password file for them. There are no password files in the distribution, so if you don't create any, then nobody will be able to use your proxy (including you).

Presently the password file is pretty simple. Some day I may regret not going with something more complicated, but we'll cross that bridge when we come to it.

Where to put them: The password files (which we'll tell you how to make in just a second) have to be put in the same directory where the HoTTProxy program is. Remember that we're assuming that is /home/HoTTProxy, or C:\HoTTProxy.

What to name them: The password files should be named 'username.password' (without the quotes). Note that the word 'username' appears in italics. You replace 'username' with the intended username for the user. For example, if you want the username to be "bob", you'd name the file "bob.password" (without the quotes).

What to put in the file: The file should be a simple text file that you will create with your text editor as mentioned earlier. The password file only has one required line. The first line of the file must contain the password for that user. Note that this password is case sensitive. Optionally the file can contain a second line which would be the user-specific home page URL. Remember in the configuration file section we talked about the default home page value and said that you can set a different home page for each user if you prefer? This is where you do it. The home page URL should be "fully qualified" which is to say it should include the 'http://' and all that jazz. As of this writing any lines after the second line would be ignored by HoTTProxy.

So, a sample password file (fictitiously named bob.password) might look like this:

 Running HoTTProxy

To run HoTTProxy you'll need to go back to the command prompt that you've been using. You should already be "in" whatever directory you installed HoTTProxy in. There are actually a number of different ways to start HoTTProxy.pl running depending upon your OS and configuration, but this command should work for all:

perl HoTTProxy.pl

If you've done everything correctly, you should be greeted with a screen showing you your configuration settings. Assuming you get no errors, HoTTProxy is now running.

 Testing your HoTTProxy installation

If you've got HoTTProxy installed and running, but you're having trouble getting your phone to connect through it, it is a good idea to isolate whether the problem is on the phone side or the proxy. One way is to reconfigure the browser on a personal computer to use your HoTTProxy. If the personal computer based browser can get to the Internet through your HoTTProxy, then you know the issue is on the phone side of things.

The most common problems encountered have to do with firewalls (hardware and software). Firewalls are designed to protect your computer from unwanted traffic from the Internet. By default, most firewalls assume that all unsolicited traffic from the Internet is unwanted. You'll need to tell your firewall(s) (you may have more than one) to let port 9201 (or whatever port you configured HoTTProxy to use) to come through, and in the case of a hardware firewall, tell the firewall to forward traffic on that port to your computer. The process for doing this is too varied to be covered by this article. General tips however follow.

Hardware firewalls - are typically found in broadband routers and wireless broadband routers that you may have purchased and installed to let multiple computers use your broadband Internet connection. Without exception these devices block incoming traffic by default. Check your manual for details on "port forwarding", "virtual server", or "service" definitions and rules to find out how to allow port 9201 in, and get it to go to your computer. Additionally, some DSL modems themselves (ActionTec for example) have a built in firewall. They too can be configured to pass port 9201 to your PC - see the manual.

Software firewalls - may be something that came with your OS or something you added on to it. If you're running Microsoft Windows XP, it has a built in software firewall that is enabled by default. You can either disable the XP firewall completely (might be appropriate if you already have a good hardware firewall), or configure it to allow only port 9201 through (if say you're directly connected to the Internet). Microsoft TechNet has a good article here on configuring the XP firewall. You might also have a 3rd party software firewall that you installed yourself. Good examples would be ZoneAlarm, BlackIce, etc. You'll have to follow the manufacturer's instructions to open a port in these firewalls.

 Other Stuff

If you're running HoTTProxy on a machine that has a dynamic IP address (the ISP changes the address periodically), then installing a dynamic DNS client on the machine and setting up a DynDNS.org domain name for it would be a good idea. If you don't do this, then every time your ISP changes your IP address, you'll have to: a) realize that it changed, and b) change it in your phone, and c) tell your buddies that also use your proxy server to change their phones. How to set up DynDNS will be the topic of a separate Technical Article.

Of course you're also going to want to set up your phone to use your shiny new proxy server. See the home page for a link to instructions on configuring the proxy settings for various phones.

Last but not least, if you are having trouble getting HoTTProxy running, be sure to go to the home page and click on the "Support/Discussion Forums" link. There you will be able to get help with your problem if you present your question in a concise manner and demonstrate that you've made a reasonable effort to solve your problem yourself.