http-proxy

http-proxy
Prev	Kernun UTM Reference (5)	Next

Name

http-proxy — format of http-proxy component configuration

DESCRIPTION

General syntax rules of Kernun Firewall configuration files are described in configuration(7). This man page describes types, sections and items specific for the http-proxy component configuration.

Repeatable sections/items are marked by the '*' before section/item name.

TYPES

Configuration directives have attributes of several value-types. For the basic types description, see configuration(7).

Enumeration is a list of words (names) representing integer values. Some enumerations accept both names and direct integer values; in this case, enumeration description contains values for every name (in parenthesis next to name). For other enumerations, using of names is obligatory.

The following enumerations are used in http-proxy configuration directives:

yes-no (see common(5))

language (see common(5))

direction (see common(5))

ip-version (see common(5))

osi4-proto (see common(5))

time-cond (see common(5))

zip-mode (see common(5))

obligation (see common(5))

range-op (see common(5))

dbglev (see log(5))

logfail-mode (see log(5))

week-day (see time(5))

month (see time(5))

lock-type (see ipc(5))

auth-method (see auth(5))

virus-status (see antivirus(5))

source-address-mode (see source-address(5))

transparency (see acl(5))

user-auth-spec (see acl(5))

doctype-ident-method (see acl(5))

header-op (see acl(5))

listen-on-sock (see listen-on(5))

clear-web-db-category (see clear-web-db(5))

clear-web-db-match-mode (see clear-web-db(5))

replace-authorization-mode (name-usage obligatory)

Variants of authorization replace mode

simple: Replace the authorization data using a lookup table
radius: Replace the authorization data using a lookup table. Moreover, use a radius for authentication.

proxy-via (name-usage obligatory)

Values for controlling Via header.

pass: If a request or reply contains a Via header, it is passed through unchanged.
add: Each request or reply will get a Via header line added for the firewall host.
full: Each generated Via: header line will additionally have the http-proxy identification version shown as a Via comment field.
block: Every proxy request or reply will have all its Via header lines removed. No new Via header will be generated.
fake: All Via headers will be removed and then a fake header will be added.

http-protocol (name-usage obligatory)

Version of HTTP

HTTP-OTHER-VER: HTTP v. other than 0.9, 1.0, or 1.1
HTTP-0-9: HTTP v. 0.9
HTTP-1-0: HTTP v. 1.0
HTTP-1-1: HTTP v. 1.1

http-scheme (name-usage obligatory)

Scheme in HTTP URI

HTTP: http://...
FTP: ftp://...

cookie-table-clean (name-usage obligatory)

When to clean cookie table.

never: Table is persistent, must be deleted manually if corrupted.
on-restart: Table is deleted and recreated when the proxy is restarted, but not when reloaded.
always: Table is deleted when the proxy is restarted, reloaded, or stopped.

accept-gzip (name-usage obligatory)

How to handle the Accept-Encoding header.

no: Do not modify the Accept-Encoding header.
yes: Always add "Accept-Encoding: gzip" to the request.
client: Keep the Accept-Encoding header, but remove all encodings except gzip/x-gzip and identity. Do not add if missing.
client-add: Keep the Accept-Encoding header, but remove all encodings except gzip/x-gzip and identity. Add empty if missing.

content-gzip (name-usage obligatory)

How to handle the Content-Encoding header. Controls conversion of gzip and x-gzip values in the header. The same operation is applied also to compress and x-compress values.

keep: Do not modify Content-Encoding.
gzip: Convert x-gzip to gzip.
x-gzip: Convert gzip to x-gzip.
http: As X-GZIP for HTTP/1.0 clients and GZIP for HTTP/1.1 clients.
accept: Use the same form (gzip or x-gzip) as used by the client in the Accept-Encoding request header. Works as HTTP if Accept-Encoding is not present or does not contain gzip nor x-gzip.

http-redirect (name-usage optional)

Status code for HTTP redirection.

permanent (301): HTTP status 301 Moved Permanently
temporary (302): HTTP status 302 Found
temporary-same-method (307): HTTP status 307 Temporary Redirect

kerberos-user-match (name-usage obligatory)

How a Kerberos user name is matched in ACL and logged.

short: Match and log only the user name without the @REALM part.
full: Match and log the whole user@REALM name.

ldap-select (name-usage obligatory)

How a LDAP-CLIENT-AUTH section is selected.

name: Select by section name.
domain: Select by domain name.

auth-headers (name-usage obligatory)

Which authentication-related headers and responses are used.

proxy: Uses proxy authentication headers (Proxy-Authenticate, Proxy-Authorization) and responses (407 Proxy Authentication Required).
server: Uses origin server authentication headers (WWW-Authenticate, Authorization) and responses (401 Unauthorized).

sni-result (name-usage obligatory)

SNI inspection result.

specified: TLS 1.0 or higher with specified SNI so host and URI were changed to value from TLS ClientHello.
unspecified: TLS 1.0 or higher without specified SNI so host and URI remained unchanged.
ssl3: SSLv3 detected, therefore SNI inspection was skipped so host and URI remained unchanged.
skype: Skype protocol detected, therefore SNI inspection skipped so host and URI remained unchanged. Note that Skype uses HTTPS as well so only part of Skype communication will have this result.
unknown-protocol: Unknown protocol detected, therefore SNI inspection was skipped so host and URI remained unchanged.

ITEMS AND SECTIONS

Configuration of http-proxy library component consists of following prototypes:

via-mode ... ;
* start-line-check ... ;
* header-check ... ;
* aproxy name { ... }
* web-filter name { ... }
* ntlm-auth name { ... }
* kerberos-auth name { ... }
* http-proxy name { ... }

Description:

via-mode pass;

via-mode add [faked];

via-mode full [faked];

via-mode [block];

via-mode fake [faked];

Processing Via headers.

<branching element> (type: proxy-via, optional, default: block)
faked (type: str, optional, default: ""): full Via header value if FAKE, replacement for firewall hostname for ADD, FULL

start-line-check text-match max-len;

Check of the start-line of a HTTP message.

