proxy-ng
Prev Kernun UTM Reference (5) Next

Name

proxy-ng — format of proxy-ng 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 proxy-ng 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 proxy-ng configuration directives:

yes-no (see common(5))

ip-version (see common(5))

time-cond (see common(5))

zip-mode (see common(5))

dbglev (see log(5))

logfail-mode (see log(5))

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

session-protocol (name-usage optional)

Protocol for handling a TCP session.

tcp-proxy (0)

TCP proxy mode, no application protocol handling.

tcp-proxy-transparent (1)

TCP proxy mode, no application protocol handling, connects to the destination address of the connection from the client unless overriden by PLUG-TO.

http-proxy (2)

HTTP proxy mode.

json-type (name-usage obligatory)

Types of JSON values

raw

Raw JSON value of any type (scalar, array, or object)

null

Null value

false

Boolean false value

true

Boolean true value

uint

Unsigned integer

fract

Fractional value with 3 decimal places

str

String value

http-version (name-usage obligatory)

Version of HTTP.

HTTP-1-0, HTTP-1-1

ITEMS AND SECTIONS

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


* json-value ... ;
  log-ng { ... }
* acl-ng name { ... }
* session-acl-ng name { ... }
* http-request-acl-ng name { ... }
* http-doc-acl-ng name { ... }
* proxy-ng name { ... }
    

Description:

json-value raw raw;

json-value null path;

json-value false path;

json-value true path;

json-value uint path num_ui;

json-value fract path num_f;

json-value str path string;

A generic JSON value.

<branching element> (type: json-type)

Type of the value.

raw (type: str)

A raw string that will be parsed as an arbitrarily complex JSON.

path (type: str-list)

A path to an object element. It is the list of names of nested active level configuration JSON objects containing the value. The last is the name of the element name in the innermost object.

num_ui (type: uint64)

A value of the object element.

num_f (type: fract)

A value of the object element.

string (type: str)

A value of the object element.

Constraints:

Invalid JSON in RAW..

PATH must not be empty..

log-ng {


  level ... ;
  facility ... ;
  file ... ;
  rotate ... ;
  enabled ... ;
}

        

The log-ng section is derived from log section prototype. For detail description of it, see log(5).

Changes to the log-ng section:

Item mem-level is not valid.

Item mem-file is not valid.

Item syslog-failure is not valid.

Item data-limit is not valid.

Item dump-hold-time is not valid.

Item file (see log(5))

Section usec is not valid.

Added items & subsections:

enabled [val];

Whether the log is enabled.

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

[End of section log-ng description.]

acl-ng name {


* is-flagged ... ;
* not-flagged ... ;
* jval ... ;
  deny ... ;
  accept ... ;
  continue ... ;
  set-flag ... ;
  unset-flag ... ;
  set-rule ... ;
}

        

Access Control List.

Constraints:

Only one of ACCEPT, DENY is allowed..

Items & subsections:

is-flagged names;

Entry condition: Tests that all flags (or rule names) in the list are set.

names (type: str-list)

not-flagged names;

Entry condition: Tests that no flags (or rule names) from the list are set.

names (type: str-list)

jval raw raw;

jval null path;

jval false path;

jval true path;

jval uint path num_ui;

jval fract path num_f;

jval str path string;

An arbitrary JSON value set if this ACL matches.

<branching element> (type: json-type)

Type of the value.

raw (type: str)

A raw string that will be parsed as an arbitrarily complex JSON.

path (type: str-list)

A path to an object element. It is the list of names of nested active level configuration JSON objects containing the value. The last is the name of the element name in the innermost object.

num_ui (type: uint64)

A value of the object element.

num_f (type: fract)

A value of the object element.

string (type: str)

A value of the object element.

Constraints:

Invalid JSON in RAW..

PATH must not be empty..

deny;

Deny communication. This is the default if no ACL containing ACCEPT is applied.

accept;

Permit communication.

continue;

Do not stop checking ACLs if this ACL matches.

