Name

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

yes-no (see common(5))

direction (see common(5))

ip-version (see common(5))

time-cond (see common(5))

zip-mode (see common(5))

obligation (see common(5))

dbglev (see log(5))

logfail-mode (see log(5))

week-day (see time(5))

month (see time(5))

auth-method (see auth(5))

transparency (see acl(5))

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

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

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

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

sip-cmd (name-usage obligatory)

none, ACK, BYE, CANCEL, INFO, INVITE, NOTIFY, OPTIONS, PRACK, REFER, REGISTER, SUBSCRIBE

peer (name-usage obligatory)

none, client, server, both

message (name-usage obligatory)

request, response

ITEMS AND SECTIONS

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


* sip-proxy name { ... }
    

Description:

sip-proxy name {


  phase ... ;
* tag ... ;
  log-debug { ... }
  log-stats { ... }
  use-resolver ... ;
  cfg-resolution ... ;
  monitoring { ... }
  stats-daily { ... }
  stats-weekly { ... }
  stats-monthly { ... }
  nodaemon ... ;
  singleproc ... ;
  proxy-user ... ;
  chroot-dir ... ;
  idle-timeout ... ;
  run-block-sigalrm ... ;
  listen-on { ... }
  doctype-identification { ... }
  queue-size ... ;
  hash-salt ... ;
  ctrl-conn { ... }
  data-conn { ... }
  map-file ... ;
  timeouts { ... }
  sessions-table-size ... ;
  sockets-table-size ... ;
* keepalive ... ;
* session-acl name { ... }
* request-acl name { ... }
}

        

This section defines SIP-proxy attributes.

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

Changes to the sip-proxy section:

Section tcpserver is not valid.

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.

SIP Registration Yellow Pages File name must be specified.

Sessions table size must be specified.

Sockets table size must be specified.

Section monitoring (see monitoring(5))

Item aproxy-user is not valid.

Item data used as uri.

Item idle-timeout (see proxy(5))

Element seconds is optional, default: 60.

Added items & subsections:

queue-size [value];

Queue length for listen(2) syscall.

value (type: uint8, optional, default: 4)

hash-salt [text];

Private URI hashing salt.

When publishing data with private addresses (like our clients' Connect URI), the SIP proxy hashes it for security reasons. This hashing can be easily broken by trying all possible private addresses. Therefore, the admin can define a site-specific string that will be added to hashed address to disable this attack.

text (type: str, optional, default: "")

ctrl-conn {


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

            

Control connection options.

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

data-conn {


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

            

Data connection options.

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

map-file name;

SIP Registration (Yellow Pages) File.

name (type: str)

timeouts {


  timer-c ... ;
  timer-dj ... ;
}

            

Timeout set.

Items & subsections:

timer-c [seconds];

Proxy transaction timeout (RFC 3261 Timer C).

This timer is used to prevent situations when a request never generates a final response. When this timer fires, the session is cancelled.

seconds (type: uint32, optional, default: 3m)

timer-dj [seconds];

Wait time for message retransmits (RFC 3261 Timer D,J).

This timer is used to control removing of sessions from the table after carrying the last message (ACK or final response to non_INVITE request).

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

[End of section sip-proxy.timeouts description.]

sessions-table-size number;

Maximal number of active SIP sessions.

The necessary number can be estimated as number of phones times 3 (client's REGISTER, registrar's OPTIONS and call).

number (type: uint16)

Constraints:

Number of sessions must not be zero.

sockets-table-size number;

Maximal number of active SIP and SDP sockets.

This number must cover two sockets for every simultaneous TCP session plus two sockets for every active media channel of every simultaneous call.

number (type: uint16)

Constraints:

Number of sockets must not be zero.

keepalive peer [period [content]];

Sending keepalive packets to peer.

These items enable sending of short packets used for keeping various state tables along the path to the server alive.

peer (type: host-set)

Set of hosts interested in receiving such packets.

period (type: uint16, optional, default: 20)

content (type: str, optional, default: <NULL>)

Packet content, four zero bytes is used by default.

session-acl name {


* from ... ;
* to ... ;
* time ... ;
  time-period-set { ... }
  deny ... ;
  accept ... ;
* doctype-ident-order ... ;
  rule ... ;
  idle-timeout ... ;
  source-address ... ;
  plug-to ... ;
  hide ... ;
  reject-gracefully ... ;
}

            

The first level ACL decides only between acceptation and denial of the incoming datagram/connection.

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 auth is not valid.

Added items & subsections:

hide [peer];

Peer real address replacing by proxy one.

peer (type: peer, optional, default: none)

reject-gracefully;

Graceful rejecting session according to the RFC.

By default, the proxy ignores packets that are not correct session-initiating ones, i.e. invalid requests, correct requests for unknown servers, etc. This behavior can prevent against DoS attacks.

Sometimes, it may be useful to handle such requests gracefully, i.e. to send an answer and wait for the time specified in the RFC. This item will switch this function on. However, it is highly recommended to enable this feature solely for clients from secure (local) network.

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

request-acl name {


* from ... ;
* user ... ;
* time ... ;
  time-period-set { ... }
* session-acl ... ;
  deny ... ;
  accept ... ;
  rule ... ;
  plug-to ... ;
* request-method ... ;
* request-uri ... ;
}

            

The second level ACL decides about details or processing based on request URI.

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 server is not valid.

Item parent-acl used as session-acl.

Item doctype-ident-order is not valid.

Added items & subsections:

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;

Entry condition - matching request methods.

val (type: str-set)

request-uri val;

Entry condition - matching the whole request URI.

Proxy URIs have form sip:[<USER>@]<HOST>[:PORT], e.g., sip:sip.tns.cz:5061.

val (type: str-set)

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

[End of section sip-proxy description.]

SEE ALSO

configuration(7), listen(2), acl(5), auth(5), common(5), listen-on(5), log(5), monitoring(5), netio(5), proxy(5), time(5)