text-match (type: str-set): The line must match this.
max-len (type: uint32): Maximum number of characters in the line

header-check name-match val-match max-val-len;

Check of a HTTP message header.

name-match (type: str-set): The header name must match this.
val-match (type: str-set): The header value must match this.
max-val-len (type: uint32): Maximum number of characters of the header value

aproxy name {

  auth ... ;
  insecure-cookies ... ;
  oob-auth ... ;
  cookie-name ... ;
  logout ... ;
  timeout-idle ... ;
  timeout-unauth ... ;
  bufsz ... ;
}

Settings of authentication proxy for HTTP servers and of authentication server for out-of-band authentication.

Constraints:

Authentication method must be set.

Items & subsections:

auth none;

auth passwd file;

auth radius client;

auth ldap ldap;

auth ext file;

auth oob oob [mode [loose]];

Authentication method and attributes specification.

For more details, see auth(7).

<branching element> (type: auth-method)
file (type: str): Password/utility file name.
client (type: name of radius-client, see radius(5)): RADIUS client configuration name.
ldap (type: name of ldap-client-auth, see ldap(5)): LDAP client configuration parameters.
oob (type: name of oob-auth, see auth(5)): OOB authentication parameters.
mode (type: obligation, optional, default: required)
loose (type: key, optional)
Constraints:: Out-of-band authentication cannot be used here.

insecure-cookies;

Allow client to send session cookie using insecure (non-SSL/TLS) connections.

oob-auth;

This is out-of-band authentication server, not an HTTP authentication proxy.

cookie-name [val];

Name of session cookie.

val (type: str, optional, default: "KernunAProxySession")

logout [path];

If request URI contains this path, user is logged out.

path (type: str, optional, default: "/logout")

timeout-idle [sec];

Number of seconds until authentication expires when the client is idle (sends no requests).

sec (type: uint32, optional, default: 360)

timeout-unauth [sec];

Maximum time after which authentication expires.

sec (type: uint32, optional, default: 3600)

bufsz [bytes];

Input buffer size for mod-aproxy.

bytes (type: uint32, optional, default: 16384)

[End of section aproxy description.]

web-filter name {

  connection ... ;
  fail-ok ... ;
  sock-opt { ... }
}

External WebFilter configuration.

Items & subsections:

connection socket;

Network address of the web filter

socket (type: sock)

fail-ok;

Allow request if communication with the web filter fails

sock-opt {

  conn-timeout ... ;
  recv-bufsize ... ;
  close-timeout ... ;
  send-bufsize ... ;
  log-limit ... ;
}

Connection to web filter options.

The sock-opt section is derived from sock-opt section prototype. For detail description of it, see netio(5).

Changes to the sock-opt section:

Item recv-timeout is not valid.

Item send-timeout is not valid.

[End of section web-filter description.]

ntlm-auth name {

  domain ... ;
  workgroup ... ;
* ad-controller ... ;
  interfaces { ... }
  ldap ... ;
  timeout ... ;
  timeout-idle ... ;
  timeout-unauth ... ;
}

Constraints:

Active Directory domain name must be specified.

Active Directory controller address must be specified.

INTERFACES must be specified.

Items & subsections:

domain name;

Active Directory domain.

name (type: str)

workgroup name;

Workgroup name. If not set, the first component of the DOMAIN name (before the first period) is used.

name (type: str)

ad-controller addr;

Active Directory Domain Controller address.

addr (type: host)

interfaces {

* interface ... ;
* network ... ;
}

Selects the interfaces for communication with the Active Directory Domain Controller. If not set, all interfaces can be used. It is possible to specify either an INTERFACE section names, or network IP addresses with masks.

Constraints:

NTLM-related communication must be limited by INTERFACE or NETWORK.

Items & subsections:

interface name;

Communicate on this interface.

name (type: name of interface, see interface(5))

network addr;

Communicate on this network.

addr (type: net)

[End of section ntlm-auth.interfaces description.]

ldap name;

Ask an LDAP server for a list of groups each NTLM-authenticated user belongs to.

name (type: name of ldap-client-auth, see ldap(5))

timeout [sec];

Timeout for communicating with the NTLM helper program (0 = unlimited).

sec (type: uint16, optional, default: 5)

timeout-idle [sec];

Number of seconds until cached OOB authentication expires when the client is idle (sends no requests).

sec (type: uint32, optional, default: 360)

timeout-unauth [sec];

Maximum time after which cached OOB authentication expires.

sec (type: uint32, optional, default: 3600)

[End of section ntlm-auth description.]

kerberos-auth name {

  domain ... ;
  user-match ... ;
  kinit ... ;
  keytab ... ;
  proxy-host ... ;
* ad-controller ... ;
  ldap ... ;
  timeout-idle ... ;
  timeout-unauth ... ;
  lock ... ;
  lock-ldap ... ;
  one-per-session ... ;
}

Constraints:

Active Directory domain name must be specified.

Active Directory controller address must be specified.

Items & subsections:

domain name;

Active Directory domain.

name (type: str)

user-match [match];

How a Kerberos user name is matched in ACL and logged.

match (type: kerberos-user-match, optional, default: short)

kinit principal;

The Kerberos principal used to get a TGT for access to the LDAP. If not set, the Kernun system account in the Active Directory will be used, that is, the host name without domain followed by the dollar sign (host$). Empty principal means that the proxy should not try to obtain a ticket.

principal (type: str)

keytab path;

The keytab file used for Kerberos authentication. If not specified, the default keytab file /etc/krb5.keytab will be used.

path (type: name of shared-file, see common(5))

proxy-host name;

The proxy host name expected in authentication data from clients. This is also the proxy host name that users should set in their browser configuration. The specified host name will be used in the proxy Kerberos principal (HTTP/proxy-host). If not set, the host name of the Kernun system will be used.

name (type: str)

ad-controller addr;

Active Directory Domain Controller address.

addr (type: host)

ldap [name] name;

ldap domain;

Ask an LDAP server for a list of groups each Kerberos-authenticated user belongs to.

<branching element> (type: ldap-select, optional, default: name)
name (type: name of ldap-client-auth, see ldap(5)): LDAP-CLIENT-AUTH section name

