SQUID-GW(8)

NAME
squid-gw - http proxy

SYNOPSIS
squid-gw [ -daemon <port> ] [ -fastdaemon [<host>:]<port> ] [ -pf <pidfile> ] [ -as <tag> ]

DESCRIPTION
The Firewall Toolkit squid-gw proxy is a HTTP proxy which forwards all requests to another HTTP proxy like Squid and provides configurable access control, authentication and logging mechanisms. The basic design policy of squid-gw is to reject anything which is not explicitely allowed. For instance, any HTTP headers squid-gw does not know about are removed. In particular, HTML documents are parsed and completely rewritten into a form which all browsers should understand and treat the same way. Thus, it should not be possible to trick the browser into executing JavaScript by exploiting differences between the way the firewall and the browser parse HTML. However, there are too many places in which web browsers interpret the input as JavaScript (style sheets!), so it is not guaranteed that JavaScript can be completely blocked. (The syntax of the generated HTML is described in html.c. Note that you can configure squid-gw to deviate from that syntax. Better don't do that.)

You can configure the proxy to allow requests and define specific policies based on:

•   source IP address

•   source host name

•   destination IP address

•   destination host name

•   browser identification

•   url pattern

•   HTTP method

and selectively define response handling for:

•   Content types (MIME and heuristically detected)

•   HTTP headers

•   HTML syntax compliance

•   HTML attributes

•   Meta attributes

•   Javascript and other scripts

•   Java

•   ActiveX objects

•   Hyperlink contents

•   Cookies

•   Embedded content

•   Style sheets

All packets, and therefore all application requests go to the firewall. On the firewall, the http proxy software relays information from one side of the firewall to the other. The proxy prevents the applications on outside networks from talking directly with the applications on your inside network, and vice versa. No IP packets pass from one side of the firewall to the other. All data are passed at the application level.

The http proxy (squid-gw) generally runs as a daemon (invoked from system startup script, p.e. /etc/rc.local) and listens for requests on the specified port (tcp/8080 or tcp/3128, as indicated in /etc/services ,are reasonable defaults). Whenever the system receives an http request on this port, the http proxy checks its configuration information (in the netperm-table) and determines whether the initiating host has permission to use http. If the host has permission, the proxy authenticates the user (if required), logs the transaction and passes the request to the destination host. If the host does not have permission, the proxy logs the connection attempt and displays an error message.

The proxy may also be invoked from tcp/ip "superserver" (inetd or xinetd). -daemon parameter should be omitted in this case.

OPTIONS

  Command Line Options
The http proxy recognizes the following command line options (whether started from the command line or from within /etc/rc.local):

-daemon port
    Indicates that the http proxy runs as a daemon, and the port (name or number) on which the http proxy listens. When -daemon option is used, configuration is being read from netperm-table for every new connection accepted by proxy.

    port Specifies either a numeric id or symbolic name from the /etc/services file.

-fastdaemon [host:]port
    Indicates that the http proxy runs as a daemon, the IP address (optional) and the port (name or number) on which the http proxy listens. When -fastdaemon option is used, configuration is being read from netperm-table once the daemon starts or if SIGHUP is received.

-as tag
    Changes default application tag for netperm-table from "squid-gw" to any given string.

-pf pidfile
    Specifies a file name where daemon stores master process PID.

  Configuration Options
The http proxy reads configuration rules from the /usr/local/etc/netperm-table. It reads all rules using the squid-gw and * (wildcard) keywords.

Additionally, you can define configuration classes and assign them to individual clients based on IP address or browser. For configuration class "foo", squid-gw reads all rules using the "squid-gw-foo" and "*" keywords. Some attributes should be used only in the global configuration of squid-gw. Note that netperm-table must be readable by the user ID and group ID configured with the userid and groupid attributes; otherwise, configuration classes won't work.

The http proxy reads the netperm-table from top to bottom. If there are multiple rules in the table that could apply for a particular attribute, the http proxy uses the first one that it finds. See netperm-table(5) for a more complete explanation of netperm-table syntax and precedence.

Configuration classes are applied in the following sequence:

    1. Global configuration

    2. Client-specific class from "hosts" attribute

    3. Destination-specific class from "destinations" attribute

    4. Client-specific class from "browsers" attribute

By default, later classes override values provided by earlier classes, that is, browsers classes override destinations classes which in turn override hosts classes which in turn override the global configuration.

However, for some attributes, you can specify a level by using the -force option. Values provided by higher levels always override values provided by lower levels, no matter in what sequence the values are provided. For values of the same level, the sequence matters as described above. Each occurrence of the -force option increases the level of the succeeding values of the line by one. The default level is zero.

Suppose that you want to enable JavaScript for certain browsers ( User-Agent: SafeBrowser ). For certain other browsers ( User-Agent: GoodBrowser ), you want to enable JavaScript only when visiting a certain site ( http://safesite ). For all other browsers, you want to disable JavaScript. The following configuration will implement that policy:

    squid-gw:              block javascript
    squid-gw:              destinations http://safesite  -class safesite
    squid-gw:              destinations *
    squid-gw-safesite:     allow javascript
    squid-gw:              browsers SafeBrowser -class safebrowser
    squid-gw:              browsers GoodBrowser
    squid-gw:              browsers *           -class otherbrowser
    squid-gw-safebrowser:  allow -force javascript
    squid-gw-otherbrowser: block -force javascript

This configuration has been written in a way which does not depend on the sequence in which the classes are applied (except for the global configuration). If there is a site for which you want to block JavaScript even for SafeBrowser, just insert

    squid-gw:              destinations http://evilsite  -class evilsite

before the destinations * line and insert

    squid-gw-evilsite:     block -force -force javascript

anywhere.

As the browsers and destinations attributes can be used for global configuration only, not for configuration classes, the -hosts option has been provided for these attributes to be able to implement a policy like the above but depending on the _client_ address instead of the _destination_ address. See `Host patterns' for details.

  Global configuration
The http proxy recognizes the following attributes for global configuration:

browsers browser.. [-class class] [-hosts client-host..] [-authall]
    Specify access permissions based on the value of the User-Agent HTTP header field (that is, based on the (pretended) type of the browser). If there is no User-Agent HTTP header field, squid-gw pretends that the value is no-user-agent (for the GET, HEAD, and POST request methods) or no-connect-user-agent (for the CONNECT request method). The browsers attribute comes in two flavours: permit-browsers for permitting access for matching browsers and deny-browsers for denying access for matching browsers. browsers is equivalent to permit-browsers . If there are multiple browsers lines, all of them will be read, stopping at the first matching line. If the -class option is used, all specified configuration classes will also be read for attributes, overriding the global configuration. If at least one -hosts option is used, the client must match the -hosts options for the rule line to take effect, see chapter `Host patterns'. If the client does not match, the rule line will be ignored and squid-gw will try the next line. If there is no matching line, access will be denied. The -class option is useless for deny-browsers . browser can contain * to match any sequence of characters. Letter case is ignored. Don't forget to use quotes if browser contains blanks!

    -authall enables proxy authentication via authsrv. Note that you can not use challenge/response authentication protocols with http directly; use SSO agent for strong authentication.

Example:

    squid-gw: permit-browsers Wget* -class wget
    squid-gw: deny-browsers no-user-agent no-connect-user-agent
    squid-gw: permit-browsers "*"

The second line denies access if the User-Agent line is missing, except for a test machine called test.my.domain.

connect host[:port].. [-ipaddr address.. ] [-delay seconds] [-message message] [-hosts client-host..]
    Specify access permissions for https (SSL) based on the destination, that is, on the destination host. (See the destinations attribute for access permissions for plain HTTP URLs.) The connect attribute comes in two flavours: permit-connect for permitting access for matching destinations and deny-connect for denying access for matching destinations. connect is equivalent to permit-connect. If there are multiple connect lines, all of them will be read, stopping at the first matching line. If there is no matching line, access will be denied.

    For a connect line to match, all of the following conditions must be met: at least one host and its port match the destination address; if -ipaddr is used, at least one address matches the destination address; if -hosts is used, at least one client-host matches the client address. There must be at least one host , which will be matched against the hostname (or IP address) specified by the client (i.e., the host to which a tunnelled connection is requested). The character * in host matches any number of characters, including zero characters. If the port number is omitted, 443 (https/SSL) will be assumed. If * is specified for port (not recommended), any port number will match.

    If -ipaddr is used, at least one address must match an IP address of the host requested by the client. You can use * in address. Note that using -ipaddr turns host mostly into a comment (except for the port number). If you want to match by IP address only, just use * as host:

        squid-gw: permit-connect * -ipaddr 1.2.3.4

    As address doesn't include a port number, the port number is specified by port:

        squid-gw: permit-connect *:5555 -ipaddr 1.2.3.4

    It is highly recommended to use -ipaddr to make it harder for attackers to redirect connections.

    The -delay option can be used to slow down access to sites which are not required for work.

    For deny-connect, you can define the error message with the -message option. If no -message option is given, the message will be 'Forbidden' The -delay option can be used to cause a delay before sending the response.

    If at least one -hosts option is used, the client must match the -hosts options for the rule line to take effect, see chapter `Host patterns'. If the client does not match, the rule line will be ignored and squid-gw will try the next line.

    IMPORTANT: You should permit CONNECT only to trusted sites, not to the Internet at large. squid-gw doesn't perform any content filtering for CONNECT! You cannot block ActiveX, Java, and JavaScript!

Example:

    squid-gw: connect www.example.com -ipaddr 1.2.3.4 1.2.3.5

This line grants SSL access (port 443) to www.example.com if (and only if) that hostname resolves to IP address 1.2.3.4 or 1.2.3.5.

destinations [method] url-pattern.. [-class class] [-delay seconds] [-message message ] [-redir url] [-hosts client-host..] [-authall]
    Specify access permissions based on the destination, that is, on the requested URL (for the GET, HEAD, and POST request methods; see the B connect attribute for the CONNECT request method.) The destinations attribute comes in two flavours: permit-destinations for permitting access for matching destinations and deny-destinations for denying access for matching destinations. destinations is equivalent to permit-destinations. If there are multiple destinations lines, all of them will be read, stopping at the first matching line. If there is no matching line, access will be permitted(!).

    For permit-destinations, you can specify configurations classes with the -class option: all configuration classes specified for the first matching permit-destinations line will be read for attributes, overriding the global configuration. The -delay option can be used to slow down access to sites which are not required for work. The -class option is ignored for deny-destinations.

    For deny-destinations, you can define the error message with the -message option. If no -message option is given, the message will be 'Forbidden'. Alternatively, you can redirect the request to another URL by using the -redir option. This can be used for producing the local conditions of use. The URL should point to an internal web server; to avoid recursion, the URL must not match a deny-destinations rule which uses the -redir option. The -delay option can be used to cause a delay before sending the response. method is one of "GET", "HEAD", and "POST" (WebDAV methods are not supported at the moment). The line is considered only if the request method is method. If method is omitted (that is, the first word is not one of "GET", "HEAD", and "POST"), the line applies to all request methods. Note that upper-case letters must be used for method.

    If at least one -hosts option is used, the client must match the -hosts options for the rule line to take effect, see chapter `Host patterns'. If the client does not match, the rule line will be ignored and squid-gw will try the next line.

    See chapter `URL patterns' for details on url-pattern.

    -authall enables proxy authentication via authsrv. Note that you can not use challenge/response authentication protocols with http directly; use SSO agent for strong authentication.

    IMPORTANT: You cannot rely on deny-destinations for prohibiting access to certain sites -- there are too many ways for working around such restrictions! However, it's good enough for blocking ads and other unwanted stuff.

Example:

    squid-gw: deny-destinations http*://*.*.*.*
    squid-gw: deny-destinations http*:*/chat*?* -message "Don't chat!"
    squid-gw: deny-destinations POST http*:*/chat* -message "Don't chat!"
    squid-gw: deny-destinations *:*sex* -redir "http://int-www/use.html"
    squid-gw: destinations http://www.myowndomain.com
    squid-gw: destinations * -class notsafe -delay 1
    squid-gw-notsafe: block -force java javascript object

Explanation: The first line denies access if an IP address is given as host. All serious web sites should be accessible by name.

The next two lines attempt to prevent users from chatting: The first line disables all URLs which contain "/chat" in the path and which contain a query (that's the part starting with "?"). The second line disables POST requests to URLs which contain "/chat" in the path. As there's no host part, this applies to all web servers. Note that we allow a GET request to, say, "http://foo.bar/icons/chat.gif" (there's no query part).

The third line is an attempt at reminding users of local conditions of Internet use.

The last three lines block Java, JavaScript, and ActiveX for all sites but www.myowndomain.com.

hosts host-pattern [host-pattern...] [-class class]
    Specify access permissions for clients based on IP address. The hosts attribute comes in two flavours: permit-hosts for permitting access for matching hosts and deny-hosts for denying access for matching hosts. hosts is equivalent to permit-hosts. If there are multiple hosts lines, all of them will be read, stopping at the first matching line. If the -class option is used, all specified configuration classes will also be read for attributes, overriding the global configuration. The -class option is useless for deny-hosts. See also the -hosts option of the browsers and destinations attributes.

    -authall enables proxy authentication via authsrv. Note that you can not use challenge/response authentication protocols with http directly; use SSO agent for strong authentication.

Example:

    squid-gw: permit-hosts 199.99.99.*
    squid-gw: permit-hosts 127.0.0.1 -class local
    squid-gw: deny-hosts 199.99.99.1

href url-pattern
    Specify what URLs are allowed in HTML attributes such as HREF and SRC which take an URL as value. The href attribute comes in two flavours: permit-href for permitting matching URLs and deny-href for rejecting matching URLs. href is equivalent to permit-href. If there are multiple href lines, all of them will be read, stopping at the first matching line. If there is no matching line for an URL, the URL will be rejected. As there is no default value, configuring href is required to enable hyperlinks. The main purpose of href is to prevent browsers from accessing local services:

        <img src="http://localhost:19">

    Unfortunately, the url-pattern syntax is not yet powerful enough. For controlling access to external WWW sites, you should use destinations instead of href.

directory directory
    Specifies the directory that the http proxy makes its root directory before providing service.

groupid group
    Specifies the name of the group the http proxy uses when running.

    group
        Specifies either a name or numeric id from the /etc/group file.

timeout seconds
    Specifies the number of seconds the http proxy is idle (with no network activity) before disconnecting

userid user
    Specifies the user ID the proxy uses when running.

    user
        Specifies either a name or numeric id from the /etc/passwd file.

  Configuration classes
squid-gw understands the following attributes for global configuration and for configuration classes:

allow what..

block what..
    By default, squid-gw blocks (filters) anything it considers dangerous. You can change the blocking policy of squid-gw by using the allow and block attributes. Only the first allow line is read and only the first block line is read. The following keywords are available for what:

    •
        cookies    Cookies

    •
        embed    <EMBED> HTML tag

    •
        java    Java applets (<APPLET> HTML tag)

    •
        javascript    JavaScript (and other) scripts

    •
        object    ActiveX objects (<OBJECT> HTML tag)

    •
        style    Style sheets

    Moreover, the -force option can be used for assigning a level to the values following that option.

    To enable JavaScript, you also have to enable javascript: in HREF attributes, see href . See also script . To enable ActiveX, you also have to enable clsid: in HREF attributes.

Example:

    squid-gw-nofilter: allow cookies java javascript object

Note that there are other ways than cookies to track users. For instance, user-specific information can be encoded in URLs.

Note that there's no point in blocking Java and ActiveX if you allow JavaScript as JavaScript can be used to build HTML pages on the fly.

Note that for recent web browsers, allowing style sheets means allowing JavaScript (which in turns means allowing ActiveX)! A future version of squid-gw may attempt to filter JavaScript from style sheets.

auto-html-limit limit
    Microsoft Internet Explorer doesn't strictly pay attention to Content-Type: it treats anything which has <HTML>, <HEAD>, or <BODY> near the beginning as HTML document. "Near the beginning" means that these tags can be preceded by up to 196 arbitrary bytes. This brain damage enables bad guys to bypass HTML filtering just by using any Content-Type different from text/html. Therefore, squid-gw looks at the first limit bytes of any HTTP body received from the server, no matter what Content-Type is received. If it finds "<HTML", "<HEAD", or "<BODY" within the first limit bytes, HTML filtering will be applied. Of course, HTML rewriting will break plain text files (text/plain) and binary files (e.g., image/gif) which happen to contain these bytes near the beginning. Note that some ZIP files contain HTML markup in the ZIP comment -- MSIE will display those ZIP files as HTML... If you are sure that nobody uses MSIE, you can prevent squid-gw from scanning for "<HTML" etc. by configuring

        squid-gw: auto-html-limit 0

    Of course, you can use configuration classes to make the value of auto-html-limit depend on the browser. The default value is 256; the smallest value suitable for MSIE (according to limited testing with MSIE 3.0 for Windows 95) seems to be 196+5 = 201. You can use values up to 4096. Of course, there is no guarantee that this prevents MSIE from interpreting certain bodies as HTML. If you find out more about this MSIE brain damage, please tell the author of squid-gw. The set of strings to search for can be changed in the source code only for now (auto_html_tags in http.c).

    The body portion of the same size is used for other content-type heuristics.

client-timeout timeout
    Define the number of seconds squid-gw is idle (without network activity) before disconnecting from the client. The default value is 2 hours (PROXY_TIMEOUT in firewall.h). Only the first client-timeout line is read. For the tunnelled connection of the CONNECT request method, client-timeout is ignored and server-timeout applies to both the client and the server.

Example:

    squid-gw: client-timeout 300

content-type type/subtype.. [-milter filter-socket..]
    Specify content type permissions. The content-type attribute comes in two flavours: permit-content-type for permitting content types and specifying filtering rules and deny-content-type for denying access. content-type is equivalent to permit-content-type. If there are multiple contnent-type lines, all of them will be read, stopping at the first matching line. If there is no matching line, content will be permitted(!). Each http response is compared two times: first as declared content type (one from http header) and second as detected by heuristics. If any of those is denied, the whole response is filtered out. If there is a filter(s) specified, filter lists are being merged for declared and detected content types. The filter-socket specifies content inspection server ( unix:/domain-path or inet:port@host syntax).

cookies mode
    Define how to parse cookies. Only the first cookies line is read. There are four possible values for mode:

    •   netscape relaxed parsing as in Netscape's cookie spec

    •   netscape-quote relaxed parsing, quote non-strict values

    •   nocheck don't parse cookies at all

    •   rfc2109 strict parsing according to RFC 2109

    At this time, I have not yet encountered any HTTP server which uses RFC 2109 syntax for cookies. Therefore, the default value is netscape .

Example:

    squid-gw: cookies nocheck

drop-meta-content-type [-force].. on

drop-meta-content-type [-force].. off
    You can use this attribute tell squid-gw to drop any META tags having HTTP-EQUIV=Content-Type. Only the first drop-meta-content-type line is read.

    The default setting is off . Moreover, the -force option can be used for assigning a level to the value following that option.

html-attribute-length limit
    Limit the length of the attribute values to limit octets. The default value is 1024 (cf. RFC 1866). However, there are HTML documents which use longer attribute values. Note that setting limit very high wastes lots of memory.

Example:

    squid-gw: html-attribute-length 32768

html-attributes type:policy[/log]
    Configure how to handle suspect attributes of tags in HTML documents (e.g., "<A HREF="javascript:") received from the server. If there are multiple html-attributes lines, all of them will be read. policy applies to attributes classified as type. If /log is given, squid-gw will log any attribute classified as type. The following keywords are available for type:

    •   alphanumeric unknown attribute with a value which consists solely of characters a-z, A-Z, and 0-9 and whose name does not start with on

    •   dangerous dangerous attribute

    •   novalue unknown attribute without value and whose name does not start with on )

    •   on unknown attribute whose name starts with on

    •   unknown unknown attribute

    The classification of some attributes can be configured (see allow ), the classification of the other attributes can be changed in the source code only. Currently, squid-gw knows about HTML 2.0, HTML 3.2, HTML 4.0 (draft of 1997-07-08), some Netscape and Microsoft extensions, and some common typos and other errors. You might want to log unknown attributes to be able to add them to the table of known attributes (and reporting them to the author of squid-gw). The following keywords are available for policy:

    •   copy don't remove the attribute [ANOU]

    •   drop completely remove the attribute [ADNOU]

    •   prefix prefix the attribute name ("REMOVED-foobar") [ADNOU]

    (The letters in brackets indicate for which type the keyword can be used.) It is not recommended to use on:copy or unknown:copy.

    Any type not listed in the attribute is not changed. The default setting is

        alphanumeric:prefix
        dangerous:prefix
        novalue:copy
        on:prefix/log
        unknown:prefix

Example:

    squid-gw: html-attributes dangerous:prefix/log

html-filter [-force].. on

html-filter [-force].. off
    By default, squid-gw filters HTML documents. However, you can configure squid-gw to pass through bodies of Content-Type text/html unmodified. This will disable all HTML filtering such as removal of ActiveX, Java, and JavaScript. Only the first html-filter line is read.

Example:

    squid-gw: browsers Wget* -class wget -hosts 10.0.0.1 squid-gw-wget: html-filter off

These rules turn off HTML filtering for Wget on client 10.0.0.1 only.

html-meta type:policy[/log]
    Configure how to handle suspect META tags in HTML documents received from the server. If there are multiple html-meta lines, all of them will be read. policy applies to META tags classified as type. If /log is given, squid-gw will log any META tag classified as type. The following keywords are available for type:

    •   unknown unknown name (e.g., "<meta name=foo content=bar>")

    Note that unknown applies only to META tags with a "NAME" attribute; it does not apply to META tags with an "HTTP-EQUIV" attribute which are always considered dangerous unless known to be benign; handling of unknown "HTTP-EQUIV" META tags is controlled by html-tags dangerous (which see).

    The set of unknown names can be changed in the source code (html-meta.tab) only. Note that there is not much point in logging unknown names as web page authors and authoring tools invent way too many names of their own. The following keywords are available for policy:

    •   comment replace with comment [U]

    •   copy don't remove the tag [U]

    •   drop completely remove the tag [U]

    •   escape escape the tag ("&amp;foobar&gt;") [U]

    •   prefix prefix the tag name ("<REMOVED-foobar>") [U]

        (The letters in brackets indicate for which type the keyword can be used.) It is not recommended to use unknown:copy .

        Any type not listed in the attribute is not changed. The default setting is

            unknown:prefix

html-references type:policy[/log]
    Configure how to handle suspect numeric character references ("&#500;") and entity references ("&foobar;") in HTML documents received from the server. If there are multiple html-references lines, all of them will be read. policy applies to references classified as type. If /log is given, squid-gw will log any reference classified as type. The following keywords are available for type:

    •   unknown unknown references (e.g., "&foobar;")

    The classification of references can be changed in the source code only. Currently, squid-gw knows about HTML and ISO-Latin-1 entity references. Numeric character references are classified by value: 0-255 are known, 256-65535 are unknown, 65536 and greater are invalid. The following keywords are available for policy:

    •   copy don't remove the reference [U]

    •   drop completely remove the reference [U]

    •   escape escape the reference ("&amp;foobar;") [U]

        (The letters in brackets indicate for which type the keyword can be used.) For security, it is not recommended to use unknown:copy . Note that unknown:drop is a bad idea as a lot of HTML documents to not properly escape "&", in particular in URLs ("/cgi-bin/foobar?a=b&c=d").

        The default setting is unknown:escape . Any type not listed in the attribute is not changed.

html-tags type:policy[/log]
    Configure how to handle suspect tags ("<FOOBAR>") in HTML documents received from the server. If there are multiple html-tags lines, all of them will be read. policy applies to tags classified as type. If /log is given, squid-gw will log any tag classified as type. The following keywords are available for type:

    •   dangerous dangerous tag (e.g., "<APPLET>" when blocking Java)

    •   invalid invalid tag (e.g., "<FOOBAR%>")

    •   unknown unknown tag (e.g., "<foobar>")

    The classification of some tags can be configured (see allow ), the classification of the other tags can be changed in the source code only. Currently, squid-gw knows about HTML 2.0, HTML 3.2, HTML 4.0 (draft of 1997-07-08) and some Netscape and Microsoft extensions. You should log unknown tags to be able to add them to the table of known tags (and reporting them to the author of squid-gw). The following keywords are available for policy:

    •   comment replace with comment [DIU]

    •   copy don't remove the tag [U]

    •   drop completely remove the tag [DIU]

    •   escape escape the tag ("&amp;foobar&gt;") [DIU]

    •   prefix prefix the tag name ("<REMOVED-foobar>") [DU]

        (The letters in brackets indicate for which type the keyword can be used.) It is not recommended to use unknown:copy.

    Any type not listed in the attribute is not changed. The default setting is

        dangerous:prefix
        invalid:escape
        unknown:prefix

Example:
    squid-gw: html-tags dangerous:prefix/log invalid:drop/log

http-fields type:policy[/log]
    Configure how to handle suspect and dangerous HTTP header fields. If there are multiple http-fields lines, all of them will be read. policy applies to header fields classified as type. If /log is given, squid-gw will log any header field classified as type. The following keywords are available for type:

    •   dangerous dangerous header fields (e.g. "Location: javascript:")

    •   invalid invalid header fields (e.g., ":" missing)

    •   privacy header fields disturbing privacy (e.g., "From:")

    •   silent header fields to be dropped silently (e.g., "Content-Length:" for text/html)

    •   unknown unknown header fields (e.g., "foobar:")

    The classification of header fields can be changed in the source code only. You should log unknown header fields to be able to add them to the table of known header fields (and reporting them to the author of squid-gw). The following keywords are available for policy:

    •   copy don't remove the header field [PU]

    •   drop completely remove the header field [DIPSU]

    •   prefix prefix the name with "REMOVED-" [DPUS]

    (The letters in brackets indicate for which type the keyword can be used.) It is not recommended to use unknown:copy .

    The default setting is

        dangerous:prefix/log
        invalid:drop/log
        privacy:drop
        silent:drop
        unknown:prefix/log

    Any type not listed in the attribute is not changed.

Example:

    squid-gw: http-fields dangerous:drop/log unknown:drop/log

log event
    Define what events to log. If there are multiple log lines, all of them will be read. The following keywords are available for event:

    content-type
        log the Content-Type received from the server; this is useful for squid-log

    content-type-conflict
        if there are multiple Content-Type fields having different values, log the values received from the server; only the first value encountered will be passed on to the client, no matter how this option is configured

    incorrect-tags
        log incorrect tags such as "<a" at EOF which are removed unconditionally by squid-gw

    missing-content-type
        log instances of server responses with body but without Content-Type header field

    redirected
        log redirections caused by the -redir option of deny-destinations

    request
        log the HTTP request line received from the client; considered obsolete as exit host= line contains this information anyways.

    request-header
        log all lines of the HTTP request header received from the client; this can be used for debugging

    response-header
        log all lines of the HTTP response header received from the server; this can be used for debugging

    script-macros
        log all occurences of (removed) script macros (that is, attributes containing embedded scripts, such as "&{script};"). If JavaScript is not blocked, script macros won't be logged

    simple-response
        log the first non-empty line of a simple-response (HTTP/0.9) from the HTTP server; this can be used for debugging

    tag-attribute-pairs
        log tag/attributes pairs which are not expected to be encountered as the attribute (which is one which needs special attention such as "ACTION") should occur only with certain tags

    unknown-content-type
        log unknown Content-Type values (which squid-gw replaces with application/binary)

    user-agent
        log the value of the User-Agent request header line, if present. This can be used for finding values for the browsers attribute without having to enable log reqest-header.

    stats
        log statistics in format Stats: (CI1/CI2 CO1/CO2) (SI1/SI2 SO1/SO2) MEMORY. The numbers in parentheses are numbers of bytes processed during the session; the *1 number is the actual number processed, the *2 number is the number of bytes read or written. For instance, if the body is longer than claimed by Content-Length, these numbers may differ. CI and CO are the number of bytes received from and sent to the client, respectively. SI and SO are the number of bytes received from and sent to the server, respectively (these numbers are zero for the CONNECT request method). MEMORY is the memory usage in bytes.

Example:
    squid-gw: log content-type request
    squid-gw-debug: log request-header

referer policy [url-pattern]
    Configure how to treat the "Referer" HTTP request header line. The following values are available for policy:

    drop
        Drop all "Referer" request lines unconditionally. This is the default value.

    keep-all
        Keep all "Referer" request lines unconditionally.

    keep-same-site
        Keep "Referer" request lines only if it its host name matches the request's host name.

    keep-match
        Keep only those "Referer" request lines which match url-pattern.
Note that url-pattern
 is used only for keep-match.

server host port
    Forward to the HTTP proxy on host host port port. host can be an IP address or a hostname. This attribute is mandatory (at least one server must be in effect). Only the first server line is read.

Example:
    squid-gw: server 199.99.99.99 3128

server-timeout timeout
    Define the number of seconds squid-gw is idle (without network activity) before disconnecting from the server. The default value is 2 hours ( PROXY_TIMEOUT in firewall.h). Only the first server-timeout line is read. For the tunnelled connection of the CONNECT request method, server-timeout applies to both the client and the server.

Example:
    squid-gw: server-timeout 3600

script policy
    Configure what to do with scripts (JavaScript), that is, with stuff between <SCRIPT> and </SCRIPT> and with HTML attributes (such as ONLOAD) containing scripts. Only the first script line is read. There are two choices for policy: html causes scripts to be treated as HTML; tags etc. will be parsed and rewritten; attributes containing scripts will be treated like ordinary attributes (escaping dangerous characters). This breaks scripts which contain the characters "'", "", "<", "&", or ">". verbatim causes scripts to be passed through verbatim. This keeps scripts intact, but opens a security hole for browsers which do not understand the <SCRIPT> tag or which for some other reason interpret scripts as HTML. Therefore, you should move the script configuration to a browser-dependent configuration class. ( -force is not yet available.) The default setting is html. script is ignored if JavaScript is disabled (see block).

Example:
    squid-gw: script html
    squid-gw-netscape: script verbatim

style policy
    Same as script for <STYLE> tag (same cautions apply).

Example:
    squid-gw: style html
    squid-gw-ie6: style verbatim

user-agent name
    Replace the value of any "User-Agent:" HTTP header field with name. This can be used for improving privacy by hiding the types of browsers and operating systems. Don't forget to use quotes if the value contains blanks! Only the first user-agent line is read.

Example:
    squid-gw: user-agent Mozilla/3.0

Note that, according to the Wget 1.5.3 documentation, "Netscape Communications Corp. has claimed that false transmissions of Mozilla as the User-Agent are a copyright infringement, which will be prosecuted." This is probably a trademark issue, not a copyright issue.

  URL patterns
URL patterns are used for the destinations and href configuration attributes. There are three variants for url-pattern:

•   (1) * -- this always matches any URL under test.

•   (2) *:pattern -- compare the entire URL under test without interpretation to pattern. Letter case is ignored. * in pattern matches any number of characters.

•   (3) a URL -- compare the URL under test part by part to the pattern URL. The special scheme http*: matches http: and https:.

For variant (3), missing parts (e.g., port number, path, query) of the pattern URL match any corresponding value of the URL under test (i.e., missing parts are ignored). Letter case is ignored (even for the path!). * can be used for matching any number of characters in the following parts of the URL: user (ftp), password (ftp), host, path, query (http), fragment (http), type (ftp). If the host part looks like an IP address (ie, it contains four fields separated by dots, each field containing either * or a number between 0 and 255), the host part of the pattern matches IP address only. Currently there are some restrictions in URL matching which may be lifted in future releases:

•   The host name is compared as string; names and IP addresses are not resolved (and thus never match)

•   /./ and /../ in the path are not treated specially.

•   Some schemes such as ftp: must be followed by //; alternatively, you can use *:ftp:.

•   Hexadecimal escapes ("%ff") cannot be used in a pattern URL

  Host patterns
The -hosts option is used for the browsersanddestinations configuration attributes, including the variants with permit-ordeny- prefix. If the -hosts option is omitted, the rule line will be applied independently of the client's IP address or domain name, as long as the rest of the attribute (browser name or destination URL, respectively) matches the rule.

If at least one -hosts option is used in a configuration line, the rule will be applied only if the client's IP address or domain name matches the -hosts options. Each -hosts option is followed by at least one host-pattern. host-patternscomein two flavours: positive patterns (a host pattern, i.e., an IP address pattern or a domain name pattern) and negative patterns (the character "!" folllowed by a host pattern). -hosts options and their patterns are evaluated from left to right: as soon as a positive pattern matches, the rule will be accepted (subject to browser or URL, respectively); as soon as a negative pattern fails to match, the rule will be ignored. If a positive pattern fails to match or if a negative pattern matches, the next pattern or -hosts option will be checked. When reaching the end of patterns and -hosts options without having hit a matching positive pattern, the rule will be ignored. To make sense, a negative pattern must be followed by a positive pattern (otherwise the rule would never match). It does not matter how patterns are grouped to "-hosts" options as long as the sequence of the patterns isn't changed, i.e., the following lines are equivalent:

    squid-gw: deny-browsers Wget* -hosts !10.0.0.1 !10.0.0.2 * squid-gw: deny-browsers Wget* -hosts !10.0.0.1 -hosts !10.0.0.2 -hosts *

(Currently, there's no point in using multiple -hosts options as there are no other -hosts -like options (such as "-browsers") which could be mixed with -hosts options.)

The -hosts option is usually used for exempting certain machines from deny- rules and for restricting -permit rules to certain machines. The following example, exempts clients which are used for testing or central downloading of programs (such as browsers) from a deny- rule:

    squid-gw: deny-destinations *:*.exe -hosts !10.0.0.17 !10.0.0.18 *

This rule denies access to all URLs ending with .exe. Only for clients 10.0.0.17 and 10.0.0.18, this rule does not apply. Note that the negative patterns are followed by a positive match-all pattern. Also note that rule lines which come after the above one can still deny access even for clients 10.0.0.17 and 10.0.0.18, so the above rule is different from

    squid-gw: permit-destinations *:*.exe -hosts 10.0.0.17 10.0.0.18
    squid-gw: deny-destinations *:*.exe

EXAMPLES
The following configuration defines sample http access policy

    squid-gw:       permit-hosts 192.168.0.17 -class debug
    squid-gw:       permit-hosts 192.168.0.42 -class relax
    squid-gw:       permit-hosts 192.168.0.*
    squid-gw:       permit-browsers *
    squid-gw:       user-agent "Mozilla/3.1"
    squid-gw:       server wwwproxy.mydomain.com 3128
    squid-gw:       server-timeout 3600
    squid-gw:       client-timeout 300
    squid-gw:       log content-type request
    squid-gw:       href http: https: ftp:// mailto: news: javascript:
    squid-gw:       http-fields dangerous:drop/log unknown:drop/log
    squid-gw:       html-tags dangerous:comment/log unknown:comment/log
    squid-gw:       html-attributes alphanumeric:copy novalue:copy
    squid-gw:       html-attributes dangerous:drop unknown:drop on:drop/log
    squid-gw:       html-references unknown:escape/log
    squid-gw:       html-attribute-length 16384
    squid-gw:       destinations http://www.a-safe-site.com -class js
    squid-gw:       connect www.a-safe-site.com -ipaddr 1.2.3.4
    squid-gw-relax: allow java
    squid-gw-debug: allow cookies java javascript object
    squid-gw-debug: html-tags dangerous:prefix/log unknown:prefix/log
    squid-gw-debug: html-attributes dangerous:prefix/log unknown:prefix/log
    squid-gw-debug: html-attributes on:copy/log
    squid-gw-js:    allow javascript
    squid-gw-js:    script verbatim

FILES

/etc/rc.local
    Command script that controls automatic reboot, and includes startup information for the http proxy.

/usr/local/etc/netperm-table
    The network permissions file contains configuration information for the Firewall Toolkit, including the http proxy.

BUGS
There are numerous ways to bypass content inspection policies; keep in mind that all security features are designed to prevent accidental misuse and minimize risk caused by software bugs; there is no way to reliably block educated malicious insider. Consider using administrative methods.

WebDAV methods support is embryionic and needs further improvement. There is no way to specify those in destinations rule.

Configuration seems to be overcomplicated, maybe there should be some reasonable policy templates.

gzip and other compression methods are not supported.

Multipart responses are not supported.

SSL sessions are not being inspected.

Report bugs to arkenoi@gmail.com or fwtk-users@buoy.com mailing list. Include a complete example, explaining what you expected to happen and what actually happened. Be sure to indicate the type of system (operating system, hardware, etc.) you are using, as well as the version of the http proxy.

AUTHOR
Eberhard Mattes

SEE ALSO
netperm-table(5), rc(8), authsrv(8), netacl(8)