#=========================================================================================== # # Filename: SystemVariables.var # #=========================================================================================== # This file is contains definitions and instances for system-variables (keyword: '$') -- one of the three keywords that define the set of globally unique variables used by DBD2. # -- System Variables (this file) define how DBD2 is to calculate and format variables. # -- User variables (UserVariables.var) define the mapping between user-provided names from the dbcl client or syslog fields and sql-index values in database-templates. # -- TimeStrings (TimeStringgs.var) support extended user-definitions for formatting time-fields. # # DBD2 does not care where sytem-variable ('$'), user-variables ('var') and/or timestrings ('timestring') are are declared. Some of the options are: # -- directly in the primary configuration file. # -- in separate variable files that allow the primary configuration file to be shorter. # -- in separate 'module' files that are 'included' into the main file to localize (and modularize) a particular output-destination's definition and supporting variables into one file. # -- in separate 'varfile' files ('varfile' entries differ from 'include' files in that all keywords other than the 3 variable-defintions listed above are ignored in varfiles). # -- any combination of the above # # This file contains examples of all defined system-variables that are identified by the '$' keyword. # -- This file can be used 'as is'. It defines all possible system-variable combinations supported by DBD2 (with 'timestrings', exhaustive listings are impossible, but samples are provided. # -- Since no system-variable information is kept in memory after the startup code has resolved all user-variables, # there is no memory to be 'saved' by reducing the size of this file. # # To use this file, place a copy of it in the dbd2 working directory (default is /etc/dbd2.d unless changed in the configuration file), # then reference the filename in the global 'VarFile' variable in the configuration file. # # System Variable definitions are the various 'recepies' that tell DBD2 how to calculate and display system-manipulated values. # This file lists all possible system variable constructions, but you may opt to change their names to suit your needs and preferences. # # As in the main configuration file: # -- A hashtag starts a comment. # -- In-line comments are allowed. # -- Keywords and all name-labels are non-case-senstive. # -- If there is whitespace present, equal signs may be omitted, though my sample files will usually contain equal-signs (at least the first several lines) for illustrative purposes. #=========================================================================================== # # S y s t e m - V a r i a b l e F o r m a t s # #=========================================================================================== # $ = = = # #------------------------------------------------------------------------------------ # -- '$' is the keyword to identify a system-variable definition. #------------------------------------------------------------------------------------ # -- ('primary ingredient') is one of the following keywords: # # --- 'Time' : Converts and formats time fields using system zoneinfo files and system-calls as needed. # # --- 'Host' : Converts and formats host fields using cache-file, /etc/hosts file and DNS as applicable. # # --- 'FacPri' : Converts and formats the facility/priority field from syslog messages or from dbcl command-line parameters using systme header files and the 'facpri reference table'. # # --- 'ParmString' : syslog messages only: Refers to the optional component at the start of the message field consisting solely of space-separated '[name=value]' entries. # This is normally an empty string. # The only valid manipulation-option for this string is 'raw' (display it as-is). # # --- 'Msg' : syslog messages only: Refers to the free-form text string (including the 'tag' field) that follows the (usually empty) 'ParmString' # # --- 'TemplateKey' : The finalized list of all database-templates a message (from syslog or dbcl) was applied to. Probably useful only in select debuggging or performance-analysis scenarios. # # --- 'RawInput' : The raw (untouched) input string read by DBD2 from a dbcl or syslog (or other) client. # The only valid manipulation-option for this string is 'raw' (display it as-is). # # --- 'User' : Specifies format of user values. Uses system calls to query the host's user-authentication system to lookup usernames or user-ids and converts between numeric and string values. # # --- 'Group' : Same as 'user' above, but works on group-names or group-ids. #------------------------------------------------------------------------------------ # -- format-specifiers generally address 2 informational questions: # --- What is the 'source' of the data ? (Which of several possible instances of the 'main ingredient' should be used ?) # # ---- DBD2 provides four (4) keywords to choose a data-source from: 'syslog', 'source', 'server' and 'parms'. # ----- 'syslog' is for any data-field extracted from the syslog message itself or for the auto-timestamp of a dbcl message. # ----- 'source' represents the host that directly contacted the DBD2 server whose IP address is retrieved by DBD2 from the incoming connection socket. # ----- 'server' refers to the DBD2 server itself. # ----- 'parms' refers to any name=value pair in a syslog SdString field or on a dbcl command-line. # # --- How will the data be formatted ? # # ---- DBD2 provides a 'decision-tree for formats: # ----- 'Raw' maans the data is displayed exactly as received. # # ----- 'Int' means the data will be in some type of 'numeric' format: # # ------ 'facpri' numeric fields return a numeric value for facility, priority or a combined numeric value: [(facility-number * 8) + priority-number] # ------- 'nofacility' sub-option suppresses the facility component. # ------- 'nopriority' sub-option suppresses the priority component. # # ------ 'time' numeric fields return a signed integer representing the number of seconds since Jan 1 1970 (standard Internet time epoch). # ------- 'gmt' provides the 'raw' system-clock time (in the GMT (UTC) timezone). # ------- 'local' adjusts the gmt time by adding the (possibly negative) timezone offset to the gmt time to get a local 'system clock' value. # # ------ 'host' numeric fields return a 'numeric' IP-address-field. # ------- 'IPv4' display the IPv4 address. # ------- 'IPv6' display the IPv6 address. # # ----- 'String' means the data will be in some type of 'string' format: # # ------ 'facpri' string fields will display . as in "user.notice". # ------- 'nofacility' sub-option suppresses the facility component as in 'notice'. # ------- 'nopriority' sub-option suppresses the priority component as in 'user'. # # ------ 'time' string fields return a more readable time format in a virtually unlimited variety of formats. # # ------- 'gmt' displays all fields using the GMT (UTC) timezone. # ------- 'local' displays all fields using the local machine's timzone settings to adjust for both timezone and daylight-savings time. # # ------- There are 3 pre-configured string time formats and an open-ended, user-specified 'format' that utilizes the values from the 'timestring' keyword. # -------- 'Syslog' : [Mar 22 13:45:33] This is the well-known syslog time format (even down to the missing year and time-offset). # -------- 'Db' : [yyyymmddHHMMSS] Example: [20230322134533] This was once a popular database time format. # -------- 'Rfc' : [yyyy-mm-ddTHH:MM:SS[+/-]HH:MM] Example: [2023-03-22T13:45:33-05:00] This is rfc3339/rfc5424 format. (For the GMT timezone, the offset will be 'Z'). # -------- To use a 'timestring' format, replace the 'string' option in the option-list with 'string:#' where '#' is a time-string index value. # # ------ 'host' string fields return a 'string' hostname field. # ------- 'HostName' displays the hostname only. This is the default format of 'host' + 'string' if no suboption is provided. # ------- 'DomainName' displays the domainname only. # ------- 'FQDN' displays the Fully-Qualified-Domain-Name (both hostname and domainname). # #------------------------------------------------------------------------------------ #=========================================================================================== #=========================================================================================== # The rest of this file defines system variable names. # These definitions (and names) are neither used nor kept after parsing if they are not referenced by 'var' variables during startup. # # Each system-variable definition must be on a line by itself. # Each system-variable is a 4-part entry separated with '=' or white-space. # The '=' is optional if whitespace is present. ('=', ' = ', '= ', ' ', '\t' and '\t=\t' all parse to the same result) # # 1: '$': The keyword for defining a system-variable. # 2: : one of 'facpri', 'time', 'host', 'parmstring', 'msg', 'rawinput', 'user', 'group', 'genericint' or 'templatekey' # 3: A comma-separated list of source and format options for displaying this field. # 4: A name for this definition. Multiple names are allowed per definition. They must not contain a '$' prefix. #=========================================================================================== # My name 'scheme' is to use the 1st letter of the name to indicate the source: # : Source is 'syslog'. # 'R' Source is 'relayhost' or 'source' # 'S' Source is 'server' # 'P' Source is 'parameters' or 'parms' (dbcl name=value pairs or sdstring name=value pairs from a syslog entry). # I use proper-capitalized variable names to show word-components. #=========================================================================================== #=========================================================================================== #------------------------ # These first three primary field-types are non-syslog fields found only in parameter entries. # The valid option set for each field is defined immediately below each entry. #------------------------ $ User parms,raw PUserRaw $ user parms,string PUserStr # converts user-id to username-string using passwd file and/or nis $ user parms,int PUserInt # converts username-string to numeric user-id using passwd file and/or nis, etc $ Group parms,raw PGroupRaw $ group parms,string PGroupStr # converts group-id to groupname-string using passwd file and/or nis $ group parms,int PGroupInt # converts groupname-string to numeric group-id using passwd file and/or nis, etc $ GenericInt parms,raw PGenericIntRaw # allows time-string to change the units (1000s, millions, kilos, mega, etc) & perhaps add commas. #------------------------ # The rest of the fields define variations for the display of system-variables # Each name begins with a letter defining where the original data value will be sourced from if not from the syslog header-fields. #------------------------ # raw input fields #------------------------ $ RawInput raw = RawInput # The full (raw) input-string $ TemplateKey raw = RawTemplate # This is the template used for routing (as resolved from facprimaps and parameter-lists) #------------------------ # The next two fields are not defined for dbcl input #------------------------ $ ParmString raw ParmStringRaw, RawParmString $ Msg raw MsgRaw,RawMsg $ Msg tag,raw MsgTag $ Msg notag,raw MsgNoTag #------------------------ # facpri fields (from syslog messages) #------------------------ $ FacPri syslog,raw FacPriRaw $ facpri syslog,int FacPriInt $ facpri syslog,int,nopriority FacPriNoPriInt $ facpri syslog,int,nofacility FacPriNoFacInt $ facpri syslog,int,nofacility,nopriority FacPriNoFacNoPriInt $ facpri syslog,string FacPriStr $ facpri syslog,string,nopriority FacPriNoPriStr $ facpri syslog,string,nofacility FacPriNoFacStr $ facpri syslog,string,nofacility,nopriority FacPriNoFacNoPriStr #------------------------ # facpriparm fields (from parameter lists) #------------------------ $ FacPri parms,raw PFacPriRaw $ facpri parms,int PFacPriInt $ facpri parms,int,nopriority PFacPriNoPriInt $ facpri parms,int,nofacility PFacPriNoFacInt $ facpri parms,int,nofacility,nopriority PFacPriNoFacNoPriInt $ facpri parms,string PFacPriStr $ facpri parms,string,nopriority PFacPriNoPriStr $ facpri parms,string,nofacility PFacPriNoFacStr $ facpri parms,string,nofacility,nopriority PFacPriNoFacNoPriStr #------------------------ # time fields #------------------------ $ Time syslog,raw TimeRaw $ = time = syslog,gmttime,int TimeUTCInt $ = time = syslog,gmttime,string,db TimeUTCDb $ time syslog,gmttime,string ,rfc TimeUTCRfc $ time syslog,gmttime,string ,syslogtime TimeUTCSyslog $ time syslog,local,int TimeLocalInt $ time syslog,local,string,db TimeLocalDb $ time syslog,local,string,rfc TimeLocalRfc $ time syslog,local,string,syslogtime TimeLocalSyslog $ time syslog,gmttime,string:200 TimeUTC200 $ = time = syslog,local,string:300 TimeLocal300 #------------------------ # time fields using time from parameter-list #------------------------ $ Time parms,raw PTimeRaw $ = time = parms,gmttime,int PTimeUTCInt $ = time = parms,gmttime,string,db PTimeUTCDb $ time parms,gmttime,string,rfc PTimeUTCRfc $ time parms,gmttime,string,syslogtime PTimeUTCSyslog $ time parms,local,int PTimeLocalInt $ time parms,local,string,db PTimeLocalDb $ time parms,local,string,rfc PTimeLocalRfc $ time parms,local,string,syslogtime, PTimeLocalSyslog $ time parms,gmttime,string:200 PTimeUTC200 $ = time = parms,local,string:300 PTimeLocal300 #------------------------ # Server-time fields #------------------------ $ Time server,raw STimeRaw $ = time = server,gmttime,int STimeUtcInt $ = time = server,gmttime,string,db STimeUTCDb $ time server,gmttime,string,rfc STimeUTCRfc $ time server,gmttime,string,syslogtime STimeUTCSyslog $ time server,local,int STimelocalInt $ time server,local,string,db STimelocalDb $ time server,local,string,rfc STimelocalRfc $ time server,local,string,syslogtime STimelocalSyslog $ time server,gmttime,string:200 STimeUTC200 $ = time = server,local,string:300 STimeLocal300 #------------------------ # host fields #------------------------ $ host syslog,raw HostRaw # No prefix indicates auto-stamped source (msg-string or dbcl auto-stamp) $ host syslog,string,hostonly HostNameOnly $ host syslog,string,domain HostDomain $ host syslog,string,fqdn FQDN $ host syslog,int,ipv4 IPv4 $ host syslog,numeric,ipv6 IPv6 $ host parms,raw PHostRaw # 'P' indicates source is from parameter-list $ host parms,string,hostonly PHostNameOnly $ host parms,string,domain PHostDomain $ host parms,string,fqdn PFQDN $ host parms,int,ipv4 PIPv4 $ host parms,numeric,ipv6 PIPv6 $ host source,raw RHostRaw # 'R' indicates source is 'relay-host' (taken from peer-address of incoming socket connection) $ host source,string,hostonly RHostNameOnly $ host source,string,domain RHostDomain $ host source,string,fqdn RFQDN $ host source,int,ipv4 RIPv4 $ host source,numeric,ipv6 RIPv6 $ host server,raw SHostRaw # 'S' indicaes source is the DBD2 server $ host server,string,hostonly SHostNameOnly $ host server,string,domain SHostDomain $ host server,string,fqdn SFQDN $ host server,int,ipv4 SIPv4 $ host server,numeric,ipv6 SIPv6