timeout-idle [sec];

Number of seconds until cached group membership expires when the client is idle (sends no requests).

sec (type: uint32, optional, default: 7200)

timeout-unauth [sec];

Maximum time after which cached group membership expires.

sec (type: uint32, optional, default: 86400)

lock none;

lock semaphore;

lock lock2 [path];

lock [multilock2] [path];

An alternative implemetation of locks.

<branching element> (type: lock-type, optional, default: multilock2)
path (type: str, optional, default: <NULL>): If set to directory, file in that directory is created with name PREFIX.PID.XXXXXX, where PREFIX is a string defined by the proxy, PID is the proxy parent process ID and X is a random suffix. If not set, directory /tmp is assumed. Automatic generation of lock file name is strongly recommended, because each lock must have a unique name.

lock-ldap [val];

Whether getting groups from LDAP should be protected by LOCK. Locking may be used if the proxy is slowed down by many child processes performing Kerberos authentication to a LDAP server at the same time.

val (type: yes-no, optional, default: no)

one-per-session [val];

Whether Kerberos authentication should be performed only once per session. Authentication headers in requests following successful authentication are ignored.

val (type: yes-no, optional, default: yes)

[End of section kerberos-auth description.]

http-proxy name {

  phase ... ;
* tag ... ;
  log-debug { ... }
  log-stats { ... }
  use-resolver ... ;
  cfg-resolution ... ;
  monitoring { ... }
  stats-daily { ... }
  stats-weekly { ... }
  stats-monthly { ... }
  nodaemon ... ;
  singleproc ... ;
  app-user ... ;
  idle-timeout ... ;
  run-block-sigalrm ... ;
  listen-on { ... }
  tcpserver { ... }
  source-address ... ;
  doctype-identification { ... }
  client-conn { ... }
  server-conn { ... }
  document-root ... ;
  hdr-line-len ... ;
  blacklist-db ... ;
  connect-data-mime-db ... ;
  ftp-proxy ... ;
  max-aproxy-sessions ... ;
  max-bypass-sessions ... ;
  oob-auth-srv ... ;
  ssl-session-cache { ... }
  aproxy-lock ... ;
  cookie-table { ... }
  extended-status ... ;
* session-acl name { ... }
* request-acl name { ... }
* doc-acl name { ... }
}

HTTP proxy configuration.

The http-proxy section is derived from proxy section prototype. For detail description of it, see application(5).

Changes to the http-proxy section:

Section udpserver is not valid.

At least one SESSION-ACL must be specified (proxy must be named in some SYSTEM.ACL.SERVICES).

At least one REQUEST-ACL must be specified.

At least one DOC-ACL must be specified.

Document root path required.

BLACKLIST-DB required by REQUEST-ACL.BLACKLIST and DOC-ACL.BLACKLIST.

Section monitoring (see monitoring(5))

Item data used as uri.

Item listen-on.non-transparent (see listen-on(5))

Element port is optional, default: 80.

Element proto is optional, default: tcp.

Item listen-on.transparent (see listen-on(5))

Element port is optional, default: 80.

Element proto is optional, default: tcp.

Item tcpserver.init-children (see tcpserver(5))

Element value is optional, default: 50.

Item tcpserver.max-children (see tcpserver(5))

Element value is optional, default: 1500.

Item tcpserver.min-idle (see tcpserver(5))

Element value is optional, default: 50.

Item tcpserver.max-idle (see tcpserver(5))

Element value is optional, default: 70.

Added items & subsections:

client-conn {

  recv-bufsize ... ;
  close-timeout ... ;
  send-bufsize ... ;
  log-limit ... ;
}

Connection from client options.

The client-conn section is derived from sock-opt section prototype. For detail description of it, see netio(5).

Changes to the client-conn section:

Item conn-timeout is not valid.

Item recv-timeout is not valid.

Item send-timeout is not valid.

server-conn {

  conn-timeout ... ;
  recv-bufsize ... ;
  close-timeout ... ;
  send-bufsize ... ;
  log-limit ... ;
}

Connection to server options.

The server-conn section is derived from sock-opt section prototype. For detail description of it, see netio(5).

Changes to the server-conn section:

Item recv-timeout is not valid.

Item send-timeout is not valid.

document-root path;

Directory containing error documents and forced responses.

path (type: name of shared-dir, see common(5))

hdr-line-len [bytes];

Maximum (multi)line length in HTTP message headers (sets buffer size in header processing modules)

bytes (type: uint32, optional, default: 12Ki)

blacklist-db fname;

Name of DB file with a blacklist

fname (type: str)

connect-data-mime-db filename;

CONNECT data MIME type mapping file.

filename (type: name of shared-file, see common(5))

ftp-proxy addr anon-usr anon-pass;

Parameters for ftp-proxy used for ftp scheme requests

addr (type: sock): address of ftp-proxy
anon-usr (type: str): username for anonymous FTP
anon-pass (type: str): password for anonymous FTP

max-aproxy-sessions [val];

Maximum number of simultaneously active sessions.

val (type: uint16, optional, default: 100)

max-bypass-sessions [num];

Maximum number of simultaneous Clear Web DataBase bypass sessions. If set to 0, then bypass session management will use cookies instead, which limits a bypass to a single domain only.

num (type: uint32, optional, default: 1000)

oob-auth-srv name;

Parameters of OOB authentication server.

name (type: name of oob-auth, see auth(5))

ssl-session-cache {

  capacity ... ;
  dir ... ;
  lock ... ;
}

The ssl-session-cache section is derived from ssl-session-cache section prototype. For detail description of it, see ssl(5).

aproxy-lock [path];

Lock for exclusive access to the authentication proxy and OOB authentication session tables.

path (type: str, optional, default: <NULL>): If set to directory, file in that directory is created with name PREFIX.PID.XXXXXX, where PREFIX is a string defined by the proxy, PID is the proxy parent process ID and X is a random suffix. If not set, directory /tmp is assumed. Automatic generation of lock file name is strongly recommended, because each lock must have a unique name.

