README.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4   <title>Middleman filtering proxy server</title>
   5   <meta http-equiv="content-type"
   6  content="text/html; charset=ISO-8859-1">
   7 </head>
   8 <body>
   9 <div align="center"><big><big><big>Middleman filtering proxy server<br>
  10 <small><small>(c)2002 Jason McLaughlin &lt;<a
  11  href="mailto:jasonmc@sympatico.ca">jasonmc@sympatico.ca</a>&gt;</small></small><br>
  12 </big></big><a href="http://www.sourceforge.net/projects/middle-man">http://www.sourceforge.net/projects/middle-man</a></big><br>
  13 <br>
  14 <br>
  15 <div align="left">
  16 <div align="center"><b>Introduction</b><br>
  17 </div>
  18 <br>
  19 <br>
  20 Middleman is a powerful proxy server with many features designed to
  21 make browsing the Internet a more pleasant experience. It can do much
  22 more than just proxying though; it can be used as a layer between any
  23 web server and client to filter HTTP requests, or act as a portal
  24 between an internal network and the Internet. It has an intuitive Web
  25 interface that provides an easy way of accessing and changing the
  26 proxy's configuration, there's no need to dig through any complicated
  27 configuration files.<br>
  28 <br>
  29 <div align="center"><b>Installation</b><br>
  30 </div>
  31 <div align="left">Installing Middleman should be straightforward. After
  32 extracting the archive type "./configure &amp;&amp; make", if you're
  33 using a BSD operating system you will need to use "gmake" rather than
  34 make, if that's unavailable as a last resort you can use BSD's make,
  35 then enter the "gcc -o mman *.o" command afterwards. There are
  36 several compile-time options available for the configure script, type
  37 "./configure --help" to see a complete list.<br>
  38 <br>
  39 If you wish to have the proxy server loaded at boot time, there is a
  40 script in the "scripts" directory called mman.init to assist you with
  41 that, simply edit the paths at the top then copy it to the "/etc/rc.#"
  42 directory, where # is your current runlevel (if you're unsure what it
  43 is, use the "runlevel" command). You may need to rename the script, if
  44 you're using a debian-based distribution the naming scheme for init.d
  45 scripts is in the form "S##program", where ## is the order in which the
  46 script is loaded, and "program" is the program's name.<br>
  47 <br>
  48 There are several command line options you may use when loading the
  49 proxy server; at the very least you will need to use the -c option
  50 followed by the path to the configuration file. The -p option can be
  51 used to have middleman check (and create) a file containing the PID of
  52 the proxy server, this can be used to prevent multiple instances of the
  53 proxy server from running concurrently. The -l option can be used to
  54 specify the path to the logfile if the --enable-syslog option wasn't
  55 used during compilation, and -d to specify the level of detail which
  56 should be logged; use -h for a complete list of loglevels.<br>
  57 <br>
  58 <div align="center"><b>Using<br>
  59 </b><br>
  60 </div>
  61 Once the proxy server is running, you'll then need to configure your
  62 web browser to use it.<br>
  63 <br>
  64 If you're using Mozilla, open up the edit menu and click on
  65 preferences. Expand the "advanced" options then click on "Proxies".
  66 Click on the "Manual proxy configuration" radio button then fill in the
  67 HTTP and HTTPS fields with the IP address and port of the proxy; if
  68 you're using the default configuration, the port will be 8080.<br>
  69 <br>
  70 If you're using Konqueror, open up the settings menu and click on
  71 "Configure Konqueror". Click on the icon labeled "Proxy" in the left
  72 pane, click the "Use proxy" checkbox and then the "Manual proxy
  73 configuration" checkbox. Click on setup to the right of that then fill
  74 in the HTTP and HTTPS fields with the IP address and port of the proxy.<br>
  75 <br>
  76 <div style="text-align: center;"><span style="font-weight: bold;">URL
  77 commands<br>
  78 <br>
  79 </span><span style="font-weight: bold;"></span></div>
  80 Any feature can be temporarily bypassed by adding a special prefix to
  81 the URL. To bypass everything, use "bypass..website.com" or
  82 "/bypass../file" for HTTP requests, to bypass only some features, use
  83 "bypass[&lt;features&gt;]..website.com or
  84 "/bypass[&lt;features&gt;]../file" for HTTP requests; where
  85 &lt;features&gt; is any combination of the letters 'f' (URL filter), 'r'
  86 (redirecting), 'w' (rewrite), 'h' (header filter), 'm' (MIME filter),
  87 'c' (cookie filter), 'e' (external parser), 'p' (forwarding), and 'k'
  88 (keyword filtering). The '+' (plus) and '-' &nbsp;(minus) symbols can be
  89 used to alternate between bypassing and unbypassing the features, if the
  90 access rule bypassed it already. For example:
  91 "bypass[fw-ph]..website.com" will bypass the URL filtering and rewrite
  92 feature, and unbypass the forwarding and header filter feature. The
  93 "filter.." and "mime.." URL command will respectively show which URL or
  94 MIME filter entry matches the requested URL, if any, and provide a link
  95 to edit or delete it. The "score.." URL command will show the keyword
  96 score for a page. URL commands are also taken from the Referer header
  97 sent by your browser, making them apply to images, links, or files
  98 loaded from a webpage a URL command was used on; and any URL command
  99 used when making a request which results in a server sending back a 302
 100 redirect is added to the Location header as well. More than one URL
 101 command can be used at the same time, simply append it to the end of the
 102 previous one; for example, if you want to check if something matches a
 103 MIME filter entry but the site is blocked by a URL filter entry, you can
 104 use "bypass[f]..mime..www.somenastysite.com".<br>
 105 <br>
 106 <br>
 107 <div align="center"><b>Configuration<br>
 108 </b>
 109 <div align="left"><br>
 110 Most of the configuration is made easy by the Web interface; however,
 111 configuring the network settings will need to be done by manually
 112 editing the configuration file. At the top of the included config.xml
 113 you will see a section that looks simular to the following:<br>
 114 <br>
 115 &lt;network&gt;<br>
 116 &nbsp;&nbsp;&nbsp; &lt;listen&gt;<br>
 117 &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &lt;ip&gt;127.0.0.1&lt;/ip&gt;<br>
 118 &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &lt;port&gt;8080&lt;/port&gt;<br>
 119 &nbsp;&nbsp;&nbsp; &lt;/listen&gt;<br>
 120 &lt;/network&gt;<br>
 121 <br>
 122 Each &lt;listen&gt; section inside the &lt;network&gt; section has an
 123 &lt;ip&gt; and &lt;port&gt; option, which should contain after them the
 124 IP address and port number to listen on, respectively. You may leave out
 125 the &lt;ip&gt; option to have Middleman listen on all interfaces.
 126 Middleman, by default, can have up to 20 &lt;listen&gt; sections.<br>
 127 <br>
 128 As mentioned above, all other configuration settings can be modified
 129 through the Web interface. To access this, while using the proxy load
 130 "http://mman" in your browser; when not using the proxy, the Web
 131 interface is accessible by making a regular HTTP request for /mman to
 132 the proxy's IP address and port.<br>
 133 <br>
 134 Once you've loaded the Web interface, you will see a page with several
 135 links available at the top. <br>
 136 <br>
 137 The "Active connections" link will display a page showing all
 138 connections currently being handled by the proxy. <br>
 139 <br>
 140 The "DNS cache" link is for debugging purposes only, and will display
 141 entries in the DNS cache. <br>
 142 <br>
 143 The "Show headers" link will bring you to a page showing all the HTTP
 144 headers your browser sends, and what they look like after being
 145 filtered. Note: headers handled by Middleman aren't shown, this is to
 146 avoid confusion.<br>
 147 <br>
 148 The "Save settings" link will bring you to a page with a Filename
 149 dialog where you can save all current settings, by default it will be
 150 filled with the path to the configuration file given when the proxy
 151 server was loaded.<br>
 152 <br>
 153 The "Load settings" link will also bring you to a page with a Filename
 154 dialog, as well as an "Overwrite" option. The overwrite option can be
 155 used to select whether the settings contained in the configuration file
 156 will overwrite all current settings or simply be added to them.<br>
 157 <br>
 158 The "View log entries" link will bring you to a page showing recent
 159 entries made to the logfile, and will allow you to search through them
 160 using regular expressions. The log buffer can also be cleared from here,
 161 as well as have it's size adjusted. The level of logging detail
 162 available through the web interface is unaffected by the options given
 163 in the command line, and will always be all log entires with the
 164 exception of debug messages.<br>
 165 <br>
 166 The "Config" link will bring you to a page where all configuration
 167 settings can be accessed. On the main page you will see a dialog with a
 168 drop down list containing the name of each section, as well as a table
 169 with a list lf each section and an enable/disable radio button beside
 170 it; this can be used to quickly enable/disable a feature if it's causing
 171 problems with a website.<br>
 172 <br>
 173 When you select an item in the drop down list and click on the submit
 174 button, you will be brough to a page containing a dialog at the top as
 175 well as a list of entries for that section below, with the exception of
 176 the network section, which is read-only. The dialog at the top will
 177 always contain an "add" link, which can be used to add an additonal
 178 entry to the section, and in some cases will have several other options
 179 which will be explained below. Each entry at the bottom has an "Edit",
 180 "Delete", "Up", "Down", "Top", and "Bottom" link. The edit link will
 181 bring you to a dialog where you can edit that specific entry, the delete
 182 link will remove it from the section. The "Up" and "Down" links allow
 183 you to change the order of the entries, this is important in &nbsp;cases
 184 where more than one entry can match the same thing. The "Top" and
 185 "Bottom" links can be used to move the entry to the very top or bottom
 186 of the list.<br>
 187 <br>
 188 All entries for all sections have an "Enabled" option which allows you
 189 to disable a specific entry, as well as a "Comment" field that can be
 190 used to store a description of what the entries purpose is.<br>
 191 <br>
 192 Several sections follow an allow/deny/policy model; for these sections,
 193 each entry has an action option which will specify what happens when it
 194 is found to match. If no matching entry is found, the action the policy
 195 is set to will be taken. It is important to remember that all entries
 196 with an action opposite to the policy are searched first, and if nothing
 197 is found the entries with an action the same as the policy are not
 198 searched. So, for example, if the policy for the access section is set
 199 to "allow", and no entries with a "deny" action are found matching the
 200 connection, none of the entries with an "allow" action are looked at, so
 201 any access limitations specified in the allow entry are ignored.<br>
 202 <br>
 203 The tables below will describe all the options available in each
 204 section and the entries within them.<br>
 205 <br>
 206 <div align="center"><b>--- Access section ---</b><br>
 207 <div align="left"><br>
 208 <table cellpadding="2" cellspacing="2" border="1" width="100%">
 209   <tbody>
 210     <tr align="center">
 211       <td valign="top" colspan="2"><b>Purpose</b><br>
 212       </td>
 213     </tr>
 214     <tr>
 215       <td valign="top" colspan="2">The access feature is used to
 216 control who can access the proxy server, and to what extent.</td>
 217     </tr>
 218     <tr align="center">
 219       <td valign="top" colspan="2"><b>Global options</b><br>
 220       </td>
 221     </tr>
 222     <tr>
 223       <td valign="top">Policy<br>
 224       </td>
 225       <td valign="top">Default action to take when no matching entry is
 226 found.</td>
 227     </tr>
 228     <tr align="center">
 229       <td valign="top" colspan="2"><b>Entry options</b><br>
 230       </td>
 231     </tr>
 232     <tr>
 233       <td valign="top">IP Address<br>
 234       </td>
 235       <td valign="top">A&nbsp;regular expression matching the IP
 236 addresses this entry applies to, leaving blank will cause the entry to
 237 match everything.</td>
 238     </tr>
 239     <tr>
 240       <td style="vertical-align: top;">Username<br>
 241       </td>
 242       <td style="vertical-align: top;">If this field is not empty,
 243 clients matching this entry will be required to authenticate with the
 244 proxy server. There can be more than one entry matching the same IP
 245 address, in which case the one matching the username/password send by
 246 the browser is used.<br>
 247       </td>
 248     </tr>
 249     <tr>
 250       <td style="vertical-align: top;">Password<br>
 251       </td>
 252       <td style="vertical-align: top;">The client's password if the
 253 username field is used.<br>
 254       </td>
 255     </tr>
 256     <tr>
 257       <td valign="top">Access<br>
 258       </td>
 259       <td valign="top">
 260       <table cellpadding="2" cellspacing="2" border="0" width="100%">
 261         <tbody>
 262           <tr>
 263             <td valign="top">A&nbsp;list of features connections
 264 matching this entry are allowed to access, the options are:</td>
 265           </tr>
 266           <tr>
 267             <td valign="top">Web interface - Access to all of the web
 268 interface (access to /mman/template/&lt;template name&gt; is always
 269 allowed regardless of this)</td>
 270           </tr>
 271           <tr>
 272             <td valign="top">Proxy requests - Allowed to make regular
 273 proxy requests</td>
 274           </tr>
 275           <tr>
 276             <td valign="top"> CONNECT Requests - Allowed to make CONNECT
 277 requests</td>
 278           </tr>
 279           <tr>
 280             <td valign="top"> Transparing proxying - Allowed to make
 281 transparent proxy requests (must be allowed to make HTTP requests as
 282 well)</td>
 283           </tr>
 284           <tr>
 285             <td valign="top"> HTTP Requests - Allowed to make regular
 286 HTTP requests to proxy (for Web interface and redirected requests)<br>
 287             </td>
 288           </tr>
 289           <tr>
 290             <td valign="top">Allow bypassing - Allows features to be
 291 bypassed by prefixing with URL command</td>
 292           </tr>
 293         </tbody>
 294       </table>
 295       <br>
 296       </td>
 297     </tr>
 298     <tr>
 299       <td valign="top">Bypass<br>
 300       </td>
 301       <td valign="top">A&nbsp;list of features which will by default be
 302 bypassed when making requests.</td>
 303     </tr>
 304     <tr>
 305       <td valign="top"><br>
 306       </td>
 307       <td valign="top"><br>
 308       </td>
 309     </tr>
 310   </tbody>
 311 </table>
 312 <br>
 313 </div>
 314 <div align="left">
 315 <div align="center"><b>--- Templates section ---<br>
 316 <br>
 317 </b></div>
 318 <div align="left">
 319 <table cellpadding="2" cellspacing="2" border="1" width="100%">
 320   <tbody>
 321     <tr align="center">
 322       <td valign="top" colspan="2"><b>Purpose</b><br>
 323       </td>
 324     </tr>
 325     <tr>
 326       <td valign="top" colspan="2">Templates are used throughout
 327 Middleman as a replacement for pages which can't be displayed due to
 328 filtering, error, or other condtions.</td>
 329     </tr>
 330     <tr align="center">
 331       <td valign="top" colspan="2"><b>Global options</b><br>
 332       </td>
 333     </tr>
 334     <tr>
 335       <td valign="top">Path<br>
 336       </td>
 337       <td valign="top">Location to look for templates in if no absolute
 338 path is given.</td>
 339     </tr>
 340     <tr align="center">
 341       <td valign="top" colspan="2"><b>Entry options</b><br>
 342       </td>
 343     </tr>
 344     <tr>
 345       <td valign="top">Name<br>
 346       </td>
 347       <td valign="top">
 348       <table cellpadding="2" cellspacing="2" border="0" width="100%">
 349         <tbody>
 350           <tr>
 351             <td valign="top">The name of the template, this is used in
 352 other sections to reference it. It may also be one of the following to
 353 replace internal error messages:</td>
 354           </tr>
 355           <tr>
 356             <td valign="top">blocked - Page blocked</td>
 357           </tr>
 358           <tr>
 359             <td valign="top">nodns - DNS lookup failed</td>
 360           </tr>
 361           <tr>
 362             <td valign="top">badrequest - Malformed HTTP header from
 363 client</td>
 364           </tr>
 365           <tr>
 366             <td style="vertical-align: top;">badresponse - Malformed
 367 HTTP header from server<br>
 368             </td>
 369           </tr>
 370           <tr>
 371             <td valign="top">nofile - File not found</td>
 372           </tr>
 373           <tr>
 374             <td valign="top">noconnect - Connection failed</td>
 375           </tr>
 376           <tr>
 377             <td valign="top">noaccess - Access denied</td>
 378           </tr>
 379           <tr>
 380             <td valign="top">badprotocol - Protocol not implemented</td>
 381           </tr>
 382           <tr>
 383             <td valign="top">badauth - Authorization failed (when
 384 forwarding through SOCKS4)<br>
 385             </td>
 386           </tr>
 387           <tr>
 388             <td valign="top"><br>
 389             </td>
 390           </tr>
 391           <tr>
 392             <td valign="top">There are 3 built-in templates that can be
 393 used: tinygif (a 1x1 transparent gif image), checkedgif (a 4x4 grey and
 394 transparent checkered pattern), and tinyswf (an emtpy flash animation).</td>
 395           </tr>
 396           <tr>
 397             <td valign="top"><br>
 398             </td>
 399           </tr>
 400           <tr>
 401             <td valign="top">
 402             <div align="left">You can override the content sent by a
 403 website for certain response codes by making a template with a numerical
 404 name the same as the response code.<br>
 405             <br>
 406             </div>
 407             </td>
 408           </tr>
 409           <tr>
 410             <td valign="top"><br>
 411             </td>
 412           </tr>
 413           <tr>
 414             <td valign="top">
 415             <table cellpadding="2" cellspacing="2" border="0"
 416  width="100%">
 417               <tbody>
 418                 <tr>
 419                   <td valign="top">There are several variables that can
 420 be used in templates which will be replaced with information about the
 421 request currently being handled, they are:<br>
 422                   </td>
 423                 </tr>
 424                 <tr>
 425                   <td valign="top">$HTTP_METHOD - Method used to
 426 request file<br>
 427                   </td>
 428                 </tr>
 429                 <tr>
 430                   <td valign="top">$HTTP_HOST - Host HTTP request was
 431 made to.<br>
 432                   </td>
 433                 </tr>
 434                 <tr>
 435                   <td valign="top">$HTTP_FILE - File HTTP request was
 436 made for.<br>
 437                   </td>
 438                 </tr>
 439                 <tr>
 440                   <td valign="top">$HTTP_PORT - Port HTTP request was
 441 made to.<br>
 442                   </td>
 443                 </tr>
 444                 <tr>
 445                   <td valign="top">$IP - IP address of client making
 446 request.<br>
 447                   </td>
 448                 </tr>
 449               </tbody>
 450             </table>
 451             </td>
 452           </tr>
 453           <tr>
 454             <td valign="top"><br>
 455             </td>
 456           </tr>
 457           <tr>
 458             <td valign="top">Templates can be accessed directly by
 459 loading "http://mman/template/&lt;template name&gt;".<br>
 460             </td>
 461           </tr>
 462         </tbody>
 463       </table>
 464       <br>
 465       </td>
 466     </tr>
 467     <tr>
 468       <td valign="top">File<br>
 469       </td>
 470       <td valign="top">The filename of the template</td>
 471     </tr>
 472     <tr>
 473       <td valign="top">Mimetype<br>
 474       </td>
 475       <td valign="top">The MIME-type of the template. When using an
 476 executable, this can be set to STDIN to have the MIME-type extracted
 477 from a "Content-type" header sent by the program, this will be explained
 478 in greater depth below.</td>
 479     </tr>
 480     <tr>
 481       <td valign="top">Response code</td>
 482       <td valign="top">The response code to use when sending the
 483 template, leave blank to use internal default.</td>
 484     </tr>
 485     <tr>
 486       <td valign="top">Type<br>
 487       </td>
 488       <td valign="top">Template type, either File or Executable. If
 489 executable is choses, the file is executed and whatever it writes on
 490 STDOUT is sent as the template. Several environment variables are set
 491 for the executable to use, they will be explained further below in the
 492 external section.</td>
 493     </tr>
 494   </tbody>
 495 </table>
 496 </div>
 497 </div>
 498 </div>
 499 <br>
 500 <div align="center"><b>--- MIME section ---<br>
 501 <br>
 502 </b>
 503 <table cellpadding="2" cellspacing="2" border="1" width="100%">
 504   <tbody>
 505     <tr align="center">
 506       <td valign="top" colspan="2"><b>Purpose</b><br>
 507       </td>
 508     </tr>
 509     <tr align="left">
 510       <td valign="top" colspan="2">The mime feature allows you to
 511 filter content based on it's MIME-type.</td>
 512     </tr>
 513     <tr align="center">
 514       <td valign="top" colspan="2"><b>Global options</b><br>
 515       </td>
 516     </tr>
 517     <tr>
 518       <td valign="top">Policy<br>
 519       </td>
 520       <td valign="top">The action to take when no matching entry is
 521 found.</td>
 522     </tr>
 523     <tr>
 524       <td valign="top">Default template<br>
 525       </td>
 526       <td valign="top">The template to send for blocked MIME-types if
 527 the template option is left blank for the matching entry, or if no
 528 matching entry is found but the policy is deny.</td>
 529     </tr>
 530     <tr align="center">
 531       <td valign="top" colspan="2"><b>Entry options</b><br>
 532       </td>
 533     </tr>
 534     <tr>
 535       <td valign="top">Host<br>
 536       </td>
 537       <td valign="top">A regular expression matching the host's this
 538 entry applies to, leave blank to match everything.</td>
 539     </tr>
 540     <tr>
 541       <td valign="top">File<br>
 542       </td>
 543       <td valign="top">A regular expression matching the file's this
 544 entry applies to, leave blank to match everything.</td>
 545     </tr>
 546     <tr>
 547       <td valign="top">Mimetype<br>
 548       </td>
 549       <td valign="top">A regular expression matching the MIME-type's
 550 this entry applies to, leave blank to matching everything.</td>
 551     </tr>
 552     <tr>
 553       <td valign="top">Template<br>
 554       </td>
 555       <td valign="top">The template to send when an entry matches, this
 556 has no purpose in entries with the action set to allow.</td>
 557     </tr>
 558   </tbody>
 559 </table>
 560 <div align="left"><br>
 561 <div align="center"><b>--- Redirect section ---<br>
 562 <br>
 563 </b>
 564 <table cellpadding="2" cellspacing="2" border="1" width="100%">
 565   <tbody>
 566     <tr align="center">
 567       <td valign="top" colspan="2"><b>Purpose</b><br>
 568       </td>
 569     </tr>
 570     <tr>
 571       <td valign="top" colspan="2">The redirect feature allows you to
 572 redirect requests.</td>
 573     </tr>
 574     <tr align="center">
 575       <td valign="top" colspan="2"><b>Entry options</b><br>
 576       </td>
 577     </tr>
 578     <tr>
 579       <td valign="top">URL<br>
 580       </td>
 581       <td valign="top">A regular expression matching the URL's you wish
 582 to redirect; the URL will always be in the form "host/file" or "/file"
 583 for HTTP requests.</td>
 584     </tr>
 585     <tr>
 586       <td valign="top">Redirect<br>
 587       </td>
 588       <td valign="top">The URL to redirect to; it may contain
 589 backreferences to strings captured using parenthesis in the URL pattern.
 590 This can be in the form "host/file", or "/file" if you wish to send a
 591 relative URL when redirecting a URL in the Location: header. If this
 592 option is left blank, no action will be taken against requests matching
 593 the URL. <br>
 594       <br>
 595 See the rewrite section for additional notes on using regular
 596 expressions with backreferences.<br>
 597       </td>
 598     </tr>
 599     <tr>
 600       <td valign="top">Port<br>
 601       </td>
 602       <td valign="top">The port to redirect to; if left blank the same
 603 port the original request was made to is used.<br>
 604       </td>
 605     </tr>
 606     <tr>
 607       <td valign="top">302 Redirect<br>
 608       </td>
 609       <td valign="top">If yes, a 302 redirect is issued; otherwise the
 610 new host is connected to directly and the new file is requested. A 302
 611 redirect should always be used when possible to ensure relative links
 612 and images are correct.</td>
 613     </tr>
 614     <tr>
 615       <td valign="top">Options<br>
 616       </td>
 617       <td valign="top">
 618       <table cellpadding="2" cellspacing="2" border="0" width="100%">
 619         <tbody>
 620           <tr>
 621             <td valign="top">Several options are available to control
 622 how the URL should be handled, they are:<br>
 623             </td>
 624           </tr>
 625           <tr>
 626             <td valign="top">Encode URL - Encode the new URL.<br>
 627             </td>
 628           </tr>
 629           <tr>
 630             <td valign="top">Decode URL before - Decode the URL before
 631 attempting to match it with the regular expression<br>
 632             </td>
 633           </tr>
 634           <tr>
 635             <td valign="top">Decode URL after - Decode the new URL
 636 after matching.<br>
 637             </td>
 638           </tr>
 639         </tbody>
 640       </table>
 641       <br>
 642       </td>
 643     </tr>
 644     <tr>
 645       <td valign="top">Applies to<br>
 646       </td>
 647       <td valign="top">This option is to choose whether the redirection
 648 applies to requested URL's, the Location header when a remote site sends
 649 a 302 redirect, or both.<br>
 650       </td>
 651     </tr>
 652   </tbody>
 653 </table>
 654 <b><br>
 655 --- Forward section ---<br>
 656 <br>
 657 </b>
 658 <table cellpadding="2" cellspacing="2" border="1" width="100%">
 659   <tbody>
 660     <tr align="center">
 661       <td valign="top" colspan="2"><b>Purpose</b><br>
 662       </td>
 663     </tr>
 664     <tr>
 665       <td valign="top" colspan="2">The forward feature allows you to
 666 selectively forward requests through another proxy or SOCKS4 firewall
 667 based on their URL.<br>
 668       </td>
 669     </tr>
 670     <tr align="center">
 671       <td valign="top" colspan="2"><b>Entry options</b><br>
 672       </td>
 673     </tr>
 674     <tr>
 675       <td valign="top">Host<br>
 676       </td>
 677       <td valign="top">A regular expression matching the host's you
 678 wish to have requests forwarded for, leave blank to match everything.<br>
 679       </td>
 680     </tr>
 681     <tr>
 682       <td valign="top">File<br>
 683       </td>
 684       <td valign="top">A regular expression matching the file's you
 685 wish to have requests forwarded for, leave blank to match everything.<br>
 686       </td>
 687     </tr>
 688     <tr>
 689       <td valign="top">Proxy<br>
 690       </td>
 691       <td valign="top">The hostname or IP address of the proxy to
 692 forward through; if this is left blank, and the host or file options
 693 aren't, no action will be taken for requests matching the host and file.<br>
 694       </td>
 695     </tr>
 696     <tr>
 697       <td valign="top">Username<br>
 698       </td>
 699       <td valign="top">The username to use if the proxy requires
 700 authentication.<br>
 701       </td>
 702     </tr>
 703     <tr>
 704       <td valign="top">Password<br>
 705       </td>
 706       <td valign="top">The password to use if the proxy requires
 707 authentication.<br>
 708       </td>
 709     </tr>
 710     <tr>
 711       <td valign="top">Domain<br>
 712       </td>
 713       <td valign="top">The NT domain when using the NTLM authentication
 714 protocol.<br>
 715       </td>
 716     </tr>
 717     <tr>
 718       <td valign="top">Port<br>
 719       </td>
 720       <td valign="top">The port number of the proxy to forward through.<br>
 721       </td>
 722     </tr>
 723     <tr>
 724       <td valign="top">Type<br>
 725       </td>
 726       <td valign="top">What type of proxy to forward through; can be
 727 HTTP or SOCKS4<br>
 728       </td>
 729     </tr>
 730     <tr>
 731       <td valign="top">Applies to<br>
 732       </td>
 733       <td valign="top">What type of requests are forwarded; can be HTTP
 734 and/or CONNECT (HTTPS)<br>
 735       </td>
 736     </tr>
 737   </tbody>
 738 </table>
 739 </div>
 740 </div>
 741 </div>
 742 </div>
 743 </div>
 744 </div>
 745 </div>
 746 </div>
 747 <div align="center"><b><br>
 748 --- Header section ---<br>
 749 <br>
 750 </b>
 751 <table cellpadding="2" cellspacing="2" border="1" width="100%">
 752   <tbody>
 753     <tr align="center">
 754       <td valign="top" colspan="2"><b>Purpose</b><br>
 755       </td>
 756     </tr>
 757     <tr>
 758       <td valign="top" colspan="2">The header feature allows you to
 759 control what headers are passed from your browser to websites. In
 760 additional to the allow and deny actons in some other sections, there is
 761 an insert action which will add a new header onto the ones sent by your
 762 browser; for these entires, the Host and Type options are plaintext.<br>
 763       </td>
 764     </tr>
 765     <tr align="center">
 766       <td valign="top" colspan="2"><b>Global options</b><br>
 767       </td>
 768     </tr>
 769     <tr>
 770       <td valign="top">Policy<br>
 771       </td>
 772       <td valign="top">The action to take when no matching entries are
 773 found.<br>
 774       </td>
 775     </tr>
 776     <tr align="center">
 777       <td valign="top" colspan="2"><b>Entry options</b><br>
 778       </td>
 779     </tr>
 780     <tr>
 781       <td valign="top">Host<br>
 782       </td>
 783       <td valign="top">A regular expression matching the host's this
 784 entry applies to; leave blank to match everything.<br>
 785       </td>
 786     </tr>
 787     <tr>
 788       <td valign="top">Type<br>
 789       </td>
 790       <td valign="top">A regular expression matching the header type's
 791 this entry applies to; leave blank to match everything (header's are in
 792 the form "Type: value").<br>
 793       </td>
 794     </tr>
 795     <tr>
 796       <td valign="top">Value<br>
 797       </td>
 798       <td valign="top">A regular expression matching the header value's
 799 this entry applies to; leave blank to match everything.<br>
 800       </td>
 801     </tr>
 802   </tbody>
 803 </table>
 804 <br>
 805 <b>--- Rewrite section ---<br>
 806 <br>
 807 </b>
 808 <table cellpadding="2" cellspacing="2" border="1" width="100%">
 809   <tbody>
 810     <tr align="center">
 811       <td valign="top" colspan="2"><b>Purpose</b><br>
 812       </td>
 813     </tr>
 814     <tr>
 815       <td valign="top" colspan="2">The rewrite feature allows you to
 816 use regular expressions to modify the contents of webpages, files, the
 817 client header, and server header.<br>
 818       </td>
 819     </tr>
 820     <tr align="center">
 821       <td valign="top" colspan="2"><b>Entry options</b><br>
 822       </td>
 823     </tr>
 824     <tr>
 825       <td valign="top">Host<br>
 826       </td>
 827       <td valign="top">A regular expression matching the host's this
 828 entry applies to; leave blank to match everything.<br>
 829       </td>
 830     </tr>
 831     <tr>
 832       <td valign="top">File<br>
 833       </td>
 834       <td valign="top">A regular expression matching the file's this
 835 entry applies to; leave blank to match everything.<br>
 836       </td>
 837     </tr>
 838     <tr>
 839       <td valign="top">Mimetype<br>
 840       </td>
 841       <td valign="top">A regular expression matching the MIME-type's
 842 this entry applies to. This must be filled with something, otherwise the
 843 rewrite rule will be applied to every downloaded file, which is almost
 844 certainly not what you want. To have it applied to webpages, fill this
 845 field with "text/html"<br>
 846       </td>
 847     </tr>
 848     <tr>
 849       <td valign="top">Pattern<br>
 850       </td>
 851       <td valign="top">A regular expression pattern matching the area
 852 of text inside the file to modify; if this is left blank, and the host,
 853 file, or mimetype options aren't, this will be the last entry matched
 854 for sites matching the host, file, and mimetype.<br>
 855       </td>
 856     </tr>
 857     <tr>
 858       <td valign="top">Replace<br>
 859       </td>
 860       <td valign="top">The replacement text to use in place of the area
 861 of text matching the pattern; it may contain backreferences to strings
 862 captured using parenthesis in the pattern.<br>
 863       <br>
 864 A backrefernce to a captured string is in the form "$#", where # is a
 865 number from 1-9; "$0" will be replaced with the entire area of text
 866 matching the regular expression.<br>
 867       <br>
 868 Escape sequences may be used to represent unprintable characters, they
 869 are "\n" (newline), "\r" (carrier return), and "\t" (tab). To use a
 870 backslash as part of the replacement text, preceed it with another
 871 backslash.<br>
 872       </td>
 873     </tr>
 874     <tr>
 875       <td valign="top">Applies to<br>
 876       </td>
 877       <td valign="top">This option is to select what the rewrite rule
 878 applies to; the options are:
 879       <table cellpadding="2" cellspacing="2" border="0" width="100%">
 880         <tbody>
 881           <tr>
 882             <td valign="top">Client header - rewrite the client header;
 883 this happens before Middleaman parses it so be careful not to remove any
 884 headers needed to handle the request properly. The Mimetype option
 885 serves no purpose for this.<br>
 886             </td>
 887           </tr>
 888           <tr>
 889             <td valign="top">Server header - rewrite the header from
 890 the remote web server; same conditons from client header apply.<br>
 891             </td>
 892           </tr>
 893           <tr>
 894             <td valign="top">Body - rewrite the body of the webpage or
 895 file.<br>
 896             </td>
 897           </tr>
 898           <tr>
 899             <td style="vertical-align: top;">POST data - rewrite
 900 POST/PUT data sent when submitting a form or uploading a file.<br>
 901             </td>
 902           </tr>
 903         </tbody>
 904       </table>
 905       <br>
 906       </td>
 907     </tr>
 908   </tbody>
 909 </table>
 910 <br>
 911 <b>--- Cookies section ---<br>
 912 <br>
 913 </b>
 914 <table cellpadding="2" cellspacing="2" border="1" width="100%">
 915   <tbody>
 916     <tr align="center">
 917       <td valign="top" colspan="2"><b>Purpose</b><br>
 918       </td>
 919     </tr>
 920     <tr>
 921       <td valign="top" colspan="2">The cookies feature allows you to
 922 choose which hosts your browser is allowed to send and receive cookies
 923 to and from.<br>
 924       </td>
 925     </tr>
 926     <tr align="center">
 927       <td valign="top" colspan="2"><b>Global options</b><br>
 928       </td>
 929     </tr>
 930     <tr>
 931       <td valign="top">Policy<br>
 932       </td>
 933       <td valign="top">The action to take when no matching entry is
 934 found.<br>
 935       </td>
 936     </tr>
 937     <tr align="center">
 938       <td valign="top" colspan="2"><b>Entry options</b><br>
 939       </td>
 940     </tr>
 941     <tr>
 942       <td valign="top">Host<br>
 943       </td>
 944       <td valign="top">A regular expression matching the host's this
 945 entry applies to.<br>
 946       </td>
 947     </tr>
 948     <tr>
 949       <td valign="top">Direction<br>
 950       </td>
 951       <td valign="top">The direction of the cookie this entry applies
 952 to; can be either in (Set-cookie sent by website), out (Cookie sent by
 953 browser), or both.<br>
 954       </td>
 955     </tr>
 956   </tbody>
 957 </table>
 958 <br>
 959 </div>
 960 <div align="center"><b>--- External section ---<br>
 961 <br>
 962 </b>
 963 <table cellpadding="2" cellspacing="2" border="1" width="100%">
 964   <tbody>
 965     <tr align="center">
 966       <td valign="top" colspan="2"><b>Purpose</b><br>
 967       </td>
 968     </tr>
 969     <tr>
 970       <td valign="top" colspan="2">The external feature allows you to
 971 use any program or script to parse the contents of a file.<br>
 972       </td>
 973     </tr>
 974     <tr align="center">
 975       <td valign="top" colspan="2"><b>Entry options</b><br>
 976       </td>
 977     </tr>
 978     <tr>
 979       <td valign="top">Executable<br>
 980       </td>
 981       <td valign="top">The path to the executable; if no absolute path
 982 is given, the path as given in the PATH environment variable is searched.<br>
 983       <br>
 984 Any number of arguments can be passed by seperating them by spaces; if
 985 you're using a temporary file as the method to pass the contents of the
 986 file, it's path will be the last argument.<br>
 987       <br>
 988 When the program is executed, several environment variables are set to
 989 reflect the properties of the file being handled, they are:<br>
 990       <table cellpadding="2" cellspacing="2" border="0" width="100%">
 991         <tbody>
 992           <tr>
 993             <td valign="top">HTTP_METHOD - Method used to request the
 994 file.<br>
 995             </td>
 996           </tr>
 997           <tr>
 998             <td valign="top">HTTP_HOST - Host HTTP request was made to.<br>
 999             </td>