set-flag names;

Sets flags or rule names. See also SET-RULE.

names (type: str-list)

unset-flag names;

Unset flags or rule names. See also SET-RULE.

names (type: str-list)

set-rule names;

Sets rule names. A name used in a SET-RULE will be included in log messages if it is activated by a SET-FLAG or SET-RULE. All other names used in SET-FLAG, UNSET-FLAG, IS-FLAGGED, or NOT-FLAGGED, can be set, unset, or tested, but are not logged.

names (type: str-list)

[End of section acl-ng description.]

session-acl-ng name {


* is-flagged ... ;
* not-flagged ... ;
* jval ... ;
  deny ... ;
  accept ... ;
  continue ... ;
  set-flag ... ;
  unset-flag ... ;
  set-rule ... ;
* listen-socket-id ... ;
* from ... ;
* to ... ;
  protocol ... ;
  source-address ... ;
  plug-to ... ;
  http-error { ... }
  hand-off ... ;
}

        

Access Control List evaluated when a new TCP connection is accepted.

The session-acl-ng section is derived from acl-ng section prototype. For detail description of it, see above.

Added items & subsections:

listen-socket-id val;

Entry condition: LISTEN-SOCKET-ID of the listening socket.

val (type: str)

from addr;

Entry condition: Matches source IP address of a TCP connection from a client.

addr (type: host-set)

Set of client IP addresses or host names.

Constraints:

Regular expressions are not allowed in host set.

to addr [port port];

Entry condition: Matches destination IP address of a TCP connection from a client

addr (type: host-set)

Set of IP addresses or host names.

port port (type: port-set, optional, default: *)

Set of destination service names/port numbers.

Constraints:

Regular expressions are not allowed in host set.

protocol val;

Selects a protocol for handling the session.

val (type: session-protocol)

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.

http-error {


  error-document ... ;
* subst ... ;
}

            

Controls error responses to HTTP requests.

Items & subsections:

error-document filename;

Template of the HTTP error document.

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

subst name value;

Name/value pairs substituted to ERROR-DOCUMENT.

name (type: str)

value (type: str)

[End of section session-acl-ng.http-error description.]

hand-off val;

If YES, the proxy assumes that it connects to another proxy, not to the destination server.

val (type: yes-no)

[End of section session-acl-ng description.]

http-request-acl-ng name {


* is-flagged ... ;
* not-flagged ... ;
* jval ... ;
  deny ... ;
  accept ... ;
  continue ... ;
  set-flag ... ;
  unset-flag ... ;
  set-rule ... ;
* listen-socket-id ... ;
* from ... ;
* to ... ;
  source-address ... ;
  plug-to ... ;
  http-error { ... }
  hand-off ... ;
* req-method ... ;
* req-uri ... ;
* req-host ... ;
* req-path ... ;
* req-query ... ;
* req-version ... ;
}

        

Access Control List evaluated when request headers of an HTTP request are received from a client.

The http-request-acl-ng section is derived from session-acl-ng section prototype. For detail description of it, see above.

Changes to the http-request-acl-ng section:

Item protocol is not valid.

Added items & subsections:

req-method val;

The method of an HTTP request.

val (type: str-set)

req-uri val;

The request URI of an HTTP request.

val (type: str-set)

req-host addr [port port];

The host address from an HTTP request.

addr (type: host-set)

Set of IP addresses or host names.

port port (type: port-set, optional, default: *)

Set of destination service names/port numbers.

req-path val;

The path from an HTTP request URI.

val (type: str-set)

req-query val;

The query from an HTTP request URI.

val (type: str-set)

req-version val;

The HTTP version of an HTTP request.

val (type: http-version-set)

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

