The lograptor command

SYNOPSIS

lograptor [options] PATTERN [FILE ...]
lograptor [options] [-e PATTERN | -f PATTERNS_FILE ] [FILE ...]

DESCRIPTION

lograptor is a search tool for system logs saved with legacy BSD syslog format (RFC 3164) or IETF syslog format (RFC 5424).

It’s developed as a compact and configurable GREP-like tool, usable for raw or refined searches and to create customizable reports on system logs. The application mixes regex pattern matching search with scope delimiters and a configurable set of filters. You can configure additional application pattern rules using the classical regexp syntax. lograptor can also produce and publish reports in various formats. Reporting can be automated using cron.

For lograptor’s configuration see lograptor-conf(5).

For more information on adding and configuring applications see lograptor-apps(5).

OPTIONS

Positional Arguments

[FILE ...]

Input files. Each argument can be a file path or a glob pathname. A “-” stands for standard input. If no arguments are given then processes all the files included within the scope of the selected applications.

General Options

--conf FILE

Use a specific configuration file. For default try to find and use a lograptor.conf file located in the current directory, in the ~/.config/lograptor/ directory, in the ~/.local/etc/lograptor/ directory or in the /etc/lograptor/ directory. If none of them exist then uses the default configuration provided within the package into the subdirectory config/. If you call the program from the command line without other options and arguments a summary of configuration settings is dumped to stdout.

-d [0-4]

Logging level (default is 2, use 4 for debug). A level of 0 suppress also error messages about nonexistent or unreadable files.

-V, --version

Show program’s version number and exit.

--help

Show an help page about program options and exit.

Scope Selection

-a APP[,APP...], --apps APP[,APP...]

Process the log lines related to an application. An app name is valid when a configuration file is defined. For default all apps defined and enabled are processed.

--hosts HOSTNAME/IP[,HOSTNAME/IP...]

Process the log lines related to a comma separated list of hostnames and/or IP addresses. File path wildcards can be used for hostnames.

-F FIELD=PATTERN[,FIELD=PATTERN...], --filter FIELD=PATTERN[,FIELD=PATTERN...]

Process the log lines that match all the conditions for pattern rule’s field values. The filters within a single option are applied with logical conjunction (AND). Multiple -F options are used with logical disjunction (OR).

--time HH:MM,HH:MM

Process the log lines related to a time range.

--date [YYYY]MMDD[,[YYYY]MMDD]

Restrict the search scope to a date or a date interval.

--last [hour|day|week|month|Nh|Nd|Nw|Nm]

Restrict the search scope to a previous time period.

Matcher Selection

-G, --ruled

Use patterns and application rules matching. This is the default.

-X, --unruled

Use patterns only. Application pattern rules are skipped. This option is incompatible with report and filtering options.

-U, --unparsed

Match the patterns but select the lines that don’t match any application rule. This option is useful for finding anomalies and for application’s rules debugging. This option is incompatible with filters (option -F).

Matching Control

-e PATTERN, --regexp=PATTERN

The search pattern. Use the option more times to specify multiple search patterns. Empty patterns are skipped.

-f FILE, --file=FILE

Obtain patterns from FILE, one per line. Blank lines are skipped. If this option is used multiple times or is combined with the -e (–regexp) option, search for all patterns given. An empty file contains zero patterns, and therefore matches nothing.

-i, --ignore-case

Ignore case distinctions in matching, so that characters that differ only in case match each other.

-v, --invert-match

Invert the sense of matching, to select non-matching lines.

-w, --word-regexp

Force PATTERN to match only whole words. The matching substring must either be at the beginning of the line, or preceded by a non-word constituent character. Similarly, it must be either at the end of the line or followed by a non-word constituent character. Word-constituent characters are letters, digits, and the underscore.

General Output Control

--output CHANNEL[,CHANNEL...]

Send output to a comma separated list of channels. Channels have to be defined in the configuration file. For default the output is sent to stdout channel.

-c, --count

