clear-web-db — format of clear-web-db component configuration


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

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


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 clear-web-db configuration directives:

lock-type (see ipc(5))

clear-web-db-category (name-usage obligatory)

Categories of web servers recognized by the Clear Web DataBase.

advertisement, alcohol-tobacco, arts, cars-vehicles, banking, brokers, building-home, business, chats-blogs-forums, communications, crime, education, entertainment, environment, erotic-adult-nudity, extreme-hate-violence, fashion-beauty, food-restaurants, foundations-charity-social-services, gambling, games, government, hacking-phishing-fraud, health-medicine, hobbies, humour-cool, it-hardware-software, it-services-internet, illegal-drugs, instant-messaging, insurance, job-career, kids-toys-family, military-guns, mobile-phones-operators, music-radio-cinema-tv, news-magazines, peer-to-peer, personal-dating-lifestyle, politics-law, pornography, portals-search-engines, proxies, real-estate, regional, religious-spirituality, sale-auctions, sects, sex-education, shopping, social-networks, sports, streaming-broadcasting, swimwear-intimate, translation-services, travelling-vacation, uploading-downloading, warez-piracy, web-based-mail, web-hosting, money-financial, internal-servers, unknown

clear-web-db-match-mode (name-usage obligatory)

How to match Clear Web DataBase categories.


At least one category of the request URI matches the condition.


All categories in the condition are matched by categories of the request URI.


All categories of the request URI match the condition.


Categories of the request URI are exactly those in the condition.


Configuration of clear-web-db library component consists of following prototypes:

  clear-web-db { ... }
  cwcatd-wakeup ... ;
  cwcatd-retry ... ;
  clear-web-db-bypass { ... }
* clear-web-db-match ... ;


clear-web-db {

  internal-servers ... ;
  db ... ;
  lock ... ;
  local-db { ... }


Global settings for web filtration based on URL. Enables periodic updates of the database.

Items & subsections:

internal-servers [private-ip] server;

List of servers, that are categorized as INTERNAL-SERVERS, in addition to RFC 1918 IP addresses. Domain names will be resolved to IP addresses and compared to the real IP address of the server. Regexp will be compared to the target hostname (without resolving). See more information in host-matching(7).

private-ip (type: key, optional)

Categorize private IP addresses from RFC 1918 (,, as internal servers.

server (type: host-set)

Categorize matching servers as internal. See host-matching(7).

db [dir];

Local directory used to store Clear Web DataBase data.

dir (type: str, optional, default: "/data/var/clear-web-db")

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.

local-db {

  file ... ;
  timeout-search ... ;
  timeout-enqueue ... ;
  timeout-cwcatd ... ;


Locally created Clear Web database. It contains categories for automatically categorized URLs. If this section is missing in the configuration, a proxy will not use the local database.

Items & subsections:

file [path];

Name of the database file

path (type: str, optional, default: "/data/var/clear-web-local/clear-web-local.sqlite")

timeout-search [sec];

Timeout for searching the database. A proxy will wait up to this number of seconds when searching for categories of an URL and another process keeps the database locked.

sec (type: fract, optional, default: 0.100)

timeout-enqueue [sec];

Timeout for inserting an URL to be categorized into the categorizer queue. A proxy will wait up to this number of seconds when inserting an URL and another process keeps the database locked.

sec (type: fract, optional, default: 0.100)

timeout-cwcatd [sec];

The cwcatd daemon will wait up to this number of seconds before aborting the current operation when another process keeps the database locked.

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

[End of section clear-web-db.local-db description.]

[End of section clear-web-db description.]

cwcatd-wakeup [sec];

Period (in seconds) of waking up of the categorization daemon and checking the queue of categorization requests. In addition, the daemon is awaken by a signal immediately after a new request is enqueued.

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

cwcatd-retry [sec];

Time (in seconds) after which a failed automatic categorization will be retried.

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

clear-web-db-bypass {

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


Enable the bypass functionality (time-limited access to a page blocked by the Clear Web DataBase).

Items & subsections:

status [code];

Status code returned when the bypass is inactive. Default is 403 Forbidden.

code (type: uint16, optional, default: 403)

cookie [name];

Use cookies for bypass management. Default is to used a table of client IP addresses with enabled bypass.

name (type: str, optional, default: "Kernun-ClearWebDB-Bypass")

bypass cookie name

activation [sec];

Maximum time for clicking on bypass activation link after the bypass activation page is shown. If the user clicks the link later, the proxy will return the activation page again.

sec (type: uint8, optional, default: 30)

duration [sec];

Duration of allowed access.

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

[End of section clear-web-db-bypass description.]

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)


configuration(7), ipc(5), host-matching(7)