1000           </tr>
1001           <tr>
1002             <td valign="top">HTTP_FILE - File HTTP request was made for.<br>
1003             </td>
1004           </tr>
1005           <tr>
1006             <td valign="top">HTTP_PORT - Port HTTP request was made to.<br>
1007             </td>
1008           </tr>
1009           <tr>
1010             <td valign="top">IP - IP address of client making request.<br>
1011             </td>
1012           </tr>
1013         </tbody>
1014       </table>
1015       <br>
1016 Additionally, for every header received from the remote website and set
1017 by a client, an environment variable is set. All the environment
1018 variables for the server's headers start with SERVER_, and the client's
1019 start with CLIENT_; All '-' (dashes) in the header type are converted to
1020 '_' (underscores), and all characters are in uppercase.<br>
1021       <br>
1022 If an executable returns with a non-zero status code, the original
1023 content is returned.<br>
1024       </td>
1025     </tr>
1026     <tr>
1027       <td valign="top">Host<br>
1028       </td>
1029       <td valign="top">A regular expression matching the host's this
1030 entry applies to, leave blank to match everything.<br>
1031       </td>
1032     </tr>
1033     <tr>
1034       <td valign="top">File<br>
1035       </td>
1036       <td valign="top">A regular expression matching the file's this
1037 entry applies to, leave blank to match everything.<br>
1038       </td>
1039     </tr>
1040     <tr>
1041       <td valign="top">Mimetype<br>
1042       </td>
1043       <td valign="top">A regular expression matching the MIME-type's
1044 this entry applies to, leave blank to match everything.<br>
1045       </td>
1046     </tr>
1047     <tr>
1048       <td valign="top">Newmime<br>
1049       </td>
1050       <td valign="top">The MIME-type of the content returned from the
1051 external program, leave blank to have the original MIME-type preserved.<br>
1052       <br>
1053 If this is set to STDIN, the external program is expected to write
1054 "Content-type: &lt;mimetype&gt;" followed by 2 newlines as it's first
1055 output, where &lt;mimetype&gt; is the new MIME-type.<br>
1056       </td>
1057     </tr>
1058     <tr>
1059       <td valign="top">Type<br>
1060       </td>
1061       <td valign="top">The method which content is passed to the
1062 external program; if set to Pipe the content is piped to the program's
1063 STDIN, if set to File the content is stored in a temporary file and it's
1064 path is passed as the last argument.<br>
1065       </td>
1066     </tr>
1067   </tbody>
1068 </table>
1069 <span style="font-weight: bold;"><br>
1070 --- Keyword filtering ---<br>
1071 <br>
1072 </span>
1073 <table cellpadding="2" cellspacing="2" border="1"
1074  style="text-align: left; width: 100%;">
1075   <tbody>
1076     <tr align="center">
1077       <td style="vertical-align: top;" colspan="2"><span
1078  style="font-weight: bold;">Purpose</span><br>
1079       </td>
1080     </tr>
1081     <tr>
1082       <td style="vertical-align: top;" colspan="2">The keyword
1083 filtering feature allows you to block pages which may contain
1084 inappropiate content using a scoring system. When the host, file,
1085 mimetype, and keyword in an entry matches a file, it's score is added to
1086 the total score; when that total score exceeds the threshold, the page
1087 is deemed inappropiate and blocked.<br>
1088       </td>
1089     </tr>
1090     <tr align="center">
1091       <td style="vertical-align: top;" colspan="2"><span
1092  style="font-weight: bold;">Global options</span><br>
1093       </td>
1094     </tr>
1095     <tr>
1096       <td style="vertical-align: top;">Template<br>
1097       </td>
1098       <td style="vertical-align: top;">The template to send when a page
1099 exceeds the threshold.<br>
1100       </td>
1101     </tr>
1102     <tr>
1103       <td style="vertical-align: top;">Threshold<br>
1104       </td>
1105       <td style="vertical-align: top;">The number the total score must
1106 equal or exceed until it's blocked.<br>
1107       </td>
1108     </tr>
1109     <tr align="center">
1110       <td style="vertical-align: top;" colspan="2"><span
1111  style="font-weight: bold;">Entry options</span><br>
1112       </td>
1113     </tr>
1114     <tr>
1115       <td style="vertical-align: top;">Host<br>
1116       </td>
1117       <td style="vertical-align: top;">A regular expression matching
1118 the host's this entry appliesto, leave blank to match everything.<br>
1119       </td>
1120     </tr>
1121     <tr>
1122       <td style="vertical-align: top;">File<br>
1123       </td>
1124       <td style="vertical-align: top;">A regular expression matching
1125 the file's this entry applies to, leave blank to match everything.<br>
1126       </td>
1127     </tr>
1128     <tr>
1129       <td style="vertical-align: top;">Mimetype<br>
1130       </td>
1131       <td style="vertical-align: top;">A regular expression matching
1132 the mimetype's this entry applied to; it is highly advisable that you
1133 set this to something, otherwise all file's will be checked; if you're
1134 unsure, set this to "text/"<br>
1135       </td>
1136     </tr>
1137     <tr>
1138       <td style="vertical-align: top;">Keyword<br>
1139       </td>
1140       <td style="vertical-align: top;">A regular expression matching
1141 anything in the body of the document considered inappropiate, leave
1142 blank to match everything.<br>
1143       </td>
1144     </tr>
1145     <tr>
1146       <td style="vertical-align: top;">Score<br>
1147       </td>
1148       <td style="vertical-align: top;">The score this entry adds to the
1149 total score when it matches; this may be a positive or negative integer.<br>
1150       </td>
1151     </tr>
1152   </tbody>
1153 </table>
1154 <br>
1155 </div>
1156 <br>
1157 <div align="center"><b>Transparent proxying<br>
1158 <br>
1159 </b>
1160 <div align="left"><br>
1161 Middleman can be used to transparently proxy requets; to make use of
1162 this feature, you will need to use firewall software capable of
1163 forwarding connections. Configure the firewall to forward connections
1164 destined for port 80 to the proxy server; the proxy server will look at
1165 the Host header sent by the browser and use that to determine what host
1166 the request was originally intended for. This feature may not work for
1167 all browsers, sending the Host header is only required for HTTP 1.1,
1168 although most HTTP 1.0 clients send it anyways.<br>
1169 <br>
1170 If you're using iptables under Linux, the following command should do
1171 the job (replace interfaces and port to match your setup)<br>
1172 iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 80 -j REDIRECT
1173 --to-port 8080<br>
1174 <br>
1175 <div align="center"><b>Example external parser<br>
1176 <br>
1177 <br>
1178 </b>
1179 <div align="left">This is a trivial example of how to write an external
1180 parser; this will replace any page with the word "sex" in it with a
1181 warning message (shrug).<br>
1182 This should be used with the type set to "File", Mimetype set to
1183 "text/html", and Newmime set to "STDIN"<br>
1184 <br>
1185 --- SNIP ---<br>
1186 <div align="center">
1187 <div align="left">
1188 <pre>#!/bin/sh<br>if grep -i sex $1 &gt; /dev/null; then<br>    echo "Content-Type: text/html"<br>      echo ""<br>     echo "&lt;html&gt;&lt;head&gt;&lt;title&gt;Inappropiate content&lt;/title&gt;&lt;/head&gt;"<br> echo "&lt;body&gt;&lt;font size=6&gt;$HTTP_HOST$HTTP_FILE contains inappropiate content&lt;/font&gt;&lt;/body&gt;"<br>  echo "&lt;/html&gt;"<br>        exit 0<br>fi<br><br># Non-zero exit status returns original content<br>exit 1<br># Alternatively, you can send a Content-type header with the same MIME-type as the original document and cat the file (slower)<br>echo "Content-type: $SERVER_CONTENT_TYPE"<br>echo ""<br>cat $1<br></pre>
1189 </div>
1190 </div>
1191 </div>
1192 </div>
1193 <br>
1194 --- SNIP ---<br>
1195 <br>
1196 </div>
1197 </div>
1198 <br>
1199 <div align="center"><b>Frequently asked questions<br>
1200 <br>
1201 </b>
1202 <div align="left"><br>
1203 Q: I setup middleman to use an external parser, but it doesn't always
1204 work.<br>
1205 A: Middleman will refuse to buffer files in memory that exceed 512KB,
1206 this it to prevent unreasonable download times and memory exhaustion
1207 when downloading an extermely large file. This limit can be changed or
1208 removed by editing the BUFFERMAX setting in include/settings.h before
1209 compiling Middleman.<br>
1210 <br>
1211 Q: Some pages show strange numbers throughout the document, and it
1212 hangs when loading a page.<br>
1213 A: Middleman is an HTTP 1.1 proxy; some older browsers (such as
1214 netscape 4.x) will not work correctly with the proxy, the only solution
1215 is to upgrade your browser.<br>
1216 <br>
1217 Q: I get a "Bad response" error when loading a webpage that works
1218 without the proxy.<br>
1219 A: This probably means the webserver is using the old HTTP/0.9 protocol
1220 which doesn't require the webserver to send a header; there's no sane
1221 way to support this with the way Middleman is designed.<br>
1222 <br>
1223 Q: I keep getting "URL redirection limit exceeded" errors for a page
1224 while using the proxy.<br>
1225 A: The default configuration includes a redirect entry which bypasses
1226 link tracking scripts by redirecting any request which has a URL within
1227 the URL directly to that URL; i.e. requesting
1228 "http://www.somesite.com/redirect.pl?http://someothersite.com" will
1229 cause the proxy to send back a 302 redirect for
1230 "http://someothersite.com". In most cases this works as expected;
1231 however, on some sites, such as ones that make you go through a login
1232 process and have the URL you originally requested within the URL, this
1233 will not work. You can temporarily bypass this by prefixing
1234 "bypass[r].." to the URL, or permanently bypass it by adding a redirect
1235 entry above the link bypassing one with a URL pattern matching the host
1236 and no Redirect field.<br>
1237 <br>
1238 <br>
1239 <div align="center"><b>Reporting bugs<br>
1240 <br>
1241 </b>
1242 <div align="left">If you encounter any problems while using Middleman,
1243 please contact me. If the problem results in a crash, please follow
1244 these steps to help me debug the problem:<br>
1245 1) Recompile middleman using the --enable-debug option in the configure
1246 script<br>
1247 2) Type "ulimit -c unlimted" in your shell before running the proxy,
1248 this will cause middleman to dump a core file when it crashes.<br>
1249 3) Email me the compiled binary, core file, and configuration file you
1250 were using at the time. The last few log entires would also be helpful.<br>
1251 <br>
1252 <div align="center"><b>Feature requests<br>
1253 <br>
1254 </b>
1255 <div align="left">If you have any ideas on how Middleman could be
1256 improved, please email me (address at top)... I'll do my best to respond.</div>
1257 </div>
1258 </div>
1259 <div align="left"><br>
1260 </div>
1261 </div>
1262 </div>
1263 </div>
1264 </body>
1265 </html>