cookie-table {

  file ... ;
  clean ... ;
  size ... ;
  max-age ... ;
}

Table of modified cookies.

Items & subsections:

file [path];

Database file for storing the table.

path (type: str, optional, default: "/tmp/http-proxy.cookie-table")

clean [when];

When to clean then table.

when (type: cookie-table-clean, optional, default: on-restart)

size [sz];

Maximum number of stored cookies.

sz (type: uint32, optional, default: 1024)
Constraints:: Cookie table size must be at least 1.

max-age [sec];

Cookie lifetime (seconds). If a cookie itself specifies shorter lifetime, the shorter value is used instead.

sec (type: uint32, optional, default: 36000)
Constraints:: Cookie lifetime must not be zero.

[End of section http-proxy.cookie-table description.]

extended-status [val];

Permit status codes in statistical messages other than ACCEPTED and REJECTED

val (type: yes-no, optional, default: yes)

session-acl name {

* from ... ;
* to ... ;
* time ... ;
  time-period-set { ... }
  deny ... ;
  accept ... ;
* doctype-ident-order ... ;
  rule ... ;
  auth ... ;
  idle-timeout ... ;
  source-address ... ;
  plug-to ... ;
  captured-connect ... ;
* connect-session-acl ... ;
* connect-request-acl ... ;
* ip-tos-from-client ... ;
  linger-time ... ;
  client-keepalive ... ;
  server-keepalive ... ;
  language ... ;
  hand-off ... ;
  client-ssl ... ;
  server-ssl ... ;
* client-cert-match ... ;
* server-cert-match ... ;
  simulate-connect ... ;
  sni-insp ... ;
  aproxy ... ;
  ntlm-auth ... ;
  kerberos-auth ... ;
  authenticate-at ... ;
  acl-error-status ... ;
  server-from-tcp ... ;
}

The session-acl section is derived from acl-1 section prototype. For detail description of it, see acl(5).

Changes to the session-acl section:

Item user is not valid.

Item idle-timeout-peer is not valid.

SSL/TLS required on connection in order to match client certificates.

Authentication method must be set.

CONNECT-SESSION-ACL requires CAPTURED-CONNECT.

CONNECT-REQUEST-ACL requires CAPTURED-CONNECT.

Only one of NTLM-AUTH and KERBEROS-AUTH may be used.

Only one of SIMULATE-CONNECT and SNI-INSP may be used.

CLIENT-SSL and SNI-INSP are mutually exclusive.

SERVER-SSL and SNI-INSP are mutually exclusive.

Item auth (see auth(5))

Element mode is optional, default: allowed.

Added items & subsections:

captured-connect [test];

A test if this session handles a captured CONNECT request (instead of creating a tunnel to the destination server).

test (type: yes-no, optional, default: no)

connect-session-acl name;

SESSION-ACL used to handle the captured CONNECT request.

name (type: str-set)

connect-request-acl name;

REQUEST-ACL used to handle the captured CONNECT request.

name (type: str-set)

ip-tos-from-client val;

Testing an IP TOS value of received packets.

val (type: uint8-set)

linger-time [seconds];

Read end of client connection will linger for EOF after closing the write end.

seconds (type: uint32, optional, default: 1)

client-keepalive [req req] [idle idle];

Parameters of client connection keep-alive.

req req (type: uint16, optional, default: 100): max. number of requests on single connection (0 = unlimited, 1 = persistent client connections not used)
idle idle (type: uint16, optional, default: 15): max. idle time before the first request or between requests on single connection (0 = unlimited)

server-keepalive [req req] [idle idle] [conn conn];

Parameters of server connection keep-alive.

req req (type: uint16, optional, default: 100): max. number of requests on single connection (0 = unlimited, 1 = persistent client connections not used)
idle idle (type: uint16, optional, default: 15): max. idle time between requests (0 = unlimited)
conn conn (type: uint16, optional, default: 4): max. number of simultaneously open persistent connections to servers

language [lang];

Language of responses generated by Kernun.

If omitted in SESSION-ACL, English is used.If omitted in higer layer ACLs, settings from lower layer is used.

lang (type: language, optional, default: EN)

hand-off addr;

Next-hop proxy.

addr (type: sock)

client-ssl params;

Use SSL/TLS on the connection from a client.

params (type: name of ssl-params, see ssl(5))

server-ssl params;

Parameters of SSL/TLS for the connection to a server.

This item is valid only if the client SSL-PARAMS section forces faking of the server certificate for the client.

params (type: name of ssl-params, see ssl(5))

client-cert-match [subject subject] [issuer issuer];

Requirements for client certificate.

subject subject (type: str-set, optional, default: *): acceptable certificate subjects
issuer issuer (type: str-set, optional, default: *): acceptable certificate issuers

server-cert-match [subject subject] [issuer issuer];

Requirements for server certificate.

subject subject (type: str-set, optional, default: *): acceptable certificate subjects
issuer issuer (type: str-set, optional, default: *): acceptable certificate issuers

simulate-connect;

Behave as if the client issued a CONNECT request to the client connection destination address. Establish a TCP tunnel to the server. Note that the item CAPTURE-CONNECT cannot be used afterwards; use SNI-INSP instead of SIMULATE-CONNECT in such case.

sni-insp;

Obtain server name identifier for use in item sni-result of request ACLs.

aproxy name;

Act as an authentication proxy for HTTP servers.

name (type: name of aproxy, see above)

ntlm-auth name;

Enable NTLM authentication of clients.

name (type: name of ntlm-auth, see above)

kerberos-auth name [proxy-host];

Enable Kerberos authentication of clients.

name (type: name of kerberos-auth, see above)
proxy-host (type: str, optional, default: ""): The proxy host name expected in authentication data from clients. This is also the proxy host name that users should set in their browser configuration. The specified host name will be used in the proxy Kerberos principal (HTTP/proxy-host). If not set, the host name of the Kernun system will be used. This value overrides a value set in the referenced KERBEROS-AUTH section.

authenticate-at [val];

Whether the proxy will ask the client to perform proxy authentication (the default), or authentication at the origin server.