http-doc-acl-ng name {


* is-flagged ... ;
* not-flagged ... ;
* jval ... ;
  deny ... ;
  accept ... ;
  continue ... ;
  set-flag ... ;
  unset-flag ... ;
  set-rule ... ;
* listen-socket-id ... ;
* from ... ;
* to ... ;
  http-error { ... }
* req-method ... ;
* req-uri ... ;
* req-host ... ;
* req-path ... ;
* req-query ... ;
* req-version ... ;
* resp-status ... ;
* resp-version ... ;
}

        

Access Control List evaluated when response headers of an HTTP response are received from a server.

The http-doc-acl-ng section is derived from http-request-acl-ng section prototype. For detail description of it, see above.

Changes to the http-doc-acl-ng section:

Item source-address is not valid.

Item plug-to is not valid.

Item hand-off is not valid.

Added items & subsections:

resp-status val;

The status code of an HTTP response.

val (type: uint16-set)

resp-version val;

The HTTP version of an HTTP response.

val (type: http-version-set)

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

proxy-ng name {


  phase ... ;
* tag ... ;
  use-resolver ... ;
  nodaemon ... ;
  app-user ... ;
  log-debug { ... }
  log-stats { ... }
  resolver-ng { ... }
  listen-on { ... }
  tcpserver { ... }
* cfg-begin ... ;
* cfg-end ... ;
* jval ... ;
  log-audit { ... }
* session-acl name { ... }
  http-proxy { ... }
}

        

New unified multi-protocol proxy

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

Changes to the proxy-ng section:

Section exclude-log-debug is not valid.

Section log-debug used as exclude-log-debug.

Section exclude-log-stats is not valid.

Section log-stats used as exclude-log-stats.

Item cfg-resolution is not valid.

Section monitoring is not valid.

Section stats-daily is not valid.

Section stats-weekly is not valid.

Section stats-monthly is not valid.

Item singleproc is not valid.

Item idle-timeout is not valid.

Item run-block-sigalrm is not valid.

Section exclude-listen-on is not valid.

Section listen-on used as exclude-listen-on.

Section exclude-tcpserver is not valid.

Section tcpserver used as exclude-tcpserver.

Section udpserver is not valid.

Item source-address is not valid.

Section doctype-identification is not valid.

Added items & subsections:

log-debug {


  level ... ;
  facility ... ;
  file ... ;
  rotate ... ;
  enabled ... ;
}

            

The log-debug section is derived from log-ng section prototype. For detail description of it, see above.

Item facility (see log(5))

Element value is optional, default: 5.

log-stats {


  level ... ;
  facility ... ;
  file ... ;
  rotate ... ;
  enabled ... ;
}

            

The log-stats section is derived from log-ng section prototype. For detail description of it, see above.

Changes to the log-stats section:

Only values NORMAL (log top-level protocol only) and DEBUG (log all protocols) are allowed..

Item facility (see log(5))

Element value is optional, default: 6.

resolver-ng {


  cache-size ... ;
  refresh-time ... ;
  threads ... ;
}

            

Attributes for configuration of domain names resolution.

Items & subsections:

cache-size [val];

Number of cached resolved host names or IP addresses

val (type: uint32, optional, default: 10000)

refresh-time [val];

Time (seconds) after which cached DNS results are refreshed if they are used or deleted if they are unused.

val (type: fract, optional, default: 300)

threads [val];

Number of threads (parallel queries) used by DNS resolver.

val (type: uint8, optional, default: 20)

[End of section proxy-ng.resolver-ng description.]

listen-on {


* non-transparent ... ;
* transparent ... ;
}

            

Items & subsections:

non-transparent addr [version version] port port listen-socket-id listen-socket-id;

Sockets to bind for non-transparent connections.

addr (type: host)

Address to be bound

version version (type: ip-version, optional, default: undefined)

IP version selection

port port (type: port)

Port to be bound (lowest)

listen-socket-id listen-socket-id (type: str)

ID of the listening socket.

transparent listen-socket-id listen-socket-id;

Sockets to handle transparent connections.

listen-socket-id listen-socket-id (type: str)

ID of the listening socket.

[End of section proxy-ng.listen-on description.]

