From 9374a46543e9c43c009f80def8c3b2506b0b377e Mon Sep 17 00:00:00 2001 From: Michael Biebl Date: Thu, 3 Apr 2014 03:08:50 +0200 Subject: Imported Upstream version 8.2.0 --- doc/lookup_tables.html | 205 ------------------------------------------------- 1 file changed, 205 deletions(-) delete mode 100644 doc/lookup_tables.html (limited to 'doc/lookup_tables.html') diff --git a/doc/lookup_tables.html b/doc/lookup_tables.html deleted file mode 100644 index e1fcd08..0000000 --- a/doc/lookup_tables.html +++ /dev/null @@ -1,205 +0,0 @@ - - -Lookup Tables - - - -

Lookup Tables

- -

NOTE: this is proposed functionality, which is -NOT YET IMPLEMENTED! - -

Lookup tables are a powerful construct -to obtain "class" information based on message content (e.g. to build -log file names for different server types, departments or remote -offices). -

The base idea is to use a message variable as an index into a table which then -returns another value. For example, $fromhost-ip could be used as an index, with -the table value representing the type of server or the department or remote office -it is located in. A main point with lookup tables is that the lookup is very fast. -So while lookup tables can be emulated with if-elseif constructs, they are generally -much faster. Also, it is possible to reload lookup tables during rsyslog runtime without -the need for a full restart. -

The lookup tables itself exists in a separate configuration file (one per table). This -file is loaded on rsyslog startup and when a reload is requested. -

There are different types of lookup tables: -

-

Note that index integer numbers are represented by unsigned 32 bits. -

Lookup tables can be access via the lookup() built-in function. The core idea is to -set a local variable to the lookup result and later on use that local variable in templates. -

More details on usage now follow. -

Lookup Table File Format

-

Lookup table files contain a single JSON object. This object contains of a header and a -table part. -

Header

-

The header is the top-level json. It has paramters "version", "nomatch", and "type". -The version parameter -must be given and must always be one for this version of rsyslog. The nomatch -parameter is optional. If specified, it contains the value to be used if lookup() -is provided an index value for which no entry exists. The default for -"nomatch" is the empty string. Type specifies the type of lookup to be done. -

Table

-This must be an array of elements, even if only a single value exists (for obvious -reasons, we do not expect this to occur often). Each array element must contain two -fields "index" and "value". -

Example

-

This is a sample of how an ip-to-office mapping may look like: -

-{ "version":1, "nomatch":"unk", "type":"string",
-  "table":[ {"index":"10.0.1.1", "value":"A" },
-          {"index":"10.0.1.2", "value":"A" },
-          {"index":"10.0.1.3", "value":"A" },
-          {"index":"10.0.2.1", "value":"B" },
-          {"index":"10.0.2.2", "value":"B" },
-          {"index":"10.0.2.3", "value":"B" }
-        ]
-}
-
-Note: if a different IP comes in, the value "unk" -is returend thanks to the nomatch parameter in -the first line. -

-

RainerScript Statements

-

lookup_table() Object

-

This statement defines and intially loads a lookup table. Its format is -as follows: -

-lookup_table(name="name" file="/path/to/file" reloadOnHUP="on|off")
-
-

Parameters

- - -

lookup() Function

-

This function is used to actually do the table lookup. Format: -

-lookup("name", indexvalue)
-
-

Parameters

- - - -

load_lookup_table Statement

- -

Note: in the final implementation, this MAY be implemented as an action. -This is a low-level decesion that must be made during the detail development -process. Parameters and semantics will remain the same of this happens. - -

This statement is used to reload a lookup table. It will fail if -the table is static. While this statement is executed, lookups to this table -are temporarily blocked. So for large tables, there may be a slight performance -hit during the load phase. It is assume that always a triggering condition -is used to load the table. -

-load_lookup_table(name="name" errOnFail="on|off" valueOnFail="value")
-
-

Parameters

- - -

Usage example

-

For clarity, we show only those parts of rsyslog.conf that affect -lookup tables. We use the remote office example that an example lookup -table file is given above for. -

-lookup_table(name="ip2office" file="/path/to/ipoffice.lu"
-             reloadOnHUP="off")
-
-
-template(name="depfile" type="string"
-         string="/var/log/%$usr.dep%/messages")
-
-set $usr.dep = lookup("ip2office", $fromhost-ip);
-action(type="omfile" dynfile="depfile")
-
-# support for reload "commands"
-if $fromhost-ip == "10.0.1.123"
-   and $msg contains "reload office lookup table"
-   then
-   load_lookup_table(name="ip2office" errOnFail="on")
-
- -

Note: for performance reasons, it makes sense to put the reload command into -a dedicated ruleset, bound to a specific listener - which than should also -be sufficiently secured, e.g. via TLS mutual auth. - -

Implementation Details

-

The lookup table functionality is implemented via highly efficient algorithms. -The string lookup has O(log n) time complexity. The array -lookup is O(1). In case of sparseArray, we have O(log n). -

To preserve space and, more important, increase cache hit performance, equal -data values are only stored once, no matter how often a lookup index points to them. -

[rsyslog.conf overview] -[manual index] [rsyslog site]

-

This documentation is part of the -rsyslog project.
-Copyright © 2013 by Rainer Gerhards and -Adiscon. -Released under the GNU GPL version 3 or higher.

- - -- cgit v1.2.3