val (type: auth-headers, optional, default: proxy)

acl-error-status code;

Status code returned when a request is denied by ACL. If not set, default is 403 Forbidden.

code (type: uint16)

server-from-tcp [val];

Specifies which destination IP address is used for connecting to the server, in transparent sessions. By default the destination IP address of the original client TCP connection is used. If set to 'NO', the address specified inside the HTTP protocol (HTTP request) is used, i.e. the Host header or the host part of the request URI.

val (type: yes-no, optional, default: yes)

[End of section http-proxy.session-acl description.]

request-acl name {

* from ... ;
* server ... ;
* user ... ;
* time ... ;
  time-period-set { ... }
* session-acl ... ;
  deny ... ;
  accept ... ;
* doctype-ident-order ... ;
  rule ... ;
  source-address ... ;
  plug-to ... ;
* request-method ... ;
* request-scheme ... ;
* request-uri ... ;
* request-path ... ;
* referer ... ;
* blacklist ... ;
* request-version ... ;
* user-agent ... ;
* client-cert-match ... ;
* aproxy-user ... ;
* clear-web-db-match ... ;
  clear-web-db-bypass { ... }
  web-filter ... ;
  host-hdr-transp ... ;
* rewrite ... ;
  http-host ... ;
  uri-decode ... ;
  hand-off ... ;
  select-optimization ... ;
  allow-req-hdr ... ;
  delete-req-hdr-range ... ;
  allow-resp-hdr ... ;
* add-req-hdr ... ;
* add-resp-hdr ... ;
  ftp-force-utf-8 ... ;
* req-line-check ... ;
* req-hdr-check ... ;
* status-line-check ... ;
* resp-hdr-check ... ;
  accept-gzip ... ;
  content-gzip ... ;
  request-via ... ;
  response-via ... ;
  request-time ... ;
  language ... ;
  auth-req ... ;
  oob-add { ... }
  max-bytes ... ;
  dechunk-ignore-eof ... ;
  server-ssl ... ;
* server-cert-match ... ;
  sni-result ... ;
  client-altq ... ;
  server-altq ... ;
  ip-tos-to-client { ... }
  ip-tos-to-server { ... }
  file-response ... ;
  program-response ... ;
  library-response { ... }
  request-end-program ... ;
* program-env ... ;
  connect-data-filter-client ... ;
  connect-data-filter-server ... ;
  capture-connect ... ;
* modify-cookies ... ;
  delete-cookies ... ;
  request-body-match ... ;
  request-body-max-size ... ;
  replace-authorization ... ;
  acl-error-status ... ;
  deny-msg ... ;
}

The request-acl section is derived from acl-2 section prototype. For detail description of it, see acl(5).

Changes to the request-acl section:

Item parent-acl used as session-acl.

SSL/TLS required on connection in order to match server certificates.

FILE-RESPONSE cannot be combined with HAND-OFF or PLUG-TO.

PROGRAM-RESPONSE cannot be combined with HAND-OFF or PLUG-TO.

LIBRARY-RESPONSE cannot be combined with HAND-OFF or PLUG-TO.

Only one of FILE-RESPONSE, PROGRAM-RESPONSE, and LIBRARY-RESPONSE can be set.

CAPTURE-CONNECT cannot be combined with AUTH-REQ, HAND-OFF, PLUG-TO, FILE-RESPONSE, PROGRAM-RESPONSE and LIBRARY-RESPONSE.

Items DENY and CLEAR-WEB-DB-BYPASS are mutually exclusive.

Item CLEAR-WEB-DB-BYPASS requires CLEAR-WEB-DB-MATCH.

Item DENY-MSG requires DENY.

Added items & subsections:

source-address [client] [addr4 addr4] [addr6 addr6] cluster [cluster];

source-address [client] [addr4 addr4] [addr6 addr6] [physical];

source-address [client] [addr4 addr4] [addr6 addr6] no-fallback;

Source address for outgoing connections to servers.

If omitted, the proper address of the proxy will be used, i.e. in the case of a cluster, the cluster address will be used.

If not specified by the SOURCE-PORT item, a generic port will be used.

The elements entered within this item will be used by the proxy until the first of them is applicable:

- The CLIENT keyword means the original client IP address is used. This mode will be succesful in all cases except mismatch of IP address families.

- The ADDR4/ADDR6 keyword-value pairs mean that the specified address is used for a connection of corresponding address family.

- The CLUSTER keyword means that one of cluster addresses will be used. By default, the main address of the bridge is used, however, any preferred alias address can be listed in the cluster list.- The PHYSICAL option means that the address of the physical interface is used instead of the cluster one.

- The DEFAULT option means the default behavior - i.e. using of the physical address.

- The NO-FALLBACK option means that if no other way of setting the address is acceptable, the session is rejected. Without this option, the system tries to find a suitable source IP address automatically.

client (type: key, optional)
addr4 addr4 (type: host, optional, default: [0.0.0.0])
addr6 addr6 (type: host, optional, default: [::])
<branching element> (type: source-address-mode, optional, default: physical)
cluster (type: host-list, optional, default: {})
Constraints:: Address family must respect the element's address family..

plug-to addr;

Final destination server.

addr (type: sock)

Address/port of final destination server.

If port is zero, then original port is used.

request-method val;

Request methods to which this ACL is applicable.

val (type: str-set)

request-scheme val;

Matching scheme from request URI. If URI does not contain scheme, SCHEME-HTTP is assumed.

val (type: http-scheme-set)

request-uri val;

Matching the whole request URI. Proxy URIs have form <SCHEME>://<HOST>[:PORT]<PATH>[?<QUERY>], e.g., http://www.tns.cz:80/kernun/index.html.

val (type: str-set)

request-path val;

Matching request URI path.

val (type: str-set)

referer val;

Matching Referer HTTP header.

val (type: str-set)

blacklist categories;

Select this ACL if request URI (server and possibly initial part of path) is found in the blacklist with at least one matching category.

categories (type: str-set)

request-version val;

HTTP protocol version in request.

val (type: http-protocol-set)

user-agent val;

Select an ACL according to the User-AgentHTTP header.

