From 7753c45bfb54a01bbcfc666a4df43aac227a25e0 Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Thu, 24 Jan 2013 14:02:26 +0100 Subject: doc: some spec changes for lookup tables --- doc/lookup_tables.html | 66 ++++++++++++++++++-------------------------------- 1 file changed, 24 insertions(+), 42 deletions(-) diff --git a/doc/lookup_tables.html b/doc/lookup_tables.html index f8fdbbf6..5aba2568 100644 --- a/doc/lookup_tables.html +++ b/doc/lookup_tables.html @@ -33,55 +33,42 @@ is acceptable in order to reload it. 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 consist of a header line and data lines, all inside a plain -text file. +

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

Header

-

The header line is required to be -

-LookupTable version="1" nomatch="string"
-
-

Note that case is important, so "lookuptable" would be invalid. -This is intentional to protect against false positives. The version parameter +

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. Note that for version 1, -parameters must be provided in the order as specified above. -

Data Lines

-Each data line must follow this format: -
-"index"="value" # comment
-
-Where "index" and "value" are the actual values to be used. Standard escapes can be used, -most importantly '\"' represents the double quote characters. Whitespace is ignored, as -is everything after the comment character. -

Comment Lines

-

Lines starting with "#" are comments and will be ignored. Leading whitespace before the -comment character is permitted. +"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: 

-LookupTable version="1" nomatch="unk"
-# IP 10.0.1.0/1/2 belong to office A
-"10.0.1.0"="A"
-"10.0.1.1"="A"
-"10.0.1.2"="A"
-# IP 10.0.2.0/1/2 belong to office B
-"10.0.2.0"="B"
-"10.0.2.1"="B"
-"10.0.2.2"="B"
-# if a different IP comes in, the value "unk"
-# is returend thanks to the nomatch parameter in
-# the first line.
+{ "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" type="static|dynamic"
-             reloadOnHUP="on|off")
+lookup_table(name="name" file="/path/to/file" reloadOnHUP="on|off")

Parameters