.TH SQUID-GW 8 "August 2007" "OpenFWTK"
.SH NAME
squid-gw \- http proxy
.SH SYNOPSIS
.B "squid-gw "
[
.BI "-daemon " <port>
] [
.BI "-fastdaemon " [<host>:]<port>
] [
.BI "-pf " <pidfile>
] [
.BI "-as " <tag>
]
.sp
.SH DESCRIPTION
.IX  "squid-gw"  ""  "\(em http proxy"
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 
.I squid-gw 
is to reject anything which is not
explicitely allowed.  For instance, any HTTP headers 
.I 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 
.I squid-gw 
to deviate
from that syntax.  Better don't do that.)
.PP
You can configure the proxy to allow requests and define specific
policies based on:
.IP "\(bu" 4m
source IP address
.IP "\(bu" 4m
source host name
.IP "\(bu" 4m
destination IP address
.IP "\(bu" 4m
destination host name
.IP "\(bu" 4m
browser identification
.IP "\(bu" 4m
url pattern
.IP "\(bu" 4m
HTTP method
.PP
and selectively define response handling for:
.IP "\(bu" 4m
Content types (MIME and heuristically detected)
.IP "\(bu" 4m
HTTP headers
.IP "\(bu" 4m
HTML syntax compliance
.IP "\(bu" 4m
HTML attributes
.IP "\(bu" 4m
Meta attributes
.IP "\(bu" 4m
Javascript and other scripts
.IP "\(bu" 4m
Java
.IP "\(bu" 4m
ActiveX objects
.IP "\(bu" 4m
Hyperlink contents
.IP "\(bu" 4m
Cookies
.IP "\(bu" 4m
Embedded content
.IP "\(bu" 4m
Style sheets
.PP
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.
.PP
The http proxy
.RB "(" squid-gw ")"
generally runs as a daemon (invoked from system startup script, p.e.
.IR "/etc/rc.local" )
and listens for requests on the specified port (tcp/8080 or tcp/3128, 
as indicated
in
.IR "/etc/services" 
,are reasonable defaults).
Whenever the system receives an http request on this port, the http
proxy checks its configuration information (in the
.IR "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.
.PP
The proxy may also be invoked from tcp/ip "superserver" (inetd or xinetd).
.IR "-daemon" 
parameter should be omitted in this case.
.PP
.SH OPTIONS
.SS Command Line Options
The http proxy recognizes the following command line options (whether
started from the command line or from within
.IR /etc/rc.local ):
.TP
.BI "-daemon " port
Indicates that the http proxy runs as a daemon, and the port (name
or number) on which the http proxy listens. When 
.IR "-daemon" 
option is used, configuration is being read from
.IR netperm-table
for every new connection accepted by proxy.
.IP
.I port
Specifies either a numeric id or symbolic name from the
.I /etc/services
file.
.TP
.BI "-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
.IR "-fastdaemon" 
option is used, configuration is being read from
.IR netperm-table
once the daemon starts or if 
.IR SIGHUP 
is received.
.TP
.BI "-as " tag
Changes default application tag for 
.IR netperm-table 
from "squid-gw" to any given 
string.
.TP
.BI "-pf " pidfile
Specifies a file name where daemon stores master process PID.
.SS Configuration Options
The http proxy reads configuration rules from the
.IR "/usr/local/etc/netperm-table" .
It reads all rules using the
.B squid-gw
and
.B *
(wildcard) keywords. 
.PP
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
.I netperm-table 
must be readable by the user ID and group ID
configured with the 
.B userid
and 
.B groupid
attributes; otherwise,
configuration classes won't work.
.PP
The http proxy reads the
.I 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
.BR "netperm-table"  (5)
for a more complete explanation of 
.I netperm-table
syntax and precedence.
.PP
Configuration classes are applied in the following sequence:
.RS
.PP
1.  Global configuration
.PP
2.  Client-specific class from "hosts" attribute
.PP
3.  Destination-specific class from "destinations" attribute
.PP
4.  Client-specific class from "browsers" attribute
.PP
.RE
By default, later classes override values provided by earlier classes,
that is, 
.B browsers
classes override 
.B destinations 
classes which
in turn override 
.B hosts 
classes which in turn override the global configuration.
.PP
However, for some attributes, you can specify a level by using the
.B \-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 
.B \-force 
option increases the
level of the succeeding values of the line by one.  The default level
is zero.
.PP
Suppose that you want to enable JavaScript for certain browsers
(
.I "User-Agent: SafeBrowser"
).  For certain other browsers (
.I "User-Agent: GoodBrowser"
), you want to enable JavaScript only when visiting a
certain site (
.I http://safesite
).  For all other browsers, you want to
disable JavaScript.  The following configuration will implement that
policy:
.PP
.sp 1
.nf
.na 
.RS
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
.RE
.fa
.fi
.PP
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 
.I SafeBrowser, 
just insert
.PP
.RS
.nf
.na 
squid-gw:              destinations http://evilsite  -class evilsite
.fa
.fi
.RE
.PP
before the 
.B "destinations *"
line and insert
.PP
.RS
.nf
.na 
squid-gw-evilsite:     block -force -force javascript
.fa
.fi
.RE
.PP
anywhere.
.PP
As the 
.B browsers 
and 
.B destinations 
attributes can be used for global
configuration only, not for configuration classes, the 
.B -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.
.SS Global configuration
The http proxy recognizes the following attributes for global configuration:
.TP
.BI "browsers " "browser.. " "[-class " "class" "] [-hosts " "client-host.." "] [-authall]" 
Specify access permissions based on the value of the 
.B User-Agent
HTTP header field (that is, based on the (pretended) type of the
browser).  If there is no 
.B User-Agent 
HTTP header field, squid-gw
pretends that the value is 
.B no-user-agent 
(for the 
.B "GET, HEAD, "
and 
.B "POST "
request methods) or 
.B "no-connect-user-agent " 
(for the
.B CONNECT 
request method).  The 
.B "browsers " 
attribute comes in two
flavours: 
.B "permit-browsers " 
for permitting access for matching
browsers and 
.B "deny-browsers " 
for denying access for matching
browsers.  
.B "browsers " 
is equivalent to 
.B "permit-browsers ".  
If there are multiple 
.B "browsers " 
lines, all of them will be read,
stopping at the first matching line.  If the 
.B \-class 
option is
used, all specified configuration classes will also be read for
attributes, overriding the global configuration.  If at least one
.B "-hosts " 
option is used, the client must match the 
.B "-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 
.B \-class 
option is
useless for 
.B "deny-browsers ".  
.I browser 
can contain 
.B "* " 
to
match any sequence of characters.  Letter case is ignored.  Don't
forget to use quotes if 
.I browser 
contains blanks!
.sp
.B \-authall 
enables proxy authentication via
.IR authsrv .
Note that you can not use challenge/response authentication protocols
with http directly; use SSO agent for strong authentication.
.PP
Example:
.PP
.RS
.nf
.na 
squid-gw: permit-browsers Wget* -class wget
squid-gw: deny-browsers no-user-agent no-connect-user-agent
squid-gw: permit-browsers "*"
.fa
.fi
.RE
.PP
The second line denies access if the 
.B User-Agent
line is missing, except for a test machine called test.my.domain.
.TP
.BI "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
.B destinations 
attribute for access permissions for plain HTTP
URLs.)  The 
.B connect
attribute comes in two flavours:
.B permit-connect 
for permitting access for matching destinations and 
.B deny-connect 
for denying access for matching destinations.
.B connect
is equivalent to 
.B permit-connect.  
If there are multiple 
.B connect
lines, all of them will be read, stopping at
the first matching line.  If there is no matching line, access
will be denied.
.sp
For a 
.B connect 
line to match, all of the following conditions
must be met: at least one 
.I host 
and its 
.I port 
match
the destination address; if 
.B \-ipaddr
is used, at least one
.I address 
matches the destination address; if 
.B -hosts 
is used, at least one 
.I client-host
matches the client address.
There must be at least one
.I  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 
.B "*" 
in 
.I host matches any
number of characters, including zero characters.  If the port
number is omitted, 443 (https/SSL) will be assumed.  If 
.B "*" 
is specified for 
.I port 
(not recommended), any port number will match.
.sp
If 
.B \-ipaddr 
is used, at least one 
.I address 
must match an IP
address of the host requested by the client.  You can use 
.B "*" 
in
.I address. 
Note that using 
.B "-ipaddr" 
turns
.I host 
mostly into a comment (except for the port number).  If you want
to match by IP address only, just use 
.B "*" 
as 
.I host:
.sp
	squid-gw: permit-connect * -ipaddr 1.2.3.4