val (type: str-set)

client-cert-match [subject subject] [issuer issuer];

Select an ACL according to a client certificate.

subject subject (type: str-set, optional, default: *): acceptable certificate subjects
issuer issuer (type: str-set, optional, default: *): acceptable certificate issuers

aproxy-user none;

aproxy-user [name] [name [group group]];

User and group specification.

<branching element> (type: user-auth-spec, optional, default: name)
name (type: str-set, optional, default: *): user name (authenticated on firewall)
group group (type: str-set, optional, default: *): list of groups, if present, both NAME and GROUP must match

clear-web-db-match [any] categories-set;

clear-web-db-match all categories-list;

clear-web-db-match subset categories-set;

clear-web-db-match exact categories-list;

Clear Web Matching Control.

This item is used as an ACL entry condition for a URL based on Clear Web category matching.

<branching element> (type: clear-web-db-match-mode, optional, default: any)
categories-set (type: clear-web-db-category-set)
categories-list (type: clear-web-db-category-list)

clear-web-db-bypass {

  status ... ;
  cookie ... ;
  activation ... ;
  duration ... ;
}

The clear-web-db-bypass section is derived from clear-web-db-bypass section prototype. For detail description of it, see clear-web-db(5).

web-filter name;

Enables web filter and selects web filter server

name (type: name of web-filter, see above)

host-hdr-transp [enable-loopback];

Enables transparent proxy behavior for non-transparent connections. If the request URI contains only path and no server address, uses the content of the Host header as the server address.

enable-loopback (type: key, optional): Permits connections to local addresses.

rewrite match subst [redirect redirect];

Change request URI.

match (type: regexp): URIs matching this regular expression
subst (type: str): will be substituted with this ($1..$9 are references to parenthesized subexpressions of MATCH, $$ means $)
redirect redirect (type: http-redirect, optional, default: undefined): the proxy will return HTTP redirect with the rewritten URI instead of directly serving the rewritten URI

http-host addr;

Change request URI host and Host header.

addr (type: sock)

uri-decode [val];

Decode unreserved characters in a request URI encoded as %XX. This item must be set to NO for some clients or servers that require their URIs to be passed unmodified. Matching of REQUEST-URI and REQUEST-PATH is always done with decoded unreserved characters, regadless the value of this item.

val (type: yes-no, optional, default: no)

hand-off addr;

Next-hop proxy.

addr (type: sock)

select-optimization [c2s [s2c]];

Optimization of read/write/select operations.

c2s (type: uint32, optional, default: 0): max. number of client->server reads/writes without calling select
s2c (type: uint32, optional, default: 0): max. number of server->client reads/writes without calling select

allow-req-hdr name;

Pass only these request headers. If not used, all request headers.

name (type: str-set): names of allowed headers

delete-req-hdr-range;

Remove request header Range.

allow-resp-hdr name;

Pass only these response headers.

name (type: str-set): names of allowed headers

add-req-hdr name value;

Add a request header. The header is added literaly and does not replace any already existing header of the same name. The header is not checked for compliance with RFC.

name (type: str): Header name.
value (type: str): Header value.

add-resp-hdr name value;

Add a response header. The header is added literaly and does not replace any already existing header of the same name. The header is not checked for compliance with RFC.

name (type: str): Header name.
value (type: str): Header value.

ftp-force-utf-8;

When retrieving and displaying FTP directory, use UTF-8.

It means sending the "OPTS UTF8 ON" command to the server, and adding the "charset=UTF-8" info to the web page displayed.

req-line-check text-match max-len;

Check of request line.

text-match (type: str-set): The line must match this.
max-len (type: uint32): Maximum number of characters in the line

req-hdr-check name-match val-match max-val-len;

Check of request headers.

name-match (type: str-set): The header name must match this.
val-match (type: str-set): The header value must match this.
max-val-len (type: uint32): Maximum number of characters of the header value

status-line-check text-match max-len;

Check of response status line.

text-match (type: str-set): The line must match this.
max-len (type: uint32): Maximum number of characters in the line

resp-hdr-check name-match val-match max-val-len;

Check of response headers.

name-match (type: str-set): The header name must match this.
val-match (type: str-set): The header value must match this.
max-val-len (type: uint32): Maximum number of characters of the header value

accept-gzip [gzip-only];

Modify Accept-Encoding header so that only identity and gzip encodings will be accepted. This is useful if the response will be passed to HTML filter later.

gzip-only (type: accept-gzip, optional, default: client-add)

content-gzip [mode];

Convert between gzip and x-gzip in the Content-Encoding response header.

mode (type: content-gzip, optional, default: accept)

request-via pass;

request-via add [faked];

request-via full [faked];

request-via [block];

request-via fake [faked];

Processing Via headers in requests.

<branching element> (type: proxy-via, optional, default: block)
faked (type: str, optional, default: ""): full Via header value if FAKE, replacement for firewall hostname for ADD, FULL

response-via pass;

response-via add [faked];

response-via full [faked];

response-via [block];

response-via fake [faked];

Processing Via headers in responses.

<branching element> (type: proxy-via, optional, default: block)
faked (type: str, optional, default: ""): full Via header value if FAKE, replacement for firewall hostname for ADD, FULL

request-time seconds;

Limited time of single request.

seconds (type: uint32)

language lang;

Language of responses generated by Kernun.

If omitted in SESSION-ACL, English is used.If omitted in higer layer ACLs, settings from lower layer is used.

lang (type: language)

auth-req realm;

Send authentication request back to client.

realm (type: str): realm sent to clients

oob-add {

  timeout-idle ... ;
  timeout-unauth ... ;
}

If this is an OOB authentication server and the user has been authenticated successfully, add the user to the OOB authentication session table.

Items & subsections:

timeout-idle [sec];

Number of seconds until authentication expires when the client is idle (sends no requests).

sec (type: uint32, optional, default: 360)

timeout-unauth [sec];

Maximum time after which authentication expires.

sec (type: uint32, optional, default: 3600)

[End of section http-proxy.request-acl.oob-add description.]

max-bytes [cout [cin [sout [sin]]]];

