The global section gives access to configuration options that affect the overall operation of the proxy server.
Table 5-1. General options
Option | Type | Description |
---|---|---|
Hostname | String | The hostname of the proxy, this needs to be configured properly for CARP and Web interface requests through HTTP to work. |
Connection timeout | INT | The timeout in seconds to wait for a connection to be established before giving up. |
Header timeout | INT | The timeout in seconds to wait for a client to make the initial HTTP request. |
Keepalive timeout | INT | The timeout in seconds to wait for keepalive requests. |
Maximum buffer size | FILE_SIZE | The maximum size in bytes of files that are buffered and processed by the rewrite, keyword, and external features. |
Temporary directory | String | The directory temporary files are stored in. |
Web interface line length | INT | The maximum length of a string with no spaces until an explicit break is placed in it, this is needed since lines without spaces won't wrap in a table, causing formatting problems. |
CONNECT ports | PORT_RANGE_LIST | The ports outgoing CONNECT requests are allowed to be made to; |
Connection pool size | INT | The number of keep-alive connections to HTTP and FTP servers to keep in the connection pool; these connections will be shared between threads. |
Connection pool timeout | INT | The time in seconds a connection may remain in the connection pool before being removed. |
Always compress mimetype | String | A regular expression matching the MIME-types which should always be buffered and compressed even if they wouldn't be buffered otherwise. |
Compress outgoing | Boolean | Toggle gzip or deflate encoding of outgoing processed content if the client supports it. If the proxy server is running locally, it is recommended you disable this feature. |
Compress incoming | Boolean | This option will make Middleman attach an Accept-Encoding header that lets the Web server know we can accept gzip and deflate content encodings regardless of whether or not the browser making the request supports it; if the browser doesn't support it, it will be buffered and decompressed before sending. |
Add X-Forwarded-For header | Boolean | This option will add a header letting an upstream proxy or Web server know the IP address where the original request came from. |
Add Via header | Boolean | This option will add a header letting an upstream proxy or Web server know what proxy server the request passed through. |
Table 5-2. FTP options
Option | Type | Description |
---|---|---|
Passive mode | Boolean | Use passive mode for FTP transfers; this is useful if you are behind a firewall that prevents the FTP server from opening a connection to you. |
Timeout | INT | The timeout to wait for a response to commands sent to the FTP server. |
Anonymous login | String | The login to use when none is explicitly given in the URL. |
Anonymous password | String | The password to use when none is explicitly given in the URL. |
Sort order | Radio buttons | The order FTP directory listings are sorted. |
Sort field | Checkboxes | The field which FTP directory listings are sorted |
Table 5-3. DNSBL options
Option | Type | Description |
---|---|---|
Template | String | The template to send when domain is found to be blocked. |
Domain | String | The domain to prefix the domain being checked to; i.e. in.dnsbl.org will cause a lookup for bad.com.in.dnsbl.org to be made when a page from the bad.com domain is requested. |
Blocked IP addresses | IP_RANGE_LIST | A comma separated list of IP addresses that can be returned when doing the DNS lookup which will cause the page to be blocked. |
Table 5-4. Prefetch global options
Option | Type | Description |
---|---|---|
Threads | INT | The number of threads to run in the background prefetching files. Middleman needs to be restarted for this setting to take effect. |
Queue size | INT | The size of the prefetch queue. |
Table 5-5. Prefetch entry options
Option | Type | Description |
---|---|---|
Tag name | String | The HTML tag the attribute is in. |
Tag attribute | String | The HTML tag attribute holding the URL to be prefetched. |
Attribute pattern | String | A regular expression matching the attribute value this entry applies to. |
Maximum file size | FILE_SIZE | The maximum size of the prefetched file. |
Recursion level | INT | If the URL leads to another HTML page, this is the depth links will be followed. Setting to 0 causes links to be followed indefintely. |
The network section is used to configure general network settings. The configuration file must be saved and the proxy server has to be restarted before any changes take effect.
The profiles section allows groups of profiles to be enabled or disabled based on the URL being requested. This is useful to enable or disable groups of related entries in other sections together.
Table 5-7. Profiles options
Option | Type | Description |
---|---|---|
Protocol | String | A regular expression matching the protocol this entry applies to; leave empty to match everything. |
Host | String | A regular expression matching the host's this entry applies to; leave empty to match everything. |
File | String | A regular expression matching the file's this entry applies to; leave empty to match everything |
Mime type | String | A regular expression matching the MIME-type's this entry applies to; leave empty to match everything. MIME-type matching is done after receiving the server header, so it may only be used for certain features; header filtering, cache refresh policy, and cache store selection are done before the server header is received. |
Port range list | PORT_RANGE_LIST | A comma seperated list of ports or port ranges this entyr applies to. |
Added profiles | STRING_LIST | A comma separated list of profiles to add when this entry matches. |
Removed profiles | STRING_LIST | A comma separated list of profiles to remove when this entry matches. |
URL Command | STRING_LIST | A comma seperated list of URL commands which will activate this entry. If left empty, this entry is enabled regardless of which URL commands are used. |
The access feature is used to control who can access the proxy server, and to what extent.
Table 5-8. Access global options
Option | Type | Description |
---|---|---|
Policy | Radio buttons | Default action to take when no matching entry is found. |
Table 5-9. Access entry options
Option | Type | Description |
---|---|---|
IP Address | String | A regular expression matching the IP addresses this entry applies to, leaving blank will cause the entry to match everything. |
PAM authentication | Boolean | If this option is selected, clients will be required to authenticate with the proxy and PAM will be used to authenticate the username and password. This option will work only if the proxy is configured and compiled with PAM support. |
User name | String | 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. This option is a regular expression. |
Password | String | The client's password if the username field is used. |
Access | Checkboxes | A list of features that connections matching this entry are allowed to access, the options are:
|
Bypass | Checkboxes | A list of features which will by default be bypassed when making requests. |
The caching section is used to configure global cache options and to add/remove cache storage spaces.
Table 5-10. Cache global options
Option | Type | Description |
---|---|---|
Violate RFC | Boolean | This option will cause the proxy server to violate some rules in the HTTP RFC to help improve cache performance; specifically, when a website requests that the file not be cached with the “No-Cache” directive in the Cache-Control header, the proxy will cache it anyways but always validate it with an If-Modified-Since conditional request. |
Memory cache size | FILE_SIZE | The maximum size in bytes of the memory cache. |
Memory free extra | FILE_SIZE | The number of additional bytes to free up when the memory is cleaned. |
Minimum file size | FILE_SIZE | The minimum file size in bytes of any cached file. |
Maximum file size | FILE_SIZE | The maximum file size in bytes of any cached file; if set to 0, no maximum file size is imposed. |
Maximum wait size | FILE_SIZE | It's not possible with the current design for one thread to download a file being cached by another thread, but that thread can wait for the other to finish and then use it; this option will configure the maximum size the cache file can get before it stops waiting and transfers the file directly from the server. |
Prefetch window | INT | This option can be used to specify the time period after a file is prefetched in which it will be exempt from any refresh or expiry rules. |
ICP port | INT | The UDP port to listen for ICP packets on. |
ICP timeout | INT | The timeout in milliseconds for response ICP packets. |
Store balance method | Radio buttons | This option controls how the storage directory a file goes into is selected. Fill size will select the storage directory with the least total bytes used, Fill percent will select the storage directory with the lowest percentage of space used. |
Table 5-11. Cache store entry options
Option | Type | Description |
---|---|---|
Path | String | The directory where cached files are stored. |
Maximum disk size | FILE_SIZE | The amount of space that should be used to store cached files in this directory. |
Disk free extra | FILE_SIZE | When the cache is cleaned, this additional amount will be freed as well. This option can be useful to prevent the cache from getting evicted too often, which can hurt performance. |
Table 5-12. Cache refresh entry options
Option | Type | Description |
---|---|---|
Cachable | Boolean | Whether or not requests matching this entry are cached. |
Minimum age | UINT | The minimum age any file must be according to the Last-Modified header before it is cached. |
Maximum age | UINT | The maximum age of any cached file before it must be revalidated; this overrides any given expiry time. |
Revalidate age | UINT | The maximum age of any cached file which didn't include any headers that indicate when it should expire before it must be revalidated; if set to 0, all cached files whose expiry time is uncertain will be verified. If no "Last-Modified" header is received to calculate the percent of age freshness, the cached file is always revalidated. |
Last-Modified time factor | UINT | The percentage of time between the date given in the Last-Modified header and the current time a cached file will be considered fresh after downloading. |
Templates are used throughout Middleman as a replacement for pages which can't be displayed due to filtering, error, or other conditions.
Table 5-13. Templates global options
Option | Type | Description |
---|---|---|
Path | String | Location to look for templates in if no absolute path is given. |
Table 5-14. Templates entry options
Option | Type | Description |
---|---|---|
Name | String | 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:
|
File | String | The filename of the template |
Mime type | String | 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 | INT | The response code to use when sending the template, leave blank to use internal default. |
Type | Radio buttons | 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. |
Parsable | Boolean | If this option is selected, all variables in the template will be substituted. |
The mime feature allows you to filter content based on it's MIME-type.
Table 5-15. Mime global options
Option | Type | Description |
---|---|---|
Policy | Radio buttons | The action to take when no matching entry is found. |
Default template | String | 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. |
Table 5-16. Mime entry options
Option | Type | Description |
---|---|---|
Host | String | A regular expression matching the host's this entry applies to, leave blank to match everything. |
File | String | A regular expression matching the file's this entry applies to, leave blank to match everything. |
Mime type | String | A regular expression matching the MIME-type's this entry applies to, leave blank to matching everything. |
Template | String | The template to send when an entry matches, this has no purpose in entries with the action set to allow. |
The redirect feature allows you to redirect requests.
Table 5-17. Redirect entry options
Option | Type | Description |
---|---|---|
URL | String | A regular expression matching the URL's you wish to redirect; the URL will always be in the form "protocol://host/file" or "/file" for HTTP requests. |
Redirect | String | The URL to redirect to; it may contain back references to strings captured using parenthesis in the URL pattern. This can be in the form "protocol://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 back references. |
Port | INT | The port to redirect to; if left blank the same port the original request was made to is used. |
302 Redirect | Boolean | 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 | Checkboxes | Several options are available to control how the URL should be handled, they are:
|
Applies to | Radio buttons | 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. |
The forward feature allows you to selectively forward requests through another proxy or SOCKS4 firewall based on their URL.
Table 5-18. Forward global options
Option | Type | Description |
---|---|---|
Enable CARP | Boolean | Enable Cache Array Routing Protocol. |
Table 5-19. Forward entry options
Option | Type | Description |
---|---|---|
Proxy | String | 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. |
User name | String | The username to use if the proxy requires authentication. |
Password | String | The password to use if the proxy requires authentication. |
Domain | String | The NT domain when using the NTLM authentication protocol. |
Port | INT | The port number of the proxy to forward through. |
ICP Peer type | Radio buttons | The peering releationship of this proxy, see “Internet caching protocol” section below for further details. |
ICP Port | INT | The UDP port ICP packets are sent to. |
Type | Radio buttons | What type of proxy to forward through; can be HTTP, SOCKS4, or CONNECT. |
Applies to | Checkboxes | What type of requests are forwarded; can be HTTP and/or CONNECT (HTTPS) |
The header feature allows you to control what headers are passed from your browser to websites. In additional to the allow and deny actions in some other sections, there is an insert action which will add a new header onto the ones sent by your browser; for these entires, the Type and Value options are plain text.
Table 5-20. Header global options
Option | Type | Description |
---|---|---|
Policy | Radio buttons | The action to take when no matching entries are found. |
Table 5-21. Header entry options
Option | Type | Description |
---|---|---|
Type | String | A regular expression matching the header type's this entry applies to; leave blank to match everything (header's are in the form "Type: value"). |
Value | String | A regular expression matching the header value's this entry applies to; leave blank to match everything. |
Applies to | Checkboxes | This option is to select whether or not this entry applies to the server header, client header, or both. |
The rewrite feature allows you to use regular expressions to modify the contents of web pages, files, the client header, and server header.
Table 5-22. Rewrite entry options
Option | Type | Description |
---|---|---|
Mime type | String | A regular expression matching the MIME-type's this entry applies to. This must be filled with something, otherwise the rewrite rule will be applied to every downloaded file, which is almost certainly not what you want. To have it applied to web pages, fill this field with "text/html" |
Size | INT | The maximum size of the file this entry is allowed to match. -1 matches all files smaller than the maximum buffer size, 0 matches all files, and > 0 matches files up to that size. If a file is larger than the maximum buffer size, it will be partially buffered and the rest will be sent unprocessed. |
Pattern | String | A regular expression pattern matching the area of text inside the file to modify; if this is left blank, and the host, file, or mimetype options aren't, this will be the last entry matched for sites matching the host, file, and mimetype. |
Replace | Multiline string | The replacement text to use in place of the area of text matching the pattern; it may contain back references to strings captured using parenthesis in the pattern. A back reference to a captured string is in the form "$#", where # is a number from 1-9; "$0" will be replaced with the entire area of text matching the regular expression. Escape sequences may be used to represent unprintable characters, they are "\n" (newline), "\r" (carrier return), and "\t" (tab). To use a backslash as part of the replacement text, precede it with another backslash. |
Applies to | Checkboxes | This option is to select what the rewrite rule applies to; the options are:
|
The cookies feature allows you to choose which hosts your browser is allowed to send and receive cookies to and from.
Table 5-23. Cookie global options
Option | Type | Description |
---|---|---|
Policy | Radio buttons | The action to take when no matching entry is found. |
Table 5-24. Cookie entry options
Option | Type | Description |
---|---|---|
Expiry year range | Two integers | The cookie expiry year range this entry applies to. |
Expiry month range | Two strings | The cookie expiry month range this entry applies to. |
Expiry day range | Two integers | The cookie expiry day range this entry applies to. |
Expiry weekday range | Two strings | The cookie expiry weekday range this entry applies to. |
Expiry hour range | Two integers | The cookie expiry hour range this entry applies to. |
Expiry minute range | Two integers | The cookie expiry minute range this entry applies to. |
Domain | String | A regular expression matching the cookie's domain attribute this entry applies to. |
Path | String | A regular expression matching the cookie's path attribute this entry applies to. |
Direction | Radio buttons | The direction of the cookie this entry applies to; can be either in (Set-cookie sent by website), out (Cookie sent by browser), or both. |
Time match mode | Radio buttons | The direction of the cookie this entry applies to; can be either in (Set-cookie sent by website), out (Cookie sent by browser), or both. |
The external feature allows you to use any program or script to parse the contents of a file.
Table 5-25. External entry options
Option | Type | Description |
---|---|---|
Executable | String | The path to the executable; if no absolute path is given, the path as given in the PATH environment variable is searched. Any number of arguments can be passed by separating them by spaces; if you're using a temporary file as the method to pass the contents of the file, it's path will be the last argument. When the program is executed, several environment variables are set to reflect the properties of the file being handled, they are:
|
Mime type | String | A regular expression matching the MIME-type's this entry applies to, leave blank to match everything. |
Size | INT | The maximum size of the file this entry is allowed to match. -1 matches all files smaller than the maximum buffer size, 0 matches all files, and > 0 matches files up to that size. If a file is larger than the maximum buffer size, it will be partially buffered and the rest will be sent unprocessed. |
New mime type | String | The MIME-type of the content returned from the external program, leave blank to have the original MIME-type preserved. If this is set to STDIN, the external program is expected to write "Content-type: <mimetype>" followed by 2 newlines as it's first output, where <mimetype> is the new MIME-type. |
Type | Radio buttons | The method which content is passed to the external program; if set to Pipe the content is piped to the program's STDIN, if set to File the content is stored in a temporary file and it's path is passed as the last argument. |
The keyword filtering feature allows you to block pages which may contain inappropriate content using a scoring system. When the host, file, mimetype, and keyword in an entry matches a file, it's score is added to the total score; when that total score exceeds the threshold, the page is deemed inappropriate and blocked.
Table 5-26. Keyword global options
Option | Type | Description |
---|---|---|
Threshold | INT | The number the total score must equal or exceed until it's blocked. |
Template | String | The template to send when a page exceeds the threshold. |
Table 5-27. Keyword entry options
Option | Type | Description |
---|---|---|
Mime type | String | A regular expression matching the mimetype's this entry applied to; it is highly advisable that you set this to something, otherwise all file's will be checked; if you're unsure, set this to "text/" |
Size | INT | The maximum size of the file this entry is allowed to match. -1 matches all files smaller than the maximum buffer size, 0 matches all files, and > 0 matches files up to that size. If a file is larger than the maximum buffer size, it will be partially buffered and the rest will be sent unprocessed. |
Keyword | String | A regular expression matching anything in the body of the document considered inappropriate, leave blank to match everything. |
Score | INT | The score this entry adds to the total score when it matches; this may be a positive or negative integer. |
The limits feature allows access to the proxy server to be restricted based on date/time, bandwidth usage, and requests made. More than one entry may be allowed to match, in this case the last to match is used; this makes it possible for example to limit bandwidth usage between Monday and Friday to 1GB, and not allow more than 200MB per day.
Table 5-28. Limits entry options
Option | Type | Description |
---|---|---|
Action | Radio buttons | The action to take when this entry matches. If deny, any request falling into the specified time range is blocked, otherwise the request is allowed. When limiting transfered data or requests is desired, an allow action should be used which will then become a deny action when the limit is reached. |
Template | String | The template to send when this entry results in access being denied. The specified template is only sent if the page was blocked due to the time restrictions, 'maxbandwidth' and 'maxrequests' are used for excessive bandwidth or requests, respectively. |
Month range | Two strings | The range of months this entry applies to. |
Day range | Two integers | The range of days this entry applies to. |
Weekday range | Two strings | The range of weekdays this entry applies to. |
Hour range | Two integers | The hour range this entry applies to. |
Minute range | Two integers | The range of minutes this entry applies to. |
Byte transfer limit | UINT | The maximum number of bytes that may be downloaded by the proxy during the time span this entry matches. |
Current bytes | UINT | The current number of bytes transferred in this time span; this setting is not saved, reloading the configuration or restarting the proxy will reset it. |
Request limit | UINT | The maximum number of requests that may be made by a client during the time span this entry matches. |
Current requests | UINT | The current number of requests made in this time span; this setting is not saved, reloading the configuration or restarting the proxy will reset it. |
Time match mode | Radio buttons | The method used to match the time. Absolute will match the exact date/time, All ranges will match if the current time falls into every choses range. For example, with absolute selected with the weekday and time ranges respectively set to Monday-Friday, 8:00 to 17:00, the entry will match any time between 8am Monday and 5pm Friday; with all ranges selected the entry will match 8am to 5pm on any day between Monday and Friday. |
Flags | Checkboxes | The 'limit cache transfers' option will place bandwidth limits on transfers to the client that didn't result in any bandwidth from a website. |