.sp
As 
.I address
doesn't include a port number, the port number is specified by
.I port:
.sp
	squid-gw: permit-connect *:5555 -ipaddr 1.2.3.4
.sp
It is highly recommended to use 
.B \-ipaddr
to make it harder for attackers to redirect connections.
.sp
The
.B \-delay
option can be used to slow down access to sites
which are not required for work.
.sp
For
.B deny-connect,
you can define the error message with the
.B \-message
option. If no
.B \-message
option is given, the message will be
.B 'Forbidden'
The
.B \-delay
option can be used to cause a delay before sending the response.
.sp
If at least one
.B \-hosts
option is used, the client must match the
.B \-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.
.sp
.B IMPORTANT:
You should permit 
.B CONNECT 
only to trusted sites, not to the Internet at large.  
squid-gw doesn't perform any content filtering for 
.B CONNECT!  
You cannot block ActiveX, Java, and JavaScript!
.TP
Example:
.RS
.nf
.na 
.PP
squid-gw: connect www.example.com -ipaddr 1.2.3.4 1.2.3.5
.fa
.fi
.PP
.RE
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.
.TP
.BI "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
.B destinations 
attribute comes in two flavours:
.B permit-destinations
for permitting access for matching destinations and 
.B deny-destinations 
for denying access for matching destinations.  
.B destinations
is equivalent to
.B permit-destinations.  
If there are multiple 
.B destinations
lines, all of them will be read, stopping at the first matching
line.  If there is no matching line, access will be permitted(!).
.sp
For 
.B permit-destinations, 
you can specify configurations classes with the 
.B -class
option: all configuration classes specified for the first matching 
.B permit-destinations 
line will be read for attributes, overriding the global configuration. The 
.B -delay
option can be used to slow down access to sites which are not
required for work.  The 
.B -class 
option is ignored for
.B deny-destinations.
.sp
For 
.B deny-destinations, 
you can define the error message with the
.B -message 
option.  If no 
.B -message 
option is given, the message will be 
.B 'Forbidden'.  
Alternatively, you can redirect the request
to another URL by using the 
.B -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 
.B deny-destinations 
rule which uses the 
.B -redir 
option.  The
.B -delay 
option can be used to cause a delay before sending the response.
.I 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 
.I method.  
If 
.I 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 
.I method.
.sp
If at least one 
.B -hosts 
option is used, the client must match the 
.B -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.
.sp
See chapter `URL patterns' for details on 
.IR "url-pattern" .
.sp
.B \-authall 
enables proxy authentication via
.IR authsrv .
Note that you can not use challenge/response authentication protocols
with http directly; use SSO agent for strong authentication.
.sp
.B IMPORTANT:
You cannot rely on
.B 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.
.TP
Example:
.RS
.nf
.na 
.PP
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
.fa
.fi
.PP
.RE
Explanation: The first line denies access if an IP address is
given as host.  All serious web sites should be accessible by
name.
.sp
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).
.sp
The third line is an attempt at reminding users of local
conditions of Internet use.
.sp
The last three lines block Java, JavaScript, and ActiveX for all
sites but www.myowndomain.com.

.TP
.BI "hosts " "host-pattern [host-pattern...] " "[-class " "class" "]"
Specify access permissions for clients based on IP address.  The
.B hosts
attribute comes in two flavours: 
.B permit-hosts 
for permitting access for matching hosts and 
.B deny-hosts
for denying access for matching hosts.  
.B hosts
is equivalent to
.B permit-hosts.  
If there are multiple 
.B hosts 
lines, all of them
will be read, stopping at the first matching line.  If the 
.B -class
option is used, all specified configuration classes will also be
read for attributes, overriding the global configuration.  The
.B -class 
option is useless for 
.B deny-hosts.  
See also the 
.B -hosts
option of the 
.B browsers
and 
.B destinations 
attributes.
.sp
.B \-authall 
enables proxy authentication via
.IR authsrv .
Note that you can not use challenge/response authentication protocols
with http directly; use SSO agent for strong authentication.
.TP
Example:
.RS
.nf
.na 
.PP
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
.fa
.fi
.PP
.RE
.TP
.BI "href " "url-pattern"
Specify what URLs are allowed in HTML attributes such as HREF and
SRC which take an URL as value.  The 
.B href 
attribute comes in
two flavours: 
.B permit-href 
for permitting matching URLs and
.B deny-href 
for rejecting matching URLs.  
.B href 
is equivalent to
.B permit-href.  
If there are multiple 
.B 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 
.B href 
is required to enable
hyperlinks.  The main purpose of 
.B href 
is to prevent
browsers from accessing local services:
.sp
	<img src="http://localhost:19">
.sp
Unfortunately, the 
.I url-pattern
syntax is not yet powerful enough.  
For controlling access to external WWW sites, you should use 
.B destinations 
instead of 
.B href.
.TP
.BI "directory " directory
Specifies the directory that the http proxy makes its root directory
before providing service.  
.TP
.BI "groupid " group
Specifies the name of the group the http proxy uses when running.
.RS
.TP
.I group
Specifies either a name or numeric id from the
.I /etc/group
file.
.RE
.TP
.BI "timeout " seconds
Specifies the number of seconds the http proxy is idle (with no
network activity) before disconnecting
.TP
.BI "userid " user
Specifies the user ID the proxy uses when running.
.RS
.TP
.I user
Specifies either a name or numeric id from the
.I /etc/passwd
file. 
.RE
.SS Configuration classes
squid-gw understands the following attributes for global configuration
and for configuration classes:
.TP
.BI "allow " what..
.TP
.BI "block " what..
By default, squid-gw blocks (filters) anything it considers
dangerous.  You can change the blocking policy of squid-gw by
using the 
.B "allow" 
and 
.B "block" 
attributes.  Only the first 
.B "allow"
line is read and only the first 
.B "block" 
line is read.  The following keywords are available for 
.I what:
.RS
.sp
.IP "\(bu" 4m
cookies	Cookies
.IP "\(bu" 4m
embed		<EMBED> HTML tag
.IP "\(bu" 4m
java		Java applets (<APPLET> HTML tag)
.IP "\(bu" 4m
javascript	JavaScript (and other) scripts
.IP "\(bu" 4m
object		ActiveX objects (<OBJECT> HTML tag)
.IP "\(bu" 4m
style		Style sheets
.sp
.RE
.RS
Moreover, the
.B -force
option can be used for assigning a level to the values following that option.
.sp
To enable JavaScript, you also have to enable 
.B "javascript:" 
in HREF attributes, see 
.B "href".  
See also 
.B "script".  
To enable ActiveX, you also have to enable 
.B "clsid:" 
in HREF attributes.
.RE
.TP
Example:
.RS
.nf
.na 
.PP
squid-gw-nofilter: allow cookies java javascript object
.fa
.fi
.RE
.PP
Note that there are other ways than cookies to track users.  For
instance, user-specific information can be encoded in URLs.
.sp
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.
.sp
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.
.TP
.BI "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 
.I 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 
.I 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
.sp
	squid-gw: auto-html-limit 0
.sp
Of course, you can use configuration classes to make the value of
.B 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).
.sp
The body portion of the same size is used for other
.B content-type
heuristics.
.TP
.BI "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
.B "client-timeout" 
line is read.  For the tunnelled connection of
the 
.B CONNECT 
request method, 
.B "client-timeout" 
is ignored and
.B "server-timeout" 
applies to both the client and the server.
.TP
Example:
.RS
.nf
.na 
.PP
squid-gw: client-timeout 300
.fa
.fi
.RE
.TP
.BI "content-type " "type" "/" "subtype.." " [-milter " "filter-socket.." "]"
Specify content type permissions. The
.B content-type 
attribute comes in two flavours:
.B permit-content-type
for permitting content types and specifying filtering rules and
.B deny-content-type for denying access.
.B content-type
is equivalent to 
.BR "permit-content-type" .
If there are multiple 
.B 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
.I filter-socket
specifies content inspection server (
.BI "unix:/" domain-path 
or 
.BI "inet:" port "@" host
syntax).
.RE
.TP
.BI "cookies " mode
Define how to parse cookies.  Only the first 
.B "cookies" 
line is read.  There are four possible values for 
.I mode:
.RS
.sp
.IP "\(bu" 4m
netscape        relaxed parsing as in Netscape's cookie spec
.IP "\(bu" 4m
netscape-quote  relaxed parsing, quote non-strict values
.IP "\(bu" 4m
nocheck         don't parse cookies at all
.IP "\(bu" 4m
rfc2109         strict parsing according to RFC 2109
.RE
.sp
.RS
At this time, I have not yet encountered any HTTP server which
uses RFC 2109 syntax for cookies.  Therefore, the default value
is 
.B "netscape".
.RE
.TP
Example:
.sp
squid-gw: cookies nocheck
.TP
.B drop-meta-content-type [-force].. on
.TP
.B 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
.B "drop-meta-content-type" 
line is read.
.sp
The default setting is 
.B "off". 
Moreover, the 
.B -force 
option can be
used for assigning a level to the value following that option.
.TP
.BI "html-attribute-length " limit
Limit the length of the attribute values to 
.I limit 
octets.  The
default value is 1024 (cf. RFC 1866).  However, there are HTML
documents which use longer attribute values.  Note that setting
.I limit 
very high wastes lots of memory.
.TP
Example:
.sp
squid-gw: html-attribute-length 32768
.TP
.BI "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 
.B "html-attributes" 
lines, all of them will be read.  
.I policy
applies to attributes classified as
.I type.  
If 
.B "/log" 
is given, squid-gw will log any attribute
classified as 
.I type.  
The following keywords are available for
.I type:
.RS
.sp
.IP "\(bu" 4m
.B 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 
.B "on"
.IP "\(bu" 4m
.B dangerous 
dangerous attribute
.IP "\(bu" 4m
.B novalue 
unknown attribute without value and whose name does
not start with 
.B "on"
)
.IP "\(bu" 4m
.B on 
unknown attribute whose name starts with 
.B "on"
.IP "\(bu" 4m
.B unknown 
unknown attribute
.sp
.RE
.RS
The classification of some attributes can be configured (see
.B "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
.I policy:
.sp
.IP "\(bu" 4m
.B copy
don't remove the attribute 
.I [ANOU]
.IP "\(bu" 4m
.B drop
completely remove the attribute
.I [ADNOU]
.IP "\(bu" 4m
.B prefix 
prefix the attribute name ("REMOVED-foobar")
.I [ADNOU]
.sp
.RE
.RS
(The letters in brackets indicate for which 
.I type
the keyword
can be used.)  It is not recommended to use 
.B "on:copy" 
or
.B "unknown:copy."
.sp
Any 
.I type 
not listed in the attribute is not changed.  The
default setting is
.sp
.RS
alphanumeric:prefix
.br
dangerous:prefix
.br
novalue:copy
.br
on:prefix/log
.br
unknown:prefix
.RE
.RE
.TP
Example:
.sp
squid-gw: html-attributes dangerous:prefix/log
.TP
.B "html-filter [-force].. on"
.TP
.B "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
.B "html-filter" 
line is read.
.TP
Example:
.sp
squid-gw:      browsers Wget* -class wget -hosts 10.0.0.1
squid-gw-wget: html-filter off
.sp
.PP
These rules turn off HTML filtering for Wget on client 10.0.0.1 only.
.TP
.BI "html-meta " "type:policy" "[/log]"
Configure how to handle suspect META tags in HTML documents
received from the server.  If there are multiple 
.B "html-meta"
lines, all of them will be read.  
.I policy 
applies to META tags classified as 
.I type.
If 
.B "/log" 
is given, squid-gw will log any META tag classified as 
.I type.  
The following keywords are available for 
.I type:
.RS
.sp
.IP "\(bu" 4m
.B unknown
unknown name (e.g., "<meta name=foo content=bar>")
.sp
.RE
.RS
Note that 
.B "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 
.B "html-tags dangerous" 
(which see).
.sp
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 
.I policy:
.sp
.IP "\(bu" 4m
.B comment
replace with comment
.I [U]
.IP "\(bu" 4m
.B copy
don't remove the tag
.I [U]
.IP "\(bu" 4m
.B drop
completely remove the tag
.I [U]
.IP "\(bu" 4m
.B escape
escape the tag ("&amp;foobar&gt;")
.I [U]
.IP "\(bu" 4m
.B prefix
prefix the tag name ("<REMOVED-foobar>")
.I [U]
.sp
.RS
(The letters in brackets indicate for which
.I type
the keyword can be used.)  It is not recommended to use
.B "unknown:copy".
.sp
Any
.I type
not listed in the attribute is not changed.  The default setting is
.sp
.RS
unknown:prefix
.RE
.RE
.RE
.TP
.BI "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
.B "html-references" 
lines, all of them will be read.  
.I policy
applies to references classified as 
.I type.  
If 
.B "/log" 
is given,
squid-gw will log any reference classified as 
.I type.  
The following keywords are available for 
.I type:
.RS
.sp
.IP "\(bu" 4m
.B unknown
unknown references (e.g., "&foobar;")
.sp
.RE
.RS
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
.I policy:
.sp
.IP "\(bu" 4m
.B copy
don't remove the reference 
.I [U]
.IP "\(bu" 4m
.B drop
completely remove the reference
.I [U]
.IP "\(bu" 4m
.B escape
escape the reference ("&amp;foobar;")
.I [U]
.sp
(The letters in brackets indicate for which 
.I type 
the keyword
can be used.)  For security, it is not recommended to use
.B "unknown:copy".  
Note that 
.B "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").
.sp
The default setting is 
.B "unknown:escape".  
Any 
.I type 
not listed in the attribute is not changed.
.RE
.TP
.BI "html-tags " "type:policy" "[/log]"
Configure how to handle suspect tags ("<FOOBAR>") in HTML
documents received from the server.  If there are multiple
.B "html-tags" 
lines, all of them will be read.  
.I policy applies to tags classified as 
.I type.  
If 
.B "/log" 
is given, squid-gw will log any tag classified as 
.I type.  
The following keywords are available for 
.I type:
.RS
.sp
.IP "\(bu" 4m
.B dangerous
dangerous tag (e.g., "<APPLET>" when blocking Java)
.IP "\(bu" 4m
.B invalid
invalid tag (e.g., "<FOOBAR%>")
.IP "\(bu" 4m
.B unknown
unknown tag (e.g., "<foobar>")
.sp
.RE
.RS
The classification of some tags can be configured (see 
.B "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 
.I policy:
.sp
.IP "\(bu" 4m
.B comment
replace with comment
.I [DIU]
.IP "\(bu" 4m
.B copy 
don't remove the tag
.I [U]
.IP "\(bu" 4m
.B drop
completely remove the tag
.I [DIU]
.IP "\(bu" 4m
.B escape
escape the tag ("&amp;foobar&gt;")
.I [DIU]
.IP "\(bu" 4m
.B prefix
prefix the tag name ("<REMOVED-foobar>")
.I [DU]
.sp
(The letters in brackets indicate for which 
.I type 
the keyword
can be used.)  It is not recommended to use
.B "unknown:copy."
.sp
.RE
.RS
Any
.I type
not listed in the attribute is not changed.  The default setting is
.sp
.RS
dangerous:prefix
.br
invalid:escape
.br
unknown:prefix
.sp
.RE
.RE
.TP
Example:
.RS
squid-gw: html-tags dangerous:prefix/log invalid:drop/log
.RE
.TP
.BI "http-fields " "type:policy" "[/log]"
Configure how to handle suspect and dangerous HTTP header fields.
If there are multiple 
.B "http-fields" 
lines, all of them will be read.  
.I policy
applies to header fields classified as 
.I type.
If 
.B "/log" 
is given, squid-gw will log any header field classified
as 
.I type.  
The following keywords are available for 
.I type:
.RS
.sp
.IP "\(bu" 4m
.B dangerous
dangerous header fields (e.g. "Location: javascript:")
.IP "\(bu" 4m
.B invalid
invalid header fields (e.g., ":" missing)
.IP "\(bu" 4m
.B privacy
header fields disturbing privacy (e.g., "From:")
.IP "\(bu" 4m
.B silent
header fields to be dropped silently (e.g., "Content-Length:" for text/html)
.IP "\(bu" 4m
.B unknown
unknown header fields (e.g., "foobar:")
.sp
.RE
.RS
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
.I policy:
.sp
.IP "\(bu" 4m
.B copy
don't remove the header field
.I [PU]
.IP "\(bu" 4m
.B drop
completely remove the header field 
.I [DIPSU]
.IP "\(bu" 4m
.B prefix
prefix the name with "REMOVED-"
.I [DPUS]
.sp
.RE
.RS
(The letters in brackets indicate for which 
.I type 
the keyword can be used.)  It is not recommended to use 
.B "unknown:copy".
.sp
The default setting is
.sp
.RS
dangerous:prefix/log
.br
invalid:drop/log
.br
privacy:drop
.br
silent:drop
.br
unknown:prefix/log
.sp
.RE
Any
.I type
not listed in the attribute is not changed.
.RE
.TP
Example:
.sp
.RS
squid-gw: http-fields dangerous:drop/log unknown:drop/log
.RE
.TP
.BI "log " event
Define what events to log.  If there are multiple 
.B "log" lines,
all of them will be read.  The following keywords are available
for 
.I event:
.sp
.RS
.TP
.B content-type
log the Content-Type received from the server; this is useful for squid-log
.TP
.B 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
.TP
.B incorrect-tags
log incorrect tags such as "<a" at EOF which are
removed unconditionally by squid-gw
.TP
.B missing-content-type
log instances of server responses with body but
without Content-Type header field
.TP
.B redirected
log redirections caused by the 
.B \-redir
option of
.B "deny-destinations"
.TP
.B request
log the HTTP request line received from the client;
considered obsolete as 
.B "exit host= "
line contains this information anyways.
.TP
.B request-header
log all lines of the HTTP request header received from
the client; this can be used for debugging
.TP
.B response-header
log all lines of the HTTP response header received
from the server; this can be used for debugging
.TP
.B 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
.TP
.B 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
.TP
.B 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
.TP
.B unknown-content-type
log unknown Content-Type values (which squid-gw replaces
with 
.BR "application/binary" )
.TP
.B user-agent
log the value of the User-Agent request header line,
if present.  This can be used for finding values for
the 
.B "browsers" 
attribute without having to enable 
.BR "log reqest-header" .
.TP
.B stats
log statistics in format 
.B Stats:
.IR "(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.  
.IR "CI " "and " CO 
are the number of bytes received from
and sent to the client, respectively.  
.IR "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).  
.I MEMORY 
is the memory usage in bytes.
.RE
.TP
Example:
squid-gw: log content-type request
.br
squid-gw-debug: log request-header
.TP
.BI "referer " "policy [url-pattern]"
Configure how to treat the "Referer" HTTP request header line.
The following values are available for 
.IR "policy" :
.RS
.sp
.TP
.B drop
Drop all "Referer" request lines unconditionally.
This is the default value.
.TP
.B keep-all
Keep all "Referer" request lines unconditionally.
.TP
.B keep-same-site
Keep "Referer" request lines only if it its host name
matches the request's host name.
.TP
.B keep-match
Keep only those "Referer" request lines which match
.IR url-pattern .
.RE
Note that 
.B url-pattern
 is used only for 
.BR "keep-match" .
.TP
.BI "server " "host port"
Forward to the HTTP proxy on host
.I host
port
.IR port .
.I host
can be an IP address or a hostname.  This attribute is mandatory (at
least one 
.B "server"
must be in effect).  Only the first 
.B "server"
line is read.
.TP
Example:
squid-gw: server 199.99.99.99 3128
.TP
.BI "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 (
.B PROXY_TIMEOUT 
in firewall.h).  Only the first
.B "server-timeout" 
line is read.  For the tunnelled connection of
the CONNECT request method, 
.B "server-timeout" 
applies to both the client and the server.
.TP
Example:
squid-gw: server-timeout 3600
.TP
.BI "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 
.B "script"
line is read.  There are two choices for 
.IR "policy" : 
.B "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 ">".
.B "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
.B "script" 
configuration to a browser-dependent configuration
class.  (
.B "\-force" 
is not yet available.)  The default setting is
.BR "html" .  
.B "script" 
is ignored if JavaScript is disabled (see
.BR "block" ")."
.TP
Example:
squid-gw: script html
.br
squid-gw-netscape: script verbatim
.TP
.BI "style " policy
Same as
.B script
for <STYLE> tag (same cautions apply).
.TP
Example:
squid-gw: style html
.br
squid-gw-ie6: style verbatim
.TP
.BI "user-agent " name
Replace the value of any "User-Agent:" HTTP header field with
.IR "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 
.B "user-agent"
line is read.
.TP
Example:
squid-gw: user-agent Mozilla/3.0
.PP
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.
.SS URL patterns
URL patterns are used for the 
.B "destinations" 
and 
.B "href" 
configuration attributes.  There are three variants for 
.IR "url-pattern" :
.sp
.IP "\(bu" 4m
(1)
.B "*"
-- this always matches any URL under test.
.IP "\(bu" 4m
(2)
.BI "*:" pattern 
-- compare the entire URL under test without
interpretation to 
.IR "pattern" .  
Letter case is ignored.  
.B "*" 
in
.I pattern
matches any number of characters.
.IP "\(bu" 4m
(3)
a URL -- compare the URL under test part by part to the pattern
URL.  The special scheme 
.B "http*:" 
matches 
.B "http:" 
and 
.BR "https:" .
.sp
.PP
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!).  
.B "*" 
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 
.B "*" 
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:
.sp
.IP "\(bu" 4m
The host name is compared as string; names and IP addresses are not
resolved (and thus never match)
.IP "\(bu" 4m
.BR "/./ " and " /../ "
in the path are not treated specially.
.IP "\(bu" 4m
Some schemes such as 
.B "ftp:"
must be followed by
.BR "//" ;
alternatively, you can use 
.BR "*:ftp:" .
.IP "\(bu" 4m
Hexadecimal escapes ("%ff") cannot be used in a pattern URL
.SS Host patterns
The 
.B "-hosts" 
option is used for the 
.BR "browsers" and "destinations"
configuration attributes, including the variants with
.BR "permit-" or "deny-"
prefix.  If the
.B "-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.
.sp
If at least one 
.B "-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 
.B "-hosts" 
options.  Each 
.B "-hosts" option is followed by at
least one 
.IR "host-pattern" .  
.IR "host-pattern" s come in
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).  
.B "-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 
.B "-hosts" 
option will be
checked.  When reaching the end of patterns and 
.B "-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:
.RS
.sp
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 *
.RE
.sp
(Currently, there's no point in using multiple 
.B "-hosts" 
options as there are no other 
.B "-hosts" 
-like options (such as "-browsers") which could be mixed with 
.B "-hosts" 
options.)
.sp
The 
.B "-hosts" 
option is usually used for exempting certain machines
from 
.B "deny-" 
rules and for restricting 
.B "-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
.B "deny-" 
rule:
.sp
.RS
squid-gw:     deny-destinations *:*.exe -hosts !10.0.0.17 !10.0.0.18 *
.RE
.sp
This rule denies access to all URLs ending with 
.BR ".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
.RS
.sp
squid-gw:     permit-destinations *:*.exe -hosts 10.0.0.17 10.0.0.18
.br
squid-gw:     deny-destinations *:*.exe
.RE
.SH EXAMPLES
The following configuration defines sample http access policy
.sp
.nf
.na
.RS
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
.RE
.fa
.fi
.sp
.SH FILES
.IP /etc/rc.local
Command script that controls automatic reboot, and includes startup
information for the http proxy.
.IP /usr/local/etc/netperm-table
The network permissions file contains configuration information
for the Firewall Toolkit, including the http proxy.
.SH 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.
.sp
WebDAV methods support is embryionic and needs further improvement.
There is no way to specify those in
.B destinations
rule.
.sp
Configuration seems to be overcomplicated, maybe there should be some
reasonable policy templates.
.sp
gzip and other compression methods are not supported.
.sp
Multipart responses are not supported.
.sp
SSL sessions are not being inspected.
.sp
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.
.SH AUTHOR
Eberhard Mattes
.SH SEE ALSO
.BR netperm-table "(5), " rc "(8), "authsrv "(8), "netacl "(8)"