Maximum number of transferred bytes (0 = unlimited).

cout (type: uint64, optional, default: 0): (received from client)
cin (type: uint64, optional, default: 0): (sent to client)
sout (type: uint64, optional, default: 0): (sent to server)
sin (type: uint64, optional, default: 0): (received from server)

dechunk-ignore-eof [val];

Ignore premature connection close by a server when waiting for a chunk (behave as if there was a terminating zero-sized chunk).

val (type: yes-no, optional, default: no)

server-ssl params;

Use SSL/TLS on the connection to a server.

params (type: name of ssl-params, see ssl(5))

server-cert-match [subject subject] [issuer issuer];

Requirements for server certificate.

subject subject (type: str-set, optional, default: *): acceptable certificate subjects
issuer issuer (type: str-set, optional, default: *): acceptable certificate issuers

sni-result [result];

Result of the SNI inspection. Default value is "specified".

result (type: sni-result-set, optional, default: {})

client-altq altq [paltq paltq];

ALTQ queues for data sent to client.

altq (type: name of pf-queue, see pf-queue(5)): queue name
paltq paltq (type: name of pf-queue, see pf-queue(5), optional, default: NULL): priority queue name (if set, used for TCP ACK without data)

server-altq altq [paltq paltq];

ALTQ queues for data sent to server.

altq (type: name of pf-queue, see pf-queue(5)): queue name
paltq paltq (type: name of pf-queue, see pf-queue(5), optional, default: NULL): priority queue name (if set, used for TCP ACK without data)

ip-tos-to-client {

  fixed ... ;
  received ... ;
  other ... ;
}

The ip-tos-to-client section is derived from ip-tos-to-client section prototype. For detail description of it, see netio(5).

ip-tos-to-server {

  fixed ... ;
  received ... ;
  other ... ;
}

The ip-tos-to-server section is derived from ip-tos-to-server section prototype. For detail description of it, see netio(5).

file-response [status-code status-code] [mime-type mime-type] [path [request-uri]];

Do not contact a server and send a local file obtained by concatenating the document-root path and the specified file path or the request URI path.

status-code status-code (type: uint16, optional, default: 200): status code of response
mime-type mime-type (type: str, optional, default: "text/html"): Document Content-Type.
path (type: str, optional, default: ""): Path of the response file (under DOCUMENT-ROOT).
request-uri (type: key, optional): Append request URI path after request (return file selected by request URI in subdirectory PATH of DOCUMENT-ROOT).

program-response path [runtime];

Do not contact a server and start a program. The program is passed the complete request to the standard input. The standard output of the program is sent to the client. The program mustgenerate a complete response beginning with a response lineand headers.

path (type: name of shared-file, see common(5)): Program name.
runtime (type: uint32, optional, default: 10): Maximum allowed runtime of the program (seconds). After expiration, the program is signalled by SIGTERM. If zero, the allowed runtime is unlimited.

library-response {

lib ... ;
* param ... ;
}

Constraints:

Item LIB must be specified.

Items & subsections:

lib path;

Path to the shared library.

path (type: str)

param name value;

Optional parameters for the library.

name (type: str): Parameter name.
value (type: str): Parameter value.

[End of section http-proxy.request-acl.library-response description.]

request-end-program path;

A program executed asynchronously by the proxy when a request processing finishes.

path (type: name of shared-file, see common(5)): Program name.

program-env name val;

Additional environment variables passed to programs executed PROGRAM-RESPONSE and REQUEST-END-PROGRAM.

name (type: str): Name of the environment variable.
val (type: str): Value of the environment variable.

connect-data-filter-client rules;

Client CONNECT data filtering.

rules (type: name of data-match, see mod-match(5))

connect-data-filter-server rules;

Server CONNECT data filtering.

rules (type: name of data-match, see mod-match(5))

capture-connect [stats-log stats-log];

In the case of a CONNECT request, restart the session and handle the communication itself instead of creating a TCP tunnel to the destination server.

stats-log stats-log (type: yes-no, optional, default: no): Whether statistics log message is produced for capture-connect request itself. Stats messages for the requests performed later in this 'caputre-connected' session are not affected by this value, they are logged anyway.

modify-cookies name [params params] [max-age max-age] [any-client] [keep-not-found];

Matching cookies will be modified so that they are useless outside the internal network.

name (type: str-set): Modify only cookies with matching name.
params params (type: str-set, optional, default: *): Modify only cookies with matching parameters. Is matched against the string containing all cookie parameters following the cookie NAME and VALUE.
max-age max-age (type: uint32, optional, default: 0): Cookie lifetime (seconds). If zero or not set, the value from HTTP-PROXY.COOKIE-TABLE.MAX-AGE is used. If a cookie itself specifies shorter lifetime, the shorter value is used instead.
any-client (type: key, optional): Modify a cookie even if it comes from other client address than it was previously sent to.
keep-not-found (type: key, optional): Keep the cookie value unchanged if not found in the cookie table. Otherwise, values of unknown cookies are set to the empty string.

delete-cookies [ip-from-query];

Delete all cookies for the client IP in the cookie table.

ip-from-query (type: key, optional): Use IP address written in the query part of the request URI instead of the client IP address.

request-body-match rules;

Rules for matching content of the request body.

rules (type: name of data-match, see mod-match(5))

request-body-max-size bytes;

Maximum size of the request body.

bytes (type: uint64)

replace-authorization [simple] db-file [keep-not-found] [replace-not-found replace-not-found];

replace-authorization radius db-file [keep-not-found] [replace-not-found replace-not-found] radius radius radius-delimiter radius-delimiter;

Replaces user name and password in a request Authorization header.

