Most of the configuration is made easy by the Web interface; however,
configuring the network settings will need to be done by manually
editing the configuration file. At the top of the included config.xml
you will see a section that looks simular to the following:
<network>
<listen>
<ip>127.0.0.1</ip>
<port>8080</port>
</listen>
</network>
Each <listen> section inside the <network> section has an
<ip> and <port> option, which should contain after them the
IP address and port number to listen on, respectively. You may leave out
the <ip> option to have Middleman listen on all interfaces.
Middleman, by default, can have up to 20 <listen> sections.
As mentioned above, all other configuration settings can be modified
through the Web interface. To access this, while using the proxy load
"http://mman" in your browser; when not using the proxy, the Web
interface is accessible by making a regular HTTP request for /mman to
the proxy's IP address and port.
Once you've loaded the Web interface, you will see a page with several
links available at the top.
The "Active connections" link will display a page showing all
connections currently being handled by the proxy.
The "DNS cache" link is for debugging purposes only, and will display
entries in the DNS cache.
The "Show headers" link will bring you to a page showing all the HTTP
headers your browser sends, and what they look like after being
filtered. Note: headers handled by Middleman aren't shown, this is to
avoid confusion.
The "Save settings" link will bring you to a page with a Filename
dialog where you can save all current settings, by default it will be
filled with the path to the configuration file given when the proxy
server was loaded.
The "Load settings" link will also bring you to a page with a Filename
dialog, as well as an "Overwrite" option. The overwrite option can be
used to select whether the settings contained in the configuration file
will overwrite all current settings or simply be added to them.
The "View log entries" link will bring you to a page showing recent
entries made to the logfile, and will allow you to search through them
using regular expressions. The log buffer can also be cleared from here,
as well as have it's size adjusted. The level of logging detail
available through the web interface is unaffected by the options given
in the command line, and will always be all log entires with the
exception of debug messages.
The "Config" link will bring you to a page where all configuration
settings can be accessed. On the main page you will see a dialog with a
drop down list containing the name of each section, as well as a table
with a list lf each section and an enable/disable radio button beside
it; this can be used to quickly enable/disable a feature if it's causing
problems with a website.
When you select an item in the drop down list and click on the submit
button, you will be brough to a page containing a dialog at the top as
well as a list of entries for that section below, with the exception of
the network section, which is read-only. The dialog at the top will
always contain an "add" link, which can be used to add an additonal
entry to the section, and in some cases will have several other options
which will be explained below. Each entry at the bottom has an "Edit",
"Delete", "Up", "Down", "Top", and "Bottom" link. The edit link will
bring you to a dialog where you can edit that specific entry, the delete
link will remove it from the section. The "Up" and "Down" links allow
you to change the order of the entries, this is important in cases
where more than one entry can match the same thing. The "Top" and
"Bottom" links can be used to move the entry to the very top or bottom
of the list.
All entries for all sections have an "Enabled" option which allows you
to disable a specific entry, as well as a "Comment" field that can be
used to store a description of what the entries purpose is.
Several sections follow an allow/deny/policy model; for these sections,
each entry has an action option which will specify what happens when it
is found to match. If no matching entry is found, the action the policy
is set to will be taken. It is important to remember that all entries
with an action opposite to the policy are searched first, and if nothing
is found the entries with an action the same as the policy are not
searched. So, for example, if the policy for the access section is set
to "allow", and no entries with a "deny" action are found matching the
connection, none of the entries with an "allow" action are looked at, so
any access limitations specified in the allow entry are ignored.
The tables below will describe all the options available in each
section and the entries within them.
--- Access section ---
Purpose
|
The access feature is used to
control who can access the proxy server, and to what extent. |
Global options
|
Policy
|
Default action to take when no matching entry is
found. |
Entry options
|
IP Address
|
A regular expression matching the IP
addresses this entry applies to, leaving blank will cause the entry to
match everything. |
Username
|
If this field is not empty,
clients matching this entry will be required to authenticate with the
proxy server. There can be more than one entry matching the same IP
address, in which case the one matching the username/password send by
the browser is used.
|
Password
|
The client's password if the
username field is used.
|
Access
|
A list of features connections
matching this entry are allowed to access, the options are: |
Web interface - Access to all of the web
interface (access to /mman/template/<template name> is always
allowed regardless of this) |
Proxy requests - Allowed to make regular
proxy requests |
CONNECT Requests - Allowed to make CONNECT
requests |
Transparing proxying - Allowed to make
transparent proxy requests (must be allowed to make HTTP requests as
well) |
HTTP Requests - Allowed to make regular
HTTP requests to proxy (for Web interface and redirected requests)
|
Allow bypassing - Allows features to be
bypassed by prefixing with URL command |
|
Bypass
|
A list of features which will by default be
bypassed when making requests. |
|
|
--- Templates section ---
Purpose
|
Templates are used throughout
Middleman as a replacement for pages which can't be displayed due to
filtering, error, or other condtions. |
Global options
|
Path
|
Location to look for templates in if no absolute
path is given. |
Entry options
|
Name
|
The name of the template, this is used in
other sections to reference it. It may also be one of the following to
replace internal error messages: |
blocked - Page blocked |
nodns - DNS lookup failed |
badrequest - Malformed HTTP header from
client |
badresponse - Malformed
HTTP header from server
|
nofile - File not found |
noconnect - Connection failed |
noaccess - Access denied |
badprotocol - Protocol not implemented |
badauth - Authorization failed (when
forwarding through SOCKS4)
|
|
There are 3 built-in templates that can be
used: tinygif (a 1x1 transparent gif image), checkedgif (a 4x4 grey and
transparent checkered pattern), and tinyswf (an emtpy flash animation). |
|
You can override the content sent by a
website for certain response codes by making a template with a numerical
name the same as the response code.
|
|
There are several variables that can
be used in templates which will be replaced with information about the
request currently being handled, they are:
|
$HTTP_METHOD - Method used to
request file
|
$HTTP_HOST - Host HTTP request was
made to.
|
$HTTP_FILE - File HTTP request was
made for.
|
$HTTP_PORT - Port HTTP request was
made to.
|
$IP - IP address of client making
request.
|
|
|
Templates can be accessed directly by
loading "http://mman/template/<template name>".
|
|
File
|
The filename of the template |
Mimetype
|
The MIME-type of the template. When using an
executable, this can be set to STDIN to have the MIME-type extracted
from a "Content-type" header sent by the program, this will be explained
in greater depth below. |
Response code |
The response code to use when sending the
template, leave blank to use internal default. |
Type
|
Template type, either File or Executable. If
executable is choses, the file is executed and whatever it writes on
STDOUT is sent as the template. Several environment variables are set
for the executable to use, they will be explained further below in the
external section. |
--- MIME section ---
Purpose
|
The mime feature allows you to
filter content based on it's MIME-type. |
Global options
|
Policy
|
The action to take when no matching entry is
found. |
Default template
|
The template to send for blocked MIME-types if
the template option is left blank for the matching entry, or if no
matching entry is found but the policy is deny. |
Entry options
|
Host
|
A regular expression matching the host's this
entry applies to, leave blank to match everything. |
File
|
A regular expression matching the file's this
entry applies to, leave blank to match everything. |
Mimetype
|
A regular expression matching the MIME-type's
this entry applies to, leave blank to matching everything. |
Template
|
The template to send when an entry matches, this
has no purpose in entries with the action set to allow. |
--- Redirect section ---
Purpose
|
The redirect feature allows you to
redirect requests. |
Entry options
|
URL
|
A regular expression matching the URL's you wish
to redirect; the URL will always be in the form "host/file" or "/file"
for HTTP requests. |
Redirect
|
The URL to redirect to; it may contain
backreferences to strings captured using parenthesis in the URL pattern.
This can be in the form "host/file", or "/file" if you wish to send a
relative URL when redirecting a URL in the Location: header. If this
option is left blank, no action will be taken against requests matching
the URL.
See the rewrite section for additional notes on using regular
expressions with backreferences.
|
Port
|
The port to redirect to; if left blank the same
port the original request was made to is used.
|
302 Redirect
|
If yes, a 302 redirect is issued; otherwise the
new host is connected to directly and the new file is requested. A 302
redirect should always be used when possible to ensure relative links
and images are correct. |
Options
|
Several options are available to control
how the URL should be handled, they are:
|
Encode URL - Encode the new URL.
|
Decode URL before - Decode the URL before
attempting to match it with the regular expression
|
Decode URL after - Decode the new URL
after matching.
|
|
Applies to
|
This option is to choose whether the redirection
applies to requested URL's, the Location header when a remote site sends
a 302 redirect, or both.
|
--- Forward section ---
Purpose
|
The forward feature allows you to
selectively forward requests through another proxy or SOCKS4 firewall
based on their URL.
|
Entry options
|
Host
|
A regular expression matching the host's you
wish to have requests forwarded for, leave blank to match everything.
|
File
|
A regular expression matching the file's you
wish to have requests forwarded for, leave blank to match everything.
|
Proxy
|
The hostname or IP address of the proxy to
forward through; if this is left blank, and the host or file options
aren't, no action will be taken for requests matching the host and file.
|
Username
|
The username to use if the proxy requires
authentication.
|
Password
|
The password to use if the proxy requires
authentication.
|
Domain
|
The NT domain when using the NTLM authentication
protocol.
|
Port
|
The port number of the proxy to forward through.
|
Type
|
What type of proxy to forward through; can be
HTTP or SOCKS4
|
Applies to
|
What type of requests are forwarded; can be HTTP
and/or CONNECT (HTTPS)
|