tcpserver {


  max-sessions ... ;
  queue-size ... ;
  worker-threads ... ;
}

            

General TCP server parameters.

Items & subsections:

max-sessions [value];

Maximum number of concurrent sessions from clients.

value (type: uint16, optional, default: 1500)

queue-size [value];

Queue length for listen(2) syscall, 0 for system default.

value (type: uint16, optional, default: 0)

worker-threads val;

Number of threads for handling network communication. If not set, a default value is determined according to the number of CPUs.

val (type: uint8)

[End of section proxy-ng.tcpserver description.]

cfg-begin filename;

Configuration files that will be read before the file generated from the CML configuration.

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

cfg-end filename;

Configuration files that will be read after the file generated from the CML configuration.

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

jval raw raw;

jval null path;

jval false path;

jval true path;

jval uint path num_ui;

jval fract path num_f;

jval str path string;

An arbitrary JSON value which is set unconditionally upon proxy startup.

<branching element> (type: json-type)

Type of the value.

raw (type: str)

A raw string that will be parsed as an arbitrarily complex JSON.

path (type: str-list)

A path to an object element. It is the list of names of nested active level configuration JSON objects containing the value. The last is the name of the element name in the innermost object.

num_ui (type: uint64)

A value of the object element.

num_f (type: fract)

A value of the object element.

string (type: str)

A value of the object element.

Constraints:

Invalid JSON in RAW..

PATH must not be empty..

log-audit {


  level ... ;
  facility ... ;
  file ... ;
  rotate ... ;
  enabled ... ;
}

            

The log-audit section is derived from log-ng section prototype. For detail description of it, see above.

Changes to the log-audit section:

Only values NORMAL (all audit messages) and ERROR (security violations attempts only) are allowed..

Item facility (see log(5))

Element value is optional, default: 5.

session-acl name {


* is-flagged ... ;
* not-flagged ... ;
* jval ... ;
  deny ... ;
  accept ... ;
  continue ... ;
  set-flag ... ;
  unset-flag ... ;
  set-rule ... ;
* listen-socket-id ... ;
* from ... ;
* to ... ;
  protocol ... ;
  source-address ... ;
  plug-to ... ;
  http-error { ... }
  hand-off ... ;
}

            

The session-acl section is derived from session-acl-ng section prototype. For detail description of it, see above.

http-proxy {


* request-acl name { ... }
* doc-acl name { ... }
}

            

Control of sessions handled as HTTP.

Items & subsections:

request-acl name {


* is-flagged ... ;
* not-flagged ... ;
* jval ... ;
  deny ... ;
  accept ... ;
  continue ... ;
  set-flag ... ;
  unset-flag ... ;
  set-rule ... ;
* listen-socket-id ... ;
* from ... ;
* to ... ;
  source-address ... ;
  plug-to ... ;
  http-error { ... }
  hand-off ... ;
* req-method ... ;
* req-uri ... ;
* req-host ... ;
* req-path ... ;
* req-query ... ;
* req-version ... ;
}

                

The request-acl section is derived from http-request-acl-ng section prototype. For detail description of it, see above.

doc-acl name {


* is-flagged ... ;
* not-flagged ... ;
* jval ... ;
  deny ... ;
  accept ... ;
  continue ... ;
  set-flag ... ;
  unset-flag ... ;
  set-rule ... ;
* listen-socket-id ... ;
* from ... ;
* to ... ;
  http-error { ... }
* req-method ... ;
* req-uri ... ;
* req-host ... ;
* req-path ... ;
* req-query ... ;
* req-version ... ;
* resp-status ... ;
* resp-version ... ;
}

                

The doc-acl section is derived from http-doc-acl-ng section prototype. For detail description of it, see above.

[End of section proxy-ng.http-proxy description.]

[End of section proxy-ng description.]

SEE ALSO

configuration(7), listen(2), application(5), common(5), log(5), source-address(5)

Prev Up Next
pop3-proxy.cfg Home radius