Skip to content

Latest commit

 

History

History
170 lines (109 loc) · 6.12 KB

README.rdoc

File metadata and controls

170 lines (109 loc) · 6.12 KB
Raw
                    ,.
                   ;:::
,  _ .___mouseHole_;:::_web_proxy___. __, .

          ... rewrite web pages
           ... run little apps
            ... crossite ajax
             ... persistence
              ... all that!

about mouseHole = ↑

MouseHole is a personal web proxy written in Ruby designed to be simple to script. Scripts can rewrite the web as you view it, altering content and behavior as you browse. Basically, it’s an alternative to Greasemonkey, which does similar things from inside the Firefox web browser.

Believe it or not, though, MouseHole does a lot more than that. Here’s a taste of what you’ll be seeing:

running mouseHole = ↑

MouseHole can either intrude completely upon your browsing experience or you can keep it off in the outskirts, for whenever you’ve got a second to duck into that little crack in the wall. You can run it on one machine and use it wherever, allowing whomever you want to poke their head in.

The underlying ideas are always the same, though.

  • 1

    Start MouseHole.

  • 2

    Visit 127.0.0.1:3704/ to view your settings.

  • 3

    Set MouseHole as your web proxy.

  • 4

    Install user scripts.

  • 5

    Or, write your own.

starting mouseHole == ↑

To start using mouseHole, simply run the script. On Windows, click on mouseHole.exe. On other operating systems, run ‘ruby bin/mouseHole’ from inside the unpacked mouseHole directory. A text window should popup showing that mouseHole is started.

You can pass in the hostname and port number you’d like to run MouseHole on.

  • mouseHole 203.203.203.203 to run on publicly accessible IP 203.203.203.203.

  • mouseHole 127.0.0.1 5300 to run on a different port on localhost.

If your Web access itself is through a proxy, set the HTTP_PROXY environment variable to the IP:PORT of that proxy.

the doorway == ↑

Visit the hostname and port you choose above in your browser. Normally, this will be 127.0.0.1:3704/. The doorway will appear. A page with a bit of mouseHole-related graffitis. (Once you get the proxy setup, you’ll be able to use mh/ or mouse.hole/ instead of the IP:PORT.)

The doorway lets you configure the scripts you have installed. There’s not much to it. You can turn scripts on and off. Or you can tell it what sites it can or can’t control. The doorway will also let you know if a script has been loaded or if it has errors.

setting mouseHole as proxy == ↑

This is the moment of decision. Will you use mouseHole for your whole browser experience? Or will you use it only occassionally? Or would you like to be able to turn it on and off at will?

using mouseHole exclusively === ↑

If you’re using Firefox, open the Preferences window. Select the General tab. Click the Connection Settings button. Activate the Manual Proxy Configuration settings. Fill in MouseHole’s hostname and port. (Again, the default is 127.0.0.1 and port 3704.)

If you’re on OS X and want to use it to proxy all Safari traffic, go to the Network preference pane (in System Preferences), select Web Proxy, enter 127.0.0.1 as address and 3704 as port.

speeding up with lighttpd or apache2 === ↑

If you want to go robust, you can run MouseHole through LightTPD/FastCGI (a free web server) or Apache2/mod_ruby (also free). The LightTPD seems to work better for most people, so (if you’re on Linux or OSX) give it a try.

You’ll need LightTPD, FastCGI, and FCGI-Ruby installed. Once all are installed, fire it all up with:

mouseHole -s lighttpd

You can pass in all the typical commandline options as well, if you like.

mouseHole -s lighttpd --no-tidy 127.0.0.1 3704

Logs for script errors are stored in ~/.mouseHole/log.

If you’d like to run Apache2, be sure you have Apache2 and mod_ruby installed. Then, get it started with:

mouseHole -s apache2

To stop Apache:

apachectl -f ~/.mouseHole/temp/apache/httpd.conf -k stop

occasional mouseHole === ↑

Firefox has a few useful extensions for managing proxies.

adds a button to your toolbar. The button turns proxying on and off.

toolbar, a context menu and/or a status bar menu for switching between several proxies. The status bar menu is especially handy as it is small, but displays the name of your current proxy, which you can right-click on to change.

using proxyLike === ↑

ProxyLike is a mouseHole user script which lets you pass URLs into mouseHole for rewriting on a case-by-case. To install ProxyLike, you’ll need to use mouseHole as your proxy for a bit. Once you’ve got mouseHole running as your proxy (described above), visit www.whytheluckystiff.net/mouseHole/proxylike.user.rb. mouseHole will guide you through the installation.

You can now turn off your proxy settings in your browser. Pass URLs into ProxyLike by prefixing the URL with your mouseHole IP:PORT.

Onslaught through mouseHole.

You can also install scripts through ProxyLike. If you have it installed, you can upgrade ProxyLike with:

http://127.0.0.1:3704/http:/www.whytheluckystiff.net/mouseHole/proxylike.user.rb.

install user scripts == ↑

To install a script, simply visit an existing script and MouseHole will auto-detect this and prompt you for installation.

At this time, there is no way to install a script sitting on your hard drive (because file:// URLs don’t go through proxies) without throwing it in .mouseHole/userScripts and restarting MouseHole or uploading the script to a remote server. (1.2 and up detects new scripts in .mouseHole/userScripts and refreshes them as you edit it.)

A list of known MouseHole scripts is available at UserScripts.

Making Your Own Scripts == ↑

For help in writing your own script, see mousehole.rubyforge.org/wiki/wiki.pl?Editing_MouseHole_Scripts.

For debugging purposes, you can visit localhost:3704/mouseHole/database to view a database dump of MouseHole.