<branching element> (type: replace-authorization-mode, optional, default: simple): Mode of the authorization replacement
db-file (type: str): A database file for replacement. It must be in the format used by action HTML-REPLACE in REQUEST-BODY-MATCH.RULES. Each record of the replacement database must contain two values: user name and password.
keep-not-found (type: key, optional): If set and replacement values are not found in the database, pass the selected HTML form controls unchanged. Otherwise, values of the selected controls are deleted.
replace-not-found replace-not-found (type: str, optional, default: <NULL>): If set and replacement values are not found in the database, replace values of the selected HTML form controls by this value.
radius radius (type: name of radius-client, see radius(5)): Radius client configuration to be used for authentication.
radius-delimiter radius-delimiter (type: str): A single character used as delimiter of the internal password and the radius password. Last occurence of the delimiter is used. If not present in the particular password, all the password text is interpreted as the radius password.
Constraints:: Only one of elements KEEP-NOT-FOUND and REPLACE-NOT-FOUND may be specified.

acl-error-status code;

Status code returned when a request is denied by ACL. If not set, default is 403 Forbidden.

code (type: uint16)

deny-msg [template template] [msg];

The error page returned when a request is denied by ACL. If not set, a generic "denied by security policy" page is returned, except when the denying ACL contains item CLEAR-WEB-DB-MATCH. In this case, the returned page will display the categories of the request URI that match the CLEAR-WEB-DB-MATCH item. See also http-proxy(8) for the instructions how to create custom error pages.

template template (type: str, optional, default: ""): error page template file name, without the .html.LANGUAGE-CHARSET suffix, relative to the DOCUMENT-ROOT directory
msg (type: str, optional, default: ""): a message inserted into the error page template

[End of section http-proxy.request-acl description.]

doc-acl name {

* from ... ;
* server ... ;
* user ... ;
* time ... ;
  time-period-set { ... }
* request-acl ... ;
  deny ... ;
  accept ... ;
  rule ... ;
* content-type ... ;
* mime-type ... ;
  force-doctype-ident ... ;
  html-filter ... ;
* request-scheme ... ;
* referer ... ;
* request-path ... ;
* blacklist ... ;
  set-mime-type ... ;
  replace-response ... ;
  jpeg-scan-sz ... ;
* filter-images ... ;
  antivirus ... ;
  accept-antivirus-status ... ;
  response-body-match ... ;
  client-altq ... ;
  server-altq ... ;
  deny-msg ... ;
}

The doc-acl section is derived from acl-3 section prototype. For detail description of it, see acl(5).

Changes to the doc-acl section:

Item parent-acl used as request-acl.

Item direction is not valid.

Item size is not valid.

Item virus-status is not valid.

Item modify-header is not valid.

Item replace is not valid.

SET-MIME-TYPE and REPLACE-RESPONSE are mutually exclusive.

SET-MIME-TYPE and FORCE-DOCTYPE-IDENT are mutually exclusive.

REPLACE-RESPONSE and FORCE-DOCTYPE-IDENT are mutually exclusive.

Item DENY-MSG requires DENY..

Added items & subsections:

request-scheme val;

Matching scheme from request URI. If URI does not contain scheme, SCHEME-HTTP is assumed.

val (type: http-scheme-set)

referer val;

Matching Referer HTTP header.

val (type: str-set)

request-path val;

Matching request URI path. Proxy URIs have form [<SCHEME>://<HOST>[:PORT]]<PATH>[?<QUERY>], e.g., http://www.tns.cz:80/kernun/index.html

val (type: str-set)

blacklist categories;

Select this ACL if request URI (server and possibly initial part of path) is found in the blacklist with at least one matching category.

categories (type: str-set)

set-mime-type val;

Set Content-Type header sent to the client.

val (type: str)

replace-response status-code mime-type path;

Send a local file instead of a server response.

status-code (type: uint16): status code of response
mime-type (type: str): Document Content-Type.
path (type: str): file to send (relative to document-root if relative path)

jpeg-scan-sz [sz];

Maximum length of the initial part of an JPEG image file scanned for image type and size.

sz (type: uint16, optional, default: 1024)

filter-images width height path;

Send a local file instead of some images (MIME types image/gif, image/jpeg, image/png). Matching is done according to image size, image which has invalid format orunknown size is treated as 0 x 0 image for matching.

width (type: uint16-set): images width
height (type: uint16-set): images height
path (type: str): file to send (relative to document-root if relative path), an extension according to type (.gif/.jpeg/.png) will be appended

antivirus channel [interval interval] [chunk chunk] [limit limit];

Antivirus usage mode.

Check document by antivirus, with settings for passing initial part of unchecked data through the antivirus module during antivirus checking.

channel (type: name-list of antivirus, see antivirus(5)): Name of ANTIVIRUS global section used.
interval interval (type: uint16, optional, default: 0): Seconds between passing blocks of unchecked data (0 = do not send unchecked data).
chunk chunk (type: uint32, optional, default: 0): Size of each block of unchecked data.
limit limit (type: uint32, optional, default: 0): Maximum size of unchecked data passed before antivirus check is completed. Remaining data will be passed only after successful checking.

accept-antivirus-status status;

Defines set of antivirus status codes (in addition to FREE) that allow further passing of data. Other status codes cause termination of data transfer. If not set, data are passed only if the antivirus returns status FREE.

status (type: virus-status-set)

response-body-match rules;

Rules for matching content of the response body.

rules (type: name of data-match, see mod-match(5))

client-altq altq [paltq paltq];

ALTQ queues for data sent to client.

altq (type: name of pf-queue, see pf-queue(5)): queue name
paltq paltq (type: name of pf-queue, see pf-queue(5), optional, default: NULL): priority queue name (if set, used for TCP ACK without data)

server-altq altq [paltq paltq];

ALTQ queues for data sent to server.

altq (type: name of pf-queue, see pf-queue(5)): queue name
paltq paltq (type: name of pf-queue, see pf-queue(5), optional, default: NULL): priority queue name (if set, used for TCP ACK without data)

deny-msg [template template] [msg];

template template (type: str, optional, default: ""): error page template file name, without the .html.LANGUAGE-CHARSET suffix, relative to the DOCUMENT-ROOT directory
msg (type: str, optional, default: ""): a message inserted into the error page template

[End of section http-proxy.doc-acl description.]

[End of section http-proxy description.]

Prev	Up	Next
http-control	Home	http-proxy.cfg

Name

DESCRIPTION

TYPES

ITEMS AND SECTIONS

SEE ALSO