Suppress normal output; instead print a count of matching lines for each input file. With the -v/–invert-match option count non-matching lines.

--color [(auto|always|never)]

Use markers to highlight the matching strings. The colors are defined by the environment variable LOGRAPTOR_COLORS.

-L, --files-without-match

Print only names of FILEs containing no match.

-l, --files-with-match

Print only names of FILEs containing matches. The scanning will stop on the first match.

-m NUM, --max-count NUM

Stop reading a file after NUM matching lines. When -c/–count option is also used, lograptor does not output a count greater than NUM. When using -t/–thread option the limit is related to the number of threads and not to the number of lines matched.

-o, --only-matching

Print only the matched (non-empty) parts of a matching line, with each such part on a separate output line.

-q, --quiet

Quiet; do not write anything to standard output. Exit immediately with zero status if any match is found, even if an error was detected.

-s, --no-messages

Suppress error messages about nonexistent or unreadable files. Equivalent to -d 0.

Output Data Control

--report [NAME]

Produce a report at the end of processing. If NAME is omitted that use the default report defined in the lograptor configuration file.

--ip-lookup

Translate IP addresses to DNS names. Use a DNS local cache to improve the speed of the lookups and reduce the network service’s load.

--uid-lookup

Translate UIDs to usernames. The configured local system authentication is used for lookups, so it must be inherent to the UIDs that have to be resolved.

--anonymize

Anonymize defined application rule’s fields value. Translation tables are built in volatile memory for each run. The anonymous tokens have the format FILTER_NNN. This option overrides –ip-lookup and –uid-lookup options. WARNING: this is an experimental feature.

Output Line Prefix Control

-n, --line-number

Prefix each line of output with the line number within its input file.

-H, --with-filename

Print the file name for each match. This is the default when there is more than one file to search.

-h, --no-filename

Suppress the prefixing of file names on output. This is the default when there is only one file (or only standard input) to search.

Context Line Control

-T, --thread

The context is the log thread of the application. The thread rules defined in application configuration files are used.

-A NUM, --after-context NUM

Print NUM lines of trailing context after matching lines. Places a line containing a group separator (described under –group-separator option) between contiguous groups of matches. With the -o or –only-matching option, this has no effect and a warning is given.

-B NUM, --before-context NUM

Print NUM lines of leading context before matching lines. Places a line containing a group separator (described under –group-separator) between contiguous groups of matches. With the -o or –only-matching option, this has no effect and a warning is given.

-C NUM, --context NUM

Print NUM lines of output context. Places a line containing a group separator (described under –group-separator) between contiguous groups of matches. With the -o or –only-matching option, this has no effect and a warning is given.

--group-separator SEP

Use SEP as a group separator. By default SEP is double hyphen (–).

--no-group-separator

Use empty string as a group separator.

File and Directory Selection

-r, --recursive

Read all files under each directory, recursively, following symbolic links only if they are on the command line.

-R, --dereference-recursive

Read all files under each directory, recursively. Follow all symbolic links, unlike -r.

--exclude GLOB

Skip any file with a name suffix that matches the pattern GLOB, using wildcard matching; a name suffix is either the whole name, or any suffix starting after a / and before a +non-/. When searching recursively, skip any subfile whose base name matches GLOB; the base name is the part after the last /. A pattern can use *, ?, and […] as wildcards, and to quote a wildcard or backslash character literally.

--exclude-from FILE

Skip files whose base name matches any of the file-name globs read from FILE (using wildcard matching as described under –exclude).

--exclude-dir DIR

Skip any command-line directory with a name suffix that matches the pattern GLOB. When searching recursively, skip any subdirectory whose base name matches GLOB. Ignore any redundant trailing slashes in GLOB.

--include GLOB

Search only files whose base name matches GLOB (using wildcard matching as described under –exclude).

FILES

/etc/lograptor/lograptor.conf

/etc/lograptor/conf.d/*.conf

/usr/bin/lograptor

AUTHORS

Davide Brunato <brunato@sissa.it>